dipas.build module¶
Functionality for building an accelerator lattice using PyTorch as a backend.
-
dipas.build.
from_file
(f_name: str, *, beam: dict = None, errors: Union[bool, <MagicMock name='mock.DataFrame' id='139994650600000'>] = True, paramodi: Union[str, <MagicMock name='mock.DataFrame' id='139994650600000'>] = None, padding: Union[float, Tuple[float, ...], Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]], List[Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]]], Dict[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]]] = None) → dipas.elements.Segment¶ Build lattice from MADX script file.
Uses the first beam command and the first sequence encountered via USE when parsing the script. If no USE command is found then the first SEQUENCE in the script is considered.
- Parameters
f_name (str) – File path pointing to the MADX script.
beam (dict, optional) – Beam specification similar to the MADX command beam. If not provided then the script will be searched for a beam command instead. Otherwise the user provided beam specification will override any specification in the script.
errors (bool or str, optional) –
- Whether and how to assign alignment errors to lattice elements. The following options are available:
False - Ignore error specifications in the script.
True - Apply error specifications from the script, interpreting any involved expressions. In case no random functions are involved in error specification the final values will be the same (when comparing the thus built lattice and MADX). However if random functions are involved then, even if the same seed for the random number generator (RNG) is used, the final values are likely to differ because MADX uses a different RNG than the present parser. Hence this option will result in alignment errors for the same elements and values from the same random variates, but not exactly the same values.
- pd.DataFrame - For details about the structure see
apply_errors()
. Using a data frame the exact same values (from MADX) will be assigned. In order to ensure compatibility across multiple runs of the script, make sure to also set
eoption, seed = <rng_seed>
.
- pd.DataFrame - For details about the structure see
paramodi (str or pd.DataFrame, optional) – Device settings to be used when building the lattice. Can be either the file path pointing to a paramodi file or a corresponding data frame, as returned by
external.Paramodi.parse()
. Note that the first encountered purpose is used, if that is undesired, the data frame should be filtered accordingly. For details seeupdate_from_paramodi()
.padding (float or tuple or dict, optional) – Additional padding applied to lattice elements. See
elements.Aperture
.
- Returns
lattice
- Return type
See also
assign_errors()
,update_from_paramodi()
-
dipas.build.
from_script
(script: str, *, beam: dict = None, errors: Union[bool, <MagicMock name='mock.DataFrame' id='139994650600000'>] = True, paramodi: Union[str, <MagicMock name='mock.DataFrame' id='139994650600000'>] = None, padding: Union[float, Tuple[float, ...], Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]], List[Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]]], Dict[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]]] = None) → dipas.elements.Segment¶ Build lattice from MADX script (for details see
from_file()
).
-
dipas.build.
from_twiss
(twiss: Union[str, <MagicMock name='mock.DataFrame' id='139994650600000'>], *, beam: dict, center: bool = False, errors: Optional[<MagicMock name='mock.DataFrame' id='139994650600000'>] = None, paramodi: Optional[<MagicMock name='mock.DataFrame' id='139994650600000'>] = None, padding: Union[float, Tuple[float, ...], Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]], List[Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]]], Dict[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]], None] = None) → dipas.elements.Segment¶ Build lattice from the given device data (optionally applying errors and/or paramodi specifications).
- Parameters
twiss (str or pd.DataFrame) – File path pointing to a TWISS file or corresponding data frame such as returned by
dipas.madx.utils.convert_tfs()
. Must contain the following columns:NAME, KEYWORD, S, ... any required element attributes ...
.errors (pd.DataFrame) – See
from_file()
.paramodi (pd.DataFrame) – See
from_file()
.padding (PaddingSpec) – See
from_file()
.
- Returns
lattice
- Return type
-
dipas.build.
from_device_data
(devices: <MagicMock name='mock.DataFrame' id='139994650600000'>, *, beam: dict, errors: Optional[<MagicMock name='mock.DataFrame' id='139994650600000'>] = None, paramodi: Optional[<MagicMock name='mock.DataFrame' id='139994650600000'>] = None, padding: Union[float, Tuple[float, ...], Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]], List[Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]]], Dict[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]], int, dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError, Tuple[Union[str, Pattern[AnyStr], Type[Union[dipas.elements.CompactElement, dipas.elements.PartitionedElement, AlignmentError]]], int], None], Union[float, Tuple[float, ...]]], None] = None) → dipas.elements.Segment¶ Build lattice from the given device data (optionally applying errors and/or paramodi specifications).
- Parameters
devices (pd.DataFrame) – Indices are element labels and columns are attributes. For details see
collect_device_data()
.errors (pd.DataFrame) – See
from_file()
.paramodi (pd.DataFrame) – See
from_file()
.padding (PaddingSpec) – See
from_file()
.
- Returns
lattice
- Return type
-
dipas.build.
update_from_twiss
(lattice: dipas.elements.Segment, twiss: Union[str, <MagicMock name='mock.DataFrame' id='139994650600000'>]) → None¶ Update the given lattice with the attributes specified in the given TWISS data.
- Parameters
lattice (
Segment
) –twiss (str or pd.DataFrame) – File name pointing to the TWISS file or equivalent data frame (such as returned by
dipas.madx.utils.convert_tfs()
).
-
dipas.build.
update_from_paramodi
(lattice: dipas.elements.Segment, paramodi: Union[str, <MagicMock name='mock.DataFrame' id='139994650600000'>]) → None¶ Apply the specified paramodi definitions to the given lattice in-place.
The following paramodi specifications are currently supported (others are ignored):
[SBend] *
hkick
- Increases/Decreases the SBend’sangle
attribute.[Quadrupole] *
kl
- Replaces the Quadrupole’sk1
attribute.[HKicker] *
hkick
- Replaces the HKicker’skick
attribute.[VKicker] *
vkick
- Replaces the VKicker’skick
attribute.
- Parameters
lattice (
Segment
) –paramodi (str or pd.DataFrame) – File name pointing to the paramodi file or data frame with layout corresponding to
external.Paramodi.parse()
.
-
dipas.build.
create_script
(beam: dict, *, sequence: Union[str, dipas.elements.Segment], errors: Union[typing_extensions.Literal[True][True], dipas.elements.Segment, str] = '', track: str = '') → str¶ Create a MADX script that can be used for particle tracking in the given sequence.
Note
The sequence string must start with the sequence’s label.
- Parameters
beam (dict) – Beam configuration that will be transformed to the “beam” command.
sequence (str or
Segment
) – Part of the script describing the sequence.errors (True or
Segment
or str) – Part of the script describing error definitions. If True then sequence must be a Segment and it will be used to generate the error specifications.track (str) – Part of the script describing the tracking.
- Returns
script – The compound MADX script.
- Return type
str
- Raises
SerializerError – If the sequence string does not start with a label.
-
dipas.build.
sequence_script
(lattice: dipas.elements.Segment, label: str = 'seq', *, markup: str = 'madx') → str¶ Convert the given lattice to a corresponding MADX sequence script or HTML file.
Important
The sequence must not assume implicit drift spaces; elements are laid out as presented.
- Parameters
lattice (Segment) – The lattice to be converted. Elements are placed one after another (no implicit drifts).
label (str, optional) – The label of the sequence to be used in the script.
markup (str, optional) – The markup language which is used for dumping the sequence; one of {“madx”, “html”}.
- Returns
script
- Return type
str
-
dipas.build.
error_script
(lattice: dipas.elements.Segment) → str¶ Convert error definitions in form of AlignmentError to a corresponding MADX script.
Important
Elements which have associated errors must have a (unique) label (uniqueness is not checked for).
- Parameters
lattice (Segment) –
- Returns
script – The corresponding MADX statements for assigning the associated errors.
- Return type
str
- Raises
SerializerError – If an element with associated errors has no label.
-
dipas.build.
track_script
(particles: Union[<MagicMock name='mock.ndarray' id='139994648062552'>, <MagicMock name='mock.Tensor' id='139994648269432'>], observe: Sequence[str], aperture: bool = True, recloss: bool = True, turns: int = 1, maxaper: Union[tuple, list] = (0.1, 0.01, 0.1, 0.01, 1.0, 0.1)) → str¶ Convert particle array / tensor to corresponding MADX track script.
Uses
onetable = true
and hence the results will be available at the file “trackone”.- Parameters
particles (array) – Array / tensor of shape (6, N) where N is the number of particles.
observe (list or tuple) – Labels of places where to observe.
aperture (bool) –
recloss (bool) –
turns (int) –
maxaper (tuple or list) –
- Returns
script
- Return type
str
- Raises
ValueError – If the given particle array has an illegal shape (must be (6,N) where N is the number of particles).