ramannoodle.pmodel

Classes for various polarizability models.

class ramannoodle.pmodel.ARTModel(ref_structure, ref_polarizability, is_dummy_model=False)

Bases: InterpolationModel

Polarizability model based on atomic Raman tensors (ARTs).

This model is a flavor of InterpolationModel with added restrictions. The degrees of freedom (DOF) in ARTModel are displacements of individual atoms. 1D interpolations are used, with only two amplitudes allowed per DOF. Atomic displacements can be in any direction, so long as all three directions for a given atom are orthogonal.

All assumptions from InterpolationModel apply.

Note

Degrees of freedom cannot (and should not) be added using the add_dof() and add_dof_from_files() methods inherited from InterpolationModel. Usage of these methods will raise a UserError. Instead, use add_art() or add_art_from_files().

Warning

Due to the way ARTModel is implemented, the predicted tensor of the reference structure may be offset slightly. This is a fixed offset and therefore has no influence on Raman spectra calculations.

Parameters:

  • ref_structure (ReferenceStructure) – Reference structure on which to base the model.

  • ref_polarizability (ndarray[Any, dtype[float64]]) – Array with shape (3,3) giving polarizability of the reference structure.

  • is_dummy_model (bool)

add_art(atom_index, cart_direction, amplitudes, polarizabilities)

Add an atomic Raman tensor (ART).

Specification of an ART requires an atom index, displacement direction, displacement amplitudes, and corresponding known polarizabilities for each amplitude. ARTs related to the specified ART by symmetry are added automatically.

Parameters:

  • atom_index (int) – Atom index in the reference structure.

  • cart_direction (ndarray[Any, dtype[float64]]) – (Å) Array with shape (3,). Must be orthogonal to all previously added ARTs belonging to the atom at atom_index.

  • amplitudes (ndarray[Any, dtype[float64]]) – (Å) Array with shape (1,) or (2,). Duplicate amplitudes, either those explicitly provided or those generated by structural symmetries, will raise InvalidDOFException.

  • polarizabilities (ndarray[Any, dtype[float64]]) – Array with shape (1,3,3) or (2,3,3) containing known polarizabilities for each amplitude. If dummy model, this parameter is ignored.

Raises:

InvalidDOFException – Provided ART was invalid.

Return type:

None

add_art_from_files(filepaths, file_format)

Add an atomic Raman tensor (ART) from file(s).

Required directions, amplitudes, and polarizabilities are automatically determined from provided files. Files should be chosen such that the resulting ARTs are valid under the same restrictions of add_art().

Parameters:
Raises:
Return type:

None

add_art_from_pymatgen(pymatgen_structures, polarizabilities)

Add an atomic Raman tensor (ART) from pymatgen Structures and polarizabilities.

Required directions, amplitudes, and polarizabilities are automatically determined from provided structures. Structures should be chosen such that the resulting ARTs are valid under the same restrictions of add_art().

Parameters:
Raises:

InvalidDOFException – ART assembled from supplied Structures was invalid. See add_art() for restrictions.

Return type:

None

get_dof_indexes(atom_indexes_or_symbols)

Return the DOF indexes of certain atoms.

Parameters:

atom_indexes_or_symbols (int | str | list[int | str]) – If integer or list of integers, specifies atom indexes. If string or list of strings, specifies atom symbols. Mixtures of indexes and symbols are allowed.

Return type:

list[int]

get_masked_model(dof_indexes_to_mask)

Return new model with certain degrees of freedom masked (deactivated).

Model masking allows for the calculation of partial Raman spectra in which only certain degrees of freedom are considered.

Parameters:

dof_indexes_to_mask (list[int]) – DOF indexes associated with specific atoms can be retrieved using get_dof_indexes().

Return type:

ARTModel

get_specification_tuples()

Return tuples with information on model.

Return type:

list[tuple[int, list[int], list[ndarray[Any, dtype[float64]]]]]

Returns:

  1. parent atom index

  2. List of atom indexes that are symmetrically equivalent to parent atom index

  3. Currently specified ART directions for parent atom indexes – (Å) List of arrays with shape (3,).

class ramannoodle.pmodel.InterpolationModel(ref_structure, ref_polarizability, is_dummy_model=False)

Bases: PolarizabilityModel

Polarizability model based on interpolation around degrees of freedom (DOFs).

