API Reference

This section provides detailed API documentation for py-electrostatic modules and classes.

Main Module: calculator

class pyelectrostatic.calculator.CompositeCalculator(list_of_calculators: list, *args, **kwargs)

Bases: Calculator

Create a calculator that combines two different calculators.

This calculator adds the energy and forces of two or more different calculators.

calculate(atoms=None, *args, **kwargs)

Calculate the energy and forces of the system.

Parameters:

atoms – The atoms object to calculate.

class pyelectrostatic.calculator.ElectrostaticCalculator(*args, **kwargs)

Bases: Calculator

Calculator for long-range electrostatic interaction.

Long range calculator.

calculate(atoms=None, *args, **kwargs)

The actual function called by the ASE calculator

check_asr(threshold: float = 1e-06) → None

Check if the acoustic sum rule is enforced on the effective charges.

This is very important to properly compute the forces on the structure.

get_longrange_phonons(q_point: ndarray, struct: Structure, convert_from_cc=True) → ndarray

PHONONS

Use the dipole moment to return the nonanalitic phonons. This evaluation is correct in the limit eta -> oo

param q_point:

The q vector at which the dynamical matrix is evaluated. By default accepts cellconstructor units (rad / A) To pass into Bohr^-1 in units of 2pi, use convert_from_cc = False

type q_point:

ndarray

param struct:

The structure used to perform the calculation

type struct:

CC.Structure.Structure

param convert_from_cc:

If true (default) use rad / A (the q points as they are stored into cellconstructor Phonons) Otherwhise, use the default units of this calculator (2pi / Bohr)

type convert_from_cc:

bool

Results

force_constant_matrix :: ndarray(size = (3*nat, 3*nat), dtype = np.complex128)

The force constant matrix at the provided q point. The result is in Ry/Bohr^2

get_supercell_fc(structure: Structure, ase_units=False) → ndarray

SUPERCELL FC MATRIX

Return the force constant matrix of the given supercell structure. It works in the limit eta -> oo

Results

fc_matrixnp.ndarray(size = (3*nat, 3*nat), dtype = np.double)

The force constant matrix in the supercell. It is not divided by the masses. Units are Ry/Bohr if ase_units is false, eV/A otherwise

init(reference_structure: Structure, effective_charges: ndarray, dielectric_tensor: ndarray, unique_atom_element: str | None = None, supercell: tuple[int, int, int] = (1, 1, 1), use_nufft: bool = True) → None

INITIALIZE THE CALCULATOR

Setup the calculator to evaluate energy and forces. The calculator need a reference structure and effective charges of all atoms in the system. These quantities needs to be setup only at the beginnig. The reference structure should match the correct order of atoms that are provided when the calculator is executed.

A supercell can be specified, if the calculator is actually going to be used in a supercell structure from the one provided. In that case, the default order is the same in the provided generate_supercell method from cellconstructor.Structure.Structure. This is the default behaviour of the set_tau subroutine from quantum espresso.

Structure, effective charges and dielectric tensors are copied.

param reference_structure:

The average position of each atom.

type reference_structure:

CC.Structure.Structure

param effective_charges:

The effective charges, it must be a 3-rank tensor where the indices are Z[i, j, k] -> i is the atom index, j is the polarization of the electric field, k is the atomic-cartesian coordinate.

type effective_charges:

ndarray

param dielectric_tensor:

The 3x3 matrix containing the high-frequency static dielectric tensor.

type dielectric_tensor:

ndarray

param supercell:

Optional, if provided, generates automatically the data for the calculation on a supercell.

type supercell:

tuple

param unique_atom_element:

The atomic name of the species used to identify the origin of the structure. There must be just one per cell If None, the first atom is used. TODO: find a better way!

type unique_atom_element:

str

param use_nufft:

If True, use NUFFT-based calculation which scales as O(N²) for fixed cell. If False, use the standard k-point summation which scales as O(N³).

type use_nufft:

bool

init_from_phonons(dynamical_matrix: Phonons, unique_atom_element: str | None = None, use_nufft: bool = False) → None

INITIALIZE THE CALCULATOR

Uses the reference of the dynamical matrix to initialize the phonons. Everything is read from the dynamical matrix, included the supercell.

see init documentation for more details

param - dynamical_matrix:

the dynamical matrix of the system

param - unique_atom_element:

the string of unique atom element in the structure (default: None, the first atom is used)

param - use_nufft:

