Skip to content

0.7.0

Latest
Compare
Choose a tag to compare
@jank324 jank324 released this 13 Dec 14:18
05ad2c9

We are proud to announce this new major release of Cheetah! This is probably the biggest release since the original Cheetah release, with many with significant upgrades under the hood. Cheetah is now fully vectorised and compatible with PyTorch broadcasting rules, while additional physics and higher fidelity options for existing physics have also been introduced. Despite extensive testing, you might still encounter a few bugs. Please report them by opening an issue, so we can fix them as soon as possible and improve the experience for everyone.

🚨 Breaking Changes

  • Cheetah is now vectorised. This means that you can run multiple simulations in parallel by passing a batch of beams and settings, resulting a number of interfaces being changed. For Cheetah developers this means that you now have to account for an arbitrary-dimensional tensor of most of the properties of you element, rather than a single value, vector or whatever else a property was before. (see #116, #157, #170, #172, #173, #198, #208, #213, #215, #218, #229, #233, #258, #265, #284, #291) (@jank324, @cr-xu, @Hespe, @roussel-ryan)
  • As part of the vectorised rewrite, the Aperture no longer removes particles. Instead, ParticleBeam.survival_probabilities tracks the probability that a particle has survived (i.e. the inverse probability that it has been lost). This also comes with the removal of Beam.empty. Note that particle losses in Aperture are currently not differentiable. This will be addressed in a future release. (see #268) (@cr-xu, @jank324)
  • The fifth particle coordinate s is renamed to tau. Now Cheetah uses the canonical variables in phase space $(x,px=\frac{P_x}{p_0},y,py, \tau=c\Delta t, \delta=\Delta E/{p_0 c})$. In addition, the trailing "s" was removed from some beam property names (e.g. beam.xs becomes beam.x). (see #163, #284) (@cr-xu, @Hespe)
  • Screen no longer blocks the beam (by default). To return to old behaviour, set Screen.is_blocking = True. (see #208) (@jank324, @roussel-ryan)
  • The way dtypes are determined is now more in line with PyTorch's conventions. This may cause different-than-expected dtypes in old code. (see #254) (@Hespe, @jank324)
  • Beam.parameters() no longer shadows torch.nn.Module.parameters(). The previously returned properties now need to be queried individually. (see #300) (@Hespe)
  • e1 and e2 in Dipole and RBend have been renamed and made more consistent between the different magnet types. They now have prefixes dipole_ and rbend_ respectively. (see #289) (@Hespe, @jank324)
  • The _transfer_map property of CustomTransferMap has been renamed to predefined_transfer_map. (see #289) (@Hespe, @jank324)

🚀 Features

  • CustomTransferMap elements created by combining multiple other elements will now reflect that in their name attribute (see #100) (@jank324)
  • Add a new class method for ParticleBeam to generate a 3D uniformly distributed ellipsoidal beam (see #146) (@cr-xu, @jank324)
  • Add Python 3.12 support (see #161) (@jank324)
  • Implement space charge using Green's function in a SpaceChargeKick element (see #142) (@greglenerd, @RemiLehe, @ax3l, @cr-xu, @jank324)
  • Segments can now be imported from Bmad to devices other than torch.device("cpu") and dtypes other than torch.float32 (see #196, #206) (@jank324)
  • Screen now offers the option to use KDE for differentiable images (see #200) (@cr-xu, @roussel-ryan)
  • Moving Elements and Beams to a different device and changing their dtype like with any torch.nn.Module is now possible (see #209) (@jank324)
  • Quadrupole now supports tracking with Cheetah's matrix-based method or with Bmad's more accurate method (see #153) (@jp-ga, @jank324)
  • Port Bmad-X tracking methods to Cheetah for Quadrupole, Drift, and Dipole (see #153, #240) (@jp-ga, @jank324)
  • Add TransverseDeflectingCavity element (following the Bmad-X implementation) (see #240, #278 #296) (@jp-ga, @cr-xu, @jank324)
  • Dipole and RBend now take a focusing moment k1 (see #235, #247) (@Hespe)
  • Implement a converter for lattice files imported from Elegant (see #222, #251, #273, #281) (@Hespe, @jank324)
  • Beam and Element objects now have a .clone() method to create a deep copy (see #289) (@Hespe, @jank324)
  • ParticleBeam now comes with methods for plotting the beam distribution in a variety of ways (see #292) (@roussel-ryan, @jank324)

🐛 Bug fixes

  • Now all Element have a default length of torch.zeros((1)), fixing occasional issues with using elements without length, such as Marker, BPM, Screen, and Aperture. (see #143) (@cr-xu)
  • Fix bug in Cavity _track_beam (see #150) (@jp-ga)
  • Fix issue where dipoles would not get a unique name by default (see #186) (@Hespe)
  • Add name to Drift element __repr__ (see #201) (@ansantam)
  • Fix bug where dtype was not used when creating a ParameterBeam from Twiss parameters (see #206) (@jank324)
  • Fix bug after running Segment.inactive_elements_as_drifts the drifts could have the wrong dtype (see #206) (@jank324)
  • Fix an issue where splitting elements would result in splits with a different dtype (see #211) (@jank324)
  • Fix issue in Bmad import where collimators had no length by interpreting them as Drift + Aperture (see #249) (@jank324)
  • Fix NumPy 2 compatibility issues with PyTorch on Windows (see #220, #242) (@Hespe)
  • Fix issue with Dipole hgap conversion in Bmad import (see #261) (@cr-xu)
  • Fix plotting for segments that contain tensors with require_grad=True (see #288) (@Hespe)
  • Fix bug where Element.length could not be set as a torch.nn.Parameter (see #301) (@jank324, @Hespe)
  • Fix registration of torch.nn.Parameter at initilization for elements and beams (see #303) (@Hespe)
  • Fix warnings about NumPy deprecations and unintentional tensor clones (see #308) (@Hespe)

🐆 Other

  • Update versions of some steps used by GitHub actions to handle Node.js 16 end-of-life (@jank324)
  • Update versions in pre-commit config (see #148) (@jank324)
  • Split accelerator and beam into separate submodules (see #158) (@jank324)
  • Update reference from arXiv preprint to PRAB publication (see #166) (@jank324)
  • Rename converter modules to the respective name of the accelerator code (see #167) (@jank324)
  • Added imports to the code example in the README (see #188) (@jank324)
  • Refactor definitions of physical constants (see #189) (@Hespe)
  • Fix the quadrupole strength units in the quadrupole docstring (see #202) (@ansantam)
  • Add CI runs for macOS (arm64) and Windows (see #226) (@cr-xu, @jank324, @Hespe)
  • Clean up CI pipelines (see #243, #244) (@jank324)
  • Fix logo display in README (see #252) (@jank324)
  • Made Beam an abstract class (see #284) (@Hespe)
  • Releases are now automatically archived on Zenodo and given a DOI (@jank324)
  • The Acknowledgements section in the README has been updated to reflect new contributors (see #304) (@jank324, @AnEichler)

🌟 First Time Contributors