One is free to specify the interpolation order as well as the precise the DOFs, so long as they are orthogonal. For example, one can employ first-order (linear) interpolation around phonon displacements to calculate a conventional Raman spectrum. One can achieve identical results – often with fewer calculations – by using first-order interpolations around atomic displacements.

This model’s key assumption is that each degree of freedom in a system modulates the polarizability independently.

Parameters:

  • ref_structure (ReferenceStructure) – Reference structure on which to base the model.

  • ref_polarizability (ndarray[Any, dtype[float64]]) – Array with shape (3,3) with polarizability of the reference structure.

  • is_dummy_model (bool)

add_dof(cart_displacement, amplitudes, polarizabilities, interpolation_order, include_ref_polarizability=True)

Add a degree of freedom (DOF).

Specification of a DOF requires a displacement (directions the atoms move) alongside displacement amplitudes and corresponding known polarizabilities for each amplitude. Alongside the DOF specified, all DOFs related by the system’s symmetry will be added as well. The interpolation order can be specified, though one must ensure that sufficient data is available.

Parameters:

  • cart_displacement (ndarray[Any, dtype[float64]]) – (Å) Array with shape (N,3) where N is the number of atoms. The magnitude of the displacement is ignored, only the direction is used. Must be orthogonal to all previously added DOFs.

  • amplitudes (ndarray[Any, dtype[float64]]) – (Å) Array with shape (L,). Duplicate amplitudes, either those explicitly provided or those generated by structural symmetries, will raise InvalidDOFException.

  • polarizabilities (ndarray[Any, dtype[float64]]) – Array with shape (1,3,3) or (2,3,3) containing known polarizabilities for each amplitude. If dummy model, this parameter is ignored.

  • interpolation_order (int) – Must be less than the number of total number of amplitudes after symmetry considerations.

  • include_ref_polarizability (bool) – Whether to include the references polarizability at 0.0 amplitude in the interpolation.

Raises:

InvalidDOFException – Provided degree of freedom was invalid.

Return type:

None

add_dof_from_files(filepaths, file_format, interpolation_order)

Add a degree of freedom (DOF) from file(s).

Required displacements, amplitudes, and polarizabilities are automatically determined from provided files. Files should be chosen such that the resulting DOFs are valid under the same restrictions of add_dof().

Parameters:
Raises:
Return type:

None

add_dof_from_pymatgen(pymatgen_structures, polarizabilities, interpolation_order)

Add a degree of freedom from a list of pymatgen Structures and polarizabilities.

Parameters:

  • pymatgen_structures (list[Structure]) – List of length M.

  • polarizabilities (ndarray[Any, dtype[float64]]) – Array with shape (M,3,3).

  • interpolation_order (int) – Must be less than the number of total number of amplitudes after symmetry considerations.

Raises:
Return type:

None

calc_polarizabilities(positions_batch)

Return estimated polarizabilities for a batch of fractional positions.

Parameters:

positions_batch (ndarray[Any, dtype[float64]]) – (fractional) Array with shape (S,N,3) where S is the number of samples and N is the number of atoms.

Return type:

ndarray[Any, dtype[float64]]

Returns:

Array with shape (S,3,3).

Raises:

UserError – Model is a dummy model.

get_masked_model(dof_indexes_to_mask)

Return new model with certain degrees of freedom deactivated.

Model masking allows for the calculation of partial Raman spectra in which only certain degrees of freedom are considered.

Return type:

InterpolationModel

Parameters:

dof_indexes_to_mask (list[int])

unmask()

Clear mask, activating all specified DOFs.

Return type:

None

property cart_basis_vectors: list[ndarray[Any, dtype[float64]]]

Get (a copy of) cartesian basis vectors.

Returns:

(Å) List of length J containing arrays with shape (N,3) where J is the number of specified degrees of freedom and N is the number of atoms.

property interpolations: list[BSpline]

Get (a copy of) interpolations.

Returns:

List of length J where J is the number of specified degrees of freedom.

property is_dummy_model: bool

Get whether model is a dummy model.

property mask: ndarray[Any, dtype[bool]]

Get (a copy of) mask.

Returns:

Array with shape (J,) where J is the number of specified degrees of freedom.

property ref_polarizability: ndarray[Any, dtype[float64]]

Get (a copy of) reference polarizability.

Returns:

Array with shape (3,3).

property ref_structure: ReferenceStructure

Get (a copy of) reference structure.

Subpackages