Release 0.16.0

Release 0.16.0 brings the following changes:

Enhancements

• A new module, pyhdtoolkit.cpymadtools.coupling has been added, and now hosts functions to get the closest tune approach (pyhdtoolkit.cpymadtools.coupling.get_closest_tune_approach) and match coupling through Ripken parameters (pyhdtoolkit.cpymadtools.coupling.match_no_coupling_through_ripkens).
• The pyhdtoolkit.cpymadtools.lhc module has a new function, pyhdtoolkit.cpymadtools.lhc.get_lhc_bpms_list, which returns the list of monitoring BPMs for the current LHC sequence in use.
• The pyhdtoolkit.cpymadtools.lhc module now hosts the pyhdtoolkit.cpymadtools.lhc.get_lhc_tune_and_chroma_knobs function.
• The pyhdtoolkit.cpymadtools.plotters.plot_machine_layout have now been made public api.
• The DEFAULT_TWISS_COLUMNS constant in pyhdtoolkit.cpymadtools.constants now includes the element length.
• A new private _misc module has been added to the pyhdtoolkit.utils sub-package.

Bug Fixes

• The pyhdtoolkit.cpymadtools.plotters.AperturePlotter.plot_aperture and pyhdtoolkit.cpymadtools.plotters.LatticePlotter.plot_latwiss functions now properly propagate the xoffset and xlimits parameters to pyhdtoolkit.cpymadtools.plotters.plot_machine_layout, which restores the proper functionality for these parameters and speeds up the plotting significantly when they are used.
• The pyhdtoolkit.cpymadtools.coupling.get_closest_tune_approach function now does not provide chromaticiy targets in its matching, as it can mess up the algorithm when given CHROM which it does.
• The pyhdtoolkit.cpymadtools.matching.match_tunes_and_chromaticities function now properly handles the knobs sent depending on the matching targets. For instance, only tune knobs are varied when only tune targets are provided. Explicitely given knobs are always sent.
• The pyhdtoolkit.cpymadtools.twiss.get_twiss_tfs function now calls the TWISS command from MAD-X and accepts keyword arguments.

Documentation

• All docstrings have been reviewed and now include examples. Those mentioning caveats have been given special admonitions to do so.
• The documentation has gone through a major overhaul and is now built on sphinx and its extensions. It now also includes a quickstart tutorial, a gallery of examples, a contributing guide and a reference bibliography. Feedback on the new documentation is very welcome.

Maintenance

• The deprecated pyhdtoolkit.cpymadtools.special module has been removed.
• The functions in pyhdtoolkit.cpymadtools.plotters do not enforce any rcParams anymore, and these are fully left to the user.
• The pyhdtoolkit.cpymadtools.lhc.match_no_coupling_through_ripkens, pyhdtoolkit.cpymadtools.matching.get_closest_tune_approach and pyhdtoolkit.cpymadtools.matching.get_lhc_tune_and_chroma_knobs functions have been deprecated in favor of their counterparts in other modules. They will be removed in a future release.

See v0.16.0 release notes on GitHub and the full changes since v0.15.1.

Release 0.15.1

Release 0.15.1 is a minor version with a single fix.

Fixed:

• The misalign_lhc_ir_quadrupoles function in the cpymadtools.errors module can now properly handle several IPs at the same time. Its ip parameter has been renamed to ips and properly expects a sequence.

Release 0.15.0

Release 0.15.0 brings the following changes.

Changed:

• The CORRECTOR_LIMITS dict of dict in the cpymadtools.constants module has been changed to a simple dictionary and renamed HLLHC_CORRECTOR_LIMITS as it only contained HighLumi values.
• Exceptions are properly logged as exceptions, with stack information.

Added:

