File formats

A STEMsalabim simulation is set-up via input files and its results are stored in an output file. The file for configuring a simulation is described in detail at Parameter files. Here, we describe the format of the crystal file, i.e., the atomic information about the specimen, and the output file, in which the results are stored.

Crystal file format

The crystal file is expected to be in XYZ format.

  1. The first line contains the number of atoms.

  2. The second line contains the cell dimension in x,y,z direction as floating point numbers in units of nm, separated by a space. Optionally, it can contain the x, y, z dimensions in the .exyz format:

    Lattice="lx 0.0 0.0 0.0 ly 0.0 0.0 0.0 lz"
    
  3. The atomic information is given from the third line onwards, with each line corresponding to a single atom. Each line must have exactly 5 columns:

    • The atomic species as elemental abbreviation (e.g., Ga for gallium)
    • the x,y,z coordinates as floating point numbers in units of nm
    • the mean square displacement for the frozen lattice dislocations in units of \(nm^2\).
    • (optional) The id of the slice this atom belongs to. This can be used to do custom slicing.

Below is a very brief, artificial example (without custom slicing):

5
1.0 2.0 10.0
Ga  0.0  0.0   0.0   1e-5
P   0.2  0.1   0.0   2e-5
Ga  0.0  0.0   1.0   1e-5
P   1.2  0.1   0.0   2e-5
O   1.0  2.0  10.0   0.0

Note

Atomic coordinates outside of the cell are periodically wrapped in x and y and clipped to the simulation box in z direction!

Output file format

All results of a STEMsalabim simulation are written to a binary NetCDF file. The NetCDF format is based on the Hierarchical Data Format and there are libraries to read the data for many programming languages.

The structure of NetCDF files can be inspected using the handy tool ncdump -h YOUR_FILE.nc (don’t forget the -h parameter, otherwise the whole content of the file is dumped!). Here is the output of an example run:

