Simulation Parameters¶

A STEMsalabim simulation is mainly configured via parameter files, with a few exceptions where configuration options may be overriden by command line arguments.

Parameter files¶

The configuration file that STEMsalabim expects for the command line parameter --params is formatted using the simple JSON-like syntax of libConfig syntax. Below all available parameters are tabulated. Each section (block in the libConfig syntax) is described separately below.

`application`¶

The application block contains general settings regarding the simulation.

application: {
    random_seed = 0;             # the random seed. 0 -> generate
}

application.random_seed

unsigned int [default: `0`]

In the frozen lattice approximation, the atoms are randomly dislocated from their equilibrium position. The random seed for that can be specified here. If set to 0, a random seed is generated by the program. For reproduction of previous results, the seed can be set to a specific value.

`simulation`¶

Some general settings specific to this simulation.

simulation: {
    title = "benchmarksmall";    # title of the simulation
    bandwidth_limiting = true;   # bandwidth limit the wave functions?
    normalize_always = false;    # normalize wave functions after each slice?
    output_file = "out.nc";      # output file name
    tmp_dir = "/tmp/";           # directory for temporary files.
    output_compress = "false";   # compress output data. This reduces file sizes, but increases IO times.
}

simulation.title

string [default: ``]

The title of the simulation, as saved in the output NC file.

simulation.bandwidth_limiting

boolean [default: `true`]

Enforce cylindrical symmetry on all wave functions/operations. This results in all wave functions to be clipped significantly in momentum space. However, the benefit of reduced artefacts due to periodic boundary conditions is usually more important.

simulation.normalize_always

boolean [default: `false`]

Renormalize the electronic wave function after each slice of the multi-slice approximation, so that lost intensitiy due to limited k space grid is compensated for. Usually, this is not necessary, so the default is false.

simulation.output_file

string [default: ``]

Path to the result NetCDF file. Please read Output file format to learn about its format. Relative paths are interpreted relative to the working directory of the simulation.

simulation.tmp_dir

string [default: `folder of ouput file`]

When MPI parallelized, all MPI processors will write their results to temporary binary files in this directory, and only at the end of each frozen lattice configuration, the results are merged. We recommend using a local directory here (local to each MPI processor) so that access is fast. By default, the directory of the output file is used, which typically is not local but on a network file system. This can have a profound effect when CBED results are collected, i.e., output becomes large.

simulation.output_compress

boolean [default: `false`]

The written output data can be compressed by HDF5. This obviously takes more I/O time, but reduces output file sizes.

`probe`¶

Parameters of the STEM probe.

probe: {
    c5 = 5e6;                    # Fifth order spherical aberrations coefficient. in nm
    cs = 2e3;                    # Third order spherical aberrations coefficient. in nm
    defocus = -2.0;              # defocus value in nm
    fwhm_defoci = 6.0;           # FWHM of the defocus distribution when simulating a defocus series for Cc.
    num_defoci = 1;              # number of the defoci when simulating a defocus series for Cc. Should be odd.
    astigmatism_ca = 0;          # Two-fold astigmatism. in nm
    astigmatism_angle = 0;       # Two-fold astigmatism angle. in mrad
    min_apert = 0.0;             # Minimum numerical aperture of the objective. in mrad
    max_apert = 24.0;            # Maximum numerical aperture of the objective. in mrad
    beam_energy = 200.0;         # Electron beam energy. in kV
    scan_density = 40;           # The sampling density for the electron probe scanning. in 1/nm
}

probe.c5

number (nm) [default: `5e7`]

Fifth order spherical aberrations coefficient.

probe.cs

number (nm) [default: `2e4`]

Third order spherical aberrations coefficient.

probe.defocus

number (nm) [default: `2.0`]

Probe defocus.

probe.fwhm_defoci

number (nm) [default: `6.0`]

STEMsalabim can calculate a defocus series to model chromatic aberrations. In that case, this parameter is the full-width-half-maximum of the normal distribution of defocus spread in nm.

probe.num_defoci

number [default: `1`]

STEMsalabim can calculate a defocus series to model chromatic aberrations. In that case, this parameter is the number of defoci calculated.

