PYRWS Command Line

pyrws

Command-line program to generate rigid waist shift configurations for the LHC. Given a sequence, optics file, ip and RWS setting, will output the knob settings for the triplets, rematching quadrupoles and MQTs. Plots can be generated too.

pyrws [OPTIONS]

Options

--sequence <sequence>

Required Path to the LHC sequence file to use.

--opticsfile <opticsfile>

Required Path to the LHC optics file to use.

--ip <ip>

Required Which IP to prepare the waist shift knob for. Should be 1, 2, 5 or 8.

Default

1

--waist_shift_setting <waist_shift_setting>

Required Unit setting of the rigid waist shift. A value of 1 corresponds to a 0.5% change in the triplets powering.

--outputdir <outputdir>

Directory in which to write output files. Defaults to ‘outputs/’ in the current working directory.

Default

/home/runner/work/pyrws/pyrws/outputs

--use_knobs_from <use_knobs_from>

If provided, should point to the output directory of a previous run of this script. The matching quadrupole knobs will then be retrieved from their expected location in this directory and used for this run, instead of attempting a rematching of the waist shift knob (which can sometimes fail at very low betastar configurations).

--energy <energy>

Beam energy in [GeV]

Default

6800

--qx <qx>

The horizontal tune to match to.

Default

62.31

--qy <qy>

The vertical tune to match to.

Default

60.32

--show_plots <show_plots>

Whether to ask matplotlib to show plots.

Default

False

--mplstyle <mplstyle>

Name of a matplotlib style to use for plots.

--figsize <figsize>

Figure size for the created plots. Will affect the visibility of the plots. Defaults to the standard matplotlib rcParams value.

--loglevel <loglevel>

Sets the logging level.

Default

info

Options

trace | debug | info | warning | error | critical

PYRWS Modules

Useful Constants

Specific constants to be used in the package, to help with consistency.

Checkers Functionality

Module with functions to perform checks after having created a rigid waist shift knob for a given optics configuration.

pyrws.checks.style_fields_changes(nominal_fields_dataframe: pandas.core.frame.DataFrame, matched_fields_dataframe: pandas.core.frame.DataFrame)[source]

Return a Styler object from the nominal and matched fields dataframes, to easily display the change of powering for relevant magnets.

Important

The provided dataframes should hold columns with checks of the reach of limits powering, namely the percent column is used in this function. This is a regular output of the knob creation of this package.

pyrws.checks.style_fields_dataframe(dataframe: pandas.core.frame.DataFrame)[source]

Return a Styler object from the nominal or matched provided fields dataframe, to easily display the reach of limits.

Important

The provided dataframe should hold columns with checks of the reach of limits powering, namely imax, ampere and percent. This is a regular output of the knob creation of this package.

Core Functionality

Module with functions to perform the rigid waist shift and matching through a Madx object.

class pyrws.core.BeamConfig(twiss_tfs: tfs.frame.TfsDataFrame, triplets_knobs: Dict[str, float], quads_knobs: Dict[str, float], working_point_knobs: Dict[str, float])[source]
pyrws.core.get_bare_waist_shift_beam1_config(madx: cpymad.madx.Madx, ip: int, rigidty_waist_shift_value: float, energy: float, qx: float, qy: float) → pyrws.core.BeamConfig[source]

Applies the rigid waist shift at the provided ip for beam 1, and returns the corresponding configuration for beam 1 (twiss table, triplet knobs, independent IR quadrupoles knobs).

Note

All the caveats of applying the rigid waist shift apply here as well. For more information see the documentation of pyhdtoolkit.cpymadtools.lhc.apply_lhc_rigidity_waist_shift_knob.

Important

It is assumed that the sequence and opticsfile have already been called beforehand.