If True, use NUFFT-based calculation which scales as O(N²) for fixed cell.

type - use_nufft:

bool

init_kpoints()

INITIALIZE THE K POINTS

Define the k points within the cutoff so that

\[\left| \vec k \right| < \frac{C}{\eta}\]

where \(C\) is the cutoff and \(\eta\) is the size of the gaussian charge core.

We store the k vectors in Bohr^-1 to have a consistent units

setup_structure(target_structure: Structure)

Set the effective_charge and reference structure.

pyelectrostatic.calculator.convert_to_cc_structure(item)

Convert any structure into a Cellconstructor Structure.

pyelectrostatic.calculator.is_julia_available()

ElectrostaticCalculator

class pyelectrostatic.calculator.ElectrostaticCalculator(*args, **kwargs)

Bases: Calculator

Calculator for long-range electrostatic interaction.

Long range calculator.

__init__(*args, **kwargs)

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.

calculate(atoms=None, *args, **kwargs)

The actual function called by the ASE calculator

check_asr(threshold: float = 1e-06) → None

Check if the acoustic sum rule is enforced on the effective charges.

This is very important to properly compute the forces on the structure.

get_longrange_phonons(q_point: ndarray, struct: Structure, convert_from_cc=True) → ndarray

PHONONS

Use the dipole moment to return the nonanalitic phonons. This evaluation is correct in the limit eta -> oo

param q_point:

The q vector at which the dynamical matrix is evaluated. By default accepts cellconstructor units (rad / A) To pass into Bohr^-1 in units of 2pi, use convert_from_cc = False

type q_point:

ndarray

param struct:

The structure used to perform the calculation

type struct:

CC.Structure.Structure

param convert_from_cc:

If true (default) use rad / A (the q points as they are stored into cellconstructor Phonons) Otherwhise, use the default units of this calculator (2pi / Bohr)

type convert_from_cc:

bool

Results

force_constant_matrix :: ndarray(size = (3*nat, 3*nat), dtype = np.complex128)

The force constant matrix at the provided q point. The result is in Ry/Bohr^2

get_supercell_fc(structure: Structure, ase_units=False) → ndarray

SUPERCELL FC MATRIX

Return the force constant matrix of the given supercell structure. It works in the limit eta -> oo

Results

fc_matrixnp.ndarray(size = (3*nat, 3*nat), dtype = np.double)

The force constant matrix in the supercell. It is not divided by the masses. Units are Ry/Bohr if ase_units is false, eV/A otherwise

init(reference_structure: Structure, effective_charges: ndarray, dielectric_tensor: ndarray, unique_atom_element: str | None = None, supercell: tuple[int, int, int] = (1, 1, 1), use_nufft: bool = True) → None

INITIALIZE THE CALCULATOR

Setup the calculator to evaluate energy and forces. The calculator need a reference structure and effective charges of all atoms in the system. These quantities needs to be setup only at the beginnig. The reference structure should match the correct order of atoms that are provided when the calculator is executed.

A supercell can be specified, if the calculator is actually going to be used in a supercell structure from the one provided. In that case, the default order is the same in the provided generate_supercell method from cellconstructor.Structure.Structure. This is the default behaviour of the set_tau subroutine from quantum espresso.

Structure, effective charges and dielectric tensors are copied.

param reference_structure:

The average position of each atom.

type reference_structure:

CC.Structure.Structure

param effective_charges:

The effective charges, it must be a 3-rank tensor where the indices are Z[i, j, k] -> i is the atom index, j is the polarization of the electric field, k is the atomic-cartesian coordinate.

type effective_charges:

ndarray

param dielectric_tensor:

The 3x3 matrix containing the high-frequency static dielectric tensor.

type dielectric_tensor:

ndarray

param supercell:

Optional, if provided, generates automatically the data for the calculation on a supercell.

type supercell:

tuple

param unique_atom_element:

The atomic name of the species used to identify the origin of the structure. There must be just one per cell If None, the first atom is used. TODO: find a better way!

type unique_atom_element:

str

param use_nufft:

If True, use NUFFT-based calculation which scales as O(N²) for fixed cell. If False, use the standard k-point summation which scales as O(N³).

type use_nufft:

bool

init_from_phonons(dynamical_matrix: Phonons, unique_atom_element: str | None = None, use_nufft: bool = False) → None

INITIALIZE THE CALCULATOR

