adsorpy.molecule_lib module

Contains all the molecules that can be used in this simulation.

Also includes molecule loader scripts, for which the molecule data is not included in this lib. You need to supply your own .xyz files, or you can use preconfigured simple shapes.

adsorpy.molecule_lib.AtomKey

Atom key validator. String of length 1 or 2 denoting chemical symbols.

alias of Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=2, pattern=None, ascii_only=None)]

adsorpy.molecule_lib._load_radii_from_json()

Load the van der Waals radii from the vdw_radii.json file.

Uses Pydantic to validate the JSON.

Return type:

dict[str, float]

Returns:

dict of the chemical symbols (keys) and van der Waals radii (values).

adsorpy.molecule_lib.RADII: Final[dict[str, float]] = {'Ac': 2.8, 'Ag': 2.53, 'Al': 2.25, 'Am': 2.83, 'Ar': 1.83, 'As': 1.88, 'Au': 2.32, 'B': 1.91, 'Ba': 3.03, 'Be': 1.98, 'Bi': 2.54, 'Bk': 3.4, 'Br': 1.86, 'C': 1.77, 'Ca': 2.62, 'Cd': 2.49, 'Ce': 2.88, 'Cf': 3.05, 'Cl': 1.82, 'Cm': 3.05, 'Co': 2.4, 'Cr': 2.45, 'Cs': 3.48, 'Cu': 2.38, 'Dy': 2.87, 'Er': 2.83, 'Es': 2.7, 'Eu': 2.87, 'F': 1.46, 'Fe': 2.44, 'Ga': 2.32, 'Gd': 2.83, 'Ge': 2.29, 'H': 1.2, 'He': 1.43, 'Hf': 2.63, 'Hg': 2.45, 'Ho': 2.81, 'I': 2.04, 'In': 2.43, 'Ir': 2.41, 'K': 2.73, 'Kr': 2.25, 'La': 2.98, 'Li': 2.12, 'Lu': 2.74, 'Mg': 2.51, 'Mn': 2.45, 'Mo': 2.45, 'N': 1.66, 'Na': 2.5, 'Nb': 2.56, 'Nd': 2.95, 'Ne': 1.58, 'Ni': 2.4, 'Np': 2.82, 'O': 1.5, 'Os': 2.48, 'P': 1.9, 'Pa': 2.88, 'Pb': 2.6, 'Pd': 2.15, 'Pr': 2.92, 'Pt': 2.29, 'Pu': 2.81, 'Rb': 3.21, 'Re': 2.49, 'Rh': 2.44, 'Ru': 2.46, 'S': 1.89, 'Sb': 2.47, 'Sc': 2.58, 'Se': 1.82, 'Si': 2.19, 'Sm': 2.9, 'Sn': 2.42, 'Sr': 2.84, 'Ta': 2.53, 'Tb': 2.79, 'Tc': 2.44, 'Te': 1.99, 'Th': 2.93, 'Ti': 2.46, 'Tl': 2.47, 'Tm': 2.79, 'U': 2.71, 'V': 2.42, 'W': 2.57, 'Xe': 2.06, 'Y': 2.75, 'Yb': 2.8, 'Zn': 2.39, 'Zr': 2.52}

Key-value pairs of chemical symbols and van der Waals radii.

Reference:

S. Alvarez, “A cartography of the van der Waals territories,” Dalton Trans., vol. 42, no. 24, pp. 8617-8636, Jun. 2013, doi: 10.1039/C3DT50599E.

adsorpy.molecule_lib.discorectangle(radius, distance, x_offset=0.0, y_offset=0.0)

Create a disco-rectangle using the union of two circles and a rectangle.

The circles are automatically approximated using linear segments (error of 1% or less).

Parameters:

• radius (float) – Radius of the two circles in angstrom.

• distance (float) – Distance between the two halves in angstrom.

• x_offset (float) – X offset.

• y_offset (float) – Y offset.

Return type:

Polygon

Returns:

The molecule shape as a polygon.

adsorpy.molecule_lib.circulium(radius, x_offset=0.0, y_offset=0.0, quad_segs=8)

Create a simple circular polygon.

The circles are automatically approximated using linear segments (error of 1% or less).

Parameters:

• radius (float) – Radius of the circle.

• x_offset (float) – The x-offset in angstrom.

• y_offset (float) – The y-offset in angstrom.

• quad_segs (int) – The amount of linear segments in a quarter circle.

Return type:

Polygon

Returns:

The molecule shape as a polygon.

adsorpy.molecule_lib.dogbonium(scale=1.0)

