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
precision = "single"; # single or double precision
skip_simulation = false; # skip the actual multi-slice simulation (for debugging)
}
- 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.
- application.precision
string [default: `single`]
Set to
d
ordouble
orhigh
to use double precision for the calculation. Note, that this increases computer time, memory consumption, and output file size.- application.skip_simulation
boolean [default: `false`]
Do not carry out the actual multi-slice simulation, but only write the crystal information to the output file. This is for debugging purposes.
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
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.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.fwhm_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 number of sampling grid points for the calculation. 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 wholex
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 wholey
width of the supercell is scanned.- adf.detector_min_angle
number (mrad) [default: `1.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: `300`]
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 to1.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 value0
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 wholey
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 wholey
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 value0
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: {
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.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.
http_reporting
¶
Settings for HTTP reporting of simulation progress.
http_reporting: { # send POST status requests of the simulation to some HTTP endpoint.
reporting = true; # reporting can be disabled with this parameter.
url = "http://my_url"; # The URL to POST to.
auth_user = "my_user"; # username for HTTP basic auth
auth_pass = "my_pass"; # password for HTTP basic auth
parameters: { # All parameters in this http_reporting.parameters are sent as query.
# in addition to the status information. Use whatever your API needs.
my_login = "username";
my_token = "abcdef";
}
}
- http_reporting.reporting
boolean [default: `false`]
Should the simulation status be announced via HTTP POST requests? See HTTP Status reporting for details.
- http_reporting.url
string [default: ``]
The HTTP API endpoint for the status reporting. See HTTP Status reporting for details.
- http_reporting.auth_user
string [default: ``]
The username for HTTP Basic Authentication. Leave empty to not authenticate.
- http_reporting.auth_pass
string [default: ``]
The password for HTTP Basic Authentication.
- http_reporting.params
libConfig block [default: `{}`]
Additional parameters to include in the HTTP POST JSON requests. See HTTP Status reporting for details.
Command line arguments¶
- –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 thread0
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.
- –skip-simulation
flag
Override configuration parameter application.skip_simulation to true when this flag is set.
- –num-configurations
integer
Override configuration parameter frozen_phonon.number_configurations.
- –defocus, -d
float
Override the value of the probe.defocus setting. If specified exactly once, a single defocus is calculated. If specified exactly three times, the functionality is similar to the probe.defocus parameter.
- –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.
- –title, -t
string
Override the value of the simulation.title setting.