miniff package

Submodules

miniff.ewald module

miniff.ewald.ewald_cutoffs(eta, volume, charge, scale=1, eps=1e-07)

Compute the required Ewald cutoffs for the given tolerance.

Parameters

• eta (float) – Gaussian charge screening parameter.

• volume (float) – Unit cell volume.

• charge (float) – Sum of individual charges squared.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

• eps (float) – The required tolerance.

Returns

• r_cut (float) – Cutoff value in real space.

• k_cut (float) – Cutoff value in reciprocal space.

miniff.ewald.ewald_k_cutoff_error(k_cut, eta, volume, charge, scale=1)

An error associated with the k-space cutoff of Ewald summations. Eq. 5 in doi:10.1016/j.cplett.2005.05.106

Parameters

• k_cut (float) – k-space cutoff.

• eta (float) – Gaussian charge screening parameter.

• volume (float) – Unit cell volume.

• charge (float) – Sum of individual charges squared.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

Returns

result – The error estimate.

Return type

float

miniff.ewald.ewald_real_cutoff_error(r_cut, eta, volume, charge, scale=1)

An error associated with the real cutoff of Ewald summations. Eq. 4 in doi:10.1016/j.cplett.2005.05.106

Parameters

• r_cut (float) – Real-space cutoff.

• eta (float) – Gaussian charge screening parameter.

• volume (float) – Unit cell volume.

• charge (float) – Sum of individual charges squared.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

Returns

result – The error estimate.

Return type

float

miniff.ewald.stat_cell(cells, squeeze=True)

Computes statistics for cell(s): volumes and charges.

Parameters

• cells (list, tuple, Cell) – Cell(s) to compute cutoffs for.

• squeeze (bool) – If True, squeezes the output for a single cell.

Returns

• volume (np.ndarray, float) – Volume(s).

• charge (np.ndarray, float) – Sum(s) of charges squared.

miniff.kernel module

class miniff.kernel.Cell(vectors: numpy.ndarray, coordinates: numpy.ndarray, values: numpy.ndarray, meta: dict = <factory>, _vectors_inv: Optional[dataclasses.InitVar] = None)

Bases: object

Describes a unit cell.

cartesian

coordinates: numpy.ndarray

copy(vectors=None, coordinates=None, cartesian=None, values=None, meta=None, proto=None)

Creates a copy with optional modifications.

distances(cutoff=None, other=None)

Computes inter-point distances.

Parameters

• cutoff (float) – Cutoff for obtaining distances.

• other (Cell, np.ndarray) – Other cell to compute distances to

Returns

result – The resulting distance matrix.

Return type

np.ndarray, csr_matrix

classmethod from_cartesian(vectors, cartesian, values, *args, proto=None, _vectors_inv=None, **kwargs)

Constructs an instance from cartesian coordinates.

classmethod from_state_dict(data)

classmethod load(f)

Load Cell(s) from stream.

Parameters

f (file) – File-like object.

Returns

result – The resulting Cell(s).

Return type

list, Cell

meta: dict

normalized()

Puts all points inside box boundaries and returns a copy.

classmethod random(density, atoms, shape=None)

Prepares a unit cell with random atomic positions.

Parameters

• density (float) – Atomic density.

• atoms (dict) – A dictionary with specimen-count pairs.

• shape ({"box"}) – The shape of the resulting cell.

Returns

result – The resulting unit cell.

Return type

UnitCell

repeated(*args)

Prepares a supercell.

Parameters

*args – Repeat counts along each vector.

Returns

supercell – The resulting supercell.

Return type

Cell

static save(cells, f)

Saves cells.

Parameters

• cells (list, Cell) – Cells to save.

• f (file) – File-like object.

size

state_dict()

values: numpy.ndarray

values_encoded

values_lookup

values_uq

vectors: numpy.ndarray

vectors_inv

volume

class miniff.kernel.CellImages(cell: miniff.kernel.Cell, cartesian: numpy.ndarray, shift: numpy.ndarray, distances: scipy.sparse.csr.csr_matrix, cutoff: float, reciprocal_grid: numpy.ndarray = None)

Bases: object

adf(theta, sigma, cutoff, fmt='{}-[{},{}]')

Computes the angular distribution function.

Parameters

• theta (np.ndarray, float) – Radius values.

• sigma (float) – Smearing.

• cutoff (float) – Radial cutoff value.

• fmt (str) – A format string for keys.

Returns

result – Radial distribution function values.

Return type

dict

cartesian: numpy.ndarray

cell: miniff.kernel.Cell

cutoff: float

distances: scipy.sparse.csr.csr_matrix

eval(potentials, kname, squeeze=True, ignore_missing_species=False, out=None, **kwargs)

Computes potentials: values, gradients and more.

Parameters

• images (CellImages) – Cell and its images.

• potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• squeeze (bool) – If True, returns a single array whenever a single potential is passed.

• ignore_missing_species (bool) – If True, no error is raised whenever a specimen in the potential description is not found in the cell.

• out (np.ndarray) – The output buffer [n_potentials, n_atoms] for kname == “kernel” and [n_potentials, n_atoms, n_atoms, 3] for kname == “kernel_gradient”. Any kind of reduction including resolved=False and calls self.total, self.grad calls will use the buffer for intermediate results but will still allocate a new array for the output.

• kwargs – Other arguments to eval_potentials.

Returns

result – The result of the potential computation given the cell data.

Return type

np.ndarray

grad(potentials, kname='kernel_gradient', **kwargs)

Total energy gradients with respect to cartesian atomic coordinates.

Similarly to self.total, this function totally ignores any symmetry issues related to double-counting, etc.

Parameters

• images (CellImages) – Cell and its images.

• potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• kwargs – Other arguments to total.

Returns

gradients – Total energy gradients.

Return type

np.ndarray

grad_cell(potentials, kname='kernel_cell_gradient', **kwargs)

Total energy gradients with respect to cell vectors assuming cartesian atomic coordinates are fixed.

Parameters

• images (CellImages) – Cell and its images.

• potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• kwargs – Other arguments to total.

Returns

gradients – Total energy gradients.

Return type

np.ndarray

n_images

pair_reduction_function(f, fmt='{}-{}')

Pair reduction function.

Parameters

• f (Callable) – A function reducing pair-specific distances, see self.rdf for an example.

• fmt (str) – A format string for keys.

Returns

result – Pair function values.

Return type

dict

rdf(r, sigma, fmt='{}-{}')

Computes the radial distribution function.

Parameters

• r (np.ndarray, float) – Radius values.

• sigma (float) – Smearing.

• fmt (str) – A format string for keys.

Returns

result – Radial distribution function values.

Return type

dict

reciprocal_grid: numpy.ndarray = None

shift: numpy.ndarray

size

total(potentials, kname='kernel', squeeze=False, resolving=False, **kwargs)

Total energy as a sum of all possible potential terms.

Note that this function totally ignores any symmetry issues related to double-counting, etc.

Parameters

• images (CellImages) – Cell and its images.

• potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• squeeze (bool) – If True, returns a single array whenever a single potential is passed.

• resolving (bool) – If True, runs species-resolving kernels.

• kwargs – Other arguments to eval.

Returns

energy – The total energy value.

Return type

float

class miniff.kernel.ScalarFunctionWrapper(sample, potentials, include_coordinates=True, include_vectors=False, normalize=None, prefer_parallel=None, cell_logger=None, track_potential_fidelity=False, **kwargs)

Bases: object

eval(coordinates, vectors)

Computes function and gradients.

Parameters

• coordinates (np.ndarray) – Cell (crystal) coordinates.

• vectors (np.ndarray) – Cell vectors.

Returns

• cell (Cell) – The resulting cell with energy and gradients set.

• f (float) – The energy value.

• gc (np.ndarray) – Cartesian gradients.

• gv (np.ndarray) – Vector gradients.

eval_(coordinates, vectors)

Computes function and gradients. (Skips saving into history.)

Parameters

• coordinates (np.ndarray) – Cell (crystal) coordinates.

• vectors (np.ndarray) – Cell vectors.

Returns

• cell (Cell) – The resulting cell with energy and gradients set.

• f (float) – The energy value.

• gc (np.ndarray) – Cartesian gradients.

• gv (np.ndarray) – Vector gradients.

eval_to_cell(coordinates: numpy.ndarray, vectors: numpy.ndarray) → miniff.kernel.Cell

f(coordinates: numpy.ndarray, vectors: numpy.ndarray) → float

gc(coordinates: numpy.ndarray, vectors: numpy.ndarray) → numpy.ndarray

gv(coordinates: numpy.ndarray, vectors: numpy.ndarray) → numpy.ndarray

make_cell(coordinates, vectors)

start_recording()

Starts recording of coordinates passed.

stop_recording() → miniff.kernel.SnapshotHistory

Stops the recording of coordinates and returns all cells recorded.

class miniff.kernel.SnapshotHistory(iterable=(), /)

Bases: list

miniff.kernel.batch_rdf(cells, *args, inner=<function CellImages.rdf>, **kwargs)

Averaged radial distribution function.

Parameters

• cells (list, tuple) – A collection of wrapped cells to process.

• inner (Callable) – The function computing distribution for a single cell.

• args –

• kwargs – Arguments to inner.

Returns

result – Radial distribution function values.

Return type

dict

miniff.kernel.common_cutoff(potentials)

The maximal (common) cutoff of many potentials.

Parameters

potentials (Iterable) – Potentials to compute the cutoff for.

Returns

result – The resulting cutoff.

Return type

float

miniff.kernel.compute_images(cell, cutoff, reciprocal_cutoff=None, pbc=True)

Compute cell images given image shift vectors and cutoff distance.

Parameters

• cell (Cell) – Cell to process.

• cutoff (float) – The distance cutoff value.

• reciprocal_cutoff (float) – Optional reciprocal cutoff for the reciprocal grid.

• pbc (bool) – If True, assumes periodic boundary conditions.

Returns

images – Images with neighbor and distance information.

Return type

CellImages

miniff.kernel.compute_reciprocal_grid(cell, cutoff)

Computes the reciprocal grid.

Parameters

• cell (Cell) – Cell to process.

• cutoff (float) – The value of the reciprocal cutoff.

Returns

grid – A 2D array with reciprocal grid points.

Return type

np.ndarray

miniff.kernel.compute_shift_vectors(cell, cutoff=None, pbc=True)

Computes shift vectors given a cell and its environment.

Parameters

• cell (Cell) – Cell to process.

• cutoff (float) – Maximal distance computed (smaller=faster). Ignored if x is specified.

• pbc (bool) – If True, assumes periodic boundary conditions. Otherwise returns a single zero shift vector.

Returns

shift_vectors – A 2D array with shift vectors.

Return type

np.ndarray

miniff.kernel.encode_potentials(potentials, lookup, default=None)

Encodes potentials to have species as integers.

Parameters

• potentials (list, tuple) – Potentials to encode.

• lookup (dict) – A lookup dictionary.

• default (int) – The default value to replace non-existing entries. If None, raises KeyError.

Returns

result – The resulting list of potentials.

Return type

list

miniff.kernel.encode_species(species, lookup, default=None)

Transforms species into an array of integers encoding species.

Parameters

• species (list, tuple, np.ndarray) – Species to encode.

• lookup (dict) – A lookup dictionary.

• default (int) – The default value to replace non-existing entries. If None, raises KeyError.

Returns

result – The resulting integer array.

Return type

np.ndarray

miniff.kernel.eval(images, potentials, kname, squeeze=True, ignore_missing_species=False, out=None, **kwargs)

Computes potentials: values, gradients and more.

