Running Simulations

After completing the Installation of the package, you shoud have access to several high level functions to run and analyze RSA simulations. A complete lists of high level functions is shown in the Exported Functions section.

To start RSA simulations only two inputs, namely the number of simulations you want to perform and the path to the input file, are needed:

NRuns = 1000
inputfile_path = "/home/fabian/Sync/Coding/Julia/Scripts/lattice.inp"
rsa_results, Nmolecules, molecules, Ngrids, grids, lattice, events = perform_multiple_rsa_runs(NRuns, inputfile_path)

As a result you will obtain all information found in the input file (Nmolecules, molecules, Ngrids, grids, lattice, events), as well as all results of the rsa simulations (rsa_results). Details on the obtained objects are explained in the Exported Functions section as well as the Datastructure section.

For simple analysis tasks, the obtained objects are simply passed to another function:

myplot = plot_RSA_run(rsa_results[352].status, Ngrids, grids, Nmolecules, molecules, lattice)
savefig(myplot, "RSA_run_352.png")

Default functions for plotting RSA runs, evaluating the covered area, and calculating the effective gap size are provided in the Analysis section.

Exported Functions

RSA Runs

RSA.perform_multiple_rsa_runs — Function

perform_multiple_rsa_runs(NRuns::Integer, inputfile_path::String)
perform_multiple_rsa_runs(NRuns::Integer, inputfile_path::String; hdf5::Bool = false)

Performs NRuns RSA simulations controlled by the input file found under the given path inputfile_path.

Optional input

hdf5: Flag to request the generation of a HDF5 file storing all information.

Return values

Returns input information and results as structs in the follwing order:

rsa_results: Vector storing all results of the RSA simulations. Every vector entry is a rsa_run_results_struct struct containing all information for a single RSA run.
Nmolecules: Total number of molecule types used.
molecules: Vector storing all information concerning the molecule types. Every vector entry is a molecule_struct struct containing all information for a single molecule type.
Ngrids: Total number of grid types used.
grids: Vector storing all information concerning the grid types. Every vector entry is a grid_struct struct containing all information for a single grid type.
lattice: A lattice_struct containing all information of the used lattice.
events: A events_struct containing all information of the events and general RSA settings.

source

RSA.read_hdf5_output_file — Function

read_hdf5_output_file(hdf5_file::String, generation::Int64)

Reads and returns all information of RSA simulations within a generation from a HDF5 file found under the given path hdf5_file.

Return values

Returns input information and results as structs in the follwing order:

rsa_results: Vector storing all results of the RSA simulations. Every vector entry is a rsa_run_results_struct struct containing all information for a single RSA run.
Nmolecules: Total number of molecule types used.
molecules: Vector storing all information concerning the molecule types. Every vector entry is a molecule_struct struct containing all information for a single molecule type.
Ngrids: Total number of grid types used.
grids: Vector storing all information concerning the grid types. Every vector entry is a grid_struct struct containing all information for a single grid type.
lattice: A lattice_struct containing all information of the used lattice.
events: A events_struct containing all information of the events and general RSA settings.

source

Analysis

RSA.plot_RSA_run — Function

plot_RSA_run(status, Ngrids, grids, Nmolecules, molecules, lattice)
plot_RSA_run(status, Ngrids, grids, Nmolecules, molecules, lattice; pixel_per_angstrom = 10.0, boundary_cells = 1, silent=true, gridplot = nothing, withmargins = false)

Create an image of the surface covered by adsorbates.

Input

status: A status field of a rsa_run_results_struct object.
Ngrids: Integer number of present grid types.
grids: A grid_struct object.
Nmolecules: Integer number of present molecule types.
molecules: A molecule_struct object.
lattice: A lattice_struct object.

Optional input

pixel_per_angstrom: Resolution of the image controlled by the number of pixels for a distance of 1 angstrom as floating point number.
boundary_cells: Integer number of boundary cells used to plot periodic boundary conditions.
silent: Bool flag to request additional output statements.
gridplot: A prepared plot of the grid points to prevent the repeated generation of an identical background.
withmargins: Flag to add a default white space around the simulation cell. By default no white space is added.