netcdf out {

group: AMBER {
  dimensions:
    atom = 164140 ;
    elements = 1 ;
    spatial = 3 ;
    cell_spatial = 3 ;
    cell_angular = 3 ;
    label = 6 ;
    frame = 10 ;
    slices = 142 ;
    grid_x = 490 ;
    grid_y = 490 ;
  variables:
    char spatial(spatial) ;
    char cell_spatial(cell_spatial) ;
    char cell_angular(cell_angular, label) ;
    float coordinates(frame, atom, spatial) ;
        coordinates:unit = "nanometer" ;
    float lattice_coordinates(frame, atom, spatial) ;
    float cell_lengths(frame, cell_spatial) ;
        cell_lengths:unit = "nanometer" ;
    float cell_angles(frame, cell_angular) ;
        cell_angles:unit = "degree" ;
    float radius(frame, atom) ;
        radius:unit = "nanometer" ;
    float msd(frame, atom) ;
    int slice(frame, atom) ;
    float slice_coordinates(slices) ;
    short element(frame, atom) ;
    float system_lengths(cell_spatial) ;
    float system_angles(cell_spatial) ;
    char atom_types(elements, label) ;

  // group attributes:
        :Conventions = "AMBER" ;
        :ConventionVersion = "1.0" ;
        :program = "STEMsalabim" ;
        :programVersion = "5.0.0b" ;
        :title = "sim" ;
  } // group AMBER

group: runtime {

  // group attributes:
        :programVersionMajor = "5" ;
        :programVersionMinor = "0" ;
        :programVersionPatch = "0b" ;
        :gitCommit = "f1dcc606c9a78b12fc3afda9496f638992b591bf" ;
        :title = "sim" ;
        :UUID = "8dce768e-f1d6-4876-bb20-c301e3e323f8" ;
        :time_start = "2019-02-12 13:25:43" ;
        :time_stop = "2019-02-13 00:06:05" ;
  } // group runtime

group: params {
  dimensions:
    defocus = 1 ;
    plasmon_energies = 51 ;
  variables:
    float defocus(defocus) ;
    float defocus_weights(defocus) ;
    float plasmon_energies(plasmon_energies) ;

  // group attributes:
        :program_arguments = "--params=inp.cfg --num-threads=4 --tmp-dir=/local --output-file=out.nc" ;
        :config_file_contents = "..." ;

  group: application {

    // group attributes:
            :random_seed = 967613772U ;
    } // group application

  group: simulation {

    // group attributes:
            :title = "sim" ;
            :normalize_always = 0US ;
            :bandwidth_limiting = 1US ;
            :output_file = "out.nc" ;
            :output_compress = 0US ;
    } // group simulation

  group: probe {

    // group attributes:
            :c5 = 5000000. ;
            :cs = 2000. ;
            :astigmatism_ca = 0. ;
            :defocus = -0. ;
            :fwhm_defoci = 6. ;
            :num_defoci = 1U ;
            :astigmatism_angle = 0. ;
            :min_apert = 0. ;
            :max_apert = 15.07 ;
            :beam_energy = 200. ;
            :scan_density = 40. ;
    } // group probe

  group: specimen {

    // group attributes:
            :max_potential_radius = 0.3 ;
            :crystal_file = "Si_110_10x10x200_300K.xyz" ;
    } // group specimen

  group: grating {

    // group attributes:
            :density = 90. ;
            :nx = 490U ;
            :ny = 490U ;
            :slice_thickness = 0.76806 ;
    } // group grating

  group: adf {

    // group attributes:
            :enabled = 1US ;
            :x = 0.5, 0.6 ;
            :y = 0.5, 0.6 ;
            :detector_min_angle = 0. ;
            :detector_max_angle = 150. ;
            :detector_num_angles = 151U ;
            :detector_interval_exponent = 1.f ;
            :average_configurations = 1US ;
            :average_defoci = 1US ;
            :save_slices_every = 10U ;
    } // group adf

  group: cbed {

    // group attributes:
            :enabled = 1US ;
            :x = 0.5, 0.6 ;
            :y = 0.5, 0.6 ;
            :size = 0U, 0U ;
            :average_configurations = 1US ;
            :average_defoci = 0US ;
            :save_slices_every = 101U ;
    } // group cbed

  group: frozen_phonon {

    // group attributes:
            :number_configurations = 10U ;
            :fixed_slicing = 1US ;
            :enabled = 1US ;
    } // group frozen_phonon

  group: plasmon_scattering {

    // group attributes:
            :enabled = 1US ;
            :simple_mode = 0US ;
            :plural_scattering = 0US ;
            :max_energy = 25.f ;
            :energy_grid_density = 2.f ;
            :mean_free_path = 128.f ;
            :plasmon_energy = 16.9f ;
            :plasmon_fwhm = 4.f ;
    } // group plasmon_scattering
  } // group params

group: adf {
  dimensions:
    adf_position_x = 22 ;
    adf_position_y = 22 ;
    adf_detector_angle = 151 ;
    adf_defocus = 1 ;
    adf_phonon = 1 ;
    adf_slice = 15 ;
    coordinate_dim = 2 ;
    adf_plasmon_energies = 51 ;
  variables:
    float adf_intensities(adf_defocus, adf_position_x, adf_position_y, adf_phonon, adf_slice, adf_plasmon_energies, adf_detector_angle) ;
    float center_of_mass(adf_defocus, adf_position_x, adf_position_y, adf_phonon, adf_slice, adf_plasmon_energies, coordinate_dim) ;
    double adf_probe_x_grid(adf_position_x) ;
    double adf_probe_y_grid(adf_position_y) ;
    double adf_detector_grid(adf_detector_angle) ;
    double adf_slice_coords(adf_slice) ;
  } // group adf

group: cbed {
  dimensions:
    cbed_position_x = 22 ;
    cbed_position_y = 22 ;
    cbed_k_x = 327 ;
    cbed_k_y = 327 ;
    cbed_defocus = 1 ;
    cbed_phonon = 1 ;
    cbed_slice = 2 ;
    cbed_plasmon_energies = 51 ;
  variables:
    float cbed_intensities(cbed_defocus, cbed_position_x, cbed_position_y, cbed_phonon, cbed_slice, cbed_plasmon_energies, cbed_k_x, cbed_k_y) ;
    double cbed_probe_x_grid(cbed_position_x) ;
    double cbed_probe_y_grid(cbed_position_y) ;
    double cbed_x_grid(cbed_k_x) ;
    double cbed_y_grid(cbed_k_y) ;
    double cbed_slice_coords(cbed_slice) ;
  } // group cbed
}

The structure of NetCDF files is hierarchical and organized in groups. The following groups are written by STEMsalabim:

AMBER

This group contains the atomic coordinates, species, displacements, radii, etc. for the complete crystal for each single calculated frozen lattice configuration, as well as for each calculated defocus value. The AMBER group content is compatible with the AMBER specifications. A STEMsalabim NetCDF file can be opened seamlessly with the Ovito crystal viewer.

