httk.workflow.vasp

Small, dependency-free VASP runner helpers for native v2 workflows.

This is an independent, data-oriented interface rather than a port of the historic VASP_* Python or shell APIs. Historical authorship is documented in v1_runtime/NOTICE.

The implementation is split across cohesive sibling modules — inputs, diagnostics, remedies, and reports — and this package is a thin public facade that re-exports their surface unchanged. Importing the package also registers the packaged VASP workflows with the generic scaffold (see the workflows module), which is how httk workflow job new --workflow vasp-relax resolves a runner the scaffold never names.

Attributes

VASP_RESTART_ARTIFACTS
DEFAULT_KPOINT_CENTERING
KPOINT_CENTERINGS
DEFAULT_REMEDY_HISTORY
REMEDY_OPERATIONS

Classes

PoscarHeader	The VASP-5 header information needed by execution helpers.
PotcarAssembly	One assembled POTCAR and the provenance of every piece in it.
PotcarChoice	Which pseudopotential of a library one species was given.
VaspPreparationOptions	Options for dependency-free VASP input preparation.
RemedyPolicy	One named, ordered ladder of bounded remedies.
VaspRemedyDecision	One explicit bounded remedy proposal.
VaspRunReport	Classified result of one supervised VASP execution.

Functions

clean_outcar([path, output])	Remove the largest reproducible k-point detail blocks from OUTCAR.
clean_vasp_outputs([directory, keep, also_remove])	Remove standard rerun outputs while preserving declared names.
diagnose_vasp_files([directory])	Diagnose completion and final convergence from VASP output files.
last_oszicar_energy([path])	Return the final E0 value, or None when it is absent.
last_vasprun_volume([path])	Return the final volume reported by vasprun.xml.
outcar_plane_wave_count([path])	Return OUTCAR's maximum plane-wave count.
outcar_potim([path])	Return the last optimizer step size from OUTCAR.
validate_vasp_workdir([path, maximum_length])	Validate VASP's conservative absolute-path length constraint.
assemble_potcar(library, *[, poscar, output, ...])	Assemble POTCAR from explicit species and a configurable suffix policy.
automatic_kpoint_grid(density, *[, poscar, minimum, ...])	Calculate a reciprocal-length automatic grid.
calculate_nbands(*[, poscar, potcar, incar, divisor])	Calculate a conservative VASP band count from input metadata.
contcar_to_poscar([contcar, reference, output])	Replace CONTCAR's comment with the reference POSCAR comment.
derive_seed(entropy)	Derive one reproducible 63-bit seed from a caller-supplied string.
normalize_poscar_handedness([path])	Make a left-handed POSCAR lattice right-handed without moving sites.
potcar_summary([path, output])	Write a non-potential metadata summary suitable for logs.
prepare_vasp_inputs([options, directory])	Prepare POSCAR, POTCAR, KPOINTS, and INCAR with recorded choices.
rattle_poscar([path, amplitude, seed, entropy])	Apply a deterministic bounded perturbation to POSCAR site coordinates.
read_incar([path])	Read the last value of each simple INCAR assignment.
read_poscar_header([path])	Read a VASP-5 POSCAR header without interpreting site coordinates.
scale_poscar_lattice(factor[, path])	Multiply POSCAR's universal linear scale by a positive factor.
suggested_magnetic_moments([path])	Return the explicit comment override or a five-per-atom default.
update_incar(values[, path])	Atomically replace selected INCAR tags while preserving other lines.
write_automatic_kpoints(grid[, path, centering])	Write a standard automatic KPOINTS file.
apply_vasp_remedy(decision, *[, directory, ...])	Explicitly apply a proposed remedy through a replayable workdir batch.
job_remedy_history_path(payload)	Return the job-scoped remedy history file of one job payload.
plan_vasp_remedy(diagnostics, *[, directory, ...])	Return, but do not apply, the next remedy of policy.
register_remedy_policy(name, sequences, precedence, *)	Register one named remedy policy and return the normalized result.
remedy_policy(name)	Return one registered remedy policy, naming the alternatives if absent.
remedy_policy_names()	Return the names of every registered remedy policy, in registration order.
run_vasp(argv, *[, directory, timeout, ...])	Run VASP with live VASP-5/6 diagnostics and a structured report.

