Zgoubi¶

Additional documentation can be found in the following references:

https://arxiv.org/pdf/1405.4921.pdf

Running Zgoubi with Zgoubidoo¶

Provides an interface to run Zgoubi from Python; supports multiprocessing and concurrent programming.

See also

The full Zgoubi User Guide can also be consulted for reference.

exception zgoubidoo.zgoubi.ZgoubiException(m)[source]¶: Exception raised for errors when running Zgoubi.

class zgoubidoo.zgoubi.ZgoubiResults(results: List[Mapping], options: Optional[Mapping] = None)[source]¶

Results from a Zgoubi executable run.

ZgoubiResults is used to store results and outputs from a single or multiple Zgoubi runs. It is instanciated from a list of dictionnaries containing the results (each one being a mapping between MappedParameters (to identify from which run the results are from) and the results themselves (also a dictionnary)).

Methods and properties of ZgoubiResults are used to access and process individual or multiple results. In particular it is possible to extract a set of tracks from the results.

Examples

>>> 1 + 1 # TODO

Parameters

results – a list of dictionnaries structure with the Zgoubi run information and errors.
options –

classmethod merge(*results: zgoubidoo.zgoubi.ZgoubiResults)[source]¶

Merge multiple ZgoubiResults into one.

Parameters: results – list of ZgoubiResults to copy
Returns: a new ZgoubiResults instance containing the concatenated results.

__len__() → int[source]¶: Length of the results list.

__copy__() → zgoubidoo.zgoubi.ZgoubiResults [source]¶: Shallow copy operation.

__getitem__(item: int)[source]¶: Retrieve results from the list using a numeric index.

get_tracks(parameters: Optional[_MappedParametersListType] = None, force_reload: bool = False, transformation: Optional[_CoordinateTransformationType] = None) → _pd.DataFrame[source]¶

Collects all tracks from the different Zgoubi instances matching the given parameters list in the results and concatenate them.

Parameters

parameters –
force_reload –
transformation –

Returns

A concatenated DataFrame with all the tracks in the result matching the parameters list.

property tracks¶

Collects all tracks from the different Zgoubi instances in the results and concatenate them.

Returns: A concatenated DataFrame with all the tracks in the result.

property tracks_global¶

Collects all tracks from the different Zgoubi instances in the results and concatenate them.

Returns: A concatenated DataFrame with all the tracks in the result.

property tracks_frenet¶

Collects all tracks from the different Zgoubi instances in the results and concatenate them.

Returns: A concatenated DataFrame with all the tracks in the result.

get_srloss(parameters: Optional[_MappedParametersListType] = None, force_reload: bool = False) → _pd.DataFrame[source]¶

Parameters

parameters –
force_reload –

Returns:

property srloss¶: Returns:

get_srloss_steps(parameters: Optional[_MappedParametersListType] = None, force_reload: bool = False, with_survey: bool = True) → _pd.DataFrame[source]¶

Parameters

parameters –
force_reload – the data are cached in most cases to allow multiple calls, this flag will force the data to
reloaded. (be) –
with_survey – performs the transformation of the coordinates using the survey information (this is
a transformation from the local coordinates of the element to the global reference frame) (basically) –

Returns:

property srloss_steps¶: Returns:

property matrix¶

Collects all matrix data from the different Zgoubi instances in the results and concatenate them.

Returns: A concatenated DataFrame with all the matrix information from the previous run.

get_optics(force_reload: bool = False) → Optional[pandas.core.frame.DataFrame][source]¶

Collects all optics data from the different Zgoubi instances in the results and concatenate them.

Parameters: force_reload –
Returns: A concatenated DataFrame with all the optics information from the previous run.

property optics¶: Returns:

compute_step_by_step_transfer_matrix(force_reload: bool = False) → Optional[pandas.core.frame.DataFrame][source]¶

Parameters: force_reload –

Returns:

property step_by_step_transfer_matrix¶: Returns:

compute_step_by_step_optics(twiss_init: Optional[georges_core.sequences.betablock.BetaBlock] = None, force_reload: bool = False) → Optional[pandas.core.frame.DataFrame][source]¶

Parameters

twiss_init –
force_reload –

Returns:

property step_by_step_periodic_optics¶: Returns:

property results¶

Raw information from the Zgoubi run.

Provides the raw data structures from the Zgoubi runs.

Returns: a list of mappings.

property paths¶

Path of all the directories for the runs present in the results.

Returns: a list of directories.

property mappings¶

Parametric mappings of all the runs present in the results.

Returns: a list of parametric mappings.

save(destination: str = '.', what: Optional[List[str]] = None)[source]¶

Save files.

Parameters

destination –
what –

print(what: str = 'result')[source]¶: Helper function to print the raw results from a Zgoubi run.

class zgoubidoo.zgoubi.Zgoubi(executable: str = 'zgoubi', path: Optional[str] = None, n_procs: Optional[int] = None)[source]¶

High level interface to run Zgoubi from Python.

Zgoubi is responsible for running the Zgoubi executable within Zgoubidoo. It will run Zgoubi as a subprocess and offers a variety of concurency and parallelisation features.

The Zgoubi object is an interface to the Zgoubi executable. The executable can be found automatically or its name and path can be specified.

The Zgoubi executable is called on an instance of Input specifying a list of paths containing Zgoubi input files. Multiple instances can thus be run in parallel.

TODO details on concurrency

Parameters

executable (-) – name of the Zgoubi executable
path (-) – path to the Zgoubi executable
n_procs (-) – maximum number of Zgoubi simulations to be started in parallel

EXECUTABLE_NAME: str = 'zgoubi'¶: Default name of the Zgoubi executable.

INPUT_FILENAME: str = 'zgoubi.dat'¶: Name of the input file (typically zgoubi.dat).

RESULT_FILE: str = 'zgoubi.res'¶: Default name of the Zgoubi result ‘.res’ file.

static find_labeled_output(out: Iterable[str], label: str, keyword: str) → List[str][source]¶

Process the Zgoubi parent and retrieves parent data for a particular labeled element.

Parameters

out (-) – the Zgoubi parent
label (-) – the label of the element to be retrieved
keyword (-) –

Returns

the parent of the given label