Parameters

• images (CellImages) – Cell and its images.

• potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• squeeze (bool) – If True, returns a single array whenever a single potential is passed.

• ignore_missing_species (bool) – If True, no error is raised whenever a specimen in the potential description is not found in the cell.

• out (np.ndarray) – The output buffer [n_potentials, n_atoms] for kname == “kernel” and [n_potentials, n_atoms, n_atoms, 3] for kname == “kernel_gradient”. Any kind of reduction including resolved=False and calls self.total, self.grad calls will use the buffer for intermediate results but will still allocate a new array for the output.

• kwargs – Other arguments to eval_potentials.

Returns

result – The result of the potential computation given the cell data.

Return type

np.ndarray

miniff.kernel.grad(images, potentials, kname='kernel_gradient', **kwargs)

Total energy gradients with respect to cartesian atomic coordinates.

Similarly to self.total, this function totally ignores any symmetry issues related to double-counting, etc.

Parameters

• images (CellImages) – Cell and its images.

• potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• kwargs – Other arguments to total.

Returns

gradients – Total energy gradients.

Return type

np.ndarray

miniff.kernel.grad_cell(images, potentials, kname='kernel_cell_gradient', **kwargs)

Total energy gradients with respect to cell vectors assuming cartesian atomic coordinates are fixed.

Parameters

• images (CellImages) – Cell and its images.

• potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• kwargs – Other arguments to total.

Returns

gradients – Total energy gradients.

Return type

np.ndarray

miniff.kernel.profile(potentials, f, *args, **kwargs)

Profiles a collection of potentials.

Parameters

• potentials (list) – Potentials to profile.

• f (Callable) – A function f(x1, …) -> UnitCell preparing a unit cell for the given set of parameters.

• args – Sampling of x1, … arguments of the function f.

• kwargs – Arguments to compute_images.

Returns

energy – Energies on the multidimensional grid defined by args.

Return type

np.ndarray

miniff.kernel.profile_directed_strain(potentials, cell, strain, direction, **kwargs)

Profiles a collection of potentials by applying strain.

Parameters

• potentials (list) – Potentials to profile.

• cell (UnitCell) – The original cell.

• strain (Iterable) – The relative strain.

• direction (list, tuple, np.ndarray) – The strain direction.

• kwargs – Arguments to compute_images.

Returns

energy – Energies of strained cells.

Return type

np.ndarray

miniff.kernel.profile_strain(potentials, cell, *args, **kwargs)

Profiles a collection of potentials by applying strain.

Parameters

• potentials (list) – Potentials to profile.

• cell (UnitCell) – The original cell.

• args – Relative strains along all vectors.

• kwargs – Arguments to compute_images.

Returns

energy – Energies of strained cells.

Return type

np.ndarray

miniff.kernel.total(images, potentials, kname='kernel', squeeze=False, resolving=False, **kwargs)

Total energy as a sum of all possible potential terms.

Note that this function totally ignores any symmetry issues related to double-counting, etc.

Parameters

• images (CellImages) – Cell and its images.

• potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• squeeze (bool) – If True, returns a single array whenever a single potential is passed.

• resolving (bool) – If True, runs species-resolving kernels.

• kwargs – Other arguments to eval.

Returns

energy – The total energy value.

Return type

float

miniff.ml module

class miniff.ml.Dataset(per_cell_dataset, *per_point_datasets)

Bases: Generic[torch.utils.data.dataset.T_co]

static assert_compatible(items)

Checks whether input datasets are compatible to be merged into one.

Parameters

items (list, tuple) – Items to merge.

Returns

• n_samples (int)

• n_atoms (int)

• n_species (tuple)

• n_features (tuple)

• n_coords (int)

• dtype (torch.dtype) – Resulting dataset dimensions and dtype.

static cat(items)

Merges multiple datasets into a single one.

Parameters

items (list, tuple) – Items to merge.

Returns

result – The resulting contiguous dataset.

Return type

Dataset

property dtype

static from_tensors(tensors, like=None)

Constructs a dataset from nested tensor structure.

Parameters

• tensors (list, tuple) – Tensors (energy, features, etc).

• like (Dataset) – If set, copies tags from the dataset provided.

Returns

dataset – The resulting dataset.

Return type

Dataset

property per_cell_dataset: miniff.ml.PerCellDataset

property per_point_datasets: Tuple[miniff.ml.PerPointDataset, ...]

class miniff.ml.MergedDataset(*datasets)

Bases: Generic[torch.utils.data.dataset.T_co]

to(dtype)

Converts this dataset to the provided type.

Parameters

dtype – The data type to convert to.

Returns

result – The dataset of the given type.

Return type

MergedDataset

class miniff.ml.NNPotentialFamily(parameters, cutoff, kernels, parameter_defaults=None, tag=None, proto=None, pre_compute_r=None, additional_inputs=None, complement_accumulating=True, complement_num_grad=True, doc=None)

Bases: miniff.potentials.NestedLocalPotentialFamily

get_state_dict(potential)

Retrieves a state dict.

Parameters

potential (NNPotential) – A potential to represent.

Returns

result – Potential parameters and other information.

Return type

dict

instance_from_state_dict(data)

Restores a potential from its dict representation. This routine attempt to guess the context of the serialized data: only potentials created using ml_util.behler_nn and default arguments can be properly restored.

Parameters

data (dict) – A dict with the data.

Returns

result – The restored potential.

Return type

NNPotential

class miniff.ml.NoneTolerantTensorDataset(*tensors)

Bases: Generic[torch.utils.data.dataset.T_co]

class miniff.ml.Normalization(energy_scale, features_scale, energy_offsets, features_offsets, length_scale=None, charges_scale=None, charges_offsets=None)

Bases: object

apply_to_module(module, specimen, fw=True, output='energy', simplify=True)

Wraps a module into normalization layers (input and output).

Parameters

• module (torch.nn.Module) – The potential turning normalized descriptors into normalized energies.

• specimen (int) – The specimen handle.

• fw (bool) – If True, performs a “forward” operation: assuming the module accepts plain features and outputs plain energies, returns another module accepting normalized features and returning normalized energies. Otherwise performs the inverse.

• output ({'energy', 'charge'}) – The output to scale: energy or charge.

• simplify (bool) – Attempt to simplify the resulting module.

Returns

result – The resulting module with normalization layers added.

Return type

torch.nn.Sequential

static atom_counts(dataset)

Calculates atoms per each unit cell and assembles counts into a single tensor.

Parameters

dataset (Dataset) – The dataset to process.

Returns

result – A 2D tensor [n_samples, len(per_point_datasets)] with counts.

Return type

torch.Tensor

bw(dataset, inplace=False)

Rescales dataset back to original values.

Parameters

• dataset (Dataset) – The dataset to rescale.

• inplace (bool) – If True, performs the operation in-place and returns the same dataset.

Returns

result – The original dataset.

Return type

Dataset

bw_charges(charges, specimen)

Rescales charges back to their original values.

Parameters

• charges (torch.Tensor) – Charges to rescale.

• specimen (int) – The index of the dataset charges belong to.

bw_energy(energy, atom_counts)

Rescales the energy back to its original values.

Parameters

• energy (torch.Tensor) – Energy to rescale.

• atom_counts (torch.Tensor) – A 2D matrix with atom counts per cell.

bw_energy_components(energy, specimen)

Rescales energy per-atom components back to their original values.

Parameters

• energy (torch.Tensor) – Energy to rescale.

• specimen (int) – The index of the dataset energies belong to (specimen index).

bw_energy_g(energy_g)

Rescales the energy gradients back to their original values.

Parameters

energy_g (torch.Tensor) – Energy gradients to rescale.

bw_features(features, specimen)

Rescales features back to their original values.

Parameters

• features (torch.Tensor) – Features to rescale.

• specimen (int) – The index of the dataset gradients belong to.

bw_features_g(features_g, specimen)

Rescales features’ gradients back to their original values.

Parameters

• features_g (torch.Tensor) – Features’ gradients to rescale.

• specimen (int) – The index of the dataset gradients belong to.

classmethod from_dataset(dataset, ignore_normalization_errors=False, pad=True, offset_energy=False, offset_features='mean', offset_charges=False, scale_energy=1, scale_features=2, scale_charges=1, scale_energy_gradients=1, pca_features=False)

Prepares normalization based on the dataset provided.

Parameters

• dataset (Dataset) – The dataset to pick normalization for.

• ignore_normalization_errors (bool) – Forces to ignore dataset parts which cannot be normalized.

• pad (bool) – Stabilize least-squares problem when determining per-specimen energy offsets.

• offset_energy (bool) –

• offset_features ({False, True, "mean"}) –

• offset_charges (bool) – If True, offsets energies, descriptors, and/or charges.

• scale_energy (float) –

• scale_features (float) –

• scale_charges (float) –

• scale_energy_gradients (float) – If set scales energies, descriptors, and/or charges to the value specified.

• pca_features (float, int, bool, Callable) – If set, performs principal component analysis (e.g. SVD) and prepares a truncated linear transformation of descriptors as a part of normalization. Float value has the meaning of a relative cutoff of singular values with respect to the maximal singular value. Integer value corresponds to the number of highest singular values to chose. Callable is expected to take the output of torch.svd and to return the bool mask of singular entries chosen.

Returns

normalization – The resulting normalization.

Return type

Normalization

fw(dataset, inplace=False)

Rescales dataset to ranges suitable for machine learning.

Parameters

• dataset (Dataset) – The dataset to rescale.

• inplace (bool) – If True, performs the operation in-place and returns the same dataset.

Returns

result – The resulting scaled dataset.

Return type

Dataset

fw_charges(charges, specimen)

Rescales charges.

Parameters

• charges (torch.Tensor) – Charges to rescale.

• specimen (int) – The index of the dataset charges belong to.

fw_energy(energy, atom_counts)

Rescales the energy.

Parameters

• energy (torch.Tensor) – Energy to rescale.

• atom_counts (torch.Tensor) – A 2D matrix with atom counts per cell.

fw_energy_components(energy, specimen)

Rescales energy per-atom components.

Parameters

• energy (torch.Tensor) – Energy to rescale.

• specimen (int) – The index of the dataset energies belong to (specimen index).

fw_energy_g(energy_g)

Rescales the energy gradients.

Parameters

energy_g (torch.Tensor) – Energy gradients to rescale.

fw_features(features, specimen)

Rescales features.

Parameters

• features (torch.Tensor) – Features to rescale.

• specimen (int) – The index of the dataset gradients belong to (specimen index).

fw_features_g(features_g, specimen)

Rescales features’ gradients.

Parameters

• features_g (torch.Tensor) – Features’ gradients to rescale.

• specimen (int) – The index of the dataset gradients belong to.

is_gradient_available() → bool

Determines whether gradient normalization data is present.

load_state_dict(d)

Loads state dictionary.

Parameters

d (dict) – Dictionary to load.

static lsq_energy_offsets(dataset, pad=True)

Solves a least-squares problem for the best representation of cell energies as a sum of per-atom components.

Parameters

• dataset (Dataset) – The dataset to process.

• pad (bool) – If True, stabilizes energy padding by minimizing padding values together with the residuals.

Returns

• energy_offsets (torch.Tensor) – A 1D tensor with per-specimen energy offsets.

• residuals (torch.Tensor) – A 2D tensor [n_samples, 1] with energy residuals after offsets have been subtracted.

state_dict()

Returns a dict of parameters describing this normalization. No copies are made.

Returns

params – A dict of parameters.

Return type

dict

to(dtype)

Converts this normalization to the provided type.

