adsorpy.randomsequentialadsorption module

Random sequential adsorption (RSA) simulator on a grid.

In this module, all the adsorpy classes are defined. This is the base of the simulation. This module contains the lowest level methods for the library. run_simulation is preferred.

adsorpy.randomsequentialadsorption._create_empty_coords()[source]

Optimised localised function for dataclass factory.

Return type:

ndarray[tuple[Literal[2], Literal[1]], dtype[double]]

Returns:

Empty coordinates.

class adsorpy.randomsequentialadsorption.Config(*args, **kwargs)[source]

Bases: object

Dataclass containing the config variables read from data/config.

Variables:

  • sites – The number of sites in the x-direction.

  • xsize – Under construction, do not use.

  • ysize – Under construction, do not use.

  • zsize – Under construction, do not use.

  • max_molecule_count – The maximum amount of molecule placements to attempt.

  • lattice_a – The lattice spacing in Angstrom.

  • boundary_type – The boundary type. ‘soft’, ‘hard’, or ‘periodic’.

  • sticking_probability – The sticking probability of the molecules, between 0 and 1.

Parameters:
sites: Annotated[int, Gt(gt=0)] | None
xsize: Annotated[float, Gt(gt=0)] | None
ysize: Annotated[float, Gt(gt=0)] | None
zsize: Annotated[float, Gt(gt=0)] | None
max_molecule_count: Annotated[int, Gt(gt=0)]
lattice_a: Annotated[float, Gt(gt=0)]
boundary_type: Literal['soft', 'hard', 'periodic']
sticking_probability: Annotated[float, Ge(ge=0)]
__init__(*args, **kwargs)
Parameters:

  • __dataclass_self__ (PydanticDataclass)

  • args (Any)

  • kwargs (Any)

Return type:

None

adsorpy.randomsequentialadsorption._config_loader(rsa_config)[source]

Load the RsaConfig into the Config class.

Parameters:

rsa_config (RsaConfig) – The RsaConfig.

Return type:

Config

Returns:

The Config.

class adsorpy.randomsequentialadsorption.BoundaryParameters(boundary_type, rot_cnt=0, dbl_max_radius=0.0)[source]

Bases: object

Store the boundary parameters for the surface and the molecule groups.

Mostly empty for ‘soft’ boundaries, utilises different parameters for ‘hard’ and ‘periodic’ boundaries.

Variables:

  • molecules_flag (Final[bool]) – True if this is the boundary parameter class for molecules, False if it used for a surface.

  • boundary_type (Final[str]) – The boundary type.

  • soft_flag (bool) – True if used for a soft boundary condition. Only one flag can be True.

  • hard_flag (bool) – True if used for a hard boundary condition. Only one flag can be True.

  • periodic_flag (bool) – True if used for a periodic boundary condition. Only one flag can be True.

  • hard_inner (BoolArray) – All sites close to the edge of the hard boundary. These sites are True, others False.

  • molecules_bounding_coords – Molecule bounding box coordinates: min/max x/y values.

  • allowed_idx (IdxArray) – Index of allowed rotations. When close to a hard boundary, some rotations are no longer possible.

  • allowed_bools (BoolArray) – Booleans belonging to the allowed rotations. When near the hard boundary, some rotations are impossible.

  • extended_grid (CoordsArray) – The surface site coordinates of the extended (periodic) grid.

  • extended_occupied_by (IdxArray) – The occupancy of the extended (periodic) grid. Filled with the indices of the molecules on the grid.

  • extended_idx (IdxArray) – Index of the extended (periodic) grid.

  • close_to_edge (BoolArray) – Boolean array denoting closeness to the edge. If close to the edge, periodicity must be taken into account.

  • extended_vacant (BoolArray) – Boolean array denoting vacantness of the extended (periodic) grid. True if a site is vacant, False otherwise.

  • edge_flag (bool) – Flag indicating closeness to the edge. Reset this for every placement attempt.

  • mirror_counter (int) – A counter for the molecules + mirror molecules.

  • mirrors (IdxArray) – Mirror indices.

  • biggest_diameter (float) – The biggest radius between the two largest molecules in the simulation.

  • tree (STRtree) – STRtree, currently unused.

Parameters:

  • boundary_type (str)

  • rot_cnt (int)

  • dbl_max_radius (float)

Initialise the boundary parameters for soft, periodic, hard.

