Example Code

Examples will be listed here

1. How to install
2. Footprint generation
   • First time generation
   • Generating a molecule footprint again
3. How to run a simulation, with examples of the various modes
4. ...

How to install

We recommend Pycharm (you can get professional for free with an academic email address) or Visual Studio Code (also free) if you are new to Python.

The easiest way to install adsorpy is via

pip install adsorpy

You can download a specific version by setting

pip install adsorpy==[version number]

but we recommend using the latest (stable) version. Upgrading can be done via

pip install -U adsorpy

How to generate a molecule footprint

First time generation

If you want to generate a footprint for a new molecule, or a new footprint for an existing molecule, use

from adsorpy.molecule_lib import first_time_loader

dict_out = first_time_loader(path_to_your_xyz_file)

Running this code results in an interactive plot window where orientation and offset can be adjusted.

Input can be filtered with the optional arguments. The full function signature is given as:

def first_time_loader(
    file_name: str | Path,
    ignore_atoms: str | list[str] | None = None,
    x_offset: float | None = None,
    y_offset: float | None = None,
    roll: float | None = None,
    pitch: float | None = None,
    yaw: float | None = None,
    z_trim: float | None = None,
    reference_lattice_spacing: float = 4.74,
) -> dict[str, str | float | list[str] | Path | None]:
    """Script to run when you first load the molecule. Shows the molecule in xy, zy, and xz perspective, and vdwaals.

    Can be used to rotate the molecule until satisfied, and will print a string that can be used for the xyz reader.

    :param file_name: File name. Include the path.
    :param ignore_atoms: Atoms to be ignored, optional. Either a string or an iterable of strings.
    :param x_offset: The x offset.
    :param y_offset: The y offset.
    :param roll: Rotation along the x-axis.
    :param pitch: Rotation along the y-axis.
    :param yaw: Rotation along the z axis.
    :param z_trim: Value below which all molecules are ignored.
    :param reference_lattice_spacing: The lattice spacing of the reference grid.
    :return: The updated dict of parameters after rotation and translation.
    """

The ignore_atoms string or list of strings filters out the molecules that are not to be included in the footprint. Example: if you have a molecule on a Cu surface, filtering Cu will result in just the molecule.

If the x_offset, y_offset, roll, pitch, or yaw are not given, they are initialised as 0.

If the z_trim is not given, no trim is applied. All molecules are included, regardless of z value. Example: if you have a molecule on a surface, filtering the z-value where the surface starts results in a footprint of just the molecule.

The reference lattice spacing is a guide to the eye to show you how the molecule will adsorb on the surface.

Closing the plot window results in the printing of a dictionary string containing the molecule parameters at time of closing. These values are also returned with type signature

dict_out: dict[str, str | float | list[str] | Path | None]

n.b.: Path is an import from

from pathlib import Path

It is used to return an OS-agnostic path to the .xyz file of your molecule.

Generating a molecule footprint again

If you have saved your dict_out, you can use it to regenerate an identical molecule:

from adsorpy.molecule_lib import xyz_reader

molecule_polygon = xyz_reader(**dict_out)

The double asterisk unpacks the dictionary as key-value pairs for the function input. The return type is

from shapely import Polygon

molecule_polygon: Polygon

A molecule is supposed to be single Polygon. Generation of MultiPolygons is theoretically possible, but it may have unexpected consequences. Before you use a MultiPolygon, ask: is this what the molecule is supposed to look like?