API reference

API reference#

Auto-generated signatures and docstrings for the public phono3py Python API. For a tutorial-style guide, see Phono3py API.

Top-level functions#

phono3py.load

Create a Phono3py instance from parameters and/or input files.

phono3py.load(phono3py_yaml=None, supercell_matrix=None, primitive_matrix='auto', phonon_supercell_matrix=None, is_nac=True, calculator=None, unitcell=None, supercell=None, nac_params=None, unitcell_filename=None, supercell_filename=None, born_filename=None, forces_fc3_filename=None, forces_fc2_filename=None, fc3_filename=None, fc2_filename=None, fc_calculator=None, fc_calculator_options=None, factor=None, produce_fc=True, is_symmetry=True, symmetrize_fc=True, is_mesh_symmetry=True, is_compact_fc=True, use_pypolymlp=False, mlp_params=None, use_grg=False, make_r0_average=True, symprec=1e-05, log_level=0, lang='Rust')[source]#

Create a Phono3py instance from parameters and/or input files.

A "phono3py_yaml"-like file is parsed unless crystal structure information is given through unitcell_filename, supercell_filename, unitcell (PhonopyAtoms-like), or supercell (PhonopyAtoms-like). Even when a "phono3py_yaml"- like file is parsed, parameters other than the crystal structure can be overwritten by keyword arguments.

"fc3.hdf5" is read if it is found in the current directory. Otherwise, if "FORCES_FC3" and "phono3py_disp.yaml" are found, they are read and fc3 (and fc2) are produced. Similarly, "fc2.hdf5" is read if found; otherwise "FORCES_FC2" plus "phono3py_disp.yaml" are used to produce fc2.

When forces_fc3_filename / forces_fc2_filename are not given, "FORCES_FC3" and "FORCES_FC2" are searched in the current directory. With type-1 "FORCES_FC3" (or "FORCES_FC2"), "phono3py_disp.yaml" is also required.

Crystal structure – in order of priority:

unitcell_filename  (with supercell_matrix)
supercell_filename
unitcell           (with supercell_matrix)
supercell
phono3py_yaml-like

Force sets or force constants (optional) – in order of priority:

1. fc3_filename       (fc2_filename)
2. forces_fc3_filename (forces_fc2_filename); for type-1 format
   phono3py_disp.yaml must also be supplied.
3. fc3.hdf5 and fc2.hdf5 in the current directory.
4. FORCES_FC3 and FORCES_FC2 in the current directory.
   FORCES_FC2 is optional; for type-1 format
   phono3py_disp.yaml is also searched. When FORCES_FC2 is
   missing, FORCES_FC3 is used to create fc2.

Parameters for non-analytical term correction (NAC) (optional) – in order of priority:

born_filename
nac_params
phono3py_yaml_like.nac_params when present and is_nac=True
BORN in the current directory when is_nac=True

Parameters:

phono3py_yaml (str or os.PathLike, optional) – Path to a "phono3py.yaml"-like file. When given, the contents are parsed. Default is None.
supercell_matrix (array_like, optional) – Transformation matrix to the supercell from the unit cell. shape=(3,) or (3, 3), dtype=int. A 1D array is treated as the diagonal of a 3x3 matrix. Default is the identity matrix.
primitive_matrix (str or array_like, optional) – Transformation matrix to the primitive cell from the unit cell. Default is "auto", which guesses the matrix from crystal symmetry (centring types "F", "I", "A", "C", "R", or primitive "P"). To use the unit cell as the primitive cell (identity transformation), pass "P". None is treated the same as "auto". When a centring symbol is given, the primitive matrix defined at https://spglib.github.io/spglib/definition.html is used. When a "phono3py.yaml"-like file is loaded and contains a primitive_matrix, that value takes priority over the default "auto".
phonon_supercell_matrix (array_like, optional) – Supercell matrix used for fc2 when a different dimension is desired from the one used for fc3. Same format as supercell_matrix. Default is None, which uses supercell_matrix for fc2. Only valid when unitcell or unitcell_filename is given.
is_nac (bool, optional) – When True, look for "BORN". When False, NAC is turned off. Default is True.
calculator (str, optional) – Calculator name ("vasp", "qe", …) used to switch the set of physical units when parsing calculator input/output files. Default is None, which is equivalent to "vasp".
unitcell (PhonopyAtoms, optional) – Input unit cell. Default is None.
supercell (PhonopyAtoms, optional) – Input supercell. When given, primitive_matrix defaults to "auto" (can be overwritten) and supercell_matrix is ignored. Default is None.

nac_params (dict, optional) –

Parameters for non-analytical term correction:

'born':       Born effective charges,
              shape=(atoms in primitive, 3, 3),
              dtype=float.
'dielectric': dielectric constant matrix,
              shape=(3, 3), dtype=float.
'factor':     unit conversion factor (float).

Default is None.

unitcell_filename (str or os.PathLike, optional) – Path to a unit-cell file. Default is None.
supercell_filename (str or os.PathLike, optional) – Path to a supercell file. When given, supercell_matrix is ignored. Default is None.
born_filename (str or os.PathLike, optional) – Path to a "BORN" file containing NAC parameters. Default is None.
forces_fc3_filename (str, os.PathLike, or sequence, optional) – Either a two-element sequence of paths corresponding to ("FORCES_FC3", "phono3py_disp.yaml") for the type-1 format, or a single path to "FORCES_FC3" for the type-2 format. Default is None.
forces_fc2_filename (str, os.PathLike, or sequence, optional) – Same as forces_fc3_filename but for fc2. Default is None.
fc3_filename (str or os.PathLike, optional) – Path to a file storing fc3 (e.g. "fc3.hdf5"). Default is None.
fc2_filename (str or os.PathLike, optional) – Path to a file storing fc2 (e.g. "fc2.hdf5"). Default is None.
fc_calculator (str, optional) – Force-constants calculator. One of None, "traditional", "symfc", or "alm". Default is None (equivalent to "traditional").
fc_calculator_options (str, optional) – Options string forwarded to the chosen calculator. Use "<fc2_opts>|<fc3_opts>" to set separate options for fc2 and fc3. For "alm", each parameter is split by "," and each key/value pair is written as "key = value". Default is None.
factor (float, optional) – Deprecated. Default is None.
produce_fc (bool, optional) – Compute force constants from displacements and forces. When False, only the dataset is set up. Default is True.
is_symmetry (bool, optional) – Use crystal symmetry (beyond lattice translation). Default is True.
symmetrize_fc (bool, optional) – Symmetrize the force constants after producing them. Applied per fc order (fc2 / fc3): only effective when the corresponding calculator (after "|" splitting of fc_calculator) is None or "traditional". fc2 or fc3 produced by "symfc" or "alm" is already symmetrized by the solver. Default is True.
is_mesh_symmetry (bool, optional) – Use reciprocal-mesh symmetry. Default is True.

