pymatgen.analysis.magnetism package

Package for analysis of magnetic structures.

Submodules

pymatgen.analysis.magnetism.analyzer module

This module provides some useful functions for dealing with magnetic Structures (e.g. Structures with associated magmom tags).

class CollinearMagneticStructureAnalyzer(structure: Structure, overwrite_magmom_mode: str | OverwriteMagmomMode = OverwriteMagmomMode.none, round_magmoms: bool = False, detect_valences: bool = False, make_primitive: bool = True, default_magmoms: dict | None = None, set_net_positive: bool = True, threshold: float = 0, threshold_nonmag: float = 0.1, threshold_ordering: float = 1e-08)

Bases: object

A class which provides a few helpful methods to analyze collinear magnetic structures.

If magnetic moments are not defined, moments will be taken either from default_magmoms.yaml (similar to the default magmoms in MPRelaxSet, with a few extra definitions) or from a specie:magmom dict provided by the default_magmoms kwarg.

Input magmoms can be replaced using the ‘overwrite_magmom_mode’ kwarg. This can be: * “none” to do nothing, * “respect_sign” which will overwrite existing magmoms with

those from default_magmoms but will keep sites with positive magmoms positive, negative magmoms negative and zero magmoms zero,

• “respect_zeros”, which will give a ferromagnetic structure (all positive magmoms from default_magmoms) but still keep sites with zero magmoms as zero,

• “replace_all” which will try to guess initial magmoms for all sites in the structure irrespective of input structure (this is most suitable for an initial DFT calculation),

• “replace_all_if_undefined” is the same as “replace_all” but only if no magmoms are defined in input structure, otherwise it will respect existing magmoms.

• “normalize” will normalize magmoms to unity, but will respect sign (used for comparing orderings), magmoms < threshold will be set to zero

Parameters:

• structure – input Structure object

• overwrite_magmom_mode – “respect_sign”, “respect_zeros”, “replace_all”, “replace_all_if_undefined”, “normalize” (default “none”)

• round_magmoms – will round input magmoms to specified number of decimal places if integer is supplied, if set to a float will try and group magmoms together using a kernel density estimator of provided width, and extracting peaks of the estimator detect_valences: if True, will attempt to assign valences to input structure

• make_primitive – if True, will transform to primitive magnetic cell

• default_magmoms – (optional) dict specifying default magmoms

• set_net_positive – if True, will change sign of magnetic moments such that the net magnetization is positive. Argument will be ignored if mode “respect_sign” is used.

• threshold – number (in Bohr magnetons) below which magmoms will be rounded to zero

• threshold_nonmag – number (in Bohr magneton) below which nonmagnetic ions (with no magmom specified in default_magmoms) will be rounded to zero

• threshold_ordering – number (absolute of sum of all magmoms, in Bohr magneton) below which total magnetization is treated as zero when defining magnetic ordering. Defaults to 1e-8.

get_exchange_group_info(symprec: float = 0.01, angle_tolerance: float = 5) → tuple[str, int]

Get the information on the symmetry of the Hamiltonian describing the exchange energy of the system, taking into account relative direction of magnetic moments but not their absolute direction.

This is not strictly accurate (e.g. some/many atoms will have zero magnetic moments), but defining symmetry this way is a useful way of keeping track of distinct magnetic orderings within pymatgen.

Parameters:

• symprec (float) – same as SpacegroupAnalyzer (Default value = 1e-2)

• angle_tolerance (float) – same as SpacegroupAnalyzer (Default value = 5)

Returns:

spacegroup_symbol, international_number

Return type:

tuple[str, int]

get_ferromagnetic_structure(make_primitive: bool = True) → Structure

Get a Structure with all magnetic moments positive or zero.

Parameters:

make_primitive – Whether to make structure primitive after making all magnetic moments positive (Default value = True)

Returns:

Structure

get_nonmagnetic_structure(make_primitive: bool = True) → Structure

Get a Structure without magnetic moments defined.

Parameters:

make_primitive – Whether to make structure primitive after removing magnetic information (Default value = True)

Returns:

Structure

