xtrack_tools API

xtrack_tools.env.create_xsuite_environment(sequence_file=None, kinetic_energy=6800, seq_name=None, rerun_madx=False, json_file=None)[source]

Create or load an xsuite environment for a given MAD-X sequence.

The environment is generated from a MAD-X sequence file and cached to JSON. If the cached JSON exists and is newer than the sequence file, it will be used unless rerun_madx is set to True.

Parameters:

  • beam – LHC beam number to resolve the default sequence file, if sequence_file is not provided.

  • sequence_file (Optional[Path]) – Path to a MAD-X sequence file. Required if beam is not set.

  • kinetic_energy (float) – Beam kinetic energy in GeV used to set the particle reference.

  • seq_name (Optional[str]) – Sequence name inside the environment; defaults to the file stem.

  • rerun_madx (bool) – Force regeneration of the JSON cache by rerunning MAD-X.

  • json_file (Optional[Path]) – Optional path for the cached JSON representation.

Return type:

Environment

Returns:

The loaded xt.Environment with particle reference set.

Raises:

  • ValueError – If neither beam nor sequence_file is provided.

  • FileNotFoundError – If the sequence file is missing when regeneration is needed.

xtrack_tools.env.initialise_env(matched_tunes, magnet_strengths, corrector_table, sequence_file=None, kinetic_energy=6800, seq_name=None, json_file=None, strict_set=True)[source]

Initialise an xsuite environment with tune knobs, magnet strengths, and correctors.

Parameters:

  • matched_tunes (dict[str, float]) – Mapping of tune knob names to values (e.g., dqx_b1_op).

  • magnet_strengths (dict[str, float]) – Mapping of element variable names to strengths, such as mqy.b5l2.b1.k1.

  • corrector_table (TfsDataFrame) – TFS table with corrector settings.

  • beam – LHC beam number to resolve the default sequence file.

  • sequence_file (Optional[Path]) – Path to the MAD-X sequence file.

  • kinetic_energy (float) – Beam kinetic energy in GeV.

  • seq_name (Optional[str]) – Sequence name inside the environment.

  • json_file (Optional[Path]) – Optional path for cached JSON environment.

  • strict_set – If True, validate existing corrector strengths before applying.

Return type:

Environment

Returns:

The configured xt.Environment ready for tracking or optics analysis.

Raises:

ValueError – If tune knob names do not match the expected format.

Coordinate generation utilities for accelerator tracking simulations.

This module provides functions for generating action-angle coordinates and creating initial conditions for particle tracking.

xtrack_tools.coordinates.create_initial_conditions(action, angle, twiss_data, kick_plane='xy', starting_bpm=0)[source]

Create initial conditions for a specific track from action-angle coordinates.

Parameters:

  • action (float | np.ndarray) – Action value(s) (scalar or array)

  • angle (float | np.ndarray) – Angle value(s) (scalar or array, same shape as action)

  • twiss_data (pd.DataFrame) – Twiss parameters at starting point

  • kick_plane (str) – Plane to kick (“x”, “y”, or “xy”)

  • starting_bpm (str | int) – Starting BPM name or index

Return type:

dict[str, float | np.ndarray]

Returns:

Dictionary with initial coordinates (x, px, y, py, t, pt)

xtrack_tools.coordinates.generate_action_angle_coordinates(num_tracks, action_range)[source]

Generate action-angle coordinate pairs for tracking.

Parameters:

  • num_tracks (int) – Total number of tracks needed

  • action_range (tuple[float, float]) – Tuple of (min_action, max_action) in meters

  • num_actions – Number of action values (optional, calculated if not provided)

Return type:

tuple[list[float], list[float]]

Returns:

Tuple of (action_list, angle_list) where both lists have length num_tracks

xtrack_tools.coordinates.get_kick_plane_category(ntrk, use_diagonal_kicks)[source]

Determine kick plane category for a track.

Parameters:

  • ntrk (int) – Track number

  • use_diagonal_kicks (bool) – Whether to kick both planes

Return type:

str

Returns:

Kick plane category string (“xy”, “x”, or “y”)

xtrack_tools.coordinates.validate_coordinate_generation(num_tracks, action_list, angle_list)[source]

Validate that action-angle coordinate generation produces the expected number of tracks.

Parameters:

  • num_tracks (int) – Expected number of tracks

  • action_list (list[float]) – Generated action values

  • angle_list (list[float]) – Generated angle values

Return type:

bool

Returns:

True if validation passes

Raises:

AssertionError – If validation fails