Uses the reference of the dynamical matrix to initialize the phonons. Everything is read from the dynamical matrix, included the supercell.

see init documentation for more details

param - dynamical_matrix:

the dynamical matrix of the system

param - unique_atom_element:

the string of unique atom element in the structure (default: None, the first atom is used)

param - use_nufft:

If True, use NUFFT-based calculation which scales as O(N²) for fixed cell.

type - use_nufft:

bool

init_kpoints()

INITIALIZE THE K POINTS

Define the k points within the cutoff so that

\[\left| \vec k \right| < \frac{C}{\eta}\]

where \(C\) is the cutoff and \(\eta\) is the size of the gaussian charge core.

We store the k vectors in Bohr^-1 to have a consistent units

setup_structure(target_structure: Structure)

Set the effective_charge and reference structure.

CompositeCalculator

class pyelectrostatic.calculator.CompositeCalculator(list_of_calculators: list, *args, **kwargs)

Bases: Calculator

Create a calculator that combines two different calculators.

This calculator adds the energy and forces of two or more different calculators.

__init__(list_of_calculators: list, *args, **kwargs)

Initialize the calculator.

Parameters:

list_of_calculators – The list of calculators to combine.

calculate(atoms=None, *args, **kwargs)

Calculate the energy and forces of the system.

Parameters:

atoms – The atoms object to calculate.

Utility Functions

pyelectrostatic.calculator.convert_to_cc_structure(item)

Convert any structure into a Cellconstructor Structure.

pyelectrostatic.calculator.is_julia_available()

Utilities Module

pyelectrostatic.utils.plot_cutoff_convergence(cutoffs, energies, forces, show=True, save_data=None, last_reference=True)

PLOT THE CONVERGENCE OF THE CUTOFF

This is a simple utility that plots in a fancy way the calculation performed by study_cutoff_convergence.

param cutoffs:

The list of the cutoffs values

type cutoffs:

ndarray

param energies:

the list of total energy for each cutoff

type energies:

ndarray

param forces:

The total forces on the structure for each cutoff

type forces:

ndarray

param show:

If true, calls the show function of matplotlib at the end

type show:

bool

param save_data:

Optional: path to a file on which the data are saved for further analysis

type save_data:

string

param last_reference:

If true, subtract the last cutoff as a reference

type last_reference:

bool

Example

>>>   # [initialize the calculator and structure]
>>>   cutoffs = np.linspace(0, 30, 10)
>>>   energies, forces = pyelectrostatic.utils.study_cutoff_convergence(calculator, structure, cutoffs)
>>>   pyelectrostatic.utils.plot_cutoff_convergence(cutoffs, energies, forces)

pyelectrostatic.utils.study_cutoff_convergence(calculator, structure, cutoffs=array([0., 3.33333333, 6.66666667, 10., 13.33333333, 16.66666667, 20., 23.33333333, 26.66666667, 30.]), progress=True)

STUDY CUTOFF CONVERGENCE

This utility function helps to choose a good cutoff for the convergence. You need to pass the calculator, a target structure and a list of cutoffs, we return the total energies for each cutoff and the forces on the atoms.

param calculator:

The long range interaction calculator

type calculator:

pyelectrostatic.calculator.LongRangeInteractions

param structure:

Either a cellconstructor or an ASE crystal structure on which the test is carried.

type structure:

cellconstructor.Structure.Structure or ase.Atoms

param cutoffs:

The list of the cutoffs (in Angstrom). The default value is 10 steps between 0 and 30 A

type cutoffs:

list (or ndarray), optional

param progress:

If true, print in stdout the progress of the calculation

type progress:

bool

Results

energiesndarray(size = len(cutoffs))

The value of the total energy per unit cell for each cutoff value

forcesndarray(size = (len(cutoffs), nat, 3))

The force that acts on each atom for each value of the cutoff

Interface Module

pyelectrostatic.interface.get_forceset_from_phonopy_disp(calculator, disp_file='phonopy_disp.yaml', forceset_file='FORCE_SETS')

Read a phonopy_disp.yalm file, and use the given ASE calculator to write the FORCE_SET file This can be used to interface the code with phonopy for phonon calculation.

Parameters:

• calculator (ASE or cellconstructor calculator.) – The calculator used to compute forces and energies

• disp_file (string) – Path to the file phonopy_disp.yaml that contains info about the displacements.

• forceset_file (string) – Path to the output file on which to write the FORCE_SET file.