BornAgain ≻ git-develop ≻ Documentation ≻ Python scripting ≻ Understand the syntax

Python syntax used in BornAgain scripts

We shall employ the same reflectometry script as on the preceding page to explain some Python syntax used in BornAgain scripts.

For easy reference, here again the full script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# dependencies = ["bornagain>=25,<26"]
# ///
"""
Basic example of specular reflectometry simulation.
The sample consists of 20 alternating Ti and Ni layers.
"""
import bornagain as ba
ba.require_versions("bornagain>=25,<26")
from bornagain import deg, angstrom, nm


def get_sample():
    # Materials
    vacuum = ba.Vacuum()
    ti_color = (0.05, 0.62, 0.55)
    ti_mat = ba.SLDMaterial("Ti", ti_color, -1.9493e-06, 0)
    ni_color = (0.93, 0.48, 0.14)
    ni_mat = ba.SLDMaterial("Ni", ni_color, 9.4245e-06, 0)
    si_color = (0.30, 0.62, 0.86)
    si_mat = ba.SLDMaterial("Si", si_color, 2.0704e-06, 0)

    # Layers
    top_layer = ba.Layer(vacuum)
    ti_layer = ba.Layer(ti_mat, 30*angstrom)
    ni_layer = ba.Layer(ni_mat, 70*angstrom)
    substrate = ba.Layer(si_mat)

    # Periodic stack
    n_repetitions = 10
    stack = ba.LayerStack(n_repetitions)
    stack.addLayer(ti_layer)
    stack.addLayer(ni_layer)

    # Sample
    sample = ba.Sample()
    sample.addLayer(top_layer)
    sample.addStack(stack)
    sample.addLayer(substrate)

    return sample


def get_simulation(sample):
    n = 500
    scan = ba.AlphaScan(n, 2*deg/n, 2*deg)
    scan.setWavelength(1.54*angstrom)
    return ba.SpecularSimulation(scan, sample)


if __name__ == '__main__':
    sample = get_sample()
    ba.showSample3D(sample, sample_size=120*nm, seed=0)
    simulation = get_simulation(sample)
    result = simulation.simulate()
    ba.plot_datafield(result)
    ba.plt.show()
auto/Examples/specular/basics/AlternatingLayers.py

We shall now explain the code.

The shebang line

#!/usr/bin/env python3

selects python3 when an executable script is launched directly on Unix-like operating systems; see the chapter on how to run scripts from the command line. It is ignored otherwise, as is all text from the comment start character # to the end of the line.

The # /// script block declares dependencies for uv; see Versioned Python scripts.

The text between triple quotes at the start of the script

"""
Text, text, text
"""

is the module’s docstring: a description available through Python’s help system.

import bornagain as ba gives the package the short name ba. The import from bornagain import deg, angstrom, nm provides unit constants used to express angles and lengths. ba.require_versions(...) checks installed versions at runtime.

The function

def get_sample():
    ...

constructs and returns a sample model. For more reference, see the sample section.

The function

def get_simulation(sample):
    ...

constructs and returns a simulation model. For more information, see the simulation section, and specifically the reflectometry reference.

The clause

if __name__ == '__main__':

ensures that the following statements are only executed if the script is called directly, as a “main” program. This makes the script importable without immediately running the simulation.

The lines

sample = get_sample()
simulation = get_simulation(sample)
result = simulation.simulate()

construct a sample and instrument model and run a simulation. The function simulate() returns a Datafield instance.

The line

ba.plot_datafield(result)

plots the simulated reflectivity as function of the incident glancing angle, using a BornAgain helper built on MatPlotLib. Like the simulation classes, BornAgain’s data import, fitting, plotting, and sample-inspection helpers are called directly through the ba package object.

ba.showSample3D(...) opens a 3D view of the sample. ba.plt.show() displays the Matplotlib figures.