Return values

A plots object of the covered surface.

source

RSA.plot_single_molecule — Function

plot_single_molecule(molecule_id, Nmolecules, molecules)
plot_single_molecule(molecule_id, Nmolecules, molecules; pixel_per_angstrom = 10.0)

Create an image of a single adsorbate.

Input

molecule_id: Number of the molecule in the molecules vector to be used.
Nmolecules: Number of present molecule types.
molecules: A molecule_struct object.

Optional input

pixel_per_angstrom: Resolution of the image controlled by the number of pixels for a distance of 1 angstrom.

Return values

A plots object of the adsorbate.

source

RSA.animate_RSA_run — Function

animate_RSA_run(stepinfo, Ngrids, grids, Nmolecules, molecules, lattice)
animate_RSA_run(stepinfo, Ngrids, grids, Nmolecules, molecules, lattice; pixel_per_angstrom = 10.0, boundary_cells = 1, startstep = 1, laststep = 0, withmargins = false)

Create an animation of a RSA simulation.

Input

stepinfo: A stepinfo field of a rsarunresults_struct.
Ngrids: Number of present grid types.
grids: A grid_struct object.
Nmolecules: Number of present molecule types.
molecules: A molecule_struct object.
lattice: A lattice_struct object.

Optional input

pixel_per_angstrom: Resolution of the image controlled by the number of pixels for a distance of 1 angstrom.
boundary_cells: Number of boundary cells used to plot periodic boundary conditions.
startstep: First RSA step shown by the animation.
laststep: Last RSA step shown by the animation. A value of zero (default) requests all steps of the given stepinfo.
withmargins: Flag to add a default white space around the simulation cell. By default no white space is added.

Return values

A plots object containing the animation of the RSA simulation.

Hints

Generation of large animations is extremely slow.
Only reasonable to use for the a few thousand steps.

source

RSA.plot_count_area_histograms — Function

plot_count_area_histograms(Nruns, rsa_results, Nmolecules, molecules, lattice)
plot_count_area_histograms(Nruns, rsa_results, Nmolecules, molecules, lattice; status = true, plotonly = true, count = 1.0, area = 1.0, normalized = false)

Create histograms counting the number of adsorbed molecules and the covered area. For every molecule type each histogram is generated. In addition, a final set of histograms is generated for all molecule types combined.

Input

Nruns: Total number of RSA simulations.
rsa_results: A rsarunresults_struct object.
Nmolecules: Number of present molecule types.
molecules: A molecule_struct object.
lattice: A lattice_struct object.

Optional input

status: Flag forcing the recalculation of the status based on the stepinfo field.
plotonly: Flag to request additional metrics.
count: Bin size for histogram showing molecule counts.
area: Bin size for histograms showing covered area.
normalized: Flag to normalize the histogram with Plots internals.

Return values

plotonly = true (default): A vector of histograms is returned. Count and covered surface is contained pairwise for every molecule type while the second last element contains the total adsorbate count and the last element the total covered area.
plotonly = false: In addition to the histogram vector, vectors storing the mean values, standarddeviation, min and max values, as well as the simulation closest to the mean value are returned. In the following order: histograms, means, standarddeviations, minvalues, minvalueids, maxvalues, maxvalueids, averagevalues, averagevalue_ids.

source

RSA.plot_effective_gap_size — Function

plot_effective_gap_size(status, Ngrids, grids, Nmolecules, molecules, lattice)
plot_effective_gap_size(status, Ngrids, grids, Nmolecules, molecules, lattice; pixel_per_angstrom = 10.0, gapsonly = false, withstroke = true, plotonly = true, normalized = false, withmargins = false)

Create an image of the effective gap sizes as well as the histogram showing the frequency of all gap sizes.

Input

status: A status field of a rsarunresults_struct.
Ngrids: Number of present grid types.
grids: A grid_struct object.
Nmolecules: Number of present molecule types.
molecules: A molecule_struct object.
lattice: A lattice_struct object.

Optional input