Attributes  
Conventions String “AMBER” (required for AMBER)
ConventionVersion Version of the AMBER spec.
program Program name (“STEMsalabim”)
programVersion STEMsalabim’s version
title Simulation title (Param simulation.title)
Dimensions  
atom Number of atoms
elements Number of different elements
spatial Number of spatial dimensions (3)
cell_spatial Number of spatial dimensions (3)
cell_angular Number of spatial dimensions (3)
label Character String for element names (6)
frame Number of frozen phonon configurations * number of defoci
slices Number of slices in the multi-slice approximation
grid_x Number of simulation grid points in x direction
grid_y Number of simulation grid points in y direction
Variables  
spatial Names of the spatial dimensions (“x,y,z”)
cell_spatial Names of the spatial cell parameters (“a,b,c”)
cell_angular Names of the cell angles (“alpha,beta,gamma”)
coordinates Coordinates of the atoms [nm]
lattice_coordinates Equilibrium coordinates of the atoms (i.e. lattice positions without displacements) [nm]
cell_lengths Cell lengths (Same for each frame) [nm]
cell_angles Cell angles (Same for each frame, always “90, 90, 90”) [degree]
radius Radii of each atom [nm]
msd Mean square displacement of each atom [nm^2]
slice Slice id of each atom
slice_coordinates z-Coordinate of each slice [nm]
element Element id of each atom (see atom_types)
system_lengths Cell lengths [nm]
system_angles Cell angles [degree]
atom_types Description of atom types

runtime

Attributes  
programVersionMajor Major version of STEMsalabim
programVersionMinor Minor version of STEMsalabim
programVersionPatch Patch version of STEMsalabim
gitCommit Commit hash of the git commit of STEMsalabim
title Simulation title (Param simulation.title)
UUID Automatically generated universally unique identifier of this run.
time_start Start time of the simulation run
time_stop Finish time of the simulation run

params

Note

The params group contains subgroups with attributes that correspond exactly to the simulation parameters as written, except

  • /params/application/random_seed is set to the generated random seed
  • /params/grating/nx and /params/grating/ny contain the simulation grid size used.
Attributes  
program_arguments CLI arguments of this run
config_file_contents Contents of the parameter file of this run.
Dimensions  
defocus Number of defocus (param probe.num_defoci)
Variables  
defocus The values of the defoci of the defocus series
defocus_weights The weights for defocus averaging corresponding to each defocus

adf

Dimensions  
adf_position_x Number of probe positions in x direction
adf_position_y Number of probe positions in y direction
adf_detector_angle Number of stored detector angle bins
adf_defocus Number of stored defoci (1 when averaged over defoci)
adf_phonon Number of stored frozen phonon configuration (1 when averaged over configurations)
adf_slice Number of stored slices
coordinate_dim x,y coordinate dimension (2)
Variables  
adf_intensities ADF intensities of each pixel [fraction of beam]
center_of_mass Center of mass of each pixel [mrad]
adf_probe_x_grid Position vector of the probe in x direction [nm]
adf_probe_y_grid Position vector of the probe in y direction [nm]
adf_detector_grid Lower angles of the detector bins [mrad]
adf_slice_coords Coordinates of the stored slices [nm]

cbed

Dimensions  
cbed_position_x Number of probe positions in x direction
cbed_position_y Number of probe positions in y direction
cbed_k_x Number of k grid in k_x direction
cbed_k_y Number of k grid in k_y direction
cbed_defocus Number of stored defoci (1 when averaged over defoci)
cbed_phonon Number of stored frozen phonon configuration (1 when averaged over configurations)
cbed_slice Number of stored slices
Variables  
cbed_intensities cbed intensities of each pixel [fraction of beam]
cbed_probe_x_grid Position vector of the probe in x direction [nm]
cbed_probe_y_grid Position vector of the probe in y direction [nm]
cbed_x_grid Angles of k_x grid [mrad]
cbed_y_grid Angles of k_y grid [mrad]
cbed_slice_coords Coordinates of the stored slices [nm]

Reading NC Files

For a detailed view of the structure, we suggest using the ncdump utility: ncdump -h some_results_file.nc. As the underlying file format of NetCDF is HDF5, you may use any other HDF5 viewer to have a look at the results.

There are NetCDF bindings for most popular programming languages.

  1. In MATLAB, we recommend using h5read() and the other HDF5 functions.
  2. For Python, use the netCDF4 module.