CHANGELOG

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.16.2] – 2026-04-13

Fixed

  • Bad conflict resolution in AcceleratorFactory.

[0.16.1] – 2026-04-13

Added

  • New OptimisationAlgorithm: PredefinedSolution. It is automatically created when the Accelerator is unpickled and uses the stored SimulationOutput to fake the optimization process.

  • New OptimisationAlgorithm: NSGA-III, adapted to high-dimensionality problems.

  • New ObjectivesFactory: RemainBelow. Sets an upper limit for a variable.

  • Refactored creation of DesignSpaceFactory. Opens way to manual definition of variables/constraints in TOML, rather than using design_space_preset = abs_phase_amplitude or design_space_preset = RelPhaseAmplitudeWithConstrainedSyncPhase.

    • [x] Choose design_space_preset = UserDefined

    • [x] Set variable_names = ['k_e', 'phi_0_abs] (for example)

    • [x] Set constraint_names = ['phi_s'] (for example)

    • [ ] Ensure that order of variables is not hard-coded somewhere.

    • [ ] Find an intuitive way to set limits for the different variables and constraints.

Fixed

  • Synchronous phases can be used as constraints again.

    • Synchronous phases in constraints calculations was taken from SimulationOutput.elts (nominal settings) instead of SimulationOutput.set_of_cavity_settings. This bug was nasty. Fixing it dramatically improved constrained optimization.

  • Information message when creating ListOfElements subset printed wrong end of linac subset.

[0.16.0] – 2026-03-04

Added

  • The key pickle_paths in the [files] section of the TOML configuration file allows you to control pickling of Accelerators.

    • If a given PKL file exists, it is unpickled and associated calculations are skipped.

    • If it does not exist, corresponding Accelerator is pickled at the end of the simulation.

    • Configuration file example:

    [files.pickle_paths]
Reference = "reference.pkl"

# Scenario 1: pre-computed solution (skips optimization if file exists)
[files.pickle_paths.000001]
Solution = "solution-000001.pkl"

# Scenario 2: alternatives with custom names (optimization still runs, the
# pickled Accelerators will be appended)
[files.pickle_paths.000002]
"Conservative approach" = "design-conservative.pkl"
"Aggressive tuning" = "design-aggressive.pkl"

# Scenario 3: solution + alternatives
[files.pickle_paths.000003]
Solution = "solution-000003.pkl"
"Tweaked design" = "tweaked.pkl"
"Experimental config" = "experimental.pkl"

Changed

  • AcceleratorFactory produces a dict[int, list[Accelerator] instead of a plain list[Accelerator]. Keys are FaultScenario index, values corresponding Accelerators – including unpickled Accelerators for comparison. Nothing should change for you if you use the functions from the ui.workflow_setup module.

  • plot.factory is more robust, and allows plotting any number of Accelerators. Use the only_solver_id key to filter by BeamCalculator.

[0.15.2] – 2026-03-04

Added

  • Build on Python 3.14.

Fixed

  • Build on manylinux.

[0.15.1] – 2026-03-03

Changed

  • AcceleratorFactory produces a dict[int, list[Accelerator] instead of a plain list[Accelerator]. Keys are FaultScenario index, values corresponding Accelerators – including unpickled Accelerators for comparison. Nothing should change for you if you use the functions from the ui.workflow_setup module.

  • plot.factory is more robust, and allows plotting any number of Accelerators. Use the only_solver_id key to filter by BeamCalculator.

0.15.1 – unreleased

Added

  • New Objective: MinimizeVariation to minimize std of a quantity.

  • Check the new ObjectivesFactory: RegularEnvelope for an example of usage.

  • New Accelerator.plot method for rapid plotting of stored data.

Changed

  • Accelerator.elts must now be called without the ().

[0.15.0] – 2025-12-11

Added

  • In the [wtf] section of the TOML configuration file:

    • id_nature can be set to "lattice" or "section". The indexes listed in failed will then be lattice or section index.

    • index_offset = 1 optional configuration key makes indexes in failed and compensating_manual start at 1 instead of 0. With this option, failed = [[50]] means the 50th cavity/element, not the 51st.

    • New entry automatic_study. Two values allowed for now: "single cavity failures" and "cryomodule failures". All the cavities/cryomodules indicated in failed will be failed one after another. Typical usage; this will run a systematic study of all single cavity failures in the second section.

automatic_study = "single cavity failures"
failed = [1]
id_nature = "section"

[!IMPORTANT] This new feature introduced a new dependency between AcceleratorFactory and FaultScenarioFactory. If you created your Accelerator and FaultScenario yourself instead of using utility functions from the ui module, automatic_study will not be supported.

[0.14.1] – 2025-12-10

Changed

  • Deprecated numpy API in Cython is no longer used.

  • The Accelerator factories NoFault and WithFault are deprecated. Prefer the general purpose AcceleratorFactory.

Fixed

  • The k_b parameter of FIELD_MAP was not updated.

    • We always keep it equal to k_e for now.

[0.14.0] – 2025-12-04

Added

  • Explicit Cython optional dependency in pyproject.toml.

Changed

  • Refactored the RfField class, which is now called Field.

    • Opens up the way for DC and 3D fields support.

      • FIELD_MAP 7700 is partially supported: motion is integrated on axis.

    • Massive speed-up w.r.t 0.13.5:

      • Envelope1D is ~40% faster.

      • CyEnvelope1D is ~50% faster.

      • Envelope3D is ~25% faster. Note that it is not fully optimized.

[!IMPORTANT] If you encounter a “wrong number of attributes” error using CyEnvelope1D, it means that Cython modules were not recompiled. Recompile the Cython modules following the classic instructions.

[0.13.5] – 2025-11-27

Changed

  • Modernized the experimental module: Plotter, SimulationOutputEvaluator. Write some tutorial before official functionality release.

Fixed

  • Cython solver was not used even if configuration asked for it.

[0.13.4] – 2025-11-26

Fixed

[0.13.3] – 2025-11-25

Fixed

  • Removed pymoo dependencies and NSGA algorithm to avoid build errors.

[0.13.2] – 2025-11-25

Fixed

  • Bad output path resolution due to a merge conflict.

[0.13.1] – 2025-11-25

Changed

  • export_phase is now a mandatory configuration entry for beam calculators. Former default behavior is preserved: if this entry is not given, we set it to "as_in_cavity_settings".

Fixed

  • Field map phase is correctly exported in the DAT files.

  • Ensured that the default_value of configuration entries are used.

  • TraceWin compensation works again.

[0.13.0] – 2025-11-05

Added

  • SNS-like compensation method:

    • Activate it with reference_phase_policy = "phi_s", strategy = "corrector at exit" and "objective_preset = "CorrectorAtExit".

    • n_compensating cavities around each failure are used to keep energy longitudinal shape “reasonable”.

      • n_compensating = 0 is currently not supported.

    • All downstream cavities are rephased to preserve longitudinal acceptance.

    • Final n_correctors cavities accelerate the beam to retrieve nominal energy.

Deprecated

  • All the Objective subclasses are now in the lightwin.optimisation.objective .objective module. Old import paths still work but raise a warning when used. The Objective subclasses are:

    • MinimizeDifferenceWithRef

    • MinimizeMismatch

    • QuantityIsBetween

[0.12.1] – 2025-08-26

Changed

  • More consistent documentation of parameters type.

Fixed

  • cython transfer matrices were not used

[0.12.0] – 2025-08-25

Added

  • The cavities reference phase is now determined by reference_phase_policy.

    • This is more permissive than flag_phi_abs, that could only be True or False.

    • Now, reference phase can be phi_0_abs, phi_0_rel, phi_s or as_in_dat_file!

Changed

  • The CavitySettings object, and in particular its handling of phases and reference phases, is more robust.

    • This update introduced significant changes: do not hesitate to file an issue if you encounter MissingAttributeError, or any phase-related error.

Deprecated

  • Do not use the TOML flag_phi_abs configuration entry anymore, prefer reference_phase_policy.

    • If flag_phi_abs is found, a deprecation warning is raised.

    • For now, flag_phi_abs as precedence over reference_phase_policy to keep backward compatibility.

[0.11.4] – 2025-08-21

Added

  • New Sphinx directive to nicely display dictionaries.

  • Support for Bayesian Optimization kwargs.

Fixed

  • Selection of simulated_annealing was in fact not possible.

[0.11.3] – 2025-08-20

Added

  • New optimization algorithms:

    • Simulated Annealing.

    • Bayesian Optimization.

[0.11.2] – 2025-08-20

Fixed

  • Dummy import error in test suite.

[0.11.1] – 2025-08-20

Changed

  • Tables listing configuration options are more consistent in the html documentation.

[0.11.0] – 2025-08-19

Added

  • Calculation of energy and phase acceptances (#5).

  • New physics package holding helper physical functions (#6).

  • New plot preset: acceptance.

  • Explicit error message when trying to plot some bugged quantities:

    • Transfer matrix components (TraceWin)

    • Phase acceptance (TraceWin)

Fixed

  • Objective position was plotted at the wrong place when the x-axis of plot was index of elements.

  • r_zdelta components can be get and plotted using transfer_matrix plot preset.

  • Symmetric plot (envelope, acceptance) work as expected.

[0.10.6] – 2025-07-04

Added

  • Documentation for setuptools_scm issues when downloading LightWin as an archive.

[0.10.5] – 2025-07-01

Fixed

  • Missing dependencies in linux Github Actions wheel builder.

[0.10.4] – 2025-07-01

Added

  • Introduced BeamKwargs typing. Easier to know the values stored in this object.

[0.10.3] – 2025-06-30

Fixed

  • Bug introduced in the beam parameters test by 0.10.2.

[0.10.2] – 2025-06-30

Fixed

  • MinimizeDifferenceWithRef residuals func now returns an always positive value.

    • Does not make any difference with OptimisationAlgorithm such as LeastSquares which take the squared residuals. May be a game changer for other algorithms.

  • Flag to handle SimulationOutput.get(..., elt=elt) when elt: Element is not in SimulationOutput.elts.

    • Fixed some errors at Objective creation.

[0.10.1] – 2025-06-06

Fixed

  • Update of CITATION.cff, CHANGELOG.md

[0.10.0] – 2025-06-06

Added

  • release.py script, CONTRIBUTING.md to ease collaboration.

Changed

  • Accelerator.get, SimulationOutput.get, ListOfElements.get now accept arguments found in FieldMap.

    • e.g.: ListOfElements.get("freq_cavity_mhz") is now valid.

[0.10.0rc0] – 2025-05-12

Changed

  • Refactored the get methods.

    • It may introduce some bugs, do not hesitate to reach me out in case of problem.

Fixed

  • get refactoring fixed several bugs:

    • Some get methods such as SimulationOutput.get did not consider the phase_space_name keyword argument.

    • get methods behavior are more consistent.

[0.9.4] – 2025-05-06

Added

  • Wrote the documentation for the magic get methods.

  • Added get examples in the example notebook.

[0.9.3] – 2025-04-09

Fixed

  • The lightwin.config_manager symlink pointing to lightwin.config.config_manager did not resolve on Windows. It was deleted and all import lightwin.config_manager were replaced by import lightwin.config.config_manager.

Changed

  • import lightwin.config_manager no longer works! Replace all occurrences by import lightwin.config.config_manager.

[0.9.2] – 2025-04-07

Added

  • Type hints for the .get methods.

  • Notebook example to showcase how LightWin can be used.

  • You can give matplotlib.axes.Axes.plot kwargs in the plots TOML section.

[0.9.1] – 2025-01-30

Added

  • When tagging a version:

    • The package is built and tested on several platforms, before being released to PyPI.

    • CITATION.cff is automatically updated accordingly.

  • Package on pip (simpler installation with pip install lightwin).

Changed

  • Data used for examples was moved from data/example/ to src/lightwin/data/ads/.

[0.9.0] – 2025-01-21

Added

  • CI/CD tasks:

    • Automatic linting with pre-commit.ci.

    • Automatic checking of common mistakes with pre-commit.ci.

    • Run automatic tests using pytest and GitHub workflows.

  • Badges to quickly see if something went wrong.

Changed

  • Introduced optional dependencies.

    • Install them with pip install -e .[docs] or pip install -e .[test].

    • It is recommended to install LightWin with the test optional dependencies.

[0.8.4] 2025-01-15

Changed

  • Tests now rely on the pytest.approx functions, much cleaner than previous approach.

[0.8.3] 2025-01-13

Added

  • Version number and commit number are written in the log file.

Fixed

  • Properly handle opening/closing log files.

  • Display of some objective values.

[0.8.2] 2024-11-11

Added

  • Possibility to save optimization history. Check [save_wtf] table in data/example/lightwin.toml.

[0.8.1] 2024-11-11

Added

  • Utility scripts in ui/workflow_setup.py defining generic LightWin workflows.

  • User can provide fault_scenario_factory with a ObjectivesFactory to define objectives without altering the source code.

  • The add_objective in the [plots] TOML table to show position of objective.

[0.8.0b4] 2024-11-08

Added

  • SimulationOutput.plot() method, that calls .get under the hood and takes in the same arguments.

  • Non-normalized emittance is stored under non_norm_eps. Ex: SimulationOutput.get("non_norm_eps_phiw").

Changed

  • Normalized emittances are explicitly marked as normalized in the output.

[0.8.0b3] 2024-11-07

Added

  • SET_SYNC_PHASE commands are now handled for export in DAT file.

  • It is now possible to use the export_phase in the [beam_calculator] table to choose the type of phase to put in the output DAT file.

Changed

  • Display of cavity parameters in cav.png, so that 2nd solver does not hide 1st.

Fixed

  • Calculating phi_0_abs of a cavity when the reference was phi_s raised error.

  • path_cal not existing in TraceWin raised error instead of just creating the folder.

  • Interpolation of Twiss to compute mismatch factor was bugged.

[0.8.0b2] 2024-11-05

Fixed

  • Fixed several bugs that were outside the scope of my pytests.

    • beam_calc_post configuration key was no longer recognized.

    • Not providing the project_folder key in the [files] TOML table led to bug.

    • Some elements created bugs in CyEnvelope1D.

[0.8.0b1] 2024-11-04

Fixed

  • Dot characters in field map file names do not throw an error anymore.

  • When several Element objects have the same _personalized_name, a fallback name and a warning is raised instead of raising an AssertionError.

Changed

  • Creation of DatLine object, holding a line of the .dat file. Solves several bugs, e.g. with hyphens in personalized names.

  • Makefile for docs is up-to-date. Instructions in README.

  • Changed location of RfField object, now in core/em_field/rf_field.

  • The solver Envelope1D is now CyEnvelope1D when user wants Cython.

[0.8.0b0] 2024-10-22

Changed

  • The configuration manager was refactored.

  • NewRfField object officially replaces RfField.

  • The configurations for the different objects are now in the specs.py files, in the same folder as the object they instantiate.

Deleted

  • Constants were removed from the config module to fix circular dependency and bad design issues.

  • BeamCalculator objects now need to be given the beam configuration dict. Easiest is to instantiate BeamCalculatorFactory with **config.

  • Accelerator will also use data from beam. Instantiate AcceleratorFactory with **config.

  • SimulationOutputFactory instantiated with _beam_kwargs.

[0.7.0] 2024-10-22

Added

  • Better display of units in documentation with the new :unit: role.

[0.7.0b3] 2024-10-09

Added

  • Documentation has links to documentation from other libraries (numpy etc).

Changed

  • Documentation is nitpicky.

Fixed

  • Loading function of evaluations.csv in lw-combine-solutions to handle trailing whitespaces.

  • Documentation generation does not raise warnings anymore (except for pymoo).

[0.7.0b2] 2024-10-01

Fixed

  • Updated path to scripts in pyproject.toml; they should work again!

Changed

  • Table of Contents does not show the full path to every module/package anymore. The API section should be much clearer now!

  • Better display of the constants in the doc

[0.7.0b1] 2024-09-30

Fixed

  • Scripts moved to the lightwin module so that they can actually be imported.

  • outfolder argument in combine-solutions script is automatically created if it does not exist.

  • Documentation includes the API reference again.

  • Most of the errors raised during documentation compilation were fixed.

[0.7.0b0] 2024-09-26

Fixed

  • Released constraints on the versions of installed packages.

[0.7.0b] 2024-08-07

Changed

  • The code is packaged.

  • Installation instructions were updated.

  • It is not necessary to add LightWin to your PATH.

  • Imports of LightWin modules and functions must be imported from lightwin: from lightwin.<foo> import <fee>.

  • Cython compilation is automatic.

[0.6.21] 2024-06-07

Added

  • Support for REPEAT_ELE command.

  • Basic support for SET_SYNC_PHASE. This command can be kept in the input .dat, but output .dat will hold relative or absolute phase (determined by the BeamCalculator.reference_phase).

Changed

  • When creating the BeamCalculator, prefer method="RK4" over method="RK" for 4th order Runge-Kutta method.

[0.6.20] 2024-05-31

Added

  • Basic support for ADJUST commands

  • New functionality: pass beauty.

  • After a FaultScenario is fixed, use insert_beauty_pass_instructions from util.beauty_pass to add diagnostics and adjust and let TraceWin refine the settings.

  • Prefer providing TraceWin with cancel_matchingP = true (would be too long).

  • Do NOT provide cancel_matching = true nor cancel_matching = false. Just drop this argument out (FIXME).

  • Compensating, rephased and failed cavities will be incorrectly displayed as nominal (green) cavities in the output figures (FIXME).

Fixed

  • Personalized name of field maps 1100, 100 and of quadrupoles are now exported in output dat file.

  • Note that this is a temporary patch, a more robust solution will be implemented in future updates.

[0.6.19] 2024-05-27

Added

  • Support for the TraceWin command line arguments: algo, cancel_matching and cancel_matchingP

  • You can provide a shift key in wtf to shift the window of compensating cavities.

    • Example with 4 compensating lattices:

      • shift=0 -> 2 upstream and 2 downstream compensating lattices

      • shift=+1 -> 1 upstream and 3 downstream compensating lattices

      • shift=-1 -> 3 upstream and 1 downstream compensating lattices

  • Variable/Constraint limits can be changed after creation with the change_limits method.

  • You can override the default kwargs in the OptimisationAlgorithm actual algo.

  • Support for pickling/unpickling objects.

    • In other words: some objects such as Accelerator or SimulationOutput can be saved in binary format, so they can be reloaded and reused in a later Python instance without the hassle of recreating and recomputing everything.

Changed

  • A configuration file is mandatory to select the TraceWin executables.

Fixed

  • SimulationOutput created by TraceWin have a is_multiparticle attribute that matches reality.

  • Position envelopes are now plotted in deg instead of degdeg (1degdeg = 180 / pi deg).

[0.6.18] 2024-04-23

Added

  • You can forbid a cavity from being retuned (ex: a rebuncher which is here to rebunch, not to try funny beamy things). Just set my_cavity.can_be_retuned = False.

  • By default, a lattice without any retunable cavity is skipped when selecting the compensating cavities; this behavior can be modified by setting a min_number_of_cavities_in_lattice with l neighboring lattices method in the configuration.

Changed

  • New typing features impose the use of Python 3.12.

  • The idx key in the wtf dictionary is now called id_nature, which can be one of the following:

    • cavity: we consider that failed = [[10]] means “the 10th cavity is down”.

    • element: we consider that failed = [[10]] means “the 10th element is down”. If the 10th element is not a cavity, an error is raised.

    • name: we consider that failed = [["FM10"]] means “the first element which name is ‘FM10’ is down”.

  • With the l neighboring lattices strategy, l can now be odd.

  • You can provide tie_strategy = "downstream first" or tie_strategy = "upstream first" to favour up/downstream cavities when there is a tie in distance between compensating cavities/lattices and failed.

Fixed

  • Colors in Evaluator plots are now reset between executions

[0.6.17] 2024-04-19

Added

  • Switch between different phases at .dat save.

Fixed

  • With the "sync_phase_amplitude" design space, the synchronous phases were saved in the .dat and labelled as relative phase (no SET_SYNC_PHASE).

[0.6.16] 2024-04-17

Added

  • New design space "rel_phase_amplitude_with_constrained_sync_phase"

  • Pytest for basic compensation with all BeamCalculator

  • Pytest for every Design Space

Deprecated

  • Some design space names are not to be used.

  • "unconstrained" -> "abs_phase_amplitude"

  • "unconstrained_rel" -> "rel_phase_amplitude"

  • "constrained_sync_phase" -> "abs_phase_amplitude_with_constrained_sync_phase"

  • "sync_phase_as_variable" -> "sync_phase_amplitude"

Removed

  • Support for .ini configuration files.

  • "phi_s_fit" entry in configuration (use the proper design space config entry instead)

Fixed

  • Lattices and their indexes correctly set.

  • Synchronous phases correctly calculated and updated; can be used as a variable again.

Future updates

[0.?.??] 2024-??-?? – branch under development

Changed

  • evaluator objects are more robust and can be configured from the .toml.

  • Plotting is now performed thanks to the plotter library.

Added

  • FIELD_MAP 70 does not raise error (warning issued with Envelope3D: no transverse tracking).

  • SUPERPOSE_MAP will be implemented for 1D maps (warning issued with Envelope3D: no transverse tracking).