Framework

SIMBA Framework Module

The main class for handling the tracking of a particle distribution through a lattice.

Settings files can be loaded in, consisting of one or more LAURA YAML files. This creates frameworkLattice objects.

These objects can be modified directly through the Framework class.

Based on the tracking code(s) provided to the framework, the particle distribution is tracked through the lattice sequentially, and output beam distributions are generated and converted to the standard OpenPMD HDF5 format.

Summary files containing Twiss parameters, and a summary of the beam files, are generated after tracking.

Classes:

• Framework: Top-level class for loading and modifying lattice settings and tracking through them

• frameworkDirectory: Class to load a tracking run from a directory and reading the Beam and Twiss files and making them available.

class Framework(*args, **kwargs)

Bases: BaseModel

The main class for handling the tracking of a particle distribution through a lattice.

Settings files can be loaded in, consisting of one or more LAURA YAML files. This creates frameworkLattice objects, each of which contains Element objects.

These objects can be modified directly through the Framework class.

Based on the tracking code(s) provided to the framework, the particle distribution is tracked through the lattice sequentially, and output beam distributions are generated and converted to the standard OpenPMD HDF5 format.

Summary files containing Twiss parameters, and a summary of the beam files, are generated after tracking.

Parameters:

• args (Any)

• kwargs (Any)

add_Generator(default=None, **kwargs)

Add a file generator based on a keyword dictionary. Sets generator to the frameworkGenerator.

Also sets the “generator” in latticeObjects to this generator.

Parameters:

default (str or None) – Name of generator code

Return type:

None

apply_changes(changes, verbose=False)

Applies a dictionary of changes to the current lattice.

Parameters:

• changes (dict) – Dictionary of changes to elements, keyed by element name and containing parameters and values to change

• verbose (bool) – Flag to indicate which elements are being modified

Return type:

None

change_Lattice_Code(latticename, code, exclude=None, nowarn=False)

Changes the tracking code for a given lattice.

Parameters:

• latticename (str) – Name of the lattice line defined in the latticeObjects

• code (str) – Simulation code to use for latticename; can be All

• exclude (str or list or tuple, optional) – Exclude certain lines from this function

• nowarn (bool) – If True, disable warning about resetting the execution location

Return type:

None

change_generator(generator)

Changes the generator from one type to another.

Parameters:

generator (str) – The generator code to which the generator object should be changed.

Return type:

None

change_subdirectory(*args, **kwargs)

Change the subdirectory and master_subdir in global_parameters to which lattice and beam files will be written.

Return type:

None

check_lattice(decimals=4)

Checks that there are no positioning errors in the lattice.

Parameters:

decimals (int) – Number of decimals to check errors

Returns:

True if errors are detected

Return type:

bool

clean: bool = False

Flag to indicate whether all files in the existing directory are to be removed

clear()

Clear out elementObjects, latticeObjects, commandObjects, groupObjects

Return type:

None

commandObjects: Dict = {}

Dictionary containing all frameworkCommand objects

property commands: list

Returns a list of all command object names

Returns:

List of command object names

Return type:

list

delete_output_files: bool = False

Flag to indicate whether output files are to be deleted after tracking

detect_changes(elementtype=None, elements=None)

Detect lattice changes from the original loaded lattice and return a dictionary of changes.

Parameters:

• elementtype (str or None) – Element type to check; check all if None

• elements (list or None) – Elements to check; check all if None

Returns:

Dictionary containing changes in the lattice, with element names and changed parameters

Return type:

dict

directory: str

The directory into which simulation files will be placed

eager_mode: bool = False

Bypass lazy loading for LAURA

elementObjects: Dict = {}

Dictionary containing all Element objects

property elements: list

Returns a list of all element names from elementObjects

Returns:

List of element names

Return type:

list

fileSettings: Dict = {}

Dictionary containing all file settings

generator: frameworkGenerator | None = None

The frameworkGenerator object

generatorSettings: Dict = {}

Dictionary containing all generator settings

generator_defaults: str | None = None

File pointing to defaults for constructing the frameworkGenerator

generator_keywords: Dict = {}

Default keywords for the frameworkGenerator loaded from generator_defaults in master_lattice/Generators

getElement(element, param=None)