Parameters

  • madx (cpymad.madx.Madx) -- an instanciated Madx object.

  • ip (int) -- the IP at which to apply the rigid waist shift.

  • rigidty_waist_shift_value (float) -- applied unit setting of the rigidity waist shift knob. A value of 1 changes the powering of the triplets knob by 0.5%.

  • energy (float) -- beam energy for the setup, in [GeV].

  • qx (float) -- the horizontal tune to re-match to after applying the rigid waist shift.

  • qy (float) -- the vertical tune to re-match to after applying the rigit waist shift.

Returns

the result of a TWISS call as a TfsDataFrame, a dict with the names and values of the triplets powering knobs, a dict with the names and values of the independent IR quadrupoles powering knobs and a dict with the names and values of the working point knobs (tunes and chroma).

Return type

A custom BeamConfig object containing

pyrws.core.get_bare_waist_shift_beam2_config(madx: cpymad.madx.Madx, ip: int, triplet_knobs: Dict[str, float], energy: float, qx: float, qy: float) → pyrws.core.BeamConfig[source]

Applies the rigid waist shift at the provided ip for beam 1, and returns the corresponding configuration for beam 1 (twiss table, triplet knobs, independent IR quadrupoles knobs).

Note

This is similar to get_bare_waist_shift_beam1_config except that instead of applying the waist shift with a unit setting, it applies to powering knob for the triplets that were determined for beam 1. This is because the powering circuit is identical for beam 1 and beam 2 triplets, so we need to make sure they are powered the same.

Important

It is assumed that the sequence and opticsfile have already been called beforehand.

Parameters

  • madx (cpymad.madx.Madx) -- an instanciated Madx object.

  • ip (int) -- the IP at which to apply the rigid waist shift.

  • triplet_knobs (float) -- the triplets powering knob values for the given ip, as returned by get_bare_waist_shift_beam1_config.

  • energy (float) -- beam energy for the setup, in [GeV].

  • qx (float) -- the horizontal tune to re-match to after applying the rigid waist shift.

  • qy (float) -- the vertical tune to re-match to after applying the rigit waist shift.

Returns

the result of a TWISS call as a TfsDataFrame, a dict with the names and values of the triplets powering knobs, a dict with the names and values of the independent IR quadrupoles powering knobs and a dict with the names and values of the working point knobs (tunes and chroma).

Return type

A custom BeamConfig object containing

pyrws.core.get_matched_waist_shift_config(madx: cpymad.madx.Madx, beam: int, ip: int, nominal_twiss: tfs.frame.TfsDataFrame, bare_twiss: tfs.frame.TfsDataFrame, qx: float, qy: float) → pyrws.core.BeamConfig[source]

Performs relevant matchings to improve the rigid waist shift at the provided ip for beam 1, and returns the corresponding configuration for beam the provided beam (twiss table, triplet knobs, independent IR quadrupoles knobs).

Note

There is a bunch of hard-coded logic in this function, such as the matching points location etc.

Important

This assumes to whole setups from get_nominal_beam_config and then get_bare_waist_shift_beam1_config or get_bare_waist_shift_beam2_config have been called beforehand (aka the waist shift is applied).

Parameters

  • madx (cpymad.madx.Madx) -- an instanciated Madx object.

  • beam (int) -- the beam number, should be 1 or 2.

  • ip (int) -- the IP at which to apply the rigid waist shift.

  • nominal_twiss (tfs.TfsDataFrame) -- the TfsDataFrame with the TWISS table from the nominal scenario, which is used to determine matching constraint values.

  • bare_twiss (tfs.TfsDataFrame) -- the TfsDataFrame with the TWISS table from the bare waist shift scenario, which is used to determine matching constraint values.

  • qx (float) -- the horizontal tune to re-match to after applying the rigid waist shift.

  • qy (float) -- the vertical tune to re-match to after applying the rigit waist shift.

Returns

the result of a TWISS call as a TfsDataFrame, a dict with the names and values of the triplets powering knobs, a dict with the names and values of the independent IR quadrupoles powering knobs and a dict with the names and values of the working point knobs (tunes and chroma).

Return type

A custom BeamConfig object containing

