Developers

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

create_event_list!(occupation,event_list,event_possible)

This is the slowest implementation to create a list of possible events. Here, the occupation vector is used to find occupied states. This information is used to set all events in the event_possible vector to trueif theevent_list` vector is indicating that the event is starting from the occupied state.

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.

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.

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.

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.

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.

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.

time_progression(total_time::Float64, total_rate_constant::Float64)

Based on a random number r (in the range 0 to 1) and the total rate constant k the time t progression is calculated based on:

\[t_{old} = t_{new} - \frac{ln(1 - r)}{k}\]

Returning the value of $t_{old}$.

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.

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.

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.

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.

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.

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.