Working with Zgoubi Input

Zgoubidoo’s input module: interface for Zgoubi input file.

This module interfaces Zgoubi input files to the other components of Zgoubidoo. Its main feature is the Input class, which allows to represent a set of Zgoubi input commands and serialize it into a valid input file. The input can also be validated using a set of validators, following the Zgoubi input constraints.

The inputs are serialized and saved as zgoubi.dat in temporary directories. When serializing an input it is possible to provide a parametric mapping (combinations of the variations of one or more parameters) to generate multiple Zgoubi input files.

zgoubidoo.input.PathsListType = typing.List[typing.Tuple[typing.Mapping[str, typing.Union[pint.quantity.build_quantity_class.<locals>.Quantity, float, str]], typing.Union[str, tempfile.TemporaryDirectory], bool]]

Type alias for a list of parametric keys and paths values.

exception zgoubidoo.input.ZgoubiInputException(m)

Exception raised for errors within Zgoubi Input.

class zgoubidoo.input.Input(name: str = 'beamline', line: Optional[Sequence[zgoubidoo.commands.commands.Command]] = None)

Main class interfacing Zgoubi input files data structure.

A Zgoubidoo Input object represents the Zgoubi input file data structure. It is thus essentially a list of Zgoubidoo objects representing commands and elements for the generation of Zgoubi input files.

The Input supports a str representation allowing to generate the Zgoubi input. Additionnally, calling the object will write the string representation to a Zgoubi input file.

Parameters

• name – name of the input to be created.

• line – if not None the new input will contain that Command sequence.

Examples

>>> zi = Input(name='test_beamline')
>>> len(zi) == 0
True
>>> zi.name
'test_beamline'
>>> zi()

__str__() → str

Provides the string representation, a valid Zgoubi input stream.

Constructs the Zgoubi input sequence with the serialization of each command. An implicit End command is added in case it is not present. The Input name is used as a header.

Returns

a valid Zgoubi input stream as a string.

__call__(*, mappings: Optional[List[Mapping[str, Union[pint.quantity.build_quantity_class.<locals>.Quantity, float, str]]]] = None, filename: str = 'zgoubi.dat', path: Optional[str] = None) → zgoubidoo.input.Input

TODO :param mappings: :param filename: :param path:

Returns:

__len__() → int

Length of the input sequence.

Returns

the number of elements in the sequence.

__iadd__(command: zgoubidoo.commands.commands.Command) → zgoubidoo.input.Input

Append a command at the end of the input sequence.

Parameters

command – the command to be appended.

Returns

the input sequence (in-place operation).

__isub__(other: Union[str, zgoubidoo.commands.commands.Command]) → zgoubidoo.input.Input

Remove a command from the input sequence.

Parameters

other – the Command to be removed or the LABEL1 of the command to be removed as a string.

Returns

the Input itself (in-place operation).

__getitem__(items: Union[slice, int, float, str, CommandType, type, Iterable[Union[CommandType, type, str]]]) → Union[_Command, Input]

Multi-purpose dictionnary-like elements access and filtering.

A triple interafce is provided:

