Core Crystalline Builder

CrystalNPs.py

class pyNanoMatBuilder.crystalNPs.Crystal(crystal: str = 'Au', scaleDmin2: float = None, setSymbols2: ndarray = None, userDefCif: str = None, shape: str = 'sphere', size: float = None, directionsPPD: ndarray = None, buildPPD: str = 'xyz', directionWire: float = None, directionCylinder: float = None, refPlaneWire: float = None, nRotWire: int = 6, hollow_sphere_diameter: float = None, surfacesWulff: ndarray = None, eSurfacesWulff: ndarray = None, sizesWulff: ndarray = None, symWulff: bool = True, aseSymPrec: float = 0.0001, pbc: bool = False, threshold: float = 0.001, dbFolder: str = None, **kwargs)

Bases: pyNMBcore

A class for generating XYZ and CIF files of crystalline nanoparticles (NPs) of various shapes and sizes, based on user-defined compounds (either by name, e.g., “Fe bcc”, or from a CIF file). The supported nanoparticle shapes include:

Spheres
Ellipsoids
Parallelepipeds
Cylinders and wires with different cross-sections
Wulff constructions: cube, octahedron, cuboctahedron, dodecahedron, spheroids, and their truncated versions

Key Features: - Allows to choose the NP size, shape and composition. - Supports Wulff construction with customizable surface energies. - Enables the creation of wires with defined orientations and cross-sections. - Can analyze the structure in detail, including symmetry and properties. - Offers options for core/surface differentiation based on a threshold. - Generates outputs in XYZ and CIF formats for visualization and simulations. - Provides compatibility with jMol for 3D visualization.

Additional Notes: - The symmetry analysis can be skipped to speed up computations. - Periodic boundary conditions (PBC) can be enabled if needed. - Customizable precision thresholds for structural analysis.

Initialize a Crystal nanoparticle generator with specified parameters.

Parameters:

crystal (str) – Chemical element or compound name (default: “Au”). See pyNMBu.ciflist() for available options.
scaleDmin2 (float, optional) – Scale factor for unit cell minimum dimension.
setSymbols2 (np.ndarray, optional) – Array of chemical symbols to replace default.
userDefCif (str, optional) – Path to user-defined CIF file.
shape (str) – Nanoparticle shape. Options: ‘sphere’, ‘ellipsoid’, ‘pppd’ (parallelepiped), ‘wire’, ‘cylinder’, or ‘Wulff: <shape>’ (default: “sphere”).
size (list, optional) – Size specification (format depends on shape): - Sphere: [diameter] - Ellipsoid/Parallelepiped: [size_x, size_y, size_z] - Wire/Cylinder: [cross-section diameter, length]
directionsPPD (np.ndarray, optional) – Three direction vectors for parallelepiped.
buildPPD (str) – Parallelepiped coordinate system: ‘xyz’ or ‘abc’ (default: “xyz”).
directionWire (list, optional) – Wire growth direction (default: [0, 0, 1]).
directionCylinder (list, optional) – Cylinder growth direction (default: [0, 0, 1]).
refPlaneWire (list, optional) – Miller indices of wire reference plane.
nRotWire (int) – Number of rotations for wire cross-section (default: 6).
hollow_sphere_diameter (list, optional) – Hollow sphere diameter (Kirkendall effect).
surfacesWulff (np.ndarray, optional) – Miller indices for Wulff surfaces.
eSurfacesWulff (np.ndarray, optional) – Surface energies for Wulff construction.
sizesWulff (np.ndarray, optional) – Size parameters for Wulff construction.
symWulff (bool) – Apply symmetry to Wulff construction (default: True).
jmolCrystalShape (bool) – Generate JMol visualization script (default: True).
aseSymPrec (float) – Symmetry precision threshold (default: 1e-4).
pbc (bool) – Enable periodic boundary conditions (default: False).
threshold (float) – Plane truncation distance threshold (default: 1e-3).
dbFolder (str, optional) – Database folder path for CIF files.
postAnalyzis (bool) – Perform post-construction analysis (default: True).
aseView (bool) – Enable ASE visualization (default: False).
thresholdCoreSurface (float) – Core/surface differentiation threshold (default: 1.0).
skipSymmetryAnalyzis (bool) – Skip symmetry analysis (default: False).
noOutput (bool) – Suppress printed output (default: False).
calcPropOnly (bool) – Calculate properties only without structure generation (default: False).

loadExternalCif()

Load an external CIF file and extract the crystal name.

Checks if a CIF file is already loaded to avoid redundant loading. Extracts the crystal name from specific CIF tags if available.

Raises:: SystemExit – If the CIF file is not found.

bulk(noOutput)

Retrieve bulk crystal structure parameters.

Loads CIF data from either a user-defined file or the internal database.

Parameters:: noOutput (bool) – If False, prints status information.
Raises:: SystemExit – If crystal not found and no external CIF provided.

makeSuperCell(noOutput)

Create a supercell based on the nanoparticle shape and size.

Determines the appropriate supercell dimensions based on the particle shape, then constructs and centers the supercell at the origin.

Parameters:: noOutput (bool) – If False, details are printed.

makeSphere(noOutput)

Create a spherical nanoparticle by removing atoms outside the defined radius.

Computes dimensions from the provided diameter in nanometers.

Parameters:: noOutput (bool) – If False, details are printed.

makeEllipsoid(noOutput)

Create an ellipsoidal nanoparticle by removing atoms outside the defined ellipsoid.

Parameters:: noOutput (bool) – If False, details are printed.

makeWire(noOutput=False)

Create a nanowire by truncating atoms based on reference planes.

Uses rotated planes around the growth direction to define wire cross-section. Measures and stores the wire length, radius, and volume.

Parameters:: noOutput (bool) – If False, details are printed (default: False).
Returns:: The generated nanowire structure.
Return type:: ase.Atoms

makeCylinder(noOutput=False)

Create a cylindrical nanoparticle.

Aligns the specified direction to the Z-axis, removes atoms outside the cylinder, and measures the resulting dimensions.

Parameters:: noOutput (bool) – If False, details are printed (default: False).
Returns:: The generated cylindrical nanoparticle.
Return type:: ase.Atoms

Note

size = [diameter_nm, length_nm] directionCylinder = [h, k, l]

makeParallelepiped(noOutput)

Create a parallelepiped-shaped nanoparticle.

Truncates atoms based on specified directions. If using Cartesian coordinates (“xyz”), directions are used directly. Otherwise, normal vectors are calculated and lattice transformation is applied.

Parameters:: noOutput (bool) – If False, details are printed.

makeWulff(noOutput)

Calculate truncation distances for Wulff nanoparticles.

Determines truncation planes based on provided surfaces and surface energies. Removes atoms above these planes to create the final shape.

Parameters:: noOutput (bool) – If False, details are printed.

Note

Updates self.trPlanes with normalized truncation planes and distances. Updates self.NP with the truncated structure.

makeNP(noOutput)

Generate a nanoparticle of the specified shape.

Constructs different nanoparticle types based on user-defined shape and size. Supports spheres, ellipsoids, parallelepipeds, wires, cylinders, and Wulff constructions.

Parameters:: noOutput (bool) – If False, details are printed.

Note

Updates self.NP with the generated nanoparticle structure. Updates self.nAtoms, self.cog, and self.trPlanes attributes.

predefinedParameters4WulffShapes(noOutput)

Assign pre-defined parameters for Wulff shapes.

Retrieves pre-defined properties (truncation planes, symmetry, MOI) for Wulff shapes from the internal database. Validates shape compatibility with crystal lattice.

Parameters:: noOutput (bool) – If False, details are printed.

Note

Updates self.eSurfacesWulff, self.surfacesWulff, and self.symWulff.

prop()

Display unit cell and nanoparticle properties.

Parameters:: noOutput (bool) – If False, details are printed.

Geometric Nanoparticle Shapes

platonicNPs.py

class pyNanoMatBuilder.platonicNPs.PlatonicNP(**kwargs)

Bases: pyNMBcore

Base class for all Platonic nanoparticles providing common functionality.

Parameters:

postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

class pyNanoMatBuilder.platonicNPs.regfccOh(element: str = 'Au', Rnn: float = 2.7, nOrder: int = 1, shape: str = 'regfccOh', **kwargs)

Bases: PlatonicNP

A class for generating XYZ and CIF files of regular fcc octahedral nanoparticles (NPs).

Generates NPs of various sizes, based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features:

Allows to choose the NP size.
Can analyze the structure in detail, including symmetry and properties.
Offers options for core/surface differentiation based on a threshold.
Generates outputs in XYZ and CIF formats for visualization and simulations.
Provides compatibility with jMol for 3D visualization.

Additional Notes:

The nOrder parameter determines the level of imbrication.
The symmetry analysis can be skipped to speed up computations.
Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

element (str) – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nOrder (int) – Determines the level of imbrication = the number of atomic layers along an edge (e.g., nOrder=1 means 2 atoms per edge).
shape (str) – Shape ‘regfccOh’.
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

nAtoms

Number of atoms in the NP.

Type:: int

nAtomsPerLayer

Number of atoms in each atomic layer.

Type:: list

nAtomsPerEdge

Number of atoms per edge.

Type:: int

interLayerDistance

Distance between atomic layers.

Type:: float

jmolCrystalShape

Flag for JMol visualization.

Type:: bool

cog

Center of gravity of the NP.

Type:: np.array

imageFile

Path to a reference image.

Type:: str

trPlanes

Truncation plane equations.

Type:: array

nFaces = 8

nEdges = 12

nVertices = 6

edgeLengthF = 1

radiusCSF = np.float64(0.7071067811865476)

radiusISF = np.float64(0.40824829046386296)

radiusMSF = 0.5

dihedralAngle = np.float64(109.47122063449069)

interShellF = np.float64(1.414213562373095)

nAtomsF(i)

Returns the number of atoms of an octahedron of size i.

Parameters:: i (int) – The order or size parameter.
Returns:: The calculated number of atoms.
Return type:: int

nAtomsPerShellAnalytic()

Computes the number of atoms per shell in an ordered nanoparticle.

The function iterates over each shell layer (from 1 to nOrder), computes the number of atoms for the given shell, and subtracts the cumulative sum of the previous shells to get the number of new atoms in the current shell.

Returns:

A list where each element represents the number of atoms: in a specific shell.

Return type:

list

nAtomsPerShellCumulativeAnalytic()

Computes the cumulative number of atoms up to each shell.

This function returns the total number of atoms present in the nanoparticle for each shell layer, building up cumulatively.

Returns:

A list where each element represents the total number of: atoms present up to that shell.

Return type:

list

nAtomsAnalytic()

Computes the total number of atoms in the nanoparticle.

Returns:: Total number of atoms.
Return type:: int

edgeLength()

Computes the edge length of the nanoparticle in Å.

The edge length is determined based on the interatomic distance (Rnn) and the number of atomic layers (nOrder).

Returns:: The edge length in Å.
Return type:: float

radiusCircumscribedSphere()

Computes the radius of the circumscribed sphere of the nanoparticle in Å.

Returns:: Radius.
Return type:: float

radiusInscribedSphere()

Computes the radius of the inscribed sphere of the nanoparticle in Å.

Returns:: Radius.
Return type:: float

radiusMidSphere()

Computes the radius of the midsphere of the nanoparticle in Å.

The midsphere is a sphere that touches the edges of the nanoparticle.

Returns:: Radius.
Return type:: float

area()

Computes the surface area of the nanoparticle in square Ångströms.

Returns:: Surface area.
Return type:: float

volume()

Computes the volume of the nanoparticle in cubic Ångströms.

Returns:: Volume.
Return type:: float

MakeVertices(i)

Generates the coordinates of the vertices, edges, and faces for the ith shell of an octahedral nanoparticle.

Parameters:

i (int) – Index of the shell layer.

Returns:

CoordVertices (np.ndarray): the 6 vertex coordinates
of the ith shell of an octahedron
edges (np.ndarray): indexes of the 30 edges
faces (np.ndarray): indexes of the 20 faces

Return type:

tuple

coords(noOutput)

Generates atomic coordinates for an octahedral nanoparticle.

Parameters:: noOutput (bool) – If False, displays progress and timing information.

Steps:

Generates vertex atoms.
Calculates and places edge atoms along the edges.
Generates facet atoms to fill in faces.
Adds core atoms layer by layer.
Stores final atomic positions in an ASE Atoms object.

Returns:: None (updates class attributes).

calc_sasview_dims(noOutput): Computes the dimensions of the nanoparticle for direct comparison with SasView models.

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.platonicNPs.regIco(element: str = 'Au', Rnn: float = 2.7, nShell: int = 1, shape: str = 'regIco', double_ico: bool = False, **kwargs)

Bases: PlatonicNP

A class for generating XYZ and CIF files of regular icosahedral nanoparticles (NPs).

Generates NPs of various sizes, based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features:

Allows to choose the NP size.
Can analyze the structure in detail, including symmetry and properties.
Offers options for core/surface differentiation based on a threshold.
Generates outputs in XYZ and CIF formats for visualization and simulations.
Provides compatibility with jMol for 3D visualization.

Additional Notes:

The symmetry analysis can be skipped to speed up computations.
Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

element (str) – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nShell (int) – Number of shells = the number of atomic layers along an edge (e.g., nOrder=1 means 2 atoms per edge).
shape (str) – Shape ‘regIco’.
double_ico (bool) – If True, generates a double icosahedron.
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

nAtoms

Number of atoms in the NP.

Type:: int

nAtomsPerShell

Number of atoms in each shell.

Type:: list

interShellDistance

Distance between atomic shells.

Type:: float

jmolCrystalShape

Flag for JMol visualization.

Type:: bool

imageFile

Path to a reference image.

Type:: str

trPlanes

Truncation plane equations.

Type:: array

nFaces = 20

nEdges = 30

nVertices = 12

phi = np.float64(1.618033988749895)

edgeLengthF = 1

radiusCSF = np.float64(0.9510565162951535)

interShellF = np.float64(1.0514622242382672)

radiusISF = np.float64(0.7557613140761706)

nAtomsF(i)

Returns the number of atoms of an icosahedron of size i.

Parameters:: i (int) – The shell number or size parameter.
Returns:: The calculated number of atoms.
Return type:: int

nAtomsPerShellAnalytic()

Computes the number of atoms per shell in an ordered nanoparticle.

The function iterates over each shell layer, computes the number of atoms for the given shell, and subtracts the cumulative sum of the previous shells to get the number of new atoms in the current shell.

Returns:

A list where each element represents the number of atoms: in a specific shell.

Return type:

list

nAtomsPerShellCumulativeAnalytic()

Computes the cumulative number of atoms up to each shell.

This function returns the total number of atoms present in the nanoparticle for each shell layer, building up cumulatively.

Returns:

A list where each element represents the total number of: atoms present up to that shell.

Return type:

list

nAtomsAnalytic()

Computes the total number of atoms in the nanoparticle.

Returns:: Total number of atoms.
Return type:: int

edgeLength()

Computes the edge length of the nanoparticle in Å.