pixel_per_angstrom: Resolution of the image controlled by the number of pixels for a distance of 1 angstrom.
gapsonly: Flag to request a visualization of only the gaps (removing all adsorbates).
withstroke: Flag to add a stroke to the visualization of the gap sizes.
plotonly: Flag to request additional metrics.
normalized: Flag to normalize the histogram with Plots internals.
withmargins: Flag to add a default white space around the simulation cell. By default no white space is added.

Return values

plotonly = true (default): Returns the histogram showing the frequency of all gap sizes and a plots object for the visualization of the gaps in the following order: histogram, plot.
plotonly = false: In addition to the default case, a vector containing the obtained effective gap sizes as well as a vector of the corresponding free grid point are returned. Information are returned in the following order: histogram, plot, gap sizes, free grid points.

source

RSA.plot_count_area_convergence — Function

plot_count_area_convergence(Nruns, rsa_results, Nmolecules, molecules, lattice)
plot_count_area_convergence(Nruns, rsa_results, Nmolecules, molecules, lattice; status = true, plotonly = true, properties = ["means", "standarddeviations"], stride = 1, reference = true, resolution = 600)

Create plots showing the convergence of the metrics with the number of RSA simulations.

Input

Nruns: Total number of RSA simulations.
rsa_results: A rsarunresults_struct object.
Nmolecules: Number of present molecule types.
molecules: A molecule_struct object.
lattice: A lattice_struct object.

Optional input

status: Flag forcing the recalculation of the status based on the stepinfo field.
plotonly: Flag to request the plotted data in addition to the plots.
properties: Vector of the metrics to be plotted. Accepted values are "means", "standarddeviations", "minvalues", "minvalue_ids", "maxvalues", "maxvalue_ids", "avgvalues", and "avgvalue_ids".
stride: Number of runs added between two evaluations of the metrics. The final evaluation always includes all runs.
reference: Flag to add the value obtained with all RSA runs as a dashed horizontal line.
resolution: Resolution of the images controlled by the dpi value.

Return values

plotonly = true (default): A matrix of plots. First index indicates the plotted molecule (area or count) while second index follows the order of the requested properties.
plotonly = false: In addition to the matrix of plots, the vector of the evaluated numbers of runs and the plotted values are returned. The values are given as a vector over the data sets, with every element being a matrix of the evaluated numbers of runs in rows and the requested properties in columns. Information are returned in the following order: plots, numbers of runs, values.

source

RSA.plot_single_run_convergence — Function

plot_single_run_convergence(stepinfo, Nmolecules, molecules, lattice)
plot_single_run_convergence(stepinfo, Nmolecules, molecules, lattice; errorrange = 0.0, startstep = 1, laststep = 0, plotonly = true, resolution = 600)

Create a plot showing the convergence of adsorbate count and covered area of a single RSA simulation with the number of performed RSA steps.

Input

stepinfo: A stepinfo field of a rsarunresults_struct.
Nmolecules: Number of present molecule types.
molecules: A molecule_struct object.
lattice: A lattice_struct object.

Optional input

errorrange: Range in % which is added to and subtracted from the final value of every property. The resulting range is highlighted within the plot. A value of zero (default) requests no range.
startstep: First RSA step shown by the plot.
laststep: Last RSA step shown by the plot. A value of zero (default) requests all steps of the given stepinfo.
plotonly: Flag to request the plotted data in addition to the plot.
resolution: Resolution of the image controlled by the dpi value.

Return values

plotonly = true (default): A vector containing the plots for each adsorbate and all adsorbates together.
plotonly = false: In addition to the plots, a vector containing the ploted data as well as a vector stating at which step convergence is reached are returned.

source

Datastructure

RSA.rsa_run_results_struct — Type

Mutable struct to store all results of multiple RSA runs.

Fields

