geom.classes.molecule

Classes

molecule

Represents a molecular system and provides methods for geometry transformations, filtering, and nanostructure creation.

Module Contents

class geom.classes.molecule.molecule

Represents a molecular system and provides methods for geometry transformations, filtering, and nanostructure creation.

This class includes:

• Reading and storing atomic coordinates from XYZ files.

• Geometrical transformations (translation, centering, mirroring).

• Filtering atoms based on predefined geometric shapes (sphere, cylinder, ribbon, disk, triangle, etc.).

• Creating nanostructures (icosahedra, cuboctahedra, decahedra) using ASE.

• Generating alloy structures by random atom substitutions.

Dependencies:

• NumPy: Used for numerical operations on atomic coordinates.

• ASE: Used for nanostructure generation (clusters and nanoparticles).

• functions.output: Handles error messaging and output operations.

• classes.parameters: Provides lattice constants and structural parameters.

atoms

List of atom types in the molecule.

Type:

list[str]

nAtoms

Number of atoms in the molecule.

Type:

int

xyz_center

Coordinates of the geometrical center.

Type:

numpy.ndarray

xyz_min

Minimum coordinate values along each axis.

Type:

numpy.ndarray

xyz_max

Maximum coordinate values along each axis.

Type:

numpy.ndarray

atoms = []

nAtoms = 0

xyz

xyz_center

xyz_min

xyz_max

trans_geom_center_to_000()

Translates the molecular geometry such that its geometrical center moves to (0,0,0).

Returns:

Updates the molecule’s atomic coordinates in place.

Return type:

None

read_geom(geom_file, translate_geom_to_000)

Reads an XYZ file and stores atomic coordinates.

Parameters:

• geom_file (str) – Path to the XYZ file containing the molecular geometry.

• translate_geom_to_000 (bool) – If True, translates the molecular geometry to the origin.

Returns:

The molecule object with updated atomic coordinates.

Return type:

molecule

Notes

• Computes the geometrical center of the structure.

• Stores the minimum and maximum coordinates for bounding box calculations.

• Can output a translated structure if translate_geom_to_000 is set to True.

change_atomtype(new_atomtype)

Changes the atom type for all atoms in the molecule.

Parameters:

new_atomtype (str) – The new atom type to assign.

Returns:

Updated molecule object with modified atom types.

Return type:

molecule

Notes

• This function is mainly used in core-shell structure creation.

remove_duplicate_xyz(decimals=8)

Removes duplicate atomic coordinates from the molecule.

Parameters:

decimals (int) – Number of decimal places used to compare coordinates.

Returns:

Updated molecule object without duplicate XYZ entries.

Return type:

molecule

Notes

• The first occurrence of each coordinate is preserved.

• Atom labels remain aligned with their corresponding XYZ columns.

translate_geom(shift, dir_factor)

Translates the molecular geometry along a specified axis.

Parameters:

• shift (float) – The amount to shift the molecule in angstroms.

• dir_factor (list[float]) – The direction factors along x, y, and z axes.

Returns:

The translated molecule object.

Return type:

molecule

Notes

• Positive and negative direction factors determine the translation axis.

slice_xyz_by_z_threshold(inp, z_threshold=-0.1)

Slice coordinates by eliminating atoms with z ≤ threshold.

Parameters:

• inp – Input parameters (for atom type)

• z_threshold – Threshold value. Atoms with z ≤ this value are removed.

Returns:

Updated object with sliced coordinates

Return type:

self

filter_xyz_graphene_to_ribbon(inp)

Filters the graphene sheet to create a ribbon of a specified length and width.

Parameters:

inp (input_class) – The input parameters containing X and Y lengths.

Returns:

The filtered molecule containing only atoms within the ribbon.

Return type:

molecule

filter_xyz_graphene_to_disk(inp)

Filters the graphene sheet to create a disk of a given radius.

Parameters:

inp (input_class) – The input parameters containing the disk radius.

Returns:

The filtered molecule containing only atoms within the disk.

Return type:

molecule

filter_xyz_graphene_to_ring(inp)

Filters the graphene sheet to create a ring structure with an inner and outer radius.

Parameters:

inp (input_class) – The input parameters containing inner and outer radius values.

Returns:

The filtered molecule containing only atoms within the ring.

Return type:

molecule

filter_xyz_graphene_to_triangle(inp)

Filters the graphene sheet to create a triangular structure based on the edge type.

Parameters:

inp (input_class) – The input parameters containing side length and edge type.

Returns:

The filtered molecule containing only atoms within the triangle.

Return type:

molecule

remove_dangling_bonds_graphene(inp)

Removes dangling bonds from a generated graphene structure.

Parameters:

inp (input_class) – The input parameters for graphene filtering.

Returns:

The molecule object with dangling atoms removed.

Return type:

molecule

Notes

• Performs up to 3 iterations to remove all dangling atoms.

• If dangling atoms remain after 3 iterations, an error is raised.

filter_xyz_in_sphere(inp)

Filters atoms in the molecular geometry, keeping only those inside a sphere of a given radius.

Parameters:

inp (input_class) – The input parameters containing sphere radius and center coordinates.

Returns:

Updates the molecule by removing atoms outside the sphere.

Return type:

None

Notes

• The sphere is centered at inp.sphere_center.

• Any atom with a distance greater than inp.radius from the sphere center is removed.

• This function is commonly used to create spherical nanoparticles.

filter_xyz_in_cylinder(inp)

