0.8.4

🚨 Breaking Changes

• DirtyNameWarnings are now suppressed when sanitize_name is explicitly set to False (see #658) (@jank324, @Hespe)

🚀 Features

• Improve the speed of SpaceChargeKick by up to 2x by replacing its custom Cloud-in-Cell implementation with the new general implementation (see #653) (@jank324)
• Implement Undulator transverse focusing effect on charged particle beam (see #659) (@Hespe)
• Add Segment.partition_at method to divide a Segment into subcells before and after a given named Element (see #666) (@Hespe, @jank324)
• Add Segment.with_consecutive_elements_merged method to merge consecutive elements of the same type, and a .merge method to Element subclasses to merge two elements of the same type. (see #667) (@jank324)

🐛 Bug fixes

• Fix Sextupole not being skippable if its tracking method is set to linear (see #655) (@Hespe)
• Fix issue where ParticleBeam.randomly_subsampled method would not be stochastic if the random_state argument was not passed. This also fixes a test failure introduced by changes on the MPS backend in PyTorch 2.13. (see #655) (@jank324, @Hespe)
• Fix a bug where some magnet names that are invalid identifiers (i.e. cannot be used with the segment.element_name syntax) would not be sanitised correctly (e.g. when they start with a digit). (see #658) (@jank324, @Hespe)
• Fix KDE stability issue leading to NaNs (see #660) (@jp-ga)
• Methods of Element and Segment that internally construct new instances no longer emit DirtyNameWarnings (see #669) (@Hespe)

🐆 Other

• Non-deterministic torch features now raise a warning in tests instead of a failure. This also fixes a test failure introduced by changes on the MPS backend in PyTorch 2.13. (see #655) (@Hespe, @jank324)
• Add example notebook on implementing custom elements to documentation (see #522) (@jank324)

0.8.3

🚨 Breaking Changes

• Change default method of Screen from "histogram" to "cloud-in-cell" (see #625) (@roussel-ryan, @cr-xu, @jank324)

🚀 Features

• Allow special characters in quoted names in use line expressions from Fortran namelist-based lattice files created by Elegant and Bmad (see #637) (@cr-xu)
• A new Superimposed element was added that allows zero-length elements like BPMs to be superimposed in the centre of another element (see #591) (@jank324, @phys-cgarnier)
• Add all missing off-diagonal terms to the from_parameters and transformed_to methods of all Beam subclasses (see #635) (@cr-xu, @jank324)
• Implement a new differentiable Cloud-In-Cell (CIC) method for n-D charge deposition and add it to Screen. The new method is up to two orders of magnitude faster than the existing and previously only differentiable option kde method. (see #625) (@roussel-ryan, @cr-xu, @jank324)
• Add a metadata property to elements, allowing users to store arbitrary, serialisable annotations that are not used in simulation, such as control-system addresses and PV names. (see #646) (@cr-xu, @jank324, @Hespe, @roussel-ryan)

🐛 Bug fixes

• Fix an issue where off-diagonal elements are not included in the conversion from ParameterBeam to ParticleBeam (see #635) (@cr-xu)

🐆 Other

• Limit UNVECTORIZED_NUM_ATTR_DIMS to only those attributes with more than 0 dimensions and add defining_features to beam classes like already implemented for element classes. (see #627) (@cr-xu, @jank324)

🌟 First Time Contributors

• Christopher Garnier (@phys-cgarnier)

0.8.2

🚀 Features

• All plotting functions in Segment now accept an optional axes or figure object with an interface loosely mimicking that of Seaborn. If they are passed one, they use it, otherwise they create one themselves. Either way, they return the axes or figure they used. (see #604) (@jank324)

🐛 Bug fixes

• RPN parsing was made more robust to missing whitespace in expressions, and arc trig expressions were added to infix parsing. (see #585) (@amylizzle)
• Fix issue, where the first example in the gradient-based optimisation notebook from the docs would not run because the k1 of the quadrupoles was set to 0.0, which causes the gradients to be undefined (see #588, #603) (@jank324, @cr-xu)
• Update the elegant conversion to include missing dipole attributes, converting hgap to gap and fint to fringe_integral. (see #624) (@cr-xu)
• Update the to_openpmd_particlegroup conversion to use int for status and add detach() before tensor to numpy conversion. (see #629) (@roussel-ryan)
• Fix an issue where negative length elements are incorrectly removed by the Segment.without_inactive_zero_length_elements method (see #633) (@cr-xu)
• Patch emittance NaN and 0.0 conditions, which caused Twiss parameters to be NaN or inf under some conditions. (see #639) (@jank324)

🐆 Other

• Automate publishing to PyPI when new releases are created on GitHub (see #423) (@jank324)

0.8.1

🚨 Breaking Changes

• NoVisualizationWarning was renamed to VisualizationWarning to be more general, and can now be thrown for other visualisation issues as well. (see #610) (@amylizzle, @jank324)

🚀 Features

• Update to (default) 3d-assets version 1.2.0 with RBend and CombinedCorrector models (see #605, #610) (@jank324)
• Add option to dynamically specify the branch or tag of the 3d-assets repository to use when generating 3D meshes (see #618) (@jank324)
• Converter to load Elegant SDDS beam distributions (see #612) (@cr-xu, @jank324)
• Improve efficiency of 3D rendering of large lattices by using the Scene class instead of Mesh concatenation (see #610) (@amylizzle)
• New warning about elements with a length of 0.0 not being 3D rendered to-scale (see #610) (@amylizzle, @jank324)

🐛 Bug fixes

• Fixed rotation orientation of dipoles and quadrupoles when rendering 3D models (see #610) (@amylizzle)
• Fix bug when reading null fields from LatticeJSON files (see #619) (@alekseevpavel04)

🐆 Other

• The copyright years were updated to 2026 (see #608) (@jank324)
• Fix format issue caused by new black version (see #611) (@jank324)

🌟 First Time Contributors

• @alekseevpavel04

0.8.0

This major release comes with significant overhauls of some core components of Cheetah. Highlights include an overhaul of the tracking system to support second-order tracking and transfer map/tensor caching; clearer tracking methods names; improved reliability of the gradients computed through Cheetah; a more PyTorch-like typing behaviour; and overall speed improvements of up to 7x in some cases.

🚨 Breaking Changes

• Segment.set_attrs_on_every_element_of_type has been renamed to Segment.set_attrs_on_every_element, and made more general, with the element_type argument being optional and renamed to filter_type. (see #476) (@jank324, @cr-xu)
• Cheetah Modules (Element, Beam, Species) no longer automatically change the device and dtype of passed parameters. Instead, the user is expected to make sure that the device and dtype of parameters and Modules match. This is more in line with how Modules included in PyTorch operate. (see #538, #552) (@jank324, @Hespe)
• Add support for Python 3.14, and remove support for Python 3.10, as well as increase the minimum required versions for some dependencies. (see #582) (@jank324)
• The tracking system has been widely overhauled. As part of this overhaul we renamed the tracking method "cheetah" to "linear" and "bmadx" to "drift_kick_drift". The existing methods "cheetah" and "bmadx" have been fully deprecated and will no longer work. Cheetah will raise an informative error for a number of releases to give users time to adapt their code. (see #476, #596) (@jank324, @Hespe, @cr-xu)

🚀 Features

• Implement second-order tracking for Drift, Dipole and Quadrupole elements, and add a convenient method to set tracking methods for an entire segment. This comes with an overhaul of the overall tracking system. (see #476) (@cr-xu, @jank324, @Hespe)
• Cavity now supports travelling wave cavities in addition to standing wave cavities via the cavity_type argument (see #286) (@zihan-zh, @jank324)
• Documented PyTorch compile for improved speed (see #390) (@ax3l)
• Beam classes now account for dispersion. Dispersion correction is included in the Twiss and emittance computations. Dispersion arguments are added to from_parameters and from_twiss beam initialisation methods. (see #540) (@cr-xu)
• Add convenience methods to Segment for getting an ordered list of all element names and the index of a specific element by its name (see #534) (@roussel-ryan, @jank324)
• First- and second-order transfer maps are now cached resulting in potential speed-ups of up to 10x and more (see #532, #565) (@jank324)
• Methods for creating ParticleBeam instances from distributions via stochastic sampling now make sure that the statistics of the generated particles match the desired distribution (see #546) (@cr-xu)
• BPM elements now support misalignments (see #533) (@roussel-ryan, @jank324)
• Speed up tracking by replacing some PyTorch operations with faster alternatives (see #538, #558, #555, #556, #563, #561) (@jank324, @Hespe)
• New CombinedCorrector element that combines the functionality of HorizontalCorrector and VerticalCorrector (see #589) (@jank324, @amylizzle)

🐛 Bug fixes

• Shorten __repr__ of Segment for large lattices to prevent debugging slowdowns (see #529) (@Hespe)
• Fix typo saying Bmad in Elegant import method docstring (see #531) (@jank324)
• Remove division by zero in Cavity for off-crest phase (see #549, #550) (@Hespe)
• Fix issue with SpaceChargeKick where the particle species was not preserved (see #560) (@austin-hoover, @jank324)
• Fix bug that caused beams to revert to electron species when tracking through Cavity element, resulting in unexpected acceleration behaviour when tracking non-electron species through multiple Cavity elements. (see #570) (@jank324, @hjkim-iris, @Copilot)
• Fix issue where branching in the computations could "hide" gradients w.r.t. to some inputs under certain conditions, leading to incorrect gradient computations. (see #553) (@jank324, @Hespe)

🐆 Other

• Add a speed benchmarking workflow of tracking through the ARES lattice (see #527) (@Hespe)
• Add tests that track through every subclass of Element for all permissible dtypes and device combinations (see #499) (@Hespe)
• Fix false dtype in Screen documentation (see #544) (@jp-ga)
• Fix an issue where running the plot tests on Windows (most notably on the recently upgraded GitHub Actions Windows runners) would sporadically fail with a _tkinter.TclError: Can't find a usable init.tcl in the following directories error, by forcing the matplotlib backend to Agg when running tests on Windows. (see #567) (@jank324)
• Temporarily removed flake8-black from format Action because it causes issues with the latest black version. This has since been reinstated. (see #569, #575) (@jank324)
• Fix typo in README (see #581) (@jank324)
• Update ARES LatticeJSON file to match the latest properties in Cheetah (see #588) (@cr-xu, @jank324)

🌟 First Time Contributors

• Zihan Zhu (@zihan-zh)
• Austin Hoover (@austin-hoover)
• @hjkim-iris

0.7.5

🚀 Features

• Add support for elements (especially Drift) with negative length (see #480) (@Hespe)
• Warnings are now available in the top-level namespace so that they can be referenced as e.g. cheetah.PhysicsWarning to shorten filterwarnigns code. (see #497) (@jank324)
• Add the ability to the Bmad and Elegant converters to parse expressions that access properties from other elements (see #501, #498) (@amylizzle, @jank324)
• Update the Elegant converter to allow element names with colon as well as the definition of reversed beamlines with a minus sign. (see #504) (@cr-xu, @jank324)
• Segments can now conveniently be reversed with the Segment.reversed method (see #504) (@jank324)
• New feature for generating 3D models of lattices and viewing them (see #352, #502, #511) (@jank324, @chrisjcc, @SuchethShenoy)

🐛 Bug fixes

• Fix various dtype and device pertaining to ParticleBeam, Species and SpaceChargeKick (see #485, #486, #490, #491) (@Hespe, @jank324, @adhamrait)
• Remove incorrect implementation of split from HorizontalCorrector and VerticalCorrector (see #480) (@Hespe)

🐆 Other

• Updated contributor list and funding strings in README and on docs index page (see #487) (@jank324)
• Add a Binder and link to cheetah-demos (see #482) (@smartsammler, @jank324)
• PyTorch is now configured to use only deterministic algorithms during tests, preventing intermittent test failures (see #480) (@Hespe)
• Make README example more copy-paste friendly, and generally improve it and the simple intro notebook in the docs. (see #493, #496) (@jank324, @ax3l)
• Fix comparison tests to work with new PyPI release of Ocelot. Remove Twiss tests where they are not needed. Increase tolerances where Cheetah and Ocelot follow slightly different models. (see #513, #519) (@jank324, @cr-xu, @Hespe)

🌟 First Time Contributors

• Julian Gethmann (@smartsammler)
• Arjun Dhamrait (@adhamrait)
• Christian Contreras-Campana (@chrisjcc)
• Sucheth Shenoy (@SuchethShenoy)

0.7.4

🚀 Features

• The new warning system was extended to have more specific subclasses of PhysicsWarning to allow for better and easier filtering of warnings (see #415) (@Hespe, @jank324)
• Implement an infix notation parser for Bmad and Elegant converters, fixing a potential security issue where eval() could be called on user input. (see #412) (@amylizzle)
• Improve numerical stability of the base_rmatrix and base_ttensor functions (related to #469) (see #474) (@Hespe, @jank324)
• Minor speed improvements in base_rmatrix and base_ttensor by reducing memory allocations for constants, and skipping rotation computations when the present tilt has now effect. (see #474) (@Hespe, @jank324)

🐛 Bug fixes

• Fix issue that base_rmatrix has large error for small k1 values even for double precision (see #469) (@cr-xu)
• Rework the covariance computation in ParticleBeam.as_parameter_beam to fix an issue that caused the covariance to be computed incorrectly for vectorised beams (see #471) (@cr-xu, @jank324, @Hespe)
• Unrecognised element properties in Bmad and Elegant lattice files now print a warning instead of exiting with an AssertionError (see #415) (@amylizzle, @jank324)
• A bug was fixed that caused the Bmad and Elegant importers to incorrectly parse ; line endings and comments starting with # (see #415) (@Hespe, @jank324)
• The santize_names parameter is now correctly passed to BPM and Marker elements when converting from Elegant (see #473) (@amylizzle)

0.7.3

🚨 Breaking Changes

• The default resolution of all plotting functions on Segment is now None, i.e. element-wise. For most lattices this will only result in faster plotting, but note that it is possible that your plots look slightly different, especially if your lattice is short or has few elements. (see #459) (@jank324, @Hespe)
• Cheetah now requires torch>=2.3 (see #461) (@jank324)
• Combine the num_grid_points_{x,y,tau} arguments of SpaceChargeKick into the grid_shape tuple. Fixes the cloning of SpaceChargeKick. In addition, the grid_extend_* properties were renamed to grid_extent_* (see #418) (@Hespe, @jank324)
• Warning messages, which were previously just printed are now produced using the warnings module, brining with it all the features of the latter. (see #450) (@Hespe, @jank324)

🚀 Features

• Add KQUAD and CSRCSBEND element names to Elegant converter (see #409) (@amylizzle)
• Add Sextupole to Bmad, Elegant, and Ocelot converters (see #430) (@Hespe)
• Implement convenience method for quickly setting attributes for all elements of a type in a Segment (see #431) (@jank324)
• Add a method to ParticleBeam that lets you subsample a particle beam with fewer particles and the same distribution (see #432, #465) (@jank324)
• Segment now has new functions beam_along_segment_generator and get_beam_attrs_along_segment for easily retrieving beam objects and their properties. The plot functions have been refactored to use these, and two functions plot_beam_attrs and plot_beam_attrs_over_lattice were added for straightforward plotting of different beam attributes in a single line of code. (see #436, #440) (@jank324, @amylizzle)
• Beam subclasses now track their s position along the beamline (see #436) (@jank324)
• There is a warning now when converting elements from Elegant or Bmad that have names which are invalid for use with the segment.element_name syntax, and add a convenience method for explicitly converting these names to valid Python variable names. (see #411) (@amylizzle, @jank324)
• Rotation matrices are no longer computed twice for forward and backward phase space rotations (see #452) (@Hespe)

🐛 Bug fixes

• Fix issue where Dipole with tracking_method="bmadx" and angle=0.0 would output NaN values as a result of a division by zero (see #434) (@jank324)
• Fix issue in CI space-charge tests (incorrect beam duration in non-relativistic case) (see #446) (@RemiLehe)
• Fix issue that passing tensors with requires_grad=True does not result in gradient tracked particles when using ParticleBeam.from_parameters initialization (see #445) (@cr-xu)
• Fix import of CustomTransferMap from Elegant. The affine phase-space component was previously not carried through (see #455) (@Hespe)
• Provide more default values for parameters in the Elegant conversion, where elements without length l for example broke the converter. (see #442) (@cr-xu)
• Functions using Sextupole.split and Sextupole.plot no longer raise an error (see #453) (@Hespe)

🐆 Other

• Bmad is no longer actively run in the test workflows, and comparisons to Bmad are now done on static pre-computed results from Bmad. This also removes the use of Anaconda in the test workflow. (see #429, #431) (@jank324)
• The PyTorch pin to <=2.6 was removed, as the issue with abort trap: 6 was caused by Bmad is no longer actively used in the test workflow (see #429, #431) (@jank324)
• There was a temporary pin snowballstemmer<3.0 for the docs build because of an issue with the latest release. It has since been unpinned again because the release was yanked. Refer to sphinx-doc/sphinx#13533 and snowballstem/snowball#229. (see #436, #438) (@jank324)
• Assert that the last row of a predefined transfer map is always correct when creating a CustomTransferMap element (see #462) (@jank324, @Hespe)
• Minimum compatible versions were defined for all dependencies, and tests were added to ensure that the minimum versions are compatible with Cheetah. (see #463) (@Hespe, @jank324)
• Add a pytest marker for running tests on all subclasses of Element. The marker automatically detects if an MWE has not yet been defined for a subclass and alerts the developer through a test failure. (see #418) (@Hespe, @jank324)

🌟 First Time Contributors

• Copilot 🤖

0.7.2

🚨 Breaking Changes

• Replace the Segment.plot_reference_particle_traces with a clearer visualisation in the for of Segment.plot_mean_and_std. This also changes the plot generated by the Segment.plot_overview method. (see #392) (@RemiLehe)
• The order of the pixels in Screen.reading was changed to start from the bottom left instead of the top left. This is now consistent with the Screen.pixel_bin_centers and Screen.pixel_bin_edges properties. (see #408) (@jank324)

🚀 Features

• Implement split method for the Solenoid element (see #380) (@cr-xu)
• Implement a more robust RPN parser, fixing a bug where short strings in an Elegant variable definition would cause parsing to fail. (see #387, #417) (@amylizzle, @Hespe, @jank324)
• Add a Sextupole element (see #406) (@jank324, @Hespe)

🐛 Bug fixes

• Fix issue where semicolons after an Elegant line would cause parsing to fail (see #383) (@amylizzle)
• Fix Twiss plot to plot samples also after elements in nested (see #388) (@RemiLehe)
• Fix issue where generating screen images did not work on GPU because Screen.pixel_bin_centers was not on the same device (see #372) (@roussel-ryan, @jank324)
• Fix issue where Quadrupole.tracking_method was not preserved on cloning (see #404) (@RemiLehe, @jank324)
• The vertical screen misalignment is now correctly applied to y instead of px (see #405) (@RemiLehe)
• Fix issues when generating screen images caused by the sign of particle charges (see #394) (@Hespe, @jank324)
• Fix an issue where newer versions of torch only accept a torch.Tensor as input to torch.rad2deg (see #417) (@jank324)
• Fix bug that caused correlations to be lost in the conversion from a ParameterBeam to a ParticleBeam (see #408) (@jank324, @Hespe)

🐆 Other

• Temporarily limit torch dependency to 2.6 or lower to avoid abort trap: 6 error with 2.7 (at least on macOS) (see #419) (@jank324)

🌟 First Time Contributors

• Amelia Pollard (@amylizzle)

0.7.1

🚨 Breaking Changes

• The incoming argument of Segment.plot_overview is no longer optional. This change also affects the order of the arguments. Fixes an exception that was raised by an underlying plot function that requires incoming to be set. (see #316, #344) (@Hespe)
• Python 3.9 is no longer supported. This does not immediately break existing code, but might cause it to break in the future. (see #325) (@jank324)
• The covariance properties of the different beam classes were renamed from names like cor_x and sigma_xpx to consistent names like cov_xpx (see #331) (@jank324)
• The signature of the transfer_map method of all element subclasses was extended by a non-optional species argument (see #276) (@cr-xu, @jank324, @Hespe)
• ParticleBeam.plot_distribution allows for Seaborn-style passing of axs and returns the latter as well. In line with that change for the purpose of overlaying distributions, the contour argument of ParticleBeam.plot_2d_distribution was replaced by a style argument. (see #330) (@jank324)
• The default values for total_charge in both beam classes are no longer 0.0 but more sensible values (see #377) (@jank324)
• ParameterBeam._mu and ParameterBeam._cov were renamed to ParameterBeam.mu and ParameterBeam.cov (see #378) (@jank324)

🚀 Features

• ParticleBeam now supports importing from and exporting to openPMD-beamphysics HDF5 files and ParticleGroup objects. This allows for easy conversion to and from other file formats supported by openPMD-beamphysics. (see #305, #320) (@cr-xu, @Hespe)
• Add marker, quadrupole and csbend element names to the Elegant converter (see #327) (@jank324)
• Add Python 3.13 support (see #275) (@jank324)
• Methods to_parameter_beam and to_particle_beam have been added for convenient conversion between ParticleBeam and ParameterBeam (see #331) (@jank324)
• Beam classes now have the mu_tau and mu_p properties on their interfaces (see #331) (@jank324)
• Lattice and beam converters now adhere to the default torch dtype when no explicit dtype is passed (see #340) (@Hespe, @jank324)
• Add options to include or exclude the first and last element when retrieving a Segment.subcell and improve error handling (see #350) (@Hespe, @jank324)
• Add support for particle species through a new Species class (see #276, #376) (@cr-xu, @jank324, @Hespe)
• Various optimisations for a roughly 2x speed improvement over v0.7.0 (see #367) (@jank324, @Hespe)

🐛 Bug fixes

• Fix issue where a space before a comma could cause the Elegant and Bmad converters to fail (see #327) (@jank324)
• Fix issue of BPM and Screen not properly converting the dtype of their readings (see #335) (@Hespe)
• Fix is_active and is_skippable of some elements not being boolean properties (see #357) (@jank324)

🐆 Other

• Test tolerances were adjusted reduce the chance of random test failures (see #309, #324) (@Hespe, @jank324)
• The copyright years were updated to 2025 (see #318) (@jank324)
• The broken institution logo rendering in the documentation has been fixed (see #318) (@jank324)
• Added pyproject.toml to conform with PEP 660 as enforced as of pip 25 for editable installs (see #334) (@jank324)
• Add TUHH logo to contributing institution logos (see #338) (@jank324)
• The tests for backward-mode differentiation with space charge was improved by checking the accuracy of the gradients (see #339) (@RemiLehe)
• A tests for forward-mode differentiation with space charge was added (see #339) (@RemiLehe)
• Link to different ImpactX example in test docstring (see #341) (@ax3l)
• Add link to the new Discord server (see #355, #382) (@jank324)
• Fix typo that said "quadrupole" in a dipole docstring (see #358) (@jank324)
• Type annotations were updated to the post-PEP 585/604... style (see #360) (@jank324)
• Add badge to the README for the number of downloads from PyPI (see #364) (@jank324)