Parameters:

  • boundary_type (str) – String denoting the boundary type.

  • rot_cnt (int) – Count of allowed rotations. 0 for non-molecules.

  • dbl_max_radius (float) – double the maximum radius of the molecule.

__init__(boundary_type, rot_cnt=0, dbl_max_radius=0.0)[source]

Initialise the boundary parameters for soft, periodic, hard.

Parameters:

  • boundary_type (str) – String denoting the boundary type.

  • rot_cnt (int) – Count of allowed rotations. 0 for non-molecules.

  • dbl_max_radius (float) – double the maximum radius of the molecule.

Return type:

None

molecules_flag: Final[bool]
boundary_type: Final[str]
soft_flag: bool
hard_flag: bool
periodic_flag: bool
hard_inner: ndarray[tuple[int], dtype[bool]]
molecules_bounding_coords: ndarray[tuple[int, Literal[4]], dtype[float64]]
allowed_idx: ndarray[tuple[int], dtype[int64]]
allowed_bools: ndarray[tuple[int], dtype[bool]]
extended_grid: ndarray[tuple[Literal[2], int], dtype[float64]]
extended_occupied_by: ndarray[tuple[int], dtype[int64]]
extended_idx: ndarray[tuple[int], dtype[int64]]
close_to_edge: ndarray[tuple[int], dtype[bool]]
extended_vacant: ndarray[tuple[int], dtype[bool]]
edge_flag: bool
mirror_counter: int
mirrors: ndarray[tuple[int], dtype[int64]]
biggest_diameter: float
tree: STRtree
static set_boundary_flags(boundary_type)[source]

Take a string of the boundary flags and turns it into any of three bools.

Boolean checking is cheaper than string evaluation.

Parameters:

boundary_type (str) – The boundary type. Either soft, hard, or periodic. Throws an error otherwise.

Return type:

tuple[bool, bool, bool]

Returns:

The soft, hard, and periodic flags. One is set to True. If not, an error is thrown.

Raises:

  • TypeError – If boundary_type is not a string.

  • ValueError – If boundary_type is not ‘soft’, ‘hard’, or ‘periodic’.

generate_boundary_conditions(surf, molgr=None)[source]

Generate the boundary conditions and modifies the available sites.

If the boundary condition is soft, generate nothing.

Parameters:

  • surf (Surface) – The surface.

  • molgr (MoleculeGroup | None) – The molecule group for which the boundary conditions are defined. Optional.

Return type:

None

class adsorpy.randomsequentialadsorption.MoleculeGroup(rsa_config, molecule, rotation_symmetry, reflection_symmetry, site_count, mgc, rotation_count=360, sticking_probability=None)[source]

Bases: object

Create the molecule group class.

It stores the basic shapes of rotated molecules such that they can be translated later. It also keeps track of several other values such as radius.

Variables:

  • group_id (Final[int]) – ID value of the molecule group. Automatically iterates when making new molecule groups.

  • config (Final[Config]) – Config values.

  • molecule (Final[Polygon]) – Molecule polygon.

  • rotation_symmetry (Final[int]) – Rotation symmetry. 0 for no symmetry, 1 for circle, n (int >= 2) for n-fold.

  • reflection_symmetry (Final[bool]) – Reflection symmetry. True for reflection symmetry over the y-axis, False for no reflection symmetry.

  • area (Final[float]) – Area of the molecule.

  • min_radius (Final[float]) – Inradius of the molecule.

  • max_radius (Final[float]) – Circumradius of the molecule.

  • rotation_count (int) – Rotation count of the molecule. How many rotations are to be considered?

  • __max_rotation (Final[int]) – Molecules can only rotate between 0 and 360 degrees (excluding the endpoint). Do not touch.

  • rot_refl_count (Final[int]) – Rotation + reflection count. If the molecule has no reflection symmetry, all rotations must also be attempted while reflected.

  • allowed_rotations (NDArray[double]) – Rotations for the molecule.

  • rotated_molecules (ndarray[tuple[int], dtype[Polygon]]) – Array of rotated molecules. Used as templates, only translation is needed to get into position.

  • rotated_buffer_molecules (ndarray[tuple[int, int], dtype[Polygon]]) – Buffer molecules are a special type of polygon used for vectorised calculations.

  • molecule_counter (int) – Molecule counter for this molecule type.

  • occupied_by (ndarray[tuple[int], dtype[longlong]]) – Which molecule hinders what? Defaults to -1 (invalid). Special value -2 indicates unreachable.

  • sticking_probability (float) – Sticking probability of the molecule.

  • vacant (ndarray[tuple[int], dtype[bool]]) – Vacancy array for the molecule. Shows which sites are guaranteed to be unreachable (False) and which are free.

  • vacancy_count (int) – Counts the vacant sites. Updates per placement.

  • bp (BoundaryParameters) – Boundary parameter class.

  • gap_dists (NDArray[double]) – Distances for the molecules, measured as the sum of the circumradii.

  • minmax_gaps (NDArray[double]) – Distance as the sum between the circumradius and inradius of two molecules.

