MAD-NG

This module provides functions to read and write turn-by-turn measurement data produced by the MAD-NG code. MAD-NG stores its tracking data in the TFS (Table File System) file format.

Data is loaded into the standardised TbtData structure used by turn_by_turn, allowing easy post-processing and conversion between formats.

Dependencies:

  • Requires the tfs-pandas >= 4.0.0 package for compatibility with MAD-NG features. Earlier versions does not support MAD-NG TFS files.

turn_by_turn.madng.convert_to_tbt(df: pd.DataFrame | tfs.TfsDataFrame) → TbtData[source]

Convert a TFS or pandas DataFrame to a TbtData object.

This function parses the required turn-by-turn columns, reconstructs the particle-by-particle tracking data, and returns a TbtData instance that can be written or converted to other formats.

Parameters:

df (pd.DataFrame | TfsDataFrame) -- DataFrame containing MAD-NG turn-by-turn tracking data.

Returns:

The extracted and structured turn-by-turn data.

Return type:

TbtData

Raises:

  • TypeError -- If the input is not a recognised DataFrame type.

  • ValueError -- If the data structure is inconsistent (e.g., lost particles).

turn_by_turn.madng.read_tbt(file_path: str | Path) → TbtData[source]

Read turn-by-turn data from a MAD-NG TFS file.

Loads the TFS file using tfs-pandas and converts its contents into a TbtData object for use with the turn_by_turn toolkit.

Parameters:

file_path (str | Path) -- Path to the MAD-NG TFS measurement file.

Returns:

The loaded turn-by-turn data.

Return type:

TbtData

Raises:

ImportError -- If the tfs-pandas package is not installed.

turn_by_turn.madng.write_tbt(output_path: str | Path, tbt_data: TbtData) → None[source]

Write turn-by-turn data to a MAD-NG TFS file.

Takes a TbtData object and writes its contents to disk in the standard TFS format used by MAD-NG, including relevant headers (date, time, origin).

Parameters:

  • output_path (str | Path) -- Destination file path for the TFS file.

  • tbt_data (TbtData) -- The turn-by-turn data to write.

Raises:

ImportError -- If the tfs-pandas package is not installed.

XTrack TbT Conversion

Helpers to convert data produced by the xtrack tracking framework into the turn_by_turn TbtData format.

This module converts monitor data from xtrack into the corresponding TbtData representation. It currently supports data produced by:

  • xtrack.MultiElementMonitor recorded via xtrack.Line.record_multi_element_last_track.

  • One or more xtrack.ParticlesMonitor elements placed in the line.

The appropriate converter is selected based on which monitor data are present on the provided xtrack.Line. If multi-element monitor data are available, they are preferred; otherwise particle monitor data are used.

turn_by_turn.xtrack.converter.convert_to_tbt(xline: Line) → TbtData[source]

Convert tracking results from an xtrack.Line into a TbtData object.

Dispatches to one of the specific converters in turn_by_turn.xtrack depending on which monitor data is available in the provided Line.

Supported source datatypes and resulting TbtData.meta['source_datatype'] values:

  • xtrack_multi_element_monitor: when converting from an

    xtrack.MultiElementMonitor (via record_multi_element_last_track).

  • xtrack_particles_monitor: when converting from one or more

    xtrack.ParticlesMonitor elements.

Parameters:

xline (Line) -- An xtrack.Line containing monitor data.

Returns:

The extracted turn-by-turn data. The meta mapping contains a source_datatype key describing the origin of the data.

Return type:

TbtData

Raises:

  • ImportError -- If the xtrack package is not installed.

  • TypeError -- If the input is not an xtrack.Line.

  • ValueError -- If no suitable monitor data is found on the provided Line.

turn_by_turn.xtrack.converter.read_tbt(path: str | Path) → None[source]

Not implemented.

Reading TBT data directly from files is not supported for xtrack. Use convert_to_tbt to convert an in-memory xtrack.Line instead.

XTrack TbT Conversion from Multi-Element Monitor

Convert Xsuite MultiElementMonitor output into TbtData. Reference: https://xsuite.readthedocs.io/en/latest/track.html#multi-element-monitor

