adsorpy.run_simulation module

Runs the simulation.

run_simulation() should provide the user with customisability. Molecules can be generated from .xyz using molecule_lib. The config.json can be found in the adsorpy folder as well.

adsorpy.run_simulation.run_simulation(rsa_config=None, molecules_list=None, rotation_symmetries=None, reflection_symmetries=None, rotation_counts=None, lattice_type='triangular', site_count=None, lattice_a=None, boundary_condition=None, simulation_type='sequential', dosing_distribution=None, include_rejected_flux=False, calculate_gap_size=False, print_output_flag=False, plot_output_flag=False, seed=None, timestep_limit=1000000, site_x_coords=None, site_y_coords=None, bounding_x_coord=None, bounding_y_coord=None, sticking_probability=1.0)

Run the RSA simulation.

If no molecule is provided, defaults to a circular molecule of radius 0.55 Angstrom. Ensure that all lists are of equal length. If only one molecule is provided, adding it to a list is not needed. If the simulation_type is “codosing”, the dosing_distribution parameter is used, otherwise it is ignored.

Parameters:

• rsa_config (RsaConfig | None) – Input parameters defined in the config.

• molecules_list (Polygon | list[Polygon] | ndarray[tuple[int], dtype[Polygon]] | None) – List of molecules. Ensure this list is equal in length to the next three entries.

• rotation_symmetries (int | list[int] | ndarray[tuple[int], dtype[int_]] | None) – Rotation symmetries. 0 for circle, 1 for no symmetry, 2 twofold, 3 threefold, etc.

• reflection_symmetries (bool | list[bool] | ndarray[tuple[int], dtype[bool]] | None) – Mirror symmetries. True means mirror symmetry, False means no mirror symmetry.

• rotation_counts (int | list[int] | ndarray[tuple[int], dtype[int_]] | None) – Number of rotations to be considered. Preferably numbers that divide 360.

• lattice_type (str) – The lattice type. “triangular”, “honeycomb”, or “square”.

• site_count (int | None) – The site count along one axis. Optional. If None, defaults to the value in config.json.

• lattice_a (float | None) – The lattice spacing in Angstrom. If None, defaults to the value in config.json.

• boundary_condition (str | None) – The boundary condition. Optional, can be soft/hard/periodic. If None, defaults to config.

• simulation_type (str) – Type of simulation. Valid types are “sequential”, “codosing”, and “cascade”.

• dosing_distribution (list[float] | ndarray[tuple[int], dtype[double]] | None) – The distribution of the adsorption attempts in case of “codosing”. Uniform if None.

• include_rejected_flux (bool) – Whether to include rejected flux in the simulation. If True, sites can be reattempted.

• calculate_gap_size (bool) – Whether to calculate the gap size of the simulation.

• print_output_flag (bool) – Toggle printing output of simulation.

• plot_output_flag (bool) – Toggle plotting output of simulation.

• seed (int | Generator | None) – The seed for the simulation. If None, takes the datetime in microseconds: YYYMMDDhhmmssuuuuuu.

• timestep_limit (int) – The maximum number of timesteps to simulate for when the flux is taken into account.

• site_x_coords (ndarray[tuple[int], dtype[double]] | None) – x coordinates of the sites. If this and the next four arguments are provided, generate custom.

• site_y_coords (ndarray[tuple[int], dtype[double]] | None) – y coordinates of the sites. Custom surface overrides site_count and lattice_a.

• bounding_x_coord (float | None) – The bounding box x coordinate value. Only use for custom surface. Leave None otherwise.

• bounding_y_coord (float | None) – The bounding box y coordinate value. Ensure the previous three arguments are provided.

• sticking_probability (float | list[float] | ndarray[tuple[int], dtype[double]]) – The sticking probability. Default is 1.0 from config. Per molecule or for all.

Return type:

tuple[list[int], ndarray[tuple[int], dtype[double]], int | Generator, tuple[ndarray[tuple[int], dtype[int_]], ...], ndarray[tuple[int], dtype[int_]], Simulator]

Returns:

0. The molecule count on the surface per molecule group.

1. The gap size distribution.

2. The RNG seed or Generator.

3. The fluxes/doses as a tuple of lists of counts per stepcount of adsorption event.

4. The available surface function (ASF).

5. The Simulator class.

Raises:

TypeError – If the sticking probability is an invalid type.

adsorpy.run_simulation._run_sequential(sim, surf, molecules, time_count, timestep_limit)

adsorpy.run_simulation._run_codosing(sim, surf, molecules, time_count, timestep_limit, dosing_distribution=None)

adsorpy.run_simulation._run_cascade(sim, surf, molecules, time_count, timestep_limit)

adsorpy.run_simulation._run_flux(sim, surf, molecules, timestep_limit)

Adsorb while taking steps into account.

Parameters:

• sim (Simulator) – Simulator.

• surf (Surface) – Surface.

• molecules (list[MoleculeGroup]) – MoleculeGroups list, the molecules that will be added to the surface.

• timestep_limit (int) – int, number of timesteps to simulate.

Return type:

tuple[tuple[ndarray[tuple[int], dtype[int_]], ...], ndarray[tuple[int], dtype[int_]]]

Returns:

list of indices during which adsorption takes place.

adsorpy.run_simulation._run_flux_fixedrotation(sim, surf, molecules, timestep_limit, distribution=None)

Adsorb while taking steps into account. Rotation is fixed and sites are varied instead.

Parameters:

• sim (Simulator) – Simulator.

• surf (Surface) – Surface.

• molecules (list[MoleculeGroup]) – MoleculeGroups list, the molecules that will be added to the surface.

• timestep_limit (int) – int, number of timesteps to simulate.

