API reference

This section provides an overview of all core classes and functions and then expands each module with full per-member documentation.

Classes overview

Class	Purpose
pymkmkit.network_reader.State	Immutable thermodynamic-state container used for energy and ZPE lookup.
pymkmkit.network_reader.ElementaryStep	Immutable container for evaluated forward/reverse barriers and reaction heats.
pymkmkit.network_reader.ReactionPath	Immutable container for net reaction energy of a named pathway.
pymkmkit.yaml_writer.InlineList	List subclass that forces flow-style YAML rendering.

Functions overview

pymkmkit._version.get_version()	Return the installed package version.
pymkmkit.vasp_freq.extract_incar_settings(text)	Extract selected INCAR parameters from OUTCAR text.
pymkmkit.vasp_freq.extract_potcar_info(text)	Extract unique POTCAR descriptors from OUTCAR text.
pymkmkit.vasp_freq.extract_ionic_energies(text)	Extract ionic-step electronic energies from OUTCAR text.
pymkmkit.vasp_freq.extract_total_energies(text)	Extract free energies (TOTEN) from OUTCAR text.
pymkmkit.vasp_freq.extract_frequencies(text)	Extract vibrational frequencies from OUTCAR.
pymkmkit.vasp_freq.extract_perturbed_hessian(text)	Extract the perturbed Hessian block from OUTCAR.
pymkmkit.vasp_freq.frequencies_from_partial_hessian(...)	Recover vibrational frequencies from a partial Hessian matrix.
pymkmkit.vasp_freq.formula_from_atom_order(atoms)	Build a chemical formula preserving first-seen element order.
pymkmkit.vasp_freq.lattice_vectors(atoms[, ...])	Return lattice vectors rounded for stable YAML serialization.
pymkmkit.vasp_freq.geometry_direct_strings(atoms)	Return fractional coordinates as list of strings.
pymkmkit.vasp_freq.parse_vasp_frequency(...)	Parse a VASP frequency OUTCAR file into pymkmkit YAML schema.
pymkmkit.vasp_freq.parse_vasp_optimization(...)	Parse a VASP optimization OUTCAR file into pymkmkit YAML schema.
pymkmkit.vasp_freq.average_mode_pairs(...)	Average real frequencies in sequential pairs (1+2, 3+4, ...).
pymkmkit.yaml_writer.represent_inline_list(...)	Serialize InlineList values in YAML flow style.
pymkmkit.yaml_writer.clean_none(d)	Recursively remove keys/items whose value is None.
pymkmkit.yaml_writer.write_yaml(data, filename)	Write parser output to YAML while preserving intended formatting.
pymkmkit.network_reader.read_network(...)	Parse a network YAML file into evaluated elementary-step objects.
pymkmkit.network_reader.evaluate_paths(...)	Calculate net reaction energies for each named pathway in a network.
pymkmkit.network_reader.build_ped(...[, ...])	Build and optionally save a potential energy diagram for a path.

Module details

pymkmkit.vasp_freq

pymkmkit.vasp_freq.extract_incar_settings(text)

Extract selected INCAR parameters from OUTCAR text.

Parameters:

text (str) – Full OUTCAR content.

Returns:

Mapping of key INCAR tags to parsed values.

Return type:

dict

pymkmkit.vasp_freq.extract_hubbard_u_settings(text)

Extract LDA+U settings from OUTCAR text.

pymkmkit.vasp_freq.extract_potcar_info(text)

Extract unique POTCAR descriptors from OUTCAR text.

pymkmkit.vasp_freq.extract_vasp_version(text)

Extract the VASP version string from OUTCAR text.

pymkmkit.vasp_freq.extract_execution_timestamp(text)

Extract the VASP execution date-time from OUTCAR text in UTC-like format.

pymkmkit.vasp_freq.extract_ionic_energies(text)

Extract ionic-step electronic energies from OUTCAR text.

pymkmkit.vasp_freq.extract_total_energies(text)

Extract free energies (TOTEN) from OUTCAR text.