Make a molecule shaped like a bone. Used as a pathological case.

Parameters:

scale (float) – scale of the shape.

Return type:

Polygon

Returns:

The molecule shape as a polygon.

adsorpy.molecule_lib.polygonium(verts=3, scale=1.0, roundedness=0.0)

Create a simple regular polygon with optional rounding.

Parameters:

• verts (int) – The vertex count.

• scale (float) – The scale factor of the polygon.

• roundedness (float) – The roundedness, removes sharp corners. Theoretical limit at infinity is a disk.

Return type:

Polygon

Returns:

The regular (rounded) polygon.

adsorpy.molecule_lib.xyz_reader(file_name, ignore_atoms=None, x_offset=0.0, y_offset=0.0, roll=0.0, pitch=0.0, yaw=0.0, z_trim=None, reference_lattice_spacing=1.0)

Read files in the xyz format of VASP.

Parameters:

• file_name (Path) – The name of the file, including the .xyz extension. Include the path.

• ignore_atoms (str | list[str] | None) – Atoms to ignore when making the molecule. Useful to filter out a slab.

• x_offset (float) – The offset in the x direction.

• y_offset (float) – The offset in the y direction.

• yaw (float) – Rotation along the x-axis.

• pitch (float) – Rotation along the y-axis.

• roll (float) – Rotation along the z-axis.

• z_trim (float | None) – The z value below which all molecules are removed.

• reference_lattice_spacing (float)

Return type:

Polygon

Returns:

The molecule polygon read from the xyz file.

adsorpy.molecule_lib._rotation_matrix(roll, pitch, yaw)

Compute the 3D rotation matrix using roll, pitch, and yaw.

Parameters:

• roll (float | double) – Rotation along the x-axis.

• pitch (float | double) – Rotation along the y-axis.

• yaw (float | double) – Rotation along the z-axis.

Return type:

ndarray[tuple[Literal[3], Literal[3]], dtype[double]]

Returns:

The rotation matrix.

class adsorpy.molecule_lib.MoleculeViewer(atomkeys, atompos, colours, init_roll=None, init_pitch=None, init_yaw=None, init_x_offset=None, init_y_offset=None, lattice=None)

Bases: QDialog

Molecule spatial orientation and structural viewport configuration dashboard.

Manages dynamic 3D rotational coordinate matrices (roll, pitch, yaw) for complex molecular clusters and applies linear structural spatial clipping filters.

Variables:

• _settings – Persistent configuration handle cached across software operational cycles.

• atomkeys – Active slice mappings capturing atomic parameters matching current view states.

• atompos – Active slice mappings capturing 3D coordinates matching current view states.

• colours – Active slice mappings capturing style colour tokens matching current view states.

• lattice (float) – Lattice physical constant constraint baseline scaling factor. Defaults to 1.0.

• show_bonds (bool) – State indicator controlling rendering toggles for chemical covalent bounds.

• atom_toggles (dict[str, QCheckBox]) – Active reference mapping linking atomic symbol labels to operational checkboxes.

• orig_atomkeys – Immutable baseline array tracking atomic keys loaded from source files.

• orig_atompos – Immutable matrix holding coordinates across 3D vector parameters.

• orig_colours – Immutable map listing style colour tokens for individual elements.

• roll – Current rotation angle around the longitudinal axis.

• pitch – Current elevation transformation offset angle.

• yaw – Current horizontal rotation transformation offset angle.

• x_offset – Baseline translation margin parallel to the abscissa.

• y_offset – Baseline translation margin parallel to the ordinate.

• min_z – Bounding minimum depth coordinate calculated from raw coordinates.

• max_z – Bounding maximum depth coordinate calculated from raw coordinates.

• z_cutoff – Active height clipping plane value used to filter hidden elements.

Parameters:

• atomkeys (list[str] | StrArray)

• atompos (CoordsArray3D)

• colours (list[str] | StrArray)

• init_roll (float | None)

• init_pitch (float | None)

• init_yaw (float | None)

• init_x_offset (float | None)

• init_y_offset (float | None)

• lattice (float)

Initialise matrix array buffers, orientation sliders, and plotting canvas frames.

__init__(atomkeys, atompos, colours, init_roll=None, init_pitch=None, init_yaw=None, init_x_offset=None, init_y_offset=None, lattice=None)

Initialise matrix array buffers, orientation sliders, and plotting canvas frames.

Parameters:

• atomkeys (list[str] | ndarray[tuple[int], dtype[str_]])

• atompos (ndarray[tuple[Literal[3], int], ~numpy.dtype[~numpy.float64]])