get_structure_with_only_magnetic_atoms(make_primitive: bool = True) → Structure

Get a Structure with only magnetic atoms present.

Parameters:

make_primitive – Whether to make structure primitive after removing non-magnetic atoms (Default value = True)

Returns:

Structure

get_structure_with_spin() → Structure

Get a Structure with species decorated with spin values instead of using magmom site properties.

property is_magnetic: bool

True if any non-zero magmoms present.

property magmoms: NDArray

magmoms as a NumPy array.

property magnetic_species_and_magmoms: dict[str, Any]

A dict of magnetic species and the magnitude of their associated magmoms. Will return a list if there are multiple magmoms per species.

Returns:

dict of magnetic species and magmoms

matches_ordering(other: Structure) → bool

Compares the magnetic orderings of one structure with another.

Parameters:

other – Structure to compare

Returns:

True if magnetic orderings match, False otherwise

Return type:

bool

property number_of_magnetic_sites: int

Number of magnetic sites present in structure.

number_of_unique_magnetic_sites(symprec: float = 0.001, angle_tolerance: float = 5) → int

Parameters:

• symprec (float) – same as in SpacegroupAnalyzer (Default value = 1e-3)

• angle_tolerance (float) – same as in SpacegroupAnalyzer (Default value = 5).

Returns:

Number of symmetrically-distinct magnetic sites present in structure.

Return type:

int

property ordering: Ordering

Apply heuristics to return a magnetic ordering for a collinear magnetic structure. Result is not guaranteed to be correct, just a best guess. Tolerance for minimum total magnetization to be considered ferro/ferrimagnetic is self.threshold_ordering and defaults to 1e-8.

Returns:

Enum with values FM: ferromagnetic, FiM: ferrimagnetic,

AFM: antiferromagnetic, NM: non-magnetic or Unknown. Unknown is returned if magnetic moments are not defined or structure is not collinear (in which case a warning is issued).

Return type:

Ordering

property types_of_magnetic_specie: tuple[Element | Species | DummySpecies, ...]

Specie->Species rename. Used to maintain backwards compatibility.

property types_of_magnetic_species: tuple[Element | Species | DummySpecies, ...]

Equivalent to Structure.types_of_specie but only returns magnetic species.

Returns:

types of Species

Return type:

tuple

class MagneticDeformation(deformation, type)

Bases: NamedTuple

Create new instance of MagneticDeformation(deformation, type)

deformation: float

Alias for field number 0

type: str

Alias for field number 1

class MagneticStructureEnumerator(structure: Structure, default_magmoms: dict[str, float] | None = None, strategies: Sequence[str] = ('ferromagnetic', 'antiferromagnetic'), automatic: bool = True, truncate_by_symmetry: bool | int = True, max_orderings: int | None = 64, transformation_kwargs: dict | None = None)

Bases: object

Combines MagneticStructureAnalyzer and MagOrderingTransformation to automatically generate a set of transformations for a given structure and produce a list of plausible magnetic orderings.

Generate different collinear magnetic orderings for a given input structure.

If the input structure has magnetic moments defined, it is possible to use these as a hint as to which elements are magnetic, otherwise magnetic elements will be guessed (this can be changed using default_magmoms kwarg).

Parameters:

• structure (Structure) – input structure

• default_magmoms (dict[str, float], optional) – magnetic elements to their initial magnetic moments in μB, generally these are chosen to be high-spin since they can relax to a low-spin configuration during a DFT electronic configuration

• strategies (Sequence[str]) – ordering strategies to use, choose from: ferromagnetic, antiferromagnetic, antiferromagnetic_by_motif, ferrimagnetic_by_motif and ferrimagnetic_by_species (here, “motif”, means to use a different ordering parameter for symmetry inequivalent sites)

• automatic (bool) – if True, will automatically choose sensible strategies

• truncate_by_symmetry (int) – if True (default), will remove very unsymmetrical orderings that are likely physically implausible, keeping structures with the 5 most symmetric space groups. May also be given as an int to keep a different number of the most symmetric space groups.

• max_orderings (int) – the maximum number of structures to return

• transformation_kwargs – keyword arguments to pass to MagOrderingTransformation, to change automatic cell size limits, etc.

