Skip to content

Running

qccompute.compute, qccompute.submit and qccompute.session are the methods of the default runner. A Runner of your own takes a share of the machine; see the guide.

qccompute.runner.compute(inputs: Input | Sequence[Input], *, store: Store | None = None, timeout: float | None = None, rerun: bool = False, tags: Sequence[str] = (), meta: Mapping[str, Any] | None = None, raise_exc: bool = True, progress: ProgressCallback | None = None) -> Output | list[Output]

Run one input or a list on this machine: Runner.compute of the default runner.

Parameters:

Name Type Description Default
inputs Input | Sequence[Input]

One input, or a list of them (of any programs).

required
store Store | None

See Runner.compute.

None
timeout float | None

See Runner.compute.

None
rerun bool

See Runner.compute.

False
tags Sequence[str]

See Runner.compute.

()
meta Mapping[str, Any] | None

See Runner.compute.

None
raise_exc bool

See Runner.compute.

True
progress ProgressCallback | None

See Runner.compute.

None

Returns:

Type Description
Output | list[Output]

The output, or the outputs in input order.

Raises:

Type Description
ProgramError

The calculation failed; output is the failed output.

ProgramErrors

Some calculations of a list failed.

Source code in src/qccompute/runner.py
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
def compute(
    inputs: Input | Sequence[Input],
    *,
    store: Store | None = None,
    timeout: float | None = None,
    rerun: bool = False,
    tags: Sequence[str] = (),
    meta: Mapping[str, Any] | None = None,
    raise_exc: bool = True,
    progress: ProgressCallback | None = None,
) -> Output | list[Output]:
    """Run one input or a list on this machine: `Runner.compute` of the default runner.

    Args:
        inputs: One input, or a list of them (of any programs).
        store: See `Runner.compute`.
        timeout: See `Runner.compute`.
        rerun: See `Runner.compute`.
        tags: See `Runner.compute`.
        meta: See `Runner.compute`.
        raise_exc: See `Runner.compute`.
        progress: See `Runner.compute`.

    Returns:
        The output, or the outputs in input order.

    Raises:
        ProgramError: The calculation failed; ``output`` is the failed output.
        ProgramErrors: Some calculations of a list failed.
    """
    return default_runner().compute(
        inputs,
        store=store,
        timeout=timeout,
        rerun=rerun,
        tags=tags,
        meta=meta,
        raise_exc=raise_exc,
        progress=progress,
    )

qccompute.runner.submit(inp: Input, *, store: Store | None = None, timeout: float | None = None, rerun: bool = False, tags: Sequence[str] = (), meta: Mapping[str, Any] | None = None, progress: ProgressCallback | None = None) -> Future[Output]

Start one calculation on this machine: Runner.submit of the default runner.

Parameters:

Name Type Description Default
inp Input

The input.

required
store Store | None

See Runner.compute.

None
timeout float | None

See Runner.compute.

None
rerun bool

See Runner.compute.

False
tags Sequence[str]

See Runner.compute.

()
meta Mapping[str, Any] | None

See Runner.compute.

None
progress ProgressCallback | None

See Runner.compute.

None

Returns:

Type Description
Future[Output]

A future of the output; result() raises qcdata.ProgramError for a

Future[Output]

failed calculation, and cancel() ends it even while it runs (see

Future[Output]

Runner.submit).

Source code in src/qccompute/runner.py
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
def submit(
    inp: Input,
    *,
    store: Store | None = None,
    timeout: float | None = None,
    rerun: bool = False,
    tags: Sequence[str] = (),
    meta: Mapping[str, Any] | None = None,
    progress: ProgressCallback | None = None,
) -> Future[Output]:
    """Start one calculation on this machine: `Runner.submit` of the default runner.

    Args:
        inp: The input.
        store: See `Runner.compute`.
        timeout: See `Runner.compute`.
        rerun: See `Runner.compute`.
        tags: See `Runner.compute`.
        meta: See `Runner.compute`.
        progress: See `Runner.compute`.

    Returns:
        A future of the output; ``result()`` raises `qcdata.ProgramError` for a
        failed calculation, and ``cancel()`` ends it even while it runs (see
        `Runner.submit`).
    """
    return default_runner().submit(
        inp,
        store=store,
        timeout=timeout,
        rerun=rerun,
        tags=tags,
        meta=meta,
        progress=progress,
    )

qccompute.runner.session(inp: ProgramInput, calctypes: Iterable[CalcType | str] | None = None, *, threads: int | None = None, progress: ProgressCallback | None = None) -> Session

Open a session on this machine: Runner.session of the default runner.

Parameters:

Name Type Description Default
inp ProgramInput

The program, model, keywords, structure, and the default calctype.

required
calctypes Iterable[CalcType | str] | None

The calctypes the session may run.

None
threads int | None

See Runner.session.

None
progress ProgressCallback | None

See Runner.session.

None

Returns:

Type Description
Session

The session.

Source code in src/qccompute/runner.py
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
def session(
    inp: ProgramInput,
    calctypes: Iterable[CalcType | str] | None = None,
    *,
    threads: int | None = None,
    progress: ProgressCallback | None = None,
) -> Session:
    """Open a session on this machine: `Runner.session` of the default runner.

    Args:
        inp: The program, model, keywords, structure, and the default calctype.
        calctypes: The calctypes the session may run.
        threads: See `Runner.session`.
        progress: See `Runner.session`.

    Returns:
        The session.
    """
    return default_runner().session(inp, calctypes, threads=threads, progress=progress)

qccompute.runner.Runner(threads: int | None = None, gpus: Literal['auto'] | Sequence[str] = 'auto', isolation: Literal['auto', 'process'] = 'auto')

Runs programs on a share of this machine: one input, a list, or a session.

Parameters:

Name Type Description Default
threads int | None

The runner's thread count: the most threads its calculations run at once, and what a calculation that sets no threads gets. None: OMP_NUM_THREADS if set (a dispatcher's choice), else every core this process may use (its affinity and cgroup quota).

None
gpus Literal['auto'] | Sequence[str]

GPUs it may use: "auto" for every visible GPU (CUDA_VISIBLE_DEVICES or nvidia-smi, see visible_gpus), or a list of device identifiers as for CUDA_VISIBLE_DEVICES; () for none. With "auto" and CUDA_VISIBLE_DEVICES unset, the runner sets CUDA_DEVICE_ORDER=PCI_BUS_ID (unless set), so CUDA numbers the GPUs as nvidia-smi does. A calculation gets whole GPUs.

'auto'
isolation Literal['auto', 'process']

"auto" runs programs in this process unless they cannot share it (in_process=False), which run in worker processes; "process" runs every program in a worker process, so a crash ends only the worker.

'auto'

