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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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