available_strategies: ClassVar[tuple[str, ...]] = ('ferromagnetic', 'antiferromagnetic', 'ferrimagnetic_by_motif', 'ferrimagnetic_by_species', 'antiferromagnetic_by_motif', 'nonmagnetic')

ordered_structure_origins: list[str]

ordered_structures: list[Structure]

class Ordering(*values)

Bases: Enum

Enumeration defining possible magnetic orderings.

AFM = 'AFM'

FM = 'FM'

FiM = 'FiM'

NM = 'NM'

Unknown = 'Unknown'

class OverwriteMagmomMode(*values)

Bases: Enum

Enumeration defining different modes for analyzer.

none = 'none'

normalize = 'normalize'

replace_all = 'replace_all'

replace_all_if_undefined = 'replace_all_if_undefined'

respect_sign = 'respect_sign'

respect_zeros = 'respect_zeros'

magnetic_deformation(structure_A: Structure, structure_B: Structure) → MagneticDeformation

Calculate ‘magnetic deformation proxy’, a measure of deformation (norm of finite strain) between ‘non-magnetic’ (non-spin-polarized) and ferromagnetic structures.

Adapted from Bocarsly et al. 2017, DOI: 10.1021/acs.chemmater.6b04729

Parameters:

• structure_A – Structure

• structure_B – Structure

Returns:

MagneticDeformation

pymatgen.analysis.magnetism.heisenberg module

Fit the exchange constants of a classical Heisenberg model to the energies of collinear magnetic orderings.

The model lives on a paramagnetic parent cell (ParentCell): its symmetry orbits of sites are the magnetic sublattices, and its symmetry orbits of bonds are the Interaction s, one exchange constant J each. Every ordering (ComputedOrdering) is mapped onto the parent and contributes one row of spin products per interaction; HeisenbergMapper fits the J’s to all rows by least squares.

Migrating from HeisenbergMapper 0.1

Sublattices used to be derived from the orderings themselves, which restricted all orderings to a single common supercell. They are now defined once on a paramagnetic parent cell and every ordering is mapped onto it, so orderings in different supercells can be fitted together. This changed the public surface:

• HeisenbergMapper(ordered_structures, energies, cutoff, tol) gained a parent argument in third position, so positional cutoff moves along: HeisenbergMapper(ordered_structures, energies, parent, cutoff). Supply the paramagnetic parent cell whenever you have it; leaving it as None infers it from the lowest-energy ordering and warns. tol is deprecated and ignored.

• sgraphs is gone. Each ordering is now a ComputedOrdering in mapper.orderings, carrying its own structure, magnetic_structure, energy and coupling_graph; mapper.coupling_graphs gives the list of graphs. Note these are built on the magnetic-only structure, not the full one, at the parent’s positions (ordering.ideal_magnetic_structure), not the relaxed ones.

• J labels are now 'J1(Fe1-Mn1)', 'J2(Fe1-Fe1)', …: every interaction is numbered by length across all sublattice pairs, and the pair is named per element as in a CIF file. They replace '<i>-<j>-nn', '<i>-<j>-nnn', … nn_interactions is now interactions and maps each sublattice pair (i, j) to its J labels instead of mapping 'nn'/'nnn'/'nnnn' to site pairs.

• unique_site_ids and wyckoff_ids are gone. Sublattices are now the symmetry orbits of the parent: mapper.sublattice_ids labels the magnetic sites of each ordering, and mapper.sublattice_names and mapper.sublattice_wyckoff_symbols map a sublattice id to its name ('Fe1') and its Wyckoff symbol.

• ordered_structures (the screened, energy-sorted list) is now mapper.structures. mapper.energies now holds the total energies of the screened orderings, as passed to the constructor, rather than energies per magnetic ion; those moved to mapper.energies_per_magnetic_ion. The same split applies to HeisenbergModel. The unmodified constructor inputs are still ordered_structures_/energies_.

