Pyhdtoolkit

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` 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.

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](https://github.com/fsoubelet/PyhDToolkit/releases/tag/0.16.0) and the [full changes since v0.15.1](https://github.com/fsoubelet/PyhDToolkit/compare/0.15.1...0.16.0).

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` 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` 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.