Package Contents

httk.workflow.vasp.VASP_RESTART_ARTIFACTS: tuple[str, Ellipsis] = ('CONTCAR', 'vasp-run-report.json')

httk.workflow.vasp.clean_outcar(path='OUTCAR', output='OUTCAR.cleaned')

Remove the largest reproducible k-point detail blocks from OUTCAR.

Parameters:

• path (str | os.PathLike[str]) – Read the OUTCAR file at this path.

• output (str | os.PathLike[str]) – Write the cleaned OUTCAR to this path.

Returns:

The cleaned output path.

Return type:

pathlib.Path

httk.workflow.vasp.clean_vasp_outputs(directory='.', *, keep=(), also_remove=())

Remove standard rerun outputs while preserving declared names.

The files in VASP_RESTART_ARTIFACTS — CONTCAR and vasp-run-report.json — are kept even without keep, because they are what the remedy machinery and restart promotion read: a pre-run cleanup that deletes them destroys the evidence of the run it is cleaning up after. Name them in also_remove to delete them anyway.

Parameters:

• directory (str | os.PathLike[str]) – Remove outputs from this directory.

• keep (collections.abc.Iterable[str]) – Preserve these output names.

• also_remove (collections.abc.Iterable[str]) – Allow restart artifacts to be removed by naming them here.

Returns:

The paths removed from the directory.

Raises:

ValueError – If an output to remove is not a regular file.

Return type:

tuple[pathlib.Path, Ellipsis]

httk.workflow.vasp.diagnose_vasp_files(directory='.')

Diagnose completion and final convergence from VASP output files.

Parameters:

directory (str | os.PathLike[str]) – Read VASP output files from this directory.

Returns:

Diagnostics inferred from the available output files.

Return type:

tuple[httk.workflow.supervision.Diagnostic, Ellipsis]

httk.workflow.vasp.last_oszicar_energy(path='OSZICAR')

Return the final E0 value, or None when it is absent.

Parameters:

path (str | os.PathLike[str]) – Read the OSZICAR file at this path.

Returns:

The final parsed E0 value, or None when no value is found.

Return type:

float | None

httk.workflow.vasp.last_vasprun_volume(path='vasprun.xml')

Return the final volume reported by vasprun.xml.

Parameters:

path (str | os.PathLike[str]) – Read the vasprun XML file at this path.

Returns:

The final parsed volume, or None when no volume is found.

Return type:

float | None

httk.workflow.vasp.outcar_plane_wave_count(path='OUTCAR')

Return OUTCAR’s maximum plane-wave count.

Parameters:

path (str | os.PathLike[str]) – Read the OUTCAR file at this path.

Returns:

The parsed maximum plane-wave count, or None when absent.

Return type:

int | None

httk.workflow.vasp.outcar_potim(path='OUTCAR')

Return the last optimizer step size from OUTCAR.

Parameters:

path (str | os.PathLike[str]) – Read the OUTCAR file at this path.

Returns:

The last parsed optimizer step size, or None when absent.

Return type:

float | None

httk.workflow.vasp.validate_vasp_workdir(path='.', *, maximum_length=240)

Validate VASP’s conservative absolute-path length constraint.

Parameters:

• path (str | os.PathLike[str]) – Resolve and validate this workdir path.

• maximum_length (int) – Reject resolved paths longer than this byte length.

Returns:

The resolved workdir path.

Raises:

ValueError – If the limit is invalid or the resolved path is too long.

Return type:

pathlib.Path

httk.workflow.vasp.DEFAULT_KPOINT_CENTERING = 'Monkhorst-Pack'

httk.workflow.vasp.KPOINT_CENTERINGS = ('Gamma', 'Monkhorst-Pack')

class httk.workflow.vasp.PoscarHeader

The VASP-5 header information needed by execution helpers.

Parameters:

• comment – Preserve the POSCAR comment line.

• scale – Preserve the universal POSCAR scale.

• lattice – Preserve the three lattice vectors.

• species – Preserve the VASP-5 species names.

• counts – Preserve the atom count for each species.

comment: str

scale: float

lattice: tuple[tuple[float, float, float], Ellipsis]

species: tuple[str, Ellipsis]

counts: tuple[int, Ellipsis]

class httk.workflow.vasp.PotcarAssembly

One assembled POTCAR and the provenance of every piece in it.

Parameters:

• path – Record the assembled POTCAR path.

• library – Record the pseudopotential library root.

• choices – Record the selected potential for each species.

• provenance – Record the provenance output path.

path: pathlib.Path

library: pathlib.Path

choices: tuple[PotcarChoice, Ellipsis]

provenance: pathlib.Path

as_mapping()

Serialize the assembly provenance.

Returns:

The JSON-compatible provenance mapping.

Return type:

dict[str, object]

class httk.workflow.vasp.PotcarChoice

Which pseudopotential of a library one species was given.

The suffix policy of assemble_potcar() silently prefers one PAW variant over another, and the choice changes the numbers a calculation produces, so every choice is recorded: the variant directory, the suffix that selected it, the full source path, its digest, and the TITEL the potential names itself with.

Parameters:

• species – Record the POSCAR species name.

• variant – Record the selected pseudopotential directory name.

• suffix – Record the suffix selected for the species.

• source – Record the source potential path.

• sha256 – Record the source file digest.

• titel – Record the potential’s TITEL value, when present.

species: str

variant: str

suffix: str

source: pathlib.Path

sha256: str

titel: str | None

as_mapping()

Serialize the potential choice.

Returns:

The JSON-compatible choice mapping.

Return type:

dict[str, object]

class httk.workflow.vasp.VaspPreparationOptions

Options for dependency-free VASP input preparation.

accuracy_per_atom is the target total-energy accuracy in eV per atom: EDIFFG is set to that budget for the whole cell and EDIFF to the same budget divided by ediff_margin, so the electronic loop converges roughly one and a half orders of magnitude tighter than the ionic loop it feeds. The margin of 33 is a heuristic, empirical default carried over from httk v1, not a derived quantity.

Parameters:

• kpoint_density – Set the reciprocal-length k-point density.

• centering – Select the automatic k-point centering.

• accuracy_per_atom – Set the target total-energy accuracy, or disable derived accuracy tags when unset.

• ediff_margin – Divide the cell accuracy by this margin for EDIFF.

• pseudopotential_library – Assemble POTCAR from this library when set.

• parallel_tag – Set the selected parallel INCAR tag when set.

• parallel_value – Set the value for the selected parallel tag.

• normalize_handedness – Normalize a left-handed POSCAR before preparation.

• incar_tags – Apply these explicit INCAR tags before derived defaults.

kpoint_density: float = 20.0

centering: str = 'Monkhorst-Pack'

accuracy_per_atom: float | None = 0.001

ediff_margin: float = 33.0

pseudopotential_library: str | os.PathLike[str] | None = None

parallel_tag: str | None = None

parallel_value: int | None = None

normalize_handedness: bool = True

incar_tags: collections.abc.Mapping[str, object]

httk.workflow.vasp.assemble_potcar(library, *, poscar='POSCAR', output='POTCAR', suffix_preference=('_3', '_2', '_d', '_sv', '_pv', '', '_h', '_s'), provenance=None)

Assemble POTCAR from explicit species and a configurable suffix policy.

The suffix policy decides which PAW variant each species gets, so the result describes what it chose: the returned PotcarAssembly names every potential, and the same record is written next to the POTCAR as <POTCAR>.provenance.json unless provenance names another file.

Parameters:

• library (str | os.PathLike[str]) – Search this pseudopotential library root.

• poscar (str | os.PathLike[str]) – Read species names from this POSCAR.

• output (str | os.PathLike[str]) – Write the assembled POTCAR to this path.

• suffix_preference (collections.abc.Iterable[str]) – Try these species suffixes in order.