pyrws.core.get_nominal_beam_config(madx: cpymad.madx.Madx, energy: float, beam: int, ip: int, qx: float, qy: float) → pyrws.core.BeamConfig[source]

Provided with an active Madx object, will match to the working point defined by the provided tunes qx and qy and return the nominal configuration for the provided beam (twiss table, triplet knobs, independent IR quadrupoles knobs).

Note

This will re-cycle the appropriate sequence from MSIA.EXIT.B[12] point, create lhcb1 and lhcb2 beams for 6.8 TeV, setup a flat orbit configuration (crossing angles, separation bumps at 0 etc.) and use the appropriate sequence for the provided beam.

Warning

IN OPERATION IN THE CCC, REMEMBER TO LEAVE THE ORBIT FEEDBACK ON!

Important

It is assumed that the sequence and opticsfile have already been called beforehand.

Parameters

  • madx (cpymad.madx.Madx) -- an instanciated Madx object.

  • energy (float) -- beam energy for the setup, in [GeV].

  • beam (int) -- the beam number, should be 1 or 2.

  • ip (int) -- the IP for which to get triplets and independent quadrupoles powering knobs values.

  • qx (float) -- the horizontal tune to match to.

  • qy (float) -- the vertical tune to match to.

Returns

the result of a TWISS call as a TfsDataFrame, a dict with the names and values of the triplets powering knobs, a dict with the names and values of the independent IR quadrupoles powering knobs and a dict with the names and values of the working point knobs (tunes and chroma).

Return type

A custom BeamConfig object containing

pyrws.core.get_waist_shift_config_from_applied_existing_knobs(madx: cpymad.madx.Madx, use_knobs_from: pathlib.Path, beam: int, ip: int, qx: float, qy: float) → pyrws.core.BeamConfig[source]

Performs relevant matchings to improve the rigid waist shift at the provided ip for beam 1, and returns the corresponding configuration for beam the provided beam (twiss table, triplet knobs, independent IR quadrupoles knobs).

Important

This assumes to whole setups from get_nominal_beam_config and then get_bare_waist_shift_beam1_config or get_bare_waist_shift_beam2_config have been called beforehand (aka the waist shift is applied).

Parameters

  • madx (cpymad.madx.Madx) -- an instanciated Madx object.

  • beam (int) -- the beam number, should be 1 or 2.

  • use_knobs_from (pathlib.Path) -- the directory of a previous configuration’s output, from where the knobs to use will be looked for.

  • ip (int) -- the IP at which to apply the rigid waist shift.

  • qx (float) -- the horizontal tune to re-match to after applying the rigid waist shift.

  • qy (float) -- the vertical tune to re-match to after applying the rigit waist shift.

Returns

the result of a TWISS call as a TfsDataFrame, a dict with the names and values of the triplets powering knobs, a dict with the names and values of the independent IR quadrupoles powering knobs and a dict with the names and values of the working point knobs (tunes and chroma).

Return type

A custom BeamConfig object containing

Plotting Functions

Module with functions to create different plots relevant to the rigid waist shift configurations.

pyrws.plotting.plot_betas_comparison(axis: matplotlib.axes._axes.Axes, nominal: pandas.core.frame.DataFrame, before: pandas.core.frame.DataFrame, after: pandas.core.frame.DataFrame, column: str = 'BETX', show_ips: bool = False) → None[source]

Plots the ..math:eta functions across the machine for the nominal, bare waist shift and improved waist shift scenarii on the given axis.

Parameters

  • axis (matplotlib.axes.Axes) -- the Axes object on which to plot.

  • nominal (pd.DataFrame) -- the DataFrame with TWISS functions from the nominal model.

  • before (pd.DataFrame) -- the DataFrame with TWISS functions from the bare waist shift implementation.

  • after (pd.DataFrame) -- the DataFrame with TWISS functions from the improved waist shift implementation.

  • column (str) -- the column to plot. Should be one of BETX or BETY. Defaults to BETX for the horizontal beta-functions.

  • show_ips (bool) -- if True, will show the IPs locations with vertical lines on the plot. Defaults to False.