probe.astigmatism_ca

number (nm) [default: `0`]

Two-fold astigmatism.

probe.astigmatism_angle

number (mrad) [default: `0`]

Two-fold astigmatism angle.

probe.min_apert

number (mrad) [default: `0`]

Minimum numerical aperture of the objective.

probe.max_apert

number (mrad) [default: `24`]

Maximum numerical aperture of the objective.

probe.beam_energy

number (keV) [default: `200`]

Electron beam energy.

probe.scan_density

number (1/nm) [default: `40.0`]

The sampling density for the electron probe scanning. This number multiplied by the supercell size in \(x\) and: \(y\) direction gives the number of positions, i.e., scan points, that are simulated.

`specimen`¶

Settings for the specimen and potentials.

specimen: {
    max_potential_radius = 0.3;  # potential cut-off radius. in nm
    crystal_file = "input.xyz";  # xyz file with columns [Element, x, y, z, MSD]
}

specimen.max_potential_radius

number (nm) [default: `0.3`]

Distance, after which the atomic potentials are cut off during generation of the slices’ transmission functions.

specimen.crystal_file

string [default: ``]

Path to the file containing the atomic coordinates. Please see Crystal file format to learn about its format. Relative paths are interpreted relative to the working directory of the simulation.

`grating`¶

Settings that describe the multi-slice algorithm, i.e., the density of the discretization and the slice thickness.

grating: {
    density = 360.0;             # The density for the real space and fourier space grids. in 1/nm
    slice_thickness = 0.2715;    # Multi-slice slice thickness. in nm
}

grating.density

number (1/nm) [default: `360.0`]

The density for the real space and fourier space grids. This number multiplied by the supercell size in \(x\): and \(y\) direction gives the minimal number of sampling grid points for the calculation. The actual grid size used for the simulation may be bigger than that, as an efficient size for the fourier transforms is chosen. This also determines the maximum angle \(\alpha = k\lambda\) that is described by the \(k\)-space grids.

grating.slice_thickness

number (nm) [default: `0.2715`]

The thickness of the slices in the multi-slice algorithm.

`adf`¶

Settings for collection of ADF data.

adf: {
    enabled = true;              # enable calculation and collection of ADF intensities
    x = (0.0, 1.0);              # [min, max] where min and max are in relative units
    y = (0.0, 1.0);              # [min, max] where min and max are in relative units
    detector_min_angle = 1.0;    # inner detector angle in mrad
    detector_max_angle = 300.0;  # outer detector angle in mrad
    detector_num_angles = 300;   # number of bins of the ADF detector.
    detector_interval_exponent = 1.0;     # possibility to set non-linear detector bins.
    save_slices_every = 0;       # save only every n slices. 0 -> only the sample bottom is saved.
    average_configurations = true; # average the frozen phonon configurations in the output file
    average_defoci = true;       # average the defoci in the output file
}

adf.enabled

boolean [default: `true`]

Enable or disable calculation of ADF intensities completely.

adf.x

array [default: `[0.0,1.0]`]

The relative coordinates, between which the supercell is scanned by the electron probe. When [0.0, 1.0], the whole x width of the supercell is scanned.

adf.y

array [default: `[0.0,1.0]`]

The relative coordinates, between which the supercell is scanned by the electron probe. When [0.0, 1.0], the whole y width of the supercell is scanned.

adf.detector_min_angle

number (mrad) [default: `0.0`]

Inner ADF detector angle in mrad.

adf.detector_max_angle

number (mrad) [default: `300.0`]

Outer ADF detector angle in mrad.

adf.detector_num_angles

number [default: `301`]

Number of ADF detector angle bins.

adf.detector_interval_exponent

number [default: `1.0`]

A non-linear grid spacing of the detector grid can be chosen to increase the sampling at smaller angles. The ith grid point between \(\theta_{min}\) and \(\theta_{max}\) is calculated by \(\theta_i=\theta_{min}+(i/N)^p(\theta_{max}-\theta_{min})\), where p is the interval exponent and \(N\) is the number of grid points as given by detector.angles. When set to 1.0, the grid is linear.

