core_io¶

Module for MAD-X interaction and parsing of TFS tables to Twiss tables.

class pockpy.core_io.MadxWrapper¶

Wrapper of the MAD-X wrapper cpymad.

This class is dedicated to providing useful combinations of MAD-X commands to be used as part of orbit correction analysis. For any other use of MAD-X, instead make use of cpymad directly.

Example:

>>> madx = pockpy.MadxWrapper()
>>> madx.input('some_machine.madx')
>>> madx.use_sequence('B1')
>>> twiss1 = madx.twiss(return_summ_table=False)
>>> shift_error = {'DX' : 1e-6}
>>> madx.add_misalignment(
...     pattern='MQ.12R5.B1',
...     errors=shift_error
... )
>>> twiss2 = madx.twiss(return_summ_table=False)
>>> perturbation = twiss2['X'] - twiss1['X']

add_field_error(pattern, errors, add_errors=True)¶

Adds field errors to elements in the active sequence.

For more information about the impact of adding field errors and context, see the MAD-X documentation.

Parameters

pattern (str) – Regular expression defining elements in the active sequence which are to have field errors added to them.
errors (dict) –
Dictionary of the form:
```
errors = {
    'DKN19' : 3.0,
    'DKS1' : 2.0,
    'DKNR1' : 4.0,
}
```
where the keys are using the MAD-X standard for EFCOMP in the sense that ‘DKN18’ corrsponds to ‘dkn(18)’, and the values are the corresponding magnitude of the errors. The pockpy.solver notation where ‘DK’ and ‘DKR’ are interpreted as ‘DKN’ and ‘DKNR’ respectively is supported.

Raises

ValueError – If errors does not match expected format.

add_misalignment(pattern, errors, add_errors=True)¶

Adds misalignments to matched elements in the active sequence.

Parameters

pattern (str) – Regular expression to match elements in the active sequence which are to have added misalignments.
errors (dict) – Dictionary mapping from MAD-X errors to floats.
add_errors (bool) – True if errors introduced by the call are to increment already existing ones, otherwise they are overwritten.

add_solver_element_errors(errors, add_errors=True)¶

Adds errors using an error dictionary compatible with Solver.

Parameters

errors (dict) –
Dict of the form:
```
errors = {
    pattern : {
        error_type : val
    }
}
```
where pattern is a regular expression matching elements which are to have their errors updated and error_type is a valid type of error as used in Solver, i.e. one of:
```
['DX', 'DY', 'DPSI', 'DS', 'DK0', 'DKR0', 'DK1', 'DKR1']
```
add_errors (bool) – True if all impacted errors are to be incremented, otherwise their previous errors are overwritten.

available_aperture_scan(aperture_offset, co_li, run_thrice=False, optics_type='round', col_formatter=None)¶

Performs multiple aperture computations for a list of closed orbit uncertainties, and pre-defined parameters.

Warning

Assumes an (HL-)LHC machine.

Runs an APERTURE call in MAD-X with some pre-defined parameters. For in-depth information, see the official MAD-X documentation.

Parameters

aperture_offset (str) – Path to a valid element OFFSETELEM as defined in MAD-X.
co (list) – Iterable, sorted in ascending order, of closed orbit uncertainties.
run_thrice (float) –
If False runs a single APERTURE call to compute the aperture, otherwise runs the call for three different settings and returns the worst aperture among them for each point. The three scenarios are
1. DeltaP = dPmax with a bucket edge of 0.
2. DeltaP = -dPmax with a bucket edge of 0
3. DeltaP = 0 with a bucket edge of dPmax.
optics_type (str) – Type of optics. Should be one of ‘round’, ‘flat’ or ‘injection’.

Returns

A DataFrame with the available aperture given per provided closed orbit uncertainty in co_li.

call(filename)¶

Executes the provided .madx file in MAD-X.

Parameters: filename (str) – A path to a .madx file

compute_aperture_table(aperture_offset, co=0, run_thrice=False, optics_type='round')¶

Performs an aperture computation with pre-defined parameters.

Warning

Assumes an (HL-)LHC machine.

Runs an APERTURE call in MAD-X with some pre-defined parameters. For in-depth information, see the official MAD-X documentation.

Parameters

