Releases: desy-ml/cheetah
Releases · desy-ml/cheetah
0.7.0
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 ofBeam.empty
. Note that particle losses inAperture
are currently not differentiable. This will be addressed in a future release. (see #268) (@cr-xu, @jank324) - The fifth particle coordinate
s
is renamed totau
. 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
becomesbeam.x
). (see #163, #284) (@cr-xu, @Hespe) -
Screen
no longer blocks the beam (by default). To return to old behaviour, setScreen.is_blocking = True
. (see #208) (@jank324, @roussel-ryan) - The way
dtype
s are determined is now more in line with PyTorch's conventions. This may cause different-than-expecteddtype
s in old code. (see #254) (@Hespe, @jank324) -
Beam.parameters()
no longer shadowstorch.nn.Module.parameters()
. The previously returned properties now need to be queried individually. (see #300) (@Hespe) -
e1
ande2
inDipole
andRBend
have been renamed and made more consistent between the different magnet types. They now have prefixesdipole_
andrbend_
respectively. (see #289) (@Hespe, @jank324) - The
_transfer_map
property ofCustomTransferMap
has been renamed topredefined_transfer_map
. (see #289) (@Hespe, @jank324)
🚀 Features
CustomTransferMap
elements created by combining multiple other elements will now reflect that in theirname
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) Segment
s can now be imported from Bmad to devices other thantorch.device("cpu")
and dtypes other thantorch.float32
(see #196, #206) (@jank324)Screen
now offers the option to use KDE for differentiable images (see #200) (@cr-xu, @roussel-ryan)- Moving
Element
s andBeam
s to a differentdevice
and changing theirdtype
like with anytorch.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
, andDipole
(see #153, #240) (@jp-ga, @jank324) - Add
TransverseDeflectingCavity
element (following the Bmad-X implementation) (see #240, #278 #296) (@jp-ga, @cr-xu, @jank324) Dipole
andRBend
now take a focusing momentk1
(see #235, #247) (@Hespe)- Implement a converter for lattice files imported from Elegant (see #222, #251, #273, #281) (@Hespe, @jank324)
Beam
andElement
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 oftorch.zeros((1))
, fixing occasional issues with using elements without length, such asMarker
,BPM
,Screen
, andAperture
. (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
toDrift
element__repr__
(see #201) (@ansantam) - Fix bug where
dtype
was not used when creating aParameterBeam
from Twiss parameters (see #206) (@jank324) - Fix bug after running
Segment.inactive_elements_as_drifts
the drifts could have the wrongdtype
(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 atorch.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
andbeam
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
- Grégoire Charleux (@greglenerd)
- Remi Lehe (@RemiLehe)
- Axel Huebl (@ax3l)
- Juan Pablo Gonzalez-Aguilera (@jp-ga)
- Andrea Santamaria Garcia (@ansantam)
- Ryan Roussel (@roussel-ryan)
- Christian Hespe (@Hespe)
- Annika Eichler (@AnEichler)
0.6.3
0.6.2
🚨 Breaking Changes
- The handling of
device
anddtype
was overhauled. They might not behave as expected.Element
s also no longer have adevice
attribute. (see #115) (@jank324)
🚀 Features
- Add charge to the
ParameterBeam
andParticleBeam
classes (see #86) (@cr-xu) - Add opt-in speed optimisations (see #88) (@jank324)
🐛 Bug fixes
- Fix the transfer maps in
Drift
andDipole
; Add R56 in horizontal and vertical correctors modelling (see #90) (@cr-xu) - Fix fringe_field_exit of
Dipole
is overwritten byfringe_field
bug (see #99) (@cr-xu) - Fix error caused by mismatched devices on machines with CUDA GPUs (see #97 and #115) (@jank324)
- Fix error raised when tracking a
ParameterBeam
through an activeBPM
(see #101) (@jank324) - Fix error in ASTRA beam import where the energy was set to
float64
instead offloat32
(see #111) (@jank324) - Fix missing passing of
total_charge
inParameterBeam.transformed_to
(see #112) (@jank324) - Fix
Cavitiy.__repr__
printingvoltage
value forphase
property (see #121) (@jank324)
🐆 Other
- Add pull request template (see #97) (@jank324)
- Add Acknowledgements section to README (see #103) (@jank324)
benchmark
directory was moved todesy-ml/cheetah-demos
repository (see #108) (@jank324)- Update citations to new arXiv preprint (see #117) (@jank324)
- Improve the docstring with proper units for the phase space dimensions (see #122) (@cr-xu)
- Link to the new paper (on arXiv) in the documentation (see #125) (@jank324)
0.6.1
0.6.0
🚨 Breaking Changes
- Cheetah elements are now subclasses of
torch.nn.Module
, where the parameters should always betorch.Tensor
. This makes cheetah a fully differentiable simulation code. (see #11) - The
cell
keyword argument ofcheetah.Segment
has been renamed toelements
. - Element and beam parameters must now always be passed to the constructor or set afterwards as a
torch.Tensor
. It is no longer possible to usefloat
,int
ornp.ndarray
. (see #11)
🚀 Features
- Convert from Bmad lattices files (see #65) (@jank324)
- Add proper transfer map for cavity (see #65) (@jank324, @cr-xu)
- Twiss parameter calculation and generate new beam from twiss parameter (see #62) (@jank324, @cr-xu)
- Saving and loading lattices from LatticeJSON (see #9) (@cr-xu)
- Nested
Segment
s can now be flattened (@jank324) - Ocelot converter adds support for
Cavity
,TDCavity
,Marker
,Monitor
,RBend
,SBend
,Aperture
andSolenoid
(see #78) (@jank324)
🐛 Bug fixes
- Fix dependencies on readthedocs (see #54) (@jank324)
- Fix error when tracking
ParameterBeam
through segment on CPU (see #68) (@cr-xu)
🐆 Other
0.5.19
🚀 Features
- Better error messages when beam and accelerator devices don't match (@FelixTheilen)
🐛 Bug fixes
- Fix BPM issue with
ParameterBeam
(@FelixTheilen) - Fix wrong screen reading dimensions (@cr-xu)
🐆 Other
- Improve docstrings (@FelixTheilen)
- Implement better testing with pytest (@FelixTheilen)
- Setup formatting with
black
andisort
as well asflake8
listing (@cr-xu) - Add type annotations (@jank324)
- Setup Sphinx documentation on readthedocs (@jank324)
0.5.18
0.5.17
0.5.16
0.5.15
🚀 New Features
- Ocelot has been removed as a mandatory dependency and is now only needed when someone wants to convert from Ocelot objects.
🐛 Bug Fixes
- An error that only packages with all dependencies available on PyPI can be installed from PyPI has been fixed.