Parameters

dtype – The data type to convert to.

Returns

result – The normalization of the given type.

Return type

Normalization

class miniff.ml.PerCellDataset(energy, mask=None, energy_g=None, reference=None)

Bases: Generic[torch.utils.data.dataset.T_co]

static assert_compatible(items)

Checks whether input datasets are compatible to be merged into one.

Parameters

items (list, tuple) – Items to merge.

Returns

• n_samples (int)

• n_atoms (int)

• n_coords (int)

• dtype (torch.dtype) – Resulting dataset dimensions and dtype.

static cat(items)

Merges multiple datasets into a single one.

Parameters

items (list, tuple) – Items to merge.

Returns

result – The resulting contiguous dataset.

Return type

PerCellDataset

property energy: torch.Tensor

property energy_g: torch.Tensor

static from_cells(cells, values, grad=False, **kwargs)

Prepares a per-cell dataset with total energies and energy gradients.

Parameters

• cells (Iterable) – Cells to process.

• values (torch.Tensor) – A matrix [n_samples, n_atoms] with encoded species.

• grad (bool) – Include gradients.

• kwargs – Arguments to empty tensor construction.

Returns

result – The resulting dataset.

Return type

PerCellDataset

is_gradient_available() → bool

Determines whether energy gradients data is present.

property mask: torch.Tensor

property reference: torch.Tensor

to(dtype)

Converts this dataset to the provided type.

Parameters

dtype – The data type to convert to.

Returns

result – The dataset of the given type.

Return type

PerCellDataset

class miniff.ml.PerPointDataset(features, mask, features_g=None, charges=None, energies_p=None, tag=None)

Bases: Generic[torch.utils.data.dataset.T_co]

static assert_compatible(items)

Checks whether input datasets are compatible to be merged into one.

Parameters

items (list, tuple) – Items to merge.

Returns

• n_samples (int)

• n_atoms (int)

• n_species (int)

• n_features (int)

• n_coords (int)

• dtype (torch.dtype) – Resulting dataset dimensions and dtype.

static cat(items, tag=None)

Merges multiple datasets into a single one.

Parameters

• items (list, tuple) – Items to merge.

• tag – An optional tag for this dataset.

Returns

result – The resulting contiguous dataset.

Return type

PerPointDataset

property charges: torch.Tensor

property energies_p: torch.Tensor

property features: torch.Tensor

property features_g: torch.Tensor

static from_cells(cells, descriptors, specimen, values, grad=False, charge=False, energies_p=False, tag=None, dtype=torch.float64, **kwargs)

Prepares a per-point dataset with features, feature gradients, energy gradients and partial energies.

Parameters

• cells (Iterable) – ``CellImage``s to process.

• descriptors (list) – A plain list of tagged descriptors.

• specimen – The specimen this dataset is calculated for.

• values (torch.Tensor) – A matrix [n_samples, n_atoms] with encoded species.

• grad (bool) – Include gradients.

• charge (bool) – Include atomic charges.

• energies_p (bool) – Include partial energies.

• tag – Optional tag for the dataset.

• dtype – Tensor data type.

• kwargs – Additional arguments to prepare_descriptor_data.

Returns

result – The resulting dataset.

Return type

PerPointDataset

get_features_hist(bins=100, margin=0)

Computes the histogram of features.

Parameters

• bins (int) – Bin count.

• margin (float) – Margins for binning range.

Returns

result – The resulting histogram as a [n_features, 2, bins + 1] tensor where result[:, 0] are bin edges and result[:, 1] are feature occurrence counts.

Return type

torch.Tensor

is_gradient_available() → bool

Determines whether features gradients data is present.

property mask: torch.Tensor

to(dtype)

Converts this dataset to the provided type.

Parameters

dtype – The data type to convert to.

Returns

result – The dataset of the given type.

Return type

PerPointDataset

exception miniff.ml.PotentialExtrapolationWarning

Bases: miniff.potentials.PotentialRuntimeWarning

miniff.ml.collect_atoms(cells)

Collects all atoms from all cells into a masked array.

Parameters

cells (tuple) – Cells to process.

Returns

values – An [n_samples, n_atoms] matrix with atoms.

Return type

np.ma.masked_array

miniff.ml.collect_charges(cells, out, mask=None)

Collects cell charges into a tensor.

Parameters

• cells (Iterable) – ``CellImage``s to process.

• out (torch.Tensor) – The output tensor.

• mask (np.ndarray) – An optional mask array for a particular specimen.

Returns

out – A [n_samples, n_atoms] tensor with charges per atom per cell.

Return type

torch.Tensor

miniff.ml.collect_energies(cells, out, mask=None)

Collects cell energies into a tensor.

Parameters

• cells (Iterable) – ``CellImage``s to process.

• out (torch.Tensor) – The output tensor.

• mask (np.ndarray) – An optional mask array for a particular specimen.

Returns

out – A [n_samples, 1] tensor with energies per each cell.

Return type

torch.Tensor

miniff.ml.collect_forces(cells, out, mask=None)

Collects cell forces into a tensor.

Parameters

• cells (Iterable) – ``CellImage``s to process.

• out (torch.Tensor) – The output tensor.

• mask (np.ndarray) – An optional mask array for a particular specimen.

Returns

out – A [n_samples, n_atoms, n_coords] tensor with forces per atom per cell.

Return type

torch.Tensor

miniff.ml.collect_meta(field, cells, out, mask=None)

Collects cell metadata into a tensor.

Parameters

• field (str) – The field to collect.

• cells (Iterable) – ``CellImage``s to process.

• out (torch.Tensor) – The output tensor.

• mask (np.ndarray) – An optional mask array for a particular specimen.

Returns

out – A [n_samples, *] tensor with floats per each cell.

Return type

torch.Tensor

miniff.ml.collect_partial_energies(cells, out, mask=None)

Collects partial energies into a tensor.

Parameters

• out (torch.Tensor) – The output tensor.

• mask (np.ndarray) – An optional mask array for a particular specimen.

Returns

out – A [n_samples, n_atoms] tensor with energies per atom per cell.

Return type

torch.Tensor

miniff.ml.cpu_copy(model)

Creates a CPU copy of the model.

Parameters

model (torch.nn.Module) – The module to copy.

Returns

model_copy – The COU copy.

Return type

torch.nn.Module

miniff.ml.descriptor_fidelity_middleware(descriptor_values, descriptor_fidelity_histograms)

Evaluates descriptor fidelity based on how much descriptors are presented in the histogram data.

Parameters

• descriptor_values (np.ndarray) – Descriptor values.

• descriptor_fidelity_histograms (np.ndarray) – A 3-tensor with histograms (bins and values) representing the occurrence of descriptor values in the training data.

Returns

result – The resulting fidelity, one per atom.

Return type

np.ndarray

miniff.ml.encode_species(cells)

Encodes species into integers.

Parameters

cells (tuple, list, np.ndarray) – A collection of cells to process .

Returns

• values_torch (torch.tensor) – An [n_samples, n_atoms] torch matrix with integers encoding species.

• key (np.ndarray) – A 1D array with the key to values_torch.

miniff.ml.energy_gradients(net_output, features_g, resolve=False)

Computes total energy gradients.

Parameters

• net_output (torch.Tensor, np.ndarray) – Output from the energy learning network: a 3D tensor of shape [n_samples, n_species, n_descriptors] with per-cell per-point energy gradients wrt descriptors.

• features_g (torch.Tensor, np.ndarray) – A 5D tensor of shape [n_samples, n_species, n_descriptors, n_atoms, n_coords] with per-cell per-point descriptor gradients.

• resolve (bool) – If True, returns energies per specimen.

Returns

result – A tensor of shape [n_samples, n_atoms, n_coords] if per_sample == False or a 4D tensor [n_samples, n_points, n_atoms, n_coords] if per_sample == True.

Return type

torch.Tensor

miniff.ml.eval_descriptors(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, species_row, species_mask, kernel='kernel')

Computes descriptors or their gradients.

Parameters

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A list of descriptors.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• kernel (str) – The desired descriptor kernel.

Returns

• descriptor_values (np.ndarray) – A dense array with descriptors for matching atoms only.

• descriptor_gradient_values (np.ndarray, optional) – Descriptor gradient values.

miniff.ml.forward(module, x, grad=False)

Computes energies and gradients.

Parameters

• module (torch.nn.Module) – Module to propagate.

• x (torch.Tensor) – Features input.

• grad (bool) – If True, outputs gradients as well.

Returns

• energies (torch.Tensor)

• gradients (torch.Tensor)

miniff.ml.fw_cauldron(modules, dataset, grad=False, energies_p=False, normalization=None)

Propagates modules forward and assembles the total energy and gradients. This function will take care of all masking and padding.

Parameters

• modules (list, tuple) – A list of modules mapping descriptors onto local energies.

• dataset (Dataset, list, tuple) – The dataset with descriptors or tensors to assemble the dataset from.

• grad (bool) – If True, computes gradients wrt descriptors.

• energies_p (bool) – If True, presents total energy as a sum of per-atom contributions.

• normalization (Normalization) – Optional normalization to apply (backward).

Returns

• energy (Tensor, list) – A [n_samples, 1] tensor with total energies or a list of [n_samples, n_species, 1] tensors with per-atom contributions.

• gradients (Tensor, optional) – A [n_samples, n_atoms, 3] tensor with total energy gradients.

miniff.ml.fw_cauldron_charges(modules, dataset, normalization=None)

Propagates modules forward and assembles atomic charges.

Parameters

• modules (list, tuple) – A list of modules mapping descriptors onto atomic charges.

• dataset (Dataset, list, tuple) – The dataset with descriptors or tensors to assemble the dataset from.

• normalization (Normalization) – Optional normalization to apply (backward).

Returns

charges – A list of [n_samples, n_species] tensors with atomic charges.

Return type

list

miniff.ml.inplace_options(f)

Decorates functions accepting inplace options only towards making a copy.

Parameters

f (Callable) – A function to decorate.

Returns

result – The decorated function.

Return type

Callable

miniff.ml.kernel_g_nn(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, nn, descriptor_fidelity_histograms, species_row, species_mask, out)

Neural network potential kernel.

Parameters

• kind ({'fun', 'grad', 'grad-cell', 'fidelity'}) – Indicates to return per-point energies, or energy gradients, or fidelity.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A list of descriptors.

• nn (torch.Module) – The network mapping descriptors onto individual energies.

• descriptor_fidelity_histograms (list) – A list of histograms (bins and values) representing the occurrence of descriptor values in the training data.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.ml.kernel_h_nn(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, nn, descriptor_fidelity_histograms, species_row, species_mask, out)

Neural network potential kernel.

Parameters

• kind ({'fun', 'grad', 'grad-cell', 'fidelity'}) – Indicates to return per-point energies, or energy gradients, or fidelity.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A list of descriptors.

• nn (torch.Module) – The network mapping descriptors onto individual energies.

• descriptor_fidelity_histograms (list) – A list of histograms (bins and values) representing the occurrence of descriptor values in the training data.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.ml.kernel_nn(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, nn, descriptor_fidelity_histograms, species_row, species_mask, out)

Neural network potential kernel.

Parameters

• kind ({'fun', 'grad', 'grad-cell', 'fidelity'}) – Indicates to return per-point energies, or energy gradients, or fidelity.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A list of descriptors.

• nn (torch.Module) – The network mapping descriptors onto individual energies.

• descriptor_fidelity_histograms (list) – A list of histograms (bins and values) representing the occurrence of descriptor values in the training data.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.ml.kernel_nn_fidelity(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, nn, descriptor_fidelity_histograms, species_row, species_mask, out)