• colours (list[str] | ndarray[tuple[int], dtype[str_]])

• init_roll (float | None)

• init_pitch (float | None)

• init_yaw (float | None)

• init_x_offset (float | None)

• init_y_offset (float | None)

• lattice (float | None)

Return type:

None

lattice: float

show_bonds: bool

atom_toggles: dict[str, QCheckBox]

property disabled_molecules: list[str] | None

Get a sorted list of disabled atom name keys or None if empty.

Identifies inactive elements via unchecked toggles and sorts them by ascending atomic weight indices using the master database registry.

Returns:

Chronologically sorted elements or None if all toggles are active.

_init_data(atomkeys, atompos, colours, init_roll=None, init_pitch=None, init_yaw=None, init_x_offset=None, init_y_offset=None)

Convert list inputs into persistent raw NumPy matrices and configure boundaries.

Parameters:

• atomkeys (list[str] | ndarray[tuple[int], dtype[str_]]) – list of strings of chemical symbols.

• atompos (ndarray[tuple[Literal[3], int], dtype[double]]) – Intercept array tracking three-dimensional coordinates of atoms.

• colours (list[str] | ndarray[tuple[int], dtype[str_]]) – Vector mapping hexadecimal colour tracking pointers.

• init_roll (float | None) – Baseline matrix orientation transformation offset.

• init_pitch (float | None) – Baseline matrix elevation transformation offset.

• init_yaw (float | None) – Baseline matrix horizontal rotation transformation offset.

• init_x_offset (float | None) – Baseline translation margin parallel to the abscissa.

• init_y_offset (float | None) – Baseline translation margin parallel to the ordinate.

Return type:

tuple[ndarray[tuple[int], dtype[str_]], ndarray[tuple[Literal[3], int], dtype[double]], ndarray[tuple[int], dtype[str_]]]

Returns:

Tuple containing configured baseline instance data arrays.

_fetch_setting(name, default, return_type=None)

Query registry fields from the application storage dictionary profile.

Parameters:

• name (str) – Unique configuration mapping key string tracker.

• default (TypeVar(T, bool, int, str, float)) – Fallback property return object assigned if name is missing.

• return_type (type[TypeVar(T, bool, int, str, float)] | None) – Target data object type enforcement mapping template.

Return type:

TypeVar(T, bool, int, str, float)

Returns:

Configured properties mapped to native execution type constraints.

_create_filter_panel()

Build the panel component hosting Z-cutoff adjustments and checkboxes.

Return type:

QVBoxLayout

Returns:

Main target layout framework representing Column A.

_connect_z_filter(toggle)

Connect when z filter checkbox is toggled.

Parameters:

toggle (bool) – Toggle z filter active/inactive.

Return type:

None

_create_plot_panel()

Build the panel viewport frame displaying rendered molecular assets.

Return type:

QVBoxLayout

Returns:

Main canvas workspace framework representing Column B.

_add_slider_panel(target_layout)

Append transformation sliders directly across the bottom container.

Parameters:

target_layout (QVBoxLayout | QHBoxLayout) – Top-level root layout accepting row insertions.

Return type:

None

toggle_bonds(checked)

Toggle bond rendering on or off and update the view.

Parameters:

checked (bool) – Toggle bond rendering on or off.

Return type:

None

update_z_cutoff(value)

Slot targeting real-time spinbox adjustments to update pipeline state.

Parameters:

value (float) – z-cutoff value to update.

Return type:

None

apply_atom_filters()

Calculate boolean masks against root datasets and handle redraw requests.

Return type:

None

setup_bond_controls(layout)

Create and connect the atomic bond visualisation toggle.

Parameters:

layout (QHBoxLayout | QVBoxLayout) – The QLayout instance (e.g., QVBoxLayout) where the checkbox should be added.

Return type:

None

update_values(val, name, box_widget)

Unifies slider-to-backend slot to keep widgets cleanly scoped.

Parameters:

• val (float) – The value to update the attribute to.

• name (str) – The name of the parameter to update.

• box_widget (QDoubleSpinBox) – The QDoubleSpinBox widget to update.

Return type:

None

setup_lattice_controls(layout)

Create and connect a standalone double spinbox for lattice spacing.

Parameters:

layout (QHBoxLayout | QVBoxLayout) – The layout instance where the widget should be added.

Return type:

None

update_lattice_value(float_val)

Directly sync the backend lattice variable and re-render the SVG canvas.

Parameters:

float_val (float) – The lattice spacing value.

Return type:

None

submit_values(slider_widget, name, box_widget)