• provenance (str | os.PathLike[str] | None) – Write provenance to this path, or beside the POTCAR when unset.

Returns:

The assembled POTCAR and its provenance.

Raises:

FileNotFoundError – If a species has no matching potential.

Return type:

PotcarAssembly

httk.workflow.vasp.automatic_kpoint_grid(density, *, poscar='POSCAR', minimum=3, equal=False, bump=0)

Calculate a reciprocal-length automatic grid.

Parameters:

• density (float) – Scale reciprocal lengths by this positive density.

• poscar (str | os.PathLike[str]) – Read lattice vectors from this POSCAR.

• minimum (int) – Enforce this minimum value in each grid direction.

• equal (bool) – Use the largest direction value for all directions.

• bump (int) – Add this nonnegative amount to each calculated direction.

Returns:

The three automatic grid dimensions.

Raises:

ValueError – If an argument is invalid or the lattice is singular.

Return type:

tuple[int, int, int]

httk.workflow.vasp.calculate_nbands(*, poscar='POSCAR', potcar='POTCAR', incar='INCAR', divisor=None)

Calculate a conservative VASP band count from input metadata.

The count is a heuristic, deliberately generous margin over VASP’s own default of roughly half the valence electrons plus half the atom count: too few bands is a run that stops with TOO FEW BANDS or converges to the wrong state, while a handful of extra empty bands costs only time. The spin-polarized branch adds 0.6 * electrons plus a magnetization- or atom-count-derived margin, and the maximum of the candidate formulas wins; the numbers themselves are empirical defaults carried over from httk v1. The result is rounded up to an even number, and to a multiple of divisor when a parallel band divisor (NPAR) is in play, because VASP would otherwise round NBANDS up itself and report a changed value.

Parameters:

• poscar (str | os.PathLike[str]) – Read species and atom counts from this POSCAR.

• potcar (str | os.PathLike[str]) – Read valence counts from this POTCAR.

• incar (str | os.PathLike[str]) – Read spin and magnetization tags from this INCAR.

• divisor (int | None) – Round the result up to a multiple of this positive divisor.

Returns:

The conservative even band count.

Raises:

ValueError – If the divisor or required input metadata is invalid.

Return type:

int

httk.workflow.vasp.contcar_to_poscar(contcar='CONTCAR', *, reference='POSCAR', output='POSCAR')

Replace CONTCAR’s comment with the reference POSCAR comment.

Parameters:

• contcar (str | os.PathLike[str]) – Read the relaxed structure from this CONTCAR path.

• reference (str | os.PathLike[str]) – Read the replacement comment from this POSCAR path.

• output (str | os.PathLike[str]) – Write the resulting POSCAR to this path.

Returns:

The written POSCAR path.

Raises:

ValueError – If either input file is empty.

Return type:

pathlib.Path

httk.workflow.vasp.derive_seed(entropy)

Derive one reproducible 63-bit seed from a caller-supplied string.

The string is the caller’s own identity of the perturbation — an attempt ordinal, a job key, a remedy step — so the same attempt always derives the same seed and two different attempts derive different ones, without anything reading a clock or a global random state.

Parameters:

entropy (str) – Identify the perturbation with this nonempty string.

Returns:

The reproducible seed.

Raises:

ValueError – If entropy is not a nonempty string.

Return type:

int

httk.workflow.vasp.normalize_poscar_handedness(path='POSCAR')

Make a left-handed POSCAR lattice right-handed without moving sites.

Parameters:

path (str | os.PathLike[str]) – Normalize the POSCAR file at this path.

Returns:

The normalized POSCAR path.

Return type:

pathlib.Path

httk.workflow.vasp.potcar_summary(path='POTCAR', output='POTCAR.summary')

Write a non-potential metadata summary suitable for logs.

Parameters:

• path (str | os.PathLike[str]) – Read POTCAR metadata from this path.

• output (str | os.PathLike[str]) – Write the summary to this path.

Returns:

The written summary path.

Return type:

pathlib.Path

httk.workflow.vasp.prepare_vasp_inputs(options=None, *, directory='.')