Usage

  1. Track with multi_element_monitor_at:

    import xtrack as xt
# place a MultiElementMonitor in the line via the xtrack API
monitor_names = ["BPM1", "BPM2", "BPM3"]
line.track(
     particles,
     num_turns=1024,
     multi_element_monitor_at=monitor_names,
)

  2. Convert to turn_by_turn data:

    from turn_by_turn.xtrack import convert_to_tbt

tbt = convert_to_tbt(line)

Notes

  • Data is read from line.record_multi_element_last_track.

  • The converter expects arrays with shape (turn, particle, obs) from monitor.get("x") and monitor.get("y").

  • Output order follows the order of monitor names provided to multi_element_monitor_at, independent of the order in which they appear in the line.

turn_by_turn.xtrack._multi_element_monitor.convert_to_tbt(xline: xt.Line) → TbtData[source]

Convert xtrack multi-element monitor data to TbtData.

Parameters:

xline (xt.Line) -- Tracked line containing record_multi_element_last_track.

Returns:

Turn-by-turn data for each particle and observed element.

Return type:

TbtData

Raises:

ValueError -- If monitor data is missing, or has unexpected shape.

turn_by_turn.xtrack._multi_element_monitor.is_line_suitable_for_conversion(xline: xt.Line) → bool[source]

Check if the given xtrack Line is suitable for conversion to TbtData.

This function verifies that the Line contains a non None multi-element monitor data.

Parameters:

xline (xt.Line) -- The xtrack Line to check.

Returns:

True if the Line is suitable for conversion, False otherwise.

Return type:

bool

XTrack TbT Conversion from Particle Monitors

Convert tracking results produced by one or more xtrack.ParticlesMonitor elements into the standardised TbtData format used by turn_by_turn.

Usage

from turn_by_turn.xtrack import convert_to_tbt

# after building particles and tracking a line containing # xt.ParticlesMonitor elements, convert to TbtData: tbt = convert_to_tbt(line)

Prerequisites for using convert_to_tbt:

  1. The input Line must contain one or more ParticlesMonitor elements

    positioned at each location where turn-by-turn data is required (e.g., all BPMs).

    A valid monitor setup involves:

    • Placing a xt.ParticlesMonitor instance in the line’s element sequence

      at all the places you would like to observe.

    • Configuring each monitor with identical settings:

      • start_at_turn (first turn to record, usually 0)

      • stop_at_turn (The total number of turns to record, e.g., 100)

      • num_particles (number of tracked particles)

    If any monitor is configured with different parameters, convert_to_tbt will either find no data or raise an inconsistency error.

    Also, if you specify more turns than were actually tracked, the resulting TBT data will include all turns up to the monitor’s configured limit. This may result in extra rows filled with zeros for turns where no real data was recorded, which might not be desirable for your analysis.

  2. Before conversion, you must:

    • Build particles with the desired initial coordinates

      (using line.build_particles(...)).

    • Track those particles through the line for the intended number of turns

      (using line.track(..., num_turns=num_turns)).

Once these conditions are met, pass the tracked Line to convert_to_tbt to extract the data from each particle monitor into a TbtData object.

turn_by_turn.xtrack._particles_monitor.convert_to_tbt(xline: Line) → TbtData[source]

Convert tracking results from an xtrack Line into a TbtData object.

This function extracts all ParticlesMonitor elements found in the Line, verifies they contain consistent turn-by-turn data, and assembles the results into the standard TbtData format. One TransverseData matrix is created per tracked particle.

Parameters:

xline (Line) -- An xtrack.Line containing at least one ParticlesMonitor.

Returns:

The extracted turn-by-turn data for all particles and monitors.

Return type:

TbtData

Raises:

ValueError -- If no monitors are found or data is inconsistent.

turn_by_turn.xtrack._particles_monitor.is_line_suitable_for_conversion(xline: Line) → bool[source]

Check if the given xtrack Line is suitable for conversion to TbtData.

This function verifies that the Line contains at least one ParticlesMonitor and that all monitors have consistent tracking data (same number of turns and particles).

Parameters:

xline (xt.Line) -- The xtrack Line to check.

Returns:

True if the Line is suitable for conversion, False otherwise.

Return type:

bool