The edge length is determined based on the interatomic distance (Rnn) and the number of shells (nShell).

Returns:: Edge length in Å.
Return type:: float

radiusCircumscribedSphere()

Computes the radius of the circumscribed sphere of the nanoparticle in Å.

Returns:: Radius.
Return type:: float

radiusInscribedSphere()

Computes the radius of the inscribed sphere of the nanoparticle in Å.

Returns:: Radius.
Return type:: float

area()

Computes the surface area of the nanoparticle in square Ångströms.

Returns:: Surface area.
Return type:: float

volume()

Computes the volume of the nanoparticle in cubic Ångströms.

Returns:: Volume.
Return type:: float

MakeVertices(i)

Generates the coordinates of the vertices, edges, and faces for the ith shell of an icosahedral nanoparticle.

Parameters:

i (int) – Index of the shell.

Returns:

CoordVertices (np.ndarray): the 12 vertex coordinates of the ith shell of an icosahedron
edges (np.ndarray): indexes of the 30 edges
faces (np.ndarray): indexes of the 20 faces

Return type:

tuple

edges_to_planes(coords)

Converts a list of edges in planes equations [u, v, w, d].

Parameters:: coords (np.ndarray) – Atoms coordinates.
Returns:: List of planes equations [u, v, w, d].
Return type:: planes (list of np.ndarray)

edges_to_planes2(coords)

Converts a list of edges in planes equations [u, v, w, d].

Parameters:: coords (np.ndarray) – Atoms coordinates.
Returns:: List of planes equations [u, v, w, d].
Return type:: planes (list of np.ndarray)

coords(noOutput)

Generates atomic coordinates for an icosahedral nanoparticle.

Parameters:: noOutput (bool) – If False, displays progress and timing information.

Steps:

Generates vertex atoms.
Calculates and places edge atoms along the edges.
Generates facet atoms to fill in faces.
Stores final atomic positions in an ASE Atoms object.

Returns:: None (updates class attributes).

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.platonicNPs.regfccTd(element: str = 'Au', Rnn: float = 2.7, nLayer: int = 1, shape: str = 'regfccTd', n_Td: int = 1, **kwargs)

Bases: PlatonicNP

A class for generating XYZ and CIF files of regular fcc tetrahedral nanoparticles (NPs).

Generates NPs of various sizes based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features:

Allows to choose the NP size.
Can analyze the structure in detail, including symmetry and properties.
Offers options for core/surface differentiation based on a threshold.
Generates outputs in XYZ and CIF formats for visualization and simulations.
Provides compatibility with jMol for 3D visualization.

Additional Notes:

The symmetry analysis can be skipped to speed up computations.
Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

element (str) – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nLayer (int) – Number of layers, also equals to the number of atoms per edge (e.g., nOrder=2 means 2 atoms per edge).
shape (str) – Shape ‘regfccTd’.
n_Td (int) – The number of tetrahedrons in the optional helix.
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

nAtoms

Number of atoms in the NP.

Type:: int

nAtomsPerLayer

Number of atoms in each atomic layer.

Type:: list

nAtomsPerEdge

Number of atoms per edge.

Type:: int

jmolCrystalShape

Flag for JMol visualization.

Type:: bool

cog

Center of gravity of the NP.

Type:: np.array

imageFile

Path to a reference image.

Type:: str

trPlanes

Truncation plane equations.

Type:: array

nFaces = 4

nEdges = 6

nVertices = 4

edgeLengthF = 1

heightOfPyramidF = np.float64(0.816496580927726)

radiusCSF = np.float64(0.6123724356957945)

radiusISF = np.float64(0.20412414523193154)

radiusMSF = np.float64(0.35355339059327373)

fveAngle = np.float64(54.735610317245346)

fefAngle = np.float64(70.52877936550931)

vcvAngle = np.float64(109.47122063449069)

nAtomsF(i): Returns the number of atoms of a tetrahedron of size i.

nAtomsPerLayerAnalytic()

Computes the number of atoms per shell in an ordered nanoparticle.

The function iterates over each layer, computes the number of atoms for the given layer, and subtracts the cumulative sum of the previous shells to get the number of new atoms in the current layer.

Returns:

A list where each element represents the number of atoms: in a specific layer.

Return type:

list

nAtomsAnalytic(): Computes the total number of atoms in the nanoparticle.

edgeLength()

Computes the edge length of the nanoparticle in Å.

The edge length is determined based on the interatomic distance (Rnn) and the number of atomic layers (nLayer).

heightOfPyramid(): Computes the length of the height of the pyramid in Å.

interLayerDistance(): Computes the distance between the layers in Å.

radiusCircumscribedSphere(): Computes the radius of the circumscribed sphere of the nanoparticle in Å.

radiusInscribedSphere(): Computes the radius of the inscribed sphere of the nanoparticle in Å.

radiusMidSphere()

Computes the radius of the midsphere of the nanoparticle in Å.

The midsphere is a sphere that touches the edges of the nanoparticle.

area(): Computes the surface area of the nanoparticle in square Ångströms.

volume(): Computes the volume of the nanoparticle in cubic Ångströms.

MakeVertices(nL)

Generates the coordinates of the vertices, edges, and faces for the ith shell of a tetrahedral nanoparticle.

Parameters:

nL (int) – number of layers = number of atoms per edge.

Returns:

the 4 vertex coordinates of a tetrahedron. - edges (np.ndarray): indexes of the 6 edges. - faces (np.ndarray): indexes of the 4 faces.

Return type:

CoordVertices (np.ndarray)

coords(noOutput)

Generates atomic coordinates for a tetrahedral nanoparticle.

Parameters:: noOutput (bool) – If False, displays progress and timing information.

Steps:

Generates vertex atoms.
Calculates and places edge atoms along the edges.
Generates facet atoms to fill in faces.
Adds core atoms layer by layer.
Stores final atomic positions in an ASE Atoms object.

Returns:: None (updates class attributes).

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.platonicNPs.regDD(element: str = 'Au', Rnn: float = 2.7, nShell: int = 1, shape: str = 'regDD', **kwargs)

Bases: PlatonicNP

A class for generating XYZ and CIF files of regular dodecahedral nanoparticles (NPs).

Generates NPs of various sizes based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features:

Allows to choose the NP size.
Can analyze the structure in detail, including symmetry and properties.
Offers options for core/surface differentiation based on a threshold.
Generates outputs in XYZ and CIF formats for visualization and simulations.
Provides compatibility with jMol for 3D visualization.

Additional Notes:

The symmetry analysis can be skipped to speed up computations.
Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

element (str) – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nShell (int) – Number of shells (e.g., nShell=1 means 2 atoms per edge).
shape (str) – Shape ‘regDD’.
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

nAtoms

Number of atoms in the NP.

Type:: int

nAtomsPerShell

Number of atoms in each shell.

Type:: list

interShellDistance

Distance between shells.

Type:: float

jmolCrystalShape

Flag for JMol visualization.

Type:: bool

imageFile

Path to a reference image.

Type:: str

trPlanes

Truncation plane equations.

Type:: array

nFaces = 12

nEdges = 30

nVertices = 20

phi = np.float64(1.618033988749895)

edgeLengthF = 1

radiusCSF = np.float64(1.4012585384440734)

interShellF = np.float64(0.7136441795461799)

radiusISF = np.float64(1.1135163644116068)

nAtomsF(i): Returns the number of atoms of a dodecahedron of size i.

nAtomsPerShellAnalytic()

Computes the number of atoms per shell in an ordered nanoparticle.

The function iterates over each shell layer, computes the number of atoms for the given shell, and subtracts the cumulative sum of the previous shells to get the number of new atoms in the current shell.

Returns:

A list where each element represents the number of: atoms in a specific shell.

Return type:

list

nAtomsAnalytic(): Computes the total number of atoms in the nanoparticle.

edgeLength()

Computes the edge length of the nanoparticle in Å.

The edge length is determined based on the interatomic distance (Rnn) and the number of shells (nShell).

radiusCircumscribedSphere(): Computes the radius of the circumscribed sphere of the nanoparticle in Å.

radiusInscribedSphere(): Computes the radius of the inscribed sphere of the nanoparticle in Å.

area(): Computes the surface area of the nanoparticle in square Ångströms.

volume(): Computes the volume of the nanoparticle in cubic Ångströms.

MakeVertices(i)

Generates the coordinates of the vertices, edges, and faces for the ith shell of a dodecahedral nanoparticle.

Parameters:

i (int) – Index of the shell.

Returns:

the 20 vertex coordinates of the ith shell of a dodecahedron. - edges (np.ndarray): indexes of the 30 edges. - faces (np.ndarray): indexes of the 12 faces.

Return type:

CoordVertices (np.ndarray)

coords(noOutput)

Generates atomic coordinates for a dodecahedral nanoparticle.

Parameters:: noOutput (bool) – If False, displays progress and timing information.

Steps:

Generates vertex atoms.
Calculates and places edge atoms along the edges.
Generates facet atoms to fill in faces.
Stores final atomic positions in an ASE Atoms object.

Returns:: None (updates class attributes).

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.platonicNPs.cube(crystalStructure='fcc', element='Au', Rnn: float = 2.7, nOrder: int = 1, size: int = 0, shape: str = 'cube', **kwargs)

Bases: PlatonicNP

A class for generating XYZ and CIF files of cubic nanoparticles (NPs).

Generates NPs of various sizes based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features:

Allows to choose the NP size.
Can analyze the structure in detail, including symmetry and properties.
Offers options for core/surface differentiation based on a threshold.
Generates outputs in XYZ and CIF formats for visualization and simulations.
Provides compatibility with jMol for 3D visualization.

Additional Notes:

The nOrder parameter determines the level of imbrication.
The symmetry analysis can be skipped to speed up computations.
Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

crystalStructure (str) – The crystal structure of the NP (e.g., ‘fcc’, ‘bcc’).
element (str) – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nOrder (int) – Determines the level of imbrication = the number of atomic layers along an edge (e.g., nOrder=1 means 2 atoms per edge).
size (float) – Size of the cube in nm.
shape (str) – Shape of the nanoparticle. Defaults to ‘cube’.
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

nAtoms

Number of atoms in the NP.

Type:: int

nAtomsPerShell

Number of atoms in each shell.

Type:: list

nAtomsPerEdge

Number of atoms per edge.

Type:: int

interLayerDistance

Distance between atomic layers.

Type:: float

jmolCrystalShape

Flag for JMol visualization.

Type:: bool

cog

Center of gravity of the NP.

Type:: np.array

imageFile

Path to a reference image.

Type:: str

trPlanes

Truncation plane equations.

Type:: array

nFaces = 6

nEdges = 12

nVertices = 8

edgeLengthFfcc = np.float64(1.4142135623730951)

edgeLengthFbcc = np.float64(1.1547005383792517)

radiusCSF = np.float64(0.8660254037844386)

radiusISF = 0.5

nAtomsfccF(i)

Returns the number of atoms of an fcc cube of size i x i x i.

Parameters:: i (int) – The size parameter corresponding to nOrder.
Returns:: The calculated number of atoms.
Return type:: int

nAtomsbccF(i)

Returns the number of atoms of a bcc cube of size i x i x i.

Parameters:: i (int) – The size parameter corresponding to nOrder.
Returns:: The calculated number of atoms.
Return type:: int

nAtomsPerShellAnalytic()

Computes the number of atoms per shell in an ordered nanoparticle.

The function iterates over each shell layer (from 1 to nOrder), computes the number of atoms for the given shell, and subtracts the cumulative sum of the previous shells to get the number of new atoms in the current shell.

Returns:

A list where each element represents the number of atoms: in a specific shell.

Return type:

list

nAtomsPerShellCumulativeAnalytic()

Computes the cumulative number of atoms up to each shell.

This function returns the total number of atoms present in the nanoparticle for each shell layer, building up cumulatively.

Returns:

A list where each element represents the total number of: atoms present up to that shell.

Return type:

list

nAtomsfccAnalytic()

Computes the total number of atoms in the fcc nanoparticle.

Returns:: Total number of atoms.
Return type:: int

nAtomsbccAnalytic()

Computes the total number of atoms in the bcc nanoparticle.

Returns:: Total number of atoms.
Return type:: int

edgeLength()

Computes the edge length of the nanoparticle in Å.

The edge length is determined based on the interatomic distance (Rnn), the number of atomic layers (nOrder) and the crystalStructure (fcc or bcc).

Returns:: The edge length in Å.
Return type:: float

latticeConstant()

Computes the lattice constant of the nanoparticle in Å.

Based on the interatomic distance (Rnn) and the crystalStructure (fcc or bcc).

Returns:: The lattice constant in Å.
Return type:: float

radiusCircumscribedSphere()

Computes the radius of the circumscribed sphere of the nanoparticle in Å.

Returns:: Radius.
Return type:: float

radiusInscribedSphere()

Computes the radius of the inscribed sphere of the nanoparticle in Å.

Returns:: Radius.
Return type:: float

area()

Computes the surface area of the nanoparticle in square Ångströms.

Returns:: Surface area.
Return type:: float

volume()

Computes the volume of the nanoparticle in cubic Ångströms.

Returns:: Volume.
Return type:: float

coords(noOutput)

Generates atomic coordinates for a cubic nanoparticle.

Parameters:: noOutput (bool) – If False, displays progress and timing information.

Steps:

Generates vertex atoms.
Calculates and places edge atoms along the edges.
Generates facet atoms to fill in faces.
Adds core atoms layer by layer.
Stores final atomic positions in an ASE Atoms object.

Returns:: None (updates class attributes).

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.platonicNPs.hollow_shapes(full_cube, nOrder_hollow: int = 0, **kwargs)

Bases: PlatonicNP

A class for generating XYZ and CIF files of hollow cubic nanoparticles (NPs).

Creates NPs with customizable sizes and compositions. Users can define the composition by specifying element names (e.g., “Fe”, “Au”) and provide a “cube” class instance from this module to construct the nanoparticle structure.

Key Features:

Allows to choose the cube size and the
size of its hollow.
Can analyze the structure in detail,
including symmetry and properties.
Offers options for core/surface
differentiation based on a threshold.
Generates outputs in XYZ and CIF formats
for visualization and simulations.
Provides compatibility with jMol for 3D
visualization.

Additional Notes:

The symmetry analysis can be skipped to speed up computations.
Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

full_cube (cube) – Instance of the class “cube” of the module “pNP”.
nOrder_hollow (int) – Size of the hollow in nOrder (number of atomic layers along an edge).
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

nAtoms

Number of atoms in the NP.

Type:: int

cog

Center of gravity of the NP.

Type:: np.array

create_hollow(noOutput)

Function that creates the cube hollow.

The hollow is created using planes that defines the hollow [h k l d] with d= +/- size of the hollow/2. Update: the hollow size is given in nOrder of atomic layers.

Parameters:: noOutput (bool) – If False, prints details about the NP structure.

archimedeanNPs.py

class pyNanoMatBuilder.archimedeanNPs.ArchimedeanNP(**kwargs)

Bases: PlatonicNP

Base class for all Archimedean nanoparticles providing common functionality.