Parameters:

  • rsa_config (RsaConfig)

  • molecule (Polygon)

  • rotation_symmetry (int)

  • reflection_symmetry (bool)

  • site_count (int)

  • mgc (count[int])

  • rotation_count (int)

  • sticking_probability (float | None)

Initialise the data for molecule groups.

Molecule groups are how data is stored per molecule footprint shape.

Parameters:

  • rsa_config (RsaConfig) – RsaConfig class.

  • molecule (Polygon) – (2D) polygon data representing the molecule.

  • rotation_symmetry (int) – Rotation symmetry of the molecule group. Set 0 for circular symmetry.

  • reflection_symmetry (bool) – Bool denoting reflection symmetry of the molecule group.

  • site_count (int) – The total amount of surface sites.

  • mgc (count[int]) – Molecule group counter.

  • rotation_count (int) – The amount of allowed rotations. If not provided, assumes 360.

  • sticking_probability (float | None)

__init__(rsa_config, molecule, rotation_symmetry, reflection_symmetry, site_count, mgc, rotation_count=360, sticking_probability=None)[source]

Initialise the data for molecule groups.

Molecule groups are how data is stored per molecule footprint shape.

Parameters:

  • rsa_config (RsaConfig) – RsaConfig class.

  • molecule (Polygon) – (2D) polygon data representing the molecule.

  • rotation_symmetry (int) – Rotation symmetry of the molecule group. Set 0 for circular symmetry.

  • reflection_symmetry (bool) – Bool denoting reflection symmetry of the molecule group.

  • site_count (int) – The total amount of surface sites.

  • mgc (count[int]) – Molecule group counter.

  • rotation_count (int) – The amount of allowed rotations. If not provided, assumes 360.

  • sticking_probability (float | None)

Return type:

None

group_id: Final[int]
config: Final[Config]
molecule: Final[Polygon]
rotation_symmetry: Final[int]
reflection_symmetry: Final[bool]
area: Final[float]
min_radius: Final[float]
max_radius: Final[float]
rotation_count: int
__max_rotation: Final[int]
rot_refl_count: Final[int]
allowed_rotations: NDArray[float64]
rotated_molecules: ndarray[tuple[int], dtype[Polygon]]
rotated_buffer_molecules: ndarray[tuple[int, int], dtype[Polygon]]
molecule_counter: int
occupied_by: ndarray[tuple[int], dtype[int64]]
sticking_probability: float
vacant: ndarray[tuple[int], dtype[bool]]
vacancy_count: int
bp: BoundaryParameters
gap_dists: NDArray[float64]
minmax_gaps: NDArray[float64]
generate_rotated_molecules(bopa, amgs)[source]

Generate rotated molecules and prepared buffer molecules. Generate bounding box in case of hard boundary.

Parameters:
Return type:

BoundaryParameters

Returns:

The updated boundary parameters of the molecule group we are interested in.

class adsorpy.randomsequentialadsorption.CandidateMolecule(molecule_group_idx=-1, grid_index=-1, coordinates=<factory>, molecule=<factory>, rot_idx=-1, molecule_number=-1, close_to_border=False, exists=True)[source]

Bases: object

Create a candidate molecule with temporary data.

All relevant data for a candidate molecule. The molecule group index, grid index, coordinates, molecules, rotation index, molecule number, bool to denote closeness to the border, and existence. Re-used every time. All index values are illegal by default for easier debugging.

Variables:

  • molecule_group_idx – Molecule group index value. Defaults to -1, an invalid value.

  • grid_index – Grid index value. Defaults to -1, an invalid value.

  • coordinates – Coordinates of the molecule. Defaults to np.empty((2, 1), dtype=np.float64).

  • molecule – Candidate molecule. Initially empty.

  • rot_idx – Rotation index value. Defaults to -1, an invalid value.

  • molecule_number – Molecule number value. Defaults to -1, an invalid value.

  • close_to_border – Flag denoting closeness to the border. Defaults to False.

  • exists – Flag denoting existence of this molecule. Defaults to True.

