API reference

The AtomPacker is a Python package for packing nanoclusters into supramolecular cages. It provides a set of tools for detecting cavities in molecular structures, packing nanoclusters into these cavities, and exporting the resulting structures.

class AtomPacker.Cage[source]

A container for the atoms of a macromolecular structure.

The AtomPacker.Cage class is used to store the atoms of a macromolecular structure.

property atomic: ndarray

Get the coordinates of the atoms in the molecular structure.

Returns:: An array containing the atomic information. The array has the following columns: resnum, chain, resname, element, x, y, z, radius.
Return type:: numpy.ndarray

property centroid: ndarray

Get the centroid of the cage structure.

Returns:: An array containing the xyz coordinates of the centroid of the cage structure.
Return type:: numpy.ndarray
Raises:: ValueError – If the cage is not loaded.

property coordinates: ndarray

Get the coordinates of the atoms in the molecular structure.

Returns:: An array containing the atomic coordinates. The array has the following columns: x, y, z.
Return type:: numpy.ndarray

detect_cavity(step: float = 0.6, probe_in: float = 1.4, probe_out: float = 10.0, removal_distance: float = 2.4, volume_cutoff: float = 100.0, surface: str = 'SES', nthreads: int | None = None, verbose: bool = False, **kwargs: Dict[str, Any]) → Cavity[source]

Detect the cavity in the macromolecular structure.

Parameters:

step (float, optional) – The grid spacing for the cavity detection algorithm.
probe_in (float, optional) – The radius of the inner probe.
probe_out (float, optional) – The radius of the outer probe.
removal_distance (float, optional) – The distance to remove atoms from the cavity.
volume_cutoff (float, optional) – The volume cutoff for the cavity.
surface (str, optional) – Surface representation. Keywords options are SES (Solvent Excluded Surface) or SAS (Solvent Accessible Surface), by default SES.
nthreads (int, optional) – Number of threads, by default None. If None, the number of threads is os.cpu_count() - 1.
verbose (bool, optional) – Print extra information to standard output, by default False.
kwargs (Dict[str, Any]) – Additional keyword arguments to pass to the cavity detection algorithm (pyKVFinder.detect) of pyKVFinder package.

Returns:

The cavity object. The cavity object contains the grid points of the cavity, the step size, the Probe In radius, the Probe Out radius, the removal distance, the volume cutoff, and the vertices (origin, X-axis, Y-axis, Z-axis) of the grid. Cavity points in the 3D grid (grid[nx][ny][nz]). Cavities array has integer labels in each position, that are:

-1: solvent points;
0: cage points;
1: empty space points;
>=2: cavity points.

The empty space points are regions that do not meet the chosen volume cutoff to be considered a cavity.

Return type:

Cavity

Raises:

ValueError – If the cage is not loaded.

load(filename: str, vdw: Dict[str, float] | None = None) → None[source]

Load a supramolecular cage structure file into the MDAnalysis .Univese object.

Parameters:

filename (str) – The filename of the structure file. The file format is determined by the suffix. Supported formats are: .cif, .mol2, .pdb, .xyz.
vdw (Dict[str, float], optional) – A dictionary containing the van der Waals radii for each atom type, by default None. If None, the van der Waals radii are looked up from the pyKVFinder package.

Returns:

universe – The MDAnalysis universe object containing the structure.

Return type:

MDAnalysis.Univese

Raises:

ValueError – If the file format is not supported.

pack(atom_type: str, lattice_type: str, a: float | None = None, b: float | None = None, c: float | None = None, clashing_tolerance: float = 0.0, optimize: bool = False, angles: ndarray | None = None, translations: ndarray | None = None) → Cluster[source]

Pack the cluster of atoms into the cage structure.

Parameters:

atom_type (str) – The type of atom in the cluster.
lattice_type (str) – The type of lattice in the cluster. The available lattice types are ‘bcc’, ‘fcc’, ‘hcp’, and ‘sc’, that are based on the ase.cluster module. The ase.cluster developers state that the module works properly for the three cubic crystal structures: FaceCenteredCubic (‘fcc’), BodyCenteredCubic (‘bcc’), and SimpleCubic (‘sc’). Other structures like HexagonalClosedPacked (‘hcp’) is implemented, but currently do not work correctly.
a (float, optional) – The lattice constant a. If not specified, the lattice constant will be fetched from AtomPacker.data.lattice_constants if available. If not, the experimental values from ase.data will be used.
b (float, optional) – The lattice constant b. If not specified, the lattice constant will be fetched from AtomPacker.data.lattice_constants if available. If not, the experimental values from ase.data will be used.
c (float, optional) – The lattice constant c. If not specified, the lattice constant will be fetched from AtomPacker.data.lattice_constants if available. If not, the experimental values from ase.data will be used.
clashing_tolerance (float, optional) – The clashing tolerance (Å), by default 0.0.
optimize (bool, optional) – Optimize the cluster packing, by default False.
angles (numpy.ndarray, optional) – The rotation angles for the cluster optimization, by default None. If None, the angles are [-75, -50, -25, 0, 25, 50, 75].
translations (numpy.ndarray, optional) – The translations for the cluster optimization, by default None. If None, the translations are [-0.2, 0.0, 0.2].