Parameters:

postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

class pyNanoMatBuilder.archimedeanNPs.fccCubo(element: str = 'Au', Rnn: float = 2.7, nShell: int = 1, **kwargs)

Bases: ArchimedeanNP

A class for generating XYZ and CIF files of fcc cuboctahedral nanoparticles (NPs) of various sizes, based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Parameters:

element (str) – Chemical element symbol (e.g. “Au”).
Rnn (float) – Nearest-neighbour distance in Å.
nShell (int) – Number of shells (controls imbrication).
postAnalyzis (bool) – If True, run post-construction analysis.
aseView (bool) – If True, show the structure via ASE viewer.
thresholdCoreSurface (float) – Threshold for core/surface separation.
skipSymmetryAnalyzis (bool) – If True, skip symmetry analysis.
jmolCrystalShape (bool) – If True, enable jMol script generation.
noOutput (bool) – If True, suppress printing.
calcPropOnly (bool) – If True, only compute properties, skip coords.

nAtoms

Number of atoms in the NP.

Type:: int

nAtomsPerShell

Number of atoms in each shell.

Type:: list

interShellDistance

Distance between shells.

Type:: float

Initialize the class with all necessary parameters.

Parameters:

element – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nShell (int) – Determines the level of imbrication = the number of atomic layers along an edge (e.g., nShell=1 means 2 atoms per edge).
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

self.shape

Shape ‘fccCubo’

Type:: str

self.nAtoms

Number of atoms in the NP.

Type:: int

self.nAtomsPerShell

Number of atoms in each shell.

Type:: list

self.interShellDistance

Distance between shells.

Type:: float

self.jmolCrystalShape

Flag for JMol visualization.

Type:: bool

self.imageFile

Path to a reference image.

Type:: str

self.trPlanes

Truncation plane equations.

Type:: array

nFaces = 14

nEdges = 24

nVertices = 12

edgeLengthF = 1

radiusCSF = 1

interShellF = 1.0

radiusISF = 0.75

nAtomsF(i)

Return analytic number-of-atoms factor for size i.

Parameters:: i (int) – Size/order parameter.
Returns:: Analytic count factor.
Return type:: int

nAtomsPerShellAnalytic()

Computes the number of atoms per shell in an ordered nanoparticle.

The function iterates over each shell layer, computes the number of atoms for the given shell, and subtracts the cumulative sum of the previous shells to get the number of new atoms in the current shell.

Returns:

A list where each element represents the number of atoms: in a specific shell.

Return type:

list

nAtomsPerShellCumulativeAnalytic()

Computes the cumulative number of atoms up to each shell.

This function returns the total number of atoms present in the nanoparticle for each shell layer, building up cumulatively.

Returns:

A list where each element represents the total number of: atoms present up to that shell.

Return type:

list

nAtomsAnalytic(): Computes the total number of atoms in the nanoparticle.

edgeLength()

Computes the edge length of the nanoparticle in Å .

The edge length is determined based on the interatomic distance (Rnn) and the number of shells (nShell).

radiusCircumscribedSphere()

Radius of the circumscribed sphere in Å.

Returns:: Radius in Å.
Return type:: float

radiusInscribedSphere()

Radius of the inscribed sphere (Å).

Returns:: Radius in Å.
Return type:: float

area(): Computes the surface area of the nanoparticle in square Ångströms.

volume(): Computes the volume of the nanoparticle in cubic Ångströms.

MakeVertices(i)

Generates the coordinates of the vertices, edges, and faces for the ith shell of the nanoparticle. :param - i: index of the shell :type - i: int

Returns:

CoordVertices = the 12 vertex coordinates of the ith shell of an icosahedron
edges (np.ndarray): indexes of the 30 edges
faces (np.ndarray): indexes of the 20 faces

coords(noOutput)

Generate the coordinates of a cuboctahedral nanoparticle.

Args: - noOutput (bool): If True, suppresses output messages.

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.archimedeanNPs.fccTrTd(element: str = 'Au', Rnn: float = 2.7, nLayer: int = 1, **kwargs)

Bases: ArchimedeanNP

A class for generating XYZ and CIF files of fcc truncated tetrahedral nanoparticles (NPs) of various sizes, based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features: - Allows to choose the NP size. - Can analyze the structure in detail, including symmetry and properties. - Offers options for core/surface differentiation based on a threshold. - Generates outputs in XYZ and CIF formats for visualization and simulations. - Provides compatibility with jMol for 3D visualization.

Additional Notes: - The symmetry analysis can be skipped to speed up computations. - Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

element – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nLayer (int) – Number of layers, also equals to the number of atoms per edge (e.g., nLayer=2 means 2 atoms per edge).
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

self.shape

Shape ‘fccTrTd’

Type:: str

self.nAtoms

Number of atoms in the NP.

Type:: int

self.cog

Center of gravity of the NP.

Type:: np.array

self.Tdprop

Class “regfccTd” of the module “pNP” (creates regular fcc tetrahedron)

Type:: class instance

self.interLayerDistance

Distance between two layers in Å.

Type:: float

self.nAtomsPerEdge

Number of atoms per edge.

Type:: int

self.jmolCrystalShape

Flag for JMol visualization.

Type:: bool

self.imageFile

Path to a reference image.

Type:: str

self.trPlanes

Truncation plane equations.

Type:: array

nFaces3 = 4

nFaces6 = 4

nEdges = 18

nVertices = 12

edgeLengthF = 1

radiusCSF = np.float64(1.1726039399558574)

radiusMSF = np.float64(1.0606601717798214)

cutFromVertexAt = 0.3333333333333333

nAtomsF(i): Returns a factor to compute the number of atoms of a nanoparticle of size i.

nAtomsAnalytic()

Compute the total number of atoms analytically.

Returns:: Total number of atoms for the current nAtomsPerEdge.
Return type:: int

edgeLength()

Computes the edge length of the nanoparticle in Å .

The edge length of the truncated tetrahedron equals the regular tetrahedron’s edge length divided by 3.

radiusCircumscribedSphere(): Computes the radius of the circumscribed sphere of the nanoparticle in Å.

radiusMidSphere()

Radius of the midsphere (Å), tangent to edges.

Returns:: Radius in Å.
Return type:: float

area(): Computes the surface area of the nanoparticle in square Ångströms.

volume(): Computes the volume of the nanoparticle in cubic Ångströms.

magicEdgeNumberOfTd2MakeATrTd(index: int): Returns the number of edge atoms of the tetrahedron that will lead to perfect trucated tetrahedron with all edges of equal atomic length.

NumberOfTdEdgeAtomsValid4ATrTd()

Calculate the number of edge atoms in a truncated tetrahedral nanoparticle and check if it is a valid integer.

Returns:: A tuple where the first element is True if the number is an integer, and the second element is the computed number of edge atoms.
Return type:: (bool, float)

coords(noOutput)

Generate coordinates for the truncated octahedron.

Parameters:: noOutput (bool) – If True, suppress printing and progress output.

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.archimedeanNPs.fccTrOh(element: str = 'Au', Rnn: float = 2.7, nOrder: int = 1, **kwargs)

Bases: ArchimedeanNP

A class for generating XYZ and CIF files of fcc truncated octahedral nanoparticles (NPs) of various sizes, based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features: - Allows to choose the NP size. - Can analyze the structure in detail, including symmetry and properties. - Offers options for core/surface differentiation based on a threshold. - Generates outputs in XYZ and CIF formats for visualization and simulations. - Provides compatibility with jMol for 3D visualization.

Additional Notes: - The nOrder parameter determines the level of imbrication - The symmetry analysis can be skipped to speed up computations. - Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

element – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nOrder (int) – Determines the level of imbrication = the number of atomic layers along an edge (e.g., nOrder=1 means 2 atoms per edge).
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

self.Ohprop

class “regfccOh” of the module “pNP”

Type:: class instance

self.self.cog

Center of gravity of the NP.

Type:: np.array

self.nAtoms

Number of atoms in the NP.

Type:: int

self.nAtomsPerEdge

Number of atoms per edge.

Type:: int

self.interLayerDistance

Distance between atomic layers.

Type:: float

self.jmolCrystalShape

Flag for JMol visualization.

Type:: bool

self.cog

Center of gravity of the NP.

Type:: np.array

self.imageFile

Path to a reference image.

Type:: str

self.trPlanes

Truncation plane equations.

Type:: array

nFaces4 = 6

nFaces6 = 8

nEdges = 36

nVertices = 24

edgeLengthF = 1

radiusCSF = np.float64(1.5811388300841898)

radiusMSF = 1.5

radiusISF = np.float64(1.4230249470757708)

cutFromVertexAt = 0.3333333333333333

nAtomsF(i)

Factor used to compute number of atoms for size i.

Parameters:: i (int) – Size/order parameter.
Returns:: Analytic factor for atom count.
Return type:: int

nAtomsAnalytic(): Computes the total number of atoms in the nanoparticle.

edgeLength()

Edge length (Å) of the truncated octahedron.

Returns:: Edge length in Å.
Return type:: float

sasview_dims()

Return dimensions compatible with SasView.

In pyNanoMatBuilder truncation is defined by the ratio d(truncated_edge)/d(edge) while SasView expects the ratio d(truncated_demi_axis)/d(demi_axis). This routine computes the full demi-axis and the truncated demi-axis and returns both the demi-axis and the truncature ratio.

Returns:: (demi_axis, truncature_ratio)
Return type:: tuple

octahedron_truncated_volume(length_a, t): Volume of a truncated octahedron with edge length length_a and truncation parameter t. t is defined as the ratio of the truncated edge length to the original edge length.

radiusCircumscribedSphere(): Computes the radius of the circumscribed sphere of the nanoparticle in Å.

radiusMidSphere(): Computes the radius of the midsphere of the nanoparticle in Å. The midsphere is a sphere that touches the edges of the nanoparticle.

radiusInscribedSphere(): Computes the radius of the inscribed sphere of the nanoparticle in Å .

area()

Surface area in Å^2.

Returns:: Surface area in square Ångström.
Return type:: float

volume()

Volume in Å^3.

Returns:: Volume in cubic Ångström.
Return type:: float

magicEdgeNumberOfOh2MakeATrOh(index: int)

Compute the number of edge atoms of the octahedron that will lead to perfect trucated tetrahedra with all edges of equal atomic length. :param index: The maximum number of edge atoms to consider. :type index: int

Returns:: An array of valid numbers of edge atoms for truncated octahedra.
Return type:: np.array

NumberOfOhEdgeAtomsValid4ATrOh()

Calculate the number of edge atoms in a truncated octahedral nanoparticle and check if it is a valid integer.

Returns:

(is_integer (bool), nTrOh (float)) where is_integer flags: whether the computed number of atoms per edge is integer.

Return type:

tuple

coords(noOutput)

Generate the coordinates of a truncated tetrahedral nanoparticle.

Args: - noOutput (bool): If True, suppresses output messages.

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.archimedeanNPs.fccTrCube(element: str = 'Au', Rnn: float = 2.7, nOrder: int = 1, **kwargs)

Bases: ArchimedeanNP

Truncated cubic nanoparticle (FCC) builder.

Generates XYZ/CIF outputs for fcc truncated cubes of various sizes.

Parameters:

element (str) – Chemical element symbol, e.g. “Au”.
Rnn (float) – Nearest-neighbour distance in Å.
nOrder (int) – Order/size parameter (number of layers along an edge).
postAnalyzis (bool) – If True, run post-construction analysis.
aseView (bool) – If True, show the structure using ASE viewer.
thresholdCoreSurface (float) – Threshold for core/surface separation.
skipSymmetryAnalyzis (bool) – If True, skip symmetry analysis.
jmolCrystalShape (bool) – If True, enable jMol script generation.
noOutput (bool) – If True, suppress printing.
calcPropOnly (bool) – If True, only compute properties, skip coords.

cubeProp: Instance of pNP.cube used as base geometry.

trPlanes: Truncation plane equations (if any).

nAtomsPerEdge

Number of atoms on an edge after truncation.

Type:: int

cog

Center of gravity of the final nanoparticle.

Type:: np.ndarray

Parameters:

postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

nFaces3 = 8

nFaces8 = 6

nEdges = 36

nVertices = 24

edgeLengthF = 1

radiusCSF = np.float64(1.7788236456639244)

radiusMSF = np.float64(1.7071067811865475)

radiusISF = np.float64(1.6382813268065142)

CornersAt = np.float64(0.2928932188134524)

magic_angle = np.float64(0.9553166181245092)

cutFromVertexAt = np.float64(0.16910197872576274)

NumberOfCubeEdgeAtomsValid4ATrCube(): Calculates the approximate number of atoms remaining on an edge.

edgeLength(): Edge length in Ångström for the truncated cube.

prop(): Display unit cell and nanoparticle properties.

catalanNPs.py

class pyNanoMatBuilder.catalanNPs.CatalanNP(**kwargs)

Bases: pyNMBcore

Base class for all Catalan nanoparticles providing common functionality.

Parameters:

postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

class pyNanoMatBuilder.catalanNPs.bccrDD(element: str = 'Au', Rnn: float = 2.7, nShell: int = 1, **kwargs)

Bases: CatalanNP

A class for generating XYZ and CIF files of rhombic dodecahedral nanoparticles (NPs) of various sizes, based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features: - Allows to choose the NP size. - Can analyze the structure in detail, including symmetry and properties. - Offers options for core/surface differentiation based on a threshold. - Generates outputs in XYZ and CIF formats for visualization and simulations. - Provides compatibility with jMol for 3D visualization.

Additional Notes: - The symmetry analysis can be skipped to speed up computations. - Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

element – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nShell (int) – Number of shells (e.g., nShell=1 means 2 atoms per edge).
postAnalyzis (bool) – If True, prints additional NP information. Examples: cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation. This is the distance threshold used to decide which atoms are retained.
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

self.shape

Shape ‘bccrDD’

Type:: str

self.nAtoms

Number of atoms in the NP.

Type:: int

self.nAtomsPerShell

Number of atoms in each shell.

Type:: list

self.interShellDistance3

Distance between shells at order 3.

Type:: float

self.interShellDistance4

Distance between shells at order 4.

Type:: float

self.cog

Center of gravity of the NP.

Type:: np.array

self.jmolCrystalShape

Flag for JMol visualization.

Type:: bool

self.imageFile

Path to a reference image.

Type:: str

nFaces = 12

nEdges = 24

nVertices = 14

edgeLengthF = 1

radiusCSF3rdOrderV = 1

radiusCSF4thOrderV = np.float64(1.1547005383792515)

radiusISF = np.float64(0.8164965809277259)

radiusMSF = np.float64(0.9428090415820635)

interShellF3 = 1.0

interShellF4 = np.float64(0.8660254037844387)

nAtomsF(i): returns the number of atoms of an bcc rhombic dodecahedron of size i

nAtomsPerShellAnalytic()

Computes the number of atoms per shell in an ordered nanoparticle.

The function iterates over each shell layer, computes the number of atoms for the given shell, and subtracts the cumulative sum of the previous shells to get the number of new atoms in the current shell.