Prepare POSCAR, POTCAR, KPOINTS, and INCAR with recorded choices.

incar_tags is applied to the INCAR first and wins over everything derived afterwards: the derived values are defaults for what the caller did not say, so an explicit EDIFF, MAGMOM, or NBANDS survives preparation, and an explicit ISPIN is what the band-count heuristic reads.

Parameters:

• options (VaspPreparationOptions | None) – Use these preparation options, or their defaults when unset.

• directory (str | os.PathLike[str]) – Prepare the VASP inputs in this directory.

Returns:

A record of prepared files and selected input choices.

Raises:

ValueError – If the workdir, options, or input metadata is invalid.

Return type:

dict[str, object]

httk.workflow.vasp.rattle_poscar(path='POSCAR', *, amplitude=0.01, seed=None, entropy=None)

Apply a deterministic bounded perturbation to POSCAR site coordinates.

A perturbation has to be reproducible and different between two attempts of the same calculation, so this function never invents entropy of its own: either seed names the stream explicitly, or entropy is a string derive_seed() turns into one — typically something attempt-derived, such as f"{job_key}:{attempt_ordinal}". Giving neither is refused rather than silently repeated, because two retries that rattle identically are two identical calculations.

Parameters:

• path (str | os.PathLike[str]) – Update site coordinates in this POSCAR.

• amplitude (float) – Bound each coordinate perturbation by this value.

• seed (int | None) – Use this random seed when supplied.

• entropy (str | None) – Derive a seed from this string when supplied.

Returns:

The updated POSCAR path.

Raises:

ValueError – If the perturbation settings or coordinate rows are invalid.

Return type:

pathlib.Path

httk.workflow.vasp.read_incar(path='INCAR')

Read the last value of each simple INCAR assignment.

Parameters:

path (str | os.PathLike[str]) – Read the INCAR file at this path.

Returns:

Upper-case INCAR tags mapped to their last values.

Return type:

dict[str, str]

httk.workflow.vasp.read_poscar_header(path='POSCAR')

Read a VASP-5 POSCAR header without interpreting site coordinates.

Parameters:

path (str | os.PathLike[str]) – Read the POSCAR file at this path.

Returns:

The parsed POSCAR header.

Raises:

ValueError – If the header is too short or malformed.

Return type:

PoscarHeader

httk.workflow.vasp.scale_poscar_lattice(factor, path='POSCAR')

Multiply POSCAR’s universal linear scale by a positive factor.

Parameters:

• factor (float) – Multiply the current scale by this positive finite value.

• path (str | os.PathLike[str]) – Update the POSCAR file at this path.

Returns:

The updated POSCAR path.

Raises:

ValueError – If the factor or POSCAR scale line is invalid.

Return type:

pathlib.Path

httk.workflow.vasp.suggested_magnetic_moments(path='POSCAR')

Return the explicit comment override or a five-per-atom default.

The five Bohr magnetons per atom are a heuristic starting guess, not a physical prediction: a deliberately high initial moment lets a spin-polarized relaxation fall into a low-spin solution, whereas starting too low tends to keep it there, so overestimating is the safer direction. The value of five is the empirical default carried over from httk v1. Encode a per-structure choice in the POSCAR comment as [MAGMOM=...].

Parameters:

path (str | os.PathLike[str]) – Read the POSCAR comment and species counts from this path.

Returns:

The explicit or generated MAGMOM value.

Return type:

str

httk.workflow.vasp.update_incar(values, path='INCAR')

Atomically replace selected INCAR tags while preserving other lines.

VASP allows several ;-separated assignments per line, and read_incar() reads them all, so an update has to rewrite the individual statements of a line rather than drop or keep the whole line: updating ISYM in ISPIN = 2 ; ISYM = 2 leaves ISPIN = 2 and appends the new ISYM, instead of leaving a line that still assigns the old value.

Parameters:

• values (collections.abc.Mapping[str, object]) – Replace these INCAR tag assignments.

• path (str | os.PathLike[str]) – Update the INCAR file at this path.