Filters atoms in the molecular geometry, keeping only those inside a cylindrical region.

Parameters:

inp (input_class) – The input parameters containing cylinder radius, height, and axis orientation.

Returns:

Updates the molecule by removing atoms outside the defined cylindrical region.

Return type:

None

Notes

• The cylinder is aligned along a specified axis (typically the z-axis).

• Any atom outside the given radius (inp.radius) or height (inp.rod_length) is removed.

• Used for generating rod-like nanostructures, such as metallic nanorods.

filter_xyz_in_elliptic_paraboloid(inp)

Filters atoms in the molecular geometry, keeping only those inside an elliptic paraboloid.

Parameters:

inp (input_class) – The input parameters containing coefficients (a, b, c) and height constraints.

Returns:

Updates the molecule by removing atoms outside the elliptic paraboloid.

Return type:

None

Notes

• The elliptic paraboloid is defined by the equation: [ z = c - frac{x^2}{a} - frac{y^2}{b} ]

• Atoms outside this equation’s boundary or beyond inp.z_max_paraboloid are removed.

• Used for modeling paraboloidal nanostructures, such as scanning probe tips.

filter_xyz_in_pyramid(inp, centers, planes)

Filters atoms in the molecular geometry, keeping only those inside a defined pyramid.

Parameters:

• inp (input_class) – The input parameters containing the atomic type.

• centers (dict) – Dictionary with center coordinates of the pyramid base and apex. Expected keys: “center_1”, “center_2”, “center_3”, “center_4”, “center_5”.

• planes (dict) – Dictionary with normal vectors and offsets for the pyramid planes. Expected keys: “n_125”, “n_235”, “n_345”, “n_415”.

Returns:

The molecule object with updated atomic coordinates.

Return type:

molecule

Notes

• The function first checks whether each atom lies within the bounding box of the pyramid.

• Then, the atoms are filtered using the plane equations for each pyramid face.

• The molecule is updated with only the atoms that meet these conditions.

• Computes the new geometrical center, bounding box limits, and atom count.

• The pyramid structure is defined using four planes and a set of center points.

filter_xyz_in_pentagonal_pyramid(inp, centers, planes)

Filters atoms in the molecular geometry, keeping only those inside a defined pentagonal pyramid.

Parameters:

• inp (input_class) – The input parameters containing the atomic type.

• centers (dict) – Dictionary with center coordinates of the pyramid base and apex. Expected keys: “center_1”, “center_2”, “center_3”, “center_4”, “center_5”,`”center_6”`.

• planes (dict) – Dictionary with normal vectors and offsets for the pyramid planes. Expected keys: “n_126”, “n_236”, “n_346”, “n_456”, “n_516”.

Returns:

The molecule object with updated atomic coordinates.

Return type:

molecule

Notes

• The function first checks whether each atom lies within the bounding box of the pyramid.

• Then, the atoms are filtered using the plane equations for each pyramid face.

• The molecule is updated with only the atoms that meet these conditions.

• Computes the new geometrical center, bounding box limits, and atom count.

• The pyramid structure is defined using four planes and a set of center points.

• If the base is not on the XY plane, translate the structure.

filter_xyz_in_cone(inp)

Filters atoms in the molecular geometry, keeping only those inside a cone.

Parameters:

inp (input_class) – The input parameters containing: - radius (float): Base radius of the cone. - z_max (float): Height of the cone. - atomtype (str): The atomic type for the filtered structure.

Returns:

The molecule object with updated atomic coordinates.

Return type:

molecule

Notes

• The cone is aligned along the z-axis with the apex at the origin (0,0,0).

• The equation defining the cone is: [ x^2 + y^2 leq left(frac{text{radius}}{text{z_max}}right)^2 cdot z^2 ]

• Atoms are filtered based on the cone equation and must satisfy 0 ≤ z ≤ inp.z_max.

• The function recomputes:

  • The geometrical center of the new structure.

  • The bounding box limits (xyz_min, xyz_max).

  • The updated list of atoms inside the cone.

• Typically used to shape nano-cones or probe-like structures.

create_icosahedra(inp)

Generates an atomically perfect icosahedral nanoparticle using ASE.

Parameters:

inp (input_class) – The input parameters containing radius and lattice constants.

Returns:

The generated icosahedral structure.

Return type:

molecule

create_cuboctahedra(inp)

Generates an atomically perfect cuboctahedral nanoparticle using ASE.

Parameters:

inp (input_class) – The input parameters containing radius and lattice constants.

Returns:

The generated cuboctahedral structure.

Return type:

molecule

create_decahedra(inp)

Generates an atomically perfect decahedral nanoparticle using ASE.

Parameters:

inp (input_class) – The input parameters containing radius and lattice constants.

Returns:

The generated decahedral structure.

Return type:

molecule

create_alloy(inp)

Generates an alloy by randomly substituting a percentage of atoms.

Parameters:

inp (input_class) – The input parameters containing alloy composition.

Returns:

The modified molecule with alloyed atoms.

Return type:

molecule

Notes

• Selects a fraction of atoms and replaces them with the alloy type.

• The number of atoms replaced is based on alloy_perc.

remove_dangling_atoms_metals(inp)

Removes dangling atoms from a generated metal structure.

Parameters:

inp (input_class) – The input parameters for metal filtering.

Returns:

The molecule object with dangling atoms removed.

Return type:

molecule

Notes

• Performs up to 3 iterations to remove all dangling atoms.

• If dangling atoms remain after 3 iterations, an error is raised.