NXCALS

Knob Extraction

This module provides functionality to extract knob values from NXCALS for the LHC and convert them to MAD-X compatible format using LSA services.

It handles retrieval of raw variable data from NXCALS, conversion of power converter currents to K-values, and mapping of power converter names to MAD-X naming conventions.

This module requires the installation of jpype, pyspark, and access to the CERN network to connect to NXCALS and LSA services. You can install the required packages via pip: ` python -m pip install omc3[cern] `

See the [NXCALS documentation](https://nxcals-docs.web.cern.ch/current/user-guide/data-access/quickstart/) for more information on getting access and using the Python API.

class omc3.nxcals.knob_extraction.NXCALSResult(name: 'str', value: 'float', timestamp: 'pd.Timestamp', pc_name: 'str')[source]

Bases: object

name: str
pc_name: str
timestamp: Timestamp
value: float
omc3.nxcals.knob_extraction.calc_k_from_iref(lsa_client, currents: dict[str, float], energy: float) → dict[str, float][source]

Calculate K values in the LHC from IREF using the LSA service.

Parameters:

  • lsa_client -- The LSA client instance.

  • currents (dict[str, float]) -- Dictionary of current values keyed by variable name.

  • energy (float) -- The beam energy in GeV.

Returns:

Dictionary of K values keyed by variable name.

Return type:

dict[str, float]

omc3.nxcals.knob_extraction.get_energy(spark: SparkSession, time: datetime) → tuple[float, pd.Timestamp][source]

Retrieve the beam energy of the LHC from NXCALS.

Parameters:

  • spark (SparkSession) -- Active Spark session.

  • time (datetime) -- Python datetime (timezone-aware recommended).

Returns:

Beam energy in GeV and its timestamp.

Return type:

tuple[float, pd.Timestamp]

Raises:

RuntimeError -- If no energy data is found.

omc3.nxcals.knob_extraction.get_knob_vals(spark: SparkSession, time: datetime, beam: int, patterns: list[str], expected_knobs: set[str] | None = None, log_prefix: str = '', delta_days: float = 0.25) → list[NXCALSResult][source]

Retrieve knob values for a given beam and time using specified patterns for the LHC.

This is the main entry point for extracting magnet knob values from NXCALS. The function performs a complete workflow:

  1. Queries NXCALS for power converter current measurements (I_MEAS) using variable patterns

  2. Retrieves the beam energy at the specified time

  3. Converts currents to K-values (integrated quadrupole strengths) using LSA

  4. Maps power converter names to MAD-X naming conventions

  5. Returns knob values with their timestamps

The difference between patterns and knob names:

  • patterns: NXCALS variable patterns (e.g., “RPMBB.UA%.RQT%.A%B1:I_MEAS”) used to query raw power converter current measurements. These follow CERN naming conventions and may include wildcards (%).

  • expected_knobs: MAD-X element names (e.g., “kqt12.a12b1”) representing the final knob names as used in MAD-X scripts. These are lowercase, simplified names.

Parameters:

  • spark (SparkSession) -- Active Spark session for NXCALS queries.

  • time (datetime) -- Time to retrieve data for.

  • beam (int) -- Beam number (1 or 2).

  • patterns (list[str]) -- List of NXCALS variable patterns to query for power converter currents. Patterns can include SQL-like wildcards (%). Example: “RPMBB.UA%.RQT%.A%B1:I_MEAS” matches all MQT quadrupole trim magnets for beam 1.

  • expected_knobs (set[str] | None) -- Set of expected MAD-X knob names to validate and filter results. If None, returns all found knobs without validation.

  • log_prefix (str) -- Prefix for logging messages to distinguish different extraction runs.

  • delta_days (float) -- Number of days to look back for data. Default is 0.25.

Returns:

List of NXCalResult objects containing MAD-X knob names, K-values,

timestamps, and power converter names.

Return type:

list[NXCalResult]

omc3.nxcals.knob_extraction.get_raw_vars(spark: SparkSession, time: datetime, var_name: str, delta_days: float = 0.25) → list[NXCALSResult][source]

Retrieve raw variable values from NXCALS.

Parameters:

  • spark (SparkSession) -- Active Spark session.

  • time (datetime) -- Python datetime (timezone-aware recommended).

  • var_name (str) -- Name or pattern of the variable(s) to retrieve.

  • delta_days (float) -- Number of days to look back for data. Default is 0.25.

Returns:

List of NXCalResult containing variable name, value, timestamp, and power converter name for the latest sample of each matching variable at the given time.

Return type:

list[NXCalResult]

Raises:

  • RuntimeError -- If no data is found for the variable in the given interval.

  • You may need to increase the delta_days if necessary. --

omc3.nxcals.knob_extraction.map_pc_name_to_madx(pc_name: str) → str[source]

Convert an LHC power converter name or circuit name to its corresponding MAD-X name.

This function processes the input name by removing the ‘:I_MEAS’ suffix if present, extracting the circuit name from full power converter names (starting with ‘RPMBB’ or ‘RPL’), applying specific string replacements for MAD-X compatibility, and converting the result to lowercase.

Parameters:

pc_name (str) -- The power converter or circuit name to convert.

Returns:

The converted MAD-X name.

Return type:

str

Examples

>>> map_pc_name_to_madx("RPMBB.UJ33.RCBH10.L1B1:I_MEAS")
'acb10.l1b1'
>>> map_pc_name_to_madx("RQT12.L5B1")
'kqt12.l5b1'
omc3.nxcals.knob_extraction.strip_i_meas(text: str) → str[source]

Remove the I_MEAS suffix from a variable name.

Parameters:

text (str) -- The variable name possibly ending with ‘:I_MEAS’.

Returns:

The variable name without the ‘:I_MEAS’ suffix.

Return type:

str

Extraction of MQT knobs from NXCALS.

This module provides functions to retrieve MQT (Quadrupole Trim) knob values for the LHC for a specified beam and time using NXCALS and LSA.

There are two types per arc (focusing ‘f’ and defocusing ‘d’), resulting in 16 MQT circuits per beam (8 arcs * 2 planes).

The extraction uses the underlying knob_extraction module with MQT-specific patterns.

omc3.nxcals.mqt_extraction.generate_mqt_names(beam: int) → set[str][source]

Generate the set of MAD-X MQT (Quadrupole Trim) variable names for a given beam.

Parameters:

beam (int) -- The beam number (1 or 2).

Returns:

A set of MAD-X variable names for MQT magnets, e.g., ‘kqt12.a12b1’.

Return type:

set[str]

Raises:

ValueError -- If beam is not 1 or 2.

Examples

>>> get_mqts(1)
{'kqt12.a12b1', 'kqt12.a23b1', ..., 'kqtd.a81b1'}
omc3.nxcals.mqt_extraction.get_mqt_vals(spark: SparkSession, time: datetime, beam: int, delta_days: float = 0.25) → list[NXCALSResult][source]

Retrieve MQT (Quadrupole Trim) knob values from NXCALS for a specific time and beam.

This function queries NXCALS for current measurements of MQT power converters, calculates the corresponding K-values (integrated quadrupole strengths) using LSA, and returns them in MAD-X format with timestamps.

Parameters:

  • spark (SparkSession) -- Active Spark session for NXCALS queries.

  • time (datetime) -- The timestamp for which to retrieve the data (timezone-aware required).

  • beam (int) -- The beam number (1 or 2).

  • delta_days (float) -- Number of days to look back for data. Default is 0.25.

Returns:

List of NXCalResult objects containing the MAD-X knob names, K-values, and timestamps.

Return type:

list[NXCalResult]

Raises:

  • ValueError -- If beam is not 1 or 2 (propagated from get_mqts), or if time is not timezone-aware.

  • RuntimeError -- If no data is found in NXCALS or LSA calculations fail.

omc3.nxcals.mqt_extraction.knobs_to_madx(mqt_vals: list[NXCALSResult]) → str[source]

Convert a list of NXCalResult objects to a MAD-X script string.

Parameters:

mqt_vals -- List of NXCalResult objects containing knob values.

Returns:

A string containing the MAD-X script with knob assignments.