Example Code

Examples will be listed here

1. How to install
2. Footprint generation
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 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

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,
) -> InDict:
    """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.