Returns:

A list where each element represents the number of atoms: in a specific shell.

Return type:

list

nAtomsPerShellCumulativeAnalytic()

Computes the cumulative number of atoms up to each shell.

This function returns the total number of atoms present in the nanoparticle for each shell layer, building up cumulatively.

Returns:

A list where each element represents the total number of: atoms present up to that shell.

Return type:

list

nAtomsAnalytic(): Computes the total number of atoms in the nanoparticle.

edgeLength()

Computes the edge length of the nanoparticle in Å .

The edge length is determined based on the interatomic distance (Rnn) and the number of shells (nShell).

radiusCircumscribedSphere3(): Computes the radius of the circumscribed sphere at 3th order of the nanoparticle in Å.

radiusCircumscribedSphere4(): Computes the radius of the circumscribed sphere at 4th order of the nanoparticle in Å.

radiusMidSphere(): Computes the radius of the midsphere of the nanoparticle in Å. The midsphere is a sphere that touches the edges of the nanoparticle.

radiusInscribedSphere(): Computes the radius of the inscribed sphere of the nanoparticle in Å .

area(): Computes the surface area of the nanoparticle in square Ångströms.

volume(): Computes the volume of the nanoparticle in cubic Ångströms.

MakeVertices(i)

Generates the coordinates of the vertices, edges, and faces for the ith shell of the dodecahedral nanoparticle. :param - i: Index of the shell :type - i: int

Returns:

The 14 vertex coordinates of the ith shell of an icosahedron - edges (np.ndarray): Indexes of the 24 edges - faces (np.ndarray): Indexes of the 12 faces

Return type:

CoordVertices (np.ndarray)

coords(noOutput)

Generates atomic coordinates for a tetrahedral nanoparticle.

Parameters:: noOutput (bool) – If False, displays progress and timing information.

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.catalanNPs.fccdrDD(element: str = 'Au', Rnn: float = 2.7, nShell: int = 1, **kwargs)

Bases: CatalanNP

A class for generating XYZ and CIF files of dihedral rhombic dodecahedral nanoparticles (NPs) of various sizes, based on user-defined compounds (either by name, e.g., “Fe”, “Au”, etc).

Key Features: - Allows to choose the NP size. - Can analyze the structure in detail, including symmetry and properties. - Offers options for core/surface differentiation based on a threshold. - Generates outputs in XYZ and CIF formats for visualization and simulations. - Provides compatibility with jMol for 3D visualization.

Additional Notes: - The symmetry analysis can be skipped to speed up computations. - Customizable precision thresholds for structural analysis.

Initialize the class with all necessary parameters.

Parameters:

element – Chemical element of the NP (e.g., “Au”, “Fe”).
Rnn (float) – Nearest neighbor interatomic distance in Å.
nShell (int) – Number of shells (e.g., nShell=1 means 2 atoms per edge).
postAnalyzis (bool) – If True, prints additional NP information. Examples: cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation. This is the distance threshold used to decide which atoms are retained.
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

self.shape

Shape ‘fccdrDD’

Type:: str

self.nAtoms

Number of atoms in the NP.

Type:: int

self.nAtomsPerShell

Number of atoms in each shell.

Type:: list

self.interShellDistance

Distance between shells.

Type:: float

self.jmolCrystalShape

Flag for JMol visualization.

Type:: bool

self.cog

Center of gravity of the NP.

Type:: np.array

self.imageFile

Path to a reference image.

Type:: str

nFaces = 12

nEdges = 32

nVertices = 14

edgeLengthF = 1

radiusCSF = 1

radiusCSFTB = np.float64(1.4142135623730951)

interShellF = 1.0

interShellFTB = np.float64(0.7071067811865475)

nAtomsF(i): Returns the number of atoms of an bcc rhombic dodecahedron of size i

nAtomsPerShellAnalytic()

Computes the number of atoms per shell in an ordered nanoparticle.

The function iterates over each shell layer, computes the number of atoms for the given shell, and subtracts the cumulative sum of the previous shells to get the number of new atoms in the current shell.

Returns:

A list where each element represents the number of atoms: in a specific shell.

Return type:

list

nAtomsPerShellCumulativeAnalytic()

Computes the cumulative number of atoms up to each shell.

This function returns the total number of atoms present in the nanoparticle for each shell layer, building up cumulatively.

Returns:

A list where each element represents the total number of: atoms present up to that shell.

Return type:

list

nAtomsAnalytic(): Computes the total number of atoms in the nanoparticle.

edgeLength()

Computes the edge length of the nanoparticle in Å .

The edge length is determined based on the interatomic distance (Rnn) and the number of shells (nShell).

area(): Computes the surface area of the nanoparticle in square Ångströms.

volume(): Computes the volume of the nanoparticle in cubic Ångströms.

MakeVertices(i)

Generates the coordinates of the vertices, edges, and faces for the ith shell of the dodecahedral nanoparticle. :param - i: index of the shell :type - i: int

Returns:

the 14 vertex coordinates of the ith shell of a dihedral rhombic dodecahedron - edges (np.ndarray): indexes of the 24 edges - faces (np.ndarray): indexes of the 12 faces

Return type:

CoordVertices (np.ndarray)

coords(noOutput)

Generates atomic coordinates for a dodecahedral nanoparticle.

Parameters:: noOutput (bool) – If False, displays progress and timing information.

Steps:

Generates vertex atoms.
Calculates and places edge atoms along the edges.
Generates facet atoms to fill in faces.
Stores final atomic positions in an ASE Atoms object.

Returns:: None (updates class attributes).

prop(): Display unit cell and nanoparticle properties.

johnsonNPs.py

class pyNanoMatBuilder.johnsonNPs.JohnsonNP(**kwargs)

Bases: pyNMBcore

Base class for all Johson nanoparticles providing common functionality.

Parameters:

postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation (distance threshold for retaining atoms).
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If False, generates the atomic structure of the NP.

class pyNanoMatBuilder.johnsonNPs.fcctbp(element: str = 'Au', Rnn: float = 2.7, nLayerTd: int = 1, **kwargs)

Bases: JohnsonNP

A class for generating fcc trigonal bipyramidal (fcctbp) nanoparticles (NPs) with a user-defined number of atomic layers and interatomic distances.

Key Features:

Generates a trigonal bipyramid shape with customizable atomic layers.
Computes structural properties like inter-layer distance, angles, and number of atoms.
Provides options for core/surface differentiation and symmetry analysis.
Supports visualization via ASE and Jmol for 3D structure representation.

Additional Notes:

The nLayerTd parameter determines the number of layers in one pyramid.
The Rnn parameter controls the nearest neighbor interatomic distance.
Symmetry analysis can be skipped to speed up computations.
Visualization can be enabled for both the initial structure and post-processing stages.

Initializes an fcc trigonal bipyramid (fcctbp) with the given parameters.

Parameters:

element (str) – Chemical element used to construct the NP (e.g., “Au”).
Rnn (float) – Nearest neighbor distance (in Å).
nLayerTd (int) – Number of atomic layers in each pyramid (default: 1).
postAnalyzis (bool) – If True, prints additional NP information (e.g., cell parameters, moments of inertia, inscribed/circumscribed sphere diameters, etc.).
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Threshold for core/surface classification (default: 1.0).
skipSymmetryAnalyzis (bool) – If False, performs symmetry analysis (default: False).
jmolCrystalShape (bool) – If True, generates a JMOL-compatible crystal shape (default: True).
noOutput (bool) – If True, suppresses text output (default: False).
calcPropOnly (bool) – If True, only calculates properties without generating structure (default: False).

nAtoms

Total number of atoms in the NP.

Type:: int

nAtomsPerLayer

Number of atoms in each atomic layer.

Type:: list

nAtomsPerEdge

Number of atoms per edge of the bipyramid.

Type:: int

interLayerDistance

Distance between atomic layers.

Type:: float

fveAngle

Face-vertex-edge angle.

Type:: float

fefAngle

Face-edge-face angle.

Type:: float

vcvAngle

Vertex-center-vertex angle.

Type:: float

heightOfBiPyramid

Height of the bipyramid.

Type:: float

imageFile

Path to the image representing the structure.

Type:: str

cog

Center of gravity of the NP.

Type:: np.array

trPlanes

Truncation plane equations.

Type:: np.array

nFaces = 6

nEdges = 9

nVertices = 5

edgeLengthF = 2

heightOfPyramidF = np.float64(1.632993161855452)

heightOfBiPyramidF = np.float64(3.265986323710904)

edgeLength(): Computes the edge length of the pyramids in Å using the class regfccTd of the Platonic module.

coords(noOutput)

Generates the coordinates of the fcc trigonal bipyramid.

First creates a regular fcc tetrahedron and then apply a mirror reflection to create the bipyramid. Calculates and centers the nanoparticle’s coordinates and finally computes the total number of atoms and the center of mass.

Parameters:: noOutput (bool) – Whether to suppress output messages.

prop(): Display unit cell and nanoparticle properties.

class pyNanoMatBuilder.johnsonNPs.epbpyM(element: str = 'Au', Rnn: float = 2.7, sizeP: int = 1, sizeE: int = 0, Marks: int = 0, Multiples_index_plan: bool = False, Hollow: bool = False, **kwargs)

Bases: JohnsonNP

A class for generating pentagonal bipyramidal (epbpyM) nanoparticles (NPs) with a user-defined size.

Important note: the size must be carefully defined. It is represented as a three-element array, where:

The size of the pentagon (number of bonds per pentagonal edge),
The size of the elongated part (number of bonds per elongated edge),
The number of truncated atoms at the vertices (the number of truncated atoms per pentagonal edge is doubled since there are two vertices per edge).

Key Features:

Generates a trigonal bipyramid shape with customizable atomic layers.
Computes structural properties like inter-layer distance, angles, and number of atoms.
Provides options for core/surface differentiation and symmetry analysis.
Supports visualization via ASE and Jmol for 3D structure representation.

Additional Notes:

The user must ensure that the number of truncated atoms per edge is smaller than the number of atoms on the edges. An example of sizes is given.
Symmetry analysis can be skipped to speed up computations.
Visualization can be enabled for both the initial structure and post-processing stages.

Initialize the class with the necessary parameters.

Parameters:

element (str) – Chemical element (e.g., ‘Au’, ‘Fe’).
Rnn (float) – Nearest neighbor interatomic distance in Å.
sizeP (int) – Number of bonds per pentagonal edge, defining the size of the pentagon.
sizeE (int) – Number of bonds per elongated edge, defining the size of the elongated part.
Marks (int) – Number of truncated atoms at the vertices.
postAnalyzis (bool) – If True, performs post-analysis on the generated NP.
aseView (bool) – If True, visualizes the nanoparticle structure using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation.
skipSymmetryAnalyzis (bool) – If False, performs symmetry analysis on the structure.
jmolCrystalShape (bool) – If True, generates a Jmol script for visualization.
noOutput (bool) – If True, suppresses output.
calcPropOnly (bool) – If True, only calculates properties without generating the NP.

element

The chemical element.

Type:: str

shape

The shape (‘epbpyM’).

Type:: str

Rnn

Nearest neighbor interatomic distance.

Type:: float

sizeP

Number of bonds per pentagonal edge.

Type:: int

sizeE

Number of bonds per elongated edge.

Type:: int

Marks

Number of truncated atoms.

Type:: int

nAtoms

Total number of atoms.

Type:: int

nAtomsPerPentagonalCap

Atoms in the pentagonal caps.

Type:: int

nAtomsPerElongatedPart

Atoms in the elongated part.

Type:: int

nAtomsPerEdgeOfPC

Atoms per edge of the pentagonal cap (before truncation).

Type:: int

nAtomsPerEdgeOfEP

Atoms per edge of the elongated part.

Type:: int

jmolCrystalShape

Whether to generate a Jmol script for visualization.

Type:: bool

cog

Center of gravity (CoG).

Type:: np.array

interCompactPlanesDistance

Distance between compact planes.

Type:: float

imageFile

Path to the image file.

Type:: str

nFaces3 = 10

nFaces4 = 5

nEdgesPbpy = 15

nEdgesEpbpy = 20

nVerticesPbpy = 7

nVerticesEpbpy = 12

phi = np.float64(1.618033988749895)

edgeLengthF = 1

heightOfPyramidF = np.float64(0.5257311121191336)

interCompactPlanesF = np.float64(0.8090169943749475)

magicFactorF = np.float64(1.0514622242382672)

edgeLength(whichEdge): Compute the edge length of pentagon and the elongated part in Å using Rnn and nAtomsPerEdgeOfPC / nAtomsPerEdgeOfEP.

nAtomsPerEdgeOfPC_after_truncation(): Compute the number of atoms per edge of the pentagon after truncation, using nAtomsPerEdgeOfPC and Marks.

edgeLength_after_truncation(whichEdge): Compute the edge length of pentagon and the elongated part after truncation in Å, using Rnn, nAtomsPerEdgeOfPC / nAtomsPerEdgeOfEP and Marks.

area(): Compute the surface area in square Å.

volume(): Compute the volume in cubic Å.

heightOfPyramid(): Compute the height of the pyramid in Å.

MakeVertices()

Generate the coordinates of the vertices, edges, and faces of a pentagonal bipyramid.

Returns:

the 7 vertex: coordinates of a pentagonal dipyramid
edges (np.ndarray): indexes of the 2x5: ”vertical” edges of the pentagonal cap of an elongated pentagonal bipyramid
faces (np.ndarray): indexes of the 10: triangular faces

Return type:

CoordVertices (np.ndarray)

truncationPlaneTuples4MarksDecahedron(refPlaneAtoms, debug=False)

Calculate the truncation planes for the Marks decahedron nanoparticle shape. It defines planes that truncate the vertices of the decahedron.

Parameters:

refPlaneAtoms (list) – A list of three atoms’ coordinates that define a reference plane. The list should contain: - summit atom (topmost point) - apex atom (the second point) - origin atom (used as reference)
debug (bool) – flag to enable or disable debugging information (default is False).

Returns:

An array of 5 planes: used for truncation, each defined by a normal vector and an offset.
indicesOfTruncationPlanes (list): A list of: tuples, each containing two indices that define the truncation plane pairs.

Return type:

planes (array-like)

coords(noOutput)

Generate coordinates of all atoms in the nanoparticle structure, including vertices, edges, faces, and internal atoms. Applies truncation and symmetry operations where necessary.

Parameters:: noOutput (bool) – if True, suppresses output messages during execution.
Returns:: None. Updates class attributes directly.

prop(): Display unit cell and nanoparticle properties.

otherNPs.py

class pyNanoMatBuilder.otherNPs.fcctpt(element: str = 'Au', Rnn: float = 2.7, nLayerTd: int = 1, nLayer: int = 3, **kwargs)

Bases: pyNMBcore

This class generates and manages the properties of an fcc triangular platelet, which is based on a trigonal bipyramid structure. It provides methods to calculate and manipulate atomic coordinates, compute the properties of the nanoparticle, and generate visualizations.

