Calling within python

Everything koopmans run does is available from python, for scripting parameter sweeps or driving calculations from a notebook. The same input that lives in a JSON or YAML file can be read or constructed directly, and three verbs cover the life of a calculation:

koopmans.build() prepares the calculation without running anything, so an input can be checked cheaply;
koopmans.run() runs it to completion, blocking until it finishes, and returns its outputs;
koopmans.submit() hands it to the background daemon and returns the calculation’s integer id immediately (or with wait=True, blocks like run).

Outputs come back as a plain dict, keyed by output name with every value a plain python or numpy one — energies in eV:

from koopmans import read_input_file, run

results = run(read_input_file("ozone.yaml"))

print(f"IP = {-results['parameters']['homo_energy']:.2f} eV")
print(f"EA = {-results['parameters']['lumo_energy']:.2f} eV")

An input can equally be built without a file — it is the same object the file parser produces:

from koopmans import KoopmansInput, outputs, submit

inp = KoopmansInput(
    workflow={"task": "singlepoint", "correction": "ki"},
    # ... the same blocks an input file holds ...
)
pk = submit(inp)  # returns immediately; the daemon runs it
# ... later, in this session or another:
results = outputs(pk)

The integer id survives the python session, and koopmans.outputs() reads the finished calculation back by it — raising, rather than returning half a result, while the calculation still runs or if it failed. Provenance is stored by AiiDA, the workflow engine underneath; none of its machinery is needed to read outputs back, and the per-step directory layout koopmans run writes is available from koopmans.aiida.dumping.dump_workgraph.

Reference

Drive koopmans calculations from python.

build / run / submit take a KoopmansInput and mirror the workgraph verbs of the underlying AiiDA engine. A finished calculation is read back as a plain dict of its outputs — deserialized to python / numpy values and keyed by output socket name — either from run directly or from outputs() given the calculation’s integer id. Output socket names are public API: renaming one is a user-breaking change, reviewed like a schema keyword.

build(koopmans_input: KoopmansInput) → WorkGraph[source]: Materialize the calculation’s workgraph without running it.

outputs(pk: int) → dict[str, Any][source]

Return the outputs of the finished calculation pk, deserialized.

Keyed by output socket name, with nested namespaces as nested dicts and every value a plain python / numpy one. Remote-scratch and retrieved-file handles have no plain python analogue and are omitted. A calculation that is still running, or failed, raises instead.

run(koopmans_input: KoopmansInput) → dict[str, Any][source]

Run the calculation to completion in this interpreter.

Blocks until the calculation finishes and returns its outputs (outputs()); a calculation that fails raises instead.

submit(koopmans_input: KoopmansInput, *, wait: bool = False) → int[source]

Hand the calculation to the daemon and return its integer id.

With wait=True the call blocks until the daemon finishes the calculation. The id survives the python session; read the finished calculation back with outputs().