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>.

  • 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 see update_from_paramodi().

  • padding (float or tuple or dict, optional) – Additional padding applied to lattice elements. See elements.Aperture.

Returns

lattice

Return type

Segment

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

Segment

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

Segment

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’s angle attribute.

  • [Quadrupole] * kl - Replaces the Quadrupole’s k1 attribute.

  • [HKicker] * hkick - Replaces the HKicker’s kick attribute.

  • [VKicker] * vkick - Replaces the VKicker’s kick 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).