qimpy.dft.ions.Ions

class Ions(*, checkpoint_in=(None, ''), lattice, fractional=True, coordinates=None, pseudopotentials=None)

Bases: TreeNode

Ionic system: ionic geometry and pseudopotentials.

Parameters:

checkpoint_in (CheckpointPath) –
lattice (Lattice) –
fractional (bool) –
coordinates (Optional[list]) –
pseudopotentials (list[Pseudopotential]) –

__init__(*, checkpoint_in=(None, ''), lattice, fractional=True, coordinates=None, pseudopotentials=None)

Initialize geometry and pseudopotentials.

Parameters:

fractional (bool) – [Input file] Whether to use fractional coordinates for input/output. Note that positions in memory and checkpoint files are always fractional.
coordinates (list | None) –
[Input file] List of [symbol, x, y, z, args] for each ion in unit cell. Here, symbol is the chemical symbol of the element, while x, y and z are positions in fractional or Cartesian coordinates for fractional = True or False respectively. Optional args is a dictionary of additional per-ion parameters that may include:
- Q: initial oxidation state / charge for the ion. This can be used to tune initial density for LCAO, or to specify charge disproportionation for symmetry detection.
- M: initial magnetic moment for the ion, which would be a single Mz or [Mx, My, Mz] depending on if the calculation is spinorial. Only specify in spin-polarized calculations. This can be used to tune initial magnetization for LCAO, or to specify magnetic order for symmetry detection.
- v: initial velocities [vx, vy, vz] in Cartesian coordinates.
- Relaxation constraints: TODO
Ions of the same type (symbol) must be specified consecutively.
pseudopotentials (str | list[str] | None) – [Input file] Pseudopotential filenames or filename templates. Templates for families of pseudopotentials are specified by including a $ID in the name which is replaced by the chemical symbol of the element. The list of specified file names and templates is processed in order, and the first match for each element takes precedence.
checkpoint_in (CheckpointPath) –
lattice (Lattice) –

Return type:

None

Methods

`__init__`	Initialize geometry and pseudopotentials.
`accumulate_geometry_grad`	Accumulate geometry gradient contributions of total energy.
`add_child`	Construct child object self.`attr_name` of type cls.
`add_child_one_of`	Invoke add_child on one of several child options in args.
`get_atomic_density`	Get atomic reference density (for LCAO) on grid.
`get_atomic_orbital_index`	Get ion index and quantum numbers of atomic orbitals.
`get_atomic_orbitals`	Get atomic orbitals (across all species) for specified basis.
`n_atomic_orbitals`	Total number of atomic orbitals.
`report`	Report ionic positions / attributes, and optionally forces if report_grad.
`save_checkpoint`	Save self and all children in hierarchy to cp_path.
`translation_phase`	Get translation phases at iG for a slice of atoms.
`update`	Update ionic potentials, projectors and energy components.

Attributes

`forces`	Cartesian forces [in Eh/a0] of each ion (n_ions x 3).
`labeled_positions`	Labeled positions for symmetry detection.
`n_orbital_projectors`	Total number of projectors used to generate atomic orbitals.
`n_projectors`	Total number of pseudopotential projectors.
`n_replicas`	Number of replicas used in future NEB / phonons support.
`lattice`	Lattice vectors of corresponding unit cell
`fractional`	use fractional coordinates in input/output
`n_ions`	number of ions
`n_types`	number of distinct ion types
`n_ions_type`	number of ions of each type
`symbols`	symbol for each ion type
`slices`	slice to get each ion type
`pseudopotentials`	pseudopotential for each type
`positions`	fractional positions of each ion (n_ions x 3)
`velocities`	Cartesian velocities of each ion (n_ions x 3)
`types`	type of each ion (n_ions, int)
`Q`	initial / Lowdin charge (oxidation state) for each ion
`M`	initial / Lowdin magnetic moment for each ion
`Z`	charge of each ion type (n_types, float)
`Z_tot`	total ionic charge
`rho_tilde`	ionic charge density (uses coulomb.ion_width)
`Vloc_tilde`	local potential due to ions (including from rho)
`n_core_tilde`	partial core electronic density (for XC)
`beta`	pseudopotential projectors (split-basis only)
`beta_full`	full-basis version of beta
`beta_version`	version of beta to invalidate cached projections
`D_all`	nonlocal pseudopotential matrix (all atoms)
`dEtot_drho_basis`	dE/d(basis function density) for Pulay correction
`child_names`	Names of attributes with child objects.