pymkmkit.vasp_freq.extract_frequencies(text)

Extract vibrational frequencies from OUTCAR.

VASP prints the frequency list twice. We detect the repetition by checking when the mode index restarts at 1 and stop reading.

pymkmkit.vasp_freq.extract_perturbed_hessian(text)

Extract the perturbed Hessian block from OUTCAR.

Returns:

DOF labels and Hessian matrix values for the perturbed coordinates.

Return type:

tuple[list[str], list[list[float]]] | (None, None)

pymkmkit.vasp_freq.extract_hessian_from_dynamical_modes(text, atoms)

Reconstruct Hessian from OUTCAR dynamical-mode eigenpairs.

This is a fallback for calculations where VASP prints only the Eigenvectors and eigenvalues of the dynamical matrix section (and no explicit SECOND DERIVATIVES block).

pymkmkit.vasp_freq.frequencies_from_partial_hessian(dof_labels, hessian_matrix, atoms)

Recover vibrational frequencies from a partial Hessian matrix.

Parameters:

• dof_labels (list[str]) – Degree-of-freedom labels (for example 1X).

• hessian_matrix (list[list[float]]) – Hessian values in eV/Ų units for selected DOFs.

• atoms (ase.Atoms) – Atomic structure used to assign atomic masses.

Returns:

Frequencies in cm⁻¹ sorted in descending order.

Return type:

list[float]

pymkmkit.vasp_freq.extract_ase_vibration_hessian(outcar_path, delta=0.01)

Extract a merged partial Hessian from ASE vibration cache folders.

pymkmkit.vasp_freq.formula_from_atom_order(atoms)

Build a chemical formula preserving first-seen element order.

pymkmkit.vasp_freq.lattice_vectors(atoms, precision=8)

Return lattice vectors rounded for stable YAML serialization.

pymkmkit.vasp_freq.geometry_direct_strings(atoms, precision=8)

Return fractional coordinates as list of strings.

Using strings avoids YAML ambiguity and keeps diffs clean.

pymkmkit.vasp_freq.parse_vasp_frequency(outcar_path, average_pairs=False)

Parse a VASP frequency OUTCAR file into pymkmkit YAML schema.

Parameters:

• outcar_path (str | pathlib.Path) – Path to the input OUTCAR file.

• average_pairs (bool, default=False) – If True, average vibrational modes in sequential pairs.

Returns:

Structured dictionary ready to be serialized to YAML.

Return type:

dict

pymkmkit.vasp_freq.parse_vasp_optimization(outcar_path)

Parse a VASP optimization OUTCAR file into pymkmkit YAML schema.

pymkmkit.vasp_freq.parse_ase_vibrations(outcar_path)

Parse ASE vibration cache folders plus OUTCAR geometry into YAML schema.

pymkmkit.vasp_freq.average_mode_pairs(real_freqs, imag_freqs)

Average real frequencies in sequential pairs (1+2, 3+4, …).

TS edge case: If number of real modes is odd and exactly one imaginary mode exists, drop the last unpaired real mode and proceed.

pymkmkit.network_reader

class pymkmkit.network_reader.State(name, file, electronic_energy, zpe_energy, paired_modes_averaged)

Bases: object

Thermodynamic state used in network energy bookkeeping.

Data fields:

• name: state identifier referenced by network reaction terms.

• file: resolved path to the source YAML file for this state.

• electronic_energy: electronic energy in eV from energy.electronic.

• zpe_energy: zero-point energy contribution in eV from vibrations.

• paired_modes_averaged: whether pair-averaged vibrational modes were used.

Parameters:

• name (str)

• file (Path)

• electronic_energy (float)

• zpe_energy (float)

• paired_modes_averaged (bool)

name: str

file: Path

electronic_energy: float

zpe_energy: float

paired_modes_averaged: bool

class pymkmkit.network_reader.ElementaryStep(name, step_type, reaction, forward_equation, reverse_equation, forward_barrier_electronic, reverse_barrier_electronic, forward_zpe_correction, reverse_zpe_correction, forward_total_barrier, reverse_total_barrier, reaction_heat_electronic, reaction_heat_zpe_correction, reaction_heat_total)

