matscipy.calculators.manybody.calculator

Generic Many body potential.

Classes

Manybody(atom_type, pair_type, F, G, d1F, ...)

NiceManybody(F, G, neighbourhood)

Manybody calculator with nicer API.
class matscipy.calculators.manybody.calculator.Manybody(atom_type, pair_type, F, G, d1F, d2F, d11F, d22F, d12F, d1G, d11G, d2G, d22G, d12G, cutoff, neighbourhood: Neighbourhood | None = None)

Bases: MatscipyCalculator

Attributes:
directory
label

Methods

band_structure()

Create band-structure object for plotting.

calculate(atoms, properties, system_changes)

Calculate system properties.

calculate_numerical_forces(atoms[, d])

Calculate numerical forces using finite difference.

calculate_numerical_stress(atoms[, d, voigt])

Calculate numerical stress using finite difference.

calculate_properties(atoms, properties)

This method is experimental; currently for internal use.

check_state(atoms[, tol])

Check for any system changes since last calculation.

get_birch_coefficients(atoms)

Compute the Birch coefficients (Effective elastic constants at non-zero stress).

get_born_elastic_constants(atoms)

Compute the Born elastic constants.

get_cutoff(atoms)

Return a valid cutoff.

get_dynamical_matrix(atoms)

Compute dynamical matrix (=mass weighted Hessian).

get_elastic_constants(atoms[, cg_parameters])

Compute the elastic constants at zero temperature.

get_hessian(atoms[, format, divide_by_masses])

Calculate the Hessian matrix for a generic many-body potential.

get_hessian_from_second_derivative(atoms)

Compute the Hessian matrix from second derivatives.

get_magnetic_moments([atoms])

Calculate magnetic moments projected onto atoms.

get_non_affine_contribution_to_elastic_constants(atoms)

Compute the correction of non-affine displacements to the elasticity tensor.

get_non_affine_forces_from_second_derivative(atoms)

Compute the analytical non-affine forces.

get_nonaffine_forces(atoms)

Compute the non-affine forces which result from an affine deformation of atoms.

get_property(name[, atoms, allow_calculation])

Get the named property.

get_second_derivative(atoms, drda_pc, drdb_pc)

Calculate the second derivative of the energy with respect to arbitrary variables a and b.

get_stress_contribution_to_elastic_constants(atoms)

Compute the correction to the elastic constants due to non-zero stress in the configuration.

get_stresses([atoms])

the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress

read(label)

Read atoms, parameters and calculated properties from output file.

reset()

Clear all information from old calculation.

set(**kwargs)

Set parameters like set(key1=value1, key2=value2, ...).

set_label(label)

Set label and convert label to directory and prefix.

calculation_required

export_properties

get_atoms

get_charges

get_default_parameters

get_dipole_moment

get_forces

get_magnetic_moment

get_potential_energies

get_potential_energy

get_stress

read_atoms

todict
implemented_properties: List[str] = ['free_energy', 'energy', 'stress', 'forces', 'hessian', 'born_constants', 'nonaffine_forces', 'birch_coefficients', 'dynamical_matrix', 'elastic_constants']

Properties calculator can handle (energy, forces, …)

default_parameters: Dict[str, Any] = {}

Default parameters

name = 'Manybody'
__init__(atom_type, pair_type, F, G, d1F, d2F, d11F, d22F, d12F, d1G, d11G, d2G, d22G, d12G, cutoff, neighbourhood: Neighbourhood | None = None)

Basic calculator implementation.

restart: str

Prefix for restart file. May contain a directory. Default is None: don’t restart.

ignore_bad_restart_file: bool

Deprecated, please do not use. Passing more than one positional argument to Calculator() is deprecated and will stop working in the future. Ignore broken or missing restart file. By default, it is an error if the restart file is missing or broken.

directory: str or PurePath

Working directory in which to read and write files and perform calculations.

label: str

Name used for all files. Not supported by all calculators. May contain a directory, but please use the directory parameter for that instead.