A runner never changes a number: it hands each calculation its thread count, GPUs and memory (qccompute.program.RunContext) and the program decides. It never runs more threads at once than its own count; work beyond it waits its turn (the docs' Threads page). Close a runner (or use it as a context manager) to stop its worker processes.

Source code in src/qccompute/runner.py
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
def __init__(
    self,
    threads: int | None = None,
    gpus: Literal["auto"] | Sequence[str] = "auto",
    isolation: Literal["auto", "process"] = "auto",
) -> None:
    """Create a runner."""
    if isolation not in ("auto", "process"):
        raise ValueError(f"isolation is 'auto' or 'process', not {isolation!r}.")
    if threads is not None and (isinstance(threads, bool) or threads < 1):
        raise ValueError("threads must be a positive integer.")
    self.threads: int = threads or default_threads()
    self.isolation = isolation
    self._gpus_arg = gpus
    self._gpus: dict[str, float | None] | None = (
        None if gpus == "auto" else {str(g): None for g in gpus}
    )
    if gpus == "auto":  # before any program starts CUDA (its plan may)
        _pci_bus_order()
    self._memory: float | None | Literal[False] = False
    self._entries: dict[int, _Entry] = {}
    self._entries_lock = threading.Lock()
    # Workers by pool (program and GPUs), each with its users: calls in flight
    # and open sessions; workers being started, by pool.
    self._pools: dict[tuple[str, tuple[str, ...]], dict[Worker, int]] = {}
    self._starting: dict[tuple[str, tuple[str, ...]], int] = {}
    self._pools_changed = threading.Condition()
    self._all_workers: weakref.WeakSet[Worker] = weakref.WeakSet()
    self._closed = False
    # The count top-level work runs under; submitted calculations' threads and
    # futures not yet done.
    self._count = Count(self.threads, warn=True)
    self._submitting = threading.Lock()
    self._futures: ThreadPoolExecutor | None = None
    self._submitted: set[_Future] = set()

gpus: tuple[str, ...] property

The GPUs this runner uses (found on first use for "auto").

close() -> None

Stop this runner's worker processes; it cannot run in workers afterwards.

Submitted calculations that have not started are cancelled, and so is work waiting for the runner's threads. A worker still running a calculation (from another thread) is killed with every process it started; that calculation fails with kind environment.

Source code in src/qccompute/runner.py
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
def close(self) -> None:
    """Stop this runner's worker processes; it cannot run in workers afterwards.

    Submitted calculations that have not started are cancelled, and so is work
    waiting for the runner's threads. A worker still running a calculation (from
    another thread) is killed with every process it started; that calculation
    fails with kind ``environment``.
    """
    with self._submitting:
        futures, self._futures = self._futures, None
        waiting = [f for f in self._submitted if not f._control.started]
    for future in waiting:
        future.cancel()
    self._count.close()
    if futures is not None:
        futures.shutdown(wait=False, cancel_futures=True)
    with self._pools_changed:
        self._closed = True
        self._pools.clear()
        self._pools_changed.notify_all()
    for worker in list(self._all_workers):
        worker.close()

identities(inp: Input) -> dict[str, str]

The numerics identity of the input's program and of every subprogram.

{name: numerics}, by name, recursively through the subprograms' own subprograms, from the programs this runner would run now, each asked with its own spec (qccompute.program.numerics_of). A program named with several specs gets its distinct identities sorted and joined by ";" ("gfn2:5;gxtb-2.0.1:7"), so the map stays {program: string}. A program that is not installed is left out.

Parameters:

Name Type Description Default
inp Input

The input.

required

Returns:

Type Description
dict[str, str]

The identities the runner sets on the input's output

dict[str, str]

(execution.identities), and a store files its run under.

Source code in src/qccompute/runner.py
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
def identities(self, inp: Input) -> dict[str, str]:
    """The numerics identity of the input's program and of every subprogram.

    ``{name: numerics}``, by name, recursively through the subprograms' own
    subprograms, from the programs this runner would run now, each asked with its
    own spec (`qccompute.program.numerics_of`). A program named with several specs
    gets its distinct identities sorted and joined by ``";"``
    (``"gfn2:5;gxtb-2.0.1:7"``), so the map stays ``{program: string}``. A program
    that is not installed is left out.

    Args:
        inp: The input.

    Returns:
        The identities the runner sets on the input's output
        (``execution.identities``), and a store files its run under.
    """
    if not isinstance(inp, ProgramInput):
        entry = self._entry(inp)
        return {} if entry is None else {FILES: numerics_of(entry.program, inp)}
    found: dict[str, set[str]] = {}
    pending: list[ProgramSpec] = [inp]
    while pending:
        spec = pending.pop()
        program = find_program(spec.program)
        if program is not None:
            found.setdefault(spec.program, set()).add(numerics_of(program, spec))
        pending.extend(spec.subprograms)
    return {name: ";".join(sorted(found[name])) for name in sorted(found)}

compute(inputs: Input | Sequence[Input], *, store: Store | None = None, timeout: float | None = None, rerun: bool = False, tags: Sequence[str] = (), meta: Mapping[str, Any] | None = None, raise_exc: bool = True, progress: ProgressCallback | None = None) -> Output | list[Output]

Run one input, or a list of independent inputs side by side.

Every input is planned first: an input its program refuses fails at once, without running. One calculation gets the runner's whole thread count unless it sets threads; a list shares it, each input getting the count divided by the inputs that run (store hits don't count), and inputs of a program with batches go to it together in one call. Work beyond the runner's count waits its turn. The docs' Threads page explains the rules.

Parameters:

Name Type Description Default
inputs Input | Sequence[Input]

One input, or a list of them (of any programs).

required
store Store | None

Look each input up first and return a reusable stored output; store every output that ran, with the identities of the programs that made it (identities). A stored run is reused only when its identities are those of the programs the runner would run now: a success always, a failure only when the input determines it (kind input, unsupported or convergence, or program with such a cause); rerun=True runs past it.

None
timeout float | None

Seconds each calculation may run, from when it starts; past it, the calculation fails with kind timeout. Programs that start processes enforce it, and the runner kills programs in worker processes. In this process it is the program's to honour (ctx.timeout): the runner cannot stop a thread, and only starts none of its subprograms after it. For a hard limit on any program, use isolation="process".

None
rerun bool

Run even when the store has a reusable output.

False
tags Sequence[str]

Tags for every key computed or reused (needs store).

()
meta Mapping[str, Any] | None

Metadata stored with each run (needs store).

None
raise_exc bool

Raise for failures (after every input of a list ran); False returns failed outputs in place.

True
progress ProgressCallback | None

Called with the events programs emit while they run (qcopt: one per step): small JSON objects, each with "path", the program names from the input down to the program that emitted it (a subprogram's events come through its parent). It may be called from several threads at once, and must be quick; an exception it raises is a warning. Stored outputs emit nothing; nothing is stored. A list's events do not say which input they are from: submit each input with a callable of its own for that.

None

Returns:

Type Description
Output | list[Output]

The output, or the outputs in input order.

Raises:

Type Description
ProgramError

The calculation failed; its output is the failed output, with partial results and logs.

ProgramErrors

Some calculations of a list failed; results holds every output in input order.

RuntimeError

Called from a thread that is running a calculation or a session request (a program uses ctx.compute).

Source code in src/qccompute/runner.py
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
def compute(
    self,
    inputs: Input | Sequence[Input],
    *,
    store: Store | None = None,
    timeout: float | None = None,
    rerun: bool = False,
    tags: Sequence[str] = (),
    meta: Mapping[str, Any] | None = None,
    raise_exc: bool = True,
    progress: ProgressCallback | None = None,
) -> Output | list[Output]:
    """Run one input, or a list of independent inputs side by side.

    Every input is planned first: an input its program refuses fails at once,
    without running. One calculation gets the runner's whole thread count unless
    it sets ``threads``; a list shares it, each input getting the count divided by
    the inputs that run (store hits don't count), and inputs of a program with
    batches go to it together in one call. Work beyond the runner's count waits
    its turn. The docs' Threads page explains the rules.

    Args:
        inputs: One input, or a list of them (of any programs).
        store: Look each input up first and return a reusable stored output; store
            every output that ran, with the identities of the programs that made
            it (`identities`). A stored run is reused only when its identities
            are those of the programs the runner would run now: a success always,
            a failure only when the input determines it (kind ``input``,
            ``unsupported`` or ``convergence``, or ``program`` with such a cause);
            ``rerun=True`` runs past it.
        timeout: Seconds each calculation may run, from when it starts; past it,
            the calculation fails with kind ``timeout``. Programs that start
            processes enforce it, and the runner kills programs in worker
            processes. In this process it is the program's to honour
            (``ctx.timeout``): the runner cannot stop a thread, and only starts
            none of its subprograms after it. For a hard limit on any program, use
            ``isolation="process"``.
        rerun: Run even when the store has a reusable output.
        tags: Tags for every key computed or reused (needs ``store``).
        meta: Metadata stored with each run (needs ``store``).
        raise_exc: Raise for failures (after every input of a list ran); False
            returns failed outputs in place.
        progress: Called with the events programs emit while they run (qcopt:
            one per step): small JSON objects, each with ``"path"``, the program
            names from the input down to the program that emitted it (a
            subprogram's events come through its parent). It may be called from
            several threads at once, and must be quick; an exception it raises
            is a warning. Stored outputs emit nothing; nothing is stored. A
            list's events do not say which input they are from: `submit` each
            input with a callable of its own for that.

    Returns:
        The output, or the outputs in input order.

    Raises:
        ProgramError: The calculation failed; its ``output`` is the failed
            output, with partial results and logs.
        ProgramErrors: Some calculations of a list failed; ``results`` holds
            every output in input order.
        RuntimeError: Called from a thread that is running a calculation or a
            session request (a program uses ``ctx.compute``).
    """
    check_free()
    if (tags or meta) and store is None:
        raise ValueError("tags and meta are stored with runs: pass a store.")
    if timeout is not None and not timeout > 0:
        raise ValueError("timeout must be a positive number of seconds.")
    if isinstance(inputs, ProgramInput | FileInput):
        out, failure = self._one(
            inputs, store, timeout, rerun, tags, meta, progress
        )
        if failure is not None and raise_exc:
            raise failure
        return out
    inputs = list(inputs)
    outputs: list[Output | None] = [None] * len(inputs)
    failures: dict[int, ProgramError] = {}
    listed = self._run_list(
        inputs, store, rerun, tags, meta, self._top(), timeout, None, progress
    )
    for i, out, failure in listed:
        outputs[i] = out
        if failure is not None:
            failures[i] = failure
    done = [o for o in outputs if o is not None]
    if failures and raise_exc:
        raise ProgramErrors(
            f"{len(failures)} of {len(inputs)} calculations failed",
            [failures[i] for i in sorted(failures)],
            done,
        )
    return done

submit(inp: Input, *, store: Store | None = None, timeout: float | None = None, rerun: bool = False, tags: Sequence[str] = (), meta: Mapping[str, Any] | None = None, progress: ProgressCallback | None = None) -> Future[Output]

Start one calculation and return at once: a future of its output.

For workflows whose next calculations depend on earlier ones (per reaction, a transition-state search, then the IRC from its saddle, then both ends minimized): submit each calculation when its inputs are known, and the next as each future finishes (concurrent.futures.wait, as_completed or add_done_callback).

A stored output, or an input its program refuses, resolves the future before this returns. The others start in the order submitted, as the runner's threads allow: a calculation without a threads keyword takes all of them, so to run many at once, set threads (usually 1) on each input (the docs' Threads page). A calculation never waits on a future itself: a program runs its subprograms through ctx.compute.

