airsspy.jf.runners

Execution runners for AIRSS calculations.

Pure computation classes with no jobflow dependency. Each runner handles one buildcell invocation or one CASTEP relaxation cycle. They are usable standalone or within jobflow Makers.

Module Contents

Classes

AirssCastepSinglePointRunner	Execute a CASTEP single-point calculation.
AirssCastepRelaxRunner	Execute a cyclic CASTEP geometry optimisation.
AirssScriptRelaxRunner	Base runner for external AIRSS relaxation scripts (gulp_relax, pp3_relax).
AirssGulpRelaxRunner	Runner for GULP relaxation via the external gulp_relax script.
AirssPp3RelaxRunner	Runner for pp3 relaxation via the external pp3_relax script.
AirssVaspRelaxRunner	Execute a local VASP relaxation in <struct_name>.vasp.
AirssVaspSinglePointRunner	Execute a local VASP single-point calculation.
AirssAbacusRelaxRunner	Execute a cyclic ABACUS geometry optimisation.
AirssAbacusSinglePointRunner	Execute a single ABACUS single-point (SCF) calculation.

Functions

clean_files	Remove files associated with a failed calculation.
run_buildcell	Run the buildcell executable to generate a random structure.
compose_task_doc	Extract results from a completed CASTEP calculation.

Data

logger

API

airsspy.jf.runners.logger

‘getLogger(…)’

airsspy.jf.runners.clean_files(struct_name: str, extensions: list[str], extra_paths: list[str] | None = None) → None

Remove files associated with a failed calculation.

Args: struct_name: Structure name (without extension). extensions: File extensions to remove (e.g. [".castep", ".cell"]). extra_paths: Additional paths to remove (files or directories).

airsspy.jf.runners.run_buildcell(seed_name: str, seed_content: str, build_timeout: int = 30, write_seed: bool = True, seed_text_transform=None, max_attempts: int = 3) → Optional[dict[str, str]]

Run the buildcell executable to generate a random structure.

Args: seed_name: Name of the seed (without extension). seed_content: Content of the seed .cell file. build_timeout: Timeout in seconds for each buildcell attempt. write_seed: Whether to write the seed .cell file to disk. seed_text_transform: Optional callable that rewrites seed content before each buildcell attempt. max_attempts: Maximum number of buildcell attempts.

Returns: Dictionary with struct_name, seed_name, seed_hash, struct_content keys, or None if all attempts timed out.

class airsspy.jf.runners.AirssCastepSinglePointRunner(executable: str = 'castep.mpi')

Execute a CASTEP single-point calculation.

Initialization

clean_failed(struct_name: str) → None

prepare_inputs(struct_name: str, cellinput, paraminput) → None

Write .cell and .param files to disk.

Args: struct_name: Seed name (without extension). cellinput: A CastepInput/CellInput instance or string. paraminput: A CastepInput/ParamInput instance or string.

run(struct_name: str, cellinput, paraminput) → int

Run a single-point calculation.

Args: struct_name: Seed name (without extension). cellinput: Cell input (CellInput instance or string). paraminput: Param input (ParamInput instance or string).

Returns: 0 on success, non-zero on failure.

class airsspy.jf.runners.AirssCastepRelaxRunner(executable: str = 'castep.mpi', max_fails: int = 2, max_iterations: int = 200)

Bases: airsspy.jf.runners.AirssCastepSinglePointRunner

Execute a cyclic CASTEP geometry optimisation.

Runs successive relaxations, copying the output cell back to the input between cycles. Requires two consecutive successful runs to declare convergence. Stops at max_iterations.

Initialization

run(struct_name: str, cellinput, paraminput) → int

Run cyclic CASTEP relaxation.

Args: struct_name: Seed name (without extension). cellinput: Cell input (CellInput instance or string). paraminput: Param input (ParamInput instance or string).

Returns: 0 if converged, 1 if not converged or failed.

airsspy.jf.runners.compose_task_doc(struct_name: str) → dict

Extract results from a completed CASTEP calculation.

Reads the .castep and .cell files, computes derived properties, writes a <struct_name>.res file to disk, and returns a dictionary suitable for constructing an AirssResultDoc.

Args: struct_name: Seed name (without extension).

Returns: Dictionary with energy, structure, volume, formula, etc.

class airsspy.jf.runners.AirssScriptRelaxRunner(executable: str = 'gulp', timeout: int = 600, max_attempts: int = 3)

Base runner for external AIRSS relaxation scripts (gulp_relax, pp3_relax).

Calls an external script and checks the output file for success. Subclasses must override _get_cmd and set _param_suffix.

Initialization

clean_failed(struct_name: str) → None

run(struct_name: str, struct_content: str, param_content: str, seed_name: Optional[str] = None) → int

Run relaxation via the external script.