aperture_offset (str) – Path to a valid element OFFSETELEM as defined in MAD-X.
co (float) – Closed orbit uncertainty.
run_thrice (float) –
If False runs a single APERTURE call to compute the aperture, otherwise runs the call for three different settings and returns the worst aperture among them for each point. The three scenarios are
1. DeltaP = dPmax with a bucket edge of 0.
2. DeltaP = -dPmax with a bucket edge of 0
3. DeltaP = 0 with a bucket edge of dPmax.
optics_type (str) – Type of optics. Should be one of ‘round’, ‘flat’ or ‘injection’.

Returns

A DataFrame with the available aperture.

get_corrector_strength(index)¶

Returns the corrector strength in the machine.

NOTE: Corrector strength is given in radians.

Parameters: index (list) – List or pandas Index containing corrector names of interest.
Returns: A pandas Series containing the corrector strength usage of each corrector specified by index.

input(cmd)¶

Executes a given command in MAD-X.

Parameters: cmd (str) – A MAD-X command on a single line.

makethin(sequence, option_li)¶

Executes a MAKETHIN command in MAD-X.

Parameters

sequence (str) – Name of sequence to be made thin.
option_li (list) –
List of dicts as per:
```
option_li = [
    {
        'class' : 'QUADRUPOLE',
        'slice' : 10
    },
    {
        'pattern' : '^MQXF.*',
        'slice' : 20
    },
]
```
Any given dict must contain a ‘slice’ entry, and at least one of ‘class’ and ‘pattern’.

The selections are performed sequentially with the options of the first dictionary in the list applied first and terminated by a MAKETHIN command.

Raises

KeyError – If option_li does not match expected format.

quit()¶: Terminates the current MAD-X instance.

remove_all_sextupole_fields()¶: Sets the strength of all sextupoles to zero.

remove_errors(pattern='.*')¶

Removes all misalignments and field errors from matched elements.

Parameters: pattern – Regular expression specifying all elements in the active sequence which are to have their misalignments and field errors removed. Defaults to maching all elements.

set_corrector_strength(corrector_dict, increment=False)¶

Adds strength to specified correctors in the active sequence.

NOTE: Corrector strength is given in radians.

Parameters

corrector_dict (dict) – A dict-like (e.g. pandas.Series) mapping from corrector name to corrector strength in radians.
increment (bool) – If True, increments the current corrector strength in the machine.

twiss(centre=True, return_summ_table=True, return_minimal_columns=False)¶

Runs Twiss inside MAD-X for the active sequence.

Parameters

centre (bool) – True if Twiss parameters are to be evaluated at the middle of elements, otherwise they are evalutated at their entrance.
return_summ_table (bool) – True if the SUMM table is to be returned as a second output.
return_minimal_columns (bool) – True if only the columns used for POCKPy (as defined in config.MINIMUM_TWISS_COLUMNS) are to be returned for the Twiss table.

Returns

The Twiss and SUMM table from the Twiss call if return_summ_table is True, otherwise just the Twiss table.

Raises

RuntimeError – If no Twiss table is produced.

use_sequence(seq, start='#S', end='#E')¶

Sets the active sequence inside MAD-X.

Parameters

seq (str) – Sequence to activate.
start (str) – Element from which the active sequence starts. Defaults to the first element of the sequence.
end (str) – Element defining the end of the active sequence. Defaults to the last element of the sequence.

verbose(switch=True)¶

Makes the output less or more verbose inside the MAD-X instance.

Note

Does not always result in any notable difference.

Parameters: switch (bool) – True for more verbose, False for less.

pockpy.core_io.load_tfs_table(filename)¶

Takes a .tfs file and returns the Twiss and SUMM tables.

Parameters: filename (str) – Path to .tfs file from a Twiss call.
Returns: A Twiss and SUMM table for the given machine and beam.

pockpy.core_io.madx_to_tables(filename, makethin_option_li=None)¶

Takes a .madx file for a machine and returns a Twiss table to be used for the for Solver.

Parameters: filename (str) – Path to a .madx file defining the machine.
Returns: A Twiss table DataFrame and a Summ table expressed as a dict, both containing the requisite data for the sequences defined in config.SEQUENCE_NAMES.

pockpy.core_io.tfs_to_tables(filename_dict)¶

Takes .tfs files and returns a Twiss table for Solver.

Parameters: filename_dict (dict) – A dict mapping from beam name to corresponding .tfs table.
Returns: A DataFrame containing the Twiss table for input to Solver.