Unified spinbox-to-slider slot handling native numerical typing.

Parameters:

• slider_widget (QSlider) – The QSlider instance.

• name (str) – The name of the parameter to update using setattr().

• box_widget (QDoubleSpinBox) – The QDoubleSpinBox instance to link to the slider.

Return type:

None

toggle_svg_background(checked)

Swap rendering canvas stylesheets dynamically.

Parameters:

checked (bool) – True for background, False for foreground.

Return type:

None

transform()

Transform the 3D atom coordinates using the roll, pitch, yaw, x-offset, and y-offset.

Return type:

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

Returns:

The transformed 3D atom coordinates.

_circles(pts, idx1, idx2, offset)

Create svg Circles using the atom coordinates.

Parameters:

• pts (ndarray[tuple[Literal[3], int], dtype[double]]) – The 3D atom coordinates.

• idx1 (Literal[0, 1, 2]) – The first index. 0 = x, 1 = y, 2 = z.

• idx2 (Literal[0, 1, 2]) – The second index. 0 = x, 1 = y, 2 = z.

• offset (float) – The offset from the first axis.

Return type:

list[Circle]

Returns:

A list of svg Circles.

draw()

Draw the molecule projection as a 2D SVG file with 4 tiles.

Top left: xy. Top right: yz. Bottom left: xz. Bottom right: xy van der Waals projection with reference.

Return type:

None

staticMetaObject = PySide6.QtCore.QMetaObject("MoleculeViewer" inherits "QDialog": )

adsorpy.molecule_lib.first_time_loader(file_name, roll=0.0, pitch=0.0, yaw=0.0, x_offset=0.0, y_offset=0.0, ignore_atoms=None, z_trim=None, reference_lattice_spacing=1.0)

Load molecule for the first time to save settings. Uses PySide6.

Parameters:

• file_name (Path) – File path/name for the .xyz file to load the molecule from.

• ignore_atoms (str | list[str] | None) – List of atoms to ignore. Leave empty to interactively toggle all.

• roll (float) – Roll angle in degrees. Leave empty for default.

• pitch (float) – Pitch angle in degrees.

• yaw (float) – Yaw angle in degrees.

• x_offset (float) – X offset in angstrom.

• y_offset (float) – Y offset in angstrom.

• z_trim (float | None) – Z trimming factor in angstrom. Filter all atoms with lower z values.

• reference_lattice_spacing (float) – spacing for the reference lattice in angstrom.

Return type:

dict[str, str | float | list[str] | None]

Returns:

1. “file_name”: str,

2. ”roll”: float,

3. ”pitch”: float,

4. ”yaw”: float,

5. ”x_offset”: float,

6. ”y_offset”: float,

7. ”ignore_atoms”: list[str],

8. ”z_trim”: float | None

adsorpy.molecule_lib._xyz_verifier(atomkeys, atompos, listed_molecule_count)

Check if the .xyz file is of the correct format.

Parameters:

• atomkeys (ndarray[tuple[int], dtype[str_]]) – Atom key values (element abbreviations).

• atompos (ndarray[tuple[Literal[3], int], dtype[double]]) – Atom positions in 3D.

• listed_molecule_count (longlong | None) – Number of molecules according to the file. If None is passed, something is wrong.

Raises:

ValueError –

1. If the .xyz file has no listed molecule count or an invalid count.

2. if the .xyz file’s molecule count does not match the read molecule count.

3. if the .xyz file contains bad molecule names.

4. if the atom keys and atom coordinate lists are not equal in length.

5. if coordinates are nan or infinite.

6. if the coordinates are not 3D.

Return type:

None

adsorpy.molecule_lib._initialise_reader(file_name, ignore_atoms=None, z_trim=None)

Initialise the xyz_reader and first_time_loader.

Parameters:

• file_name (str | Path) – name of the file to read.

• ignore_atoms (str | list[str] | None) – list of atoms to ignore.

• z_trim (float | None) – z value under which to remove the atoms.

Return type:

tuple[ndarray[tuple[int], dtype[str_]], ndarray[tuple[Literal[3], int], dtype[double]]]

Returns:

a tuple of the atom keys and atom positions in 3D. Filtered.

Raises:

ValueError –

1. if the file type is not .xyz

2. if the used settings would return an empty molecule

adsorpy.molecule_lib.save_molecule_svg(molecule, lattice=1.0, filename='')

Save the molecule shape as an SVG with a locked aspect ratio.

Return type:

None

Parameters:

• molecule (Polygon)

• lattice (float)

• filename (str | Path | BytesIO)