Tags

# New features

## Intrabeam Scattering
* Implementation of IBS effect in mbtrack2, the `IntrabeamScattering` class was added in mbtrack2.tracking.ibs.
* It implements an approximate IBS kick based on an analytical model.
* Four analytical models are available: Piwinski Standard, Piwinski Modified, Completely Integrated Piwinski model, and Bane high-energy approximation. It is recommended to use Completely Integrated Piwinski model (CIMP) for fast simulations.

## Important behavior change in `Optics` class
* Default behavior of `Optics` is changed when AT lattice is loaded: now it defaults to optic function to s=0 instead of average ones.
* Default behavior of `LongRangeResistiveWall` and `ImpedanceModel` when an AT lattice is loaded is to normalized by `average_beta / local_beta`
* Adds `Optics.average_beta` attribute

## Nonlinear chromaticity
* `Synchrotron.get_chroma` can be used to compute nonlinear chromaticity from pyAT lattice.
* Nonlinear chromaticity can be used in `TransverseMap` and `TransverseSectorMap`.
* `TransverseMap` now inherits from `TransverseSectorMap`.

## `SynchrotronRadiation` object
* Adds a `SynchrotronRadiation.qexcitation` optional parameter to turn off quantum excitation.
* Improved performance.

# Other improvements and modifications
* General performance improvements in many classes.
* Update `CircularResistiveWall` class in resistive_wall.py to replace numerical integrations with analytical forms for improved performance.
* Use `scipy.integrate.trapezoid` for compatibility with newer version of numpy
* Update `BeamIonElement` to work in a more general case.
* Update `TransverseSpaceCharge` to work in a more general case.
* `ComplexData.name_and_coefficients_table` is now a staticmethod.
* Extend `WakeField` to "mixed" componenets (xydip, yxdip, ...).
* Small fix/improvements for rf.py (`CavityResonator` for n_bin=1)
* Add `Element.track_bunch_if_non_empty` decorator.
* Modify `Bunch.binning` to add a `return_full_length` optional parameter.
* Modify `Mpi.share_distributions` for n_bin=1.
* Modify `WakePotential` for n_bin=1 and use `track_bunch_if_non_empty` decorator.
* Modify `PhysicalModel` to return errors if needed.
* Adds `Beam.init_bunch_list_mpi`, a convenience method to initialize a beam using MPI parallelisation with a `Bunch` per core.

## Project management
* Add \> 400 tests and organize them in unit-tests and physics-tests.
* Add `assert_attr_changed` test function.
* renamed particles_electromagnetic_fields.py into emfields.py and changed all the imports
* added CODEOWNERS file for automatic review assignment for merge requests
* Update pyproject.toml and poetry.lock with pytest-mock

# Bugfix
* Fix `CavityResonator.is_CBI_stable`
* Fix quadrupolar wake potential sign
* Bugfixes with beam_ion_elements.py
* Fix adts in `TransverseMapSector`
* Fix `WakePotential.check_sampling`
* Fix `Sweep.plot`
* Fix `Monitor` sub-classes sometimes getting stuck when flushing data.
* Fix `generate_transverse_map_sector` functionality to deduce chromaticity from pyAT lattice.

# Authors who took part in this release
Alexis Gamelin, Vadim Gubaidulin, Keon Hee Kim, Watanyu Foosang, Teresia Olsson

# New features

## Space Charge

* Adds transverse space-charge module, implemented in TransverseSpaceCharge class.
* Space-charge is implemented as a slice-by-slice kick utilising the Bassetti-Erskine formula.
* Adds electromagnetic fields module. Handles Faddeeva function and electromagnetic fields for space-charge and beam-ion interactions.

## Ions

* Adds a beam_ion_effects module. It handles the generation of ions from a given residual gas pressure and the interaction between ions and the stored beam.
* Beam-ion interaction is implemented with weak-strong, strong-strong and Particle-In-Cell models.
* New classes: BeamIonElement, IonParticles, IonAperture, IonMonitor

