Release 25.0.0

This release consolidates the transition to a Python-only interface begun in v24.

Versioning

From here on, we follow Semantic Versioning (MAJOR.MINOR.PATCH): major releases introduce incompatible API changes, minor releases add functionality while preserving compatibility, and patch releases provide backward-compatible bug fixes.

The new ba.require_versions helper, to be used near the top of any script, stops execution with a clear error when the BornAgain module or any other dependency does not meet a version requirement. Usage is demonstrated in all our example scripts.

Additionally, each example declares the required version of Python, BornAgain, and any other dependency, in a header comment. This is particularly useful when working under the modern Python environment manager uv. The command uv run example.py automatically launches the script in the right environment without prior setup. Of course, BornAgain continues to work in more traditional Python environments.

API simplification

A number of external dependencies and internal components of the C++ BornAgain core were discarded as remnants from the GUI era.

The reading of data formats now mostly relies on established Python packages like NumPy, FabIO, h5py, and nexusformat. Reflectometry tables and BerSANS files are still parsed by BornAgain’s Python helpers.

Calculation of fit objective functions is no longer handled inside BornAgain; each fitting script now freely defines its objective function and passes it to an optimizer from lmfit or SciPy.

Mask shapes were completely removed from the BornAgain core. Detector masks are now supplied as boolean NumPy arrays, where True marks an excluded pixel. These arrays can be created in the script or with the help of an external tool. To ease this process we released a separate GUI tool PixelMasker, which reads standard 2D image formats and exports masks as boolean arrays.

Python helpers

Python helpers for data import, plotting, fitting, and sample inspection are now available directly from the bornagain module, including Matplotlib’s pyplot through ba.plt.

To make the Python API cleaner and safer to use, the plotting and 3D-view functions declare their options explicitly, with warnings or errors for unexpected arguments. Internal SWIG proxy types and helpers are no longer exposed through the public interface.

Plotting has been reworked to make it more flexible and consistent. Simulation results, measurements with error bars, and transformed data can be combined in custom Matplotlib figures, with shared conventions for intensity scales. The same plotting functions can be reused in customizable live fit monitors, independently of the optimizer.

Sample model and simulated physics

Simulation capabilities were extended:

  • Diffuse scattering from rough interfaces now supports polarized beams and magnetic samples
  • Diffuse scattering from rough interfaces is now evaluated below the sample horizon
  • Beam from below (negative grazing angle) is supported in specular, GISAS, and depth-probe simulations
  • DepthprobeSimulation supports magnetic samples and polarized beams
  • Simulations support custom backgrounds, defined right in the script, including coordinate-dependent backgrounds
  • Wavelength scans now support relative wavelength distributions

Sample and particle models were also extended:

  • Pyramid2, Pyramid3, Pyramid4, and Pyramid6 accept obtuse dihedral angles
  • Pyramid2 accepts separate taper angles for its length and width
  • Added Paracrystal1D for directional grating-like paracrystals

Example collection

The example collection has been expanded with:

  • polarized neutron scattering from rough interfaces with magnetic contrast
  • polarized neutron reflectometry and off-specular scattering from CoFe/IrMn stripe domains, following Saerbeck et al.
  • reflectometry through the substrate
  • custom backgrounds
  • Fourier transforms of scattering data
  • a new guide demonstrating how to define neutron and X-ray materials from chemical formulas using periodictable

The examples have been regrouped by simulation type and are now presented in a visual catalog in the documentation, with scripts available for download. All the required data files for examples are now located beside the scripts, replacing the BA_DATA_DIR environment variable.

Conclusion

We have made every effort to preserve compatibility with v24: most existing API calls remain supported, including those for static plotting. The CHANGELOG and the migration guide list the compatibility exceptions and explain how to update affected scripts.

For further improvements and bug fixes, see the CHANGELOG.

October 16, 2026