Parameters:

Name Type Description Default
inp Input

The input.

required
store Store | None

See compute.

None
timeout float | None

See compute; counted from when the calculation starts.

None
rerun bool

See compute.

False
tags Sequence[str]

See compute.

()
meta Mapping[str, Any] | None

See compute.

None
progress ProgressCallback | None

See compute; the calculation's events, from the threads that run it.

None

Returns:

Type Description
Future[Output]

The future: its result() is the output, or raises

Future[Output]

qcdata.ProgramError with the failed output, as compute does.

Future[Output]

future.cancel() cancels the calculation even while it runs: a

Future[Output]

waiting one never starts; a running one in a worker process is killed

Future[Output]

with every process it started, and one in this process ends at its next

Future[Output]

look at ctx.timeout (which reads 0) and starts no more subprograms,

Future[Output]

as for a timeout. A cancelled calculation's output is never stored.

Raises:

Type Description
RuntimeError

Called from a thread that is running a calculation or a session request.

Source code in src/qccompute/runner.py
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
def submit(
    self,
    inp: Input,
    *,
    store: Store | None = None,
    timeout: float | None = None,
    rerun: bool = False,
    tags: Sequence[str] = (),
    meta: Mapping[str, Any] | None = None,
    progress: ProgressCallback | None = None,
) -> Future[Output]:
    """Start one calculation and return at once: a future of its output.

    For workflows whose next calculations depend on earlier ones (per reaction, a
    transition-state search, then the IRC from its saddle, then both ends
    minimized): submit each calculation when its inputs are known, and the next as
    each future finishes (``concurrent.futures.wait``, ``as_completed`` or
    ``add_done_callback``).

    A stored output, or an input its program refuses, resolves the future before
    this returns. The others start in the order submitted, as the runner's
    threads allow: a calculation without a ``threads`` keyword takes all of them,
    so to run many at once, set ``threads`` (usually 1) on each input (the docs'
    Threads page). A calculation never waits on a future itself: a program runs
    its subprograms through ``ctx.compute``.

    Args:
        inp: The input.
        store: See `compute`.
        timeout: See `compute`; counted from when the calculation starts.
        rerun: See `compute`.
        tags: See `compute`.
        meta: See `compute`.
        progress: See `compute`; the calculation's events, from the threads
            that run it.

    Returns:
        The future: its ``result()`` is the output, or raises
        `qcdata.ProgramError` with the failed output, as `compute` does.
        ``future.cancel()`` cancels the calculation even while it runs: a
        waiting one never starts; a running one in a worker process is killed
        with every process it started, and one in this process ends at its next
        look at ``ctx.timeout`` (which reads 0) and starts no more subprograms,
        as for a timeout. A cancelled calculation's output is never stored.

    Raises:
        RuntimeError: Called from a thread that is running a calculation or a
            session request.
    """
    check_free()
    if (tags or meta) and store is None:
        raise ValueError("tags and meta are stored with runs: pass a store.")
    if timeout is not None and not timeout > 0:
        raise ValueError("timeout must be a positive number of seconds.")
    key = ""
    if store is not None:
        key, hit = self._lookup(store, inp, rerun)
        if hit is not None:
            if tags:
                store.tag(key, *tags)
            return _resolved(hit, None if hit.success else _error(hit))
    try:
        entry, plan = self._plan(inp)
    except Exception as e:  # noqa: BLE001 - refused before running
        out, failure = _refused(inp, e, self.identities(inp))
        if store is not None:
            _put(store, key, out, tags, meta)
        return _resolved(out, failure)
    holder = self._top()
    gpus = self._gpus_of(holder, plan)
    threads = _threads(inp, holder.threads, _unasked(inp, gpus, holder.threads))
    task = _Task(0, inp, entry, plan, threads, gpus)
    control = _Control()
    future = _Future(control)
    stored = (store, key, tags, meta)
    with self._submitting:
        if self._futures is None:
            self._futures = ThreadPoolExecutor(
                self.threads, thread_name_prefix="qccompute-submit"
            )
        self._submitted.add(future)
        self._futures.submit(
            self._run_submitted, task, future, timeout, progress, stored, control
        )
    future.add_done_callback(self._submitted.discard)
    return future

stop(future: Future[Output]) -> bool

Ask a submitted calculation to stop at its next step, keeping what it reached.

The program sees the request as ctx.stop_requested() (in a worker process too), ends at its next step and returns its partial output (a search's frames so far) as a failure of kind stopped: future.result() raises qcdata.ProgramError with it as output. The request covers the calculation's subprograms, and one that has not started yet stops at its first step. A program with no steps runs to its end. A stopped output is never stored. Unlike future.cancel(), which discards the calculation, a stop keeps what it reached.

Parameters:

Name Type Description Default
future Future[Output]

A future from submit.

required

Returns:

Type Description
bool

Whether the request was made: False once the calculation is done.

Raises:

Type Description
ValueError

The future is not one submit made.

Source code in src/qccompute/runner.py
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
def stop(self, future: Future[Output]) -> bool:
    """Ask a submitted calculation to stop at its next step, keeping what it reached.

    The program sees the request as ``ctx.stop_requested()`` (in a worker process
    too), ends at its next step and returns its partial output (a search's frames
    so far) as a failure of kind ``stopped``: ``future.result()`` raises
    `qcdata.ProgramError` with it as ``output``. The request covers the
    calculation's subprograms, and one that has not started yet stops at its
    first step. A program with no steps runs to its end. A stopped output is never
    stored. Unlike ``future.cancel()``, which discards the calculation, a stop
    keeps what it reached.

    Args:
        future: A future from `submit`.

    Returns:
        Whether the request was made: False once the calculation is done.

    Raises:
        ValueError: The future is not one `submit` made.
    """
    return _stop(future)

session(inp: ProgramInput, calctypes: Iterable[CalcType | str] | None = None, *, threads: int | None = None, progress: ProgressCallback | None = None) -> Session

Open a session: one program and molecule at many geometries.

A program with sessions of its own (capabilities().sessions) opens one, pinned to the input's settings and warm-started between geometries: in this process it is the program's own session, behind a thin wrapper that counts its requests' threads. Programs in worker processes give a session over the worker's pipe, with the same methods; sessions of a program on a GPU share its worker there. For any other program the session runs each geometry through compute, from scratch (record["warm_start"] is false): it is a convenience, not a speed-up.

The session's thread count is threads, else its input's threads keyword, else the runner's whole count (1 for a session given GPUs). Each request runs on it: the requests of a compute_many, and requests from several threads at once, share it. An open session that computes nothing holds no threads. A session gets the GPUs its plan asks for.

Parameters:

Name Type Description Default
inp ProgramInput

The program, model, keywords and structure; its calctype and geometry are the defaults of a request.

required
calctypes Iterable[CalcType | str] | None

The calctypes the session may run (default: everything the method supports; declaring narrows it).

None
threads int | None

The session's thread count (at most the runner's).