atoms: Atoms object

Optional Atoms object to which the calculator will be attached. When restarting, atoms will get its positions and unit-cell updated from file.

get_cutoff(atoms)

Return a valid cutoff.

calculate(atoms, properties, system_changes)

Calculate system properties.

get_hessian(atoms, format='sparse', divide_by_masses=False)

Calculate the Hessian matrix for a generic many-body potential.

For an atomic configuration with N atoms in d dimensions the hessian matrix is a symmetric, hermitian matrix with a shape of (d*N,d*N). The matrix is in general a sparse matrix, which consists of dense blocks of shape (d,d), which are the mixed second derivatives.

Parameters:

  • atoms (ase.Atoms) – Atomic configuration in a local or global minima.

  • format ("sparse" or "neighbour-list") – Output format of the hessian matrix.

  • divide_by_masses (bool) – if true return the dynamic matrix else hessian matrix

Returns:

  • bsr_matrix – either hessian or dynamic matrix

  • Restrictions

  • ———-

  • This method is currently only implemented for three dimensional systems

get_second_derivative(atoms, drda_pc, drdb_pc, i_p=None, j_p=None, r_p=None, r_pc=None)

Calculate the second derivative of the energy with respect to arbitrary variables a and b.

Parameters:

  • atoms (ase.Atoms) – Atomic configuration in a local or global minima.

  • drda_pc/drdb_pc (array_like) – Derivative of atom positions with respect to variable a/b.

  • i_p (array) – First atom index

  • j_p (array) – Second atom index

  • r_p (array) – Absolute distance

  • r_pc (array) – Distance vector

get_hessian_from_second_derivative(atoms)

Compute the Hessian matrix from second derivatives.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_non_affine_forces_from_second_derivative(atoms)

Compute the analytical non-affine forces.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_born_elastic_constants(atoms)

Compute the Born elastic constants.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_nonaffine_forces(atoms)

Compute the non-affine forces which result from an affine deformation of atoms.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

band_structure()

Create band-structure object for plotting.

calculate_numerical_forces(atoms, d=0.001)

Calculate numerical forces using finite difference.

All atoms will be displaced by +d and -d in all directions.

calculate_numerical_stress(atoms, d=1e-06, voigt=True)

Calculate numerical stress using finite difference.

calculate_properties(atoms, properties)

This method is experimental; currently for internal use.

calculation_required(atoms, properties)
check_state(atoms, tol=1e-15)

Check for any system changes since last calculation.

property directory: str
discard_results_on_any_change = False

Whether we purge the results following any change in the set() method.

export_properties()
get_atoms()
get_birch_coefficients(atoms)

Compute the Birch coefficients (Effective elastic constants at non-zero stress).

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_charges(atoms=None)
get_default_parameters()
get_dipole_moment(atoms=None)
get_dynamical_matrix(atoms)

Compute dynamical matrix (=mass weighted Hessian).

get_elastic_constants(atoms, cg_parameters={'M': None, 'atol': 1e-05, 'callback': None, 'maxiter': None, 'rtol': 1e-05, 'x0': None})

Compute the elastic constants at zero temperature. These are sum of the born, the non-affine and the stress contribution.

Parameters:

  • atoms (ase.Atoms) – Atomic configuration in a local or global minima.

  • cg_parameters (dict) –

    Dictonary for the conjugate-gradient solver.

    x0: {array, matrix}

    Starting guess for the solution.

    rtol/atol: float, optional

    Tolerances for convergence, norm(residual) <= max(rtol*norm(b), atol).

    maxiter: int

    Maximum number of iterations. Iteration will stop after maxiter steps even if the specified tolerance has not been achieved.

    M: {sparse matrix, dense matrix, LinearOperator}

    Preconditioner for A.

    callback: function

    User-supplied function to call after each iteration.

get_forces(atoms=None)
get_magnetic_moment(atoms=None)
get_magnetic_moments(atoms=None)