Parameters:
molecule_group_idx: int
grid_index: int
coordinates: ndarray[tuple[Literal[2], Literal[1]], dtype[float64]]
molecule: Polygon
rot_idx: int
molecule_number: int
close_to_border: bool
exists: bool
get_canddata()[source]

Prepare the candidate data for storage in the molecule data storage class.

Return type:

tuple[int, bool, int, int, int, bool, float, float, Polygon]

Returns:

Mol num, exists flag, group idx, grid idx, rot idx, close to border flag, x coord, y coord, polygon.

__init__(molecule_group_idx=-1, grid_index=-1, coordinates=<factory>, molecule=<factory>, rot_idx=-1, molecule_number=-1, close_to_border=False, exists=True)
Parameters:
Return type:

None

class adsorpy.randomsequentialadsorption.Simulator(rsa_config, include_rejected_flux, surf, mol_groups, rng, boundary_type=None)[source]

Bases: object

Perform Random Sequential Adsorption (RSA).

The class that brings it all together. Places/(re)moves the molecules, updates positioning, keeps track of a lot of things. Allows for plotting as well, as well as gap size analysis.

Variables:

  • config (Final[Config]) – Config values.

  • rng (Generator) – Random number generator.

  • surf (Surface) – Surface class.

  • molgroups (list[MoleculeGroup]) – List of the molecule group classes.

  • molgrcount (int) – Count of the molecule group classes.

  • bp (BoundaryParameters) – Boundary parameter class.

  • flux_flag (bool) – Flag denoting whether occupied sites can be re-attempted for placement.

  • total_molecule_counter (longlong) – Counter for all molecules on the surface.

  • outer_rads (NDArray[double]) – Circumradii of all molecules. (Value of two max radii added together).

  • minmax_rads (NDArray[double]) – Sums of inradii and circumradii. (Value of one max and one min radius added together).

  • mol_data (MoleculeData) – Molecule data. This is where the values of the placed molecules and mirror molecules are stored.

  • __unclaimed – ID value for unreachable sites: sites that are not covered by a molecule but still not reachable.

Parameters:

Initialise the simulator, combine the other classes.

Parameters:

  • rsa_config (RsaConfig) – RsaConfig class.

  • include_rejected_flux (bool) – allows adsorption attempts to occupied sites.

  • surf (Surface) – Surface class.

  • mol_groups (list[MoleculeGroup]) – the molecule groups.

  • rng (Generator) – random number generator. This is needed for seeded runs (all are seeded).

  • boundary_type (str | None) – type of boundary conditions, optional. If None, defaults to config.json (periodic).

Raises:

ValueError – if no molecules are provided.

__init__(rsa_config, include_rejected_flux, surf, mol_groups, rng, boundary_type=None)[source]

Initialise the simulator, combine the other classes.

Parameters:

  • rsa_config (RsaConfig) – RsaConfig class.

  • include_rejected_flux (bool) – allows adsorption attempts to occupied sites.

  • surf (Surface) – Surface class.

  • mol_groups (list[MoleculeGroup]) – the molecule groups.

  • rng (Generator) – random number generator. This is needed for seeded runs (all are seeded).

  • boundary_type (str | None) – type of boundary conditions, optional. If None, defaults to config.json (periodic).

Raises:

ValueError – if no molecules are provided.

Return type:

None

config: Final[Config]
rng: Generator
surf: Surface
molgroups: list[MoleculeGroup]
molgrcount: int
bp: BoundaryParameters
flux_flag: bool
total_molecule_counter: int64
outer_rads: NDArray[float64]
minmax_rads: NDArray[float64]
mol_data: MoleculeData
__unclaimed: Final[int]
_calculate_radii()[source]

Calculate the min and max radii for the gap arrays.

Return type:

None

attempt_place_molecule(surf, pmg, grid_idx=None, first_rot_idx=None)[source]

Try to place a molecule.

It calls functions to check for adjacency and intersection. If the molecule does not touch any others, it is stored. Otherwise, it is discarded.