Note

A fundamental lower limit for the grid spacing is given by the grating.density density. Finer sampling than the grating density will result in odd artefacts!

adf.save_slices_every

integer [default: `1`]

The ADF intensity is calculated and stored after every slice that is a multiple of this parameter. The default value of 1 results in every slice to be saved, higher numbers skip slices. The value 0 corresponds to the intensity only being saved after the last slice, i.e., at the sample bottom.

adf.average_configurations

boolean [default: `true`]

Whether or not to perform in-place averaging over frozen lattice configurations during writing to the output file.

adf.average_defoci

boolean [default: `true`]

Whether or not to perform in-place (weighted) averaging over defoci during writing to the output file.

`cbed`¶

Settings for collection of CBEDs.

Note

Storing CBEDs will increase the output file size drastically. Moreover, the information contained in the CBEDs may be redundant to the ADF data.

cbed: {
    enabled = true;                # enable calculation and collection of CBED intensities
    x = (0.0, 1.0);                # [min, max] where min and max are in relative units
    y = (0.0, 1.0);                # [min, max] where min and max are in relative units
    size = [128, 128];             # When provided, this parameter determines the size of CBEDs saved
                                   # to the output file. The CBEDs are resized using bilinear interpolation.
    save_slices_every = 0;         # save only every n slices. 0 -> only the sample bottom is saved.
    average_configurations = true; # average the frozen phonon configurations in the output file
    average_defoci = true;         # average the defoci in the output file
}

cbed.enabled

boolean [default: `false`]

Enable or disable calculation of CBED intensities completely.

cbed.x

array [default: `[0.0,1.0]`]

The relative x coordinates, between which CBED images are to be saved. When [0.0, 1.0], the whole y width of the supercell is scanned.

cbed.y

array [default: `[0.0,1.0]`]

The relative y coordinates, between which CBED images are to be saved. When [0.0, 1.0], the whole y width of the supercell is scanned.

cbed.size

array [default: `[0.0,0.0]`]

Width and height of the CBEDs. Saving CBEDs can become very disk-space intensive, especially when the k grids are huge (as required for big samples). When this parameter is given, one can choose the size of the CBEDs that are saved to the output file. The images are reduced using bilinear interpolation. The total intensity is preserved. Leave the parameter out or set any direction to 0 to use the original size.

cbed.save_slices_every

integer [default: `1`]

The STEM intensity is calculated and stored after every slice that is a multiple of this parameter. The default value of 1 results in every slice to be saved, higher numbers skip slices. The value 0 corresponds to the intensity only being saved after the last slice, i.e., at the sample bottom.

cbed.average_configurations

boolean [default: `true`]

Whether or not to perform in-place averaging over frozen lattice configurations during writing to the output file.

cbed.average_defoci

boolean [default: `true`]

Whether or not to perform in-place (weighted) averaging over defoci during writing to the output file.

`frozen_phonon`¶

Settings for the frozen_phonon algorithm to simulate TDS.

frozen_phonon: {
    enabled = true;              # enable or disable the frozen phonon feature
    number_configurations = 15;  # Number of frozen phonon configurations to calculate
    fixed_slicing = true;        # When this is true, the z coordinate is not varied during phonon vibrations.
}

frozen_phonon.enabled

boolean [default: `true`]

Whether diffuse thermal scattering via frozen phonon approximation should be enabled.

frozen_phonon.number_configurations

integer [default: `1`]

Number of frozen phonon configurations to calculate.

frozen_phonon.fixed_slicing

boolean [default: `true`]

When true, the z coordinates (beam direction) of the atoms is not varied, resulting in fixed slicing between subsequent frozen phonon configurations.

`plasmon_scattering`¶

Settings for the single plasmon scattering.

plasmon_scattering: {
    enabled = true;              # enable or disable the feature
    simple_mode = true;                # No energy resolution, only E = 0 and 0 < E < max_energy
    max_energy = 10;                   # max energy of the energy grid considered for plasmon energy transfer in eV
    energy_grid_density = 10;          # density of the energy grid in 1/eV
    mean_free_path = 120;              # mean free path of a plasmon in nm
    plasmon_energy = 16.7;             # plasmon energy in eV
    plasmon_fwhm = 3.7;                # plasmon energy FWHM in eV
}

