📚 API Documentation

MOXελ is a Python package for parallel calculation of energy voxels, with emphasis on reticular chemistry.

moxel.utils

This module provides helper functions for creating voxels.

Note

Currently, interactions are modelled with the Lennard-Jones (LJ) potential.

Attention

Consider tuning the n_jobs parameter to get the best performance for your system:

from timeit import timeit

setup = 'from moxel.utils import voxels_from_file'
n_jobs = [1, 2, 8, 16]  # Modify this according to your system.

for n in n_jobs:
    stmt = f'voxels_from_file("path/to/cif", n_jobs={n})'
    time = timeit(stmt=stmt, setup=setup, number=1)
    print(f'Time with {n} jobs: {time:.3f} s')

class moxel.utils.Grid(grid_size=25, *, cutoff=10.0, epsilon=50.0, sigma=2.5)[source]

A 3D energy grid over a crystal structure.

Parameters:

grid_size (int, default=25) – Number of grid points along each dimension.
cutoff (float, default=10.0) – Cutoff radius (Å) for the LJ potential.
epsilon (float, default=50.0) – Epsilon value (ε/K) of the probe atom.
sigma (float, default=2.5) – Sigma value (σ/Å) of the probe atom.

structure

Available only after Grid.load_structure() has been called.

Type:: pymatgen.core.structure.Structure

structure_name

Available only after Grid.load_structure() has been called.

Type:: str

cubic_box

Available only after Grid.calculate() has been called.

Type:: bool

voxels

Available only after Grid.calculate() has been called.

Type:: array of shape (grid_size,)*3

calculate(cubic_box=False, length=30.0, potential='lj', clip=None, n_jobs=None)[source]

Iterate over the grid and return voxels.

For computational efficiency and to assure (approximately) the same spatial resolution, the grid is overlayed over a supercell scaled according to MIC, see mic_scale_factors().

If lattice angles are significantly different than 90°, to avoid distortions set cubic_box to True. In this case, the grid is overlayed over a cubic box of size length centered at the origin but periodicity is no longer guaranteed.

Parameters:

potential (str, default='lj') – The potential used to calculate voxels. Currently, only the LJ potential is supported.
cubic_box (bool, default=False) – If True, the simulation box is cubic.
length (float, default=30.0) – The size of the cubic box in Å. Takes effect only if cubic_box=True.
clip (float, optional) – If specified, voxels are filled with energy values clipped within [-clip, clip]. Otherwise, voxels are filled with the Boltzmann factor.
n_jobs (int, optional) – Number of jobs to run in parallel. If None, then the number returned by os.cpu_count() is used.

Returns:

voxels

Return type:

array of shape (grid_size,)*3

lj_potential(coords)[source]

Calculate LJ potential at cartesian or fractional coordinates.

Parameters:: coordinates (array_like of shape (3,)) – If cubic_box=True cartesian. Else, fractional.
Returns:: energy
Return type:: float

load_structure(pathname)[source]

Load a crystal structure from a file in a format supported by pymatgen.core.Structure.from_file().

Parameters:: pathname (str) – Pathname to the file.

moxel.utils.mic_scale_factors(r, lattice_vectors)[source]

Return scale factors to satisfy minimum image convention [MIC].

Parameters:

r (float) – The cutoff radius used in MIC convetion.
lattice_vectors (array of shape (3, 3)) – The lattice vectors of the unit cell. Each row corresponds to a lattice vector.

Returns:

scale_factors – scale_factors[i] scales lattice_vectors[i].

Return type:

array of shape (3,)

References

[MIC]

Smith, “The Minimum Image Convention in Non-Cubic MD Cells”, 1989.

moxel.utils.voxels_from_dir(cif_dirname, out_pathname, grid_size=25, *, cutoff=10.0, epsilon=50.0, sigma=2.5, cubic_box=False, length=30.0, clip=None, n_jobs=None)[source]

Calculate voxels from a directory of .cif files and store them.

Voxels are stored under out_pathname as .npy files.

Parameters:

cif_dirname (str) – Pathname to the directory containing the .cif files.
out_pathname (str) – Pathname to the directory under which voxels are stored.
grid_size (int, default=25) – Number of grid points along each dimension.
cutoff (float, default=10.0) – Cutoff radius (Å) for the LJ potential.
epsilon (float, default=50.0) – Epsilon value (ε/K) of the probe atom.
sigma (float, default=2.5) – Sigma value (σ/Å) of the probe atom.
cubic_box (bool, default=False) – If True, the simulation box is cubic.
length (float, default=30.0) – The size of the cubic box in Å. Takes effect only if cubic_box=True.
clip (float, optional) – If specified, voxels are filled with energy values clipped within [-clip, clip]. Otherwise, voxels are filled with the Boltzmann factor.
n_jobs (int, optional) – Number of jobs to run in parallel. If None, then the number returned by os.cpu_count() is used.

Notes

Structures that can’t be processsed are omitted.

moxel.utils.voxels_from_file(cif_pathname, grid_size=25, *, cutoff=10.0, epsilon=50.0, sigma=2.5, cubic_box=False, length=30.0, clip=None, n_jobs=None, only_voxels=True)[source]

Calculate and return voxels from .cif file.

Parameters:

cif_pathname (str) – Pathname to the .cif file.
only_voxels (bool, default=True) – Determines out type.

Returns:

out – If only_voxels=True array, else Grid.

Return type:

array or Grid