• The LatticePlotter.plot_latwiss function in the cpymadtools.plotters module can now plot the k1 gradient of dipoles that have one, if asked to, which will appear with a lower alpha than regular quadrupoles. A new boolean parameter plot_dipole_k1 is used for this.
• Type hints have been added to all elements of the cpymadtools.constants module.
• Several new constants have been introduced in the cpymadtools.constants module:
  • Supplementing the DEFAULT_TWISS_COLUMNS list, a similar but slightly different one, MONITOR_TWISS_COLUMNS, has been added with elements present in OMC macros.
  • Constants lists for LHC IP bump flags have been added: LHC_CROSSING_ANGLE_FLAGS, LHC_PARALLEL_SEPARATION_FLAGS, LHC_IP_OFFSET_FLAGS, LHC_ANGLE_FLAGS, LHC_EXPERIMENT_STATE_FLAGS and LHC_IP2_SPECIAL_FLAG.
  • Constants lists for LHC triplets corrector knobs have been added: LHC_KQSX_KNOBS, LHC_KCSX_KNOBS, LHC_KCSSX_KNOBS, LHC_KCOX_KNOBS, LHC_KCOSX_KNOBS, LHC_KCTX_KNOBS with their signification in comments.
  • Constants lists for LHC arc corrector knobs have been added: LHC_KQTF_KNOBS, LHC_KQS_KNOBS, LHC_KSF_KNOBS, LHC_KSS_KNOBS, LHC_KCS_KNOBS, LHC_KCO_KNOBS, LHC_KCD_KNOBS, LHC_KO_KNOBS with their signification in comments.
• A new module, cpymadtools.correctors, has been added with currently functionality to query LHC triplet and arc corrector powering status (relatively to their max powering).
• A new function, reset_bump_flags in the cpymadtools.special module which will reset all LHC IP bump flags to 0.

Deprecated:

• The entire cpymadtools.special module is deprecated. Its contents are mirrored in a new cpymadtools.lhc module, which will be reorganised in a next release. Users are encouraged to use the new module, as cpymadtools.special will be removed entirely once PyhDToolkit reaches version 1.0.

Release 0.14.1

Release 0.14.1 is a minor version with no functionality change.

Both tracking functions ptc_track_particle and track_single_particle in respectively the cpymadtools.ptc and cpymadtools.track modules now log a warning when a string value is given to their sequence argument.

Giving a value means the provided sequence will be USE-ed in MAD-X, leading to a loss of set errors, orbit corrections etc whch the user should be well aware of. This caveat has been added to the functions' docstrings.

An info level log has also been added at the start of each function for consistency with the rest of the package.

Release 0.14.0

Release 0.14.0 brings significant API changes, some of them backwards-incompatible.

Changed:

• Functions from the cpymadtools.latwiss module have into a class named LatticePlotter in the cpymadtools.plotters module.
• The old AperturePlotter class in the cpymadtools.plotters module has been renamed to BeamEnvelopePlotter to reflect its role, and functions in this class have also been renamed accordingly.
• The old TuneDiagramPlotter.plot_blank_tune_diagram function in the cpymadtools.plotters module has replaced the TuneDiagramPlotter.plot_tune_diagram function and taken its name.
• The phd matplotlib style has a new setting for legend.framealpha set at 0.9.

Added:

• A new AperturePlotter class in the cpymadtools.plotters module replacing the old one, with functionality to plot the aperture tolerances as calculated from the APERTURE command in MAD-X, jointly with the lattice layout.
• A CrossingSchemePlotter class in the cpymadtools.plotters module, with functionality to plot the orbit crossings at LHC IPs.
• The new TuneDiagramPlotter.plot_tune_diagram function in the cpymadtools.plotters module is now more customisable, can be given a title, a figure size, add legends, differentiate between resonance lines of different orders and given a specific order up to which to plot resonance lines.

Removed:

• The cpymadtools.latwiss module has been removed.
• The old TuneDiagramPlotter.plot_blank_tune_diagram function in the cpymadtools.plotters module has been removed.

Note: the class currently named DynamicAperturePlotter in the cpymadtools.plotters module is misleadingly named and will be renamed in a future release.

Release 0.13.3

Release 0.13.3 brings the following:

Changed:

• All functions in the cpymadtools module which offer the telescopic_squeeze argument now have it default to True to reflect operational scenarios of Run III.
• The correct_lhc_orbit function in cpymadtools.orbit now takes a required sequence positional argument.
• The correct_lhc_orbit function in cpymadtools.orbit now defaults its mode argument to micado like the CORRECT command in MAD-X does.
• The AperturePlotter.plot_aperture function in cpymadtools.plotters now has a default figsize argument of (13, 20) instead of 15, 15.
• The minimum required version of tfs-pandas is now 3.0.0.