is_compact_fc (bool, optional) –

Use compact force-constant shape:

fc3 True:  (primitive, supercell, supercell, 3, 3, 3)
fc3 False: (supercell, supercell, supercell, 3, 3, 3)
fc2 True:  (primitive, supercell, 3, 3)
fc2 False: (supercell, supercell, 3, 3)

Default is True.

use_pypolymlp (bool, optional) – Use pypolymlp to generate force constants. Default is False.
mlp_params (dict, optional) – Parameters for the machine-learning potential. Default is None.
use_grg (bool, optional) – Use a generalized regular grid (GRG). Default is False.
make_r0_average (bool, optional) – Average the fc3 real-to-reciprocal-space transformation over the three atoms in each triplet when True (default). When False, only the first atom is used. False is provided for rough backward compatibility with v2.x results.
symprec (float, optional) – Tolerance used to find crystal symmetry. Default is 1e-5.
log_level (int, optional) – Verbosity control. Default is 0.
lang (Literal["C", "Rust"], optional) – Backend implementation for compute-heavy kernels. "C" uses the existing C extension; "Rust" selects the experimental phonors backend. Default is "Rust".

Return type:

Phono3py

`Phono3py` class#

class phono3py.Phono3py(unitcell, supercell_matrix=None, primitive_matrix='auto', phonon_supercell_matrix=None, cutoff_frequency=0.0001, frequency_factor_to_THz=None, is_symmetry=True, is_mesh_symmetry=True, use_grg=False, SNF_coordinates='reciprocal', make_r0_average=True, symprec=1e-05, calculator=None, log_level=0, lang='Rust')[source]#

Bases: object

Phono3py main API.

A Phono3py instance is created from a unit cell, a supercell matrix, and a primitive matrix. It manages displacement generation for fc3 (and optionally fc2 when a separate phonon_supercell_matrix is given), construction of second- and third-order force constants from displacement-force datasets, phonon-phonon interaction calculation on a reciprocal-space grid, and derived quantities such as the imaginary and real parts of the phonon self-energy, the spectral function, the joint density of states, and the lattice thermal conductivity (RTA, direct solution of the linearized phonon Boltzmann equation, and the Wigner transport equation).

Most attributes are exposed as @property accessors documented individually below. See Phono3py API for a tutorial-style overview of the typical workflow.

Examples

>>> import numpy as np
>>> from phono3py import Phono3py
>>> from phonopy.structure.atoms import PhonopyAtoms
>>> a = 3.111
>>> c = 4.978
>>> x = 1.0 / 3
>>> unitcell = PhonopyAtoms(
...     symbols=["Al", "Al", "N", "N"],
...     cell=[[a, 0, 0], [-a / 2, a * np.sqrt(3) / 2, 0], [0, 0, c]],
...     scaled_positions=[
...         [x, 2 * x, 0],
...         [2 * x, x, 0.5],
...         [x, 2 * x, 0.1181],
...         [2 * x, x, 0.6181],
...     ],
... )
>>> ph3 = Phono3py(
...     unitcell, supercell_matrix=[3, 3, 2], primitive_matrix="auto"
... )
>>> ph3.generate_displacements()
>>> # Obtain forces by running an external calculator on
>>> # ph3.supercells_with_displacements, then:
>>> # ph3.forces = sets_of_forces
>>> # ph3.produce_fc3()
>>> # ph3.mesh_numbers = 30
>>> # ph3.init_phph_interaction()
>>> # ph3.run_thermal_conductivity(temperatures=range(0, 1001, 10))

Parameters:

unitcell (PhonopyAtoms)
supercell_matrix (Sequence[int] | Sequence[Sequence[int]] | NDArray[np.int64] | None)
primitive_matrix (Literal['P', 'F', 'I', 'A', 'C', 'R', 'auto'] | Sequence[Sequence[float]] | NDArray[np.double] | None)
phonon_supercell_matrix (Sequence[int] | Sequence[Sequence[int]] | NDArray[np.int64] | None)
cutoff_frequency (float)
frequency_factor_to_THz (float | None)
is_symmetry (bool)
is_mesh_symmetry (bool)
use_grg (bool)
SNF_coordinates (Literal['reciprocal', 'direct'])
make_r0_average (bool)
symprec (float)
calculator (str | None)
log_level (int)
lang (Literal['C', 'Rust'])

property version: str#: Return phono3py release version number.

property calculator: str | None#: Return calculator name such as 'vasp', 'qe', etc.

property lang: Literal['C', 'Rust']#

Return the selected backend implementation.

"C" uses the existing C extension; "Rust" selects the experimental phonors backend.

property fc3: ndarray[tuple[Any, ...], dtype[float64]] | None#

Setter and getter of third-order force constants (fc3).

shape=(s, s, s, 3, 3, 3) (full) or (p, s, s, 3, 3, 3) (compact), where s and p are the numbers of atoms in the supercell and the primitive cell. dtype='double', order='C'.

property fc3_nonzero_indices: ndarray[tuple[Any, ...], dtype[int8]] | None#

Setter and getter of the non-zero element mask of fc3.

Boolean mask of atom-triplet indices whose fc3 elements are kept non-zero. This is produced by symfc when a cutoff distance is specified; None otherwise. shape=(s, s, s) or (p, s, s) matching the shape of fc3. dtype='byte', order='C'.

property fc3_cutoff: float | None#

Return the fc3 cutoff distance in Angstroms.

Only available when fc3 was computed with symfc and a cutoff was specified; None otherwise.

property fc2: ndarray[tuple[Any, ...], dtype[float64]] | None#

Setter and getter of second-order force constants (fc2).

shape=(s, s, 3, 3) (full) or (p, s, 3, 3) (compact), where s and p are the numbers of atoms in the supercell and the primitive cell. dtype='double', order='C'.

property fc2_cutoff: float | None#

Return the fc2 cutoff distance in Angstroms.

Only available when fc2 was computed with symfc and a cutoff was specified; None otherwise.

property force_constants: ndarray[tuple[Any, ...], dtype[float64]] | None#: Return fc2. Phonopy-compatible alias for fc2.

property sigmas: list[float | None]#

Setter and getter of smearing widths used for delta functions.

Each element is either a Gaussian standard deviation (in the same unit as phonon frequencies, typically THz) or None. A None entry switches that calculation to the linear tetrahedron method instead of Gaussian smearing.

property sigma_cutoff: float | None#