accumulate_geometry_grad(system)

Accumulate geometry gradient contributions of total energy. Each contribution is accumulated to a grad attribute, only if the corresponding requires_grad is enabled. Force contributions are collected in self.positions.grad. Stress contributions are collected in system.lattice.grad. Assumes Hellman-Feynman theorem, i.e., electronic system must be converged. Note that this invokes system.electrons.accumulate_geometry_grad as a dependency and therefore includes electronic force / stress contributions.

Parameters:

self (Ions) –
system (System) –

Return type:

None

get_atomic_density(grid, n_electrons, M_tot)

Get atomic reference density (for LCAO) on grid. The overall norm / charge of the generated density is set by n_electrons. The magnetization mode and overall magnitude is set by M_tot.

Parameters:

self (Ions) –
grid (Grid) –
n_electrons (float) –
M_tot (Tensor) –

Return type:

FieldH

get_atomic_orbital_index(basis)

Get ion index and quantum numbers of atomic orbitals. The result is an n_orbitals x 5 integer tensor, with ion index as the first column. For non-spinorial pseudopotentials, the remaining columns are (n, l, m, 0) in non-spinorial calculations, and (n, l, m, 2m_s) in spinorial calculations. For spinorial pseudopotentials, the remaining columns are (n, l, 2j, 2m_j).

Parameters:

self (Ions) –
basis (Basis) –

Return type:

Tensor

get_atomic_orbitals(basis)

Get atomic orbitals (across all species) for specified basis.

Parameters:

self (Ions) –
basis (Basis) –

Return type:

Wavefunction

n_atomic_orbitals(n_spinor)

Total number of atomic orbitals. This depends on the number of spinorial components n_spinor.

Parameters:: n_spinor (int) –
Return type:: int

report(report_grad)

Report ionic positions / attributes, and optionally forces if report_grad.

Parameters:: report_grad (bool) –
Return type:: None

translation_phase(iG, atom_slice=slice(None, None, None))

Get translation phases at iG for a slice of atoms. The result has atoms as the final dimension; summing over that dimension yields the structure factor corresponding to these atoms.

Parameters:

iG (Tensor) –
atom_slice (slice) –

Return type:

Tensor

update(system)

Update ionic potentials, projectors and energy components. The grids used for the potentials are derived from system, and the energy components are stored within system.E.

Parameters:

self (Ions) –
system (System) –

Return type:

None

D_all: Tensor: nonlocal pseudopotential matrix (all atoms)

M: Tensor | None: initial / Lowdin magnetic moment for each ion

Q: Tensor | None: initial / Lowdin charge (oxidation state) for each ion

Vloc_tilde: FieldH: local potential due to ions (including from rho)

Z: Tensor: charge of each ion type (n_types, float)

Z_tot: float: total ionic charge

beta: Wavefunction: pseudopotential projectors (split-basis only)

beta_full: Wavefunction | None: full-basis version of beta

beta_version: int: version of beta to invalidate cached projections

dEtot_drho_basis: float: dE/d(basis function density) for Pulay correction

property forces: Tensor: Cartesian forces [in Eh/a0] of each ion (n_ions x 3). This converts from the fractional energy gradient in positions.grad, which should have already been calculated.

fractional: bool: use fractional coordinates in input/output

property labeled_positions: LabeledPositions | None: Labeled positions for symmetry detection.

lattice: Lattice: Lattice vectors of corresponding unit cell

n_core_tilde: FieldH: partial core electronic density (for XC)

n_ions: int: number of ions

n_ions_type: list[int]: number of ions of each type

property n_orbital_projectors: int: Total number of projectors used to generate atomic orbitals.

property n_projectors: int: Total number of pseudopotential projectors.

property n_replicas: int: Number of replicas used in future NEB / phonons support.

n_types: int: number of distinct ion types

positions: Tensor: fractional positions of each ion (n_ions x 3)

pseudopotentials: list[Pseudopotential]: pseudopotential for each type

rho_tilde: FieldH: ionic charge density (uses coulomb.ion_width)

slices: list[slice]: slice to get each ion type

symbols: list[str]: symbol for each ion type

types: Tensor: type of each ion (n_ions, int)

velocities: Tensor | None: Cartesian velocities of each ion (n_ions x 3)