Args: struct_name: Structure name (without extension). struct_content: Content of the .cell file. param_content: Content of the code-specific param file. seed_name: Seed name (needed by GULP for .lib file rename).

Returns: 0 on success, 1 on failure.

class airsspy.jf.runners.AirssGulpRelaxRunner(executable: str = 'ggulp', timeout: int = 600, max_attempts: int = 3, cluster: bool = False, pressure: float = 0.0)

Bases: airsspy.jf.runners.AirssScriptRelaxRunner

Runner for GULP relaxation via the external gulp_relax script.

Calls gulp_relax <exe> <cluster> <pressure> <struct_name> and checks for success via gulp_relax_finish_ok() and "Volume" in stdout.

Initialization

class airsspy.jf.runners.AirssPp3RelaxRunner(executable: str = 'pp3', timeout: int = 600, max_attempts: int = 3)

Bases: airsspy.jf.runners.AirssScriptRelaxRunner

Runner for pp3 relaxation via the external pp3_relax script.

Calls pp3_relax <exe> <struct_name> and checks for success via gulp_relax_finish_ok().

Initialization

class airsspy.jf.runners.AirssVaspRelaxRunner(executable: str = 'vasp_std', pressure: float = 0.0, potcar_dir: str | None = None, potcar_map: dict[str, str] | None = None, max_fails: int = 2, max_iterations: int = 200)

Execute a local VASP relaxation in <struct_name>.vasp.

Initialization

clean_failed(struct_name: str) → None

prepare_inputs(struct_name: str, cell_content: str, incar_content: str, kpoints_path: str | pathlib.Path | None = None) → dict

Write top-level AIRSS inputs and prepare VASP input directory.

run(struct_name: str, cell_content: str, incar_content: str, kpoints_path: str | pathlib.Path | None = None) → int

Run a cyclic VASP relaxation.

As with the CASTEP runner, two consecutive converged VASP runs are required before declaring success. Between cycles, CONTCAR is copied back to POSCAR so the next invocation continues from the last relaxed geometry.

class airsspy.jf.runners.AirssVaspSinglePointRunner(executable: str = 'vasp_std', pressure: float = 0.0, potcar_dir: str | None = None, potcar_map: dict[str, str] | None = None, max_fails: int = 2, max_iterations: int = 200)

Bases: airsspy.jf.runners.AirssVaspRelaxRunner

Execute a local VASP single-point calculation.

Initialization

prepare_inputs(struct_name: str, cell_content: str, incar_content: str, kpoints_path: str | pathlib.Path | None = None) → dict

run(struct_name: str, cell_content: str, incar_content: str, kpoints_path: str | pathlib.Path | None = None) → int

Run one VASP single-point calculation.

class airsspy.jf.runners.AirssAbacusRelaxRunner(executable: str = 'abacus', max_fails: int = 2, max_iterations: int = 200, pressure: float = 0.0)

Execute a cyclic ABACUS geometry optimisation.

Calls the ABACUS binary directly and manages the relaxation loop in Python, following the same two-phase pattern as abacus_relax:

1. Three short rough runs with relax_nmax=3

2. Full convergence loop until two successive convergences

Between each ABACUS invocation, the structure is read from STRU_ION_D, converted back to .cell format, and fed into the next iteration.

Initialization

clean_failed(struct_name: str) → None

prepare_inputs(struct_name: str, cell_content: str, input_content: str) → None

Write .cell and .INPUT files, convert .cell to STRU.

Args: struct_name: Structure name (without extension). cell_content: Content of the .cell file. input_content: Content of the ABACUS INPUT file.

run(struct_name: str, cell_content: str, input_content: str) → int

Run cyclic ABACUS relaxation.

Phase 1: three rough runs with relax_nmax=3 for initial optimisation. Phase 2: full convergence loop until two consecutive convergences or max_iterations is reached.

Args: struct_name: Structure name (without extension). cell_content: Content of the .cell file. input_content: Content of the ABACUS INPUT file.

Returns: 0 if converged, 1 if not converged or failed.

class airsspy.jf.runners.AirssAbacusSinglePointRunner(executable: str = 'abacus')

Execute a single ABACUS single-point (SCF) calculation.

Runs ABACUS once with calculation scf in the INPUT file. No cyclic relaxation loop. Checks for TOTAL  Time in the output to determine success.

Initialization

clean_failed(struct_name: str) → None

prepare_inputs(struct_name: str, cell_content: str, input_content: str) → None

Write .cell, .INPUT files and convert to STRU.

Forces calculation scf in the INPUT file regardless of what the user specified.

run(struct_name: str, cell_content: str, input_content: str) → int

Run a single-point ABACUS calculation.

Args: struct_name: Structure name (without extension). cell_content: Content of the .cell file. input_content: Content of the ABACUS INPUT file.

Returns: 0 on success, 1 on failure.