Setter and getter of the smearing cutoff width.

Given as a multiple of the Gaussian standard deviation. For example, 5 truncates the tail at 5 sigma. None disables truncation.

property nac_params: dict[str, Any] | None#

Setter and getter of parameters for non-analytical term correction.

The dict has the following keys:

'born':       ndarray, Born effective charges,
              shape=(atoms in primitive, 3, 3),
              dtype='double', order='C'.
'factor':     float, unit conversion factor.
'dielectric': ndarray, dielectric constant tensor,
              shape=(3, 3), dtype='double', order='C'.

Unlike the BORN file, Born effective charges of all atoms in the primitive cell must be supplied (not just the symmetrically independent ones).

property dynamical_matrix: DynamicalMatrix | None#: Return the DynamicalMatrix instance (not the matrix itself).

property primitive: Primitive#: Return primitive cell.

property unitcell: PhonopyAtoms#: Return input unit cell.

property supercell: Supercell#: Return supercell for fc3.

property phonon_supercell: Supercell#: Return supercell for fc2.

property phonon_primitive: Primitive#

Return primitive cell for fc2.

This represents the same primitive cell as primitive, but is constructed from the fc2 supercell and may therefore not be numerically identical bit-for-bit.

property symmetry: Symmetry#: Return symmetry of the supercell.

property primitive_symmetry: Symmetry#: Return symmetry of the primitive cell.

property phonon_supercell_symmetry: Symmetry#: Return symmetry of the fc2 supercell (phonon_supercell).

property supercell_matrix: ndarray[tuple[Any, ...], dtype[int64]]#

Return transformation matrix to the supercell from the unit cell.

shape=(3, 3), dtype='int64', order='C'.

property phonon_supercell_matrix: ndarray[tuple[Any, ...], dtype[int64]] | None#

Return transformation matrix to the fc2 supercell from the unit cell.

shape=(3, 3), dtype='int64', order='C'. None when the same supercell as fc3 is used.

property primitive_matrix: ndarray[tuple[Any, ...], dtype[float64]] | None#

Return transformation matrix to the primitive cell from the unit cell.

shape=(3, 3), dtype='double', order='C'.

property unit_conversion_factor: float#

Return phonon frequency unit conversion factor.

This factor converts sqrt(<force> / <distance> / <AMU>) / 2pi / 1e12 to the chosen phonon frequency unit. The default value converts to THz for displacements in Angstroms and forces in eV/Angstrom (i.e. the VASP default).

property dataset: Fc3Type1DisplacementDataset | Type2DisplacementDataset | None#

Setter and getter of the fc3 displacement-force dataset.

Dataset containing displacements in supercells, and optionally forces and supercell energies. The format is one of two types.

Type 1. Pairs of atomic displacements per supercell (for fc3):

{'natom': number of atoms in supercell,
 'first_atoms': [
   {'number': atom index of first displaced atom,
    'displacement': displacement in Cartesian coordinates,
    'forces': forces on atoms in supercell,
    'id': displacement id (1, 2, ..., n_first_atoms),
    'second_atoms': [
      {'number': atom index of second displaced atom,
       'displacement': displacement in Cartesian coordinates,
       'forces': forces on atoms in supercell,
       'supercell_energy': energy of supercell,
       'pair_distance': distance between paired atoms,
       'included': bool flag (with cutoff_pair_distance,
           whether this pair is used to compute fc3),
       'id': displacement id (n_first_atoms + 1, ...)},
      ...
    ]},
   ...
 ]}

Type 2. All atomic displacements in each supercell:

{'displacements':      ndarray, dtype='double', order='C',
                       shape=(supercells, atoms in supercell, 3),
 'forces':             ndarray, dtype='double', order='C',
                       shape=(supercells, atoms in supercell, 3),
 'supercell_energies': ndarray, dtype='double',
                       shape=(supercells,)}

In type 2, displacements and forces may be given as any array-like that can be reshaped to (supercells, atoms in supercell, 3).

For type 1, duplicates and cutoff_distance may also be present when pair displacements are generated; duplicates gives duplicated supercell ids as pairs.

property phonon_dataset: Type1DisplacementDataset | Type2DisplacementDataset | None#

Setter and getter of the fc2 displacement-force dataset.

Dataset containing displacements in the fc2 supercells, and optionally forces and supercell energies. The format is one of two types.

Type 1. One atomic displacement per supercell:

{'natom': number of atoms in supercell,
 'first_atoms': [
   {'number': atom index of displaced atom,
    'displacement': displacement in Cartesian coordinates,
    'forces': forces on atoms in supercell,
    'supercell_energy': energy of supercell},
   ...
 ]}

Type 2. All atomic displacements in each supercell:

{'displacements':      ndarray, dtype='double', order='C',
                       shape=(supercells, atoms in supercell, 3),
 'forces':             ndarray, dtype='double', order='C',
                       shape=(supercells, atoms in supercell, 3),
 'supercell_energies': ndarray, dtype='double',
                       shape=(supercells,)}

In type 2, displacements and forces may be given as any array-like that can be reshaped to (supercells, atoms in supercell, 3).

property mlp_dataset: Type2DisplacementDataset | None#

Setter and getter of the displacement-force dataset used to train an MLP.

Uses the same supercell as the fc3 displacement-force dataset. Only the type-2 format is supported; the dict must contain the keys "displacements", "forces", and "supercell_energies".

property phonon_mlp_dataset: Type2DisplacementDataset | None#

Setter and getter of the phonon MLP displacement-force dataset.

Uses the same supercell as the fc2 displacement-force dataset. Only the type-2 format is supported; the dict must contain the keys "displacements", "forces", and "supercell_energies".

property mlp: PhonopyMLP | None#: Setter and getter of the PhonopyMLP machine-learning potential.

property phonon_mlp: PhonopyMLP | None#: Return the PhonopyMLP instance used to predict fc2 forces.

property band_indices: Sequence[ndarray[tuple[Any, ...], dtype[int64]]]#

Setter and getter of band indices.

List of integer-index arrays selecting the bands at which ph-ph-interaction-derived properties are computed. Each entry is an NDArray[np.int64].

property masses: ndarray[tuple[Any, ...], dtype[float64]]#

Setter and getter of atomic masses of the primitive cell.

shape=(atoms in primitive,), dtype='double'. Setting propagates the new masses to the unit cell, supercell, phonon primitive cell, and phonon supercell so that the cells stay consistent.

property supercells_with_displacements: list[PhonopyAtoms | None]#

Return the fc3 supercells with displacements applied.

Built from the displacement dataset generated by generate_displacements(). Pair displacements that fall outside the cutoff distance appear as None.

