factory module

Define a factory to easily create Accelerator.

class AcceleratorFactory(beam_calculators, files, beam, **kwargs)

Bases: object

A class to create accelerators.

Parameters:

• beam_calculators (BeamCalculator | Sequence[BeamCalculator | None])

• files (dict[str, Any])

• beam (BeamKwargs)

__init__(beam_calculators, files, beam, **kwargs)

Facilitate creation of Accelerator objects.

Parameters:

• beam_calculators (BeamCalculator | Sequence[BeamCalculator | None]) – Objects that will compute propagation of the beam.

• files (dict[str, Any]) – Configuration entries for the input/output paths.

• beam (BeamKwargs) – Configuration dictionary holding the initial beam parameters.

• kwargs – Other configuration dictionaries.

Return type:

None

_pickle_paths

Parsed dictionary holding path to the different pickles. Typical structure:

{
    "Reference": "reference.pkl",
    "scenarios": {
        # Scenario 1: pre-computed solution (skips optimization)
        1: {"Solution": "solution-000001.pkl"},
        # Scenario 2: alternatives with custom names
        # (optimization still runs, the pickled Accelerators
        # will be appended)
        2: {
            "Solution": None,
            "Conservative approach": "design-conservative.pkl",
            "Aggressive tuning": "design-aggressive.pkl",
        },
        # Scenario 3: solution + alternatives
        3: {
            "Solution": "solution-000003.pkl",
            "Tweaked design": "tweaked.pkl",
            "Experimental config": "experimental.pkl",
        }
    }
}

property pickler: MyPickler

create_all(wtf=None)

Create reference and broken accelerators.

Also loads any additional pre-computed accelerators from pickle files specified in the configuration.

Parameters:

wtf (dict[str, Any] | None, default: None) – “What To Fail/Fit” configuration. Can contain automatic fault generation parameters that will be resolved into specific cavity failures.

Return type:

tuple[dict[int, list[Accelerator]], dict[str, Any] | None]

Returns:

• accelerators – Dictionary where keys are FaultScenario indexes, and values are lists of corresponding Accelerator. First index corresponds to reference accelerator (no failure).

• updated_wtf – The resolved wtf configuration with explicit cavity failures. None if no wtf was provided.

create_reference()

Unpickle or create from scratch the reference (nominal) accelerator.

Return type:

Accelerator

Returns:

The nominal accelerator without failures.

create_all_broken(n_scenarios)

Unpickle or create from scratch several broken accelerators.

Parameters:

n_scenarios (int) – Number of broken accelerators to create. This is also the number of FaultScenario we will create.

Return type:

dict[int, list[Accelerator]]

Returns:

Dict associating FaultScenario index to corresponding broken Accelerator.

_create_one_accelerator(name, status, index, output_path)

Create or load a single accelerator.

Parameters:

• name (str) – Accelerator name (e.g., "Reference", "Solution").

• status (Literal['reference', 'broken', 'fix']) – Current status design. Ignored if the Accelerator is unpickled.

• index (int) – Corresponding FaultScenario index. A null index is reserved for reference accelerator.

• output_path (Path) – Path where accelerator data will be stored.

Return type:

Accelerator

Returns:

Loaded from pickle if available, otherwise freshly created.

_build_accelerator(name, status, index, output_path, pickle_path)

Build a new accelerator from scratch.

Parameters:

• name (str) – Accelerator name.

• status (Literal['reference', 'broken', 'fix']) – Current status design.

• index (int) – Corresponding FaultScenario index. A null index is reserved for reference accelerator.

• output_path (Path) – Path where accelerator data will be stored.

• pickle_path (Path | None) – Optional path where accelerator will be pickled after creation.

Return type:

Accelerator

Returns:

Newly created accelerator instance.

_create_output_directories(output_path)

Create output directory structure for an accelerator.

Creates the main accelerator directory and subdirectories for each beam calculator.

The default structure will look like:

YYYY.MM.DD_HHhmm_SSs_MILLIms/
├── 000000_ref
│   ├── 0_Envelope1D/
│   └── 1_TraceWin/
├── 000001
│   ├── 0_Envelope1D/
│   └── 1_TraceWin/
├── 000002
│   ├── 0_Envelope1D/
│   └── 1_TraceWin/
├── 000003
│   ├── 0_Envelope1D/
│   └── 1_TraceWin/
└── lightwin.log

• The main YYYY.MM.DD_HHhMM_SSs_MILLIms/ directory is created at the same location as the original DAT file. You can override its name with the project_folder key in the [files] TOML section.

• In every accelerator_path (eg 000002/), you will find one directory per BeamCalculator. In this example, compensation settings were found with Envelope1D and a second simulation was made with TraceWin.

Parameters:

output_path (Path)

Return type:

None

_check_consistency_reference_phase_policies(cavities)

