Skip to content

API Reference

Parsing functions

parse_dos(path: Path | str) -> DOSResult

Parse an AkaiKKR DOS output file.

Parameters:

Name Type Description Default

path

Path | str

Path to the DOS output file.

 required

Returns:

Type Description
DOSResult

The parsed DOS result.

parse_go(path: Path | str) -> GOResult

Parse an AkaiKKR GO output file.

Parameters:

Name Type Description Default

path

Path | str

Path to the GO output file.

 required

Returns:

Type Description
GOResult

The parsed GO result.

parse_spc(path: Path | str, *, base_dir: Path | str | None = None, data_up: Path | str | None = None, data_down: Path | str | None = None) -> SPCResult

Parse an AkaiKKR SPC output file.

Spectral function data files (*_up.spc, *_dn.spc) are located automatically by appending _up.spc / _dn.spc to input_params.file and resolving from base_dir. Supply data_up or data_down to override either path explicitly.

Parameters:

Name Type Description Default

path

Path | str

Path to the SPC log file.

 required

base_dir

Path | str | None

Directory from which input_params.file is resolved to auto-locate the spectral function data files. Defaults to the log file's parent directory.

 None

data_up

Path | str | None

Explicit path to the spin-up spectral function data file.

 None

data_down

Path | str | None

Explicit path to the spin-down spectral function data file.

 None

Returns:

Type Description
SPCResult

The parsed SPC result.

Input file generation

InputFile dataclass

An AkaiKKR input file.

Can be constructed directly from individual parameters or reconstructed from any parsed CalculationResult via from_result(). Call to_string() to render the free-column text that AkaiKKR expects, or write() to save it to disk.

Attributes:

Name Type Description
mode str

Calculation mode — "go", "dos", or "spc".
data_file str

Data file prefix written to the second line of the input (e.g. "data/fe").
bravais str

Bravais lattice type (e.g. "bcc", "fcc", "hexagonal").
a float

Lattice constant in bohr.
atom_types list[AtomType]

Ordered list of site-type definitions. Component concentrations must be fractions (0–1) and must sum to 1.0 per type.
positions list[AtomPosition]

Ordered list of fractional atomic positions.
c_over_a float

c/a ratio. Rendered as "," (AkaiKKR default) when equal to 1.0.
b_over_a float

b/a ratio. Same convention as c_over_a.
alpha float

α lattice angle in degrees. Rendered as "," when 90.0.
beta float

β lattice angle in degrees. Same convention.
gamma float

γ lattice angle in degrees. Same convention.
edelt float

Energy mesh spacing in Ry.
ewidth float

Energy window half-width in Ry.
reltyp str

Relativistic approximation ("nrl", "sra", "fra").
sdftyp str

Exchange-correlation functional (e.g. "mjwasa", "mjw", "ggapw").
magtyp str

Magnetic treatment — "mag" or "nmag".
record str

Record type — "2nd" or "1st".
outtyp str

Output type — "update" or "quit".
bzqlty int

Brillouin zone mesh quality (integer).
maxitr int

Maximum number of SCF iterations.
pmix float

Mixing parameter.
title str

Optional comment placed on the first line. Auto-derived from bravais and the first atom-type name when empty.
kpath KPath | None

k-point path for Bloch spectral function calculations. Must be None unless mode is "spc".

__post_init__() -> None

Validate field consistency after construction.

Raises:

Type Description
InputValidationError

If any field violates a structural constraint.

from_result(result: CalculationResult, *, mode: str | None = None, kpath: KPath | None = None, reset_rmt: bool = False) -> InputFile classmethod

Reconstruct an InputFile from a parsed AkaiKKR result.

All scalar parameters are taken from result.input_params. Atom types and positions are copied from the result, with an option to reset the muffin-tin radii to zero so AkaiKKR recomputes them.

Parameters:

Name Type Description Default

result

CalculationResult

Any parsed calculation result (GO, DOS, or SPC).

 required

mode

str | None

Override the calculation mode. Defaults to the mode recorded in result.input_params.go.

 None

kpath

KPath | None

k-point path for SPC calculations. Only valid when mode is "spc".

 None

reset_rmt

bool

When True, sets every muffin-tin radius to 0.0 so AkaiKKR recomputes it automatically on the next run. Defaults to False, which preserves the radii exactly as they appear in the parsed result.

 False

Returns:

Type Description
InputFile

A new InputFile ready to render or further modify.

Raises:

Type Description
InputValidationError