None
progress ProgressCallback | None

Called with the events the program emits while the session runs requests; see compute.

None

Returns:

Type Description
Session

The session; use it as a context manager, or close it.

Raises:

Type Description
ProgramError

The program is not installed or rejects the input.

Source code in src/qccompute/runner.py
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
def session(
    self,
    inp: ProgramInput,
    calctypes: Iterable[CalcType | str] | None = None,
    *,
    threads: int | None = None,
    progress: ProgressCallback | None = None,
) -> Session:
    """Open a session: one program and molecule at many geometries.

    A program with sessions of its own (``capabilities().sessions``) opens one,
    pinned to the input's settings and warm-started between geometries: in this
    process it is the program's own session, behind a thin wrapper that counts
    its requests' threads. Programs in worker processes give a session over the
    worker's pipe, with the same methods; sessions of a program on a GPU share its
    worker there. For any other program the session runs each geometry through
    ``compute``, from scratch (``record["warm_start"]`` is false): it is a
    convenience, not a speed-up.

    The session's thread count is ``threads``, else its input's ``threads``
    keyword, else the runner's whole count (1 for a session given GPUs). Each
    request runs on it: the requests of a ``compute_many``, and requests from
    several threads at once, share it. An open session that computes nothing
    holds no threads. A session gets the GPUs its plan asks for.

    Args:
        inp: The program, model, keywords and structure; its calctype and
            geometry are the defaults of a request.
        calctypes: The calctypes the session may run (default: everything the
            method supports; declaring narrows it).
        threads: The session's thread count (at most the runner's).
        progress: Called with the events the program emits while the session
            runs requests; see `compute`.

    Returns:
        The session; use it as a context manager, or close it.

    Raises:
        ProgramError: The program is not installed or rejects the input.
    """
    if threads is not None and (isinstance(threads, bool) or threads < 1):
        raise ValueError("threads must be a positive integer.")
    return self._open_session(inp, calctypes, threads, self._top(), None, progress)

qccompute.runner.Store

What a runner needs of a calculation store (qcstore.Store implements it).

A key names a calculation: qcdata.calculation_key(inp), the input as given. Which code produced a run's numbers is kept apart from the key, as the run's identities: {program: numerics} for the input's program and every subprogram it names, which the runner sets on every output it returns (output.execution.identities).

key(inp: Input) -> str

The key of an input.

Source code in src/qccompute/runner.py
150
151
152
def key(self, inp: Input) -> str:
    """The key of an input."""
    ...

get(key: str, identities: Mapping[str, str]) -> Output | None

The preferred run of a key made with exactly these identities, if any.

Source code in src/qccompute/runner.py
154
155
156
def get(self, key: str, identities: Mapping[str, str]) -> Output | None:
    """The preferred run of a key made with exactly these identities, if any."""
    ...

put(output: Output, *, tags: Sequence[str] = (), meta: Mapping[str, Any] | None = None) -> str

Store a run under its input's key and output.execution.identities.

Source code in src/qccompute/runner.py
158
159
160
161
162
163
164
165
166
def put(
    self,
    output: Output,
    *,
    tags: Sequence[str] = (),
    meta: Mapping[str, Any] | None = None,
) -> str:
    """Store a run under its input's key and ``output.execution.identities``."""
    ...

tag(key: str, *tags: str) -> None

Add tags to a key.

Source code in src/qccompute/runner.py
168
169
170
def tag(self, key: str, *tags: str) -> None:
    """Add tags to a key."""
    ...

qccompute.runner.default_runner() -> Runner

The runner of qccompute.compute: this machine, made on first use.

It shares every core this process may use and every visible GPU (each calculation gets the threads it asks for: 1 unless its input or program says more), runs programs in this process unless they cannot share it, and closes its workers at exit. It cannot be reconfigured; make a Runner for anything else.

Source code in src/qccompute/runner.py
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
def default_runner() -> Runner:
    """The runner of ``qccompute.compute``: this machine, made on first use.

    It shares every core this process may use and every visible GPU (each calculation
    gets the threads it asks for: 1 unless its input or program says more), runs
    programs in this process unless they cannot share it, and closes its workers at
    exit. It cannot be reconfigured; make a `Runner` for anything else.
    """
    global _default
    if _default is None:
        with _default_lock:
            if _default is None:
                _default = Runner()
                atexit.register(_default.close)
    return _default

Workers

qccompute.worker.Worker(program: str, *, threads: int | None = None, gpus: Sequence[str] | None = None, environment: Mapping[str, str] | None = None)

One program in a worker process of its own.

Parameters:

Name Type Description Default
program str

The program's name (an installed program) or module:attribute.

required
threads int | None

CPU threads the process's numerical libraries start with (the THREAD_VARIABLES, unless the environment sets them); each call's own threads come in its ctx, at which the worker holds the BLAS and OpenMP pools while the call runs. None: not set.

None
gpus Sequence[str] | None

GPUs the process sees (CUDA_VISIBLE_DEVICES); None: as this one.

None
environment Mapping[str, str] | None

More environment variables for the process.

None

Raises:

Type Description
ProgramError

The worker did not start (kind environment, code worker_died): the program is not installed, or its import failed.

Source code in src/qccompute/worker.py
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
def __init__(
    self,
    program: str,
    *,
    threads: int | None = None,
    gpus: Sequence[str] | None = None,
    environment: Mapping[str, str] | None = None,
) -> None:
    """Start the worker, read its hello and set the connection's options."""
    env = dict(os.environ)
    # The worker imports what this process can import; not through PYTHONPATH,
    # which programs the worker starts (Psi4, other Pythons) would inherit.
    env[PATH_VARIABLE] = os.pathsep.join(p for p in sys.path if p)
    if threads is not None:
        for name in THREAD_VARIABLES:
            env.setdefault(name, str(threads))
    if gpus is not None:
        env["CUDA_VISIBLE_DEVICES"] = ",".join(gpus)
    env.update(environment or {})
    self.spec = program
    # The worker's calculations make their temporary scratch in it, so a worker
    # killed mid-calculation leaves none behind once this is removed (`close`).
    self._scratch = Path(tempfile.mkdtemp(prefix="qccompute-worker-"))
    self._proc = subprocess.Popen(
        [
            sys.executable,
            *("-m", "qccompute.serve", program),
            *("--scratch", str(self._scratch)),
        ],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        env=env,
    )
    self._stderr: collections.deque[str] = collections.deque(maxlen=40)
    threading.Thread(target=self._drain, daemon=True).start()
    self._lock = threading.Lock()
    self._write_lock = threading.Lock()
    self._ids = 0
    self._dead: ProgramError | None = None
    # The caller's control of the message in flight, the file that asks it to
    # stop, and whether it cancelled it; the controls this worker has served.
    self._flight_lock = threading.Lock()
    self._flight: _Control | None = None
    self._stop_file: Path | None = None
    self._stops: Path | None = None  # a directory for stop files, made on use
    self._cancelled = False
    self._watched: weakref.WeakSet[_Control] = weakref.WeakSet()
    self._dir: Path | None = None
    assert self._proc.stdout is not None and self._proc.stdin is not None
    self._lines = _wire.Lines(self._proc.stdout.fileno())
    self._in: IO[bytes] = self._proc.stdin
    self._parent = _Parent()
    self._calls = Host(self._parent)
    line = self._lines.readline()
    if not line:
        raise self._died("did not start")
    hello = json.loads(line)
    self.hello: dict[str, Any] = hello
    self.name: str = hello["program"]
    self.capabilities: Capabilities = Capabilities.model_validate(
        hello["capabilities"]
    )
    if hello.get("array_files") or hello.get("calls"):
        if hello.get("array_files"):
            self._dir = Path(tempfile.mkdtemp(prefix="qccompute-worker-"))
            self._calls.array_dir = self._dir
        self._ask(
            "options",
            array_dir=None if self._dir is None else str(self._dir),
            calls=bool(hello.get("calls")),
        )