Calculate magnetic moments projected onto atoms.

get_non_affine_contribution_to_elastic_constants(atoms, eigenvalues=None, eigenvectors=None, pc_parameters=None, cg_parameters={'M': None, 'atol': 1e-05, 'callback': None, 'maxiter': None, 'rtol': 1e-05, 'x0': None})

Compute the correction of non-affine displacements to the elasticity tensor. The computation of the occuring inverse of the Hessian matrix is bypassed by using a cg solver.

If eigenvalues and and eigenvectors are given the inverse of the Hessian can be easily computed.

Parameters:

  • atoms (ase.Atoms) – Atomic configuration in a local or global minima.

  • eigenvalues (array) – Eigenvalues in ascending order obtained by diagonalization of Hessian matrix. If given, use eigenvalues and eigenvectors to compute non-affine contribution.

  • eigenvectors (array) – Eigenvectors corresponding to eigenvalues.

  • cg_parameters (dict) –

    Dictonary for the conjugate-gradient solver.

    x0: {array, matrix}

    Starting guess for the solution.

    rtol/atol: float, optional

    Tolerances for convergence, norm(residual) <= max( rtol*norm(b), atol).

    maxiter: int

    Maximum number of iterations. Iteration will stop after maxiter steps even if the specified tolerance has not been achieved.

    M: {sparse matrix, dense matrix, LinearOperator}

    Preconditioner for A.

    callback: function

    User-supplied function to call after each iteration.

  • pc_parameters (dict) –

    Dictonary for the incomplete LU decomposition of the Hessian.

    A: array_like

    Sparse matrix to factorize.

    drop_tol: float

    Drop tolerance for an incomplete LU decomposition.

    fill_factor: float

    Specifies the fill ratio upper bound.

    drop_rule: str

    Comma-separated string of drop rules to use.

    permc_spec: str

    How to permute the columns of the matrix for sparsity.

    diag_pivot_thresh: float

    Threshold used for a diagonal entry to be an acceptable pivot.

    relax: int

    Expert option for customizing the degree of relaxing supernodes.

    panel_size: int

    Expert option for customizing the panel size.

    options: dict

    Dictionary containing additional expert options to SuperLU.

get_potential_energies(atoms=None)
get_potential_energy(atoms=None, force_consistent=False)
get_property(name, atoms=None, allow_calculation=True)

Get the named property.

get_stress(atoms=None)
get_stress_contribution_to_elastic_constants(atoms)

Compute the correction to the elastic constants due to non-zero stress in the configuration. Stress term results from working with the Cauchy stress.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_stresses(atoms=None)

the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress

ignored_changes: Set[str] = {}

Properties of Atoms which we ignore for the purposes of cache

property label
read(label)

Read atoms, parameters and calculated properties from output file.

Read result from self.label file. Raise ReadError if the file is not there. If the file is corrupted or contains an error message from the calculation, a ReadError should also be raised. In case of succes, these attributes must set:

atoms: Atoms object

The state of the atoms from last calculation.

parameters: Parameters object

The parameter dictionary.

results: dict

Calculated properties like energy and forces.

The FileIOCalculator.read() method will typically read atoms and parameters and get the results dict by calling the read_results() method.

classmethod read_atoms(restart, **kwargs)
reset()

Clear all information from old calculation.

set(**kwargs)

Set parameters like set(key1=value1, key2=value2, …).

A dictionary containing the parameters that have been changed is returned.

Subclasses must implement a set() method that will look at the chaneged parameters and decide if a call to reset() is needed. If the changed parameters are harmless, like a change in verbosity, then there is no need to call reset().

The special keyword ‘parameters’ can be used to read parameters from a file.

set_label(label)

Set label and convert label to directory and prefix.

Examples:

  • label=’abc’: (directory=’.’, prefix=’abc’)

  • label=’dir1/abc’: (directory=’dir1’, prefix=’abc’)

  • label=None: (directory=’.’, prefix=None)