property phonon_supercells_with_displacements: list[PhonopyAtoms]#

Return the fc2 supercells with displacements applied.

Built from the phonon displacement dataset generated by generate_displacements() or generate_fc2_displacements().

property mesh_numbers: ndarray[tuple[Any, ...], dtype[int64]] | None#

Setter and getter of the reciprocal-space sampling mesh.

The getter returns the diagonal of the grid-generating matrix (BZGrid.D_diag), shape=(3,), dtype='int64', or None if no grid has been set. The setter accepts a scalar distance-like value, a length-3 sequence of integers, or a (3, 3) integer matrix; see Phono3py API for details.

property thermal_conductivity: RTACalculator | LBTECalculator | None#

Return the thermal-conductivity calculator instance.

Populated by run_thermal_conductivity(). RTACalculator for the relaxation-time approximation (is_LBTE=False), LBTECalculator for the direct solution of the linearized Boltzmann equation or the Wigner transport equation (is_LBTE=True), or None before the calculation has run.

property displacements: ndarray[tuple[Any, ...], dtype[float64]]#

Setter and getter of displacements in the fc3 supercells.

See the docstring of dataset for the type-1 and type-2 formats. The getter always returns a type-2-style ndarray (it synthesizes one when the underlying dataset is type-1) with shape=(supercells, atoms in supercell, 3), dtype='double', order='C'.

The setter accepts an array-like of the same shape and stores it as a type-2 dataset. Setting raises RuntimeError when the existing dataset is type-1.

property forces: ndarray[tuple[Any, ...], dtype[float64]] | None#

Setter and getter of supercell forces in the fc3 dataset.

shape=(supercells with displacements, atoms in supercell, 3), dtype='double', order='C'.

The order of supercells must match the order in supercells_with_displacements. The setter accepts any array-like with the same shape.

property supercell_energies: ndarray[tuple[Any, ...], dtype[float64]] | None#

Setter and getter of supercell energies in the fc3 dataset.

shape=(supercells with displacements,), dtype='double'.

The order of supercells must match the order in supercells_with_displacements. The setter accepts any array-like with the same shape.

property phonon_displacements: ndarray[tuple[Any, ...], dtype[float64]]#

Setter and getter of displacements in the fc2 supercells.

See the docstring of phonon_dataset for the type-1 and type-2 formats. The getter always returns a type-2-style ndarray (it synthesizes one when the underlying dataset is type-1) with shape=(supercells, atoms in supercell, 3), dtype='double', order='C'.

The setter accepts an array-like of the same shape and stores it as a type-2 dataset. Setting raises RuntimeError when the existing dataset is type-1 or when phonon_supercell_matrix is not set.

property phonon_forces: ndarray[tuple[Any, ...], dtype[float64]] | None#

Setter and getter of supercell forces in the fc2 dataset.

shape=(supercells with displacements, atoms in supercell, 3), dtype='double', order='C'.

The order of supercells must match the order in phonon_supercells_with_displacements. The setter accepts any array-like with the same shape.

property phonon_supercell_energies: ndarray[tuple[Any, ...], dtype[float64]] | None#

Setter and getter of supercell energies in the fc2 dataset.

shape=(supercells with displacements,), dtype='double'.

The order of supercells must match the order in phonon_supercells_with_displacements. The setter accepts any array-like with the same shape.

property phph_interaction: Interaction | None#

Return the ph-ph Interaction instance.

Created by init_phph_interaction(). None before initialization.

property detailed_gammas: list[ndarray[tuple[Any, ...], dtype[float64]]] | None#

Return scattering-event-resolved imaginary self-energies.

Populated by run_imag_self_energy(..., keep_gamma_detail=True)(). Returns None when keep_gamma_detail was not requested. Raises RuntimeError if run_imag_self_energy() has not been called.

property grid: BZGrid | None#

Return the Brillouin-zone grid (BZGrid) used for the calculation.

None before mesh_numbers has been set.

init_phph_interaction(nac_q_direction=None, constant_averaged_interaction=None, frequency_scale_factor=None, symmetrize_fc3q=False, lapack_zheev_uplo='L', openmp_per_triplets=None)[source]#

Initialize ph-ph interaction calculation.

This method creates an instance of Interaction class, which is necessary to run ph-ph interaction calculation. The input data such as grids, force constants, etc, are stored to be ready for the calculation.

Note

fc3 and fc2, and optionally nac_params have to be set before calling this method. fc3 and fc2 can be made either from sets of forces and displacements of supercells or be set simply via attributes.

Parameters:

nac_q_direction (array_like, optional) – Direction of q-vector watching from Gamma point used for non-analytical term correction. This is effective only at q=0 (physically q->0). The direction is given in crystallographic (fractional) coordinates. shape=(3,), dtype=’double’. Default value is None, which means this feature is not used.
constant_averaged_interaction (float, optional) – Ph-ph interaction strength array is replaced by a scalar value. Default is None, which means this feature is not used.
frequency_scale_factor (float, optional) – All phonon frequencies are scaled by this value. Default is None, which means phonon frequencies are not scaled.
symmetrize_fc3q (bool, optional) – fc3 in phonon space is symmetrized by permutation symmetry. Default is False.
lapack_zheev_uplo (str, optional) – ‘L’ or ‘U’. Default is ‘L’. This is passed to LAPACK zheev used for phonon solver.
openmp_per_triplets (bool or None, optional, default is None) – Normally this parameter should not be touched. When True, ph-ph interaction strength calculation runs with OpenMP distribution over triplets, and over bands when False. None will choose one of them automatically.

Return type:

None

set_phonon_data(frequencies, eigenvectors, grid_address)[source]#

Set phonon frequencies and eigenvectors in Interaction instance.

Harmonic phonon information is stored in Interaction instance. For example, this information store in a file is read and passed to Phono3py instance by using this method. The grid_address is used for the consistency check.

Parameters:

frequencies (array_like) – Phonon frequencies. shape=(num_grid_points, num_band), dtype=’double’, order=’C’
eigenvectors (array_like) – Phonon eigenvectors shape=(num_grid_points, num_band, num_band) dtype=’cdouble’, order=’C’
grid_address (array_like) – Grid point addresses by integers. The first dimension may not be prod(mesh) because it includes Brillouin zone boundary. The detail is found in the docstring of phono3py.phonon3.triplets.get_triplets_at_q. shape=(num_grid_points, 3), dtype=int

Return type:

None

get_phonon_data()[source]#

Return phonon frequencies, eigenvectors, and grid addresses.

Grid addresses give the q-point location with respect to the reciprocal basis vectors by integers, with:

