geom.classes.molecule ===================== .. py:module:: geom.classes.molecule Classes ------- .. autoapisummary:: geom.classes.molecule.molecule Module Contents --------------- .. py:class:: 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. .. attribute:: atoms List of atom types in the molecule. :type: list[str] .. attribute:: nAtoms Number of atoms in the molecule. :type: int .. attribute:: xyz_center Coordinates of the geometrical center. :type: numpy.ndarray .. attribute:: xyz_min Minimum coordinate values along each axis. :type: numpy.ndarray .. attribute:: xyz_max Maximum coordinate values along each axis. :type: numpy.ndarray .. py:attribute:: atoms :value: [] .. py:attribute:: nAtoms :value: 0 .. py:attribute:: xyz .. py:attribute:: xyz_center .. py:attribute:: xyz_min .. py:attribute:: xyz_max .. py:method:: 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. :rtype: None .. py:method:: read_geom(geom_file, translate_geom_to_000) Reads an XYZ file and stores atomic coordinates. :param geom_file: Path to the XYZ file containing the molecular geometry. :type geom_file: str :param translate_geom_to_000: If True, translates the molecular geometry to the origin. :type translate_geom_to_000: bool :returns: The molecule object with updated atomic coordinates. :rtype: molecule .. rubric:: 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. .. py:method:: change_atomtype(new_atomtype) Changes the atom type for all atoms in the molecule. :param new_atomtype: The new atom type to assign. :type new_atomtype: str :returns: Updated molecule object with modified atom types. :rtype: molecule .. rubric:: Notes - This function is mainly used in core-shell structure creation. .. py:method:: remove_duplicate_xyz(decimals=8) Removes duplicate atomic coordinates from the molecule. :param decimals: Number of decimal places used to compare coordinates. :type decimals: int :returns: Updated molecule object without duplicate XYZ entries. :rtype: molecule .. rubric:: Notes - The first occurrence of each coordinate is preserved. - Atom labels remain aligned with their corresponding XYZ columns. .. py:method:: translate_geom(shift, dir_factor) Translates the molecular geometry along a specified axis. :param shift: The amount to shift the molecule in angstroms. :type shift: float :param dir_factor: The direction factors along x, y, and z axes. :type dir_factor: list[float] :returns: The translated molecule object. :rtype: molecule .. rubric:: Notes - Positive and negative direction factors determine the translation axis. .. py:method:: slice_xyz_by_z_threshold(inp, z_threshold=-0.1) Slice coordinates by eliminating atoms with z ≤ threshold. :param inp: Input parameters (for atom type) :param z_threshold: Threshold value. Atoms with z ≤ this value are removed. :returns: Updated object with sliced coordinates :rtype: self .. py:method:: filter_xyz_graphene_to_ribbon(inp) Filters the graphene sheet to create a ribbon of a specified length and width. :param inp: The input parameters containing X and Y lengths. :type inp: input_class :returns: The filtered molecule containing only atoms within the ribbon. :rtype: molecule .. py:method:: filter_xyz_graphene_to_disk(inp) Filters the graphene sheet to create a disk of a given radius. :param inp: The input parameters containing the disk radius. :type inp: input_class :returns: The filtered molecule containing only atoms within the disk. :rtype: molecule .. py:method:: filter_xyz_graphene_to_ring(inp) Filters the graphene sheet to create a ring structure with an inner and outer radius. :param inp: The input parameters containing inner and outer radius values. :type inp: input_class :returns: The filtered molecule containing only atoms within the ring. :rtype: molecule .. py:method:: filter_xyz_graphene_to_triangle(inp) Filters the graphene sheet to create a triangular structure based on the edge type. :param inp: The input parameters containing side length and edge type. :type inp: input_class :returns: The filtered molecule containing only atoms within the triangle. :rtype: molecule .. py:method:: remove_dangling_bonds_graphene(inp) Removes dangling bonds from a generated graphene structure. :param inp: The input parameters for graphene filtering. :type inp: input_class :returns: The molecule object with dangling atoms removed. :rtype: molecule .. rubric:: Notes - Performs up to 3 iterations to remove all dangling atoms. - If dangling atoms remain after 3 iterations, an error is raised. .. py:method:: filter_xyz_in_sphere(inp) Filters atoms in the molecular geometry, keeping only those inside a sphere of a given radius. :param inp: The input parameters containing sphere radius and center coordinates. :type inp: input_class :returns: Updates the molecule by removing atoms outside the sphere. :rtype: None .. rubric:: 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. .. py:method:: filter_xyz_in_cylinder(inp) Filters atoms in the molecular geometry, keeping only those inside a cylindrical region. :param inp: The input parameters containing cylinder radius, height, and axis orientation. :type inp: input_class :returns: Updates the molecule by removing atoms outside the defined cylindrical region. :rtype: None .. rubric:: 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. .. py:method:: filter_xyz_in_elliptic_paraboloid(inp) Filters atoms in the molecular geometry, keeping only those inside an elliptic paraboloid. :param inp: The input parameters containing coefficients (`a`, `b`, `c`) and height constraints. :type inp: input_class :returns: Updates the molecule by removing atoms outside the elliptic paraboloid. :rtype: None .. rubric:: 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. .. py:method:: filter_xyz_in_pyramid(inp, centers, planes) Filters atoms in the molecular geometry, keeping only those inside a defined pyramid. :param inp: The input parameters containing the atomic type. :type inp: input_class :param centers: Dictionary with center coordinates of the pyramid base and apex. Expected keys: `"center_1"`, `"center_2"`, `"center_3"`, `"center_4"`, `"center_5"`. :type centers: dict :param planes: Dictionary with normal vectors and offsets for the pyramid planes. Expected keys: `"n_125"`, `"n_235"`, `"n_345"`, `"n_415"`. :type planes: dict :returns: The molecule object with updated atomic coordinates. :rtype: molecule .. rubric:: 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. .. py:method:: filter_xyz_in_pentagonal_pyramid(inp, centers, planes) Filters atoms in the molecular geometry, keeping only those inside a defined pentagonal pyramid. :param inp: The input parameters containing the atomic type. :type inp: input_class :param centers: Dictionary with center coordinates of the pyramid base and apex. Expected keys: `"center_1"`, `"center_2"`, `"center_3"`, `"center_4"`, `"center_5"`,`"center_6"`. :type centers: dict :param planes: Dictionary with normal vectors and offsets for the pyramid planes. Expected keys: `"n_126"`, `"n_236"`, `"n_346"`, `"n_456"`, `"n_516"`. :type planes: dict :returns: The molecule object with updated atomic coordinates. :rtype: molecule .. rubric:: 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. .. py:method:: filter_xyz_in_cone(inp) Filters atoms in the molecular geometry, keeping only those inside a cone. :param inp: 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. :type inp: input_class :returns: The molecule object with updated atomic coordinates. :rtype: molecule .. rubric:: 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. .. py:method:: create_icosahedra(inp) Generates an atomically perfect icosahedral nanoparticle using ASE. :param inp: The input parameters containing radius and lattice constants. :type inp: input_class :returns: The generated icosahedral structure. :rtype: molecule .. py:method:: create_cuboctahedra(inp) Generates an atomically perfect cuboctahedral nanoparticle using ASE. :param inp: The input parameters containing radius and lattice constants. :type inp: input_class :returns: The generated cuboctahedral structure. :rtype: molecule .. py:method:: create_decahedra(inp) Generates an atomically perfect decahedral nanoparticle using ASE. :param inp: The input parameters containing radius and lattice constants. :type inp: input_class :returns: The generated decahedral structure. :rtype: molecule .. py:method:: create_alloy(inp) Generates an alloy by randomly substituting a percentage of atoms. :param inp: The input parameters containing alloy composition. :type inp: input_class :returns: The modified molecule with alloyed atoms. :rtype: molecule .. rubric:: Notes - Selects a fraction of atoms and replaces them with the alloy type. - The number of atoms replaced is based on `alloy_perc`. .. py:method:: remove_dangling_atoms_metals(inp) Removes dangling atoms from a generated metal structure. :param inp: The input parameters for metal filtering. :type inp: input_class :returns: The molecule object with dangling atoms removed. :rtype: molecule .. rubric:: Notes - Performs up to 3 iterations to remove all dangling atoms. - If dangling atoms remain after 3 iterations, an error is raised.