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. This random seed is also used for the generation of the positions of the plasmon scattering function.

`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.
    chunking_enabled = "true";          # chunk the stored data.
    save_probe_wavefunction = "false"   # save the probe wavefunction at each scan point
}

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.

simulation.chunking_enabled

boolean [default: `true`]

The written output data is chunked by default. If the output gets too big, especially when CBEDs are enabled, errors can occur. These can be prevented by switching the chunking off.

simulation.save_probe_wavefunction

boolean [default: `false`]

This switch allows to save the probe wave function at each scan point. This may slow down the simulation because of the IO operations for each pixel by possibly different threads and MPI processes. The wavefunctions are stored in text files as complex numbers.

`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 = 0;                        # defocus value in nm
    delta_defocus_max = 6.0;            # The maximum value which will be added/subtracted to/from the mean defocus value to determine the defoci to use for defocus series for Cc. in nm
    fwhm_defocus_distribution = 7.5     # Full width at half maximum of the Gaussian which determines the defocus weigths for defocus series for Cc. in nm
    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
    aperture_bitmap_file = ""           # Path to file which gives values for aperture function
}

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: `0`]

Probe defocus.

probe.delta_defocus_max

number (nm) [default: `6.0`]

STEMsalabim can calculate a defocus series to model chromatic aberrations. In that case, this parameter is the maximum value which will be added/subtracted to/from the mean defocus value to determine the defoci to use for defocus series for Cc. e.g. the ensemble (probe.defocus = 0, probe.delta_defocus_max = 12, probe.num_defoci = 7) would give the defoci [-12, -8, -4, 0, 4, 8, 12].

probe.fwhm_defocus_distribution

number (nm) [default: `7.5`]

STEMsalabim can calculate a defocus series to model chromatic aberrations. In that case, this parameter is the full width at half maximum of the Gaussian which determines the defocus weigths. It comes from equation (2) in [Beyer, A., et al., Journal of microscopy 262.2 (2016): 171-177., https://onlinelibrary.wiley.com/doi/10.1111/jmi.12284]. The default value of 7.5 is “for the JEOL JEM-2200 FS microscope with a CC of 1.5 mm and a dE of 0.42 eV follows a [fwhm_defocus_distribution] of 7.5 nm at 200 kV acceleration voltage “

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.

probe.aperture_bitmap_file

string [default: `””`]

Path to a text file containing values for the aperture function. It is assumed that the file has a number of columns and rows equal to the grid size in x and y direction, respectively. The values from the file will overwrite what usually would be determined by min_apert and max_apert.

`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
    max_angle = 0;                 # Maximum angle up to which CBEDs are saved
}

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.

cbed.max_angle

double [default: 0.0] Maximum angle up to which CBEDs are save. When max_angle > 0, then the CBED will only be stored up to this value. This will overwrite the other CBED-size settings bandwidth limiting and resizing.

`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
    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
    plasmons_scatteringfunction_cutoff = 3;     # radial cutoff of the plasmon scattering function. in nm
    number_of_potential_positionsPerSlice = 0;  # the number of the positions to which the plasmon scattering function is translated
    calculate_plasmons_in_all_slices = true;    # calculate plasmon scattering in all slices?
}

plasmon_scattering.enabled

boolean [default: `false`]

Whether to enable plasmon scattering.

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.

plasmons_scatteringfunction_cutoff

[default: `3`] The radial cutoff of the plasmon scattering function.

number_of_potential_positionsPerSlice

[default: `0`] The number of the random positions, to which the plasmon scattering function is translated.

calculate_plasmons_in_all_slices

[default: ``] Choose if plasmon scattering will be calculated in all slices, or just in the last one, i.e. at the full specimen thickness.

`specimen tilt`¶

Settings for specimen tilt.

specimen_tilt: {
    enabled = false;                        # enable specimen tilt
    specimen_tilt_angle_x = 0;                  # tilt angle in x direction in mrad
    specimen_tilt_angle_y = 0;                  # tilt angle in y direction in mrad
    adjust_slice_thickness = false;         # whether to adjust the slice thickness
}

specimen_tilt.enabled

boolean [default: `false`]

Whether to enable specimen tilt.

specimen_tilt.specimen_tilt_angle_x

float (eV) [default: `0`]

The tilt angle in x direction in mrad.

specimen_tilt.specimen_tilt_angle_y

float (eV) [default: `0`]

The tilt angle in y direction in mrad.

specimen_tilt.adjust_slice_thickness

boolean [default: `false`]

Whether to adjust the slice thickness to account for the different beam path for the propagating wave due to specimen tilt.

`beam tilt`¶

Settings for beam tilt.

beam_tilt: {
    enabled = false;                        # enable beam tilt
    beam_tilt_angle_x = 0;                  # tilt angle in x direction in mrad
    beam_tilt_angle_y = 0;                  # tilt angle in y direction in mrad
    adjust_slice_thickness = false;         # whether to adjust the slice thickness

}

beam_tilt.enabled

boolean [default: `false`]

Whether to enable beam tilt.

beam_tilt.beam_tilt_angle_x

float (eV) [default: `0`]

The tilt angle in x direction in mrad. The actually simulated will be slightly different, and is dependent on the grid in k space.

beam_tilt.beam_tilt_angle_y

float (eV) [default: `0`]

The tilt angle in x direction in mrad. The actually simulated will be slightly different, and is dependent on the grid in k space.

beam_tilt.adjust_slice_thickness

boolean [default: `false`]

Whether to adjust the slice thickness to account for the different beam path for the propagating wave due to beam tilt.

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 usual NetCDF output file or an external file, depending on whether or not --use-external-potential-file is set. When ssb-run is also called with --stored-potentials, the potentials are read from the file instead of being recalculated.

–use-external-potential-file

flag

If set to true and also --stored-potentials is set, slice coulomb potentials will be saved in the file given via --external-potential-file instead of saving them in the usual netcdf output file. If not set but --stored-potentials is set, the potentials will be stored in the usual netcdf output file.

–external-potential-file

string [default: stored_potentials.nc]

Path to the file which shall store the slice coulomb potentials.

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 a NetCDF file. They must have been calculated via ssb-mkin --stored-potentials .... Depending on whether or not --use-external-potential-file is set, the potentials are read from the usual NetCDF output file or another file.

–use-external-potential-file

flag

If set to true and also --stored-potentials is set, potentials from the file given via --external-potential-file will be used. If not set but --stored-potentials is set, it is assumed that the potentials are stored inside the usual NetCDF output file.

–external-potential-file

string [default: stored_potentials.nc]

Path to the file which stores the scattering potentials. This file can either be a NetCDF file which only holds the potentials, or the usual NetCDF output file which also stores the potentials.

Simulation Parameters¶

Parameter files¶

application¶

simulation¶

probe¶

specimen¶

grating¶

adf¶

cbed¶

frozen_phonon¶

plasmon_scattering¶

specimen tilt¶

beam tilt¶

Command line arguments¶

stemsalabim¶

ssb-mkin¶

ssb-run¶

`application`¶

`simulation`¶

`probe`¶

`specimen`¶

`grating`¶

`adf`¶

`cbed`¶

`frozen_phonon`¶

`plasmon_scattering`¶

`specimen tilt`¶

`beam tilt`¶