Pyhdtoolkit

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.

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` is a hotfix for the `get_pattern_twiss` function in `cpymadtoos.twiss`.

Starting with [cpymad 1.9.0](https://github.com/hibtc/cpymad/commit/b003c748c00242a159b0a303321ad5e4ae94c8c3), `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 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.

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.

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.