BornAgain ≻ 1.19 ≻ Documentation ≻ Python scripting ≻ Getting started ≻ 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

#!/usr/bin/env python3
"""
Basic example of specular reflectometry simulation with BornAgain.
The sample consists of 20 alternating Ti and Ni layers.
"""
import bornagain as ba
from bornagain import deg, angstrom


def get_sample():
    # Define materials
    m_ambient = ba.MaterialBySLD("Vacuum", 0, 0)
    m_ti = ba.MaterialBySLD("Ti", -1.9493e-06, 0)
    m_ni = ba.MaterialBySLD("Ni", 9.4245e-06, 0)
    m_substrate = ba.MaterialBySLD("SiSubstrate", 2.0704e-06, 0)

    # Define layers
    ambient_layer = ba.Layer(m_ambient)
    ti_layer = ba.Layer(m_ti, 30*angstrom)
    ni_layer = ba.Layer(m_ni, 70*angstrom)
    substrate_layer = ba.Layer(m_substrate)

    # Define sample
    sample = ba.MultiLayer()
    sample.addLayer(ambient_layer)
    for i in range(10):
        sample.addLayer(ti_layer)
        sample.addLayer(ni_layer)
    sample.addLayer(substrate_layer)

    return sample


def get_simulation(sample, scan_size=500):
    simulation = ba.SpecularSimulation()
    scan = ba.AngularSpecScan(1.54*angstrom, scan_size, 0, 2*deg)
    simulation.setScan(scan)
    simulation.setSample(sample)
    return simulation


if __name__ == '__main__':
    import ba_plot
    sample = get_sample()
    simulation = get_simulation(sample)
    ba_plot.run_and_plot(simulation)
AlternatingLayers.py

We shall now explain the code section by section.

Front matter

The shebang line 

#!/usr/bin/env python3
makes the script executable under Unix-like operating systems, see the chapter on how to run scripts from the command line.

Lines between triple quotes 

"""
Text, text, text
"""
are comments.

The line 

import bornagain as ba
imports the Python module bornagain (small caps, see chapter on how to find BornAgain), and assigns it the alias ba for brevity. Classes and functions from the BornAgain API are now available with the prefix ba..

The line 

from bornagain import deg, angstrom
makes a few frequently used symbols, namely the unit multipliers for degree and angstrom, available without prefix.

Sample

get_sample is a function without arguments. It returns an object of type MultiLayer.

The return statement is preceded by three stances. Each stance starts with a comment line, 

    # comment extends from hash character to end of line

BornAgain functions that start with a capital letter, like MaterialBySLD or Layer are constructors or constructor-like global functions. They return new objects. An object is an instance of a class. The function MaterialBySLD instantiates an object of type Material the function Layer an object of type Layer.

Function like addLayer is a member function of class MultiLayer. This can be seen from the two lines 

    sample = ba.MultiLayer()
    sample.addLayer(ambient_layer)
where sample is created as a new instance of class MultiLayer.

Simulation

get_simulation(sample, scan_size=500) is a function with one required argument (sample) and one optional keyword argument (scan_size). If the function is called with only one argument, then scan_size is assigned the default value 500.

angstrom and deg are numeric constants. They are used to convert physical quantities to internal units nanometer and radian.

The function returns an object of type SpecularSimulation.

Main program

The line 

if __name__ == '__main__':
is standard Python idiom. It ensures that the following is executed if and only if this script is executed directly, as a main program, but not if this script is included as a submodule in some other code.

The lines 

    sample = get_sample()
    simulation = get_simulation(sample)
call the two functions defined above in order to obtain the sample model and then the full simulation setup, comprising sample and instrument model.

Finally, the single line 

    ba_plot.run_and_plot(simulation)
runs the simulation and plots the result, using MatPlotLib. It uses the module ba_plot, imported a few lines before. See section Plot and export for other ways of running simulations and plotting or exporting results.