q_points = grid_address / np.array(mesh, dtype='double')

Returns:

frequencies (ndarray) – shape=(num_grid_points, num_band), dtype='double', order='C'.
eigenvectors (ndarray) – shape=(num_grid_points, num_band, num_band), dtype='cdouble', order='C'.
grid_address (ndarray) – Integer grid-point addresses (the first dimension may exceed prod(mesh) because BZ-boundary points are included). shape=(num_grid_points, 3), dtype=int.

Raises:

RuntimeError – When init_phph_interaction() has not been called.

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[complex128]], ndarray[tuple[Any, …], dtype[int64]]]

See also

set_phonon_data

run_phonon_solver(grid_points=None)[source]#

Run harmonic phonon calculation on grid points.

Parameters:: grid_points (array_like or None, optional) – A list of grid point indices of Phono3py.grid.addresses. Specifying None runs all phonons on the grid points unless those phonons were already calculated. Normally phonons at [0, 0, 0] point is already calculated before calling this method. Phonon calculations are performed automatically when needed internally for ph-ph calculation. Therefore calling this method is not necessary in most cases. The phonon results are obtained by Phono3py.get_phonon_data().
Return type:: None

generate_displacements(distance=None, cutoff_pair_distance=None, is_plusminus='auto', is_diagonal=True, number_of_snapshots=None, random_seed=None, max_distance=None, number_estimation_factor=None)[source]#

Generate the fc3 displacement dataset in the supercell.

Two modes are supported depending on whether number_of_snapshots is given.

Systematic mode (number_of_snapshots is None): single and pair atomic displacements are generated using crystal symmetry. For fc3 two atoms are displaced per configuration. The first displacement is taken in the perfect supercell along its basis vectors – this keeps more symmetry intact, which typically reduces the number of second displacements needed. The second displacement is then taken in the once-displaced supercell.

Random mode (number_of_snapshots is an int or "auto"): the requested number of supercells with random atomic displacements is generated. When max_distance is given, displacements use random directions and random distances drawn uniformly from [distance, max_distance]; otherwise all atoms are displaced by the same Euclidean distance equal to distance.

Note

When phonon_supercell_matrix is not given, fc2 is computed from the same displacements as fc3. When it is given, fc2 displacements in the phonon supercell are generated separately (unless they already exist). To control fc2 displacements independently, call generate_fc2_displacements().

Parameters:

distance (float, optional) – Constant displacement Euclidean distance in Angstroms. Default is None, which means 0.03. In random- direction-random-distance mode this value also acts as the minimum distance: sampled distances smaller than this are clamped to it.
cutoff_pair_distance (float, optional) – Cutoff Euclidean distance (in Angstroms) used to drop pair displacements that are too far apart from the fc3 calculation. Default is None (no cutoff).
is_plusminus (bool or "auto", optional) – With True, atoms are displaced in both positive and negative directions. With False, only one direction. With "auto" (default), both directions are used unless they are symmetrically equivalent, in which case only one is kept.
is_diagonal (bool, optional) – With True (default), second displacements may be chosen off-axis if doing so reduces the displacement count. With False, second displacements are taken strictly along the supercell basis vectors.
number_of_snapshots (int, "auto", or None, optional) – Number of supercell snapshots with random displacements. With "auto", the minimum required number is estimated using symfc and then multiplied by number_estimation_factor. Default is None (systematic mode).
random_seed (int or None, optional) – Random seed for random displacement generation. Default is None.
max_distance (float or None, optional) – When specified, displacements use random direction and random distance with distance as the lower bound and max_distance as the upper bound of a uniform distribution. Default is None.
number_estimation_factor (float, optional) – Multiplier applied to the symfc estimate when number_of_snapshots="auto". Default is None, which uses 8 when max_distance is given and 4 otherwise.

Return type:

None

generate_fc2_displacements(distance=None, is_plusminus='auto', is_diagonal=False, number_of_snapshots=None, random_seed=None, max_distance=None)[source]#

Generate the fc2 displacement dataset in the phonon supercell.

Two modes are supported. In systematic mode (default), single atomic displacements in the phonon supercell are generated using crystal symmetry. In random mode (when number_of_snapshots is given), the requested number of supercells with random displacements is generated. Calling this method clears any cached fc2 supercells with displacements.

Note

is_diagonal=False is the default so that the fc2 first-displacement direction stays consistent with the first-displacement direction used by the fc3 pair generator.

Parameters:

distance (float, optional) – Constant displacement Euclidean distance in Angstroms. Default is None, which means 0.03. In random- direction-random-distance mode this value also acts as the minimum distance: sampled distances smaller than this are clamped to it.
is_plusminus (bool or "auto", optional) – With True, atoms are displaced in both positive and negative directions. With False, only one direction. With "auto" (default), both directions are used unless they are symmetrically equivalent, in which case only one is kept.
is_diagonal (bool, optional) – With False (default), displacements are taken strictly along the supercell basis vectors. With True, off-axis directions may be chosen if doing so reduces the displacement count.
number_of_snapshots (int, "auto", or None, optional) – Number of supercell snapshots with random displacements. With "auto", the minimum required number is estimated using symfc and then doubled. Default is None (systematic mode).
random_seed (int or None, optional) – Random seed for random displacement generation. Default is None.
max_distance (float or None, optional) – When specified, displacements use random direction and random distance with distance as the lower bound and max_distance as the upper bound of a uniform distribution. Default is None.

Return type:

None

produce_fc3(symmetrize_fc3r=None, is_compact_fc=True, fc_calculator=None, fc_calculator_options=None, use_symfc_projector=None)[source]#

Calculate fc3 (and optionally fc2) from displacements and forces.

The solver is chosen by fc_calculator:

None (default) or "traditional": built-in finite-difference solver. The returned fc3 is not symmetrized; to enforce translational and permutation invariance, call symmetrize_fc3() afterwards (and symmetrize_fc2() when applicable).
"symfc": symfc solver, which returns symmetrized force constants in one shot. When a cutoff distance is configured via fc_calculator_options, it is captured into fc3_cutoff (and fc2_cutoff when fc2 is produced here), and the boolean mask of non-zero atomic triplets is captured into fc3_nonzero_indices.
"alm": ALM solver, which handles symmetrization internally.

When phonon_supercell_matrix is not set, fc2 is produced alongside fc3 and stored in fc2. When phonon_supercell_matrix is set, fc2 is not populated here – call produce_fc2() to compute fc2 in the larger phonon supercell.

Parameters:

symmetrize_fc3r (bool, optional) – Deprecated. Passing any value emits a DeprecationWarning. With the traditional solver, call symmetrize_fc3() (and symmetrize_fc2() when applicable) after produce_fc3() instead. Default is None.