• get_exchange now returns (ex_params, residual) rather than ex_params alone. It is a least-squares fit over all orderings instead of an exactly-determined solve. The {"<J>": ...} fallback for a single interaction is gone: that J is now fitted together with E0. residual is the RMS fit residual in meV per magnetic ion and is also stored on mapper.residual and on HeisenbergModel. It is only meaningful with substantially more orderings than fitted parameters; otherwise the extra parameters overfit, lowering the residual without improving the fit. get_exchange reports an ill-conditioned fit with a UserWarning instead of the module logger.

• Interactions are no longer cut to n - 1 for n orderings, longest first. Instead, each interaction the orderings cannot separate from E0 and the shorter interactions is left out, with a UserWarning.

• estimate_exchange, get_low_energy_orderings and get_mft_temperature are deprecated. Use get_exchange for bond-resolved J_ij, and a Monte Carlo solver (e.g. VAMPIRE, via HeisenbergModel) rather than the mean field estimate for a critical temperature.

• HeisenbergScreener(ordered_structures, energies) now takes the list of ComputedOrdering objects and exposes screened_orderings in place of screened_structures/screened_energies.

• Couplings are found on the parent geometry, mapped into each ordering’s supercell, not on the relaxed orderings: relaxation of the orderings no longer decides which pairs couple or which J they belong to. An inferred parent is itself a relaxed cell, so pass the unrelaxed one to get the full benefit.

• Every sublattice pair couples through at least its nearest bonds, also with a cutoff. Without a cutoff, the nearest bonds are taken per pair rather than once per site, and are only the shortest ones, not all within 10% of them.

• Bonds share an exchange constant only if a symmetry operation of the parent maps one onto the other, not because they have the same length. Bonds of equal length that are not symmetry-equivalent get separate J’s.

class Bond(start: int, end: int, image: tuple[int, int, int])

Bases: NamedTuple

Bond from parent site start to parent site end, image parent cells away.

Create new instance of Bond(start, end, image)

end: int

Alias for field number 1

image: tuple[int, int, int]

Alias for field number 2

reversed() → Bond

The same bond, seen from its end site.

start: int

Alias for field number 0

class ComputedOrdering(structure: Structure, energy: float, parent: ParentCell, matcher: StructureMatcher, default_magmoms: dict | None = None)

Bases: object

One collinear magnetic ordering with its computed energy, mapped onto the parent cell.

Parameters:

• structure (Structure) – The ordering, with moments, in any supercell of the parent.

• energy (float) – Its total energy (eV).

• parent (ParentCell) – The parent cell it is mapped onto.

• matcher (StructureMatcher) – Maps the parent onto the ordering. It must have primitive_cell=False and attempt_supercell=True.

• default_magmoms (dict) – Elements that can carry a moment, as in CollinearMagneticStructureAnalyzer. Defaults to None, which uses default_magmoms.yaml.

coupled_bonds()

Yield (i, j, image, interaction) for every coupled bond between sites of ideal_magnetic_structure, once from each end.

property coupling_graph: StructureGraph

Graph of the coupled bonds, on ideal_magnetic_structure.

property energy_per_magnetic_ion: float

Total energy divided by the number of magnetic ions (eV).

property magnetic_structure: Structure

Sites of the magnetic species, including any whose moment relaxed to zero.

spin_products(signs_only: bool = False) → dict[str, float]

-sum m_i m_j over the bonds of each interaction, per magnetic ion, keyed by label.

Parameters:

signs_only (bool) – Use the sign of each moment instead of its value.

property sublattice_ids: list[int]

Parent sublattice of each site of magnetic_structure.

class HeisenbergMapper(ordered_structures, energies, parent=None, cutoff=0, tol: float | None = None, symprec: float = 0.01, matcher: StructureMatcher | None = None, default_magmoms: dict | None = None)

Bases: object

Compute exchange parameters from the energies of collinear magnetic orderings.

The model is defined once, on a paramagnetic parent cell: its symmetry orbits of sites are the magnetic sublattices, and its symmetry orbits of bonds are the interactions, one exchange constant J each. Every ordering is mapped onto the parent, so orderings in different supercells share one set of exchange constants, and each ordering contributes one row of spin products to a least-squares fit.