• distribution (list[float] | None) – list of floats indicating the distribution of the molecules. Empty for uniform distribution.

Return type:

tuple[tuple[ndarray[tuple[int], dtype[int_]], ...], ndarray[tuple[int], dtype[int_]]]

Returns:

list of indices during which adsorption takes place.

adsorpy.run_simulation._initialise_run_parameters(molecules_list=None, rotation_symmetries=None, reflection_symmetries=None, rotation_counts=None, simulation_type='sequential')

Initialise run parameters.

Parameters:

• molecules_list (Polygon | list[Polygon] | ndarray[tuple[int], dtype[Polygon]] | None) – 2D Molecule footprints.

• rotation_symmetries (int | list[int] | ndarray[tuple[int], dtype[int_]] | None) – Rotation symmetries of the molecules.

• reflection_symmetries (bool | list[bool] | ndarray[tuple[int], dtype[bool]] | None) – Reflection symmetries of the molecules.

• rotation_counts (int | list[int] | ndarray[tuple[int], dtype[int_]] | None) – Number of rotations.

• simulation_type (str) – Type of dosing scheme.

Return type:

tuple[ndarray[tuple[int], dtype[Polygon]], ndarray[tuple[int], dtype[int_]], ndarray[tuple[int], dtype[bool]], ndarray[tuple[int], dtype[int_]]]

Returns:

List of molecules, rotation symmetries, reflection symmetries, rotation counts.

Raises:

ValueError – If the requested simulation_type does not exist.

adsorpy.run_simulation._turn_into_list(val_or_list, compare_to)

Turn a variable or a list into an array.

Parameters:

• val_or_list (Union[TypeVar(T1), list[TypeVar(T1)], ndarray[tuple[int], dtype[TypeVar(T2, bound= generic | Polygon)]]]) – value or list.

• compare_to (type[TypeVar(T1)]) – comparison type. Should be either the type of the value or the type in the list.

Return type:

ndarray[tuple[int], dtype[TypeVar(T2, bound= generic | Polygon)]]

Returns:

the 1D array of the original variable or list.

adsorpy.run_simulation._repeater(orig_array, comparison_len)

Take the array and repeat it if it has a length of 1.

Parameters:

• orig_array (TypeVar(Tn, bound= ndarray[tuple[int], dtype[generic | Polygon]])) – original array.

• comparison_len (int) – length of the repetition.

Return type:

TypeVar(Tn, bound= ndarray[tuple[int], dtype[generic | Polygon]])

Returns:

the array repeated to the proper length.

adsorpy.run_simulation._error_checker(molecules_list, rotation_symmetries, reflection_symmetries, rotation_counts, simulation_type, dosing_distribution=None, boundary_condition=None, site_x_coords=None, site_y_coords=None, bounding_x_coord=None, bounding_y_coord=None)

Check the errors. Returns bool denoting custom grid (False if grid is not custom).

Parameters:

• molecules_list (ndarray[tuple[int], dtype[Polygon]]) – list of molecules.

• rotation_symmetries (ndarray[tuple[int], dtype[int_]]) – rotation symmetries.

• reflection_symmetries (ndarray[tuple[int], dtype[bool]]) – reflection symmetries.

• rotation_counts (ndarray[tuple[int], dtype[int_]]) – rotation counts.

• simulation_type (str) – simulation type.

• dosing_distribution (list[float] | ndarray[tuple[int], dtype[double]] | None) – dosing distribution.

• boundary_condition (str | None) – boundary condition.

• site_x_coords (ndarray[tuple[int], dtype[double]] | None) – site x coordinates.

• site_y_coords (ndarray[tuple[int], dtype[double]] | None) – site y coordinates.

• bounding_x_coord (float | None) – boundary x coordinate.

• bounding_y_coord (float | None) – boundary y coordinate.

Return type:

bool

Returns:

the custom grid flag.

Raises:

ValueError –

1. if the length of the molecules, symmetries, reflections, and rotations are unequal,

2. if the dosing distribution is not the same length as the molecule list,

3. if the provided boundary condition is not supported,

4. if the custom grid x/y coordinates/boundaries are not all empty or not all provided.

adsorpy.run_simulation._postprocessing(sim, surf, molecules, print_output_flag, plot_output_flag, calculate_gap_size, results_folder, timestr)

Perform post-processing of the data.

Parameters:

• sim (Simulator) – simulator.

• surf (Surface) – surface.

• molecules (list[MoleculeGroup]) – list of molecules.

• print_output_flag (bool) – True if output such as coverages and fraction of covered area should be printed.

• plot_output_flag (bool) – True if plots are to be shown.

• calculate_gap_size (bool) – True if gap size should be calculated. Can be computationally intensive.

• results_folder (str | Path) – results folder.

• timestr (str) – timestr to use.

Return type:

ndarray[tuple[int], dtype[double]]

Returns:

the gap size distribution. Empty array if calculate_gap_size is False.

adsorpy.run_simulation._select_and_run(sim, surf, molecules, simulation_type, include_rejected_flux, time_count, timestep_limit, dosing_distribution=None)

Select and run. A collection of the simulations. Putting them in one function helps streamline adjusting them.

Parameters:

• sim – simulator.

• surf – surface.

• molecules – list of molecules.

• simulation_type – simulation type.

• include_rejected_flux – True if rejected flux should be included.

• timestep_limit – number of time steps.

• dosing_distribution – dosing distribution. Leave empty if not needed or uniform.

Returns:

Fluxes per molecule if selected.

Raises:

ValueError – if the simulation_type (dosing scheme) and flux flag combination are not supported.

adsorpy.run_simulation.main()

Run the RSA script, for demonstration purposes.

Return type:

Literal[0]

Returns:

0 on success.