Release 24.0

This release brings important changes in the sample model. We rectify the logic by inverting the place of inter-particle structures and particles in the model hierarchy. For the first time, we support three-dimensional bulk structures, starting with dilute and dense random assemblies. Ground is laid for future addition of ordered 3D structures.

This release breaks Python scripts and GUI projects. Structural changes are so deep that we cannot provide a migration script. However, thanks to progress in agentic coding based on a large language model, we can offer a new migration service: Send us your script from BornAgain 23 or earlier, and we will try conversion to BornAgain 24 using our trained coding agent.

We now describe the most important changes in some detail.

Instrument model

In the instrument model, we added support for a detector below the horizon and for a beam entering from below.

Support for polarization has been improved. The polarization analyzer now takes three arguments: direction, parallel transmission, and antiparallel transmission.

The Offspecular now performs adaptive integration along phi_f; therefore the n_phi argument could be removed. The integration can be controlled with ‘setOffspecIntegratorOptions’.

Sample model

Rectified hierarchy

In the Sample model, we completely removed the Layout class. To recall, the previous model hierarchy was

• Sample
  • Layer
    • Layout
      • has particles
      • has an IInterference class, except if particles are uncorrelated

The new model hierarchy is

• Sample
  • Layer
    • Struct

The interparticle structure is specified by classes that inherit from the abstract interface class Struct. The prefix “Interference” has been dropped from all class names:

• Struct
  • Struct2D
    • Disordered2D
      • Dilute2D
      • Dense2D
    • Ordered2D
      • Crystal1D
      • Crystal2D
      • FiniteCrystal2D
      • Paracrystal2D
      • RadialParacrystal
  • Struct3D
    • Disordered3D
      • Dilute3D
      • Dense3D

In the future, we intend to add Ordered3D classes to support bulk lattices.

Dilute vs dense random assemblies

The Disordered2D and Disordered3D stand for random particle assemblies. By default, these assemblies are either Dilute, meaning that particles are completely uncorrelated, or Dense. For dense assemblies, excluded-volume interactions are taken into account, and the structure factor is computed according to the Percus-Yevick approximation.

Suspended vs deposited 2D structures

In the past, 2D structures were always deposited on top of a reference plane. This was the bottom interface of a layer, except for the substrate where the reference was the top interface.

Now 2D structures must be added using new functions

• Layer::deposit2D
• Layer::suspend2D While “deposit” attaches the bottom of the embedded particles to the bottom of the layer, “suspend” attaches the top of the particles to the top of the layer. While “deposit” must not be used with the substrate layer, “suspend” must not be used with the top layer.

If a plane is only partly covered by structure, or is to be covered by an incoherent mixture of different structures, then use the functions

• Layer::addDeposit2D
• Layer::addSuspend2D which take an additional coverage argument (with values between 0 and 1).

Particle alignment

In the past, particles wer aligned at the bottom, i.e. the lowest point of the particle volume was placed in the reference plane. There was some workaround for spheres in lattices, and some exception for soft particles. To end with that confusion, alignemnt at bottom, center, or top must now explicitly be specified in the Particle, Compound, CoreShell, Mixture, Mesocrystal constructors.

Mixtures

The new Mixture class, implemented upon user request, represents particle sites occupied at random by different kinds of particles.

Ordered structures

For 2D ordered systems, the parameter lateralPositionVariance (former positionVariance) has now the dimension length (instead of area).

For the Mesocrystal class, there is a new setMesoReciprocalSum option.

Form factor classes

There are a few changes to form factor classes:

• Ellipsoid added
• HemiEllipsoid replaced by EllipsoidalSegment
• HorizontalCylinder accepts cutFromTop and cutFromBottom arguments

Materials

The Material class has been reengineered so that refraction-index-based and SLD-based materials can be used together.

The SimulationOption setUseAvgMaterials is now true by default. This means that the transmission and reflection computation uses a refractive index that takes into account not only the bulk material of a layer but also its particle decoration. The new default ensures correctness (within the limits of DWBA) even for dense decorations. Setting the option back to false is a legitimate approximation for dilute decorations, but has no computational advantages. Therefore it should be rarely needed, except perhaps for reproducing previous simulations.

Further changes

For further improvements and bug fixes, see the CHANGELOG.

Best greetings from the BornAgain maintainer team:

Ammar Nejati, Mikhail Svechnikov, Joachim Wuttke

January 1, 0001