Raises:

ValueError – If the cage is not loaded.
ValueError – If the cavity is not detected.
ValueError – If the clashing tolerance is less than 0.

preview(show_cavity: bool = False, show_cluster: bool = False, renderer: str = 'browser', **kwargs: Dict[str, Any]) → None[source]

Preview the cage system (cage, cavity, and cluster) in a 3D viewer.

Parameters:

show_cavity (bool, optional) – Show the cavity in the 3D viewer, by default False.
show_cluster (bool, optional) – Show the cluster in the 3D viewer, by default False.
renderer (str, optional) – The renderer to use for the 3D viewer. Supported renderers are ‘browser’ (default), ‘notebook’ and ‘png’.
**kwargs (Dict[str, Any]) – Additional keyword arguments to pass to the scatter_3d function of the plotly.express package.

Raises:

ValueError – If the cage is not loaded.

Warns:

UserWarning – If the cavity is not detected, a warning is issued.
UserWarning – If the cluster is not packed, a warning is issued.

class AtomPacker.Cavity(grid: ndarray, step: float, probe_in: float, probe_out: float, removal_distance: float, volume_cutoff: float, vertices: ndarray, surface: str = 'SES')[source]

A class representing a cavity in a molecular structure.

The Cavity class provides methods for detecting cavities, calculating cavity properties, and exporting cavity data.

property coordinates: ndarray: Get the xyz coordinates of the cavity.

preview(renderer: str = 'browser', opacity: float = 1.0, **kwargs: Dict[str, Any]) → None[source]

Preview the cavity in a 3D viewer.

Parameters:

renderer (str, optional) – The renderer to use for the 3D viewer. Supported renderers are ‘browser’ (default), ‘notebook’ and ‘png’.
opacity (float, optional) – The opacity of the atoms in the 3D viewer, by default 1.0. The opacity value ranges from 0.0 (completely transparent) to 1.0 (completely opaque).
**kwargs (Dict[str, Any]) – Additional keyword arguments to pass to the scatter_3d function of the plotly.express package.

save(filename: str = 'cavity.pdb') → None[source]

Export the cavity data to a file.

This method exports the cavity data represented by the Cavity object to a file in a specified format. The supported formats include PDB, and XYZ.

Parameters:: filename (str) – The name of the file to export the cavity data to. The filename of the structure file. The file format is determined by the suffix. Supported formats are: .pdb, .xyz.

select_cavity(indices: List[int]) → None[source]

Select a cavity from the list of detected cavities.

This method selects a cavity from the list of detected cavities based on the indices of the cavity in the list.

Parameters:

indices (List[int]) –

The indices of the cavities to select. Cavity points in the 3D grid (grid[nx][ny][nz]). Cavities array has integer labels in each position, that are:

-1: solvent points;
0: cage points;
1: empty space points;
>=2: cavity points.

property volume: float64

Calculate the volume of the cavity.

This method calculates the volume of the cavity represented by the Cavity object. It uses a grid-based algorithm to estimate the volume of the cavity based on the number of grid points inside the cavity.

class AtomPacker.Cluster(cluster: Cluster, cavity: Cavity)[source]

A class representing a cluster of atoms inside a supramolecular cage.

The Cluster class provides methods for calculating cluster properties and exporting cluster data.

property coordinates: Return the coordinates of the atoms in the cluster.

diameter(method: str = 'maximum') → float[source]

Calculate the diameter of the cluster.

Parameters:

method (str, optional) –

The method to use for calculating the diameter of the cluster. Supported methods are ‘maximum’ (default), ‘shape’, and ‘volume’.

’maximum’: calculates the maximum distance between any two atoms in the cluster, considering their radius.
’shape’: uses ase.cluster.Cluster.get_diameter(‘shape’) to return the diameter of a sphere with the same volume as the atoms.
’volume’: uses ase.cluster.Cluster.get_diameter(‘volume’) to return the averaged diameter calculated from the directions given by the defined surfaces.

Returns:

The diameter of the cluster.

Return type:

float

property maximum_number_of_atoms: int

Calculate the maximum number of atoms in the cluster.

The maximum number of atoms is calculated based on the volume of the cavity divided by the volume of the atom in the cluster. The formula is given by:

\[N_{max} = \left \lceil \frac{V_{cav}}{V_a} \right \rceil = \left \lceil \frac{V_{cav}}{\frac{4}{3}\pi R_a^3} \ \right \rceil\]