Parameters:

  • surf (Surface) – The surface.

  • pmg (MoleculeGroup) – The primary molecule group (pmg) we want to place.

  • grid_idx (int | longlong | None) – A grid index value, optional. If set, try to place on this index instead of a random one.

  • first_rot_idx (int | longlong | None) – The first rotation to attempt, optional.

  • self (Simulator)

  • surf

  • pmg

  • grid_idx

  • first_rot_idx

Return type:

tuple[bool, int, int, int, int, list[int]]

Returns:

Bool for placement of mol, the mol counter, mol group, placement index, rot index, and vacant count.

update_placement(cand, surf, pmg, amgs)[source]

Update the stored molecules, coordinates, and index arrays.

Add a new molecule.

Parameters:
Return type:

longlong

Returns:

The total placed molecule count.

trim_buffer(occupier_idx, pmg, mol_group, surf)[source]

Trim the available sites by removing inaccessible sites.

Take a buffered (isodistance) area around the positioned molecule of the minimum radius of the other molecule, then removes all coordinates within the buffer area from the list of available positions for the other. Nothing can be placed closer to existing molecules than this minimum radius.

Parameters:

  • occupier_idx (int) – Index of the molecule that covers the sites.

  • pmg (MoleculeGroup) – Primary molecule group, the group that has been positioned.

  • mol_group (MoleculeGroup) – One of the molecule groups. The group whose data is updated.

  • surf (Surface) – The Surface.

Return type:

None

Returns:

The molecule group whose availability has been updated.

plot_covered_grid(surf, amgs, save_flag=False, plt_flag=False, timestr='', results_folder='', use_ax=None)[source]

Plot the molecules with the grid and save it as a figure.

Parameters:

  • surf (Surface) – The surface.

  • amgs (list[MoleculeGroup]) – All molecule groups.

  • save_flag (bool) – True: save the figure.

  • plt_flag (bool) – True: plot the figure.

  • timestr (str) – The timestring, can be used for saving the name.

  • results_folder (str | Path) – The folder in which the results will be saved.

  • use_ax (Axes | None) – The plt.Axes object of the figure. Optional.

Return type:

Axes

Returns:

The updated plt.Axes object.

svgplot_covered_grid(surf=None, amgs=None, filename='', rounding=4, dark_mode_bool=False)[source]

Plot the covered grid as an SVG.

Parameters:

  • surf (Surface | None) – The surface object.

  • amgs (list[MoleculeGroup] | None) – A list of the molecule groups.

  • filename (str | Path | BytesIO) – The file name as string or path.

  • rounding (int) – How many digits to round all values to.

  • dark_mode_bool (bool) – Boolean denoting dark mode. If False, assume light mode.

Return type:

None

attempt_cascading_placement(surf, *molgrs, site_idx=None)[source]

Try to place molecules in the order of the arguments on the same random site. Stops when one fits.

Parameters:

  • surf (Surface) – The surface.

  • molgrs (MoleculeGroup) – The molecule groups. Placement occurs in the order of this argument.

  • site_idx (int | None) – Site to attempt placement on. If not given, pick random.

Return type:

tuple[bool, int, int, int | None, int, list[int]]

Returns:

The output of Simulator.attempt_place_molecule().

attempt_random_placement(surf, *molgrs, weights=None)[source]

Pick from a list of molecule groups and places a random one.

Parameters:
Return type:

tuple[bool, int, int, int, int, list[int]]

Returns:

The output of Simulator.attempt_place_molecule().

analyse_gap_size(surf=None, keepzero=False)[source]

Analyse the gap distance based on the distance from surface sites to the nearest molecule.

Parameters:

  • surf (Surface | None) – The surface.

  • keepzero (bool) – Flag denoting whether to keep distances of zero (inside of polygon).

Return type:

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

Returns:

The gap size distribution.

check_if_overlap()[source]

Check if any of the polygons overlap.

Slow function. It should always return False. Feel free to use to rigorously check a filled surface. If the simulator has a periodic surface, periodic molecules will be checked as well.

Return type:

bool

Returns:

True if there is overlap. False if all molecules are disjoint.

property coverage: ndarray[tuple[int], dtype[float64]]

Calculate the coverage per molecule group.

The total coverage is the sum of the list.

Returns:

Array of coverages per molecule group.

property fraction_of_covered_area: ndarray[tuple[int], dtype[float64]]

Calculate the fraction of covered area per molecule group.

The total fraction of covered area is the sum of the list.

Returns:

Array of the fraction of covered area per molecule group.