If the resolved mode is not a valid AkaiKKR mode.

to_string() -> str

Render the input file as a string in AkaiKKR free-column format.

Returns:

Type Description
str

The complete input file text, terminated by a newline.

write(path: Path | str) -> None

Write the rendered input file to disk.

Parameters:

Name Type Description Default

path

Path | str

Destination file path. Parent directories must exist.

 required

KPath dataclass

A sequence of high-symmetry k-points for a band-structure calculation.

Attributes:

Name Type Description
nkpts int

Total number of k-points sampled along the full path.
points list[KPoint]

Ordered list of high-symmetry k-points defining the path.

KPoint dataclass

One high-symmetry k-point on a band-structure path.

Coordinates are stored as strings to preserve fractional notation (e.g. "1/2", "3/4"), which AkaiKKR reads directly from the input file.

Attributes:

Name Type Description
x str

First reciprocal-lattice coordinate (e.g. "0", "1/2").
y str

Second reciprocal-lattice coordinate.
z str

Third reciprocal-lattice coordinate.
label str | None

Optional human-readable Brillouin-zone label (e.g. "Γ", "H"). Stored for annotation purposes only — not written to the AkaiKKR input file.

DOS result

DOSResult dataclass

Parsed result from an AkaiKKR DOS output file.

Attributes:

Name Type Description
dos_components list[DOSComponent]

All parsed DOS blocks — spin-up entries first, spin-down second.
total_up DOSCurve | None

Total DOS curve for the spin-up channel, when present.
total_down DOSCurve | None

Total DOS curve for the spin-down channel, when present.
integrated_up DOSCurve | None

Integrated DOS curve for the spin-up channel, when present.
integrated_down DOSCurve | None

Integrated DOS curve for the spin-down channel, when present.
atomic_properties list[AtomicProperties]

Per-(type, component) electronic and magnetic properties.

spin_down: list[DOSComponent] property

Return all spin-down DOS components in component-index order.

spin_up: list[DOSComponent] property

Return all spin-up DOS components in component-index order.

get(component_index: int, spin: str) -> DOSComponent | None

Return one DOS component by component index and spin.

Parameters:

Name Type Description Default

component_index

int

One-based DOS component index.

 required

spin

str

Spin channel — "up" or "down".

 required

Returns:

Type Description
DOSComponent | None

The matching DOS component, or None if not found.
Notes

This is a compatibility alias for get_component().

get_component(component_index: int, spin: str) -> DOSComponent | None

Return one DOS component by component index and spin.

Parameters:

Name Type Description Default

component_index

int

One-based DOS component index.

 required

spin

str

Spin channel — "up" or "down".

 required

Returns:

Type Description
DOSComponent | None

The matching DOS component, or None if not found.

select(*, component_index: int | None = None, type_name: str | None = None, symbol: str | None = None, label: str | None = None, spin: str | None = None) -> list[DOSComponent]

Return DOS components matching the provided filters.

Parameters:

Name Type Description Default

component_index

int | None

Optional one-based DOS component index filter.

 None

type_name

str | None

Optional AkaiKKR site-type filter.

 None

symbol

str | None

Optional chemical symbol filter.

 None

label

str | None

Optional public component-label filter.

 None

spin

str | None

Optional spin-channel filter.

 None

Returns:

Type Description
list[DOSComponent]

All components satisfying the provided filters.

to_dataframe() -> pd.DataFrame

Convert all DOS components to one pandas DataFrame.

Returns:

Type Description
DataFrame

A DataFrame with one row per DOS point and columns for component
DataFrame

metadata, spin, energy, orbital projections, and total DOS.

DOSComponent dataclass

Density of states for one CPA component and spin channel.

Attributes:

Name Type Description
component_index int

One-based component index from DOS of component N.
type_name str

AkaiKKR site-type name for this component.
symbol str

Chemical element symbol for this component.
label str

User-facing component label. This is type_name for pure sites and type_name:symbol for CPA-mixed sites.
spin str

Spin channel — "up" or "down".
energy ndarray

Real-axis energy points, shape (n_points,), in Ry.
s ndarray

s-orbital projected DOS in states/Ry/cell, shape (n_points,).
p ndarray

p-orbital projected DOS in states/Ry/cell.
d ndarray

d-orbital projected DOS in states/Ry/cell.
total ndarray

Total local DOS in states/Ry/cell (sum of all orbital channels).
f ndarray | None

f-orbital projected DOS in states/Ry/cell; None when lmxtyp < 3.