## Add a Sweep element

* The new Sweep element can excite the beam between two frequencies, i.e., apply frequency sweep (chirp) to all or a given bunch in the chosen plane.
* Add option to save higher order spectrums in BunchSpectrumMonitor.
* Modify plot_bunchspectrum and streak_bunchspectrum to plot higher order spectrums.

## Other improvements and modifications

* Updated yokoya_elliptic with an analytical implementation.
* BeamLoadingEquilibrium is now computed on a grid and much faster.
* Add bunch_spectrum and plot_bunch_spectrum to BeamLoadingEquilibrium.
* Add R_factor calculation (Touschek lifetime ratio) to BeamLoadingEquilibrium.
* Add form factor contribution to lcbi_growth_rate_mode and lcbi_growth_rate.
* The energy_loss and power_loss_spectrum methods for ImpedanceModel can now take any bunch spectrum in an optional argument.

## Project management

* Added sphinx/readthedocs documentation
* Update README.md
* Added dynamic versioning and version print on import
* Added "please cite the following papers" on import
* Add Dockerfile based on gitlab-registry.synchrotron-soleil.fr/pa/collective-effects/python_mpi
* Add gitlab CI/CD .gitlab-ci.yml file
  * Add run test suite and formatters when there is a merge request or commit on "stable" or "develop" branch.
  * Build docker image and pip package when a tag is pushed and committed on "develop".

# Bugfix

* Fix resonator longitudinal wake function
* Fix an issue with random sampling in PhaseSpaceMonitor
* Fix plotting in plot_phasespacedata
* Fix some docstrings
* Fix emittance and CS invariant calculation when dispersion is included.

# Authors who took part in this release

Vadim Gubaidulin, Alexis Gamelin, Keon Hee Kim, Watanyu Foosang

# New features
Add storage ring data export to pyAT, Synchrotron.to_pyat retrun a pyAT simple_ring element.
Add an IIR filter in the ProportionalIntegralLoop class.
Add a current generator (Ig) modulation in the ProportionalIntegralLoop class.

# Other improvements and modifications
## Performance
Change the way Bunch particles coordinates are stored and accessed.
Speed-up TransverseMap.
Refactor WakePotential and add interp_on_postion option to allow for faster tracking, if False, the wake potential is interpolated on the bin center and each particle of the bin get the same value.

## Others
CavityMonitor now also records DFB_ig_phasor.
Add form factor option to CavityResonator.set_optimal_detune.
Update lcbi_growth_rate_mode, lcbi_growth_rate and lcbi_stability_diagram to optionally take  synchrotron_tune as input.
Add a CavityResonator.is_CBI_stable wrapper over lcbi_growth_rate.

## Project management
Add CONTRIBUTORS.md, update README.md and YML dependency file.
Add first unit tests for Synchrotron, Optics and Bunch class.
Update .gitignore.

# Bugfix
Fix resonator wake function for negative time and update docstrings.
Fix printing in BeamLoadingEquilibrium.
Fix double_sided_impedance for pandas>=2.X.X

# Authors who took part in this commit
Alexis Gamelin, Naoto Yamamoto, Vadim Gubaidulim

# New features

## Add various kind of loops and feedback for CavityResonator class
Add an interface in CavityResonator to allow for external FB and loops.
Add generator_phasor_record and ig_phasor_record attributes to CavityResonator.
Also change CavityMonitor and plot_cavitydata to record and display the new attributes.
Add ProportionalLoop, TunerLoop, ProportionalIntegralLoop and DirectFeedback class.
Add update_feedback method to CavityResonator to force FB update when needed.
Update CavityMonitor to now record Vc and theta.
Add option "mean" to plot_cavitydata to plot the mean phasor voltage and angle versus time for non empty bunches.
Add option "tuner_diff" to plot_cavitydata to plot the phase difference between cavity and generator current.
Add sample_voltage method to CavityResonator, used to sample the voltage seen by a zero charge particle during an RF period.

