ASE2SPRKKR architecture for developers
ASE2SPRKKR separates scientific definitions and result parsing from
the execution of native SPR-KKR programs. The SPRKKR calculator
is the main user-facing interface; scientific file formats and
execution profiles are also available independently.
Configuration files and definitions
SPR-KKR input and potential files use configuration objects.
Instances hold sections and option values; definitions specify
grammar, types, defaults, validation and parsing/writing rules.
ase2sprkkr.common provides ConfigurationContainer,
Option, ContainerDefinition and ValueDefinition,
together with grammar types and
pyparsing.
Parsing and writing configuration files
A configuration definition describes the syntax and allowed values of a file; a configuration instance holds the parsed or user-supplied values. The same definition is used for reading and writing:
Task and potential definitions assemble named sections and options, with value types, defaults and validation rules.
Parsing uses the grammar generated from those definitions to recognize the file and build configuration objects. Their option values are converted to the declared Python types and validated.
Python code can inspect or change those values, either through section attributes or the generic configuration interface.
Serialization walks the configuration using the definition’s formatting and writing rules, producing native SPR-KKR text.
For example, InputParameters.from_file("run.inp") reads a file
using the appropriate input definition, while
Potential.from_file("run.pot") uses the potential definition.
These are different schemas, but the parsing and serialization
infrastructure is shared. See Using ASE2SPRKKR for practical examples;
avoid adding file-specific parsing logic to the calculator.
TaskDefinition: task identity versus input schema
ase2sprkkr.input_parameters.task_definition.TaskDefinition
is an immutable description of one SPR-KKR task. It declares
the canonical name, associated input_parameters_definition_name,
native executable, MPI support, output reader, experimental status
and TaskFile input/output/cache manifests. It is not a second
parser or a holder of the parameter values.
The distinction matters because multiple tasks can share one input parameter schema. For example, the DMI task uses JXC input parameters:
from ase2sprkkr.input_parameters.task_definition import TaskDefinition
def task_definition():
return TaskDefinition(
"JXC", name="DMI", executable="kkrgen",
mpi=True, experimental=True, output_reader="JXC",
)
A task with its own input schema can declare
schema._task_definition alongside the corresponding
input_parameters_definition() function, as DOS and SCF do.
Tasks sharing an existing schema are instead defined separately
in ase2sprkkr.input_parameters.tasks.
Resolve task identities through the TaskRegistry, not by assuming
that an input schema name identifies exactly one task.
InputParametersRegistry owns input schema resolution.
The public API InputParameters.for_task(task_name) creates
task-bound input parameters, and ase2sprkkr info --task
shows the registered tasks.
When adding a task, define its native executable and supported
TaskFile manifests, select its parameter schema and output
reader, and add focused tests. Avoid maintaining parallel task
identities or hard-coding known files in the calculator.
Scientific layers
ase2sprkkr.input_parameters— task and schema registries, task definitions and native input parsing.ase2sprkkr.potentials— potential-file representations.ase2sprkkr.sprkkr— ASE calculator, atom/site properties, preparation, profiles and symmetry.ase2sprkkr.outputs— task output readers,TaskResult.ase2sprkkr.result_files— structured result readers, Grace.agrand NeXus export.ase2sprkkr.bindings— optional external integrations.ase2sprkkr_cli— lightweight command dispatcher and plugins.
Execution boundary
Preparation via sprkkr._preparation materializes native
inputs and file manifests. PreparedCalculation adapts those
to KKRunner specifications.
KKRunner handles local and MPI execution, SSH, schedulers, transfers, attachment and persistent runs. It does not depend on ASE2SPRKKR’s physics parsers. ASE2SPRKKR interprets completed calculations through its output reader layer. See Remote running, MPI and execution profiles for execution profiles and Persistent project calculations for persistent calculations.
Development and documentation
Source builds and optional tools are described in Installation and upgrading.
The authoritative README is doc_src/README.rst and
make docs synchronizes the root README.md. API documentation
and the examples gallery are generated from Python sources; avoid
editing generated pages. See CLI command plugins for CLI extension.
Files and processing (maintainers)
Task definitions provide KKRunner with input, output and cache file declarations. Scientific format descriptions and result readers belong to ASE2SPRKKR, not to the execution library. The files needed for reconnection must remain available until postprocessing finishes. A required output must be present; optional outputs can be absent. Application postprocessing may be retried after interruption, so its callbacks should be safe to repeat. See the KKRunner architecture before changing this execution boundary.