Check that solvers phases are consistent with DAT file.

Parameters:

cavities (Sequence[FieldMap]) – Sequence of cavity field maps to check.

Return type:

None

_parse_pickle_config(pickle_config)

Parse pickle paths configuration from TOML.

Note

When a Reference/Solution PKL is provided but does not exist, the associated Accelerator will be pickled at the end of the simulation.

Parameters:

pickle_config (dict[str, str | dict[str, str]]) –

Configuration TOML [files.pickle_paths] sub-dictionary. The expected structure is:

[files.pickle_paths]
Reference = "reference.pkl"

# Scenario 1: pre-computed solution (skips optimization)
[files.pickle_paths.000001]
Solution = "solution-000001.pkl"

# Scenario 2: alternatives with custom names (optimization
# still runs, the pickled Accelerators will be appended)
[files.pickle_paths.000002]
"Conservative approach" = "design-conservative.pkl"
"Aggressive tuning" = "design-aggressive.pkl"

# Scenario 3: solution + alternatives
[files.pickle_paths.000003]
Solution = "solution-000003.pkl"
"Tweaked design" = "tweaked.pkl"
"Experimental config" = "experimental.pkl"

Return type:

dict[int, str | dict[str, str]]

Returns:

Parsed configuration with structure:

{
    0: "reference.pkl",
    # Scenario 1: pre-computed solution (skips
    # optimization)
    1: {"Solution": "solution-000001.pkl"},
    # Scenario 2: alternatives with custom names
    # (optimization still runs, the pickled Accelerators
    # will be appended)
    2: {
        "Conservative approach": "design-conservative.pkl",
        "Aggressive tuning": "design-aggressive.pkl",
    },
    # Scenario 3: solution + alternatives
    3: {
        "Solution": "solution-000003.pkl",
        "Tweaked design": "tweaked.pkl",
        "Experimental config": "experimental.pkl",
    },
}

• 0: Path to reference accelerator pickle, or None.

• scenarios[index]: Sub-dictionary where keys are Accelerator.name, values are corresponding PKL Accelerator pickle files.

_get_pickle_path(name, index=0)

Get pickle path for a named accelerator in _pickle_paths.

Parameters:

• name (str) – Accelerator name to look up in pickle paths configuration.

• index (int, default: 0) – FaultScenario index. If not null, we look for name key in self._pickle_paths[index] subdict.

Return type:

Path | None

Returns:

Resolved absolute path if configured, None otherwise.

_load_from_pickle(name, index, pickle_path)

Load accelerator from pickle file if it exists.

Parameters:

• name (str) – Accelerator name.

• index (int) – Corresponding FaultScenario index. A null index is reserved for reference accelerator.

• pickle_path (Path) – Path to pickle file.

Return type:

Accelerator | None

Returns:

Loaded accelerator if file exists, None otherwise.

_load_additional_pickles(reserved_names={'Solution', 'Reference'})

Unpickle additional Accelerator.

Parameters:

reserved_names (set[str], default: {'Solution', 'Reference'}) – Names already used for Reference/Solution accelerators; associated paths are not unpickled.

Return type:

dict[int, list[Accelerator]]

Returns:

Additional accelerators loaded from pickle files, associated with their FaultScenario index.

create_nominal()

Create the nominal linac.

Deprecated since version 0.15.1: Prefer create_reference().

Return type:

Accelerator

create_failed(n_objects)

Create failed linac(s).

Deprecated since version 0.15.1: Prefer create_all_broken().

Parameters:

n_objects (int)

Return type:

list[Accelerator]

class NoFault(*args, **kwargs)

Bases: AcceleratorFactory

Create single accelerator without failure.

Deprecated since version 0.15.0: Prefer AcceleratorFactory.

__init__(*args, **kwargs)

Facilitate creation of Accelerator objects.

Parameters:

• beam_calculators – Objects that will compute propagation of the beam.

• files – Configuration entries for the input/output paths.

• beam – Configuration dictionary holding the initial beam parameters.

• kwargs – Other configuration dictionaries.

Return type:

None

run(*args, **kwargs)

Return type:

Accelerator

class WithFaults(*args, wtf, **kwargs)

Bases: AcceleratorFactory

Create accelerators with failures.

Deprecated since version 0.15.0: Prefer AcceleratorFactory.

Parameters:

wtf (dict[str, Any])

__init__(*args, wtf, **kwargs)

Facilitate creation of Accelerator objects.

Parameters:

• beam_calculators – Objects that will compute propagation of the beam.

• files – Configuration entries for the input/output paths.

• beam – Configuration dictionary holding the initial beam parameters.

• kwargs – Other configuration dictionaries.

• wtf (dict[str, Any])

Return type:

None

run_all(*args, **kwargs)

Return type:

list[Accelerator]