pyrws.plotting.plot_betas_deviation(axis: matplotlib.axes._axes.Axes, nominal: pandas.core.frame.DataFrame, before: pandas.core.frame.DataFrame, after: pandas.core.frame.DataFrame, column: str = 'BETX', show_ips: bool = False) → None[source]

Plots the ..math:eta functions deviation from the nominal case across the machine for the bare waist shift and improved waist shift scenarii on the given axis.

Parameters

  • axis (matplotlib.axes.Axes) -- the Axes object on which to plot.

  • nominal (pd.DataFrame) -- the DataFrame with TWISS functions from the nominal model.

  • before (pd.DataFrame) -- the DataFrame with TWISS functions from the bare waist shift implementation.

  • after (pd.DataFrame) -- the DataFrame with TWISS functions from the improved waist shift implementation.

  • column (str) -- the column to plot. Should be one of BETX or BETY. Defaults to BETX for the horizontal beta-functions.

  • show_ips (bool) -- if True, will show the IPs locations with vertical lines on the plot. Defaults to False.

pyrws.plotting.plot_phase_advances_comparison(axis: matplotlib.axes._axes.Axes, nominal: pandas.core.frame.DataFrame, before: pandas.core.frame.DataFrame, after: pandas.core.frame.DataFrame, column: str = 'MUX', show_ips: bool = False) → None[source]

Plots the phase advances (..math:mu_{x,y}) across the machine for the nominal, bare waist shift and improved waist shift scenarii on the given axis.

Parameters

  • axis (matplotlib.axes.Axes) -- the Axes object on which to plot.

  • nominal (pd.DataFrame) -- the DataFrame with TWISS functions from the nominal model.

  • before (pd.DataFrame) -- the DataFrame with TWISS functions from the bare waist shift implementation.

  • after (pd.DataFrame) -- the DataFrame with TWISS functions from the improved waist shift implementation.

  • column (str) -- the column to plot. Should be one of MUX or MUY. Defaults to MUX for the horizontal phase advances.

  • show_ips (bool) -- if True, will show the IPs locations with vertical lines on the plot. Defaults to False.

pyrws.plotting.plot_phase_differences(axis: matplotlib.axes._axes.Axes, nominal: pandas.core.frame.DataFrame, before: pandas.core.frame.DataFrame, after: pandas.core.frame.DataFrame, show_ips: bool = False) → None[source]

Plots the phase advances (..math:mu_{x,y}) across the machine for the nominal, bare waist shift and improved waist shift scenarii on the given axis.

Hint

The value ..math:mu_x - muy is interesting as it is driving the exponential term in the calculation of the difference resonance ..math:f_{1001}.

Parameters

  • axis (matplotlib.axes.Axes) -- the Axes object on which to plot.

  • nominal (pd.DataFrame) -- the DataFrame with TWISS functions from the nominal model.

  • before (pd.DataFrame) -- the DataFrame with TWISS functions from the bare waist shift implementation.

  • after (pd.DataFrame) -- the DataFrame with TWISS functions from the improved waist shift implementation.

  • column (str) -- the column to plot. Should be one of MUX or MUY. Defaults to MUX for the horizontal phase advances.

  • show_ips (bool) -- if True, will show the IPs locations with vertical lines on the plot. Defaults to False.

pyrws.plotting.plot_waist_shift_betabeatings(axis: matplotlib.axes._axes.Axes, dataframe: pandas.core.frame.DataFrame, show_ips: bool = False) → None[source]

Plots the horizontal and vertical beta-beatings on the given axis.

Note

It is expected that the dataframe contains BBX and BBY columns, with respectively the horizontal and vertical beta-beating values to plot.

