πŸ“š API Documentation

moxel package

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

Submodules

moxel.utils

This module provides helper functions for creating voxels.

Note

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

class moxel.utils.Grid(grid_size=25, cutoff=10, epsilon=50, sigma=2.5)[source]

Bases: object

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) – Cutoff radius (β„«) for the LJ potential.

  • epsilon (float, default=50) – 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, potential='lj', 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) – The size of the cubic box in Γ…. Takes effect only if cubic_box == True.

  • n_jobs (int, optional) – Number of jobs to run in parallel. If None, all processors are used.

Returns:

voxels – The energy voxels as \(e^{-\beta \mathcal{V}}\), to ensure numerical stability.

Return type:

array of shape (grid_size,)*3

Notes

For structures that can not be processsed, their voxels are filled with zeros.

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 – Energy as \(e^{-\beta \mathcal{V}}\), to ensure numerical stability.

Return type:

float

load_structure(cif_pathname)[source]

Load a crystal structure from a .cif file.

Parameters:

cif_pathname (str) – Pathname to the .cif file.

moxel.utils.batch_clean(batch_dirname)[source]

Clean a single batch.

The batch must have the form:

batch
β”œβ”€β”€voxels.npy
└──names.json

Cleaning is required since the voxels for some structures might be zero, see Grid.calculate(). After cleaning, the directory has the form:

batch
β”œβ”€β”€voxels.npy
β”œβ”€β”€names.json
β”œβ”€β”€clean_voxels.npy
└──clean_names.json
Parameters:

batch_dirname (str) – Pathname to the directory which requires cleaning.

Returns:

exit_status – If no voxels are missing 0 else 1.

Return type:

int

moxel.utils.get_names(fname)[source]

Load a list of material names saved in .json format.

Parameters:

fname (str) – Pathname to the .json file.

Returns:

names

Return type:

list

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]

  1. 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, epsilon=50, sigma=2.5, cubic_box=False, length=30, n_jobs=None)[source]

Calculate voxels from a directory of .cif files and save them under out_pathname as numpy.array of shape (n_samples, grid_size, grid_size, grid_size), where n_samples == len(cif_pathnames).

After processing the following files are created:

out_pathname
    β”œβ”€β”€voxels.npy
    └──names.json

The file names.json stores the names of the materials, which might be useful for later indexing.

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) – Cutoff radius (β„«) for the LJ potential.

  • epsilon (float, default=50) – Epsilon value (Ξ΅/K) of the probe atom.

  • sigma (float, default=25) – Sigma value (Οƒ/β„«) of the probe atom.

  • cubic_box (bool, default=False) – If True, the simulation box is cubic.

  • length (float, default=30) – The size of the cubic box in Γ…. Takes effect only if cubic_box == True.

  • n_jobs (int, optional) – Number of jobs to run in parallel. If None, all processors are used.

Notes

  • Samples in output array follow the order in sorted(os.listdir(cif_dirname)).

  • For structures that can not be processsed, their voxels are filled with zeros.

moxel.utils.voxels_from_file(cif_pathname, grid_size=25, cutoff=10, epsilon=50, sigma=2.5, cubic_box=False, length=30, n_jobs=None, only_voxels=True)[source]

Return voxels from .cif file.

Parameters:

  • cif_pathname (str) – Pathname to the .cif file.

  • grid_size (int, default=25) – Number of grid points along each dimension.

  • cutoff (float, default=10) – Cutoff radius (β„«) for the LJ potential.

  • epsilon (float, default=50) – Epsilon value (Ξ΅/K) of the probe atom.

  • sigma (float, default=25) – Sigma value (Οƒ/β„«) of the probe atom.

  • cubic_box (bool, default=False) – If True, the simulation box is cubic.

  • length (float, default=30) – The size of the cubic box in Γ…. Takes effect only if cubic_box == True.

  • n_jobs (int, optional) – Number of jobs to run in parallel. If None, all processors are used.

  • only_voxels (bool, default=True) – Determines out type.

Returns:

out – If only_voxels == True, array of shape (grid_size,)*3. Otherwise, Grid.

Return type:

array or Grid

Notes

For structures that can not be processsed, their voxels are filled with zeros.

moxel.utils.voxels_from_files(cif_pathnames, out_pathname, grid_size=25, cutoff=10, epsilon=50, sigma=2.5, cubic_box=False, length=30, n_jobs=None)[source]

Calculate voxels from a list of .cif files and store them under out_pathname as numpy.array of shape (n_samples, grid_size, grid_size, grid_size), where n_samples == len(cif_pathnames).

After processing the following files are created:

out_pathname
    β”œβ”€β”€voxels.npy
    └──names.json

The file names.json stores the names of the materials, which might be useful for later indexing.

Parameters:

  • cif_pathnames (list) – List of pathnames to 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) – Cutoff radius (β„«) for the LJ potential.

  • epsilon (float, default=50) – Epsilon value (Ξ΅/K) of the probe atom.

  • sigma (float, default=25) – Sigma value (Οƒ/β„«) of the probe atom.

  • cubic_box (bool, default=False) – If True, the simulation box is cubic.

  • length (float, default=30) – The size of the cubic box in Γ…. Takes effect only if cubic_box == True.

  • n_jobs (int, optional) – Number of jobs to run in parallel. If None, all processors are used.

Notes

  • Samples in output array follow the order in cif_pathnames.

  • For structures that can not be processsed, their voxels are filled with zeros.

moxel.visualize

This module provides helper functions for visualizing voxels.

Tip

For faster rendering you should prefer plot_voxels_pv().

moxel.visualize.plot_voxels_mpl(voxels, *, fill_pattern=None, colorbar=True, cmap='viridis', **kwargs)[source]

Visualize voxels with Axes3d.voxels.

Parameters:

  • voxels (3D array)

  • fill_pattern (3D array of bool, optional) – A 3D array of truthy values, indicating which voxels to fill. If not specified, all voxels are filled.

  • colorbar (bool, default=True) – Whether to include a colorbar.

  • cmap (str, default='viridis') – Colormap that colorizes the voxels based on their value.

  • **kwargs –

    Valid keyword arguments for Axes3d.voxels.

    Note

    Do not pass the argument facecolors of Axes3d.voxels. This argument is used under the hood by plot_voxels() to generate the colors of the voxels based on the specified cmap.

Returns:

fig

Return type:

Figure

Examples

>>> fig = plot_voxels_mpl(voxels, cmap='coolwarm')
moxel.visualize.plot_voxels_pv(voxels, **kwargs)[source]

Visualize voxels with Plotter.add_volume

Note

For interactive plots in Jupyter: pip install "pyvista[jupyter]"

Parameters:

  • voxels (3D array)

  • **kwargs (dict, optional) – Valid keyword arguments for Plotter.add_volume.

Examples

>>> plot_voxels_pv(voxels, cmap='coolwarm')