d_ev: np.ndarray property

d-orbital projected DOS in states/eV/cell.

Returns:

Type Description
ndarray

d-orbital DOS converted from states/Ry/cell to states/eV/cell.

element: str property

Return the chemical symbol.

Returns:

Type Description
str

The chemical element symbol.

energy_ev: np.ndarray property

Energy array in eV.

Returns:

Type Description
ndarray

Real-axis energy points converted from Ry to eV, shape (n_points,).

f_ev: np.ndarray | None property

f-orbital projected DOS in states/eV/cell; None when lmxtyp < 3.

Returns:

Type Description
ndarray | None

f-orbital DOS converted from states/Ry/cell to states/eV/cell,
ndarray | None

or None if f-orbital data is absent.

p_ev: np.ndarray property

p-orbital projected DOS in states/eV/cell.

Returns:

Type Description
ndarray

p-orbital DOS converted from states/Ry/cell to states/eV/cell.

s_ev: np.ndarray property

s-orbital projected DOS in states/eV/cell.

Returns:

Type Description
ndarray

s-orbital DOS converted from states/Ry/cell to states/eV/cell.

total_ev: np.ndarray property

Total local DOS in states/eV/cell.

Returns:

Type Description
ndarray

Total DOS converted from states/Ry/cell to states/eV/cell.

to_dataframe() -> pd.DataFrame

Convert this component's DOS data to a pandas DataFrame.

Returns:

Type Description
DataFrame

A DataFrame with one row per energy point and columns for
DataFrame

component metadata, orbital-resolved DOS, and total DOS.

SCF result

GOResult dataclass

Parsed result from an AkaiKKR GO output file.

to_dataframe() -> pd.DataFrame

Convert SCF iteration history to a pandas DataFrame.

Returns:

Type Description
DataFrame

A DataFrame with one row per iteration and columns for iteration
DataFrame

number, charge neutrality, magnetic moment, total energy, and
DataFrame

RMS error.

GOIteration dataclass

Data from one self-consistent field iteration.

total_energy_ev: float property

Total energy in eV.

Returns:

Type Description
float

Total energy converted from Ry to eV.

SPC result

SPCResult dataclass

Parsed result from an AkaiKKR SPC output file.

Attributes:

Name Type Description
spc_params SPCParams

SPC-specific parameters from the ***msg in spmain block.
iteration GOIteration | None

The single SCF iteration recorded in the file, or None if the iteration block is absent.
spectral_up SpectralFunction | None

Spin-up Bloch spectral function, or None if the corresponding data file was not found.
spectral_down SpectralFunction | None

Spin-down Bloch spectral function, or None if the corresponding data file was not found.

SPCParams dataclass

SPC-specific computational parameters from the ***msg in spmain block.

SpectralFunction dataclass

Bloch spectral function for one spin channel.

Attributes:

Name Type Description
spin str

Spin channel — "up" or "down".
kmesh KMeshInfo

k-mesh and energy-mesh metadata from the file header.
data ndarray | None

BSF intensity matrix of shape (n_energy, n_kpoints). None when n_sym_points == 0 (no k-path was computed).

KMeshInfo dataclass

k-mesh and energy-mesh metadata from a spectral function data file header.

Shared data models

AtomicProperties dataclass

Complete electronic properties for one (type, component) pair.

ValenceCharge dataclass

Orbital-resolved valence charge for one spin channel.

HyperfineField dataclass

Hyperfine magnetic field at the nucleus.

ChargeDensityAtNucleus dataclass

Charge density at the nuclear site.

LatticeInfo dataclass

Bravais lattice and cell geometry.

AtomType dataclass

One site type, potentially a CPA alloy mixture.

AtomicComponent dataclass

One chemical component within a mixed (CPA) site.

AtomPosition dataclass

Fractional position of an atom in the unit cell.

CoreConfig dataclass

Electronic core configuration for one atomic species.

EnergyPoint dataclass

One point in the complex energy mesh.

InputParams dataclass

Parameters from the 'data read in' header block.

SystemInfo dataclass

Computational environment and timing information.

Errors

ParseError

Signal that a file cannot be parsed as a supported AkaiKKR output.

This exception is raised when a required section is missing or when a section is present but malformed.

InvalidParameterError

Signal that a function was called with an unsupported argument value.

This exception is raised when a caller passes a value that is not in the set of accepted choices for a parameter (e.g. an unknown energy unit, spin channel, orbital name, or convergence field).