is_compact_fc (bool, optional) –

fc3 shape:

True:  (primitive, supercell, supercell, 3, 3, 3)
False: (supercell, supercell, supercell, 3, 3, 3)

Default is True.

fc_calculator (str, optional) – Force-constants calculator. One of None, "traditional", "symfc", or "alm". Default is None (equivalent to "traditional").
fc_calculator_options (str, optional) – Options string forwarded to the chosen calculator. Use "<fc2_opts>|<fc3_opts>" to set separate options for fc2 and fc3; without "|" the same options apply to both. For example, "cutoff=4|cutoff=3" sets cutoff 4 for fc2 and 3 for fc3.
use_symfc_projector (bool, optional) – Deprecated. Passing any value emits a DeprecationWarning. Call symmetrize_fc3(use_symfc_projector=True) after produce_fc3() instead. Default is None.

Return type:

None

symmetrize_fc3(use_symfc_projector=False, options=None)[source]#

Symmetrize fc3 by symfc projector or the traditional approach.

Parameters:

use_symfc_projector (bool, optional) – If True, symmetrize force constants with the symfc projector instead of the traditional approach.

options (str or None, optional) –

Options string. Accepted values depend on the backend:

symfc projector:
    "use_mkl=true"  call sparse_dot_mkl
                    (requires sparse_dot_mkl to be
                    installed).
traditional:
    "level=N"       apply translational and permutation
                    symmetries alternately N times.
                    Default level is 3.

Return type:

None

produce_fc2(symmetrize_fc2=None, is_compact_fc=True, fc_calculator=None, fc_calculator_options=None, use_symfc_projector=None)[source]#

Calculate fc2 from displacements and forces.

Uses the phonon supercell (equal to the fc3 supercell when phonon_supercell_matrix is not set). Forces are taken from phonon_dataset when present, otherwise from dataset. The solver is chosen by fc_calculator:

None (default) or "traditional": built-in finite-difference solver. The returned fc2 is not symmetrized; to enforce translational and permutation invariance, call symmetrize_fc2() afterwards.
"symfc": symfc solver, which returns symmetrized force constants in one shot. When a cutoff distance is configured via fc_calculator_options, it is captured into fc2_cutoff.
"alm": ALM solver, which handles symmetrization internally.

Parameters:

symmetrize_fc2 (bool, optional) – Deprecated. Passing any value emits a DeprecationWarning. With the traditional solver, call symmetrize_fc2() after produce_fc2() instead. Default is None.

is_compact_fc (bool, optional) –

fc2 shape:

True:  (primitive, supercell, 3, 3)
False: (supercell, supercell, 3, 3)

Default is True.

fc_calculator (str or None, optional) – Force-constants calculator. One of None, "traditional", "symfc", or "alm". Default is None (equivalent to "traditional").
fc_calculator_options (str or None, optional) – Options string forwarded to the chosen calculator.
use_symfc_projector (bool, optional) – Deprecated. Passing any value emits a DeprecationWarning. Call symmetrize_fc2(use_symfc_projector=True) after produce_fc2() instead. Default is None.

Return type:

None

symmetrize_fc2(use_symfc_projector=False, options=None)[source]#

Symmetrize fc2 by symfc projector or the traditional approach.

Parameters:

use_symfc_projector (bool, optional) – If True, symmetrize force constants with the symfc projector instead of the traditional approach.

options (str or None, optional) –

Options string. Accepted values depend on the backend:

symfc projector:
    "use_mkl=true"  call sparse_dot_mkl
                    (requires sparse_dot_mkl to be
                    installed).
traditional:
    "level=N"       apply translational and permutation
                    symmetries alternately N times.
                    Default level is 3.

Return type:

None

cutoff_fc3_by_zero(cutoff_distance, fc3=None)[source]#

Set zero to fc3 elements out of cutoff distance.

Note

fc3 is overwritten.

Parameters:

cutoff_distance (float) – After creating force constants, fc elements where any pair distance in atom triplets larger than cutoff_distance are set zero.
fc3 (ndarray[tuple[Any, ...], dtype[float64]] | None)

Return type:

None

set_permutation_symmetry()[source]#

Enforce permutation symmetry to fc2 and fc3.

Return type:: None

set_translational_invariance()[source]#

Enforce translation invariance.

This subtracts drift divided by number of elements in each row and column.

Return type:: None

run_imag_self_energy(grid_points, temperatures, frequency_points=None, frequency_step=None, num_frequency_points=None, num_points_in_batch=None, frequency_points_at_bands=False, scattering_event_class=None, write_txt=False, write_gamma_detail=False, keep_gamma_detail=False, output_filename=None)[source]#

Calculate the imaginary part of the bubble self-energy (Gamma).

The phonon self-energy is decomposed as Pi = Delta - i Gamma. Gamma is computed at the given grid points and temperatures, as a function of frequency. Results are returned as ImagSelfEnergyValues and also kept on the instance.

Parameters:

grid_points (array_like) – Grid-point indices at which Gamma is computed. shape=(grid_points,), dtype=int.
temperatures (array_like) – Temperatures at which Gamma is computed. shape=(temperatures,), dtype=float.
frequency_points (array_like, optional) – Frequency sampling points. shape=(frequency_points,), dtype=float. Default is None; when frequency_points_at_bands=False and this is None, uniform sampling is generated from num_frequency_points or frequency_step.
frequency_step (float, optional) – Uniform pitch of frequency sampling points. Default is None, which falls back to num_frequency_points.
num_frequency_points (int, optional) – Number of sampling points (including end points) used when frequency_step is not set. Default is None, which gives 201.
num_points_in_batch (int, optional) – Number of sampling points per batch. Larger batches allow more efficient multi-core utilization at the cost of memory. Default is None, which gives 10.
frequency_points_at_bands (bool, optional) – When True, use the phonon band frequencies as the frequency points. Default is False.
scattering_event_class (int, optional) – Restrict Gamma to a specific scattering event class (1 or 2). When set, only the chosen class is accumulated into gammas (the usual full Gamma is not stored). Default is None.
write_txt (bool, optional) – Write frequency points and Gamma to text files. Default is False.
write_gamma_detail (bool, optional) – Write per-scattering-event Gamma to an HDF5 file. Default is False.
keep_gamma_detail (bool, optional) – Keep per-scattering-event Gamma on the instance (accessible via detailed_gammas). Default is False.
output_filename (str, optional) – Inserted into output filenames.

Returns:

Container with frequency_points, gammas, scattering_event_class, and (when keep_gamma_detail=True) detailed_gammas.

Return type:

ImagSelfEnergyValues

