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 |
None
|
timeout |
float | None
|
See |
None
|
rerun |
bool
|
See |
False
|
tags |
Sequence[str]
|
See |
()
|
meta |
Mapping[str, Any] | None
|
See |
None
|
raise_exc |
bool
|
See |
True
|
progress |
ProgressCallback | None
|
See |
None
|
Returns:
| Type | Description |
|---|---|
Output | list[Output]
|
The output, or the outputs in input order. |
Raises:
| Type | Description |
|---|---|
ProgramError
|
The calculation failed; |
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 | |
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 |
None
|
timeout |
float | None
|
See |
None
|
rerun |
bool
|
See |
False
|
tags |
Sequence[str]
|
See |
()
|
meta |
Mapping[str, Any] | None
|
See |
None
|
progress |
ProgressCallback | None
|
See |
None
|
Returns:
| Type | Description |
|---|---|
Future[Output]
|
A future of the output; |
Future[Output]
|
failed calculation, and |
Future[Output]
|
|
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 | |
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 |
None
|
progress |
ProgressCallback | None
|
See |
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 | |
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 |
None
|
gpus |
Literal['auto'] | Sequence[str]
|
GPUs it may use: |
'auto'
|
isolation |
Literal['auto', 'process']
|
|
'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 | |
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 | |
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]
|
( |
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 | |
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 ( |
None
|
timeout |
float | None
|
Seconds each calculation may run, from when it starts; past it,
the calculation fails with kind |
None
|
rerun |
bool
|
Run even when the store has a reusable output. |
False
|
tags |
Sequence[str]
|
Tags for every key computed or reused (needs |
()
|
meta |
Mapping[str, Any] | None
|
Metadata stored with each run (needs |
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 |
None
|
Returns:
| Type | Description |
|---|---|
Output | list[Output]
|
The output, or the outputs in input order. |
Raises:
| Type | Description |
|---|---|
ProgramError
|
The calculation failed; its |
ProgramErrors
|
Some calculations of a list failed; |
RuntimeError
|
Called from a thread that is running a calculation or a
session request (a program uses |
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 | |
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 |
None
|
timeout |
float | None
|
See |
None
|
rerun |
bool
|
See |
False
|
tags |
Sequence[str]
|
See |
()
|
meta |
Mapping[str, Any] | None
|
See |
None
|
progress |
ProgressCallback | None
|
See |
None
|
Returns:
| Type | Description |
|---|---|
Future[Output]
|
The future: its |
Future[Output]
|
|
Future[Output]
|
|
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 |
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 | |
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 |
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 |
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 | |
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 |
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 | |
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 | |
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 | |
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 | |
tag(key: str, *tags: str) -> None
¶
Add tags to a key.
Source code in src/qccompute/runner.py
168 169 170 | |
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 | |
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 |
required |
threads |
int | None
|
CPU threads the process's numerical libraries start with (the
|
None
|
gpus |
Sequence[str] | None
|
GPUs the process sees ( |
None
|
environment |
Mapping[str, str] | None
|
More environment variables for the process. |
None
|
Raises:
| Type | Description |
|---|---|
ProgramError
|
The worker did not start (kind |
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 | |
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 | |
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 |
None
|
Returns:
| Type | Description |
|---|---|
ProgramOutput[Any, Data]
|
The successful output. |
Raises:
| Type | Description |
|---|---|
ProgramError
|
The calculation failed ( |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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; |
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 | |
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 | |
plan() -> Plan
¶
The session's pinned plan.
Source code in src/qccompute/worker.py
861 862 863 | |
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 | |
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_filesandcallssay what theoptionsmessage may turn on. - Every message carries an
id; replies are{"id", "ok": true, "result"}or{"id", "ok": false, "error": ErrorInfo}.ok: falseis 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}. ctxis{threads, memory_gib, device_memory_gib, timeout, scratch_dir, gpus, progress, stop_file, identities}. The GPU is fixed when the worker is spawned, sogpusmust be empty or matchCUDA_VISIBLE_DEVICES.stop_filenames 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 atthreads(at one thread for an input that names subprograms, whose grant it is). Withprogress: truethe program's progress events (ctx.progress), each with itspathfrom 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, codenon_finite). -
optionssets 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.npyfile 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 (itsctx.computeandctx.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 theidentitiesthe client gave in the message'sctx, 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 | |
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 | |
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 |
None
|
Attributes:
| Name | Type | Description |
|---|---|---|
connection |
_Connection | None
|
The client being served, through which the program's subprograms
run when it asked for |
Source code in src/qccompute/serve.py
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
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 | |
op_close(msg: dict[str, Any]) -> None
¶
Close a session.
Source code in src/qccompute/serve.py
477 478 479 480 481 | |
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 | |
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 | |
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, |
int
|
|
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 | |
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: |
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 | |