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, timings = 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), the timings of the individual steps (timings), 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.

Using Multithreading with VSCode

Running RSA simulations over VSCode in parallel is possible by changing the "julia.NumThreads" setting. Simply search for "num thread" in the settings searchbar and change to your needs. To test the new settings use the following command in your notebook:

Threads.nthreads()

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.
timings: A timings_struct containing some timing information.

source

RSA.read_hdf5_output_file — Function

read_hdf5_output_file(hdf5_file::String)

Reads and returns all information of RSA simulations 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.
timings: A timings_struct containing some timing information.

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)

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.

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)

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.

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 initial ~1000 steps (with stepinfo[:,1:1000]).

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)

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.

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, variance, min and max values, as well as the simulation closest to the mean value are returned. In the following order: histograms, means, variances, 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)

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.

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

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).

Technical fields

stepsize: Factor to increase internal matrices.
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

vectors: Vector spanning the unit cell.
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).
transvectors: Lattice vectors of the supercell.
inversevectors: 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.

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

RSA.timings_struct — Type

Mutable struct to store all timings of multiple RSA runs.

Fields

Processing_Input: Time for reading and processing input files.
Calculation_gridpoint_distance: Time for calculating distances between all grid points.
Calculation_translation_distances: Time for calculating all translation distances.
Calculation_rotation_distances: Time for calculating distances between all rotations.
Calculation_affected_points: Time used to find all affected points for every event.
Calculation_overlap: Time used to judge the overlap of two molecules (also included in previous timing).
Calculation_rateconstants: Time used to rearrange weigths of the events.
Calculation_neighbour_list: Time to calculate a neighbour list for every grid point.
RSA_runs: Time spend in RSA runs.

source