Raises:

RuntimeError – When init_phph_interaction() has not been called.

run_real_self_energy(grid_points, temperatures, frequency_points_at_bands=False, frequency_points=None, frequency_step=None, num_frequency_points=None, epsilons=None, write_txt=False, write_hdf5=False, output_filename=None)[source]#

Calculate the real part of the bubble self-energy (Delta).

The phonon self-energy is decomposed as Pi = Delta - i Gamma. Delta is computed at the given grid points and temperatures, as a function of frequency.

Parameters:

grid_points (array_like) – Grid-point indices at which Delta is computed. shape=(grid_points,), dtype=int.
temperatures (array_like) – Temperatures at which Delta is computed. shape=(temperatures,), dtype=float.
frequency_points_at_bands (bool, optional) – With False (default), frequency shifts are calculated at sampling points. With True, they are calculated at the phonon band frequencies.
frequency_points (array_like, optional) – Frequency sampling points. shape=(frequency_points,), dtype=float. Default is None; when None, uniform sampling is generated from num_frequency_points or frequency_step.
frequency_step (float, optional) – Uniform pitch of frequency sampling points. Default is None, which falls back to num_frequency_points.
num_frequency_points (int, optional) – Number of sampling points (including end points) used when frequency_step is not set. Default is None, which gives 201.
epsilons (array_like, optional) – Smearing widths used to compute the principal part. When multiple values are given, frequency shifts for each are returned. shape=(epsilons,), dtype=float. Default is None (use sigmas).
write_txt (bool, optional) – Write frequency points and Delta to text files. Default is False.
write_hdf5 (bool, optional) – Write results to HDF5 files, one per (grid point, epsilon, temperature). Default is False.
output_filename (str, optional) – Inserted into output filenames.

Returns:

frequency_points (ndarray or None) – Frequency sampling points. None when frequency_points_at_bands=True. dtype='double'.
deltas (ndarray) – Real-part frequency shifts, indexed by (epsilon, grid_point, temperature, band) with a trailing frequency-points axis (collapsed to the band frequency when frequency_points_at_bands=True). dtype='double'.

Raises:

RuntimeError – When init_phph_interaction() has not been called.

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]] | None, ndarray[tuple[Any, …], dtype[float64]]]

run_spectral_function(grid_points, temperatures, frequency_points=None, frequency_step=None, num_frequency_points=None, num_points_in_batch=None, write_txt=False, write_hdf5=False, output_filename=None)[source]#

Calculate the phonon spectral function from the bubble self-energy.

The spectral function A(omega) ~ Gamma / ((omega - Omega - Delta)^2 + Gamma^2) is computed at the given grid points and temperatures, as a function of frequency. The result is stored on the instance.

Parameters:

grid_points (array_like) – Grid-point indices at which the spectral function is computed. shape=(grid_points,), dtype=int.
temperatures (array_like) – Temperatures at which the spectral function is computed. shape=(temperatures,), dtype=float.
frequency_points (array_like, optional) – Frequency sampling points. shape=(frequency_points,), dtype=float. Default is None; when None, uniform sampling is generated from num_frequency_points or frequency_step.
frequency_step (float, optional) – Uniform pitch of frequency sampling points. Default is None, which falls back to num_frequency_points.
num_frequency_points (int, optional) – Number of sampling points (including end points) used when frequency_step is not set. Default is None, which gives 201.
num_points_in_batch (int, optional) – Number of sampling points per batch. Larger batches allow more efficient multi-core utilization at the cost of memory. Default is None, which gives 10.
write_txt (bool, optional) – Write frequency points and spectral functions to text files. Default is False.
write_hdf5 (bool, optional) – Write results to HDF5 files, one per grid point. Default is False.
output_filename (str, optional) – Inserted into output filenames.

Raises:

RuntimeError – When init_phph_interaction() has not been called.

Return type:

None

run_thermal_conductivity(is_LBTE=False, temperatures=None, is_isotope=False, mass_variances=None, grid_points=None, boundary_mfp=None, solve_collective_phonon=False, use_ave_pp=False, is_reducible_collision_matrix=False, is_kappa_star=True, gv_delta_q=None, is_full_pp=False, pinv_cutoff=None, pinv_method=0, pinv_solver=0, write_gamma=False, read_gamma=False, is_N_U=False, transport_type=None, write_kappa=False, write_gamma_detail=False, write_collision=False, read_collision=None, write_pp=False, read_pp=False, read_elph=None, write_LBTE_solution=False, compression='gzip', input_filename=None, output_filename=None, log_level=None)[source]#

Run a lattice thermal conductivity calculation.

Result is stored in thermal_conductivity (an RTACalculator when is_LBTE=False, an LBTECalculator otherwise).

Parameters:

is_LBTE (bool, optional) – False for the relaxation-time approximation (RTA), True for the direct solution of the linearized Boltzmann equation (LBTE) and the Wigner transport equation. Default is False.
temperatures (array_like, optional) –
Temperatures at which thermal conductivity is computed. shape=(temperature_points,), dtype='double'. With None (default), the defaults depend on is_LBTE:
```
is_LBTE=False:  [0, 10, ..., 1000]
is_LBTE=True:   [300]
```
is_isotope (bool, optional) – Include isotope scattering. Default is False.
mass_variances (array_like, optional) – Mass variances for isotope scattering. With None (default) and is_isotope=True, the values stored in the phono3py instance are used. shape=(atoms_in_primitive,), dtype='double'.
grid_points (array_like, optional) – Grid-point indices at which mode thermal conductivities are computed. With None (default), all required grid points are chosen internally. shape=(num_grid_points,), dtype='int64'.
boundary_mfp (float, optional) – Mean free path in micrometers used to model a simple boundary-scattering contribution. None (default) disables this contribution.
solve_collective_phonon (bool, optional) – Option for an under-development feature. Default is False.
use_ave_pp (bool, optional) – RTA only (is_LBTE=False). Use an averaged ph-ph interaction strength to compute phonon lifetimes. This does not reduce computational cost; it is mainly a modelling tool for analyzing the result. Default is False.
is_reducible_collision_matrix (bool, optional) – Direct-solution only (is_LBTE=True). Experimental: with True, the full collision matrix is constructed and solved. Default is False.
is_kappa_star (bool, optional) – With True (default), use crystal symmetry to reduce the grid points at which mode thermal conductivities are sampled.
gv_delta_q (float, optional) – Q-distance (in 1/Angstrom) used by the central finite-difference scheme for group velocity when non-analytical correction is in effect. Default is None (effectively 1e-5).
is_full_pp (bool, optional) – With True, compute all elements of the ph-ph interaction strength. With False (default) and the tetrahedron method, elements known to be zero are skipped, giving a substantial speed-up. With the smearing method, all elements are computed regardless of this flag unless sigma_cutoff is set.
pinv_cutoff (float, optional) – Direct-solution only (is_LBTE=True). Threshold to decide whether an eigenvalue is treated as zero in the pseudo-inverse of the collision matrix. See also pinv_method. Default is None (typically 1.0e-8).
pinv_method (int, optional) –
Direct-solution only (is_LBTE=True). Pseudo-inverse zero-eigenvalue criterion:
```
0:  abs(eigenvalue) < pinv_cutoff
1:  eigenvalue       < pinv_cutoff
```
Default is 0.

