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.

Release 0.11.0

Release 0.11.0 brings the following:

Added:

• A cpymadtools.utils module with convenience functions for cpymad.mad.Madx objects, for now containing a single function get_table_tfs which turns an internal MAD-X table into a `TfsDataFrame.
• The get_amplitude_detuning and get_rdts functions in the cpymadtools.ptc module now contain extensive docstrings detailing their inner workings as well as parameters used in internal MAD-X commands.
• Both functions above now have a fringe argument defaulting to False in order to enable fringe field calculations.
• Both functions above now transmit keyword arguments to respectively ptc_normal and ptc_twiss.

Release 0.10.0

Release 0.10.0 brings the following:

Added:

• The track_single_particle function in the cpymadtools.track module can now take a sequence defining observation points as argument.
• The track_single_particle function in the cpymadtools.track module can now take keyword arguments to be transmitted to the TRACK command in MAD-X.

Changed:

• The track_single_particle function in the cpymadtools.track module now defaults initial tracking coordinates to all 0.
• The track_single_particle function in the cpymadtools.track module now returns a dictionary, with one keys per defined observation point and as a value the corresponding track table. The special case where ONETABLE s given to TRACK as a keyword argument is handled, and then a single entry taken from the appropriate table with be found in the returned dictionary.

Tests have been added.

Release 0.9.2

Release 0.9.2 brings the following:

Added:

• A match_no_coupling_through_ripkens function in the cpymadtools.special module as a 0-coupling matching routine through cross-term Ripken parameters at a given location.

Fixed:

• The install_mpl_style function now installs the .mplstyle file also in the site-packages location for matplotlib, which is sometimes where it will look when running plt.style.use("phd").

• The closest tune approach routine now properly makes use of madx.batch() to restore settings.

• The plotting functions in the cpymadtools.latwiss module have updated LaTeX-compatible labels.

• The plot_survey function in the cpymadtools.latwiss module now uses clearer markers to indicate the machine survey, properly matches the colormaps of the plotted dipoles and the colorbar when using show_elements=True and lets the user config handle savefig options.