Neural network potential kernel.

Parameters

• kind ({'fun', 'grad', 'grad-cell', 'fidelity'}) – Indicates to return per-point energies, or energy gradients, or fidelity.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A list of descriptors.

• nn (torch.Module) – The network mapping descriptors onto individual energies.

• descriptor_fidelity_histograms (list) – A list of histograms (bins and values) representing the occurrence of descriptor values in the training data.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.ml.kernel_u_nn(kind, r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, nn, descriptor_fidelity_histograms, species_row, species_mask, out)

Neural network potential kernel.

Parameters

• kind ({'fun', 'grad', 'grad-cell', 'fidelity'}) – Indicates to return per-point energies, or energy gradients, or fidelity.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A list of descriptors.

• nn (torch.Module) – The network mapping descriptors onto individual energies.

• descriptor_fidelity_histograms (list) – A list of histograms (bins and values) representing the occurrence of descriptor values in the training data.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.ml.learn_cauldron(cells, descriptors, grad=False, normalize=True, extract_forces=None, extract_charges=False, energies_p=False, norm_kwargs=None, prefer_parallel=None)

A function assembling data for learning.

Parameters

• cells (tuple) – Cells to process.

• descriptors (dict) – A dictionary with atoms (keys) and descriptors.

• grad (bool) – Include gradients.

• normalize (class) – If set, normalizes with the given class and returns the normalization together with the dataset. If True, uses the Normalization class. Set to False if no normalization needed.

• extract_forces (bool, None) – If True, extracts forces from unit cell data. Defaults to grad value.

• extract_charges (bool) – If True, extract atomic charges from unit cell data.

• energies_p (bool) – If True, extract partial energies.

• norm_kwargs (dict) – Arguments to normalization.

• prefer_parallel (bool) – If True, computes descriptors with OpenMP whenever possible.

Returns

• dataset (Dataset) – The dataset.

• normalization (Normalization, optional) – The normalization.

miniff.ml.linear(w, b=None)

Assembles a linear module from weight and bias.

Parameters

• w (torch.Tensor) – Weight.

• b (torch.Tensor, None) – Bias.

Returns

result – The resulting module.

Return type

torch.nn.Linear

miniff.ml.nn_forward_middleware(descriptor_values, nn, descriptor_gradient_values=None)

Propagates descriptors into energies or energy gradients. Wraps forward and energy_gradients.

Parameters

• descriptor_values (np.ndarray) – Descriptor values.

• nn (torch.Module) – The module to propagate through.

• descriptor_gradient_values (np.ndarray) – Descriptor gradient values.

Returns

result – Energies or gradients, depending on whether descriptor_gradient_values was specified.

Return type

np.ndarray

miniff.ml.potentials_from_ml_data(nn, descriptors, normalization=None, output='energy', descriptor_fidelity_histograms=None, simplify=True)

Constructs potentials from neural networks.

Parameters

• nn (list) – A list of neural networks modelling force fields per atom type.

• descriptors (dict) – A dict with descriptors.

• normalization (Normalization) – Normalization information.

• output (str) – The output of neural networks. Used only if normalization is specified.

• descriptor_fidelity_histograms (list) – A list of histogram data showing how much training data is available per descriptor values range.

• simplify (bool) – Attempt to simplify the resulting module.

Returns

potentials – Neural-network potentials.

Return type

list

miniff.ml.prepare_descriptor_data(cells, descriptors, specimen, values, grad=False, dtype=torch.float64, **kwargs)

Computes descriptors of a unit cell dataset.

This function prepares dense datasets suitable for operations during machine learning.

Parameters

• cells (Iterable) – ``CellImage``s to process.

• descriptors (Iterable) – Pairs of descriptor targets (e.g. ‘cu-cu’) and lists of descriptors.

• specimen – The specimen this dataset is calculated for.

• values (torch.Tensor) – A matrix [n_samples, n_atoms] with encoded species.

• grad (bool) – Include gradients.

• dtype (torch.dtype) – Data type of the output.