Compute all orderings as static (SCF) calculations in the parent’s geometry. Relaxing each ordering on its own mixes lattice energy into the energy differences, and the fit puts it into the J’s.

parent

Defines the sublattices and the interactions.

Type:

ParentCell

orderings

The screened orderings, sorted by energy per magnetic ion.

Type:

list[ComputedOrdering]

ex_mat

Heisenberg Hamiltonian (per magnetic ion) for each ordering.

Type:

DataFrame

ex_params

Exchange parameter values. The J_ij are in meV/muB^2 (they multiply the raw moments, see get_exchange); the included ‘E0’ offset is in eV per magnetic ion.

Type:

dict

Map collinear orderings, possibly in different supercells of a common parent cell, onto a classical Heisenberg model.

Parameters:

• ordered_structures (list) – Magnetically ordered structures, with magmoms.

• energies (list) – Total energy (eV) of each ordering.

• parent (Structure) – Paramagnetic parent cell whose symmetry defines the magnetic sublattices and the interactions; it is reduced to its primitive cell. If None, the lowest-energy ordering is used, which is only correct if that ordering kept the parent’s symmetry. Defaults to None.

• cutoff (float) – Every bond within this distance (Angstrom) couples. A sublattice pair without such a bond still couples through its shortest bonds, so the default of 0 keeps only the shortest bonds of each pair.

• tol (float) – Deprecated and ignored. Symmetry decides which bonds share a J, so there are no shells of near-equal length any more.

• symprec (float) – Symmetry tolerance (Angstrom) for finding the parent’s sublattices and interactions. Raise it, or pass a symmetrized parent, if sublattices that should be equivalent come out split. Defaults to 0.01.

• matcher (StructureMatcher) – Maps each ordering onto the parent cell. If relaxation distorted an ordering beyond the defaults, loosen its ltol, stol or angle_tol as far as needed and keep its other settings. It must have primitive_cell=False and attempt_supercell=True, so each ordering is matched as a supercell of the parent. Defaults to StructureMatcher(primitive_cell=False, attempt_supercell=True).

• default_magmoms (dict) – Its keys are the elements that can carry a moment, as in CollinearMagneticStructureAnalyzer; oxidation states are ignored, so key by element (“Fe”, not “Fe2+”). Moments on any other element are zeroed, and those sites drop out of the fit. The values are only used as moments for a structure that carries no moments at all. It replaces default_magmoms.yaml rather than extending it, so list every magnetic element. Defaults to None, which uses default_magmoms.yaml.

property coupling_graphs

Coupling graph of each ordering, on its ideal magnetic-only cell.

Type:

list[StructureGraph]

property dists

Bond length (Angstrom) of each J label.

Type:

dict[str, float]

property energies

Total energy (eV) of each ordering, as supplied to the constructor.

Type:

list[float]

property energies_per_magnetic_ion

Energy per magnetic ion (eV) of each ordering - the energies the fit uses.

Type:

list[float]

estimate_exchange(fm_struct=None, afm_struct=None, fm_e=None, afm_e=None)

Estimate <J> for a structure based on low energy FM and AFM orderings.

Deprecated since version Use: get_exchange() instead, which fits bond-resolved J_ij over all supplied orderings.

Parameters:

• fm_struct (Structure) – fm structure with ‘magmom’ site property

• afm_struct (Structure) – afm structure with ‘magmom’ site property

• fm_e (float) – fm energy per magnetic ion

• afm_e (float) – afm energy per magnetic ion

Returns:

Average J exchange parameter (meV / magnetic ion)

Return type:

float

get_exchange()

Fit E0 and the J_ij to the energies of all orderings by least squares.

The J_ij multiply the raw moments, so they are in meV/muB^2 (bond energy J_ij * m_i * m_j); this keeps moment magnitudes that differ between orderings out of the fitted J_ij.

The residual is only meaningful with substantially more orderings than fitted parameters; otherwise the extra parameters overfit, lowering the residual without improving the fit.

Returns:

J_ij in meV/muB^2 and ‘E0’ in eV per magnetic ion. residual (float): RMS fit residual in meV per magnetic ion.

Return type:

ex_params (dict[str, float])