plasmon_scattering.enabled

boolean [default: `false`]

Whether diffuse thermal scattering via frozen phonon approximation should be enabled.

plasmon_scattering.simple_mode

integer [default: `true`]

Number of frozen phonon configurations to calculate.

plasmon_scattering.max_energy

float (eV) [default: `10`]

Max energy of the plasmon energy grid

plasmon_scattering.energy_grid_density

float (1/eV) [default: `10`]

Density of the plasmon energy grid

plasmon_scattering.mean_free_path

float (nm) [default: `120`]

Mean free path of the plasmons in the material.

plasmon_scattering.plasmon_energy

float (eV) [default: `16.7`]

Characteristic energy of the material’s plasmons.

plasmon_scattering.plasmon_fwhm

float (eV) [default: `3.7`]

Full width half maximum of the plasmon peak of the spectrum.

Command line arguments¶

stemsalabim¶

–help, -h

flag

Display a help message with a brief description of available command line parameters.

–params, -p

string (required)

Path to the configuration file as explained above in Parameter files files.

–num-threads

integer [default: `1`]

Number of threads per MPI core. Note, that STEMsalabim will do nothing if only parallelized via threads and --num-threads=1, as thread 0 of the master MPI process does not participate in the calculation. See Hybrid Parallelization model for details.

–package-size

integer [default: `10`]

The number of tasks that are sent to an MPI process. This should scale with the number of threads each MPI process spawns. A good value is \(10 \times\) the value of –num_threads.

–tmp-dir

string

Override the value of the output.tmp_dir setting.

–output-file, -o

string

Override the value of the output.output_file setting.

–crystal-file, -c

string

Override the value of the specimen.crystal_file setting.

ssb-mkin¶

–help, -h

flag

Display a help message with a brief description of available command line parameters.

–params, -p

string (required)

Path to the configuration file as explained above in Parameter files files.

–num-threads

integer [default: `1`]

Number of threads per MPI core. Note, that STEMsalabim will do nothing if only parallelized via threads and --num-threads=1, as thread 0 of the master MPI process does not participate in the calculation. See Hybrid Parallelization model for details.

–output-file, -o

string

Override the value of the output.output_file setting.

–crystal-file, -c

string

Override the value of the specimen.crystal_file setting.

–stored-potentials

flag

When set, ssb-mkin calculates the slice coulomb potentials and stores them in the output file. When ssb-run is also called with --stored-potentials, the potentials are read from the file instead of being recalculated.

ssb-run¶

–help, -h

flag

Display a help message with a brief description of available command line parameters.

–params, -p

string (required)

Path to the configuration file as explained above in Parameter files files.

–num-threads

integer [default: `1`]

Number of threads per MPI core. Note, that STEMsalabim will do nothing if only parallelized via threads and --num-threads=1, as thread 0 of the master MPI process does not participate in the calculation. See Hybrid Parallelization model for details.

–package-size

integer [default: `10`]

The number of tasks that are sent to an MPI process. This should scale with the number of threads each MPI process spawns. A good value is \(10 \times\) the value of –num_threads.

–tmp-dir

string

Override the value of the output.tmp_dir setting.

–output-file, -o

string

Override the value of the output.output_file setting.

–stored-potentials

flag

When set, ssb-run reads the slice coulomb potentials from the input NetCDF file. They must have been calculated via ssb-mkin --stored-potentials ....

Simulation Parameters¶

Parameter files¶

application¶

simulation¶

probe¶

specimen¶

grating¶

adf¶

cbed¶

frozen_phonon¶

plasmon_scattering¶

Command line arguments¶

stemsalabim¶

ssb-mkin¶

ssb-run¶

`application`¶

`simulation`¶

`probe`¶

`specimen`¶

`grating`¶

`adf`¶

`cbed`¶

`frozen_phonon`¶

`plasmon_scattering`¶