Working with sample parameters

This section gives additional details about the manipulation of sample parameters during run time, after the sample has already been constructed. For a single simulation this is normally not necessary. However, it might be useful during interactive work when the user tries to find optimal sample parameters by running a series of simulations. A similar task also arises when the theoretical model, composed of the description of the sample and of the simulation, is used for fitting real data. In this case, the fitting kernel requires a list of the existing sample parameters and a mechanism for changing the values of these parameters in order to find their optima.

In BornAgain this is done using the so-called sample parameter pool mechanism. We are going to briefly explain this approach using the code from the example Working With Sample Parameters.

In BornAgain a sample is described by a hierarchical tree of objects. For the multilayer created in this example, this tree can be graphically represented as shown in Fig. 1. Similar trees can be printed in a Python session by running

sample.printSampleTree()

Fig. 1: Tree representation of the sample structure.

The top MultiLayer object is composed of three children, namely Layer #0, Layer Interface #0 and Layer #1. The children objects might themselves also be decomposed into tree-like structures. For example, Layer #0 contains a ParticleLayout object, which holds information related to the two types of particles populating the layer. All numerical values used during the sample construction (thickness of layers, size of particles, roughness parameters) are part of the same tree structure. They are marked in the figure with shaded gray boxes.

These values are registered in the sample parameter pool using the name composed of the corresponding nodes’ names. A list of the names and values of all registered sample’s parameters can be displayed using the command

sample.printParameters()

The output will be:

'/MultiLayer/Layer0/ParticleLayout/ParticleInfo0/Particle/FormFactorCylinder/height':5
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo0/Particle/FormFactorCylinder/radius':5
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo0/Particle/position_x':0
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo0/Particle/position_y':0
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo0/Particle/position_z':0
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo0/abundance':0.5
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo1/Particle/FormFactorPrism3/height':5
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo1/Particle/FormFactorPrism3/length':10
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo1/Particle/position_x':0
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo1/Particle/position_y':0
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo1/Particle/position_z':0
'/MultiLayer/Layer0/ParticleLayout/ParticleInfo1/abundance':0.5
'/MultiLayer/Layer0/thickness':0
'/MultiLayer/Layer1/thickness':0
'/MultiLayer/crossCorrLength':0

These values can be accessed/changed during run time. For example, the height of the cylinders populating the first layer can be changed from the current value of 5 nm to 10 nm by running the command

sample.setParameterValue(’/MultiLayer/Layer0/ParticleLayout/ParticleInfo0/Particle/FormFactorCylinder/height’, 10*nanometer)

Wildcards ’*’ can be used to reduce typing or to work on a group of parameters. In the example below, the first command will change the height of all cylinders in the same way,
as in the previous example.

sample.setParameterValue(’*FormFactorCylinder/height ’, 10*nanometer)

The line below will change simultaneously both, the height and the half-side length of prisms.

sample.setParameterValue("*/FormFactorPrism3/*", 10*nanometer)

See the complete code in the working with sample parameters example.