alive: bool property

Whether the worker can take work.

version() -> str

The program's version, from the worker's hello.

Source code in src/qccompute/worker.py
260
261
262
def version(self) -> str:
    """The program's version, from the worker's hello."""
    return str(self.hello["version"])

compute(inp: ProgramInput | FileInput, ctx: RunContext | None = None) -> ProgramOutput[Any, Data]

Run one calculation in the worker.

Parameters:

Name Type Description Default
inp ProgramInput | FileInput

The input.

required
ctx RunContext | None

The grant; its timeout is enforced by killing the worker, and the program's subprograms run within it.

None

Returns:

Type Description
ProgramOutput[Any, Data]

The successful output.

Raises:

Type Description
ProgramError

The calculation failed (output is the failed output), timed out, or the worker died.

Source code in src/qccompute/worker.py
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
def compute(
    self, inp: ProgramInput | FileInput, ctx: RunContext | None = None
) -> ProgramOutput[Any, Data]:
    """Run one calculation in the worker.

    Args:
        inp: The input.
        ctx: The grant; its ``timeout`` is enforced by killing the worker, and the
            program's subprograms run within it.

    Returns:
        The successful output.

    Raises:
        ProgramError: The calculation failed (``output`` is the failed output),
            timed out, or the worker died.
    """
    timeout = ctx.timeout if ctx is not None else None
    result = self._ask(
        "compute", timeout, ctx, input=self._dump(inp), ctx=self._ctx(ctx)
    )
    out: ProgramOutput[Any, Data] = self._load(ProgramOutput, result)
    if not out.success:
        error = out.error or ErrorInfo(kind=ErrorKind.internal, message="failed")
        raise ProgramError(error, output=out)
    return out

compute_batch(inputs: Sequence[ProgramInput | FileInput], ctx: RunContext | None = None) -> list[ProgramOutput[Any, Data]]

Run many calculations together in the worker; failures in place.

Raises:

Type Description
ProgramError

The worker died or timed out.

Source code in src/qccompute/worker.py
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
def compute_batch(
    self, inputs: Sequence[ProgramInput | FileInput], ctx: RunContext | None = None
) -> list[ProgramOutput[Any, Data]]:
    """Run many calculations together in the worker; failures in place.

    Raises:
        ProgramError: The worker died or timed out.
    """
    timeout = ctx.timeout if ctx is not None else None
    result = self._ask(
        "compute_batch",
        timeout,
        ctx,
        inputs=[self._dump(i) for i in inputs],
        ctx=self._ctx(ctx),
    )
    return [self._load(ProgramOutput, r) for r in result]

plan(inp: ProgramInput) -> Plan

The program's plan of an input.

Raises:

Type Description
ProgramError

The program refuses the input.

Source code in src/qccompute/worker.py
504
505
506
507
508
509
510
def plan(self, inp: ProgramInput) -> Plan:
    """The program's plan of an input.

    Raises:
        ProgramError: The program refuses the input.
    """
    return Plan.model_validate(self._ask("plan", input=self._dump(inp)))

session(inp: ProgramInput, calctypes: Iterable[CalcType | str] | None = None, ctx: RunContext | None = None, *, on_close: Callable[[], None] | None = None) -> WorkerSession | ComputeSession

Open a session in the worker: the program's own, else one over compute.

Parameters:

Name Type Description Default
inp ProgramInput

The program, model, keywords, structure, and the default calctype.

required
calctypes Iterable[CalcType | str] | None

The calctypes the session may run.

None
ctx RunContext | None

The session's grant.

None
on_close Callable[[], None] | None

Called when the session closes (a runner returns the worker to its pool).

None

Returns:

Type Description
WorkerSession | ComputeSession

The session.

Raises:

Type Description
ProgramError

The program refuses the input, or the worker died.

Source code in src/qccompute/worker.py
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
def session(
    self,
    inp: ProgramInput,
    calctypes: Iterable[CalcType | str] | None = None,
    ctx: RunContext | None = None,
    *,
    on_close: Callable[[], None] | None = None,
) -> WorkerSession | ComputeSession:
    """Open a session in the worker: the program's own, else one over compute.

    Args:
        inp: The program, model, keywords, structure, and the default calctype.
        calctypes: The calctypes the session may run.
        ctx: The session's grant.
        on_close: Called when the session closes (a runner returns the worker
            to its pool).

    Returns:
        The session.

    Raises:
        ProgramError: The program refuses the input, or the worker died.
    """
    if not self.capabilities.sessions:
        opened = _ClosingComputeSession(
            lambda i, raise_exc=True: self._compute_any(i, ctx, raise_exc),
            inp,
            calctypes,
            program_version=self.version(),
        )
        opened.on_close = on_close
        return opened
    reply = self._ask(
        "open",
        None,
        ctx,
        input=self._dump(inp),
        calctypes=sorted(CalcType(c).value for c in calctypes)
        if calctypes
        else None,
        ctx=self._ctx(ctx),
    )
    version = str(reply.get("program_version") or self.version())
    return WorkerSession(self, reply["session"], inp, version, on_close, ctx)

close() -> None

Stop the worker: end of input closes its sessions and it exits.

A worker with a message in flight (a calculation running in another thread) is killed with every process it started, rather than waited for.

Source code in src/qccompute/worker.py
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
def close(self) -> None:
    """Stop the worker: end of input closes its sessions and it exits.

    A worker with a message in flight (a calculation running in another thread)
    is killed with every process it started, rather than waited for.
    """
    if self._lock.locked():
        self._kill()
    if self._proc.poll() is None:
        try:
            self._in.close()
        except OSError:
            pass
        try:
            self._proc.wait(timeout=30)
        except subprocess.TimeoutExpired:
            self._kill()
            self._proc.wait()
    self._dead = self._dead or ProgramError.of(
        "environment", f"The worker for {self.spec} is closed.", code="worker_died"
    )
    self._calls.close_all()  # sessions its program opened here
    if self._proc.poll() is not None and self._proc.stdout is not None:
        self._proc.stdout.close()
    for directory in (self._dir, self._stops):
        if directory is not None:
            shutil.rmtree(directory, ignore_errors=True)
    if not _keep_scratch():  # what a killed worker's calculations left
        shutil.rmtree(self._scratch, ignore_errors=True)

qccompute.worker.WorkerSession(worker: _Peer, key: str, inp: ProgramInput, program_version: str = '', on_close: Callable[[], None] | None = None, grant: RunContext | None = None)

A session in another process; see qccompute.program.Session.

A program's own session in a worker, or, inside a worker, a subprogram's session in its client. Positions and results cross the pipe as shortest round-trip decimals (large arrays as .npy files), so they are bit for bit those of the session in process.

Source code in src/qccompute/worker.py
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
def __init__(
    self,
    worker: _Peer,
    key: str,
    inp: ProgramInput,
    program_version: str = "",
    on_close: Callable[[], None] | None = None,
    grant: RunContext | None = None,
) -> None:
    """Wrap an open session of a worker."""
    self._worker = worker
    self._key = key
    self._inp = inp
    self._on_close = on_close
    self._grant = grant
    self._closed = False
    self.program: str = inp.program
    self.program_version: str = program_version

input_data: ProgramInput property

The input the session was opened with.

compute(positions: np.ndarray | None = None, calctype: CalcType | str | None = None, *, accuracy: Accuracy | float | None = None, lineage: Lineage = None, outputs: Iterable[str] = (), seed: Iterable[Lineage] = (), commit: bool = True) -> Frame