todict(skip_default=True)
class matscipy.calculators.manybody.calculator.NiceManybody(F, G, neighbourhood)

Bases: Manybody

Manybody calculator with nicer API.

Attributes:
directory
label

Methods

F()

Pair potential.

G()

Triplet potential.

band_structure()

Create band-structure object for plotting.

calculate(atoms, properties, system_changes)

Calculate system properties.

calculate_numerical_forces(atoms[, d])

Calculate numerical forces using finite difference.

calculate_numerical_stress(atoms[, d, voigt])

Calculate numerical stress using finite difference.

calculate_properties(atoms, properties)

This method is experimental; currently for internal use.

check_state(atoms[, tol])

Check for any system changes since last calculation.

get_birch_coefficients(atoms)

Compute the Birch coefficients (Effective elastic constants at non-zero stress).

get_born_elastic_constants(atoms)

Compute the Born elastic constants.

get_cutoff(atoms)

Return a valid cutoff.

get_dynamical_matrix(atoms)

Compute dynamical matrix (=mass weighted Hessian).

get_elastic_constants(atoms[, cg_parameters])

Compute the elastic constants at zero temperature.

get_hessian(atoms[, format, divide_by_masses])

Calculate the Hessian matrix for a generic many-body potential.

get_hessian_from_second_derivative(atoms)

Compute the Hessian matrix from second derivatives.

get_magnetic_moments([atoms])

Calculate magnetic moments projected onto atoms.

get_non_affine_contribution_to_elastic_constants(atoms)

Compute the correction of non-affine displacements to the elasticity tensor.

get_non_affine_forces_from_second_derivative(atoms)

Compute the analytical non-affine forces.

get_nonaffine_forces(atoms)

Compute the non-affine forces which result from an affine deformation of atoms.

get_property(name[, atoms, allow_calculation])

Get the named property.

get_second_derivative(atoms, drda_pc, drdb_pc)

Calculate the second derivative of the energy with respect to arbitrary variables a and b.

get_stress_contribution_to_elastic_constants(atoms)

Compute the correction to the elastic constants due to non-zero stress in the configuration.

get_stresses([atoms])

the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress

read(label)

Read atoms, parameters and calculated properties from output file.

reset()

Clear all information from old calculation.

set(**kwargs)

Set parameters like set(key1=value1, key2=value2, ...).

set_label(label)

Set label and convert label to directory and prefix.

calculation_required

export_properties

get_atoms

get_charges

get_default_parameters

get_dipole_moment

get_forces

get_magnetic_moment

get_potential_energies

get_potential_energy

get_stress

read_atoms

todict
class F

Bases: ABC

Pair potential.

Methods

__call__(r, xi, atom_type, pair_type)

Compute energy.

gradient(r, xi, atom_type, pair_type)

Compute gradient.

hessian(r, xi, atom_type, pair_type)

Compute hessian.
abstract gradient(r, xi, atom_type, pair_type)

Compute gradient.

abstract hessian(r, xi, atom_type, pair_type)

Compute hessian.

class G

Bases: ABC

Triplet potential.

Methods

__call__(r_ij, r_ik, atom_type, ij_type, ik_type)

Compute energy.

gradient(r_ij, r_ik, atom_type, ij_type, ik_type)

Compute gradient.

hessian(r_ij, r_ik, atom_type, ij_type, ik_type)

Compute hessian.
abstract gradient(r_ij, r_ik, atom_type, ij_type, ik_type)

Compute gradient.

abstract hessian(r_ij, r_ik, atom_type, ij_type, ik_type)

Compute hessian.

__init__(F, G, neighbourhood)

Init with pair & triplet potential + neighbourhood.

band_structure()

Create band-structure object for plotting.

calculate(atoms, properties, system_changes)

Calculate system properties.

calculate_numerical_forces(atoms, d=0.001)

Calculate numerical forces using finite difference.

All atoms will be displaced by +d and -d in all directions.