where \(V_{cav}\) is the volume of the cavity, \(V_a\) is the volume of the atom in the cluster, \(R_a\) is the radius of the atom in the cluster, and \(\lceil \cdot \rceil\) is the ceiling function.

property number_of_atoms: Get the number of atoms in the cluster.

preview(renderer: str = 'browser', opacity: float = 1.0, **kwargs: Dict[str, Any]) → None[source]

Preview the cavity in a 3D viewer.

Parameters:

renderer (str, optional) – The renderer to use for the 3D viewer. Supported renderers are ‘browser’ (default), ‘notebook’ and ‘png’.
opacity (float, optional) – The opacity of the atoms in the 3D viewer, by default 1.0. The opacity value ranges from 0.0 (completely transparent) to 1.0 (completely opaque).
**kwargs (Dict[str, Any]) – Additional keyword arguments to pass to the scatter_3d function of the plotly.express package.

save(filename: str = 'cluster.pdb') → None[source]

Export the cluster data to a file.

This method exports the cluster data represented by the Cluster object to a file in a specified format. The supported formats include PDB, and XYZ.

Parameters:: filename (str, optional) – The name of the file to export the cavity data to, by default “cluster.pdb”. The file format is determined by the suffix. Supported formats are: .pdb, .xyz.

property summary: DataFrame: Print a summary of the cluster properties.

AtomPacker.get_coordinates(grid: ndarray, step: float, vertices: ndarray) → ndarray[source]

Convert a grid of points to a numpy.ndarray of xyz coordinates.

Parameters:

grid (numpy.ndarray) – The grid points.
step (float) – The step size of the grid.
vertices (numpy.ndarray) – The vertices (origin, X-axis, Y-axis, Z-axis) of the grid.

Returns:

coordinates – The xyz coordinates of the grid points.

Return type:

numpy.ndarray

AtomPacker.get_depths(grid: ndarray, step: float) → ndarray[source]

Get the depth of a grid of cavity points.

Parameters:

grid (numpy.ndarray) – The grid of cavity points.
step (float) – The step size of the grid.

Returns:

depths – The depths of the cavity points.

Return type:

numpy.ndarray

AtomPacker.get_lattice_constants(atom_type: str, lattice_type: str) → Tuple[float, float, float] | Tuple[float, float] | float | None[source]

Get the lattice constants for a given atom type and lattice type.

Parameters:

atom_type (str) – The atomic symbol of the atom.
lattice_type (str) – The type of lattice in the cluster. The available lattice types are ‘bcc’, ‘fcc’, ‘hcp’ and ‘sc’.

Returns:

The lattice constants for the given atom type and lattice type. If None, use ase.data.reference_states.

Return type:

Tuple[float, float, float] | Tuple[float, float] | float | None

Note

The lattice constants will be fetched from AtomPacker.data.lattice_constants if available. If not, the experimental values from ase.data will be used.

Raises:: ValueError – If the lattice type is not valid.

AtomPacker.load_mmcif(filename: str, vdw: Dict[str, float] | None = None) → Universe[source]

Load a PDBx/mmCIF file into the MDAnalysis.Univese object.

Parameters:

filename (str) – The filename of the structure file.
vdw (Dict[str, float]) – A dictionary containing the van der Waals radii for each atom type, by default None. If None, the radii will be looked up from the pyKVFinder package.

Returns:

universe – The MDAnalysis universe object containing the structure.

Return type:

MDAnalysis.Univese

AtomPacker.load_mol2(filename: str, vdw: Dict[str, float] | None = None) → Universe[source]

Load a MOL2 file into the MDAnalysis.Univese object.

Parameters:

filename (str) – The filename of the structure file.
vdw (Dict[str, float]) – A dictionary containing the van der Waals radii for each atom type, by default None. If None, the radii will be looked up from the pyKVFinder package.

Returns:

universe – The MDAnalysis universe object containing the structure.

Return type:

MDAnalysis.Univese

AtomPacker.load_pdb(filename: str, vdw: Dict[str, float] | None = None) → Universe[source]

Load a PDB file into the MDAnalysis.Univese object.

Parameters:

filename (str) – The filename of the structure file.
vdw (Dict[str, float]) – A dictionary containing the van der Waals radii for each atom type, by default None. If None, the radii will be looked up from the pyKVFinder package.

Returns:

universe – The MDAnalysis universe object containing the structure.

Return type:

MDAnalysis.Univese

AtomPacker.load_xyz(filename: str, vdw: Dict[str, float] | None = None) → Universe[source]

Load a XYZ file into the MDAnalysis.Univese object.

Parameters:

filename (str) – The filename of the structure file.
vdw (Dict[str, float]) – A dictionary containing the van der Waals radii for each atom type, by default None. If None, the radii will be looked up from the pyKVFinder package.

Returns:

universe – The MDAnalysis universe object containing the structure.

Return type:

MDAnalysis.Univese