class adsorpy.randomsequentialadsorption.Surface(rsa_config, lattice_type='triangular', site_count=None, lattice_a=None, boundary_type=None, sticking_probability=None)[source]

Bases: object

Store coordinates and occupation data.

Variables:

  • config (Final[Config]) – Config values.

  • lattice_type (Final[str]) – Lattice type of the surface. Can be ‘triangular’/’hexagonal’, ‘square’ or ‘honeycomb’.

  • sites (int) – Site count of the surface in the x-direction.

  • simple_shape_flag (Final[bool]) – Currently unused. Leave True for now.

  • xsize (float | None) – Under construction, currently unused.

  • ysize (float | None) – Under construction, currently unused.

  • zsize (float | None) – Under construction, currently unused.

  • all_site_count (int) – Total site count for all molecules.

  • lattice_a (Final[float]) – Lattice spacing of the surface in Angstrom.

  • sticking_probability (Final[float]) – Sticking probability of the molecules.

  • x_max – Maximum x value of the surface. Adjusted properly for periodic surfaces.

  • y_max – Maximum y value of the surface. Adjusted properly for periodic surfaces.

  • area – Area of the surface. Adjusted properly for periodic surfaces.

  • grid_index (ndarray[tuple[int], dtype[longlong]]) – Grid index array.

  • grid_coordinates (ndarray[tuple[Literal[2], int], dtype[double]]) – Array of the grid coordinates.

  • bp – Boundary parameters of the surface.

  • tree (STRtree) – STRtree, currently unused.

Parameters:

  • rsa_config (RsaConfig)

  • lattice_type (str)

  • site_count (int | None)

  • lattice_a (float | None)

  • boundary_type (str | None)

  • sticking_probability (float | None)

Initialise the surface.

Parameters:

  • rsa_config (RsaConfig) – The input parameters defined in the config.

  • lattice_type (str) – The type of lattice to use. Can be triangular, square, or honeycomb.

  • site_count (int | None) – The number of sites, optional. If None, defaults to the default in config.json.

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

  • boundary_type (str | None) – The boundary type, optional. If None, defaults to the default in config.json (periodic).

  • sticking_probability (float | None) – Sticking probability. Default is 1.0 from config.

Raises:

ValueError – If only x or y is provided for a custom surface. Currently unusable.

__init__(rsa_config, lattice_type='triangular', site_count=None, lattice_a=None, boundary_type=None, sticking_probability=None)[source]

Initialise the surface.

Parameters:

  • rsa_config (RsaConfig) – The input parameters defined in the config.

  • lattice_type (str) – The type of lattice to use. Can be triangular, square, or honeycomb.

  • site_count (int | None) – The number of sites, optional. If None, defaults to the default in config.json.

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

  • boundary_type (str | None) – The boundary type, optional. If None, defaults to the default in config.json (periodic).

  • sticking_probability (float | None) – Sticking probability. Default is 1.0 from config.

Raises:

ValueError – If only x or y is provided for a custom surface. Currently unusable.

Return type:

None

config: Final[Config]
lattice_type: Final[str]
sites: int
simple_shape_flag: Final[bool]
xsize: float | None
ysize: float | None
zsize: float | None
all_site_count: int
lattice_a: Final[float]
sticking_probability: Final[float]
x_max
y_max
area
grid_index: ndarray[tuple[int], dtype[int64]]
grid_coordinates: ndarray[tuple[Literal[2], int], dtype[float64]]
bp
tree: STRtree
_estimate_site_count()[source]

Estimates the total site count.

Return type:

int

Returns:

Total site count.

generate_grid(rng=None)[source]

Create a hexagonal grid as a 2D numpy array with x the first index and y on the second.

Parameters:

rng (Generator | None) – The random generator. Used when generating an amorphous surface with the Delone lib.

Raises:

  • ValueError – If the lattice string is not supported (name and type are printed).

  • TypeError – If the lattice type is not supported (name and type are printed).

Return type:

None

_set_xy_max(x_all, y_all, sqrt3)[source]

Set the x_max and y_max based on boundary condition and surface type.

Parameters:
Return type:

None

generate_custom_surface(site_x_coords, site_y_coords, bounding_x_coord, bounding_y_coord)[source]

Generate a custom surface from user input.

Ensure that the origin is (0,0) and that all values are positive. Ensure that the arrays are equal in length.