pinv_solver (int, optional) –

Direct-solution only (is_LBTE=True). Choice of solver for the pseudo-inverse of the collision matrix. 0 selects the default automatically. Choices other than 1 and 4 are dangerous and not recommended:

0:  default (1 with MKL LAPACKE or scipy unavailable;
    4 otherwise).
1:  LAPACKE dsyev  -- smaller memory than dsyevd, but
    slower. Default when MKL LAPACKE is integrated or
    scipy is not installed.
2:  LAPACKE dsyevd -- larger memory than dsyev, but
    faster. Not recommended (occasional wrong result).
3:  numpy dsyevd (linalg.eigh). Not recommended
    (occasional wrong result).
4:  scipy dsyev. Default when scipy is installed and
    MKL LAPACKE is not integrated.
5:  scipy dsyevd. Not recommended (occasional wrong
    result).

Default is 0.

write_gamma (bool, optional) – RTA only (is_LBTE=False). Write mode thermal conductivity properties to files, one per grid point. When band_indices or multiple sigmas are specified, a file is written per band-index group and per sigma. Default is False.
read_gamma (bool, optional) – RTA only (is_LBTE=False). Read files written by write_gamma=True instead of recomputing ph-ph interaction strengths and imaginary self-energies. Default is False.
is_N_U (bool, optional) – RTA only (is_LBTE=False). Separate the imaginary self-energy into normal and Umklapp contributions. Default is False.
transport_type (str, optional) – "SMM19", "NJC23", or None. Default is None.
write_kappa (bool, optional) – Write thermal conductivity and related properties to a file. With multiple sigmas, one file is written per sigma. Default is False.
write_gamma_detail (bool, optional) – RTA only (is_LBTE=False). Write detailed imaginary self-energy information alongside the files produced by write_gamma. Default is False.
write_collision (bool, optional) – Direct-solution only (is_LBTE=True). Write the collision matrix to a file. With multiple sigmas, one file is written per sigma. The file can be very large. Default is False.
read_collision (str or Sequence[int], optional) – Direct-solution only (is_LBTE=True). Read the collision matrix from a file. Default is None.
write_pp (bool, optional) – Write ph-ph interaction strength to files, one per grid point. Assumes a single value in sigmas. Default is False.
read_pp (bool, optional) – Read ph-ph interaction strength from files. Default is False.
read_elph (int, optional) – Index used to read electron-phonon gammas from a file. Default is None.
write_LBTE_solution (bool, optional) – Direct-solution only (is_LBTE=True). Write the collision-matrix eigenvectors as row vectors (column vectors when pinv_solver=3). With multiple sigmas, one file is written per sigma. The file can be very large. Default is False.
compression (str, optional) – HDF5 compression for large datasets. See the h5py documentation. Default is "gzip".
input_filename (str, optional) – Deprecated. When set, the string is inserted before the filename extension in read paths. Default is None.
output_filename (str, optional) – Deprecated. When set, the string is inserted before the filename extension in write paths. Default is None.
log_level (int, optional) – Override the instance-level log_level for this call. Default is None (use the instance value).

Raises:

RuntimeError – When init_phph_interaction() has not been called.

Return type:

None

save(filename='phono3py_params.yaml', settings=None)[source]#

Save the Phono3py instance state to a YAML file.

Parameters:

filename (str or os.PathLike, optional) – Output file path. Default is "phono3py_params.yaml".

settings (dict, optional) –

Selects which sections to write. Only keys whose values differ from the defaults need to be supplied. The defaults are:

{'force_sets':            True,
 'displacements':         True,
 'force_constants':       False,
 'born_effective_charge': True,
 'dielectric_constant':   True}

Return type:

None

develop_mlp(params=None, test_size=0.1)[source]#

Develop machine learning potential.

Parameters:

params (PypolymlpParams or dict, optional) – Parameters for developing MLP. Default is None. When dict is given, PypolymlpParams instance is created from the dict.
test_size (float, optional) – Training and test data are split by this ratio. test_size=0.1 means the first 90% of the data is used for training and the rest is used for test. Default is 0.1.

Return type:

None

save_mlp(filename=None)[source]#

Save machine learning potential.

Parameters:: filename (str | PathLike | None)
Return type:: None

load_mlp(filename=None)[source]#

Load machine learning potential.

Parameters:: filename (str | PathLike | None)
Return type:: None

evaluate_mlp()[source]#

Evaluate machine learning potential.

This method calculates the supercell energies and forces from the MLP for the displacements in self._dataset of type 2. The results are stored in self._dataset.

The displacements may be generated by the produce_force_constants method with number_of_snapshots > 0. With MLP, a small distance parameter, such as 0.01, can be numerically stable for the computation of force constants.

Return type:: None

develop_phonon_mlp(params=None, test_size=0.1)[source]#

Develop MLP for fc2.

Parameters:

params (PypolymlpParams or dict, optional) – Parameters for developing MLP. Default is None. When dict is given, PypolymlpParams instance is created from the dict.
test_size (float, optional) – Training and test data are split by this ratio. test_size=0.1 means the first 90% of the data is used for training and the rest is used for test. Default is 0.1.

Return type:

None

save_phonon_mlp(filename=None)[source]#

Save machine learning potential.

Parameters:: filename (str | PathLike | None)
Return type:: None

load_phonon_mlp(filename=None)[source]#

Load machine learning potential.

Parameters:: filename (str | PathLike | None)
Return type:: None

evaluate_phonon_mlp()[source]#

Evaluate the machine learning potential.

This method calculates the supercell energies and forces from the MLP for the displacements in self._dataset of type 2. The results are stored in self._dataset.

Return type:: None

to_phono3py_yaml(configuration=None, settings=None)[source]#

Return Phono3pyYaml class instance with this data.

Parameters:

configuration (dict | None)
settings (dict | None)

Return type:

Phono3pyYaml

API reference

Contents

API reference#

Top-level functions#

Phono3py class#

`Phono3py` class#