Raises:

ValueError – If no exchange interaction is left to fit.

get_heisenberg_model()

Save results of mapping to a HeisenbergModel object.

Returns:

MSONable object.

Return type:

HeisenbergModel

get_interaction_graph(filename=None, ordering_index=0)

Get a StructureGraph with edges and weights that correspond to exchange interactions and J_ij values, respectively.

Edge weights are in meV for normalized spins, E = -sum_<ij> J_ij e_i.e_j, as used by VAMPIRE, UppASD and TB2J.

Parameters:

• filename (str) – if not None, save interaction graph to filename.

• ordering_index (int) – Which ordering (and its supercell) to build the graph for. Defaults to 0 (the lowest-energy ordering).

Returns:

Exchange interaction graph.

Return type:

StructureGraph

get_low_energy_orderings()

Find lowest energy FM and AFM orderings to compute E_AFM - E_FM.

Deprecated since version Only: used by the deprecated estimate_exchange().

Returns:

fm structure with ‘magmom’ site property afm_struct (Structure): afm structure with ‘magmom’ site property fm_e (float): fm energy afm_e (float): afm energy

Return type:

fm_struct (Structure)

get_mft_temperature(j_avg)

Crude mean field estimate of critical temperature based on <J> for one sublattice, or solving the coupled equations for a multi-sublattice material.

Deprecated since version No: direct replacement; use a Monte Carlo solver (e.g. VAMPIRE) on the exchange parameters from get_exchange() for a reliable T_c.

Parameters:

j_avg (float) – Average exchange parameter (meV / magnetic ion)

Returns:

Critical temperature mft_t (K)

Return type:

float

property interactions

J labels of each sublattice pair (i, j), i <= j, nearest first. E.g. {(0, 1): [‘J1(Fe1-Mn1)’, ‘J4(Fe1-Mn1)’]}.

Type:

dict[tuple[int, int], list[str]]

property magnetic_structures

Magnetic-only structure of each ordering.

Type:

list[Structure]

property structures

Each ordering with all ions retained.

Type:

list[Structure]

property sublattice_ids

sublattice_ids[k][i] is the sublattice id of magnetic site i in ordering k, aligned with that ordering’s graph.

Type:

list[list[int]]

property sublattice_names

Maps each sublattice id to its name, e.g. ‘Fe1’.

Type:

dict[int, str]

property sublattice_wyckoff_symbols

Maps each sublattice id to its wyckoff symbol.

Type:

dict[int, str]

class HeisenbergModel(formula=None, structures=None, magnetic_structures=None, energies=None, energies_per_magnetic_ion=None, cutoff=None, symprec=None, coupling_graphs=None, sublattice_ids=None, sublattice_names=None, sublattice_wyckoff_symbols=None, interactions=None, dists=None, ex_mat=None, ex_params=None, residual=None, igraph=None)

Bases: MSONable

Store a Heisenberg model fit to low-energy magnetic orderings. Intended to be generated by HeisenbergMapper.get_heisenberg_model().

Parameters:

• formula (str) – Reduced formula of compound.

• structures (list) – Each ordering with all ions retained, with magmoms.

• magnetic_structures (list) – Magnetic-only cell of each ordering. coupling_graphs and sublattice_ids are indexed against these, not against structures. The coupling graphs hold the same sites at the parent’s positions.

• energies (list) – Total energy (eV) of each ordering.

• energies_per_magnetic_ion (list) – Energy per magnetic ion (eV) of each ordering, the energies the exchange parameters were fitted to.

• cutoff (float) – Every bond within this distance (Angstrom) couples.

• symprec (float) – Symmetry tolerance (Angstrom) the parent’s sublattices and interactions were found with.

• coupling_graphs (list) – Coupling graph of each ordering, built on its magnetic sites at the parent’s positions.

• sublattice_ids (list[list[int]]) – sublattice_ids[k][i] is the sublattice id of site i in ordering k.

• sublattice_names (dict) – Maps each sublattice id to its name, e.g. ‘Fe1’.

• sublattice_wyckoff_symbols (dict) – Maps each sublattice id to its wyckoff symbol.