Added:

• The plot_machine_layout function in cpymadtools.latwiss now accepts keyword arguments which are transmitted to matplotlib.pyplot.scatter calls.
• The TuneDiagramPlotter.plot_blank_tune_diagram function in cpymadtools.plotters now has a figsize argument.
• The package documentation has been expanded and now includes links to example jupyter notebooks runable with binder.

Fixed:

• All plotting functions in the cpymadtools module now have LaTeX-compatible text elements.
• The plot_latwiss and plot_machine_survey functions in cpymadtools.latwiss now properly detect element types from TWISS table properties and does not rely on naming anymore.
• The plot_machine_layout function in cpymadtools.latwiss now correctly scales the colorbar to the full length of the machine and now to 1.
• The match_tunes_and_chromaticities function in cpymadtools.matching now properly handles being given either only tune targets or only chromaticity targets.
• The BeamParameters class in models.beam now properly builds in all cases and has a repr.
• Fixed some calls to the SELECT command via cpymad which might previously have had unintended side effects.

Release 0.13.2

Release 0.13.2 is a hotfix for the get_pattern_twiss function in cpymadtoos.twiss.

Starting with cpymad 1.9.0, Table.selected_rows() now actually returns the indices of the selected elements rather than returning a boolean mask.

The previous (faulty) behavior had been worked around in get_pattern_twiss, which is now an issue.
With this release, cpymad >= 1.9.0 which is now the minimum required version and the correct Table.selected_rows() behavior is used.

Release 0.13.1

Release 0.13.1 is a hotfix for the AC dipole installation routines.
Both routines now use the implementation from omc3's model_creator and will provide similar results.

Release 0.13.0

Release 0.13.0 brings the following:

Changed:

• The install_ac_dipole function in cpymadtools.special is now named install_ac_dipole_as_kicker. This kicker implementation cannot be used to affect twiss functions, only particle tracking.

Added:

• An install_ac_dipole_as_matrix function cpymadtools.special to install an AC Dipole element as a matrix, which will reflect its effect on twiss functions (which the kicker implementation does not). This matrix implementation cannot be used to influence particle tracking.

Fixed:

• The install_ac_dipole_as_kicker now properly sets the element location to avoid a negative drift (location taken from omc3's model_creator) if the sequence wasn't previously made THIN (which it should).
• The install_ac_dipole_as_kicker now makes a use, sequence=... call after installing the element. Beware this means errors, correctors etc that were set / loaded will be lost.

Release 0.12.0

Release 0.12.0 brings the following:

Added:

• A models module in cpymadtools to hold various pydantic models for data manipulated in the library functions.
• A query_beam_attributes function in cpymadtools.parameters that returns a parsed and validated MADXBeam with all BEAM attributes from the MAD-X process based on the currently defined beam.
• A ptc_twiss function in cpymadtools.ptc to conveniently create the PTC universe and perform a TWISS command according to the Ripken-Mais formalism.
• A ptc_track_particle function in cpymadtools.ptc to conveniently create the PTC universe and perform particle tracking similarly to cpymadtools.track.track_single_particle.
• A get_footprint_lines function in cpymadtools.tune to obtain the (Qx, Qy) points needed to plot the footprint based on the TfsDataFrame returned by make_footprint_table. To be considered experimental.
• A get_footprint_patches function in cpymadtools.tune to obtain a collection of matplotlib.patches.Polygon elements needed to plot the footprint based on the TfsDataFrame returned by make_footprint_table. To be considered experimental.
• The get_table_tfs function in cpmadtools.utils now takes a headers_table argument to choose an internal table to use for headers.

Changed:

• The default energy value in cpymadtools.special.make_lhc_beams has been changed to 7000 [GeV] to reflect run III scenario.
• The value for npart in cpymadtools.special.make_lhc_beams has been changed to 1.15e11 to reflect run III scenario.
• The make_footprint_table in cpymadtools.tune now returns a tfs.TfsDataFrame instead of a pandas.DataFrame, the headers of which are populated with useful values for other functions.
• The beam_parameters function in cpymadtools.parameters has been moved to the optics.beam module and renamed compute_beam_parameters.
• The default patch.linewidth value in the phd matplotlib style has been changed to 1.5.