• numerical index: provides the element from its numeric index (starting at 0, looked-up in the line property of the input (the returned object is a Command);

• slicing: provides a powerful slicing feature, using either object slice or string slice (or a mix of both); see example below (the returned object is a copy of the sliced input);

• element access: returns a filtered input containing only the given elements. The elements are given either in the form of a list of strings (or a single string), representing the class name of the element or in the form of a list of classes (or a single class).

Parameters

items – index based accessor, slice or elements types for filtering access (see above).

Returns

• with numerical index returns the object located at that position (an instance of a Command);

• with slicing returns a copy of the input, with the slicing applied (an instance of a Input);

• with element access returns a filtering copy of the input (an instance of a Input).

__getattr__(item: str) → zgoubidoo.commands.commands.Command

Parameters

item –

Returns:

__setattr__(key: str, value: Any)

Parameters

• key –

• value –

Returns:

__contains__(items: Union[str, CommandType, Tuple[Union[str, CommandType]]]) → int

Parameters

items –

Returns:

apply(f: Callable[[zgoubidoo.commands.commands.Command], zgoubidoo.commands.commands.Command]) → zgoubidoo.input.Input

Apply (map) a function on each command of the input sequence.

The function must take a single command as unique parameter and return the (modified) command.

Parameters

f – the calable function.

Returns

the input sequence (in place operation).

cleanup()

Cleanup temporary paths.

Performs the cleanup to remove the temporary paths and the Zgoubi data files (input file, but also other parent files). This is essentially the inverse of calling the input. Note that coding the input multiple times will automatically cleanup previous sets of temporary directories.

Examples

>>> zi = Input()
>>> pm = ParametricMapping()
>>> zi(mappings=pm)  # Writes input files in newly created tempoary directories
>>> zi.cleanup()  # Cleanup the temporary directories and Zgoubi input files

validate(validators: Optional[List[Callable]]) → bool

Parameters

validators –

Returns:

update(parameters: pandas.core.frame.DataFrame) → zgoubidoo.input.Input

TODO

This is essentially an update following a fit.

Parameters

parameters –

Returns:

adjust(mapping: Mapping[str, Union[pint.quantity.build_quantity_class.<locals>.Quantity, float, str]]) → Mapping[str, Union[pint.quantity.build_quantity_class.<locals>.Quantity, float, str]]

Parameters

mapping –

Returns:

index(obj: Union[str, zgoubidoo.commands.commands.Command]) → int

Index of an object in the sequence.

Provides an index for a given object within a sequence.

Parameters

obj – the object; can be an instance of a Zgoubidoo Command or a string representing the element’s LABEL1.

Returns

the index of the object in the input sequence.

Raises

ValueError if the object is not present in the input sequence. –

zgoubi_index(obj: Union[str, zgoubidoo.commands.commands.Command]) → int

Index of an object in the sequence (following Zgoubi elements numbering).

Provides an index for a given object within a sequence. This index is a valid Zgoubi command numbering index and can be used as such, for example, as a parameter to the Fit command.

Parameters

obj – the object; can be an instance of a Zgoubidoo Command or a string representing the element’s LABEL1.

Returns

the index of the object in the input sequence.

Raises

ValueError if the object is not present in the input sequence. –

replace(element, other) → zgoubidoo.input.Input

Parameters

• element –

• other –

Returns:

insert_before(element, other) → zgoubidoo.input.Input

Parameters

• element –

• other –

Returns:

insert_after(element, other) → zgoubidoo.input.Input

Parameters

• element –

• other –

Returns:

remove(prefix: str) → zgoubidoo.input.Input

Parameters

prefix –

Returns:

get_attributes(attribute: str = 'LABEL1') → List[str]

List a given command attribute in the input sequence.

In case some elements in the input sequence do not have that attribute, None is used.

Parameters

attribute – the name of the attribute.

Returns

the list of the values of the given attribute across the input sequence.

property labels

List of the LABEL1 property of each element of the input sequence.

property labels1

Same as labels.

property labels2

List of the LABEL2 property of each element of the input sequence.

property name

Name of the input sequence.

Returns

the name of the input sequence or None.

property paths

Paths where the input has been written.

Returns

a list of paths.

property mappings

List of mappings existing for the input sequence.

property keywords

Returns:

property line

Returns:

property survey_reference_frame

Provides the reference frame which was used for the prior survey of the line.

property beam

Returns:

Raises

TODO –

property beam_mappings

Returns:

survey(reference_frame: Optional[georges_core.frame.Frame] = None, with_reference_trajectory: bool = False, reference_kinematics: Optional[georges_core.kinematics.Kinematics] = None, reference_particle: Union[zgoubidoo.commands.particules.Particule, zgoubidoo.commands.particules.ParticuleType, None] = None, reference_closed_orbit: Optional[numpy.ndarray] = None, output: bool = False) → pandas.core.frame.DataFrame

Perform a survey on the input sequence.

Parameters

• reference_frame – a Zgoubidoo Frame object acting as the global reference frame.

• with_reference_trajectory –

• reference_kinematics –

• reference_particle –

• reference_closed_orbit –

• output –

Returns

the surveyed input sequence.

property valid_survey

Returns:

set_valid_survey()

Returns:

clear_survey()

Returns:

execute()

Returns:

save(destination: str = '.', what: Optional[List[str]] = None, executed_only: bool = True)

Save input and/or parent Zgoubi files to a user specified directory.

This is essentially a functionality allowing the user to save data files for further (external) post-processing.

Parameters

• destination – path to the destination where the files will be saved

• what – a list of files to be saved (default: only zgoubi.dat)

• executed_only – if True, will save only the files for the paths that have been executed by Zgoubi

classmethod from_sequence(sequence: georges_core.sequences.Sequence, options: Optional[dict] = None, converters: Optional[dict] = None, elements_database: Optional[dict] = None, beam: Optional[_BeamType] = <class 'zgoubidoo.commands.beam.BeamTwiss'>, beam_options: Optional[Mapping] = None, with_survey: bool = True, with_survey_reference: bool = True)

Parameters

• sequence –

• options –

• converters –

• elements_database –

• beam –

• beam_options –

• with_survey –

• with_survey_reference –

Returns:

static build(name: str = 'beamline', line: Optional[Deque[zgoubidoo.commands.commands.Command]] = None) → str

Build a string representing the complete input.

A string is built based on the Zgoubi serialization of all elements (commands) of the input sequence.

Parameters

• name – the name of the resulting Zgoubi input.

• line – the input sequence.

Returns

a string in a valid Zgoubi input format.

classmethod parse(stream: str, debug: bool = False) → zgoubidoo.input.Input

Parameters

• stream –

• debug –

Returns:

class zgoubidoo.input.ZgoubiInputValidator

Validation methods for Zgoubi Input.

Follows the rules as defined in the Zgoubi code and manual.

static validate_objet_is_first_command(_: zgoubidoo.input.Input) → bool

Validate that the first input command is a (mc)objet.

Parameters

_ – the input to validate

Returns

True if the validation is successful; otherwise a ZgoubiInputException is raised.

static validate_objets_do_not_exceed_imax(_: zgoubidoo.input.Input) → bool

Validate that all objets and mcobjets have their IMAX value below the maximum value.

Parameters

_ – the input to validate

Returns

True is the validation is successful; otherwise a ZgoubiInputException is raised.