Parameters

  • axis (matplotlib.axes.Axes) -- the Axes object on which to plot.

  • dataframe (pd.DataFrame) -- the DataFrame containing the beta-beating values to plot along the longitudinal coordinate S.

  • show_ips (bool) -- if True, will show the IPs locations with vertical lines on the plot. Defaults to False.

pyrws.plotting.plot_waist_shift_betabeatings_comparison(axis: matplotlib.axes._axes.Axes, before: pandas.core.frame.DataFrame, after: pandas.core.frame.DataFrame, column: str = 'BBX', show_ips: bool = False) → None[source]

Plots the before and after matching beta-beatings on the given axis.

Note

It is expected that the before and after dataframes both contain BBX and BBY columns, with respectively the horizontal and vertical beta-beating values to plot.

Parameters

  • axis (matplotlib.axes.Axes) -- the Axes object on which to plot.

  • before (pd.DataFrame) -- the DataFrame containing the beta-beating values along the longitudinal coordinate S, for the bare waist shift implementation.

  • after (pd.DataFrame) -- the DataFrame containing the beta-beating values along the longitudinal coordinate S, for the improved waist shift implementation (a.k.a. after matching).

  • column (str) -- the column to plot. Should be one of BBX or BBY. Defaults to BBX for the horizontal beta-beating.

  • show_ips (bool) -- if True, will show the IPs locations with vertical lines on the plot. Defaults to False.

Utilities

Provides miscellaneous utility functions.

pyrws.utils.add_betabeating_columns(dataframe: pandas.core.frame.DataFrame, nominal: pandas.core.frame.DataFrame) → pandas.core.frame.DataFrame[source]

Adds coupling RDTs \(\f_{1001}\) and \(\f_{1010}\) as well as beta-beating columns to the dataframe.

Parameters

  • dataframe (pd.DataFrame) -- the DataFrame to add the columns to.

  • nominal (pd.DataFrame) -- the DataFrame with reference values for the beta-beating calculations.

Returns

A copy of the original dataframe with the new columns added.

pyrws.utils.betabeating(nominal: Union[numpy.ndarray, pandas.core.series.Series], modified: Union[numpy.ndarray, pandas.core.series.Series]) → Union[numpy.ndarray, pandas.core.series.Series][source]

Compute the beta-beating from the provided arrays.

Parameters

  • nominal (Union[np.ndarray, pd.Series]) -- the nominal beta values.

  • modified (Union[np.ndarray, pd.Series]) -- the beta values to get the beta-beating for.

Returns

A new array with the computed beta-beating values.

pyrws.utils.fullpath(filepath: pathlib.Path) → str[source]

Returns the full string path to the provided filepath, which is necessary for AFS paths.

pyrws.utils.get_independent_quadrupoles_powering_knobs(madx: cpymad.madx.Madx, quad_numbers: Sequence[int], ip: int, beam: int) → Dict[str, float][source]

Returns the powering knob values for the provided quadrupoles around the given IP.

Parameters

  • madx (cpymad.madx.Madx) -- an instantiated Madx object.

  • quad_numbers (Sequence[int]) -- quadrupoles to get the powering for, by number (aka position from IP).

  • ip (int) -- the IP around which to get the quadrupoles powering knobs for.

Returns

A dict of the knob names and their values.

pyrws.utils.get_triplets_powering_knobs(madx: cpymad.madx.Madx, ip: int) → Dict[str, float][source]

Returns the triplets powering knob values at the given IP.

Parameters

  • madx (cpymad.madx.Madx) -- an instantiated Madx object.

  • ip (int) -- the IP for which to get the triplets powering knob values for.

Returns

A dict of the knob names and their values.

pyrws.utils.get_tunes_and_chroma_knobs(madx: cpymad.madx.Madx, beam: int, telescopic_squeeze: bool = True) → Dict[str, float][source]

Returns the tunes and chroma knobs.

Parameters

  • madx (cpymad.madx.Madx) -- an instantiated Madx object.

  • beam (int) -- the beam number to get knob values for.

  • telescopic_squeeze (bool) -- if set to True, returns the knobs for Telescopic Squeeze configuration. Defaults to True to reflect run III scenarios.