InputValidationError

Signal that an InputFile was constructed with invalid parameters.

This exception is raised when field values are structurally inconsistent — for example, an empty atom-type list, component concentrations that do not sum to 1.0, a position referencing an undefined type name, or a k-path supplied for a non-SPC mode.

The field attribute names the offending field so callers can programmatically distinguish which constraint was violated.

Attributes:

Name Type Description
field

Dot/bracket notation identifying the invalid field (e.g. "mode", "atom_types[NiFe].components").

__init__(field: str, message: str) -> None

Initialise the exception with the offending field name and a message.

Parameters:

Name Type Description Default

field

str

Dot/bracket notation identifying the invalid field (e.g. "mode", "atom_types[NiFe].components").

 required

message

str

Human-readable description of the constraint violation.

 required

Plotting

plot_dos(result: DOSResult, *, ef: float = 0.0, components: list[int] | None = None, system_total: bool = True, spin: str | None = None, orbitals: list[str] | None = None, energy_unit: str = 'Ry', figsize: tuple[float, float] = (3.4, 2.6)) -> Figure

Plot density of states curves.

Parameters:

Name Type Description Default

result

DOSResult

Parsed DOS result.

 required

ef

float

Fermi energy in Ry, subtracted from the energy axis.

 0.0

components

list[int] | None

Component indices to plot. Defaults to all components.

 None

system_total

bool

Add the total system DOS on top of the component curves.

 True

spin

str | None

Spin channel to plot — "up", "down", or None for both.

 None

orbitals

list[str] | None

Which orbital DOS to include, any subset of ["s", "p", "d", "f", "total"]. Defaults to ["total"]. Pass [] to hide component curves and show only system_total.

 None

energy_unit

str

"Ry" or "eV" (converts with 1 Ry = 13.6057 eV).

 'Ry'

figsize

tuple[float, float]

Matplotlib figure size (width, height) in inches.

 (3.4, 2.6)

Returns:

Type Description
Figure

The populated Matplotlib figure.

plot_convergence(result: GOResult, *, field: str = 'rms_error', figsize: tuple[float, float] = (3.4, 2.6)) -> Figure

Plot GO convergence history.

Parameters:

Name Type Description Default

result

GOResult

Parsed GO result.

 required

field

str

Which iteration field to plot — "rms_error", "moment", "total_energy", "total_energy_ev", or "neu".

 'rms_error'

figsize

tuple[float, float]

Matplotlib figure size (width, height) in inches.

 (3.4, 2.6)

Returns:

Type Description
Figure

The populated Matplotlib figure.

Parser classes

These are used internally by parse_dos(), parse_go(), and parse_spc(). You can instantiate them directly if you need finer control over the parsing process.

DOSParser

Parse AkaiKKR DOS and DSP output files.

parse(path: Path | str) -> DOSResult

Parse an AkaiKKR DOS or DSP output file.

Parameters:

Name Type Description Default

path

Path | str

Path to the DOS or DSP output file.

 required

Returns:

Type Description
DOSResult

The parsed DOS result.

GOParser

Parse AkaiKKR GO output files.

parse(path: Path | str) -> GOResult

Parse an AkaiKKR GO output file.

Parameters:

Name Type Description Default

path

Path | str

Path to the GO output file.

 required

Returns:

Type Description
GOResult

The parsed GO result.

SPCParser

Parse AkaiKKR SPC output files.

parse(path: Path | str, *, base_dir: Path | str | None = None, data_up: Path | str | None = None, data_down: Path | str | None = None) -> SPCResult

Parse an AkaiKKR SPC log file and optional spectral function data.

Spectral function data files (*_up.spc, *_dn.spc) are located automatically by appending _up.spc / _dn.spc to input_params.file and resolving from base_dir. Supply data_up or data_down to override either path explicitly.

Parameters:

Name Type Description Default

path

Path | str

Path to the SPC log file.

 required

base_dir

Path | str | None

Directory from which input_params.file is resolved to auto-locate the spectral function data files. Defaults to the log file's parent directory.

 None

data_up

Path | str | None

Explicit path to the spin-up spectral function data file; overrides auto-discovery.

 None

data_down

Path | str | None

Explicit path to the spin-down spectral function data file; overrides auto-discovery.

 None

Returns:

Type Description
SPCResult

The parsed SPC result. spectral_up / spectral_down are
SPCResult

None when their data files cannot be found.

Raises:

Type Description
ParseError

If the log file is missing required sections.