Evaluate one geometry; see qccompute.program.Session.compute.

Raises:

Type Description
ProgramError

The evaluation failed (with its failed frame), or the worker died.

Source code in src/qccompute/worker.py
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
def compute(
    self,
    positions: np.ndarray | None = None,
    calctype: CalcType | str | None = None,
    *,
    accuracy: Accuracy | float | None = None,
    lineage: Lineage = None,
    outputs: Iterable[str] = (),
    seed: Iterable[Lineage] = (),
    commit: bool = True,
) -> Frame:
    """Evaluate one geometry; see `qccompute.program.Session.compute`.

    Raises:
        ProgramError: The evaluation failed (with its failed frame), or the worker
            died.
    """
    request = Request(
        positions=positions,
        calctype=None if calctype is None else CalcType(calctype),
        accuracy=accuracy,
        lineage=lineage,
        outputs=frozenset(outputs),
        seed=list(seed),
        commit=commit,
    )
    if request.positions is not None and not np.all(np.isfinite(request.positions)):
        raise ProgramError.of(
            "numerical", "positions are not finite", code="non_finite"
        )
    frame = self._frame(self._ask("compute", **_request_fields(request)), request)
    if not frame.success:
        error = frame.error or ErrorInfo(kind=ErrorKind.internal, message="failed")
        raise ProgramError(error, frame=frame)
    return frame

compute_many(requests: Sequence[Request]) -> list[Frame]

Evaluate many geometries; see qccompute.program.Session.compute_many.

Requests with non-finite positions fail here (the wire carries no NaN); the others run in the worker.

Raises:

Type Description
ProgramErrors

Some requests failed; results holds every frame.

Source code in src/qccompute/worker.py
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
def compute_many(self, requests: Sequence[Request]) -> list[Frame]:
    """Evaluate many geometries; see `qccompute.program.Session.compute_many`.

    Requests with non-finite positions fail here (the wire carries no NaN); the
    others run in the worker.

    Raises:
        ProgramErrors: Some requests failed; ``results`` holds every frame.
    """
    frames: list[Frame | None] = [None] * len(requests)
    sent: list[int] = []
    for i, r in enumerate(requests):
        if r.positions is not None and not np.all(np.isfinite(r.positions)):
            structure = self._inp.require_structure().model_copy(
                update={"geometry": r.positions}
            )
            error = ProgramError.of(
                "numerical", "positions are not finite", code="non_finite"
            )
            frames[i] = failed_frame(structure, error, self.program)
        else:
            sent.append(i)
    if sent:
        result = self._ask(
            "compute_many", requests=[_request_fields(requests[i]) for i in sent]
        )
        for i, f in zip(sent, result, strict=True):
            frames[i] = self._frame(f, requests[i])
    return ProgramErrors.check([f for f in frames if f is not None])

reset(lineage: Lineage = ...) -> None

Forget one lineage's history (None: the default one); omitted: all.

Source code in src/qccompute/worker.py
854
855
856
857
858
859
def reset(self, lineage: Lineage = ...) -> None:
    """Forget one lineage's history (None: the default one); omitted: all."""
    if lineage is ...:
        self._ask("reset")
    else:
        self._ask("reset", lineage=lineage)

plan() -> Plan

The session's pinned plan.

Source code in src/qccompute/worker.py
861
862
863
def plan(self) -> Plan:
    """The session's pinned plan."""
    return Plan.model_validate(self._ask("plan"))

close() -> None

Close the session in the worker.

Source code in src/qccompute/worker.py
865
866
867
868
869
870
871
872
873
874
875
876
def close(self) -> None:
    """Close the session in the worker."""
    if self._closed:
        return
    self._closed = True
    if self._worker.alive:
        try:
            self._ask("close")
        except ProgramError:
            pass
    if self._on_close is not None:
        self._on_close()

qccompute.serve

The worker: one loop that hosts any program's sessions in its own process.

python -m qccompute.serve mychem                  # stdin/stdout, one client
python -m qccompute.serve mychem --socket PATH    # a Unix socket, one client at a time
python -m qccompute.serve mychem --scratch DIR    # temporary scratch made in DIR

A qccompute.worker.Worker gives its worker a --scratch directory of its own and removes it when the worker ends, so a killed worker leaves no scratch behind.

A worker keeps a program alive between calls (warm starts, a live GPU context) and isolates it: a crash ends the worker, not its caller. The program is found by name (qccompute.program.find_program: registered in this process, else the qccompute.programs entry points), given as module:attribute, or as pickle:PATH, a file holding it pickled (a runner's, for a program registered in its process that no module holds). The loop uses only qcdata and the protocol, and knows nothing of the program beyond it. Design: docs/design/program-interface.md, "Workers".

Wire, one JSON message per line:

  • The first line is the hello: {"protocol": 1, "program", "version", "capabilities", "array_files": true, "calls": true}. array_files and calls say what the options message may turn on.
  • Every message carries an id; replies are {"id", "ok": true, "result"} or {"id", "ok": false, "error": ErrorInfo}. ok: false is for the message itself (bad JSON, an unknown op or session, a failed open or plan); a failed calculation is a result: a failed Frame or ProgramOutput.
  • Ops: open {input, calctypes, ctx} -> {"session", "program_version"}; compute {session, positions, calctype, accuracy, lineage, outputs, seed, commit} -> Frame; compute_many {session, requests} -> [Frame]; reset {session, lineage} (absent: every lineage; null: the default one); plan {session}, {session, calctype} or {input}; close {session}; compute {input, ctx} (a one-off) -> ProgramOutput; compute_batch {inputs, ctx} -> [ProgramOutput]; lineages {session} where the session offers them; options {array_dir, calls}.
  • ctx is {threads, memory_gib, device_memory_gib, timeout, scratch_dir, gpus, progress, stop_file, identities}. The GPU is fixed when the worker is spawned, so gpus must be empty or match CUDA_VISIBLE_DEVICES. stop_file names a file whose existence asks the calculation to stop at its next step (ctx.stop_requested()): the client creates it while the message is in flight, and removes it after. While the message runs, the worker holds its BLAS and OpenMP pools at threads (at one thread for an input that names subprograms, whose grant it is). With progress: true the program's progress events (ctx.progress), each with its path from the worker's program down ([] for its own; a subprogram's name for one the worker ran itself), stream to the client while a message is in flight, as lines {"id", "progress": event} naming the message (for a session, each request's message); an event that is not JSON is dropped, with a note on stderr. A plain client never asks for them and never gets one.
  • Numbers are shortest round-trip decimals, so positions and results cross bit for bit. No NaN or Infinity: a message holding one is refused, and a non-finite result becomes a failed frame (kind numerical, code non_finite).
  • options sets what this connection uses; a plain JSON-lines client never sends it and gets neither:

  • array_dir: a directory both sides can read and write (workers are local). An array field over 1 MiB, in a message either way, crosses as a .npy file there, with qcdata's pointer {path, shape, dtype, sha256} in its place (the format of a saved model's arrays); the reader checks it and deletes the file.

  • calls: true: the client runs the subprograms of this worker's program (its ctx.compute and ctx.session) that the worker cannot run exactly as the client would, so they see the programs the client sees, registered ones included, and share its grant. The worker runs a call itself when every program its input names is found here with the identities the client gave in the message's ctx, may run in process, and its plan uses no GPU. While a message is in flight the worker may write call lines, {"call", "op", ...} with the ops above (compute {input}, compute_batch {inputs}, open {input, calctypes, ctx: {threads}} and the session ops); the client answers each on stdin, {"call", "ok", "result"} or {"call", "ok": false, "error"}, in any order. Without it, subprograms run in the worker's own default runner.
  • End of input closes every session and exits 0. After a reply whose error has the code device_lost (a GPU fault that poisoned the device context) the worker exits 3: nothing more can run in this process.

Hygiene: stdout carries protocol lines only. At start the worker writes the protocol to a dup of the original stdout and points file descriptor 1 at stderr, because CUDA, BLAS and other libraries print.

MessageError(message: str, kind: ErrorKind = ErrorKind.input, code: str | None = None)