calculate_numerical_stress(atoms, d=1e-06, voigt=True)

Calculate numerical stress using finite difference.

calculate_properties(atoms, properties)

This method is experimental; currently for internal use.

calculation_required(atoms, properties)
check_state(atoms, tol=1e-15)

Check for any system changes since last calculation.

default_parameters: Dict[str, Any] = {}

Default parameters

property directory: str
discard_results_on_any_change = False

Whether we purge the results following any change in the set() method.

export_properties()
get_atoms()
get_birch_coefficients(atoms)

Compute the Birch coefficients (Effective elastic constants at non-zero stress).

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_born_elastic_constants(atoms)

Compute the Born elastic constants.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_charges(atoms=None)
get_cutoff(atoms)

Return a valid cutoff.

get_default_parameters()
get_dipole_moment(atoms=None)
get_dynamical_matrix(atoms)

Compute dynamical matrix (=mass weighted Hessian).

get_elastic_constants(atoms, cg_parameters={'M': None, 'atol': 1e-05, 'callback': None, 'maxiter': None, 'rtol': 1e-05, 'x0': None})

Compute the elastic constants at zero temperature. These are sum of the born, the non-affine and the stress contribution.

Parameters:

  • atoms (ase.Atoms) – Atomic configuration in a local or global minima.

  • cg_parameters (dict) –

    Dictonary for the conjugate-gradient solver.

    x0: {array, matrix}

    Starting guess for the solution.

    rtol/atol: float, optional

    Tolerances for convergence, norm(residual) <= max(rtol*norm(b), atol).

    maxiter: int

    Maximum number of iterations. Iteration will stop after maxiter steps even if the specified tolerance has not been achieved.

    M: {sparse matrix, dense matrix, LinearOperator}

    Preconditioner for A.

    callback: function

    User-supplied function to call after each iteration.

get_forces(atoms=None)
get_hessian(atoms, format='sparse', divide_by_masses=False)

Calculate the Hessian matrix for a generic many-body potential.

For an atomic configuration with N atoms in d dimensions the hessian matrix is a symmetric, hermitian matrix with a shape of (d*N,d*N). The matrix is in general a sparse matrix, which consists of dense blocks of shape (d,d), which are the mixed second derivatives.

Parameters:

  • atoms (ase.Atoms) – Atomic configuration in a local or global minima.

  • format ("sparse" or "neighbour-list") – Output format of the hessian matrix.

  • divide_by_masses (bool) – if true return the dynamic matrix else hessian matrix

Returns:

  • bsr_matrix – either hessian or dynamic matrix

  • Restrictions

  • ———-

  • This method is currently only implemented for three dimensional systems

get_hessian_from_second_derivative(atoms)

Compute the Hessian matrix from second derivatives.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_magnetic_moment(atoms=None)
get_magnetic_moments(atoms=None)

Calculate magnetic moments projected onto atoms.

get_non_affine_contribution_to_elastic_constants(atoms, eigenvalues=None, eigenvectors=None, pc_parameters=None, cg_parameters={'M': None, 'atol': 1e-05, 'callback': None, 'maxiter': None, 'rtol': 1e-05, 'x0': None})

Compute the correction of non-affine displacements to the elasticity tensor. The computation of the occuring inverse of the Hessian matrix is bypassed by using a cg solver.

If eigenvalues and and eigenvectors are given the inverse of the Hessian can be easily computed.