• kwargs – Additional arguments to kernel.eval`.

Returns

• descriptors (torch.Tensor) – A [n_samples, n_species, n_descriptors] tensor with descriptors.

• mask (torch.Tensor) – A [n_samples, n_species] mask array indicating meaningful entries.

• descriptor_gradients (torch.Tensor, optional) – A [n_samples, n_species, n_descriptors, n_atoms, 3] tensor with descriptor gradients if gradients requested.

miniff.ml.same(items)

‘Same’ reduction: asserts all items are equal to the return value.

miniff.ml.simplify_sequential(s)

Assembles torch.nn.Sequential.

Parameters

s (torch.nn.Sequential) – Sequential module to simplify.

Returns

result – The resulting module.

Return type

torch.nn.Sequential

miniff.ml.total_energy(net_output, mask, resolve=False)

Computes total energy value per unit cell.

Parameters

• net_output (torch.Tensor, np.ndarray) – Output from the energy learning network: a 3D tensor of shape [n_samples, n_atoms, 1] with per-cell per-point energies.

• mask (torch.Tensor, np.ndarray) – A 2D mask Tensor of shape [n_samples, n_atoms] distinguishing true vs padding entries.

• resolve (bool) – If True, returns energies per specimen.

Returns

result – A 2D tensor of shape [n_samples, 1] with total energies per unit cell.

Return type

torch.Tensor

miniff.ml_util module

class miniff.ml_util.ChargeFitWorkflow(**kwargs)

Bases: miniff.ml_util.FitWorkflow

apply_normalization(*names, nn=False, nn_output='charge')

Applies the normalization.

Parameters

• names – Dataset names to apply the normalization to.

• nn (bool) – If True, applies the normalization to neural networks.

• nn_output (str) – Neural network output to deduce the normalization component. Used only if nn=True.

build_potentials(nn_output='charge')

Initializes NN potentials.

Returns

• potentials (list) – A list of potentials.

• nn_output (str) – Neural network output to deduce the normalization component.

• stats (str) – The source of descriptor distributions.

compute_descriptors(**kwargs)

Computes descriptors.

Parameters

• parallel (bool, str) – If True, computes in multiple processes.

• chunksize (int, None) – The size of a single task in parallel mode. Defaults to 100.

• source (list, None) – Which cells to take.

• destination (str) – The destination for the dataset in self.datasets.

• pool_kwargs (dict) – Arguments to Pool constructor in parallel mode.

• kwargs – Arguments to ml.learn_cauldron.

Returns

result – The resulting dataset.

Return type

Dataset

compute_normalization(source='learn', **kwargs)

Computes the normalization.

Parameters

• source (str, Dataset) – The dataset to deduce the normalization from.

• kwargs – Arguments to Normalization.from_dataset.

Returns

norm – The normalization of the dataset.

Return type

Normalization

init_closure(**kwargs)

Initializes the closure.

Parameters

• closure (Callable) – The closure initialization function.

• primary (str) – The name of the primary learning dataset.

• kwargs – Arguments to simple_energy_closure.

Returns

result – The closure.

Return type

SimpleClosure

class miniff.ml_util.FitWorkflow(**kwargs)

Bases: miniff.ml_util.Workflow

apply_normalization(*names, nn=False, nn_output='energy')

Applies the normalization.

Parameters

• names – Dataset names to apply the normalization to.

• nn (bool) – If True, applies the normalization to neural networks.

• nn_output (str) – Neural network output to deduce the normalization component. Used only if nn=True.

build_potentials(nn_output='energy', stats='learn')

Initializes NN potentials.

Returns

• potentials (list) – A list of potentials.

• nn_output (str) – Neural network output to deduce the normalization component.

• stats (str) – The source of descriptor distributions.

check_conflicts(learn_cauldron_kwargs, closure_kwargs)

Checks inputs for possible conflicts.

Parameters

• learn_cauldron_kwargs (dict) – Arguments to learn_cauldron.

• closure_kwargs (dict) – Arguments to closures.

compute_cutoff()

Computes descriptor cutoff and returns it.

Returns

result – The cutoff value.

Return type

float

compute_descriptor_stats(dataset='learn', bins=100, margin=0)

Computes descriptor statistics.

Parameters

• dataset (str) – The dataset to process.

• bins (int) – Histogram bins count.

• margin (float) – Margins for bin edges.

Returns

distributions – A list of descriptor distributions.

Return type

list

compute_descriptors(parallel=False, chunksize=None, source=None, destination='learn', pool_kwargs=None, **kwargs)

Computes descriptors.

Parameters

• parallel (bool, str) – If True, computes in multiple processes.

• chunksize (int, None) – The size of a single task in parallel mode. Defaults to 100.

• source (list, None) – Which cells to take.

• destination (str) – The destination for the dataset in self.datasets.

• pool_kwargs (dict) – Arguments to Pool constructor in parallel mode.

• kwargs – Arguments to ml.learn_cauldron.

Returns

result – The resulting dataset.

Return type

Dataset

compute_normalization(source='learn', **kwargs)

Computes the normalization.

Parameters

• source (str, Dataset) – The dataset to deduce the normalization from.

• kwargs – Arguments to Normalization.from_dataset.

Returns

norm – The normalization of the dataset.

Return type

Normalization

cuda()

Moves data to CUDA.

epoch(cleanup=True, epoch_size=1)

Runs an optimizer epoch.

Parameters

• cleanup (bool) – if True, cleans up the optimizer memory before running the epoch.

• epoch_size (int) – Number of optimizer steps taken at once.

Returns

The resulting loss data.

Return type

loss

filter_descriptors(dataset='learn', min_spread=0.01)

Filters out non-representative descriptors.

Parameters

• dataset (str) – The dataset to analyze.

• min_spread (float) – The required minimal spread of descriptor values.

Returns

descriptors – Filtered descriptors.

Return type

dict

init_closure(closure=None, primary='learn', **kwargs)

Initializes the closure.

Parameters

• closure (Callable) – The closure initialization function.

• primary (str) – The name of the primary learning dataset.

• kwargs – Arguments to simple_energy_closure.

Returns

result – The closure.

Return type

SimpleClosure

init_default_descriptors(n=6, a=None, left=1, common_grid=True, three_point=True, three_point_family=4, **kwargs)

Provides a default set of descriptors.

Parameters

• n (int) – Descriptor radial sampling.

• a (float) – Descriptor cutoff. Defaults to 12 aBohr.

• left (float) – Left descriptor edge.

• common_grid (bool) – If True, all species share the same radial grid.

• three_point ({False, True, 'all'}) – If True, include three-point descriptors with the largest cutoff value and eta=0. If ‘all’, include three-point descriptors with all etas.

• three_point_family (int) – Determines which descriptor family to use for 3-point descriptors: type-4 or type-5 descriptors.

• kwargs – Arguments to default_behler_descriptors_3. Ignored if three_point is False.

Returns

descriptors – The resulting descriptor set.

Return type

dict

init_nn(init=None, **kwargs)

Initializes neural networks into a random state.

Parameters

• init (Callable) – A function that initializes a neural network, defaults to behler_nn.

• kwargs – Arguments to SequentialSoleEnergyNN.

Returns

result – A list of initialized networks (torch Modules).

Return type

list

init_plots(on_plot_update=None, inset=0.1, inset_size=0.4, inset_offset=0.03, **kwargs)

Initializes runtime plots.

Parameters

• on_plot_update (str, Callable, None) – Action to perform whenever plots are updated: - ‘save’: save into pdf files; - ‘show’: run pyplot.show; - ‘notebook’: create plots in the notebook nd update them; - Callable: any custom callable taking this workflow as an input.

• inset (float, list, tuple) – If non-zero, inset the most dense part of the diagonal plot. The number corresponds to the fraction of the original plot shown in the inset. If list specified, insets the specific range of the diagonal plot.

• inset_size (float) – The actual size of the inset plot.

• inset_offset (float) – Offset of the inset plot.

• kwargs – Arguments to self.update_plots.

load_descriptors(arg)

Load descriptors from a file or a dictionary.

Parameters

arg (str, Path, dict) – File with descriptors to parse or a dictionary with descriptors.

Returns

descriptors – The resulting descriptors.

Return type

dict

load_potentials(potentials)

Load previously saved result.

Parameters

potentials (str, list) – File name to load from or a list of potentials.

Returns

nn_potentials – Loaded potentials.

Return type

list

plot_distributions(which=None, **kwargs)

Plot distribution of energies, forces and other quantities available.

Parameters

• which – Specify which datasets to include in order.

• kwargs – Arguments to pyplot.hist.

Returns

The resulting figure.

Return type

figure

prepare(fn_cells, cells_order='random', cells_subset=None, cells_append=False, descriptors=None, filter_descriptors=False, filter_descriptors_kwargs=None, cutoff=None, nw_kwargs=None, fn_cells_root=None, parallel=False, parallel_descriptor_chunksize=None, learn_cauldron_kwargs=None, normalization_kwargs=None, test_set=0.1, nn_kwargs=None, cuda='auto', closure_kwargs=None, plot_kwargs=None, default_descriptor_kwargs=None, load=None)

Prepares the data for the workflow.

run(n_epochs=1000, epoch_size=1, cleanup_optimizer=True, save=False, save_policy=None, save_fn='{tag}.pt', after_epoch=None, update_kwargs=None, plot_kwargs=None)

Runs the training scenario.

Parameters

• n_epochs (int) – Number of epochs to run.

• epoch_size (int) – Size of the epoch.

• cleanup_optimizer (bool) – if True, cleans up the optimizer memory before running each epoch.

• save (str, bool, None) – If set, saves intermediate potentials data to the desired location.

• save_policy (Callable) – A function(tag, loss, state) -> do_save, state which is called to determine whether saving is needed.

• save_fn (str) – A formatting string to generate potential filenames based on the dataset name.

• after_epoch (Callable) – A callback function(self) -> bool to run after each epoch. If the returned value becomes False exits the epoch loop.

• update_kwargs (dict) – Keyword arguments to update_loss.

• plot_kwargs (dict) – Keyword arguments to plot functions.

save_plots()

save_potentials(filename)

Saves potentials as a file.

Parameters

filename (str) – Save location.

split_dataset(fraction=0.1, source='learn', destination='test')

Splits a dataset into two. Useful for preparing test sets.

Parameters

• source (str) – The dataset to split.

• destination (str) – The destination to write the split part to.

• fraction (float, int) – The fraction of the data that ends up in destination in case of float, or the corresponding number of entries in case of integer.

Returns

• new_source (Dataset) – The source dataset.

• destination (Dataset) – The destination dataset.

update_loss(report_top=3, print_id=None)

Propagates and computes loss function(s).

Parameters

• report_top (int) – The number of highest errors to report.

• print_id (Callable) – A function(loss_id, index) -> str turning a numeric id into a meaningful string.

Returns

loss – A dictionary with loss functions.

Return type

dict

update_plots(update=True, diag_kwargs=None, conv_kwargs=None)

Updates plots.

class miniff.ml_util.OneShotWorkflow(**kwargs)

Bases: miniff.ml_util.SDWorkflow

static worker(job, **kwargs)

class miniff.ml_util.SDWorkflow(**kwargs)

Bases: miniff.ml_util.Workflow

generate_random_cells(n, density, atoms, a, **kwargs)

Generates a set of randomized unit cells with the specified parameters.

Parameters

• n (int) – Number of cells to generate.

• density (float) – Target atomic density.

• atoms (dict) – Atom counts.

• a (float) – Target interatomic distance.

• kwargs – Other arguments to dyn.random_cell.

Returns

result – A list of resulting cells.

Return type

list

load_potentials(potentials)

Load previously saved potential.

Parameters

potentials (list) – File names to load from or an explicit list of potentials.

Returns

potentials – The loaded potentials.

Return type

list

prepare(fn_cells=None, fn_cells_root=None, random_cells=None, potentials='learn.pt', cells_order=None, cells_subset=None, nw_kwargs=None)

run(parallel=False, pool_kwargs=None, save=None, update_state=True, **kwargs)

Computes descriptors.

Parameters

• parallel (bool, str) – If True, computes in multiple processes.

• pool_kwargs (dict) – Arguments to Pool constructor in parallel mode.

• save (str) – Saves the resulting cells to a file.

• update_state (bool) – If True, keeps the final state of dynamics as a starting point for subsequent runs.

• kwargs – Arguments to self.worker.

Returns

result – The resulting structures.

Return type

list

save_result(destination, snapshots=False)

Save resulting cells into a file.

Parameters

• destination (str, file) – The file to save to.

• snapshots (bool) – If True, saves snapshots. Saves final structures otherwise.

setup_dynamics(name='fixed-cell', ek=None, **kwargs)

Sets up dynamics wrappers.

Parameters

• name (str) – The dynamics to setup.

• ek (float) – Setup initial (random) velocities to match the provided value. This option is required (but does not guarantee) reproducible parallel runs.

• kwargs – Arguments to ScalarFunctionWrapper.

Returns

wrappers – A list of wrappers.

Return type

list

update_cutoff()

Updates the cutoff value.

Returns

cutoff – The cutoff value.

Return type

float

static worker(cell, what='relax', prefer_parallel=None, **kwargs)

class miniff.ml_util.SimpleClosure(networks, loss_function, dataset=None, criterion=None, optimizer=None, optimizer_kwargs=None, loss_function_kwargs=None)

Bases: object

learning_parameters()

Learning parameters.

Returns

params – Parameters to learn.

Return type

Iterable

loss(dataset=None, save=True)

The loss function.

Parameters

• dataset (Dataset) – The dataset to compute loss function of.

• save (bool) – If True, stores the result in self.last_loss.

Returns

result – The resulting loss and accompanying information.

Return type

stats_tuple

optimizer_init(optimizer=None, **kwargs)

Initialize the optimizer.

Parameters

• optimizer – Optimizer class.

• kwargs – Arguments to the constructor.

Returns

The resulting optimizer object.

Return type

optimizer

optimizer_step()

Performs an optimization step.

propagate(dataset=None)

Propagates the closure.

Parameters

dataset (torch.utils.data.Dataset) – The dataset to compute loss function of.

Returns

result – The resulting loss.

Return type

torch.Tensor

class miniff.ml_util.Workflow(dtype=torch.float64, log=None, seed=None, mpl_backend=None, mpl_save_ext='png', units=None, units_are_known=False, tag=None)

Bases: object

compute_neighbors(parallel=False, pool_kwargs=None, **kwargs)

Computes neighbors (images) data.

Parameters

• parallel (bool) – If True, computes in parallel.

• pool_kwargs (dict) – Arguments to Pool.

• kwargs – Arguments to kernel.compute_images.

Returns

images – A list of computed CellImage objects.

Return type

list

property cutoff

load_cells(filenames, root=None, append=False)

Loads cells (structural data) from files.

Parameters

• filenames (str, list, tuple, Path) – File names or patterns to load.

• root (str, Path) – The root folder to load from.

• append (bool) – If True, appends the data to previously loaded cells.

Returns

result – The resulting cells.

Return type

np.ndarray

classmethod load_cells_individual(filename)

Load a single piece of the dataset.

Parameters

filename (str, Path) – The path to load.

Returns

result – A list of Cells.

Return type

list

reorder_cells(order)

Reorders cells.

Parameters

order (str) – Order of cells: ‘random’.

Returns

result – Ordered cells.

Return type

list

save_cells(destination, cells=None)

Save cells into a file.

Parameters

• destination (str, file) – The file to save to.

• cells (Iterable, None) – Cells to save. Defaults to self.cells.

subset_cells(subset)

Retrieves a subset of cells.

Parameters

subset (int) – The subset size. Currently only takes a subset beginning from the first cell.

Returns

result – Subset cells.

Return type

np.ndarray

miniff.ml_util.behler_nn(n_inputs, n_internal=15, n_layers=3, bias=True, activation=None)

Behler choice for neural network potential.

Parameters

• n_inputs (int) – Input count.

• n_internal (int) – Internal dimension size.

• n_layers (int) – Linear layer count.

• bias (bool, list) – If True, use bias in linear layers (optionally, defined per-layer).

• activation – Activation layer class (defaults to Sigmoid).

Returns

result – The resulting neural network.

Return type

torch.nn.Sequential

miniff.ml_util.charges_loss(networks, data, criterion)

Charges loss function.

Parameters

• networks (list) – A list of networks to learn.

• data (Dataset) – The dataset to compute loss function of.

• criterion (torch.nn.Module) – Loss criterion.

Returns

result – The resulting loss and accompanying information.

Return type

loss_result

miniff.ml_util.default_behler_descriptors(arg, n, a, left=1, common_eta=True)

Default Behler descriptor choice.

Parameters

• arg (dict, list, tuple) – A dict with minimal distance between atoms per specimen pair or wrapped cells to deduce these distances from.

• n (int) – Descriptor count.

• a (float) – The function cutoff.

• left (float) – Left boundary factor.

• common_eta (bool) – Pick common etas.

Returns

descriptors – A dict with descriptors.

Return type

dict

miniff.ml_util.default_behler_descriptors_3(arg, a, eta=0, zeta=(1, 2, 4, 16), family=4, cos_theta0=- 1, amount_5x='full')

Default Behler descriptor choice.

Parameters

• arg (list, tuple) – A list of species or images to take species from.

• a (float) – The function cutoff.

• eta (float, list, dict) – A dingle eta, a list of etas or a dictionary with etas per specimen pair.

• zeta (float, tuple, list) – A list of zetas.

• family ({4, 5, "5x", LocalPotentialFamily}) – Descriptor family to employ. Integers stand for type-4 or type-5 descriptor kinds.

• cos_theta0 (float, tuple, list) – A list of angles where the ‘5x’ descriptor vanishes. Ignored for other descriptors.

• amount_5x ({"full", "half", "diagonal", "diag"}) – Includes all, or a half of eta combinations, or just those where eta1=eta2.

Returns

descriptors – A dict with descriptors.

Return type

dict

class miniff.ml_util.diag_plot_props(scale, unit, title)

Bases: tuple

property scale

Alias for field number 0

property title

Alias for field number 2

property unit

Alias for field number 1

miniff.ml_util.energy_loss(networks, data, criterion, w_energy, w_gradients, energies_p=False)

Energy loss function.

Parameters

• networks (list) – A list of networks to learn.

• data (Dataset) – The dataset to compute loss function of.

• criterion (torch.nn.Module) – Loss criterion.

• w_energy (float) – Energy weight in the loss function.

• w_gradients (float) – Gradients weight in the loss function.

• energies_p (bool) – If True, compares partial energies.

Returns

result – The resulting loss and accompanying information.

Return type

loss_result

miniff.ml_util.exec_workflows(description, rtn=True, log=None)

Constructs and executes workflows with the description provided.

Parameters

• description (OrderedDict) – Workflow description.

• rtn (bool) – If True, returns all workflows executed. Otherwise, returns only the last workflow.

• log (Logger) – The common logger.

Returns

result – The resulting workflow(s).

Return type

list, Workflow

miniff.ml_util.fit(*, workflow_class=<class 'miniff.ml_util.FitWorkflow'>, init=None, prepare=None, run=None)

Runs the fit workflow and returns it.

Parameters

• init – Keyword arguments to workflow initialization.

• prepare – Keyword arguments to workflow data preparation and processing.

• run – Keyword arguments to workflow run phase.

Returns

result – The resulting workflow.

Return type

FitWorkflow

miniff.ml_util.load_potentials(f, deserializer=<function torch_load>)

Loads a list of potentials from a file.

Parameters

• f (str, Path) – The file name.

• deserializer (Callable) – Deserializer routine.

Returns

result – A list of potentials.

Return type

list

class miniff.ml_util.loss_result(loss_id, loss_value, reference, prediction, components)

Bases: tuple

property components

Alias for field number 4

property loss_id

Alias for field number 0

property loss_value

Alias for field number 1

property prediction

Alias for field number 3

property reference

Alias for field number 2

miniff.ml_util.minimum_loss_save_policy(tag, loss, state)

A saving policy triggering whenever a global minimum in the loss function occurs.

Parameters

• tag (str) – Dataset tag.

• loss (loss_result) – The loss.

• state – The state object from the previous call.

Returns

• do_save (bool) – Indicates whether saving needs to be performed.

• state – Whatever data needs to be passed to the next call of this function.

miniff.ml_util.parse_lammps_input(f, simplify=True)

Parse LAMMPS input for NN potential.

Parameters

• f (file) – Text file to parse.

• simplify (bool) – Attempt to simplify the resulting module.

Returns

result – A dict of potentials.

Return type

dict

miniff.ml_util.parse_runner_input(f, strict=True)

Parses RuNNer input file for atomic descriptors.

Parameters

• f (str, file) – File or file name to parse.

• strict (bool) – Defines the behavior on unrecognized data: raises ValueError when True or ignores when False.

Returns

result – A list of descriptors.

Return type

list

miniff.ml_util.pull(a)

Pulls array to numpy.

Parameters

a (torch.Tensor) –

Returns

result – The resulting array.

Return type

np.ndarray

miniff.ml_util.requires_fields(*names)

A decorator to ensure that the listed class fields are set.

Parameters

names – A list of fields.

Returns

decorator – The decorator.

Return type

Callable

miniff.ml_util.run_workflow(workflow_class, init=None, prepare=None, run=None)

Runs the workflow and returns it.

Parameters

• workflow_class (class) – The workflow class.

• init – Keyword arguments to workflow initialization.

• prepare – Keyword arguments to workflow data preparation and processing.

• run – Keyword arguments to workflow run phase.

Returns

result – The resulting workflow.

Return type

Workflow

miniff.ml_util.save_potentials(potentials, f, serializer=<function save>)

Saves a list of potentials to a file.

Parameters

• potentials (list) – A list of potentials.

• f (str, Path) – The file to save to.

• serializer (Callable) – Serializer routine.

miniff.ml_util.simple_charges_closure(networks, dataset=None, criterion=None, optimizer=None, optimizer_kwargs=None)

Charges closure.

Parameters

• networks (list) – A list of networks to learn.

• dataset (Dataset) – Default dataset to compute loss for.

• criterion (torch.nn.Module) – Loss criterion, defaults to MSE.

• optimizer (torch.optim.Optimizer) – Optimizer, defaults to Adam.

• optimizer_kwargs (dict) – Additional optimizer arguments.

Returns

closure – The closure function.

Return type

SimpleClosure

miniff.ml_util.simple_energy_closure(networks, dataset=None, criterion=None, optimizer=None, optimizer_kwargs=None, w_energy=1, w_gradients=0, energies_p=False)

Energy and forces closure.

Parameters

• networks (list) – A list of networks to learn.

• dataset (Dataset) – Default dataset to compute loss for.

• criterion (torch.nn.Module) – Loss criterion, defaults to MSE.

• optimizer (torch.optim.Optimizer) – Optimizer, defaults to Adam.

• optimizer_kwargs (dict) – Additional optimizer arguments.

• w_energy (float) – Energy weight in the loss function.

• w_gradients (float) – Gradients weight in the loss function.

• energies_p (bool) – If True, considers the loss of partial energy.

Returns

closure – The closure function.

Return type

SimpleClosure

miniff.ml_util.test_direct(*, workflow_class=<class 'miniff.ml_util.OneShotWorkflow'>, init=None, prepare=None, run=None)

Runs the direct energy test workflow and returns it.

Parameters

• init – Keyword arguments to workflow initialization.

• prepare – Keyword arguments to workflow data preparation and processing.

• run – Keyword arguments to workflow run phase.

Returns

result – The resulting workflow.

Return type

OneShotWorkflow

miniff.ml_util.test_relax(*, workflow_class=<class 'miniff.ml_util.SDWorkflow'>, init=None, prepare=None, run=None)

Runs the batch-relax workflow and returns it.

Parameters

• init – Keyword arguments to workflow initialization.

• prepare – Keyword arguments to workflow data preparation and processing.

• run – Keyword arguments to workflow run phase.

Returns

result – The resulting workflow.

Return type

SDWorkflow

miniff.ml_util.torch_load(f, **kwargs)

Wraps torch.load to load to CPU.

Parameters

• f (str, Path) – The file name.

• kwargs – Other arguments.

Returns

Return type

The deserialized result.

miniff.potentials module

class miniff.potentials.LocalPotential(parameters, cutoff, kernels, family=None, tag=None, additional_inputs=None)

Bases: object

copy(tag=None)

A copy.

Parameters

tag (str) – An optional new tag.

Returns

Return type

A copy of this potential.

static from_state_dict(data)

Loads potential from the state dict.

fun_csr(kname, r, cartesian_row, cartesian_col, shift_vectors, species_row, species_mask, **kwargs)

CSR input function adapter.

fun_csr_split(kname, r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, species_row, species_mask, prefer_parallel=None, resolving=True, out=None, **kwargs)

CSR-split function adapter.

get_kernel_by_name(kname, resolving=True, prefer_parallel=None, rtn_key=False, size=None)

Picks a potential kernel for the given requirements.

Parameters

• kname (str) – Kernel name.

• resolving (bool) – Indicates whether the kernel needs to be resolving.

• prefer_parallel (bool, None) – Indicates whether parallel kernel is preferred.

• rtn_key (bool) – If True, returns the potential key as well.

• size (int) – Problem size.

Returns

• kernel (PotentialKernel) – The kernel requested.

• key – The key.

pre_compute_r(r_data)

Pre-computes quantities for this potential.

property pre_compute_r_functions

state_dict()

State dict of the potential.

class miniff.potentials.LocalPotentialFamily(parameters, cutoff, kernels, parameter_defaults=None, tag=None, proto=None, pre_compute_r=None, additional_inputs=None, complement_accumulating=True, complement_num_grad=True, doc=None)

Bases: object

cutoff(kwargs)

default_proto

alias of miniff.potentials.LocalPotential

get_state_dict(potential)

Retrieves a state dict.

Parameters

potential (LocalPotential) – A potential to represent.

Returns

result – Potential parameters and other information.

Return type

dict

instance_from_state_dict(data)

Restores a potential from its dict representation.

Parameters

data (dict) – A dict with the data.

Returns

result – The restored potential.

Return type

LocalPotential

instantiate(*, tag=None, empty=None, **kwargs)

Instantiate this potential.

Parameters

• tag (str) – An optional tag.

• empty (LocalPotential) – An optional empty object to use.

• kwargs – Values of parameters.

Returns

result – The potential.

Return type

LocalPotential

screen_parameters(**kwargs)

Check the validity of potential parameters.

Parameters

kwargs – Potential parameters.

Returns

result – Screened parameters.

Return type

dict

class miniff.potentials.NestedLocalPotential(parameters, cutoff, kernels, descriptors, **kwargs)

Bases: miniff.potentials.LocalPotential

copy(tag=None)

A copy.

Parameters

tag (str) – An optional new tag.

Returns

Return type

A copy of this potential.

fun_csr_split(*args, **kwargs)

CSR-split function adapter.

state_dict()

State dict of the potential.

class miniff.potentials.NestedLocalPotentialFamily(parameters, cutoff, kernels, parameter_defaults=None, tag=None, proto=None, pre_compute_r=None, additional_inputs=None, complement_accumulating=True, complement_num_grad=True, doc=None)

Bases: miniff.potentials.LocalPotentialFamily

default_proto

alias of miniff.potentials.NestedLocalPotential

get_state_dict(potential)

Retrieves a state dict.

Parameters

potential (NestedLocalPotential) – A potential to represent.

Returns

result – Potential parameters and other information.

Return type

dict

instance_from_state_dict(data)

Restores a potential from its dict representation.

Parameters

data (dict) – A dict with the data.

Returns

result – The restored potential.

Return type

LocalPotential

instantiate(tag=None, **kwargs)

Instantiate this potential.

Parameters

• tag (str) – An optional tag.

• kwargs – Values of parameters.

Returns

result – The potential.

Return type

LocalPotential

class miniff.potentials.PotentialKernel(f: Callable, name: str, out_shape: str, coordination_number: int, is_parallel: bool, is_resolving: bool)

Bases: object

Potential kernel function. This wraps cython routines and provides workarounds for limiting cases.

Parameters

• f (Callable) – The callable function.

• name (str) – Kernel name.

• out_shape (str) – A code describing the output shape.

• coordination_number (int) – Coordination number of the potential.

• is_parallel (bool) – Indicates whether this kernel is parallel.

• is_resolving (bool) – Indicates whether this kernel is resolving (i.e. provides individual energies instead of the total energy).

accumulating()

Constructs a kernel evaluating accumulating potential.

Returns

f_accu – A kernel accumulating potentials.

Return type

PotentialKernel

static compute_shape(spec, n_atoms, n_coords=3)

Calculates shape of an array to receive the output of kernel functions.

Parameters

• spec (str) – A code specifying the shape.

• n_atoms (int) – Atoms count.

• n_coords (int) – Coordinates count.

Returns

out – Array shape.

Return type

tuple

coordination_number: int

f: Callable

get_out_shape(n_atoms, n_coords=3)

id_tuple()

is_parallel: bool

is_resolving: bool

name: str

num_cell_grad(pre_compute_r_functions=None, **kwargs)

Constructs a kernel evaluating numerical cell gradients of a potential.

Parameters

• pre_compute_r_functions (list) – A list of r-dependent quantities to pre-compute.

• kwargs – Keyword arguments to num_grad.

Returns

f_grad – A kernel computing numerical gradients.

Return type

PotentialKernel

num_grad(pre_compute_r_functions=None, **kwargs)

Constructs a kernel evaluating numerical gradients of a potential.

Parameters

• pre_compute_r_functions (list) – A list of r-dependent quantities to pre-compute.

• kwargs – Keyword arguments to num_grad.

Returns

f_grad – A kernel computing numerical gradients.

Return type

PotentialKernel

out_shape: str

returning_f(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, species_row, species_mask, parameters, out=None, screen_inputs=True)

Wrapper for functions evaluating potentials and gradients.

Parameters

• r_indptr (np.ndarray) – Index pointers of a sparse csr pair distance array.

• r_indices (np.ndarray) – Column indices of a sparse csr pair distance array.

• r_data (np.ndarray, None) – Pre-computed distances between atom pairs corresponding to the above indices. If None, it will be recomputed from the cartesian coordinates data.

• cartesian_row (np.ndarray) – Cartesian coordinates corresponding to row indices.

• cartesian_col (np.ndarray) – Cartesian coordinates corresponding to column indices.

• shift_vectors (np.ndarray) – Integer shift vector of each neighbor expressed in the crystal basis.

• parameters (dict) – Potential parameters.

• out (np.ndarray) – Output array.

• species_row (np.ndarray) – Atomic species with coordinates cartesian_row encoded as integers.

• species_mask (np.ndarray) – A mask to apply to species: for example, an array with two integers corresponding to specimen Bi and Se for pair potential Bi-Se.

• screen_inputs (bool) – If True, performs input screening.

Returns

Return type

Results of kernel computation.

scaled()

Constructs a kernel evaluating scaled potential.

Returns

f_scaling – A scaling kernel.

Return type

PotentialKernel

screen_inputs(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, species_row, species_mask, out)

exception miniff.potentials.PotentialRuntimeWarning

Bases: RuntimeWarning

class miniff.potentials.PreComputeRFunction(f, parameters_map=None)

Bases: object

cache_key(parameters)

get_parameter_values(parameters)

class miniff.potentials.SW2PotentialFamily(parameters, cutoff, kernels, parameter_defaults=None, tag=None, proto=None, pre_compute_r=None, additional_inputs=None, complement_accumulating=True, complement_num_grad=True, doc=None)

Bases: miniff.potentials.LocalPotentialFamily

instantiate(min_at=(1.122462048309373, - 1), tag=None, **kwargs)

Instantiate this potential.

Parameters

• tag (str) – An optional tag.

• empty (LocalPotential) – An optional empty object to use.

• kwargs – Values of parameters.

Returns

result – The potential.

Return type

LocalPotential

miniff.potentials.behler2_p2(r, a, eta, r_sphere)

Second derivative of the two-point Behler descriptor.

Parameters

• r (float, np.ndarray) – Radial point(s).

• a (float) –

• eta (float) –

• r_sphere (float) – Behler type 2 function parameters.

Returns

result – The second derivative of the two-point descriptor.

Return type

float, np.ndarray

miniff.potentials.behler_turning_point(a, eta, r_sphere)

Searches for the turning point of the two-point Behler descriptor.

Parameters

• a (float) –

• eta (float) –

• r_sphere (float) – Behler type 2 function parameters.

Returns

result – The turning point.

Return type

float

miniff.potentials.eval_potentials(encoded_potentials, kname, sparse_pair_distances, cartesian_row, cartesian_col, shift_vectors, spec_encoded_row, pre_compute_r=False, additional_inputs=None, cutoff=None, out=None, **kwargs)

Calculates potentials: values, gradients and more.

Parameters

• encoded_potentials (list, LocalPotential) – A list of potentials or a single potential.

• kname (str, None) – Function to evaluate: ‘kernel’, ‘kernel_gradient’ or whatever other kernel function set for all potentials in the list.

• sparse_pair_distances (csr_matrix) – Pair distances.

• cartesian_row (np.ndarray) – Cartesian coordinates of atoms inside the cell.

• cartesian_col (np.ndarray) – Cartesian coordinates of surrounding atoms.

• shift_vectors (np.ndarray) – Shift vectors of each cartesian_col in the unit cell basis.

• spec_encoded_row (np.ndarray) – Species encoded as integers inside the unit cell.

• pre_compute_r (tuple) – Optional pre-computed r-dependent quantities for this set of potentials.

• additional_inputs (dict) – A dictionary with additional inputs which may be required to compute potentials.

• cutoff (float) – Optional cutoff to check potentials against.

• out (np.ndarray) – The output buffer [n_potentials, n_atoms] for kname == “kernel” and [n_potentials, n_atoms, n_atoms, 3] for kname == “kernel_gradient”.

• kwargs – Other common arguments to kernel functions.

Returns

result – The result of the potential computation given the cell data.

Return type

np.ndarray

miniff.potentials.exp_fn(r, eta)

miniff.potentials.kernel_c_ewald_self(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, eta, charges, volume, species_row, species_mask, out)

Ewald on-site potential energy kernel.

Parameters

• kind ({'fun', 'grad'}) – Indicates to return per-point energies or energy gradients.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• eta (float) – Gaussian screening parameter.

• charges (np.ndarray) – Atomic charges.

• volume (float) – Lattice volume.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_c_ewald_total(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, a, eta, charges, volume, k_grid, scale, species_row, species_mask, out)

A kernel for Ewald potential sum.

Parameters

• components (list) – A list of potential kernel components: real, k, self.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• a (float) – Cutoff of the real-space part.

• eta (float) –

• charges (np.ndarray) – An array with atomic charges.

• volume (float) – Unit cell volume.

• k_grid (np.ndarray) – Reciprocal summation grid.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_dict(kernels)

Turns a list of kernels into a lookup dictionary. Checks for collisions.

Parameters

kernels (list, tuple) – A list of kernels.

Returns

result – The resulting lookup dictionary.

Return type

dict

miniff.potentials.kernel_ewald_charge_wrapper(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, a, eta, charge_middleware, volume, k_grid, scale, species_row, species_mask, out)

A kernel combining charge descriptors into Ewald potentials.

The workflow: 1. Compute charges. 2. Feed charges to Ewald potentials.

Parameters

• kind (str) – Ewald kernel to redirect to.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A dictionary with potentials determining atomic charges.

• a (float) –

• eta (float) –

• charge_middleware ({"subtract_mean", None}) – Charge post-processing.

• volume (float) –

• k_grid (np.ndarray) – Arguments to Ewald.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_ewald_self(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, eta, charges, volume, species_row, species_mask, out)

Ewald on-site potential energy kernel.

Parameters

• kind ({'fun', 'grad'}) – Indicates to return per-point energies or energy gradients.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• eta (float) – Gaussian screening parameter.

• charges (np.ndarray) – Atomic charges.

• volume (float) – Lattice volume.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_ewald_total(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, a, eta, charges, volume, k_grid, scale, species_row, species_mask, out)

A kernel for Ewald potential sum.

Parameters

• components (list) – A list of potential kernel components: real, k, self.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• a (float) – Cutoff of the real-space part.

• eta (float) –

• charges (np.ndarray) – An array with atomic charges.

• volume (float) – Unit cell volume.

• k_grid (np.ndarray) – Reciprocal summation grid.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_g_ewald_charge_wrapper(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, a, eta, charge_middleware, volume, k_grid, scale, species_row, species_mask, out)

A kernel combining charge descriptors into Ewald potentials.

The workflow: 1. Compute charges. 2. Feed charges to Ewald potentials.

Parameters

• kind (str) – Ewald kernel to redirect to.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A dictionary with potentials determining atomic charges.

• a (float) –

• eta (float) –

• charge_middleware ({"subtract_mean", None}) – Charge post-processing.

• volume (float) –

• k_grid (np.ndarray) – Arguments to Ewald.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_g_ewald_self(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, eta, charges, volume, species_row, species_mask, out)

Ewald on-site potential energy kernel.

Parameters

• kind ({'fun', 'grad'}) – Indicates to return per-point energies or energy gradients.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• eta (float) – Gaussian screening parameter.

• charges (np.ndarray) – Atomic charges.

• volume (float) – Lattice volume.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_g_ewald_total(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, a, eta, charges, volume, k_grid, scale, species_row, species_mask, out)

A kernel for Ewald potential sum.

Parameters

• components (list) – A list of potential kernel components: real, k, self.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• a (float) – Cutoff of the real-space part.

• eta (float) –

• charges (np.ndarray) – An array with atomic charges.

• volume (float) – Unit cell volume.

• k_grid (np.ndarray) – Reciprocal summation grid.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_g_on_site(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, v0, species_row, species_mask, out)

The gradient of on-site potential is zero.

class miniff.potentials.kernel_kind(name, parallel, resolving)

Bases: tuple

property name

Alias for field number 0

property parallel

Alias for field number 1

property resolving

Alias for field number 2

miniff.potentials.kernel_on_site(r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, v0, species_row, species_mask, out)

A simple constant on-site potential scalar value. Most input arguments are irrelevant.

miniff.potentials.kernel_u_ewald_charge_wrapper(kind, r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, descriptors, a, eta, charge_middleware, volume, k_grid, scale, species_row, species_mask, out)

A kernel combining charge descriptors into Ewald potentials.

The workflow: 1. Compute charges. 2. Feed charges to Ewald potentials.

Parameters

• kind (str) – Ewald kernel to redirect to.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• descriptors (list) – A dictionary with potentials determining atomic charges.

• a (float) –

• eta (float) –

• charge_middleware ({"subtract_mean", None}) – Charge post-processing.

• volume (float) –

• k_grid (np.ndarray) – Arguments to Ewald.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_u_ewald_self(kind, r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, eta, charges, volume, species_row, species_mask, out)

Ewald on-site potential energy kernel.

Parameters

• kind ({'fun', 'grad'}) – Indicates to return per-point energies or energy gradients.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• eta (float) – Gaussian screening parameter.

• charges (np.ndarray) – Atomic charges.

• volume (float) – Lattice volume.

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.kernel_u_ewald_total(components, r_indptr, r_indices, r_data, cartesian_row, cartesian_col, shift_vectors, a, eta, charges, volume, k_grid, scale, species_row, species_mask, out)

A kernel for Ewald potential sum.

Parameters

• components (list) – A list of potential kernel components: real, k, self.

• r_indptr (np.ndarray) –

• r_indices (np.ndarray) –

• r_data (np.ndarray) –

• cartesian_row (np.ndarray) –

• cartesian_col (np.ndarray) –

• shift_vectors (np.ndarray) – Common arguments to descriptor kernels specifying coordinates and neighbor relations.

• a (float) – Cutoff of the real-space part.

• eta (float) –

• charges (np.ndarray) – An array with atomic charges.

• volume (float) – Unit cell volume.

• k_grid (np.ndarray) – Reciprocal summation grid.

• scale (float) – The scale: e^2 / 4 / π / ε0 = Hartree * aBohr

• species_row (np.ndarray) –

• species_mask (np.ndarray) –

• out (np.ndarray) –

miniff.potentials.potential_from_state_dict(data)

Restores a potential from its state dict.

Parameters

data (dict) – A state dict.

Returns

result – The restored potential.

Return type

LocalPotential

miniff.potentials.pre_compute_r(r, f_r, parameters)

Pre-computes r-dependent functions.

Some potentials may partially share pre-computed functions to speed up computations. This function prepares a dense array of pre-computed distance-dependent functions.

Parameters

• r (np.ndarray) – A 1D array of distances.

• f_r (list) – A list of pairs of parameters and the corresponding functions.

• parameters (dict) – A dict with potential parameters.

Returns

result

Return type

np.ndarray

miniff.potentials.sine_cutoff_fn(r, a)

miniff.potentials.sine_cutoff_fp(r, a)

miniff.presentation module

miniff.presentation.plot_adf(a, data, ax=None, legend=True, xlabel=True, ylabel=True, **kwargs)

Plot angular distribution function.

Parameters

• a (np.ndarray) – Angular points.

• data (dict) – ADF.

• ax (Axes) – matplotlib axes to plot on.

• legend (str, bool) – If True, creates a legend. If “labels” creates labels but does not invoke the legend. Otherwise puts neither plot labels nor the legend.

• xlabel (bool, str) – x axis label.

• ylabel (bool, str) – y axis label.

• kwargs – Passed to ax.plot.

Returns

ax – matplotlib axes.

Return type

Axes

miniff.presentation.plot_convergence(y=None, append=True, ax=None, xlabel='Step', ylabel='Error', comment=None, grid=True, labels=None)

Prepares convergence plots.

Parameters

• y (tuple, list, np.ndarray, float, None) – Error values.

• append (bool) – If True and ax is set, appends convergence data.

• ax (Axes) – matplotlib axes to plot on.

• xlabel (str) – x axis label.

• ylabel (str) – y axis label.

• comment (str) – An optional comment.

• grid (bool) – Plot grid.

• labels (list, tuple) – A list of labels for the legend.

Returns

ax – matplotlib axis.

Return type

Axes

miniff.presentation.plot_descriptors_2(descriptors, ax=None, length_unit='angstrom', xlabel=True, legend=True, **kwargs)

Plots two-point descriptor functions.

Parameters

• descriptors (dict) – A dictionary with atoms (keys) and descriptors.

• ax (Axes) – matplotlib axes to plot on.

• length_unit (str) – A valid numericalunits string expression for units.

• xlabel (bool, str) – x axis label.

• legend (bool) – If True, displays legend.

• kwargs – Arguments to pyplot.plot.

Returns

ax – matplotlib axes.

Return type

Axes

miniff.presentation.plot_diagonal(*args, replace=False, ax=None, xlabel='Reference', ylabel='Prediction', nmax=None, unit_label=None, window=None, **kwargs)

Diagonal plot “reference” vs “data”.

Parameters

• args – Reference and prediction pairs.

• replace (bool) – If True and ax set, attempts to find previous data on the plot and to re-plot it.

• ax (Axes) – matplotlib axes to plot on.

• xlabel (str, None) – x axis label.

• ylabel (str, None) – y axis label.

• nmax (int) – Displays only few most outstanding values.

• unit_label (str) – Optional label to specify units in axes labels.

• window (tuple) – An optional window to constrain to.

• kwargs – Arguments to pyplot.scatter.

Returns

ax – matplotlib axis.

Return type

Axes

miniff.presentation.plot_potential_2(potentials, limits=None, pair=None, ax=None, energy_unit='Ry', length_unit='angstrom', xlabel=True, ylabel=True, mark_points=None, origin=None, **kwargs)

Plot potential profile between a pair of points.

Parameters

• potentials (LocalPotential, list) – The potential to plot.

• limits (tuple) – Limits in absolute units. Defaults to (potential.cutoff / 10, potential.cutoff).

• pair (str) – Pair to plot.

• ax (Axes) – matplotlib axes to plot on.

• energy_unit (str) – A valid numericalunits string expression for units.

• length_unit (str) – A valid numericalunits string expression for units.

• xlabel (bool, str) – x axis label.

• ylabel (bool, str) – y axis label.

• mark_points (list, tuple) – Marks special points on the potential profile.

• origin (str, float) – Energy origin: either float number of ‘left’, ‘right’, or ‘median’.

• kwargs – Arguments to pyplot.plot.

Returns

ax – matplotlib axes.

Return type

Axes

miniff.presentation.plot_rdf(r, data, ax=None, legend=True, length_unit='Å', xlabel=True, ylabel=True, **kwargs)

Plot radial distribution function.

Parameters

• r (np.ndarray, list) – Radial points.

• data (dict) – Radial distribution functions.

• ax (Axes) – matplotlib axes to plot on.

• legend (str, bool) – If True, creates a legend. If “labels” creates labels but does not invoke the legend. Otherwise puts neither plot labels nor the legend.

• length_unit (str) – A valid numericalunits string expression for units.

• xlabel (bool, str) – x axis label.

• ylabel (bool, str) – y axis label.

• kwargs – Passed to ax.plot.

Returns

ax – matplotlib axes.

Return type

Axes

miniff.presentation.plot_rdf_panels(r, data, axes=None, legend=True, length_unit='Å', xlabel=True, ylabel=True, **kwargs)

Plot radial distribution function in separate panels.

Parameters

• r (np.ndarray, list) – Radial points.

• data (dict) – Radial distribution functions.

• axes (list) – A list of matplotlib axes to plot on.

• legend (str, bool) – If True, creates a legend by placing specimen pairs in the top-right corner.

• length_unit (str) – A valid numericalunits string expression for units.

• xlabel (bool, str) – x axis label.

• ylabel (bool, str) – y axis label.

• kwargs – Passed to ax.plot.

Returns

ax – matplotlib axes.

Return type

Axes

miniff.presentation.plot_strain_profile(potentials, cell, limits=(0.9, 1.1), direction=(1, 1, 1), ax=None, energy_unit='Ry', xlabel=True, ylabel=True, mark_points=None, origin=None, profile_kwargs=None, **kwargs)

Plot energy as a function of strain.

Parameters

• potentials (list) – Potentials to profile.

• cell (Cell) – The original cell.

• limits (tuple) – Lower and upper strain bounds.

• direction (list, tuple, np.ndarray) – Strain direction.

• ax (Axes) – matplotlib axes to plot on.

• energy_unit (str) – A valid numericalunits string expression for units.

• xlabel (bool, str) – x axis label.

• ylabel (bool, str) – y axis label.

• mark_points (list, tuple) – Marks special points on the potential profile.

• origin (str, float) – Energy origin: either float number of ‘left’, ‘right’, or ‘median’.

• profile_kwargs (dict) – Arguments to kernel.profile_directed_strain.

• kwargs – Arguments to pyplot.plot.

Returns

ax – matplotlib axes.

Return type

Axes

miniff.presentation.text_bars(values, mn=None, mx=None, palette=' ▁▂▃▄▅▆▇█')

A text bar plot.

Parameters

• values (Iterable) – Evenly distributed values as a 1D array.

• mn (float) – The minimal value.

• mx (float) – The maximal value.

• palette (str) – The palette to draw with.

Returns

result – A character bar plot.

Return type

str

miniff.units module

class miniff.units.JSONEncoderWithArray(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: json.encoder.JSONEncoder

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

class miniff.units.UnitsContext(seed=None)

Bases: object

class miniff.units.UnitsDict

Bases: dict

apply(parameters)

Applies units to parameters.

Parameters

parameters (dict) – A dict of potential parameters where units have to be applied.

Returns

result – A dict of potential parameters with units applied.

Return type

dict

get_uv(key, default=1)

Retrieves a unit value assigned to the key.

Parameters

• key – A valid dictionary key.

• default (float) – Default value.

Returns

result – The unit value.

Return type

float

lift(parameters)

Lift units from parameters (inverse to self.apply).

Parameters

parameters (dict) – A dict of potential parameters where units have to be lifted.

Returns

result – A dict of potential parameters with units lifted.

Return type

dict

repr(parameters)

Represents parameters with the units specified.

Parameters

parameters (dict) – Parameters to represent.

Returns

result – The string representation.

Return type

str

repr1(value, k, fmt='{:.3e}', spacer=' ')

Represents a single value with units.

Parameters

• value (float) – The value to represent.

• k (str) – The key to lookup units.

• fmt (str) – Floating-point format.

• spacer (str) – Spacer between value and units.

Returns

result – The resulting string.

Return type

str

exception miniff.units.UnknownUnitsWarning

Bases: RuntimeWarning

miniff.units.array_from_json(d)

miniff.units.array_to_json(a, units=None)

miniff.units.check_units_known(logger=None, tolerance=1e-06)

class miniff.units.delayed(x)

Bases: object

property val

miniff.units.dump(*args, **kwargs)

miniff.units.dumps(*args, **kwargs)

miniff.units.element_masses()

Prepares units-aware element masses.

miniff.units.init_default_atomic_units()

Initializes atomic units in numericalunits.

miniff.units.load(*args, **kwargs)

miniff.units.load_nu(data)

Loads previously saved numericalunits values.

Parameters

data (dict) – A dictionary with the serialized data.

miniff.units.loads(*args, **kwargs)

miniff.units.new_units_context

alias of miniff.units.UnitsContext

miniff.units.serialize_nu()

Retrieves the current state of numericalunits package and saves it into dict.

Returns

units – A dictionary with units.

Return type

dict

miniff.units.units_object_hook(d)

miniff.util module

miniff.util.cartesian(arrays)

Cartesian product of many coordinate arrays.

Parameters

arrays (list, tuple) – Samplings along each axis.

Returns

result – The resulting coordinates of a many-dimensional grid.

Return type

np.ndarray

miniff.util.cat(*args)

Concatenate flattened copies of array.

Parameters

args – Arrays to concatenate.

Returns

result – The concatenated array.

Return type

np.ndarray

miniff.util.default_logger(name='main', fmt='[%(levelname)s] %(asctime)s %(message)s', date_fmt='%H:%M:%S', lvl=20)

Prepares a default logger printing to stdout.

Parameters

• name (str) – Logger name.

• fmt (str) – Logger format string.

• date_fmt (str) – Date format.

• lvl (int) – Logger sink level.

Returns

The resulting logger.

Return type

logger

miniff.util.diag1(a)

Creates a diagonal tensor from a multidimensional input tensor.

Parameters

a (np.ndarray) – Diagonal values.

Returns

result – The resulting tensor with one more dimension.

Return type

np.ndarray

miniff.util.dict_reduce(d, operation)

Reduces dictionary values.

Parameters

• d (Iterable) – Dictionaries to process.

• operation (Callable) – Operation on values.

Returns

result – A dictionary with reduced values.

Return type

dict

miniff.util.lattice_up_to_radius(radius, lattice_vecs, cover=False, zero=True)

Computes grid point coordinates of the given lattice.

Parameters

• radius (float) – The cutoff radius.

• lattice_vecs (np.ndarray) – Lattice vectors.

• cover (bool) – If True, adds points to “cover” the grid.

• zero (bool) – If True, includes the origin (otherwise excludes it).

Returns

result – Grid points.

Return type

np.ndarray

miniff.util.lookup(data, key)

Looks up data in the key and prepares a new array with these values.

Parameters

• data (np.ndarray) – The data to lookup.

• key (dict) – The lookup key.

Returns

result – The resulting array with the obtained values.

Return type

np.ndarray

miniff.util.masked_unique(a, return_inverse=False, fill_value=None)

A proper implementation of np.unique for masked arrays.

Parameters

• a (np.ma.masked_array) – The array to process.

• return_inverse (bool) – If True, returns the masked inverse.

• fill_value (int) – An optional value to fill the return_inverse array.

Returns

• key (np.ndarray) – Unique entries.

• inverse (np.ma.masked_array, optional) – Integer masked array with the inverse.

miniff.util.np_hash(*a)

Silly implementation of array hashing.

Parameters

a – Arrays to hash.

Returns

result – The hash value.

Return type

bytes

miniff.util.num_grad(scalar_f, x, *args, x_name=None, eps=0.0001, **kwargs)

Numerical gradient.

Parameters

• scalar_f (function) – A function computing a scalar.

• x (np.ndarray) – The point to compute gradient at.

• x_name (str) – The name of the argument x in the target function.

• eps (float) – Numerical gradient step.

• *args –

• **kwargs – Other arguments to the function.

Returns

gradient – The gradient value(s).

Return type

np.ndarray

miniff.util.randsphere(n)

Random points on a sphere.

Parameters

n (int) – Sample count.

Returns

result – The resulting cartesian coordinates.

Return type

np.ndarray

miniff.util.split2(a, like=None)

Splits array into two halves.

Parameters

• a (np.ndarray) – The original array.

• like (tuple) – A two-tuple with arrays defining shapes of the output.

Returns

• first (np.ndarray)

• second (np.ndarray) – First and second halves.

miniff.util.unit_vectors(x, metric=None)

Unit vectors.

Parameters

• x (np.ndarray) – A collection of vectors.

• metric (np.ndarray) – An optional metric.

Returns

result – An array of the same shape as x with unit vectors.

Return type

np.ndarray

Module contents