mag4.energy

DFT total-energy parsers (VASP OUTCAR, WIEN2k case.scf).

The get_energy() dispatcher returns an EnergyResult describing both the converged total energy (in eV) and a structured convergence status, which the upcoming mag4-extract CLI uses to decide whether each configuration is safe to feed into the J-extraction formulas.

Only the fields actually needed for the four-state pipeline are extracted:

the last total energy printed in the file (assumed converged);
a coarse convergence flag (the calculation finished cleanly);
for WIEN2k: the last :DIS (charge distance) value and the verbatim :DIS / :ENE lines, so the user can verify the parser picked up the right data and that the SCF converged tightly enough.

Both parsers are streaming (line-by-line) and tolerate large output files without loading them entirely into memory.

Module Attributes

RY_TO_EV

1 Rydberg in electron-volts (CODATA 2018).

Functions

`extract_vasp_energy`(outcar_path)	Parse a VASP `OUTCAR` and return its converged total energy.
`extract_vasp_gap`(outcar_path, *[, occ_tol, ...])	Band gap from the eigenvalue/occupation block at the end of a VASP OUTCAR.
`extract_wien2k_energy`(scf_path)	Parse a WIEN2k SCF file and return its converged total energy in eV.
`extract_wien2k_gap`(scf_path, *[, occ_tol, ...])	Band gap from a WIEN2k SCF file.
`get_energy`(config_dir, code[, scf_basename])	Convenience dispatcher: parse the right output for the requested code.
`read_band_gap`(config_dir, code[, ...])	Band gap (eV) + metallicity for one config, or `BandGap(None, None)`.
`read_magnetization`(config_dir, code[, ...])	Total magnetization (μ_B) for the requested code, or `None`.
`read_site_moments`(config_dir, code, ion_indices)	Per-site magnetic moments for the requested code (dispatcher).
`read_vasp_magnetization`(config_dir)	Total magnetization (μ_B) of a converged VASP run, or `None`.
`read_vasp_site_moments`(config_dir, ion_indices)	Per-ion magnetic moments (μ_B) from a VASP `OUTCAR`.
`read_wien2k_magnetization`(config_dir[, ...])	Total magnetic moment in the cell (μ_B) from the last `:MMTOT` line.

Classes

`BandGap`(gap_eV, metallic[, vbm_eV, cbm_eV, ...])	Band gap of one configuration (eV).
`EnergyResult`(energy_eV, converged, source[, ...])	Outcome of parsing one DFT output file.

mag4.energy.RY_TO_EV: float = 13.605693122994: 1 Rydberg in electron-volts (CODATA 2018).

class mag4.energy.EnergyResult(energy_eV, converged, source, n_iter=0, diagnostics=<factory>, last_dis=None, last_dis_line=None, last_ene_line=None)[source]

Bases: object

Outcome of parsing one DFT output file.

Parameters:

energy_eV (float | None)
converged (bool)
source (str)
n_iter (int)
diagnostics (List[str])
last_dis (float | None)
last_dis_line (str | None)
last_ene_line (str | None)

energy_eV

Last total energy reported in the file, expressed in eV. None when no energy could be parsed (typically: the calculation never produced one — crashed early, file truncated, etc.).

Type:: float or None

converged

Coarse convergence flag (see backend-specific notes in extract_vasp_energy() / extract_wien2k_energy()).

Type:: bool

source

Absolute path of the file that was parsed.

Type:: str

n_iter

Number of (electronic) iterations detected. 0 if unknown.

Type:: int

diagnostics

Free-form one-line warnings / notes the caller may want to surface.

Type:: list of str

energy_eV: float | None

converged: bool

source: str

n_iter: int = 0

diagnostics: List[str]

last_dis: float | None = None: Last :DIS (charge distance) numerical value, in WIEN2k units. Populated only for WIEN2k; None for VASP or when no :DIS line was matched. Useful as a tight convergence check the user can eyeball.

last_dis_line: str | None = None: Verbatim :DIS line from the SCF file (last occurrence).

last_ene_line: str | None = None: Verbatim :ENE line whose value was used as energy_eV.

mag4.energy.extract_vasp_energy(outcar_path)[source]

Parse a VASP OUTCAR and return its converged total energy.

Convergence rule (simple, code-agnostic):

converged is True when all of the following hold:

the file exists and is readable,
at least one free energy TOTEN line was parsed,
no WARNING: ... NELM = N line was emitted,
the SCF actually converged — either VASP’s electronic marker aborting loop because EDIFF is reached or the ionic reached required accuracy appears — or the run finished cleanly (Voluntary context switches:).

The clean-finish marker is sufficient but not required: a job OOM-killed or timed out during the final clean-up drops that tail without invalidating the already-converged energy, so the EDIFF marker rescues it (see diagnostics).

Tighter convergence checks (per-element forces, stress, EDIFF / EDIFFG numerical thresholds) are intentionally NOT enforced here — they vary per project; see diagnostics for the raw flags so the caller can decide what to do.

Returns:: Always non-None; check .energy_eV and .converged to interpret the outcome.
Return type:: EnergyResult
Parameters:: outcar_path (str)

mag4.energy.extract_wien2k_energy(scf_path)[source]

Parse a WIEN2k SCF file and return its converged total energy in eV.