• interactions (dict) – {(i, j): [J label, …]} - the interactions of each sublattice pair, nearest first.

• dists (dict) – {J label: bond length in Angstrom}.

• ex_mat (DataFrame) – Heisenberg Hamiltonian (per magnetic ion) for each ordering.

• ex_params (dict) – Exchange parameter values. The J_ij are in meV/muB^2 (they multiply the raw moments, see HeisenbergMapper.get_exchange); the included ‘E0’ offset is in eV per magnetic ion.

• residual (float) – RMS residual of the fit that produced ex_params, in meV per magnetic ion.

• igraph (StructureGraph) – Exchange interaction graph, edge weights in meV.

as_dict()

Because some dicts have int keys, some sanitization is required for JSON compatibility.

classmethod from_dict(dct: dict) → Self

Create a HeisenbergModel from a dict.

class HeisenbergScreener(orderings: list[ComputedOrdering], screen=False)

Bases: object

Clean and screen magnetic orderings.

Pre-processes magnetic orderings for HeisenbergMapper. It prioritizes low-energy orderings with large and localized magnetic moments.

Parameters:

• orderings (list[ComputedOrdering]) – The orderings to screen. Each one already owns its magnetic-only substructure and its per-magnetic-ion energy.

• screen (bool) – Try to screen out high energy and low-spin configurations.

screened_orderings

Deduplicated orderings, sorted by energy per magnetic ion.

Type:

list[ComputedOrdering]

class Interaction(label: str, sublattices: tuple[int, int], length: float, bonds: frozenset[Bond])

Bases: object

One exchange constant J: a symmetry orbit of parent bonds, in both directions.

bonds: frozenset[Bond]

label: str

length: float

sublattices: tuple[int, int]

class ParentCell(structure: Structure, magnetic_species: set[str], cutoff: float = 0, symprec: float = 0.01)

Bases: object

Paramagnetic parent cell: its site orbits are the sublattices, its bond orbits the interactions.

Parameters:

• structure (Structure) – Parent cell. Moments are dropped and it is reduced to its primitive cell.

• magnetic_species (set[str]) – Elements whose sites form the magnetic sublattices.

• cutoff (float) – Every bond within this distance (Angstrom) couples. A sublattice pair without such a bond couples through its shortest bonds. Defaults to 0, which keeps only the shortest bonds of each pair.

• symprec (float) – Symmetry tolerance (Angstrom) for the sublattices and interactions. Defaults to 0.01.

coupled_bonds(structure: Structure)

Yield (i, j, image, interaction) for every coupled bond between sites of structure, once from each end.

Parameters:

structure (Structure) – Sites at parent positions that carry ‘parent_index’, in any supercell of the parent.

property magnetic_structure: Structure

Magnetic sites of the parent; sublattice_ids is indexed against it.

property sublattice_ids: list[int]

Sublattice id of each site of magnetic_structure.

pymatgen.analysis.magnetism.jahnteller module

JahnTeller distortion analysis.

class JahnTellerAnalyzer

Bases: object

Will attempt to classify if structure may be Jahn-Teller active. Class currently uses datafile of hard-coded common Jahn-Teller active ions. If structure is annotated with magnetic moments, will estimate if structure may be high-spin or low-spin. Class aims for more false-positives than false-negatives.

Init for JahnTellerAnalyzer.

get_analysis(structure: Structure, calculate_valences: bool = True, guesstimate_spin: bool = False, op_threshold: float = 0.1) → dict

Convenience method, uses get_analysis_and_structure method.

Obtain an analysis of a given structure and if it may be Jahn-Teller active or not. This is a heuristic, and may give false positives and false negatives (false positives are preferred).

Parameters:

• structure – input structure

• calculate_valences – whether to attempt to calculate valences or not, structure should have oxidation states to perform analysis (Default value = True)

• guesstimate_spin – whether to guesstimate spin state from magnetic moments or not, use with caution (Default value = False)

• op_threshold – threshold for order parameter above which to consider site to match an octahedral or tetrahedral motif, since Jahn-Teller structures can often be quite distorted, this threshold is smaller than one might expect

