Release 0.20.0

Version 0.20.0 is a feature release and brings the following changes:

Enhancements

• The pyhdtoolkit.cpymadtools.coupling.get_closest_tune_approach function now supports the run3 boolean argument introduced in version 0.19.1, which is used for the LHC case.
• The pyhdtoolkit.cpymadtools.coupling module now has a new function, pyhdtoolkit.cpymadtools.coupling.get_coupling_rdts, which will return the coupling Resonance Driving Terms throughout all elements in the sequence as columns added to the tfs.TfsDataFrame returned after a TWISS call.
• The pyhdtoolkit.cpymadtools.coupling module now has a new function, pyhdtoolkit.cpymadtools.coupling.get_cminus_from_coupling_rdts, which first calls the new pyhdtoolkit.cpymadtools.coupling.get_coupling_rdts and then wraps the optics_functions.coupling.closest_tune_approach to provide an estimate of the :math:C^{-} according to the desired calculation method.
• The pyhdtoolkit.cpymadtools.lhc module now has a new function, pyhdtoolkit.cpymadtools.lhc.carry_colinearity_knob_over, which will carry over the powering of MQSX magnets around an IP to a single side.
• The pyhdtoolkit.cpymadtools.lhc module now has a new function, pyhdtoolkit.cpymadtools.lhc.correct_lhc_global_coupling, which will runs a tricky routine to minimize the global :math:|C^{-}| through the dqmin variable.
• The pyhdtoolkit.cpymadtools.lhc module now has a new function, pyhdtoolkit.cpymadtools.lhc.do_kmodulation which simulates a K-Modulation of an inner triplet quadrupole Q1 in a desired IR, and returns a tfs.TfsDataFrame of the results.

Documentation

• Various docstrings have been corrected on wrong details, and some examples have been added.

Maintenance

• Various private helpers have been added through different modules.
• The minimum required version of tfs-pandas has been raised to 3.2.0.
• Increased test coverage.

What's Changed

• Changes for 0.20.0 by @fsoubelet in #86

Full Changelog: 0.19.2...0.20.0

Release 0.19.2

Version 0.19.2 is a patch release with no api changes, made to fix a publishing issue to PyPI.

0.19.1

Release 0.19.1 is a patch release.

Maintenance

• The pyhdtoolkit.cpymadtools.lhc.get_lhc_tune_and_chroma_knobs function now can has a new boolean argument, run3, to determine if the standard _op knobs should be returned.
• The functions in the pyhdtoolkit.cpymadtools.matching module now also have the run3 argument, and will call the Run 3 _op knobs if this argument is set to True and the LHC accelerator is passed.
• Fixes have been provided to the various Github Actions workflow of the repository.

What's Changed

• OP knobs by @fsoubelet in #85

Full Changelog: 0.19.0...0.19.1

Release 0.19.0

Release 0.19.0 brings the following changes:

Enhancements

• The pyhdtoolkit.plotting package has a new sub-package, pyhdtoolkit.plotting.sbs with modules to plot coupling (pyhdtoolkit.plotting.sbs.coupling) and phase (pyhdtoolkit.plotting.sbs.phase) segment-by-segment results.
• The pyhdtoolkit.plotting.sbs package has a new utility module, pyhdtoolkit.plotting.sbs.utils, with helpful functions for plotting.
• The pyhdtoolkit.cpymadtools.lhc module has a new function, pyhdtoolkit.cpymadtools.lhc.get_lhc_bpms_twiss_and_rdts to easily get coupling RDTs at all observation points (BPMs) in the LHC sequence.

Documentation

• A new gallery was added showcasing the plotting of segment-by-segment coupling and phase results.

Maintenance

• The quadrupole component of a dipole is now plotted with the same shade as a regular quadrupole in pyhdtoolkit.cpymadtools.plotters.LatticePlotters.plot_latwiss.
• The pyhdtoolkit.cpymadtools.plotters.LatticePlotter.plot_latwiss function now plots the quadrupole gradient of a dipole with the same shade as a normal quadrupole.
• A new dependency, the optics_functions package, was added.
• The documentation for the pyhdtoolkit.maths.plotting module has been extended.
• Tests were added for the new functionality.
• Input files for various tests have been regrouped in relevant directories for clarity.