A message the worker cannot act on: an ok: false reply.

Parameters:

Name Type Description Default
message str

What is wrong with the message.

required
kind ErrorKind

The error kind.

input
code str | None

A code refining the kind.

None
Source code in src/qccompute/serve.py
142
143
144
145
146
147
148
149
150
151
152
153
def __init__(
    self, message: str, kind: ErrorKind = ErrorKind.input, code: str | None = None
):
    """Create the error.

    Args:
        message: What is wrong with the message.
        kind: The error kind.
        code: A code refining the kind.
    """
    super().__init__(message)
    self.error = ErrorInfo(kind=kind, message=message, code=code)

of(e: ProgramError) -> MessageError classmethod

A program's refusal (of an open or a plan) as a message error.

Source code in src/qccompute/serve.py
155
156
157
158
@classmethod
def of(cls, e: ProgramError) -> MessageError:
    """A program's refusal (of an open or a plan) as a message error."""
    return cls(e.error.message, e.error.kind, e.error.code)

Host(program: Program, array_dir: Path | None = None, scratch: Path | None = None)

The sessions of one program in this process, and the ops on them.

Parameters:

Name Type Description Default
program Program

The program the worker hosts.

required
array_dir Path | None

Where array files cross (the options message sets it per connection); None: arrays cross inline.

None

Attributes:

Name Type Description
connection _Connection | None

The client being served, through which the program's subprograms run when it asked for calls.

Source code in src/qccompute/serve.py
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
def __init__(
    self,
    program: Program,
    array_dir: Path | None = None,
    scratch: Path | None = None,
):
    """Host a program; its calculations' temporary scratch goes in ``scratch``."""
    self.program = program
    self.array_dir = array_dir
    self.scratch = scratch
    self.connection: _Connection | None = None
    self.sessions: dict[str, Session] = {}
    self._threads: dict[str, int | None] = {}  # each session's grant
    self._ids = itertools.count(1)
    self._subprograms = _ClientRunner(self)
    self.device_lost = False
    self._message: Any = None  # the id of the message in flight

hello() -> dict[str, Any]

The worker's first line: protocol, program, version, capabilities, options.

Source code in src/qccompute/serve.py
266
267
268
269
270
271
272
273
274
275
def hello(self) -> dict[str, Any]:
    """The worker's first line: protocol, program, version, capabilities, options."""
    return {
        "protocol": PROTOCOL,
        "program": self.program.name,
        "version": self.program.version(),
        "capabilities": capabilities_of(self.program).model_dump(mode="json"),
        "array_files": True,
        "calls": True,
    }

handle(msg: dict[str, Any]) -> Any

The result of one message: models, lists of them, or plain values.

Raises:

Type Description
MessageError

The message cannot be acted on.

Source code in src/qccompute/serve.py
277
278
279
280
281
282
283
284
285
286
287
288
289
def handle(self, msg: dict[str, Any]) -> Any:
    """The result of one message: models, lists of them, or plain values.

    Raises:
        MessageError: The message cannot be acted on.
    """
    op = msg.get("op")
    fn: Callable[[dict[str, Any]], Any] | None = (
        getattr(self, f"op_{op}", None) if isinstance(op, str) else None
    )
    if fn is None:
        raise MessageError(f"unknown op {op!r}; ops: {_OPS}")
    return fn(msg)

answer(msg: dict[str, Any], key: str = 'id') -> str

The reply line to one parsed message, under key (id, or call).

Source code in src/qccompute/serve.py
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
def answer(self, msg: dict[str, Any], key: str = "id") -> str:
    """The reply line to one parsed message, under ``key`` (``id``, or ``call``)."""
    mid = msg.get(key)
    if key == "id":
        self._message = mid
    try:
        with holding():  # the message runs on its caller's threads
            result = _wire.dump(self.handle(msg), self.array_dir)
        try:
            return _wire.encode({key: mid, "ok": True, "result": result})
        except ValueError:
            return _wire.encode(
                {key: mid, "ok": True, "result": _non_finite(result)}
            )
    except (MessageError, ProgramError) as e:  # ProgramError: a closed session
        error = e.error
    except Exception as e:  # noqa: BLE001 - a bug in the loop or a program: keep serving
        traceback.print_exc(file=sys.stderr)
        error = ErrorInfo(
            kind=ErrorKind.internal, message=f"{type(e).__name__}: {e}"
        )
    return _wire.encode(
        {key: mid, "ok": False, "error": error.model_dump(mode="json")}
    )

op_options(msg: dict[str, Any]) -> dict[str, Any]

Set this connection's array directory and calls; the options in effect.

Source code in src/qccompute/serve.py
316
317
318
319
320
321
322
323
324
325
326
327
def op_options(self, msg: dict[str, Any]) -> dict[str, Any]:
    """Set this connection's array directory and calls; the options in effect."""
    directory = msg.get("array_dir")
    if directory is not None and not Path(directory).is_dir():
        raise MessageError(f"array_dir {directory!r} is not a directory")
    self.array_dir = None if directory is None else Path(directory)
    if self.connection is not None:
        self.connection.calls = bool(msg.get("calls"))
    return {
        "array_dir": directory,
        "calls": self.connection is not None and self.connection.calls,
    }

op_open(msg: dict[str, Any]) -> dict[str, str]

Open a session; its id and the program's version.

Source code in src/qccompute/serve.py
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
def op_open(self, msg: dict[str, Any]) -> dict[str, str]:
    """Open a session; its id and the program's version."""
    if not isinstance(self.program, SessionProgram):
        raise MessageError(
            f"{self.program.name} has no sessions", ErrorKind.unsupported
        )
    inp = self._input(msg)
    if not isinstance(inp, ProgramInput):
        raise MessageError("a session opens from a ProgramInput")
    calctypes = msg.get("calctypes")
    ctx = self._ctx(msg.get("ctx"))
    ctx._calling = inp
    held = own_threads(ctx.threads, (inp,))
    try:
        with hold_threads(held):
            session = self.program.open_session(
                inp,
                ctx,
                frozenset(CalcType(c) for c in calctypes) if calctypes else None,
            )
    except ProgramError as e:
        raise MessageError.of(e) from None
    key = f"s{next(self._ids)}"
    self.sessions[key] = session
    self._threads[key] = held
    return {"session": key, "program_version": session.program_version}

op_compute(msg: dict[str, Any]) -> Any

A session's frame, or a one-off output for input.

Source code in src/qccompute/serve.py
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
def op_compute(self, msg: dict[str, Any]) -> Any:
    """A session's frame, or a one-off output for ``input``."""
    if "input" in msg:
        out = self._compute(self._input(msg), self._ctx(msg.get("ctx")))
        self._watch(out)
        return out
    session = self._session(msg)
    fields = ("positions", "calctype", "accuracy", "lineage", "outputs", "seed")
    r = _request({k: msg[k] for k in (*fields, "commit") if k in msg})
    try:
        with hold_threads(self._threads.get(msg["session"])):
            frame = session.compute(
                r.positions,
                r.calctype,
                accuracy=r.accuracy,
                lineage=r.lineage,
                outputs=r.outputs,
                seed=r.seed,
                commit=r.commit,
            )
    except ProgramError as e:
        frame = e.frame or failed_frame(
            self._structure(session, r), e, self.program.name
        )
    self._watch(frame)
    return frame

op_compute_batch(msg: dict[str, Any]) -> Any

Outputs of many one-off inputs, computed together; failures in place.

Source code in src/qccompute/serve.py
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
def op_compute_batch(self, msg: dict[str, Any]) -> Any:
    """Outputs of many one-off inputs, computed together; failures in place."""
    inputs = [self._input({"input": i}) for i in msg.get("inputs") or []]
    ctx = self._ctx(msg.get("ctx"))
    ctx._calling = inputs
    if isinstance(self.program, BatchProgram):
        try:
            with hold_threads(own_threads(ctx.threads, inputs)):
                outs = list(self.program.compute_batch(inputs, ctx))  # type: ignore[arg-type]
        except MessageError:  # the message refused (a client's subprogram call)
            raise
        except Exception as e:  # noqa: BLE001 - a bug: every input fails with it
            outs = [_failed(i, e, self.program.name) for i in inputs]
    else:
        outs = [self._compute(i, ctx) for i in inputs]
    if ctx._refusal is not None:  # it ran a program no input names: all fail
        outs = [
            _refused(i, ctx._refusal, o) for i, o in zip(inputs, outs, strict=True)
        ]
    outs = [_with_devices(out, ctx.gpus) for out in outs]
    for out in outs:
        self._watch(out)
    return outs