Bases: object

Evaluated energetic quantities for one elementary reaction step.

Data fields include the step identity and reaction string, the symbolic forward/reverse equations used in the calculations, forward/reverse electronic and ZPE terms, and net reaction-heat terms in eV.

Parameters:

• name (str)

• step_type (str)

• reaction (str)

• forward_equation (str)

• reverse_equation (str)

• forward_barrier_electronic (float)

• reverse_barrier_electronic (float)

• forward_zpe_correction (float)

• reverse_zpe_correction (float)

• forward_total_barrier (float)

• reverse_total_barrier (float)

• reaction_heat_electronic (float)

• reaction_heat_zpe_correction (float)

• reaction_heat_total (float)

name: str

step_type: str

reaction: str

forward_equation: str

reverse_equation: str

forward_barrier_electronic: float

reverse_barrier_electronic: float

forward_zpe_correction: float

reverse_zpe_correction: float

forward_total_barrier: float

reverse_total_barrier: float

reaction_heat_electronic: float

reaction_heat_zpe_correction: float

reaction_heat_total: float

class pymkmkit.network_reader.ReactionPath(name, total_reaction_energy)

Bases: object

Aggregated energy result for a named reaction pathway.

Data fields:

• name: path identifier from the paths section.

• total_reaction_energy: sum of factor-weighted step heats in eV.

Parameters:

• name (str)

• total_reaction_energy (float)

name: str

total_reaction_energy: float

pymkmkit.network_reader.read_network(network_file)

Parse a network YAML file into evaluated elementary-step objects.

Parameters:

network_file (str | Path)

Return type:

list[ElementaryStep]

pymkmkit.network_reader.evaluate_paths(network_file)

Calculate net reaction energies for each named pathway in a network.

Parameters:

network_file (str | Path)

Return type:

list[ReactionPath]

pymkmkit.network_reader.build_fnf(network_file, *, unit='ev', include_warnings=False, split=False, node_structures=None, transition_structures=None)

Build a formatted-network-file (FNF) payload from a network YAML file.

Parameters:

• network_file (str | Path)

• unit (str)

• include_warnings (bool)

• split (bool)

• node_structures (dict[str, str] | None)

• transition_structures (dict[str, str] | None)

Return type:

dict | tuple[dict, list[str]]

pymkmkit.network_reader.build_ped(network_file, path_name, output_file=None)

Build and optionally save a potential energy diagram for a path.

Parameters:

• network_file (str | pathlib.Path) – Network definition file.

• path_name (str) – Path identifier under paths in the network YAML.

• output_file (str | pathlib.Path | None) – Image output path. When None, the plot is displayed interactively.

Return type:

None

pymkmkit.yaml_writer

class pymkmkit.yaml_writer.InlineList(iterable=(), /)

Bases: list

Force YAML to print list in flow style.

pymkmkit.yaml_writer.represent_inline_list(dumper, data)

Serialize InlineList values in YAML flow style.

Parameters:

• dumper (yaml.Dumper) – Active PyYAML dumper instance.

• data (InlineList) – Sequence to render.

Returns:

YAML node representation of the list.

Return type:

yaml.nodes.SequenceNode

pymkmkit.yaml_writer.clean_none(d)

Recursively remove keys/items whose value is None.

Parameters:

d (Any) – Arbitrary Python data structure destined for YAML output.

Returns:

Cleaned structure with None entries removed while preserving InlineList instances.

Return type:

Any

pymkmkit.yaml_writer.write_yaml(data, filename)

Write parser output to YAML while preserving intended formatting.

Parameters:

• data (dict) – Data structure to serialize.

• filename (str | pathlib.Path) – Target YAML file path.

pymkmkit._version

pymkmkit._version.get_version()

Return the installed package version.

Returns:

Installed pymkmkit version string, or "unknown" when the distribution metadata cannot be resolved (for example in editable or source-only environments).

Return type:

str