Returns:

The updated INCAR path.

Raises:

ValueError – If a tag name is empty or invalid.

Return type:

pathlib.Path

httk.workflow.vasp.write_automatic_kpoints(grid, path='KPOINTS', *, centering=DEFAULT_KPOINT_CENTERING)

Write a standard automatic KPOINTS file.

The centering defaults to DEFAULT_KPOINT_CENTERING here, in VaspPreparationOptions, and in the Bash bridge, so a workflow that hits a k-point failure class still has the Gamma remedy available.

Parameters:

• grid (collections.abc.Sequence[int]) – Write these three positive grid dimensions.

• path (str | os.PathLike[str]) – Write the KPOINTS file to this path.

• centering (str) – Use this supported k-point centering.

Returns:

The written KPOINTS path.

Raises:

ValueError – If the grid or centering is unsupported.

Return type:

pathlib.Path

httk.workflow.vasp.DEFAULT_REMEDY_HISTORY = '.httk-vasp/remedies.json'

httk.workflow.vasp.REMEDY_OPERATIONS = ('bump_bands', 'bump_kpoints', 'centering', 'contcar_to_poscar', 'equal_kpoints', 'scale_ediff',...

class httk.workflow.vasp.RemedyPolicy

One named, ordered ladder of bounded remedies.

A policy is data, not code: sequences maps a diagnosed problem to the escalating steps tried for it, precedence orders the problems so one diagnosis is remedied at a time, and refusals names the problems this policy deliberately has no input remedy for. A group with its own reviewed practice registers its own policy with register_remedy_policy() instead of editing this module.

Parameters:

• name – Identify the registered policy.

• sequences – Map diagnostic codes to ordered remedy changes.

• precedence – Order diagnostic codes for remedy selection.

• refusals – Explain diagnostic codes this policy will not remedy.

name: str

sequences: collections.abc.Mapping[str, RemedySequence]

precedence: tuple[str, Ellipsis]

refusals: collections.abc.Mapping[str, str]

class httk.workflow.vasp.VaspRemedyDecision

One explicit bounded remedy proposal.

Parameters:

• policy – Identify the policy that produced the decision.

• problem – Identify the selected diagnostic problem.

• step – Record the ladder step considered.

• changes – Record the input changes to apply.

• give_up – Mark that no remedy should be applied.

• reason – Explain the decision.

policy: str

problem: str

step: int

changes: tuple[tuple[str, object], Ellipsis]

give_up: bool

reason: str

as_mapping()

Serialize the remedy decision.

Returns:

The JSON-compatible decision mapping.

Return type:

dict[str, object]

httk.workflow.vasp.apply_vasp_remedy(decision, *, directory='.', history_path=DEFAULT_REMEDY_HISTORY, durable=False)

Explicitly apply a proposed remedy through a replayable workdir batch.

The history is recorded before the inputs change, so an application interrupted halfway advances the ladder rather than repeating one remedy for ever. A history file inside the VASP directory is written by the same replayable batch as the inputs; a job-scoped one, which the batch cannot reach, is written atomically just before the batch commits.

durable synchronizes the batch and the job-scoped history on a durable workspace, so a power cut cannot lose a remedy the ladder has already recorded. It defaults to False for a caller applying a remedy outside an attempt; the Bash bridge sources it from the workspace durability contract.

Parameters:

• decision (VaspRemedyDecision) – Apply this previously planned remedy.

• directory (str | os.PathLike[str]) – Apply changes in this VASP directory.

• history_path (str | os.PathLike[str]) – Read and update the remedy history at this path.

• durable (bool) – Synchronize the published batch when true.

Returns:

The committed remedy batch path.

Raises:

ValueError – If the decision gives up or its changes are not applicable.

Return type:

pathlib.Path

httk.workflow.vasp.job_remedy_history_path(payload)

Return the job-scoped remedy history file of one job payload.

The escalation ladder is a property of the job, not of the directory one attempt happened to run in, so it lives beside the job state in <payload>/.httk-job/ rather than in the workdir. A job with an isolated workdir therefore keeps escalating instead of silently starting the ladder from the beginning on every attempt.

Parameters:

payload (str | os.PathLike[str]) – Locate the job payload.

Returns:

The job-scoped remedy history path.

Return type:

pathlib.Path

httk.workflow.vasp.plan_vasp_remedy(diagnostics, *, directory='.', history_path=DEFAULT_REMEDY_HISTORY, policy='reviewed-v1')

Return, but do not apply, the next remedy of policy.

The decision is validated against the real contents of directory: a ladder step whose changes cannot be executed there is skipped, and the first executable step wins. When nothing is left the decision gives up, so a runner only ever hands apply_vasp_remedy() a remedy it can perform.

Parameters:

• diagnostics (collections.abc.Sequence[httk.workflow.supervision.Diagnostic]) – Supply diagnostics from the VASP run.

• directory (str | os.PathLike[str]) – Inspect and plan changes in this VASP directory.

• history_path (str | os.PathLike[str]) – Read the remedy history from this path.

• policy (str) – Select this registered remedy policy.

Returns:

The next applicable remedy decision.

Raises:

ValueError – If the remedy history or policy is invalid.

Return type:

VaspRemedyDecision

httk.workflow.vasp.register_remedy_policy(name, sequences, precedence, *, refusals=None, replace=False)

Register one named remedy policy and return the normalized result.

Every problem named in sequences must also appear in precedence, which is what decides which of several simultaneous diagnostics is acted on, and every change must spell one supported remedy operation, so a policy that cannot be executed is refused when it is registered rather than when a run needs it.

Parameters:

• name (str) – Register the policy under this nonempty name.

• sequences (collections.abc.Mapping[str, collections.abc.Sequence[collections.abc.Sequence[tuple[str, object]]]]) – Define ordered changes for each diagnostic code.

• precedence (collections.abc.Sequence[str]) – Order diagnostic codes for selection.

• refusals (collections.abc.Mapping[str, str] | None) – Explain diagnostic codes deliberately left without a remedy.

• replace (bool) – Replace an existing policy with this definition.

Returns:

The normalized registered policy.

Raises:

ValueError – If the policy is duplicate, incomplete, or unsupported.

Return type:

RemedyPolicy

httk.workflow.vasp.remedy_policy(name)

Return one registered remedy policy, naming the alternatives if absent.

Parameters:

name (str) – Select this registered policy.

Returns:

The selected remedy policy.

Raises:

ValueError – If no policy has this name.

Return type:

RemedyPolicy

httk.workflow.vasp.remedy_policy_names()

Return the names of every registered remedy policy, in registration order.

Returns:

Registered policy names in registration order.

Return type:

tuple[str, Ellipsis]

class httk.workflow.vasp.VaspRunReport

Classified result of one supervised VASP execution.

Parameters:

• process – Preserve the supervised process result.

• classification – Record the final VASP run classification.

• diagnostics – Preserve live and file-level diagnostics.

process: httk.workflow.supervision.ProcessReport

classification: str

diagnostics: tuple[httk.workflow.supervision.Diagnostic, Ellipsis]

as_mapping()

Serialize the report for JSON storage.

Returns:

The JSON-compatible report mapping.

Return type:

dict[str, object]

write(path)

Write the report as JSON.

Parameters:

path (str | os.PathLike[str]) – Write the report to this path.

Returns:

The report path.

Return type:

pathlib.Path

httk.workflow.vasp.run_vasp(argv, *, directory='.', timeout=None, termination_grace=10.0, report_path='vasp-run-report.json')

Run VASP with live VASP-5/6 diagnostics and a structured report.

Parameters:

• argv (collections.abc.Sequence[str]) – Execute this VASP command argument vector.

• directory (str | os.PathLike[str]) – Run VASP in this directory.

• timeout (float | None) – Stop the process after this duration when set.

• termination_grace (float) – Allow this duration for graceful termination.

• report_path (str | os.PathLike[str]) – Write the structured report at this workdir-relative path.

Returns:

The classified VASP run report.

Return type:

VaspRunReport