op_compute_many(msg: dict[str, Any]) -> Any

A session's frames for many requests, in order.

Source code in src/qccompute/serve.py
429
430
431
432
433
434
435
436
437
438
439
440
441
def op_compute_many(self, msg: dict[str, Any]) -> Any:
    """A session's frames for many requests, in order."""
    session = self._session(msg)
    frames: list[Frame]
    requests = [_request(r) for r in msg.get("requests") or []]
    try:
        with hold_threads(self._threads.get(msg["session"])):
            frames = session.compute_many(requests)
    except ProgramErrors as group:  # every frame, in order
        frames = group.results
    for frame in frames:
        self._watch(frame)
    return list(frames)

op_reset(msg: dict[str, Any]) -> None

Forget one lineage (null: the default one), or every lineage when absent.

Source code in src/qccompute/serve.py
443
444
445
446
447
448
449
def op_reset(self, msg: dict[str, Any]) -> None:
    """Forget one lineage (null: the default one), or every lineage when absent."""
    session = self._session(msg)
    if "lineage" in msg:
        session.reset(msg["lineage"])
    else:
        session.reset()

op_lineages(msg: dict[str, Any]) -> Any

The session's lineages with history, where the session offers them.

Source code in src/qccompute/serve.py
451
452
453
454
455
456
457
458
def op_lineages(self, msg: dict[str, Any]) -> Any:
    """The session's lineages with history, where the session offers them."""
    lineages = getattr(self._session(msg), "lineages", None)
    if lineages is None:
        raise MessageError(
            "this session does not list lineages", ErrorKind.unsupported
        )
    return list(lineages())

op_plan(msg: dict[str, Any]) -> Any

A session's plan, its input's plan at another calctype, or an input's plan.

Source code in src/qccompute/serve.py
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
def op_plan(self, msg: dict[str, Any]) -> Any:
    """A session's plan, its input's plan at another calctype, or an input's plan."""
    try:
        if "input" in msg:
            return plan_of(self.program, self._input(msg))  # type: ignore[arg-type]
        session = self._session(msg)
        if msg.get("calctype"):
            try:
                calctype = CalcType(msg["calctype"])
            except ValueError as e:
                raise MessageError(str(e)) from None
            inp = session.input_data.model_copy(update={"calctype": calctype})
            return plan_of(self.program, inp)
        return session.plan()
    except ProgramError as e:
        raise MessageError.of(e) from None

op_close(msg: dict[str, Any]) -> None

Close a session.

Source code in src/qccompute/serve.py
477
478
479
480
481
def op_close(self, msg: dict[str, Any]) -> None:
    """Close a session."""
    self._session(msg)
    self._threads.pop(msg["session"], None)
    self.sessions.pop(msg["session"]).close()

close_all() -> None

Close every session, reporting (not raising) failures.

Source code in src/qccompute/serve.py
483
484
485
486
487
488
489
490
491
def close_all(self) -> None:
    """Close every session, reporting (not raising) failures."""
    for session in list(self.sessions.values()):
        try:
            session.close()
        except Exception as e:  # noqa: BLE001 - closing at exit: report, go on
            print(f"qccompute.serve: closing a session: {e}", file=sys.stderr)
    self.sessions.clear()
    self._threads.clear()

load_program(spec: str) -> Program

The program a spec names.

A name (find_program), the object at module:attribute, or pickle:PATH: a file holding the program pickled, which a runner writes for a program registered in its process that no module holds (qccompute.runner._worker_spec).

Raises:

Type Description
SystemExit

No such program.

Source code in src/qccompute/serve.py
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def load_program(spec: str) -> Program:
    """The program a spec names.

    A name (`find_program`), the object at ``module:attribute``, or ``pickle:PATH``:
    a file holding the program pickled, which a runner writes for a program
    registered in its process that no module holds (`qccompute.runner._worker_spec`).

    Raises:
        SystemExit: No such program.
    """
    if spec.startswith("pickle:"):
        with open(spec.removeprefix("pickle:"), "rb") as f:
            loaded: Program = pickle.load(f)
        return loaded
    if ":" in spec:
        module, attr = spec.split(":", 1)
        program: Program = getattr(importlib.import_module(module), attr)
        return program
    found = find_program(spec)
    if found is None:
        raise SystemExit(
            f"qccompute.serve: no program {spec!r} (registered or in the "
            "qccompute.programs entry points)"
        )
    return found

serve(host: Host, lines: Iterable[str], write: Callable[[str], None]) -> int

Answer every message of lines through write, after the hello.

Each call is one connection: its options start unset.

Parameters:

Name Type Description Default
host Host

The program's sessions.

required
lines Iterable[str]

Message lines.

required
write Callable[[str], None]

Writes one reply line (without its newline).

required

Returns:

Type Description
int

The exit status: 0 at the end of input, EXIT_DEVICE_LOST after a

int

device_lost reply.

Source code in src/qccompute/serve.py
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
def serve(host: Host, lines: Iterable[str], write: Callable[[str], None]) -> int:
    """Answer every message of ``lines`` through ``write``, after the hello.

    Each call is one connection: its ``options`` start unset.

    Args:
        host: The program's sessions.
        lines: Message lines.
        write: Writes one reply line (without its newline).

    Returns:
        The exit status: 0 at the end of input, `EXIT_DEVICE_LOST` after a
        ``device_lost`` reply.
    """
    connection = _Connection(iter(lines), write)
    host.connection = connection
    host.array_dir = None
    connection.write(_wire.encode(host.hello()))
    for line in connection.messages():
        if not line.strip():
            continue
        reply = _reply(host, line)
        if reply is None:
            continue
        connection.write(reply)
        if host.device_lost:
            return EXIT_DEVICE_LOST
    return 0

main(argv: list[str] | None = None) -> int

Run a worker; the exit status.

Parameters:

Name Type Description Default
argv list[str] | None

Command-line arguments (default: sys.argv).

None
Source code in src/qccompute/serve.py
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
def main(argv: list[str] | None = None) -> int:
    """Run a worker; the exit status.

    Args:
        argv: Command-line arguments (default: ``sys.argv``).
    """
    parser = argparse.ArgumentParser(
        prog="python -m qccompute.serve",
        description="Host a program's sessions in this process, over JSON lines.",
    )
    parser.add_argument("program", help="a program name, or module:attribute")
    parser.add_argument(
        "--socket", help="serve a Unix socket at this path, one client at a time"
    )
    parser.add_argument(
        "--scratch",
        help="make calculations' temporary scratch directories in this directory, "
        "which the client removes when the worker ends or is killed",
    )
    args = parser.parse_args(argv)
    paths = os.environ.pop("QCCOMPUTE_WORKER_SYS_PATH", "")
    sys.path.extend(p for p in paths.split(os.pathsep) if p and p not in sys.path)
    scratch = Path(args.scratch) if args.scratch else None
    if args.socket is None:
        proto = _protocol_stdout()
        host = Host(load_program(args.program), scratch=scratch)
        try:
            return serve(host, _lines(sys.stdin), _writer(proto))
        finally:
            host.close_all()
    host = Host(load_program(args.program), scratch=scratch)
    sys.stdout = sys.stderr
    path = Path(args.socket)
    path.unlink(missing_ok=True)
    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    server.bind(str(path))
    server.listen()
    try:
        while True:
            conn, _ = server.accept()
            with (
                conn,
                conn.makefile("r", encoding="utf-8") as reader,
                conn.makefile("w", encoding="utf-8") as writer,
            ):
                status = serve(host, _lines(reader), _writer(writer))
            if status:
                return status
    finally:
        host.close_all()
        server.close()
        path.unlink(missing_ok=True)