Parameters:

  • site_x_coords (ndarray[tuple[int], dtype[double]]) – The x coordinates of the surface sites.

  • site_y_coords (ndarray[tuple[int], dtype[double]]) – The y coordinates of the surface sites.

  • bounding_x_coord (float) – The x coordinate of the bounding box.

  • bounding_y_coord (float) – The y coordinate of the bounding box.

Raises:

ValueError – If the x or y (bounding box) coordinates are not positive or unequal in length.

Return type:

None

plot_surface_sites(timestr='', directory='', axes_object=None)[source]

Plot the surface sites (for verification/validation).

Parameters:

  • timestr (str) – The timestring, can be used for saving. Leave empty to not save.

  • directory (str | Path) – The directory in which results are stored. Leave empty to not save.

  • axes_object (Axes | None) – The plt.Axes object to update, if given.

Return type:

Axes

Returns:

The plt.Axes object.

svgplot_surface_sites(filename='', dark_mode_bool=False)[source]

Plot the surface sites as an SVG file.

Parameters:

  • filename (str | Path | BytesIO) – The filepath of the SVG file. If io.BytesIO is provided, the file will be written to bytes.

  • dark_mode_bool (bool) – True if dark mode, False if light mode.

Return type:

None

make_surface_svg_elements(rounding=4)[source]

Make the SVG elements of the surface.

Parameters:

rounding (int) – The number of decimal places to round the coordinates.

Return type:

tuple[Circle, list[G | Rect], float, float]

Returns:

  1. The surface site template

  2. The surface sites as svg.G. If a hard boundary is used, also adds that as svg.Rect.

  3. The width.

  4. The height.

static create_dark_css_style(dark_mode_bool=False)[source]

Create an option to use dark colours for the SVG.

Parameters:

dark_mode_bool (bool) – True if dark mode, False otherwise.

Return type:

Style

Returns:

The Style element containing the dark mode CSS toggle.

static create_and_write_svg(filename, root_group_elements, width, height, definitions, style)[source]

Create the SVG.

Parameters:

  • filename (Path | BytesIO) – Name of the file to write to, or io.BytesIO object.

  • root_group_elements (Sequence[Rect | G | Point]) – The root elements to add to the SVG.

  • width (float) – The width of the SVG.

  • height (float) – The height of the SVG.

  • definitions (Defs) – The definitions (templates) to add to the SVG.

  • style (Style)

Return type:

None

adsorpy.randomsequentialadsorption._create_rtree_index()[source]

Optimised localised helper to instantiate a 2D RTree Index without runtime closures.

Return type:

Index

Returns:

RTree index.

class adsorpy.randomsequentialadsorption.MoleculeData(max_array_length=100, current_mirror_num=-1, last_accessed_idx=-1, mol_tree=<factory>, mirr_tree=<factory>, _otomir_fill_vals=(False, []))[source]

Bases: object

Stores the data associated with all the molecules on the surface, as well as periodic molecules.

Variables:

  • max_array_length – Maximum length of all arrays. Extends by this amount when the maximum is reached.

  • mol_counter – Molecule counter.

  • current_mol_id – Current molecule index.

  • mirr_counter – Mirror counter. Takes steps of 4.

  • current_mirror_num – Current mirror index number.

  • last_accessed_idx – Last accessed molecule index.

  • _header_names – Names of the headers.

  • _column_datatypes – Datatypes of the columns of the molecule struct array.

  • _heads_dtypes – Data types + names for the molecule struct array.

  • _fill_vals – Fill value for the new molecule. Defaults to strictly invalid values.

  • stored_data – Molecule struct array. Here, all data for the molecules is stored.

  • mol_tree – Molecules RTree.

  • _mirr_names – Names of the columns in the mirror molecule struct array.

  • _mirr_datatypes – Datatypes of the mirror molecule struct array.

  • _mirr_heads_dtypes – Data types + names for the mirror molecules struct array.

  • _mirr_fill_vals – Fill values for the new mirror molecule. Defaults to strictly invalid values.

  • stored_mirr_data – Mirror molecule struct array. Here, all data for the mirror molecules is stored.

  • mirr_tree – Mirror molecules RTree.

  • _otomir_names – Names for the origin to mirror array.

  • _otomir_types – Types of the origin to mirror array.

  • _otomir_heads_dtypes – Data types for the original molecule to mirror (otomir) struct array.

  • _otomir_fill_vals – Fill values for the origin to mirror array. Defaults to strictly invalid values.

  • orig_to_mirrors – Origin to mirror struct array. Stores indices linking mirror molecules to original molecules.

  • coords – Coordinates of the molecules.

  • mirror_coords – Mirror coordinates of the molecules.