What's Changed

• Version 0.19.0 by @fsoubelet in #82
• fix latex errors in gallery by @fsoubelet in #83
• Tweaks by @fsoubelet in #84

Full Changelog: 0.18.0...0.19.0

Release 0.18.0

Release 0.18.0 brings the following changes:

Enhancements

• The pyhdtoolkit.utils._misc module has a new function, ~pyhdtoolkit.utils._misc.add_markers_around_lhc_ip to add MAD-X markers around a given IP in order to increase the resolution of the TWISS calls in the IP vicinity.
• The pyhdtoolkit.utils._misc module has a new function, ~pyhdtoolkit.utils._misc.get_lhc_ips_positions, to determine the longitudinal position (S variable) of LHC IPs from a dataframe.
• The pyhdtoolkit.utils._misc module has a new function, ~pyhdtoolkit.utils._misc.draw_ip_locations, to add labels with the location of LHC IPs to a given ~matplotlib.axes.Axes object.
• The LHC Rigid Waist Shift gallery has been improved, and now shows a visualization of the waist shift and two ways to calculate its value.

Bug Fixes

• The ~pyhdtoolkit.cpymadtools.orbit.lhc_orbit_variables function does not return a wrong on_phi_IR5 variable anymore.

Maintenance

• The dependency on matplotlib has been pinned to <3.5 to avoid issues with the documentation plot style, to be fixed later on.
• The bibliography file for the package's documentation has been cleaned up.
• The Github icon in the documentation pages now redirects to the proper pages.
• The documentation for the ~pyhdtoolkit.maths.nonconvex_phase_sync has been improved.
• Some additional files necessary for the documentation additions are now included in the repo, but not the package.

What's Changed

• Niceties and improved documentation by @fsoubelet in #80

Full Changelog: 0.17.0...0.18.0

Release 0.17.0

Release 0.17.0 brings the following changes:

Enhancements

• The pyhdtoolkit.cpymadtools.matching module has two new wrapper functions, match_tunes and match_chromaticities, to perform matching on either tunes or chromaticities only.
• The pyhdtoolkit.cpymadtools.lhc module has a new utility function, get_magnets_powering, to get the percentage of magnets' max powering used in a given configuration.
• The pyhdtoolkit.cpymadtools.utils module has a new function, export_madx_table, to conveniently export an internal table to disk with proper regex filtering in a way that can be read by MAD-X later on.
• The pyhdtoolkit.cpymadtools.constants module now includes a regex for the (HL)LHC triplets. Beware that MAD-X itself does not understand all regex features.

Bug Fixes

• The ~pyhdtoolkit.cpymadtools.twiss.get_pattern_twiss function now properly handles being given specific columns.

Maintenance

• The deprecated pyhdtoolkit.cpymadtools.lhc.match_no_coupling_through_ripkens function has been removed, its replacement in the pyhdtoolkit.cpymadtools.coupling module should be used.
• The deprecated pyhdtoolkit.cpymadtools.lhc._get_k_strings function has been removed, its replacement in the pyhdtoolkit.cpymadtools.utils module should be used.
• The deprecated pyhdtoolkit.cpymadtools.matching.get_closest_tune_approach function has been removed, its replacement in the pyhdtoolkit.cpymadtools.coupling module should be used.
• The deprecated pyhdtoolkit.cpymadtools.matching.get_lhc_tune_and_chroma_knobs function has been removed, its replacement in the pyhdtoolkit.cpymadtools.lhc module should be used.
• The pyhdtoolkit.cpymadtools.lhc._get_k_strings helper function is now deprecated and has been moved to pyhdtoolkit.cpymadtools.utils._get_k_strings.
• The internal imports in the package have been reworked, and sub-packages now only expose their modules through __all__ opposed to some of the modules' contents previously.
• Some tests have been added.

Release 0.16.1

Release 0.16.1 is a minor version with small changes.

Changed:

• The info level logging statements in the pyhdtoolkit.cpymadtools modules have been adjusted to debug level. Info logging is left to the user scripts.
• The warning level logging statements in the pyhdtoolkit.cpymadtools modules have been modified to give a bit more information.

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.