Returns:

analysis of structure, with key ‘strength’ which may be ‘none’, ‘strong’, ‘weak’, or ‘unknown’ (Default value = 0.1)

get_analysis_and_structure(structure: Structure, calculate_valences: bool = True, guesstimate_spin: bool = False, op_threshold: float = 0.1) → tuple[dict, Structure]

Obtain an analysis of a given structure and if it may be Jahn-Teller active or not. This is a heuristic, and may give false positives and false negatives (false positives are preferred).

Parameters:

• structure – input structure

• calculate_valences – whether to attempt to calculate valences or not, structure should have oxidation states to perform analysis (Default value = True)

• guesstimate_spin – whether to guesstimate spin state from magnetic moments or not, use with caution (Default value = False)

• op_threshold – threshold for order parameter above which to consider site to match an octahedral or tetrahedral motif, since Jahn-Teller structures can often be quite distorted, this threshold is smaller than one might expect

Returns:

analysis of structure, with key ‘strength’ which may be ‘none’, ‘strong’, ‘weak’, or ‘unknown’ (Default value = 0.1) and decorated structure

get_magnitude_of_effect_from_species(species: str | Species, spin_state: str, motif: str) → str

Get magnitude of Jahn-Teller effect from provided species, spin state and motif.

Parameters:

• species – e.g. Fe2+

• spin_state – “high” or “low”

• motif – “oct” or “tet”

Returns:

“none”, “weak” or “strong”

Return type:

str

static get_magnitude_of_effect_from_spin_config(motif: str, spin_config: dict[str, float]) → str

Roughly, the magnitude of Jahn-Teller distortion will be: * in octahedral environments, strong if e_g orbitals unevenly occupied but weak if t_2g orbitals unevenly occupied * in tetrahedral environments always weaker.

Parameters:

• motif – “oct” or “tet”

• spin_config – dict of ‘e’ (e_g) and ‘t’ (t2_g) with number of electrons in each state

Returns:

“none”, “weak” or “strong”

Return type:

str

is_jahn_teller_active(structure: Structure, calculate_valences: bool = True, guesstimate_spin: bool = False, op_threshold: float = 0.1) → bool

Convenience method, uses get_analysis_and_structure method. Check if a given structure and if it may be Jahn-Teller active or not. This is a heuristic, and may give false positives and false negatives (false positives are preferred).

Parameters:

• structure – input structure

• calculate_valences – whether to attempt to calculate valences or not, structure should have oxidation states to perform analysis (Default value = True)

• guesstimate_spin – whether to guesstimate spin state from magnetic moments or not, use with caution (Default value = False)

• op_threshold – threshold for order parameter above which to consider site to match an octahedral or tetrahedral motif, since Jahn-Teller structures can often be quite distorted, this threshold is smaller than one might expect

Returns:

True if might be Jahn-Teller active, False if not

Return type:

bool

static mu_so(species: str | Species, motif: Literal['oct', 'tet'], spin_state: Literal['high', 'low']) → float | None

Calculate the spin-only magnetic moment for a given species. Only supports transition metals.

Parameters:

• species – Species

• motif ("oct" | "tet") – Tetrahedron or octahedron crystal site coordination

• spin_state ("low" | "high") – Whether the species is in a high or low spin state

Returns:

Spin-only magnetic moment in Bohr magnetons or None if

species crystal field not defined

Return type:

float

tag_structure(structure: Structure, calculate_valences: bool = True, guesstimate_spin: bool = False, op_threshold: float = 0.1) → Structure

Convenience method, uses get_analysis_and_structure method. Add a “possible_jt_active” site property on Structure.

Parameters:

• structure – input structure

• calculate_valences – whether to attempt to calculate valences or not, structure should have oxidation states to perform analysis (Default value = True)

• guesstimate_spin – whether to guesstimate spin state from magnetic moments or not, use with caution (Default value = False)

• op_threshold – threshold for order parameter above which to consider site to match an octahedral or tetrahedral motif, since Jahn-Teller structures can often be quite distorted, this threshold is smaller than one might expect

Returns:

Decorated Structure, will be in primitive setting.