Parameters:

  • atoms (ase.Atoms) – Atomic configuration in a local or global minima.

  • eigenvalues (array) – Eigenvalues in ascending order obtained by diagonalization of Hessian matrix. If given, use eigenvalues and eigenvectors to compute non-affine contribution.

  • eigenvectors (array) – Eigenvectors corresponding to eigenvalues.

  • cg_parameters (dict) –

    Dictonary for the conjugate-gradient solver.

    x0: {array, matrix}

    Starting guess for the solution.

    rtol/atol: float, optional

    Tolerances for convergence, norm(residual) <= max( rtol*norm(b), atol).

    maxiter: int

    Maximum number of iterations. Iteration will stop after maxiter steps even if the specified tolerance has not been achieved.

    M: {sparse matrix, dense matrix, LinearOperator}

    Preconditioner for A.

    callback: function

    User-supplied function to call after each iteration.

  • pc_parameters (dict) –

    Dictonary for the incomplete LU decomposition of the Hessian.

    A: array_like

    Sparse matrix to factorize.

    drop_tol: float

    Drop tolerance for an incomplete LU decomposition.

    fill_factor: float

    Specifies the fill ratio upper bound.

    drop_rule: str

    Comma-separated string of drop rules to use.

    permc_spec: str

    How to permute the columns of the matrix for sparsity.

    diag_pivot_thresh: float

    Threshold used for a diagonal entry to be an acceptable pivot.

    relax: int

    Expert option for customizing the degree of relaxing supernodes.

    panel_size: int

    Expert option for customizing the panel size.

    options: dict

    Dictionary containing additional expert options to SuperLU.

get_non_affine_forces_from_second_derivative(atoms)

Compute the analytical non-affine forces.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_nonaffine_forces(atoms)

Compute the non-affine forces which result from an affine deformation of atoms.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_potential_energies(atoms=None)
get_potential_energy(atoms=None, force_consistent=False)
get_property(name, atoms=None, allow_calculation=True)

Get the named property.

get_second_derivative(atoms, drda_pc, drdb_pc, i_p=None, j_p=None, r_p=None, r_pc=None)

Calculate the second derivative of the energy with respect to arbitrary variables a and b.

Parameters:

  • atoms (ase.Atoms) – Atomic configuration in a local or global minima.

  • drda_pc/drdb_pc (array_like) – Derivative of atom positions with respect to variable a/b.

  • i_p (array) – First atom index

  • j_p (array) – Second atom index

  • r_p (array) – Absolute distance

  • r_pc (array) – Distance vector

get_stress(atoms=None)
get_stress_contribution_to_elastic_constants(atoms)

Compute the correction to the elastic constants due to non-zero stress in the configuration. Stress term results from working with the Cauchy stress.

Parameters:

atoms (ase.Atoms) – Atomic configuration in a local or global minima.

get_stresses(atoms=None)

the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress

ignored_changes: Set[str] = {}

Properties of Atoms which we ignore for the purposes of cache

implemented_properties: List[str] = ['free_energy', 'energy', 'stress', 'forces', 'hessian', 'born_constants', 'nonaffine_forces', 'birch_coefficients', 'dynamical_matrix', 'elastic_constants']

Properties calculator can handle (energy, forces, …)

property label
name = 'Manybody'
read(label)

Read atoms, parameters and calculated properties from output file.

Read result from self.label file. Raise ReadError if the file is not there. If the file is corrupted or contains an error message from the calculation, a ReadError should also be raised. In case of succes, these attributes must set:

atoms: Atoms object

The state of the atoms from last calculation.

parameters: Parameters object

The parameter dictionary.

results: dict

Calculated properties like energy and forces.

The FileIOCalculator.read() method will typically read atoms and parameters and get the results dict by calling the read_results() method.

classmethod read_atoms(restart, **kwargs)
reset()

Clear all information from old calculation.

set(**kwargs)

Set parameters like set(key1=value1, key2=value2, …).

A dictionary containing the parameters that have been changed is returned.

Subclasses must implement a set() method that will look at the chaneged parameters and decide if a call to reset() is needed. If the changed parameters are harmless, like a change in verbosity, then there is no need to call reset().

The special keyword ‘parameters’ can be used to read parameters from a file.

set_label(label)

Set label and convert label to directory and prefix.

Examples:

  • label=’abc’: (directory=’.’, prefix=’abc’)

  • label=’dir1/abc’: (directory=’dir1’, prefix=’abc’)

  • label=None: (directory=’.’, prefix=None)

todict(skip_default=True)