Initializes the fcc triangular platelet nanoparticle.

Parameters:

element (str) – The element of the nanoparticle (default ‘Au’).
Rnn (float) – The nearest neighbor distance (default 2.7 Å).
nLayerTd (int) – Number of layers (bonds per edge) of the two tetrahedrons used to create the platelet. This value will define the edge length of the final platelet; the number of layers of the platelet will be nLayerTd + 1.
nLayer (int) – The number of layers kept for each tetrahedron (not counting the twin plane). This value will define the thickness of the platelet; the number of layers in the final platelet will be nLayer * 2.
postAnalyzis (bool) – If True, prints additional NP information.
aseView (bool) – If True, enables visualization of the NP using ASE.
thresholdCoreSurface (float) – Precision threshold for core/surface differentiation.
skipSymmetryAnalyzis (bool) – If False, performs an atomic structure analysis using pymatgen.
jmolCrystalShape (bool) – If True, generates a JMOL script for visualization.
noOutput (bool) – If False, prints details about the NP structure.
calcPropOnly (bool) – If True, enables visualization of the NP using ASE.

nFaces

The number of faces of the triangular platelet.

Type:: int

nEdges

The number of edges of the triangular platelet.

Type:: int

nVertices

The number of vertices of the triangular platelet.

Type:: int

edgeLengthF

A factor for edge length.

Type:: float

element

The chemical element for the nanoparticle.

Type:: str

shape

The shape of the nanoparticle (‘fcctpt’).

Type:: str

Rnn

The nearest neighbor distance in Angstroms.

Type:: float

nLayerTd

Number of layers (bonds per edge) of the two tetrahedrons used to create the platelet.

Type:: int

nLayer

The number of layers kept for each tetrahedron.

Type:: int

nAtoms

Number of atoms in the nanoparticle.

Type:: int

interLayerDistance

Distance between layers.

Type:: float

nAtomsPerEdge

Number of atoms per edge at the twin boundary.

Type:: int

cog

Center of gravity of the nanoparticle.

Type:: np.array

dim

Dimensions of the nanoparticle.

Type:: list

jmolCrystalShape

Flag to indicate whether to display the crystal shape in Jmol.

Type:: bool

imageFile

Path to the image file of the nanoparticle shape.

Type:: str

nFaces = 8

nEdges = 9

nVertices = 9

edgeLengthF = 2

edgeLength(): Computes the edge length of the triangular platelet in Å..

coords(noOutput)

Generates the coordinates of the triangular platelet nanoparticle.

This method creates the atomic positions by truncating a trigonal bipyramid and adjusting the coordinates based on the twin and truncation planes.

Parameters:: noOutput (bool) – Whether to suppress output messages.

prop(): Display unit cell and nanoparticle properties.

Utilities (utils/)

core functions (core.py)

class pyNanoMatBuilder.utils.core.fg

Bases: object

PURPLE = '\x1b[95m'

CYAN = '\x1b[96m'

DARKCYAN = '\x1b[36m'

BLUE = '\x1b[94m'

GREEN = '\x1b[92m'

YELLOW = '\x1b[93m'

RED = '\x1b[91m'

LIGHTGRAY = '\x1b[37m'

DARKGRAY = '\x1b[90m'

BLACK = '\x1b[30m'

WHITE = '\x1b[38;5;231m'

OFF = '\x1b[0m'

class pyNanoMatBuilder.utils.core.hl

Bases: object

BLINK = '\x1b[5m'

blink = '\x1b[25m'

BOLD = '\x1b[1m'

bold = '\x1b[21m'

UNDERL = '\x1b[4m'

underl = '\x1b[24m'

ITALIC = '\x1b[3m'

italic = '\x1b[23m'

OFF = '\x1b[0m'

class pyNanoMatBuilder.utils.core.bg

Bases: object

DARKRED = '\x1b[38;5;231;48;5;52m'

DARKREDB = '\x1b[38;5;231;48;5;52;1m'

LIGHTRED = '\x1b[48;5;217m'

LIGHTREDB = '\x1b[48;5;217;1m'

LIGHTYELLOW = '\x1b[48;5;228m'

LIGHTYELLOWB = '\x1b[48;5;228;1m'

LIGHTGREEN = '\x1b[48;5;156m'

LIGHTGREENB = '\x1b[48;5;156;1m'

LIGHTBLUE = '\x1b[48;5;117m'

LIGHTBLUEB = '\x1b[48;5;117;1m'

OFF = '\x1b[0m'

class pyNanoMatBuilder.utils.core.color

Bases: object

PURPLE = '\x1b[95m'

CYAN = '\x1b[96m'

DARKCYAN = '\x1b[36m'

BLUE = '\x1b[94m'

GREEN = '\x1b[92m'

YELLOW = '\x1b[93m'

RED = '\x1b[91m'

LIGHTGRAY = '\x1b[37m'

DARKGRAY = '\x1b[90m'

BLACK = '\x1b[30m'

WHITE = '\x1b[38;5;231m'

BOLD = '\x1b[1m'

OFF = '\x1b[0m'

pyNanoMatBuilder.utils.core.pyNMB_location(): Returns the absolute path to the root of the installed package.

pyNanoMatBuilder.utils.core.get_resource_path(sub_folder: str, filename: str) → str

Retrieve the absolute path of a resource file within the package.

This helper uses the modern ‘importlib.resources.files’ API (Python 3.9+) to ensure compatibility with various installation environments like Google Colab or virtual environments.

Parameters:

sub_folder (str) – Folder path relative to the package root (e.g., ‘resources/figs’ or ‘resources/cif_database’).
filename (str) – Name of the file (e.g., ‘banner.png’).

Returns:

The absolute string path to the file.

Return type:

str

class pyNanoMatBuilder.utils.core.timer

Bases: object

Timer class to measure elapsed time in seconds and display it in hh:mm:ss ms.

hdelay_ms(delay)

Converts a delay into a human-readable format: hh:mm:ss ms.

Parameters:: delay – A timedelta object or a float representing a duration in seconds.
Returns:: mm:ss ms.
Return type:: A formatted string in hh

chrono_start(): Starts the chrono.

chrono_stop(hdelay=False): Stops the chrono and returns the elapsed time.

chrono_show(): Prints the elapsed time.

pyNanoMatBuilder.utils.core.RAB(coord, a, b)

Calculate the distance between two atoms by indices.

Parameters:

coord (array-like) – Array of 3D coordinates.
a (int) – Index of the first atom.
b (int) – Index of the second atom.

Returns:

Distance between atoms a and b.

Return type:

float

pyNanoMatBuilder.utils.core.Rbetween2Points(p1, p2)

Calculate the distance between two points.

Parameters:

p1 (array-like) – 3D coordinates of the first point.
p2 (array-like) – 3D coordinates of the second point.

Returns:

Distance between p1 and p2.

Return type:

float

pyNanoMatBuilder.utils.core.vector(coord, a, b)

Compute the vector from point a to point b given a list of coordinates.

Parameters:

coord (array-like) – Array of 3D coordinates.
a (int) – Index of the starting point.
b (int) – Index of the ending point.

Returns:

Vector from a to b.

Return type:

np.ndarray

pyNanoMatBuilder.utils.core.vectorBetween2Points(p1, p2)

Compute the vector between two 3D points.

Parameters:

p1 (array-like) – 3D coordinates of the first point.
p2 (array-like) – 3D coordinates of the second point.

Returns:

Vector from p1 to p2.

Return type:

np.ndarray

pyNanoMatBuilder.utils.core.coord2xyz(coord)

Extracts x, y, and z from a list of 3D coordinates.

Parameters:

[[x1 (A list or array of 3D coordinates in the format)
y1
z1]
[x2
y2
z2]
...].

Returns:

Three NumPy arrays containing the x, y, and z coordinates separately.

pyNanoMatBuilder.utils.core.vertex(x, y, z, scale): Return vertex coordinates fixed to the unit sphere.

pyNanoMatBuilder.utils.core.vertexScaled(x, y, z, scale): Return vertex coordinates multiplied by the scale factor.

pyNanoMatBuilder.utils.core.RadiusSphereAfterV(V)

Computes the radius of a sphere given its volume.

Parameters:: V (float) – Volume of the sphere in cubic units.
Returns:: Radius of the sphere.
Return type:: float

Formula: R = (3V / (4π))^(1/3)

pyNanoMatBuilder.utils.core.centerOfGravity(c: ndarray, select=None): Compute center of gravity of selected atoms.

pyNanoMatBuilder.utils.core.center2cog(c: ndarray)

Centers a set of atomic coordinates to their center of gravity.

Parameters:: c (np.ndarray) – An array of shape (N, 3) representing N atomic positions (x, y, z).
Returns:: A new array of centered coordinates where the center of gravity is at (0,0,0).
Return type:: np.ndarray

Notes: - Uses centerOfGravity(c) to compute the center of gravity. - Each atomic position is shifted by subtracting the center of gravity.

pyNanoMatBuilder.utils.core.normOfV(V)

Returns the norm of a vector V. :param V: A 3-element array representing a vector [Vx, Vy, Vz]. :type V: np.ndarray

Returns:: The norm of the vector.
Return type:: float

pyNanoMatBuilder.utils.core.normV(V)

Computes the normalized unit vector of a vector V. :param V: A 3-element array representing a vector [Vx, Vy, Vz]. :type V: np.ndarray

Returns:: A 3-element array representing the normalized vector.
Return type:: np.ndarray

pyNanoMatBuilder.utils.core.AngleBetweenVV(lineDV, planeNV): Return the angle, in degrees, between two vectors.

pyNanoMatBuilder.utils.core.signedAngleBetweenVV(v1, v2, n)

Return the signed angle between two vectors in degrees in [0, 360].

Parameters:

v1 (np.ndarray) – First vector.
v2 (np.ndarray) – Second vector.
n (np.ndarray) – Normal of the plane formed by the two vectors.

Returns:

Signed angle in degrees.

Return type:

float

pyNanoMatBuilder.utils.core.centerToVertices(coordVertices: ndarray, cog: ndarray)

Computes the vectors and distances between the center of gravity (cog) and each vertex of a polyhedron. :param coordVertices: Array of shape (n_vertices, 3) containing the coordinates of the vertices. :type coordVertices: np.ndarray :param cog: A 3-element array representing the center of gravity of the nanoparticle. :type cog: np.ndarray

Returns:

directions (np.ndarray): Array of shape (n_vertices, 3) containing the vectors from cog to each vertex.
distances (np.ndarray): Array of shape (n_vertices,) containing the distances from cog to each vertex.

Return type:

tuple

pyNanoMatBuilder.utils.core.Rx(a): Return the R/x rotation matrix.

pyNanoMatBuilder.utils.core.Ry(a): Return the R/y rotation matrix.

pyNanoMatBuilder.utils.core.Rz(a): Return the R/z rotation matrix.

pyNanoMatBuilder.utils.core.EulerRotationMatrix(gamma, beta, alpha, order='zyx')

Return a 3x3 Euler rotation matrix.

Parameters:

gamma – Rot/x (°).
beta – Rot/y (°).
alpha – Rot/z (°).
order – If (order=”zyx”): returns Rz(alpha) * Ry(beta) * Rx(gamma).

Returns:

A 3x3 Euler matrix.

Return type:

np.ndarray

pyNanoMatBuilder.utils.core.plotPalette(Pcolors, namePC, angle=0, savePngAs=None)

Plot a 1D palette of colors with names.

Parameters:

Pcolors – 1D list with hex colors.
namePC – Label for each color.
angle – Rotation angle of the text.
savePngAs – Also saves the palette in a png file (default: None).

pyNanoMatBuilder.utils.core.rgb2hex(c, frac=True)

Convert an RGB color to its hexadecimal representation.

It has an optional frac argument to handle the case where the RGB values are provided as fractions (ranging from 0 to 1) or as integers (ranging from 0 to 255).

Parameters:

c – RGB color tuple.
frac (bool) – If True, RGB values are fractions (0-1).

Returns:

Hexadecimal representation.

Return type:

str

pyNanoMatBuilder.utils.core.clone(system)

Create and return a deep copy of any pyNanoMatBuilder system.

This ensures that all internal arrays, ASE atoms objects, and Pymatgen structures are fully independent from the original.

Parameters:: system – A pyNanoMatBuilder object (e.g., Crystal, Icosahedron).
Returns:: A completely independent clone of the input system.

pyNanoMatBuilder.utils.core.deleteElementsOfAList(t, list2Delete: bool)

Return a new list with elements deleted based on a boolean mask.

Parameters:

t – List or array-like.
list2Delete (bool) – Boolean mask, list2Delete[i] = True deletes t[i].

Returns:

Filtered list.

Return type:

list

pyNanoMatBuilder.utils.core.centerTitle(content=None): Centers and renders as HTML a text in the notebook font size = 16px, background color = dark grey, foreground color = white

pyNanoMatBuilder.utils.core.centertxt(content=None, font='sans', size=12, weight='normal', bgc='#000000', fgc='#ffffff')

Centers and renders as HTML a text in the notebook

input:

content = the text to render (default: None)
font = font family (default: ‘sans’, values allowed = ‘sans-serif’ | ‘serif’ | ‘monospace’ | ‘cursive’ | ‘fantasy’ | …)
size = font size (default: 12)
weight = font weight (default: ‘normal’, values allowed = ‘normal’ | ‘bold’ | ‘bolder’ | ‘lighter’ | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 )
bgc = background color (name or hex code, default = ‘#ffffff’)
fgc = foreground color (name or hex code, default = ‘#000000’)

pyNanoMatBuilder.utils.core.planeFittingLSF(coords: float64, printErrors: bool = False, printEq: bool = True)

Least-square fitting of the equation of a plane ux + vy + wz + h = 0 that passes as close as possible to a set of 3D points :param - coords: array with shape (N,3) that contains the 3 coordinates for each of the N points :type - coords: np.ndarray :param - printErrors: if True, prints the absolute error between the actual z coordinate of each points :type - printErrors: bool :param and the corresponding z-value calculated from the plane equation. The residue is also printed: :param - printEq: if True, prints equation. :type - printEq: bool

Returns:: numpy array([u v w h])

pyNanoMatBuilder.utils.core.faces_to_planes(faces, coords)

Converts a list of faces in planes equations [u, v, w, d].

Parameters:

faces (list of tuples) – List of faces [(i, j, k)] with the vertices indexes.
coords (np.ndarray) – Atoms coordinates.

Returns:

List of planes equations: [u, v, w, d].

Return type:

planes (list of np.ndarray)

Geometry Tools (geometry.py)

pyNanoMatBuilder.utils.geometry.MakeFaceCoord(Rnn, f, coord, nAtomsOnFaces, coordFaceAt)

Interpolates atom positions on a given face of a polyhedron by distributing atoms between two relevant edges.

Parameters:

Rnn (float) – Nearest neighbor distance.
f (list) – List of vertex indices defining the face.
coord (np.ndarray) – Array containing the coordinates of all atoms.
nAtomsOnFaces (int) – Counter for the number of atoms placed on faces.
coordFaceAt (list) – List of face atom coordinates to be updated.

Returns:

nAtomsOnFaces (int): Updated count of face atoms.
coordFaceAt (list): Updated list of coordinates of atoms placed on faces.

Return type:

tuple

Method:

Determines two relevant edges based on the number of vertices in the face.
Interpolates atoms along these edges.
Fills the face by interpolating between interpolated edge atoms.

pyNanoMatBuilder.utils.geometry.reduceHullFacets(self, noOutput: bool = False, tolAngle: float = 2.0, useWulff: bool = False)

Reduce crystal facets based on convex hull and coplanarit of facets.

Parameters:

noOutput (bool) – If True, suppresses output to the console. Default is False.
tolAngle (float) – Tolerance angle to define coplanarity. Default is 2.0 degree.
useWulff (bool) – If True, uses the Wulff construction planes (trPlanes_Wulff) regardless of whether the structure is optimized or not. If False, uses trPlanes_opt for optimized structures, or trPlanes for initial structures. Default is True.

Returns:

The vertices and reduced faces.

Return type:

tuple

Note

Previous hull.simplices must have been saved as Crystal.trPlanes.
trPlanes_wWlff must have been saved during the Wulff construction. The result is always saved in self.trPlanes (or self.trPlanes_opt).

pyNanoMatBuilder.utils.geometry.RotationMol(coords, angle, axis='z')

Perform a rotation of the molecule’s coordinates around a specified axis.

Parameters:

coords (numpy.ndarray) – Coordinates of the molecule as a matrix (n x 3).
angle (float) – The angle of rotation in degrees.
axis (str) – The axis around which to perform the rotation (‘x’, ‘y’, or ‘z’).

Returns:

R[0] The coordinates of the molecule after rotation, as a matrix (n x 3).

Return type:

numpy.ndarray

pyNanoMatBuilder.utils.geometry.EulerRotationMol(coords, gamma, beta, alpha, order='zyx')

Perform an Euler rotation of the molecule’s coordinates.

Parameters:

coords (numpy.ndarray) – Coordinates of the molecule as a matrix (n x 3).
gamma (float) – Angle gamma in degrees.
beta (float) – Angle beta in degrees.
alpha (float) – Angle alpha in degrees.
order (str) – The order of the Euler rotations (default is “zyx”).

Returns:

The coordinates of the molecule after the Euler rotation, as a matrix (n x 3).

Return type:

numpy.ndarray

pyNanoMatBuilder.utils.geometry.RotationMatrixFromAxisAngle(u, angle)

Generates a 3x3 rotation matrix from a unit vector representing the axis of rotation and a rotation angle. :param u: A unit vector representing the axis of rotation (3 elements). :type u: numpy.ndarray :param angle: The angle of rotation in degrees. :type angle: float

Returns:: A 3x3 rotation matrix.
Return type:: numpy.ndarray

pyNanoMatBuilder.utils.geometry.rotationMolAroundAxis(coords, angle, axis)

Return coordinates after rotation by a given angle around an [u,v,w] axis.

Parameters:

coords – natoms x 3 numpy array.
angle – Angle of rotation.
axis – Directions given under the form [u,v,w].

Returns:

Rotated coordinates.

Return type:

numpy.ndarray

pyNanoMatBuilder.utils.geometry.rotation_around_axis_through_point(coords, angle_deg, axis, center): Rotate coords (n,3) around a given axis (3,) passing through a point center (3,) by a given angle (in degrees).

pyNanoMatBuilder.utils.geometry.reflection(plane, points, doItForAtomsThatLieInTheReflectionPlane=False, eps=0.01)

Apply a mirror-image symmetry operation to an array of points.

Calculates the reflection of each point across a symmetry plane defined by the general equation $ax + by + cz + d = 0$.

Parameters:

plane (list or numpy.ndarray) – The four parameters $[a, b, c, d]$ that define the reflection plane equation.
points (numpy.ndarray) – An (N, 3) array of Cartesian coordinates representing the points to be reflected.
doItForAtomsThatLieInTheReflectionPlane (bool, optional) – If True, points located exactly on the reflection plane +- eps are processed. If False, they are skipped. Defaults to False.
(float (eps) – 1e-2): threshold associated to doItForAtomsThatLieInTheReflectionPlane
default – 1e-2): threshold associated to doItForAtomsThatLieInTheReflectionPlane

Returns:

An (N, 3) array containing the coordinates of the reflected mirror-image points.

Return type:

numpy.ndarray

pyNanoMatBuilder.utils.geometry.reflection_with_face_update(plane, points, faces, current_indices, eps=0.01, debug=False)

Apply a reflection to a set of points across a plane while mapping indices.

This function identifies points lying on the reflection plane (shared atoms) and those to be reflected (new atoms). Instead of duplicating shared atoms, it maps their local indices to their existing global indices in the assembly. New atoms are marked with a “NEW” placeholder to be indexed in the global coordinate array later.

Parameters:

plane (np.ndarray) – Plane equation [a, b, c, d] for ax + by + cz + d = 0.
points (np.ndarray) – (N, 3) Cartesian coordinates of the current unit.
faces (list of tuples) – Local face definitions (vertex indices).
current_indices (list of int) – Global indices in all_coords for each point in points.
eps (float) – Distance threshold to consider a point as lying on the plane. Defaults to 1e-2.
debug (bool) – If True, prints mapping information. Defaults to False.

Returns:

reflected_points (np.ndarray): Coordinates of the truly new atoms.
old_to_new (dict): Dictionary mapping local indices (0 to N-1) to either a global integer index or the string “NEW”.

Return type:

tuple

pyNanoMatBuilder.utils.geometry.helical_assembly(seed_coords, seed_faces, n_units, face_sequence=None, eps=0.01, debug=False)

Generate a helical assembly of polyhedra via successive face reflections.

This engine builds complex structures (like the Boerdijk-Coxeter helix) by reflecting a seed unit across its faces. It prevents atomic duplication by tracking global indices and only adding “new” vertices to the coordinate array at each step.

Parameters:

seed_coords (np.ndarray) – (N, 3) coordinates of the initial polyhedral unit (e.g., a tetrahedron).
seed_faces (list of tuples) – Vertex index tuples defining the faces of the seed unit.
n_units (int) – Total number of polyhedral units to assemble.
face_sequence (list of int, optional) – Sequence of face indices to cycle through for reflections. Defaults to range(len(seed_faces)).
eps (float) – Precision threshold for detecting atoms on the reflection plane. Defaults to 1e-2.
debug (bool) – If True, prints step-by-step assembly logs and updated global face indices. Defaults to False.

Returns:

all_coords (np.ndarray): (M, 3) array of all distinct atomic coordinates in the final helix.
n_atoms (int): Total number of unique atoms (M).

Return type:

tuple

Notes

The function maintains a ‘current_global_indices’ list to ensure topological continuity between successive units without using nearest-neighbor searches (like KDTree).

pyNanoMatBuilder.utils.geometry.reflection_tetra(plane, points)

Simplified reflection function for the helix of tetrahedrons.

Parameters:

plane – [u,v,w,d] parameters that define a plane.
points – (N, 3) array of points.

Returns:

(N, 3) array of reflected points.

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.remove_duplicate_atoms(coordinates, reference_coords, tolerance)

Robustly removes duplicate atoms from coordinates using adaptive tolerance.

Identifies atoms in ‘coordinates’ that are within ‘tolerance’ of any atom in ‘reference_coords’ and removes them. This is ideal for removing atoms added by reflection that already exist on shared faces.

Parameters:

coordinates (np.ndarray) – (N, 3) array of new atoms to filter
reference_coords (np.ndarray) – (M, 3) array of existing atoms (reference)
tolerance (float) – Distance threshold for duplicate detection. Recommended: 0.1 * Rnn for molecular structures.

Returns:

(unique_coords, n_removed)

unique_coords: (K, 3) filtered coordinates
n_removed: (int) number of duplicates removed

Return type:

tuple

Notes

Atoms from ‘coordinates’ that are far from all atoms in ‘reference_coords’ are considered unique and kept.
Efficiency: O(N*M) where N=len(coordinates), M=len(reference_coords)
Use this when adding incrementally to existing structure (helix generation)

Example

>>> new_atoms = np.array([[0.5, 0, 0], [5, 0, 0]])
>>> existing = np.array([[0, 0, 0], [1, 0, 0]])
>>> tol = 0.1
>>> unique, n_dup = remove_duplicate_atoms(new_atoms, existing, tol)
>>> print(n_dup)  # 1 (first atom is duplicate)

pyNanoMatBuilder.utils.geometry.planeRotation(Crystal: Atoms, refPlane, rotAxis, nRot=6, debug: bool = False, noOutput: bool = False)

Return planes obtained by rotating a reference plane around an axis.

Parameters:

Crystal – Crystal object.
refPlane – Plane to rotate.
rotAxis – Rotation axis.
nRot (int) – Rotation count, angle is 360°/nRot.
debug (bool) – If True, prints normalized planes.
noOutput (bool) – If True, suppresses output.

Returns:

Rotated planes in cartesian coordinates.

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.alignV1WithV2_returnR(v1, v2=array([0, 0, 1]))

Return the rotation matrix that aligns v1 with v2.

Parameters:

v1 (np.ndarray) – Source vector.
v2 (np.ndarray) – Target vector.

Returns:

3x3 rotation matrix.

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.rotateMoltoAlignItWithAxis(coords, axis, targetAxis=array([0, 0, 1]))

Return coordinates after rotation aligning axis with targetAxis.

Parameters:

coords (np.ndarray) – (n_atoms, 3) array of coordinates.
axis (np.ndarray) – Axis direction [u, v, w].
targetAxis (np.ndarray) – Target axis direction.

Returns:

Rotated coordinates (n_atoms, 3).

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.setdAsNegative(planes)

Flip plane signs so that d is negative.

Parameters:: planes (np.ndarray) – Array of planes.
Returns:: Updated planes.
Return type:: np.ndarray

pyNanoMatBuilder.utils.geometry.returnPlaneParallel2Line(V, shift=[1, 0, 0], debug=False)

Return plane parameters for a plane parallel to a direction vector.

Parameters:

V (np.ndarray) – Direction vector.
shift (list) – Shift vector used to build an arbitrary non-parallel vector.
debug (bool) – If True, prints intermediate values.

Returns:

Plane normal [a, b, c]; d must be found separately.

Return type:

np.ndarray

Method:

choose any arbitrary vector not parallel to V[i,j,k] such as V[i+1,j,k]

calculate the vector perpendicular to both of these, i.e. the cross product

this is the normal to the plane, i.e. you directly obtain the equation of the plane ax+by+cz+d = 0, d being indeterminate (to find d, it would be necessary to provide an (x0,y0,z0) point that does not belong to the line, hence d = -ax0-by0-cz0)

pyNanoMatBuilder.utils.geometry.normal2MillerPlane(Crystal, MillerIndexes, printN=True)

Return the normal direction to the plane defined by h,k,l Miller indices defined as [n1 n2 n3] = (hkl) x G*, where G* is the reciprocal metric tensor (G* = G-1). convertuvwh2hkld() function applied here converts real plane indexes to integers.

Parameters:

Crystal – Crystal object with G*.
MillerIndexes (np.ndarray) – Miller indices [h, k, l].
printN (bool) – If True, prints the computed normals.

Returns:

Integer-normalized plane normal.

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.isPlaneParrallel2Line(v1, v2, tol=1e-05)

Return True if line direction and plane normal are parallel. A line direction vector and a plane are parallel if $|angle|$ between the line and the normal vector of the plane is 90°.

Parameters:

v1 (np.ndarray) – Line direction vector.
v2 (np.ndarray) – Plane normal vector.
tol (float) – Tolerance for angle comparison in degrees.

Returns:

True if line and plane are parallel, False otherwise.

Return type:

bool

pyNanoMatBuilder.utils.geometry.isPlaneOrthogonal2Line(v1, v2, tol=1e-05)

Return True if line direction and plane normal are orthogonal. A line direction vector and a plane are orthogonal if $|angle|$ between the line and the normal vector of the plane is 0° or 180°.

Parameters:

v1 (np.ndarray) – Line direction vector.
v2 (np.ndarray) – Plane normal vector.
tol (float) – Tolerance for angle comparison in degrees.

Returns:

True if line and plane are orthogonal, False otherwise.

Return type:

bool

pyNanoMatBuilder.utils.geometry.areDirectionsOrthogonal(v1, v2, tol=1e-06)

Return True if directions are orthogonal. Lines are orthogonal if the $|angle|$ between their direction vector is 90°

Parameters:

v1 (np.ndarray) – First direction vector.
v2 (np.ndarray) – Second direction vector.
tol (float) – Tolerance for angle comparison in degrees.

Returns:

True if directions are orthogonal, False otherwise.

Return type:

bool

pyNanoMatBuilder.utils.geometry.areDirectionsParallel(v1, v2, tol=1e-06)

Return True if directions are parallel. Lines are parallel if the $|angle|$ between their direction vector is 0° or 180°.

Parameters:

v1 (np.ndarray) – First direction vector.
v2 (np.ndarray) – Second direction vector.
tol (float) – Tolerance for angle comparison in degrees.

Returns:

True if directions are parallel, False otherwise.

Return type:

bool

pyNanoMatBuilder.utils.geometry.shortestPoint2PlaneVectorDistance(plane: ndarray, point: ndarray)

Return the shortest distance, d, from a point X0 to a plane p (projection of X0 on p = P), as well as the PX0 vector.

Parameters:

plane (np.ndarray) – [u v w h] definition of the p plane
point (np.ndarray) – [x0 y0 z0] coordinates of the X0 point or (N, 3) array of points.

Returns:

the PX0 vector and ||PX0||

Return type:

v,d (tuple)

pyNanoMatBuilder.utils.geometry.Pt2planeSignedDistance(plane, point)

Return the orthogonal distance of a given point X0 to the plane p in a metric space (projection of X0 on p = P), with the sign determined by whether or not X0 is in the interior of p with respect to the center of gravity [0 0 0].

Parameters:

plane (np.ndarray) – Array [u, v, w, h] defining the plane.
point (np.ndarray) – Array [x0, y0, z0] or (N, 3) array of points.

Returns:

Signed distance(s) to the plane.

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.planeAtVertices(coordVertices: ndarray, cog: ndarray)

Returns the equation of the plane defined by vectors between the center of gravity (cog) and each vertex of a polyhedron and that is located at the vertex.

Parameters:

coordVertices (np.ndarray) – Coordinates of the vertices (n_vertices, 3).
cog (np.ndarray) – Center of gravity of the NP.

Returns:

the (cog-nvertices)x3 coordinates of the plane

Return type:

np.array(plane)

pyNanoMatBuilder.utils.geometry.planeAtPoint(plane: ndarray, P0: ndarray)

Recalculate plane d so the plane passes through P0.

Parameters:

plane (np.ndarray) – Array [a, b, c, d].
P0 (np.ndarray) – Coordinates [x0, y0, z0].

Returns:

Plane parameters [a, b, c, -(ax0+by0+cz0)].

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.normalizePlane(p): Normalize plane parameters [a, b, c, d] by the normal norm.

pyNanoMatBuilder.utils.geometry.point2PlaneDistance(point: float64, plane: float64)

Compute the shortest distance between a point and a plane in 3D space.

Parameters:

point (np.ndarray) – A 3D point as [x, y, z].
plane (np.ndarray) – A plane defined by [A, B, C, D] where Ax + By + Cz + D = 0.

Returns:

The shortest distance from the point to the plane.

Return type:

float

pyNanoMatBuilder.utils.geometry.calculateTruncationPlanesFromVertices(planes, cutFromVertexAt, nAtomsPerEdge, debug=False, noOutput=False, trTd=False)

Calculate truncation planes from vertex planes.

Parameters:

planes (np.ndarray) – Array of planes [u, v, w, d].
cutFromVertexAt (float) – Fraction of edge length to cut from each vertex.
nAtomsPerEdge (int) – Number of atoms per edge.
debug (bool) – If True, prints debug information.
noOutput (bool) – If True, suppresses output.

Returns:

Truncation planes.

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.truncateAboveEachPlane(planes: ndarray, coords, debug: bool = False, delAbove: bool = True, noOutput: bool = False, eps: float = 0.001)

Return atom indices above (or below) each plane.

Parameters:

planes (np.ndarray) – Array with plane definitions [u, v, w, d].
coords (np.ndarray) – (N, 3) array of coordinates.
debug (bool) – If True, prints selected atom indices.
delAbove (bool) – If True, deletes atoms above planes + eps; below otherwise.
noOutput (bool) – If True, suppresses output.
eps (float) – Atom-to-plane signed distance threshold.

Returns:

Unique indices of atoms above/below any input plane.

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.truncateAbovePlanes(planes: ndarray, coords: ndarray, allP: bool = False, delAbove: bool = True, debug: bool = False, noOutput: bool = False, eps: float = 0.001, depth_max: float = None)

Return a boolean mask of atoms above/below plane(s).

Parameters:

planes (np.ndarray) – Array with plane definitions [u, v, w, d].
coords (np.ndarray) – (N, 3) array of coordinates.
allP (bool) – If True, deleted atoms must lie simultaneously above ALL individual plane.
delAbove (bool) – If True, delete atoms above planes (+eps); below otherwise
precaution ((use with)
definition) (could return no atoms as a function of their)
debug (bool) – If True, prints atoms matching the conditions.
noOutput (bool) – If True, suppresses output.
eps (float) – Atom-to-plane signed distance threshold.
depth_max (float) – Reserved for depth-based filtering.

Returns:

Boolean mask for atoms above/below planes.

Return type:

np.ndarray

pyNanoMatBuilder.utils.geometry.returnPointsThatLieInPlanes(planes: ndarray, coords: ndarray, debug: bool = False, threshold: float = 0.001, noOutput: bool = False)

Finds all points (atoms) that lie within the given planes based on a signed distance criterion.

Parameters:

planes (np.ndarray) – A 2D array with plane equations [a, b, c, d].
coords (np.ndarray) – A 2D array of atom coordinates [x, y, z].
debug (bool, optional) – If True, prints additional debugging information.
threshold (float, optional) – Tolerance for distance to consider a point in plane.
noOutput (bool, optional) – If True, suppresses output messages.

Returns:

A boolean array where True indicates that the atom lies in one of the planes.

Return type:

AtomsInPlane (np.ndarray)

pyNanoMatBuilder.utils.geometry.coreSurface(self, threshold_CoreSurface: float = 0.001, noOutput=False)

Identify the core and surface atoms of a nanoparticle. This method distinguishes surface atoms from core atoms by calculating the geometric convex hull of the atomic coordinates. It can target either the initial structure (NP) or the relaxed structure (NP_opt).

Parameters:

threshold_CoreSurface (float) – The threshold used to identify surface atoms.
noOutput (bool) – If True, suppresses output during the analysis.

Returns:

A tuple containing:

list: [Hull vertices, Hull simplices, Hull neighbors, Hull equations]
surfaceAtoms (numpy.ndarray): A boolean array where True indicates that the atom lies on the surface.

Return type:

tuple

pyNanoMatBuilder.utils.geometry.peel_by_coordination(self, threshold_peeling=6, Rmax=2.9, noOutput=False)

Remove surface atoms with low coordination numbers to simulate truncation or incomplete shell growth.

This method uses a KDTree-based neighbor search (via self.kDTreeCN) to identify and delete atoms that are weakly bonded, such as vertices or edge atoms.

The method updates self.NP in place. If an optimized structure (NPopt) existed, it is used as the coordinate source for the peeling, then deleted. self.is_optimized is reset to False.

Parameters:

threshold_peeling (int) – Minimum coordination number required to keep an atom.
Rmax (float) – The cutoff distance (in Angstroms) for defining a nearest neighbor.
noOutput (bool) – If True, suppresses output messages.

Returns:

The updated nanoparticle (self.NP) after peeling.

Return type:

ase.Atoms

pyNanoMatBuilder.utils.geometry.peel_by_shifted_ellipsoid(self, shift_dist=2.5, noOutput=False)

Truncate the nanoparticle using a shape-adaptive envelope shifted in a random direction.

This method simulates asymmetric growth or partial dissolution by shifting a volume of control (defined by the particle’s own inertia tensor) and removing atoms that fall outside. By projecting coordinates into the Principal Component Analysis (PCA) local frame, the truncation volume perfectly matches the eccentricity of the NP, making it robust for both spherical and cylindrical (nanorod) geometries.

The method updates self.NP in place. If an optimized structure (NP_opt) existed, it is used as the coordinate source, then deleted. self.is_optimized is reset to False.

Parameters:

shift_dist (float) – The distance to shift the envelope (in Angstroms). 2.5 A corresponds to approximately one atomic layer.
noOutput (bool) – If True, suppresses output messages.

pyNanoMatBuilder.utils.geometry.plot_npr_triangle(self=None, is_optimized: bool = False, save_path: str = None, external_data: dict = None, color_by: str = 'Rg', color: str = 'viridis'): Hybrid Sauer Plotter for pyNanoMatBuilder with precise colorbar scaling and bold formatting.

Crystal & Wulff Utilities (crystals.py)

pyNanoMatBuilder.utils.crystals.print_ase_unitcell(system: Atoms)

Function that prints unitcell informations : chemical formula, bravais lattice, n° space group, cell parameters, volume, etc.

Parameters:: class (An instance of the Crystal)

pyNanoMatBuilder.utils.crystals.scaleUnitCell(crystal: Atoms, scaleDmin2: float, noOutput: bool = False)

Scales the unit cell of a given crystal structure to match a target nearest-neighbor distance.

This function expands the unit cell of the input crystal by creating a 2×2×2 supercell, then computes the nearest-neighbor distance and scales the entire structure to match the desired minimum nearest-neighbor distance.

Args: - crystal (Atoms): An ASE Atoms object representing the initial crystal structure. - scaleDmin2 (float): The target nearest-neighbor distance (in Å) after scaling. - noOutput (bool): If True, suppresses output messages.

Returns: - None: The function modifies the input crystal object in place.

Notes:

The function first generates a 2×2×2 supercell to ensure a representative environment.
It computes the minimum nearest-neighbor distance (Rmin) using kDTreeCN.
The structure is then uniformly scaled so that the new nearest-neighbor distance equals scaleDmin2.
The ASE set_cell method is used with scale_atoms=True to adjust atomic positions accordingly.

pyNanoMatBuilder.utils.crystals.FindInterAtomicDist(self)

Computes the interatomic distance based on the Bravais lattice (fcc, bcc or hcp only).

Returns:: Interatomic distance
Return type:: float

pyNanoMatBuilder.utils.crystals.convertuvwh2hkld(plane: float64, prthkld: bool = True)

Convert a real plane ux + vy + wz + h = 0 to integer hkl form.

Parameters:

plane (np.ndarray) – Array [u, v, w, h].
prthkld (bool) – If True, prints the hkl equation.

Returns:

Array [h, k, l, d].

Return type:

np.ndarray

pyNanoMatBuilder.utils.crystals.hklPlaneFitting(coords: float64, printEq: bool = True, printErrors: bool = False)

Context: finding the Miller indices of a plane, if relevant. Consists in a least-square fitting of the equation of a plane hx + ky + lz + d = 0 that passes as close as possible to a set of 3D points.

Parameters:

coords (np.ndarray) – array with shape (N,3) that contains the 3 coordinates for each of the N points
printErrors (bool) – if True, prints the absolute error between the actual z coordinate of each points
printed (and the corresponding z-value calculated from the plane equation. The residue is also)

Returns:

[h k l d], where h, k, and l are as close as possible to integers

Return type:

plane (np.ndarray)

pyNanoMatBuilder.utils.crystals.interPlanarSpacing(plane: ndarray, unitcell: ndarray, CrystalSystem: str = 'CUB')

Calculate the interplanar spacing.

Parameters:

plane – numpy array containing the [h k l d] parameters of the plane of equation hx + ky + lz + d = 0.
unitcell – numpy array with [a b c alpha beta gamma].
CrystalSystem – Name of the crystal system, string among: [‘CUB’, ‘HEX’, ‘TRH’, ‘TET’, ‘ORC’, ‘MCL’, ‘TRI’] = cubic, hexagonal, trigonal-rhombohedral, tetragonal, orthorombic, monoclinic, tricilinic.

Returns:

The interplanar spacing.

Return type:

float

pyNanoMatBuilder.utils.crystals.lattice_cart(Crystal, vectors, Bravais2cart=True, printV=False)

Project vectors between Bravais basis and cartesian coordinate system.

Parameters:

Crystal – Crystal object.
vectors – Vectors to project from the Bravais basis to the cartesian coordinate system (if Bravais2cart is True) or to project from the cartesian coordinate system to the Bravais basis (if Bravais2cart is False).
Bravais2cart (bool) – If True, project from Bravais to cartesian.
printV (bool) – If True, prints the resulting vectors.

Returns:

Array of projected vectors.

Return type:

np.ndarray

pyNanoMatBuilder.utils.crystals.G(Crystal)

Compute the metric tensor (G) of a crystal’s unit cell.

The metric tensor is calculated based on the unit cell parameters: the lengths of the unit cell vectors (a, b, c) and the angles (alpha, beta, gamma) between them.

Reference:: https://fr.wikibooks.org/wiki/Cristallographie_g%C3%A9om%C3%A9trique/ Outils_math%C3%A9matiques_pour_l%27%C3%A9tude_du_r%C3%A9seau_cristallin

Parameters:: Crystal – Crystal object.
Returns:: The 3x3 metric tensor (G) of the unit cell.
Return type:: numpy.ndarray

pyNanoMatBuilder.utils.crystals.Gstar(Crystal)

Compute the inverse of the metric tensor (G*) for a crystal’s unit cell.

Parameters:: Crystal – Crystal object.
Returns:: The 3x3 inverse metric tensor (G*) of the unit cell.
Return type:: numpy.ndarray

I/O (io.py)

pyNanoMatBuilder.utils.io.returnUnitcellData(system)

Function that calculates various unit cell properties from the system.cif object and assigns them to attributes within the system instance.

Parameters:: data. (An instance of the Crystal class containing CIF file)

pyNanoMatBuilder.utils.io.listCifsOfTheDatabase(): Display all CIF filenames in the database.

pyNanoMatBuilder.utils.io.get_crystal_type(self)

Find the Bravais lattice based on the space group number.

Returns:: Bravais lattice
Return type:: str

pyNanoMatBuilder.utils.io.extract_cif_info(self, cif_file)

Extract useful information from a CIF file.

Parameters:

cif_file – CIF file.

Returns:

A dictionary containing extracted CIF information:

’cif_path’ (Path): Absolute path to the CIF file.
’crystal_type’ (str): The crystal type.
’Unitcell_param’ (list): Unit cell parameters [a, b, c, α, β, γ].
’ucBL’ (str): Bravais lattice type.

Return type:

dict

pyNanoMatBuilder.utils.io.load_cif(self, cif_file, noOutput)

Loads a CIF file and extracts its information if it has not been loaded before. :param cif_file: a CIF file. :param noOutput: If False, prints the CIF file path. :type noOutput: bool

Returns:: Extracted CIF information (from extract_cif_info).
Return type:: dict

Notes: - CIF files are assumed to be stored in the “cif_database” directory. - If the file has already been loaded, its information is retrieved from self.loaded_cifs.

pyNanoMatBuilder.utils.io.ciflist(dbFolder='resources/cif_database'): Function that prints the CIF files in the built-in dataset. :param dbFolder: The database folder name (default is resources/cif_database).

pyNanoMatBuilder.utils.io.write(filename: str, atoms, wa='w', **kwargs)

Unified write function for pyNanoMatBuilder.

This function serves as a central hub for exporting data. It handles directory creation automatically and routes the data to the appropriate writer based on the file extension.

Parameters:

filename (str) – Path to the output file (e.g., ‘coords/np.xyz’).
atoms (ase.Atoms or str) – The atomic structure to save, or a string containing script content for .script/.spt files.
wa (str, optional) – Write mode. ‘w’ for overwrite (default) or ‘a’ for append (useful for multi-frame trajectories).
**kwargs – Additional arguments passed to the underlying ASE write function (e.g., ‘format’).

Note

Automatically creates parent directories if they do not exist.
Uses internal ‘writexyz’ for .xyz files to preserve custom headers.
Uses ASE for crystallography formats (.cif, .res, .pdb, etc.).
Handles raw text writing for Jmol scripts (.script, .spt).

pyNanoMatBuilder.utils.io.writexyz(filename: str, atoms: Atoms, wa: str = 'w'): Simple xyz writing, with atomic symbols/x/y/z and no other information. Automatically creates the parent directories if they do not exist. :param filename: Output filename. :type filename: str :param atoms: ASE Atoms object. :type atoms: Atoms :param wa: Write mode (‘w’ or ‘a’). :type wa: str

pyNanoMatBuilder.utils.io.create_data_csv(path_of_files, path_of_csvfiles, noOutput)

Extract dictionaries from XYZ/CSV files and create new CSV files.

Parameters:

path_of_files – Path of the directory containing the files.
path_of_csvfiles – Path of the directory where the CSV file will be created.
noOutput – If True, suppresses print statements.

Returns:

None

pyNanoMatBuilder.utils.io.imageNameWithPathway(imgName)

Construct the full file path for an image.

Constructs the full file path for an image by joining the base directory with the image name.

Parameters:: imgName (str) – The name of the image file.
Returns:: The full file path to the image file.
Return type:: str

pyNanoMatBuilder.utils.io.plotImageInPropFunction(imageFile, figsize=(2, 10), rot=0)

Plot an image using matplotlib with optional rotation and no axes.

Parameters:

imageFile (str) – The path to the image file to be displayed.
figsize (tuple) – Figure size (width, height) in inches.
rot (float) – Rotation angle in degrees (counter-clockwise).

pyNanoMatBuilder.utils.io.createDir(path2, forceDel=False)

Creates a directory at the specified path.

If the directory already exists, it will either be left unchanged or deleted and recreated based on the ‘forceDel’ argument.

Parameters:

path2 (str) – The path where the directory should be created.
forceDel (bool, optional) – If set to True, will delete the existing directory and recreate it. Default is False.

Returns:

None

Energy (energy.py)

pyNanoMatBuilder.utils.energy.full_diagnosticsEMT(atoms, verbose=True)

Run basic diagnostics on an ASE Atoms object for EMT calculations.

Parameters:

atoms – ASE Atoms object to diagnose.
verbose (bool) – If True, prints diagnostic details.

Returns:

True if no obvious fatal problems are found, else False.

Return type:

bool

pyNanoMatBuilder.utils.energy.optimizeEMT(model: Atoms, saveCoords=True, pathway='./coords/model', fthreshold=0.1)

Optimize the geometry of an atomic system using EMT and Quasi-Newton.

Parameters:

model (ase.Atoms) – Atomic system to optimize.
saveCoords (bool, optional) – If True, saves the optimized coordinates.
pathway (str, optional) – Path to save the trajectory and final structure.
fthreshold (float, optional) – Convergence threshold for forces (in eV/Å).

Returns:

Optimized atomic model.

Return type:

ase.Atoms

pyNanoMatBuilder.utils.energy.optimize(self, calculator='EMT', optimizer='QN', fthreshold=0.1)

Optimize the geometry of an atomic system using various energy calculators and geometry optimization algorithms.

Parameters:

model (ase.Atoms) – Atomic system to optimize.
saveCoords (bool, optional) – If True, saves the optimized coordinates.
pathway (str, optional) – Path to save the trajectory and final structure.
fthreshold (float, optional) – Convergence threshold for forces (in eV/Å).

Creates:: self.NP_opt (ase.Atoms): Optimized atomic model.
The following properties are also created, by calling propPostMake(): self.cog_opt self.vertices_opt self.simplices_opt self.neighbors_opt self.equations_opt jMolCS_opt

Properties (prop.py)

pyNanoMatBuilder.utils.prop.calculateCN(coords, Rmax)

Calculate the coordination number (CN) for each atom.

The coordination number is determined by counting neighbors within a spherical cutoff distance defined by Rmax.

Parameters:

coords (numpy.ndarray) – An (N, 3) array containing the Cartesian coordinates for each of the N points.
r_max (float) – The threshold distance (cutoff) used to define a coordination bond.

Returns:

An array of length N containing the calculated: coordination number for each atom.

Return type:

numpy.ndarray

pyNanoMatBuilder.utils.prop.delAtomsWithCN(coords: ndarray, Rmax: float64, targetCN: int = 12)

Return the coordination number of each atom.

CN is calculated after threshold Rmax.

Parameters:

coords – numpy array with shape (N,3) containing 3 coordinates for each of N points.
Rmax – threshold to calculate CN.

Returns:

Array containing CN for each atom.

Return type:

np.ndarray

pyNanoMatBuilder.utils.prop.findNeighbours(coords, Rmax)

Find all atoms j within cutoff distance Rmax from atom i.

For all atoms i, returns the list of all atoms j within an arbitrarily determined cutoff distance Rmax from atom i.

Parameters:

coords – numpy array with the N-atoms cartesian coordinates.
Rmax – cutoff distance.

Returns:

List of lists (len(list[i]) = number of nearest neighbours of atom i).

Return type:

list

pyNanoMatBuilder.utils.prop.printNeighbours(nn)

Print the list of nearest neighbours of each atom.

Parameters:: nn – Nearest neighbours given as a list of lists.

pyNanoMatBuilder.utils.prop.kDTreeCN(crystal: Atoms, Rmax: float = 2.9, returnD: bool = False, noOutput: bool = False)

Return the nearest neighbour (nn) table and number of NN per atom.

Parameters:

crystal (Atoms) – Crystal structure object.
Rmax (float) – The NN threshold.
returnD (bool) – If True, distances between NN are returned as well.
noOutput (bool) – If True, suppresses output messages.

Returns:

(nn, CN) or (nn, CN, dNN) if returnD is True.

Return type:

tuple

pyNanoMatBuilder.utils.prop.magicNumbers(cluster, i)

Calculate magic numbers for nanocluster stable structures.

Certain collections of atoms are more preferred due to energy minimization and exhibiting stable structures and providing unique properties to the materials. These collections of atoms providing stable structures to the materials are called MAGIC NUMBERS.

This function uses specific formulas based on the type of nanocluster (e.g., ‘regfccOh’, ‘regIco’, ‘fccCube’, etc.) to calculate a magic number based on the index i.

Parameters:

cluster (str) – The type of nanocluster for which the magic number is calculated. It can be one of the following values: ‘regfccOh’, ‘regIco’, ‘regfccTd’, ‘regDD’, ‘fccCube’, ‘bccCube’, ‘fccCubo’, ‘fccTrOh’, ‘fccTrCube’, ‘bccrDD’, ‘fccdrDD’, ‘pbpy’.
i (int) – The index of the nanocluster size. It must be a positive integer greater than zero.

Returns:

The calculated magic number for the specified nanocluster type: and index i.

Return type:

float

pyNanoMatBuilder.utils.prop.rdf(NP: Atoms, dr: float = 0.05, sigma: float = 2, ncores: int = 1, noOutput: bool = True)

rdf - g(r) - calculator for non-PBC systems.

Parameters:

NP (Atoms) – ase Atoms object
dr (float) – determines the spacing between successive radii over which g(r) is computed. Default: 0.05
sigma (float) – standard deviation for Gaussian kernel. Default: 2
ncores (int) – number of jobs to schedule for parallel processing (only used by query_ball_point() of scipy.spatial.KDTree). Default: 1
noOutput (bool) – do not print anything. Default: True

Returns:

r and g(r)

Wanna know more? Read https://doi.org/10.1021/acs.chemrev.1c00237

pyNanoMatBuilder.utils.prop.moi(model: Atoms, noOutput: bool = False)

Get the moments of inertia along the principal axes.

Notes

Units of the moments of inertia are amu.angstrom**2. Periodic boundary conditions are ignored.

pyNanoMatBuilder.utils.prop.get_moments_of_inertia_for_size(self, vectors=False)

Get the moments of inertia along the principal axes with mass normalization.

Parameters:: vectors (bool, optional) – If True, returns both eigenvalues and eigenvectors. If False, returns only eigenvalues. Defaults to False.
Returns:: Principal moments of inertia (3 values). np.ndarray: Principal axes (3x3 matrix) if vectors is True.
Return type:: np.ndarray

Notes

Periodic boundary conditions are ignored. Units of the moments of inertia are angstrom**2.

pyNanoMatBuilder.utils.prop.moi_size(model: Atoms, noOutput: bool = False)

Get the moments of inertia along the principal axes with mass normalization.

Notes

Units of the moments of inertia are angstrom**2.

pyNanoMatBuilder.utils.prop.calculate_rg(model: Atoms, mass_weighted=True, noOutput: bool = False)

Calculates the radius of gyration for an ASE Atoms object.

Parameters:

atoms (ase.Atoms) – The system to analyze.
mass_weighted (bool) – If True, weights by atomic mass. If False, calculates geometric Rg.
noOutput (bool) – If False, prints a formatted summary.

Returns:

The radius of gyration in nm.

Return type:

float

pyNanoMatBuilder.utils.prop.calculate_npr(moi, noOutput: bool = False)

Calculates Normalized Principal Moments of Inertia (NPR).

Returns:

[npr1, npr2] where npr1 = I1/I3 and npr2 = I2/I3.: Returns (1.0, 1.0) for single atoms to avoid division by zero.

Return type:

list

pyNanoMatBuilder.utils.prop.Inscribed_circumscribed_spheres(self, noOutput)

Calculates the diameters of the inscribed and circumscribed spheres for the nanoparticle (NP) based on its positions and the plane equations.

The circumscribed sphere is the smallest sphere that completely encloses the NP, while the inscribed sphere is the largest sphere that fits within the NP.

Parameters:

noOutput (bool, optional) – If set to True, suppresses output during the analysis. Default is False.

Returns:

The function updates the object’s attributes with the calculated: radius of the spheres, in Angströms.

Return type:

None

Notes

The circumscribed sphere radius is calculated as the maximum distance from the center of gravity (COG) to the NP positions, and the inscribed sphere radius is calculated as the minimum distance from the NP positions to the planes (based on Hull equations)

pyNanoMatBuilder.utils.prop.get_ellipsoid_analysis(self, noOutput=False)

Perform a Principal Component Analysis (PCA) on the outer envelope to calculate the best-fitting circumscribed ellipsoid.

This method identifies the principal axes of the nanoparticle’s surface by analyzing the covariance matrix of the Convex Hull vertices. The resulting ellipsoid is scaled such that its major semi-axis matches the maximum radial distance found in the structure, ensuring a perfect fit for circumscribed diameter measurements (e.g., 1.63 nm for a 3-shell icosahedron).

The analysis automatically selects between ‘initial structure’ and ‘optimized structure’ based on the current state of the object.

Parameters:

noOutput (bool) – If True, suppresses printed summaries and Jmol command generation. Defaults to False.

Returns:

A dictionary containing the following physical properties:

”status”: String indicating which envelope was analyzed.
”D1”, “D2”, “D3”: Major, intermediate, and minor diameters (Å).
”volume”: Volume of the ellipsoid (Å³).
”surface”: Approximate surface area (Å²) using Knud Thomsen’s formula.
”asphericity”: Ratio of D1/D3 (1.0 for a perfect sphere).

Return type:

dict

Raises:

ValueError – If fewer than 4 Hull vertices are found, indicating that coreSurface() has not been run or the NP is invalid.

Notes

Scaling Logic: The semi-axes are derived from the square root of the eigenvalues of the covariance matrix. The scale factor is defined as: scale = max_radius / sqrt(max_eigenvalue).
Surface Area: Calculated using an approximation with p=1.6075, limiting the maximum relative error to 1.061%.
Visualization: Generates a Jmol-ready command using the ‘AXES’ and ‘CENTER’ keywords for precise orientation.

pyNanoMatBuilder.utils.prop.propPostMake(self, skipChiralityCalculation, skipSymmetryAnalyzis, thresholdCoreSurface, noOutput, is_optimized=False)

Compute and store various post-construction properties of the nanoparticle.

This function calculates moments of inertia (MOI), determines the nanoparticle shape, analyzes symmetry (if required), and identifies core and surface atoms.

Parameters:

skipChiralityCalculation (bool) – If True, skips the calculation of the opd index
skipSymmetryAnalyzis (bool) – If True, skips symmetry analysis.
thresholdCoreSurface (float) – Threshold to distinguish core and surface atoms.
noOutput (bool) – If True, suppresses output messages.

pyNanoMatBuilder.utils.prop.moi

Moment of inertia tensor.

Type:: numpy.ndarray

pyNanoMatBuilder.utils.prop.moisize

Normalized moments of inertia.

Type:: numpy.ndarray

pyNanoMatBuilder.utils.prop.vertices

Geometric vertices of the nanoparticle.

Type:: numpy.ndarray

pyNanoMatBuilder.utils.prop.simplices

Simplices defining the convex hull.

Type:: numpy.ndarray

pyNanoMatBuilder.utils.prop.neighbors

Neighboring relations between facets.

Type:: numpy.ndarray

pyNanoMatBuilder.utils.prop.equations

Plane equations for the hull faces.

Type:: numpy.ndarray

pyNanoMatBuilder.utils.prop.NPcs

Copy of the nanoparticle with surface atoms visually marked.

Type:: ase.Atoms

pyNanoMatBuilder.utils.prop.NP

Original nanoparticle object.

Type:: ase.Atoms

pyNanoMatBuilder.utils.prop.sasview_dims

Dimensions for SasView, calculated only if the sasview_dims() method exists.

Type:: tuple, optional

pyNanoMatBuilder.utils.prop.NPR

normalized ratios of principal moments of inertia $NPR_{1}=I_{1}/I_{3}$ and $NPR_{2}=I_{2}/I_{3}$

Type:: numpy.ndarray

pyNanoMatBuilder.utils.prop.Rg

Radius of Gyration, in nm

Type:: float

pyNanoMatBuilder.utils.prop.compute_opd_index(NP: Atoms, cutoff=6.0, noOutput=False)

High-performance Scaled Osipov–Pickup–Dunmur chirality index computation. Article: 10.1080/00268979500100831 Uses KDTree for neighbor searching and Numba for parallelized math.

Parameters:

NP (ase.Atoms) – ase object.
cutoff (float) – Radius for neighbor search (in Angstroms).

Returns:

The scaled chirality index G0s.

Return type:

float

External programs (external_pgm.py)

pyNanoMatBuilder.utils.external_pgm.check_jmol()

pyNanoMatBuilder.utils.external_pgm.saveCoords_DrawJmol(asemol, prefix, scriptJ='', boundaries=False, noOutput=True)

Save coordinates and generate a Jmol visualization.

Parameters:

asemol – ASE Atoms object to visualize.
prefix (str) – Filename prefix for output files.
scriptJ (str) – Additional Jmol script commands.
boundaries (bool) – If True, draws boundaries without facets script.
noOutput (bool) – If True, suppresses command output.

pyNanoMatBuilder.utils.external_pgm.defCrystalShapeForJMol(self, noOutput: bool = True)

Generate a Jmol command to visualize the crystal shape based on the facets of the NP.

Parameters:: noOutput (bool) – If True, suppresses the output of the command.
Returns:: The Jmol command string for visualizing the crystal shape.
Return type:: str

pyNanoMatBuilder.utils.external_pgm.saveCN4JMol(Crystal: Atoms, save2: str = 'CN.dat', Rmax: float = 3.0, noOutput: bool = False)

Calculates the coordination number (CN) for a given crystal and generates a Jmol command for visualization.

Parameters:

Crystal (Atoms) – The crystal structure object.
save2 (str, optional) – The filename to save the coordination numbers. Defaults to ‘CN.dat’.
Rmax (float, optional) – The maximum distance for neighbors when calculating CN. Defaults to 3.0.
noOutput (bool, optional) – If set to True, suppresses the output. Defaults to False.

Returns:

None

pyNanoMatBuilder.utils.external_pgm.DrawJmol(mol, prefix, scriptJ='', noOutput=True): Generate a Jmol visualization from an existing XYZ file.

Visualization (visualID.py)

pyNanoMatBuilder.visualID.apply_css_style(): Explicitly reads and applies the visualID CSS stylesheet from the package resources.

pyNanoMatBuilder.visualID.display_md(text)

pyNanoMatBuilder.visualID.hdelay(sec)

pyNanoMatBuilder.visualID.hdelay_ms(delay)

pyNanoMatBuilder.visualID.init(): Initializes the notebook environment: applies CSS, displays the banner, and shows hostname/time. Also reports the parallel computing status

pyNanoMatBuilder.visualID.end(): Terminates the notebook session: displays duration, end time, and the termination logo from package resources.