Parameters:

  • max_array_length (int)

  • current_mirror_num (int)

  • last_accessed_idx (int)

  • mol_tree (Index)

  • mirr_tree (Index)

  • _otomir_fill_vals (Final[tuple[bool, list[int]]])

max_array_length: int
mol_counter: count[int]
current_mol_id: count[int]
mirr_counter: count[int]
current_mirror_num: int
last_accessed_idx: int
_header_names = ('self_id', 'exists', 'mol_group', 'grid_idx', 'rot_idx', 'has_periodic_images', 'x_coord', 'y_coord', 'polygon')
_column_datatypes = (<class 'int'>, <class 'bool'>, <class 'int'>, <class 'int'>, <class 'int'>, <class 'bool'>, <class 'float'>, <class 'float'>, <class 'shapely.geometry.polygon.Polygon'>)
_heads_dtypes: list[tuple[str, type]]
_fill_vals = (-1, False, -1, -1, -1, False, 0.0, 0.0, <POLYGON EMPTY>)
stored_data: np.ndarray[tuple[int], np.dtype[np.void]]
mol_tree: Index
_mirr_names = ('orig_id', 'exists', 'self_id', 'mol_group', 'grid_idx', 'rot_idx', 'x_coord', 'y_coord', 'polygon')
_mirr_datatypes = (<class 'int'>, <class 'bool'>, <class 'int'>, <class 'int'>, <class 'int'>, <class 'int'>, <class 'float'>, <class 'float'>, <class 'shapely.geometry.polygon.Polygon'>)
_mirr_heads_dtypes: list[tuple[str, type]]
_mirr_fill_vals = (-1, False, -1, -1, -1, -1, 0.0, 0.0, <POLYGON EMPTY>)
stored_mirr_data: np.ndarray[tuple[int], np.dtype[np.void]]
mirr_tree: Index
_otomir_names = ('exists', 'mirr_ids')
_otomir_types = (<class 'bool'>, <class 'object'>)
_otomir_heads_dtypes: list[tuple[str, type]]
_otomir_fill_vals: Final[tuple[bool, list[int]]]
orig_to_mirrors: np.ndarray[tuple[int], np.dtype[np.void]]
__init__(max_array_length=100, current_mirror_num=-1, last_accessed_idx=-1, mol_tree=<factory>, mirr_tree=<factory>, _otomir_fill_vals=(False, []))
Parameters:
Return type:

None

coords: CoordsArray
mirror_coords: CoordsArray
static make_struct_array(size, nameddtypes, fillvals)[source]

Make a structured array for the molecule storage.

Parameters:
Return type:

ndarray[tuple[int], dtype[void]]

Returns:

The new structured array.

add_entry(_, exists, mol_group, grid_idx, rot_idx, has_periodic_images, x_coord, y_coord, polygon)[source]

Add a new entry to the stored data. All fields are mandatory.

Parameters:

  • _ (int) – Currently unused. The molecule index. Generated automatically though. # TODO: Not used?

  • exists (bool) – Flag to determine whether the molecule exists on the surface.

  • mol_group (int) – Molecule group index. Set to -1 if invalid.

  • grid_idx (int) – Grid site index. Set to -1 if invalid.

  • rot_idx (int) – Rotation index.

  • has_periodic_images (bool) – Flag to determine whether the molecule has periodic images.

  • x_coord (float) – X-coordinate of the molecule centre.

  • y_coord (float) – Y-coordinate of the molecule centre.

  • polygon (Polygon) – The molecule polygon.

Return type:

None

add_mirror(mirr_num, orig_id, exists, mol_group, grid_idx, rot_idx, x_coord, y_coord, polygon)[source]

Add a mirror molecule to the stored molecule data.

Parameters:

  • mirr_num (int) – The mirror number for this idx. Number between 0 and 3 (inclusive).

  • orig_id (int) – The ID of the molecule for which the mirror images are added.

  • exists (bool) – Bool, denotes whether the molecule exists.

  • mol_group (int) – The molecule group ID.

  • grid_idx (int) – The grid index.

  • rot_idx (int) – The rotation index.

  • x_coord (float) – The x-coordinate.

  • y_coord (float) – The y-coordinate.

  • polygon (Polygon) – The molecule polygon at the mirrored location.

Return type:

None