Returns

A dict of the knob names and their values.

pyrws.utils.load_knobs_change_file(filepath: pathlib.Path) → Dict[str, float][source]

Loads the knob values from the file they are written in by write_knob_powering.

Parameters

filepath (Path) -- Path object to the file with the saved knob values.

Returns

A dict of knob names and their values, in absolute powering.

pyrws.utils.load_knobs_file(filepath: pathlib.Path) → Dict[str, float][source]

Loads the knob values from the file they are written in by write_knob_powering.

Parameters

filepath (Path) -- Path object to the file with the saved knob values.

Returns

A dict of knob names and their values, in absolute powering.

pyrws.utils.only_export_columns(dataframe: pandas.core.frame.DataFrame) → pandas.core.frame.DataFrame[source]

Returns a sub-selection of the dataframe with only certain columns, meant for writing to disk.

Parameters

dataframe (pd.DataFrame) -- the DataFrame to do a selection of columns for.

Returns

A copy of the original dataframe with only the desired columns in.

pyrws.utils.only_monitors(dataframe: pandas.core.frame.DataFrame) → pandas.core.frame.DataFrame[source]

Returns a sub-selection of the dataframe with only rows corresponding to monitor elements (aka BPMs), meant for writing to disk.

Parameters

dataframe (pd.DataFrame) -- the DataFrame to do a selection of columns for.

Returns

A copy of the original dataframe with only the desired rows in.

pyrws.utils.powering_delta(nominal_knobs: Dict[str, float], modified_knobs: Dict[str, float]) → Dict[str, float][source]

Compute the delta between the modified and nominal knobs, to determine the powering change that should be given in LSA.

Parameters

  • nominal_knobs (Dict[str, float]) -- a dict of the nominal knobs and their values.

  • modified_knobs (Dict[str, float]) -- a dict of the modified knobs and their values.

Returns

A dictionary of the knob names and powering delta from the modifying scenario to the nominal scenario.

pyrws.utils.prepare_output_directories(outputdir: pathlib.Path) → Tuple[Dict[str, pathlib.Path], Dict[str, pathlib.Path]][source]

Creates the proper directories where the output files will be written.

Parameters

outputdir (Path) -- the path to the main output directory, as given by the user at the command line.

Returns

A dict for each beam, with as keys the Path objects to the created output directories. In order, these are for main directory, tfs files dir, knobs dir and plots dir. The keys or the dict are main, tfs, knobs and plots.

pyrws.utils.write_knob_changeparameters(file_path: pathlib.Path, nominal_knobs: Dict[str, float], matched_knobs: Dict[str, float], knob_name: str) → None[source]

Figure out the delta from the matched to nominal knobs, and write as a TFS file that can be loaded in the Beta-Beat GUI to create the knob in LSA.

Parameters

  • file_path (Path) -- Path object to the file to write the knob change parameters to.

  • nominal_knobs (Dict[str, float]) -- the nominal values of the variables in the knob.

  • matched_knobs (Dict[str, float]) -- the post-rws matched values of the variables in the knob.

  • knob_name (str) -- the name of the knob to write the change parameters for, this is used in the headers.

pyrws.utils.write_knob_delta(file_path: pathlib.Path, nominal_knobs: Dict[str, float], matched_knobs: Dict[str, float]) → None[source]

Figure out the delta from the matched knobs to the nominal knobs, and write it down to the given file.

Parameters

  • file_path (Path) -- Path object to the file to write the knob change parameters to.

  • nominal_knobs (Dict[str, float]) -- the nominal values of the variables in the knob.

  • matched_knobs (Dict[str, float]) -- the post-rws matched values of the variables in the knob.

pyrws.utils.write_knob_powering(file_path: pathlib.Path, knob_dict: Dict[str, float]) → None[source]

Write the absolute powering values of the given knob dict to the given file.