Return type:: EnergyResult
Parameters:: scf_path (str)

Convergence rule (simple):

converged is True when all of the following hold:

the file exists and is readable,
at least one :ENE line was parsed,
at least one :ITE…: iteration block was detected,
the energy was emitted by the last iteration block of the file (i.e. the calculation didn’t crash mid-iteration).

This does not enforce a numeric threshold on :DIS (charge distance) — the value is surfaced in EnergyResult.last_dis and the verbatim :DIS line in EnergyResult.last_dis_line so the user can eyeball that the SCF converged tightly enough.

Conversion: E [eV] = E [Ry] × 13.605693122994.

mag4.energy.get_energy(config_dir, code, scf_basename=None)[source]

Convenience dispatcher: parse the right output for the requested code.

Parameters:

config_dir (str) – Path to a single configN/ directory.
code ({'vasp', 'wien2k'}) –
Which output file to look for inside config_dir:
- vasp → OUTCAR
- wien2k → SCF file (see scf_basename).
scf_basename (str, optional) – WIEN2k only. Basename (with or without the .scf suffix) of the SCF file to parse inside config_dir. Useful when several SCF runs are stored side by side under names like pbe.scf, r2scan.scf. When omitted (default) the standard WIEN2k convention <basename(config_dir)>.scf is used — i.e. config5/config5.scf for config5/.

Return type:

EnergyResult

mag4.energy.read_vasp_magnetization(config_dir)[source]

Total magnetization (μ_B) of a converged VASP run, or None.

Prefers the last mag= in OSZICAR; falls back to the OUTCAR number of electron … magnetization … line. Collinear (ISPIN=2) runs report a single scalar moment.

Return type:: Optional[float]
Parameters:: config_dir (str)

mag4.energy.read_vasp_site_moments(config_dir, ion_indices)[source]

Per-ion magnetic moments (μ_B) from a VASP OUTCAR.

Parses the last magnetization (x) block (the converged one; needs LORBIT=10/11 in the INCAR — mag4 sets LORBIT=11 by default) and returns the tot column (last field of each ion row) for the requested 1-based ion indices. Ion order follows the POSCAR; mag4 writes the magnetic atoms first, so they are ions 1 … n_mag.

Returns {ion: float or None} (None for an ion the block didn’t list, or {}-like all-None when no block/OUTCAR was found).

Return type:: Dict[int, Optional[float]]
Parameters:: config_dir (str)

mag4.energy.read_site_moments(config_dir, code, ion_indices, scf_basename=None)[source]

Per-site magnetic moments for the requested code (dispatcher).

Return type:

Dict[int, Optional[float]]

Parameters:

config_dir (str)
code (str)
scf_basename (str | None)

mag4.energy.read_wien2k_magnetization(config_dir, scf_basename=None)[source]

Total magnetic moment in the cell (μ_B) from the last :MMTOT line.

The SCF file is resolved exactly as in get_energy() (<basename(config_dir)>.scf unless scf_basename overrides it).

Return type:

Optional[float]

Parameters:

config_dir (str)
scf_basename (str | None)

mag4.energy.read_magnetization(config_dir, code, scf_basename=None)[source]

Total magnetization (μ_B) for the requested code, or None.

Return type:

Optional[float]

Parameters:

config_dir (str)
code (str)
scf_basename (str | None)

class mag4.energy.BandGap(gap_eV, metallic, vbm_eV=None, cbm_eV=None, source='', note='')[source]

Bases: object

Band gap of one configuration (eV).

gap_eV is the conduction–valence separation (0.0 when metallic); metallic is True when occupied and empty states overlap (no gap), None when the file carried no usable eigenvalue information.

Parameters:

gap_eV (float | None)
metallic (bool | None)
vbm_eV (float | None)
cbm_eV (float | None)
source (str)
note (str)

gap_eV: float | None

metallic: bool | None

vbm_eV: float | None = None

cbm_eV: float | None = None

source: str = ''

note: str = ''

mag4.energy.extract_vasp_gap(outcar_path, *, occ_tol=0.5, gap_tol=0.05)[source]

Band gap from the eigenvalue/occupation block at the end of a VASP OUTCAR.

Reads the last eigenvalue dump (after the final E-fermi line, all k-points and spin channels), splits bands into occupied (occ > occ_tol) and empty, and reports CBM − VBM. Metallic when they overlap.

Return type:

BandGap

Parameters:

outcar_path (str)
occ_tol (float)
gap_tol (float)

mag4.energy.extract_wien2k_gap(scf_path, *, occ_tol=0.5, gap_tol=0.05)[source]

Band gap from a WIEN2k SCF file.

Prefers the :GAP line (printed when lapw2 finds a gap). Otherwise — e.g. with temperature smearing — uses the Bandranges / :BANnnnnn block: VBM = highest emax of an occupied band (occ > occ_tol), CBM = lowest emin of an empty band; energies are in Ry and converted to eV.

Return type:

BandGap

Parameters:

scf_path (str)
occ_tol (float)
gap_tol (float)

mag4.energy.read_band_gap(config_dir, code, scf_basename=None, *, gap_tol=0.05)[source]

Band gap (eV) + metallicity for one config, or BandGap(None, None).

Return type:

BandGap

Parameters:

config_dir (str)
code (str)
scf_basename (str | None)
gap_tol (float)