## Add higher order momentum compaction factor
Add mcf_order optional parameter for Synchrotron class to prodivde higher-orders momentum compaction factor.
Add Synchrotron.get_mcf_order method to compute momentum compaction factor up to 3rd order from AT lattice.
Add Synchrotron.get_longitudinal_twiss method to compute the longitudinal Twiss parameters and the synchrotron tune for single or multi-harmonic RF systems.
The longitudinal invariant Js is now computed in Bunch.cs_invariant and Beam.bunch_cs and save by BeamMontior and BunchMonitor, its value is 0 by default if the longitudinal Twiss parameters are not provided in the Synchrotron class.

## Other new features
Add monopolar component to WakeField and WakePotential class.
Add loss_factor computation for WakeFunction class.
Update read_ABCI function so it can now read files with monopolar and dipolar components together.
Added group_attributes and rename_attribute convenience methods to the ImpedanceModel class.
Add share_stds method to Mpi class.
Update spectral_density function with Chebyshev, Legenre and Sacherer modes.
Add head_tail_form_factor and tune_shift_from_effective_impedance functions.
Various small improvements.

## Project management
Add pyproject.toml and pypi integration through poetry.
Reformat the code using the yapf and isort formatters.

# Bugfix
Fix Bunch.plot_phasespace for up to date version of seaborn.
Fix Bunch.emit calculation for off center beams.
Fix the sign of long wake in LongRangeResistiveWall.
Fix Hermite mode to include normalisation by the mode number.
Fix various typo and docstrings.

# Authors who took part in this commit
Alexis Gamelin, Naoto Yamamoto, Vadim Gubaidulim

# New features
Rework and vastly improve the ImpedanceModel class.
Add a new TransverseMapSector element to tracking between two positions.
Add the transverse_map_sector_generator convenience function which generate a list of TransverseMapSector elements from a ring with an AT lattice.
Update the Optics class to be able to compute the phase advance at any location on the lattice.
Add a new method to BeamLoadingEquilibrium to compute the PTBL threshold.
Add the lcbi_stability_diagram function to plot the longitudinal coupled bunch instability stability diagram for a arbitrary list of CavityResonator objects.
Improve the lcbi_growth_rate_mode and lcbi_growth_rate functions.
Add save and load methods for Bunch and Beam objects.
Improve the PhysicalModel class, the change_values and taper methods are now more pratical to use and add get_aperture and plot_resistivity methods.
Add Synchrotron.get_adts method which computes ADTS from AT lattice.
Add read_ABCI, read_ECHO2D and improve read_CST functions to import external data.
Add a plot method for both Impedance and WakeFunction class.
Added class representation for ComplexData, Impedance, WakeFunction, WakeField, Bunch and Beam classes.
Rework the deconvolution/from_wakepotential/to_impedance methods for them to work with any data loaded in the Impedance/WakeFunction classes and not just CST text files.
Improved WakeField class by adding __iter__ and __add__ methods.
Add new Jupyter notebooks for collective effects and bunch by bunch feedback.

# Bugfix
Fix Coating impedance convention.
Fix ADTS implementation in TransverseMap to use Jx/Jy instead of x/y.
Fix ImpedanceModel.power_loss_spectrum that needs a double sided impedance spectrum.
Fix ExponentialDamper class.
Fix a hard coded value of 0.5 A in BeamLoadingEquilibrium class.
Fix transverse wake sign in get_gaussian_wakepotential.

Add bunch by bunch feedback module with ExponentialDamper and FIRDamper classes.
Various improvement for WakeFunction, Impedance and WakeField classes.
Add save and load functions to ImpedanceModel and WakeField classes.
Performance improvement for WakePotential class.

Add the Courant Snyder invariant to the saved data in the BunchMonitor and BeamMontior.
Add an n_bin optional parameter for CavityResonator.
Add a new example notebook for RF cavities and longitudinal beam dynamics.
Fix several bugs on the Monitor module.
Fix a bug in the Impedance class.

First release of mbtrack2.