randomseed: Vector storing the random number of every step.
status: Matrix storing the currently adsorbed molecules in columns (molecule type, grid type, gridpoint, rotation).
Nsteps: Number of performed RSA steps.
Nevents: Matrix (molecule type, grid type) counting the number of performed events. Every element is a vector counting the event types (ads, rot, dif, con).
stepinfo: Matrix storing information for every RSA step in columns (Total number of possible events, Number of possible ads/rot/dif/con events, selected grid type, selected gridpoint, selected molecule type, selected event type, selected subevent, selected event, selected subevent).
seed_offset: Number stating the entries in the status & stepinfo matrix obtained by initializing the surface within a restart run

Technical fields

size: Current size of internal matrices.

source

RSA.molecule_struct — Type

Mutable struct to store all information concerning one molecule.

General fields

label: Label of the molecule.
grids: Vector storing all possible grids the molecule can reach.

Fixpoint fields

fixpointtype: Keyword defining the type of the used fixpoint.
fixpointatoms: Vector storing the atoms used for the fixpoint.
fixpoint: Vector storing the fixpoint.

Rotation fields

rotationmodus: Keyword selecting how rotations are generated.
rotationangle: Value of rotation angle to generate all rotations.
rotationvalues: Vector storing all explicit values to generate rotations.
Nrotations: Total number of rotations.
rotations: Vector storing the finally used rotation values.

Structural fields

coordinate_path: Path to the xyz coordinate file.
Natoms: Total number of atoms.
elements: Vector containing the elements of each atom.
elements_sorted: Element vector sorted based on the distance to the fixpoint.
dimension: Dimension of the given coordinates.
coordinates: Matrix storing the initial xyz coordinates.
coordinates_sorted: Coordinates sorted based on the distance to the fixpoint.
coordinates_rotated: Vector of matrices storing all rotated structures.
maxradius: Largest distance to the fixpoint including vdW radius of the atom.
radii: Distance to the fixpoint of every atom.
radii_sorted: Sorted distance to the fixpoint of every atom.

source

RSA.grid_struct — Type

Mutable struct to store all information concerning one grid.

General fields

label: Label of the grid.

Structural fields

Nuniquepoints: Number of uniques points within the unit cell.
uniquepoints: Matrix storing the coordinates of the unique points.
dimension: Dimension of the coordinates.
Npoints: Total number of points in the supercell.
points: Matrix storing the coordinates of all grid points.
mapping: Matrix storing the mapping (unique point, x translation, y translation) of every grid point.

source

RSA.lattice_struct — Type

Mutable struct to store all information concerning the lattice.

Structural fields

cellvectors: Vectors spanning the unit cell. One vector per column.
dimension: Dimension of the vectors.

Translation fields

transx: Number of translations along the first vector.
transy: Number of translations along the second vector.
Ncellx: Total number of cells along the first vector (is equal to transx + 1).
Ncelly: Total number of cells along the second vector (is equal to transy + 1).
transcellvectors: Lattice vectors of the supercell.
inversecellvectors: Inverse lattice vectors of the supercell.

source

RSA.events_struct — Type

Mutable struct to store all information concerning the events and general RSA settings.

General fields

steps: Maximum number of steps to be performed in a RSA simulation.
break_steps: Boolean to flag whether the max steps keyword is used.
coverage_convergence: Maximum number of steps without adsorption for coverage convergence.
break_convergence: Boolean to flag whether the coverage convergence keyword is used.
Nforce_adsorption: Number of non-adsorption steps after which an adsorption event is forced.
force_adsorption: Boolean to flag whether the forced adsorption keyword is used.
overlap2d: Boolean to flag whether 2D overlap is used.
overlap3d: Boolean to flag whether 3D overlap is used.

Restart fields

restart_flag: Boolean to flag whether this is a restart run.
restart_generation: Generation number of RSA runs the restart is based on.
restart_runs: Vector storing the run numbers of RSA runs used in the restart.
restart_file: Path to the restart hdf5 file.

Event fields

Nevents: Total number of defined events.
Nadsorptions: Number of defined adsorption events.
adsorptions: Vector storing the adsorption events.
Ndiffusions: Number of defined diffusion events.
diffusions: Vector storing the diffusion events.
Nrotations: Number of defined rotation events.
rotations: Vector storing the rotation events.
Nconformers: Number of defined conformer or conversion events.
conformers: Vector storing the conversion events.

source