Returns the element object or a parameter of that element

Parameters:

• element (str) – Name of element to get

• param (str or None) – Parameter to retrieve; if None, return the entire element

Returns:

dict or Any or – Get the param associated with element, or the entire element, or an empty dictionary if the element does not exist in the entire lattice

Return type:

class:`~laura.models.element.Element

getElementType(typ, param=None)

Gets all elements of the specified type, or the parameter of each of those elements

Parameters:

• typ (list or str or tuple) – Type or list of types to get

• param (str or None) – Parameters to retrieve; if None, get the entire object

Returns:

Get param for all elements, or all elements, or recall this function recursively if param is a list or tuple

Return type:

dict or list or Any

getSValues()

Returns a list of S values for the current lattice from latticeObjects; see getSValues().

Returns:

S values for all elements

Return type:

list

getSValuesElements()

Returns a list of (name, element, s) tuples for the current machine from latticeObjects; see getSNamesElems().

Returns:

Element names, element object and its S position

Return type:

list

getZValuesElements()

Returns a list of (name, element, z) tuples for the current machine from latticeObjects; see getZNamesElems().

Returns:

Element names, element object and its Z position

Return type:

list

globalSettings: Dict = {}

Dictionary containing all global settings

global_parameters: Dict = {}

Dictionary containing global parameters accessible to all classes

groupObjects: Dict = {}

Dictionary containing all frameworkGroup objects

property groups: list

Returns a list of all group names from groupObjects

Returns:

List of group names

Return type:

list

latticeObjects: Dict = {}

Dictionary containing all frameworkLattice objects

property lattices: list

Returns a list of all lattice names

Returns:

List of lattice names

Return type:

list

property lines: list

Returns a list of all lattice names

Returns:

List of lattice names

Return type:

list

loadElementErrors(file)

Load element errors file; see loadElementErrors()

Parameters:

file (str) – Errors file

Return type:

None

loadParametersFile(file)

loadSettings(filename=None, settings=None)

Load Lattice Settings from file or dictionary. These settings contain the lattice lines and their respective settings, YAML files and global parameters.

Parameters:

• filename (str or None) – Name of .def file containing lattice definitions

• settings (FrameworkSettings or None) – Settings for the lattice

Return type:

None

load_Elements_File(inp)

Load a YAML file or list of YAML files with element definitions. The elements entry in this file(s) are then parsed and read into elementObjects in order to build up the frameworkLattice object.

Parameters:

inp (str or list or tuple or dict) – Input file or dict containing the lattice elements

Return type:

None

load_changes_file(filename=None, apply=True, verbose=False)

Loads a saved changes file and applies the settings to the current lattice. Returns a list of changes. See apply_changes().

Parameters:

• filename (str or list or tuple or None) – Changes filename to save; if None, base it on the settings filename

• apply (bool) – Flag to apply the changes

• verbose (bool) – Flag to print the changes applied

Returns:

If filename is a list or tuple, call this function again If filename is None or a str, return the dictionary of changes.

Return type:

dict or list

machine: LAURA = None

LAURA model of lattice

master_lattice: str | None = None

Location of the master lattice files. If the package is installed, this will be configured automatically

modifyElement(elementName, parameter, value=None)

Modifies an element parameter

Parameters:

• elementName (str) – Name of element to modify

• parameter (list or str or dict) – Parameter to modify

• value (Optional[Any]) – Value to set on that element

Return type:

None

modifyElementType(elementType, parameter, value)

Modifies an element or a list of elements of a given type

Parameters:

• elementType (str) – Type of element to modify

• parameter (str) – Parameter of that element type to modify

• value (Any) – Value to set on that element(s)

Return type:

None

modifyElements(elementNames, parameter, value=None)

Modifies parameters for multiple elements

Parameters:

• elementNames (str or list) – Name(s) of element to modify

• parameter (list or str or dict) – Parameter to modify

• value (Optional[Any]) – Value to set on those elements

Return type:

None

modifyLattice(latticeName, parameter, value=None)

Modify a lattice definition,

Parameters:

• latticeName (str) – Name of lattice to modify

• parameter (str or list or dict) – Parameter(s) to update with their values

• value (Any) – Value to update

Return type:

None

modifyLattices(latticeNames, parameter, value=None)

Modify a lattice definition for a list of lattices

Parameters:

• latticeNames (str or list) – Name of lattice(s) to modify

• parameter (str or list or dict) – Parameter(s) to update with their values

• value (Any) – Value to update

Return type:

None

offsetElements(x=0, y=0, z=0)

Moves all elements by the set amount in (x, y, z) space. Updates elementObjects.

Parameters:

• x (int | float) – x offset

• y (int | float) – y offset

• z (int | float) – z offset

Return type:

None

original_elementObjects: Dict = {}

Dictionary containing all Element objects before changes are made

overwrite: bool | None = None

Flag to indicate whether existing files are to be overwritten #TODO deprecated?

password: str = ''

Password for remote execution

postProcess(files=None, startfile=None, endfile=None)

Post-processes the tracking files and converts them to HDF5. See postProcess() and the same function in the child classes for specific codes.

Parameters:

• files (list or None) – List of lattice names; if None, process all

• startfile (str or None) – Starting lattice object; if None, process from the start

• endfile (str or None) – End lattice object; if None, process to the end

Return type:

None

prepare_executables(location=None, ncpu=1)

Parameters:

• location (Optional[str])

• ncpu (int)

progress: int | float = 0

Current progress of tracking

pushRunSettings()

Updates the ‘Run Settings’ in each of the lattices

Return type:

None

read_Lattice(name, lattice)

Create an instance of a <code>Lattice class; see frameworkLattice and its child classes. This instance is then added to the latticeObjects dictionary.

Parameters:

• name (str) – The name of the lattice line

• lattice (dict) – Dictionary containing settings for the lattice line

Return type:

None

runname: str = 'CLARA_240'

Name of the run for this setup #TODO deprecated?

saveParametersFile(file, parameters)

Saves a list of parameters to a file

Parameters:

• file (str)

• parameters (dict | list | tuple)

Return type:

None

save_changes_file(filename=None, typ=None, elements=None, dictionary=False)

Save a file, or returns a dictionary, of detected changes in the lattice from the loaded version.

Parameters:

• filename (str or None) – Name of file containing changes; defaults to changes.yaml

• typ (str or None) – Element types to check; if None, check all

• elements (dict or None) – Dictionary containing elements and parameters to check; if None, check all

• dictionary (bool) – Flag to return changes as dictionary; if False, save a YAML file

Returns:

If dictionary, return a dict; otherwise, save a file and return None

Return type:

dict or None

save_lattice(lattice=None, filename=None, directory='.')

Save lattice to a file, or return a dictionary containing the lattice elements

Parameters:

• lattice (str or None) – Name of lattice file; if None, sets to the name of the lattice

• filename (str or None) – Name of the file to be saved; if None, sets to the name of the lattice + ‘_lattice.yaml’

• directory (str) – Directory to which the file will be saved

Return type:

dict | None

save_settings(filename=None, directory='.', elements=None)

Save Lattice Settings to a file.

Parameters:

• filename (str or None) – Filename to which the settings will be saved; defaults to settings.def

• directory (str) – Directory to which the settings will be saved

• elements (dict or None) – Dictionary of Element objects to save

Return type:

None

save_summary_files(twiss=True, beams=True)

Saves HDF5 summary files for the Twiss and/or Beam files using load_directory() and save_HDF5_summary_file()

Parameters:

• twiss (bool) – If True, save Twiss_Summary.hdf5 in subdirectory

• beams (bool) – If True, save Beam_Summary.hdf5 in subdirectory

Return type:

None

sddsindex: int = 0

Index for SDDS files

setElementScan(name, item, scanrange, multiplicative=False)

Define a parameter scan for a single parameter of a given machine element. See setElementScan

Parameters:

• name (str) – Name of element to scan

• item (str) – Parameter of that element to scan

• scanrange (list) – List of values to set

• multiplicative (bool) – Flag to indicate whether settings are multiplicative or additive with respect to the original value

Return type:

None

setElementType(typ, setting, values)

Modifies the specified parameter of each element of a given type

Parameters:

• typ (str) – All elements of a given type to set

• setting (str) – Parameter in those elements to set

• values (Any) – Values to set on those elements

Raises:

ValueError – If there is a mismatch between the length of values and the number of elements of that type

Return type:

None

setMasterLatticeLocation(master_lattice=None)

Set the location of the LAURA package.

This then also sets the master_lattice in global_parameters.

Parameters:

master_lattice (str) – The full path to the LAURA master lattice folder

Return type:

None

setNRuns(nruns)

Sets the number of simulation runs to a new value for all lattice objects. See setNRuns().

Parameters:

nruns (int) – Number of runs to set up

Return type:

None

setSeedValue(seed)

Sets the random number seed to a new value for all lattice objects

See setSeedValue().

Parameters:

seed (int) – Random number seed

Return type:

None

setSimCodesLocation(simcodes=None)

Set the location of the SimCodes package.

This then also sets the simcodes_location in global_parameters.

Parameters:

simcodes (str) – The full path to the SimCodes folder

Return type:

None

setSubDirectory(direc)

Change the subdirectory and master_subdir in global_parameters to which lattice and beam files will be written.

If clean, then all existing files in the directory are removed.

Parameters:

direc (str) – Directory to which files will be written. If directory does not exist, create it.

Return type:

None

set_lattice_prefix(lattice, prefix)

Sets the ‘prefix’ parameter for a lattice in latticeObjects, which determines where it looks for its starting beam distribution.

Parameters:

• lattice (str) – Name of lattice

• prefix (str) – Lattice prefix

Return type:

None

set_lattice_sample_interval(lattice, interval)

Sets the ‘sample_interval’ parameter for a lattice, which determines the sampling of the distribution. See sample_interval.

Parameters:

• lattice (str) – Name of lattice

• interval (int) – Sampling interval in units of 2 ** (3 * interval)

Return type:

None

settings: FrameworkSettings | None = None

Settings for the lattice

settingsFilename: str | None = None

Filename containing lattice settings

setupGeneratorDefaults(generator_defaults)

Parameters:

generator_defaults (str | None)

setupLAURA()

Sets up the LAURA machine

Return type:

None

setup_remote_execution(lattice, code, server, ncpu=1, ngpu=1, exclude=None, username=None, password=None)

Prepares the simulation of a given lattice line for remote execution on a server. This function modifies the remote_setup and executables attributes of the given lattice object, meaning that it can be run remotely using the run method of the lattice object.

The servers are defined in the hosts dictionary, each of which contain an address and the available codes.

Parameters:

• lattice (str) – Name of the lattice line; if “All”, sets up all lattice lines in the same way.

• code (str) – Code to be used for the remote execution. If the current lattice line is not set up for this code, then change_Lattice_Code() is called to change the code of the lattice line.

• server (str) – Name of server on which to execute the simulation. The server must be defined in the hosts dictionary.

• ncpu (int) – Number of CPUs to use for the remote execution. Default is 1.

• ngpu (int) – Number of GPUs to use for the remote execution. Default is 1. Not currently implemented.

• exclude (str | list | tuple | None (optional)) – Lattice line(s) to exclude from the remote execution setup.

• username (str | None (optional)) – Username for SSH login to the server. Defaults to username of the Framework instance, if set.

• password (str | None (optional)) – Password for SSH login to the server. Defaults to password of the Framework instance, if set.

Raises:

• ValueError – If server is not found in the defined hosts.

• ValueError – If code is not available on the specified server.

• ValueError – If username or password is not provided and not set in the Framework instance.

Return type:

None

simcodes: str | None = None

Location of the simulation codes directory. If the package is installed, this will be configured autonatically

track(files=None, startfile=None, endfile=None, preprocess=True, write=True, track=True, postprocess=True, save_summary=True, frameworkDirec=False, check_lattice=True)

Tracks the current machine, or a subset based on the ‘files’ list. The lattice is checked (check_lattice()) and saved (save_lattice()), the settings file is saved (save_settings()), and then each line in the lattice is tracked with the code specified.

Parameters:

• files (list or None) – List of files (lattice names) to track; if None, track all

• startfile (str or None) – Initial lattice name for tracking; if None, track all

• endfile (str or None) – Final lattice name for tracking; if None, track all

• preprocess (bool) – Call preProcess() before tracking each line

• write (bool) – Write each lattice file

• track (bool) – Track each lattice

• postprocess (bool) – Call postProcess() after tracking each line

• save_summary (bool) – Save beam and Twiss summary files

• frameworkDirec (bool) – If True, return a frameworkDirectory object

• check_lattice (bool) – Call check_lattice() before tracking

Returns:

Framework directory object if frameworkDirec is True

Return type:

frameworkDirectory or None

tracking: bool = False

Flag to indicate whether the Framework is tracking

updateGlobalParameters()

username: str = ''

Username for remote execution

verbose: bool = True

Flag to indicate whether status updates should be printed during tracking

class NumpySafeDumper(stream, default_style=None, default_flow_style=False, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None, sort_keys=True)

Bases: SafeDumper

yaml_representers = {<class 'NoneType'>: <function SafeRepresenter.represent_none>, <class 'bool'>: <function SafeRepresenter.represent_bool>, <class 'bytes'>: <function SafeRepresenter.represent_binary>, <class 'datetime.date'>: <function SafeRepresenter.represent_date>, <class 'datetime.datetime'>: <function SafeRepresenter.represent_datetime>, <class 'dict'>: <function SafeRepresenter.represent_dict>, <class 'float'>: <function SafeRepresenter.represent_float>, <class 'int'>: <function SafeRepresenter.represent_int>, <class 'list'>: <function SafeRepresenter.represent_list>, <class 'munch.Munch'>: <function to_yaml_safe>, <class 'numpy.bool'>: <function numpy_scalar_representer>, <class 'numpy.float32'>: <function numpy_scalar_representer>, <class 'numpy.float64'>: <function numpy_scalar_representer>, <class 'numpy.generic'>: <function numpy_scalar_representer>, <class 'numpy.int32'>: <function numpy_scalar_representer>, <class 'numpy.int64'>: <function numpy_scalar_representer>, <class 'numpy.ndarray'>: <function numpy_array_representer>, <class 'set'>: <function SafeRepresenter.represent_set>, <class 'str'>: <function SafeRepresenter.represent_str>, <class 'tuple'>: <function SafeRepresenter.represent_list>, None: <function SafeRepresenter.represent_undefined>}

dict_constructor(loader, node)

dict_representer(dumper, data)

class frameworkDirectory(*args, **kwargs)

Bases: BaseModel

Class to load a tracking run from a directory and read the Beam and Twiss files and make them available

beams: bool | beamGroup | None = False

Flag to indicate whether to load beam files

changes: str = 'changes.yaml'

Lattice changes filename

directory: str | None = None

Directory from which to load beam and Twiss files

element(element, field=None)

Get an element definition from the framework object.

Parameters:

• element (str) – Element to retrieve

• field (str | None) – Field of that element to retrieve

Returns:

Get the field of element, or the entire Element if not field

Return type:

Any or Element

framework: Framework | None = None

Framework instance

general_plot(*args, **kwargs)

Return a general_plot object; see general_plot().

getScreen(screen)

Get a beam object for the given screen; see getScreen()

Parameters:

screen (str) – Name of screen

Returns:

The beam object from screen

Return type:

beam

Raises:

ValueError – If beams is not a beamGroup object

getScreenNames()

Get beam objects from all screens

Returns:

The beam objects from the screen keyed by name

Return type:

Dict

Raises:

ValueError – If beams is not a beamGroup object

plot(*args, **kwargs)

Return a plot object; see plot().

rest_mass: float | None = None

Particle rest mass

save_summary_files(twiss=True, beams=True)

Save summary files in framework directory; see save_summary_files().

Parameters:

• twiss (bool) – If True, save Twiss_Summary.hdf5 in directory

• beams (bool) – If True, save Beam_Summary.hdf5 in directory

settings: str = 'settings.def'

Framework settings filename

twiss: bool | twiss = True

Flag to indicate whether to load Twiss files

verbose: bool = False

Flag to print status updates

load_directory(directory='.', twiss=True, beams=False, **kwargs)

Load a directory from a SIMBA tracking run and return a frameworkDirectory object

Parameters:

• directory (str)

• twiss (bool)

• beams (bool)

Return type:

frameworkDirectory

numpy_array_representer(dumper, data)

numpy_scalar_representer(dumper, data)