Skip to content

Migrating from qccompute 0.22

qccompute 0.23 runs programs through one protocol. It no longer depends on qccodec: the external programs qccodec supports are programs that qccodec registers, installed with pip install qccompute[qccodec]. There are no compatibility shims; this page lists every change.

Installing

0.22 0.23
pip install qccompute (installed qccodec) pip install qccompute[qccodec] for external programs
pip install qccompute[geometric], [tcpb], [all] pip install qccompute[qccodec] qccodec[geometric] (or [tcpb], [sella])

Running one calculation

# 0.22
out = qccompute.compute(inp, collect_files=True, print_logs=True, raise_exc=True)

# 0.23
out = qccompute.compute(inp)

A calculation runs with one thread count: its threads keyword (keywords={"threads": 8}), else the runner's whole count (every core this process may use, or OMP_NUM_THREADS if it is set). Nothing runs more threads at once than its runner has: to run many calculations at once, set threads (usually 1) on each, or run them as a list. See Threads.

compute takes store, timeout, rerun, tags, meta, raise_exc and progress. The removed options:

0.22 option 0.23
codec= register a program: qccompute.register_program(qccodec.CodecProgram(codec))
executables={"orca": path}, QCCOMPUTE_ORCA_EXECUTABLE QCCODEC_ORCA_EXECUTABLE, or CodecProgram(codec, executable=path) registered
environment= CodecProgram(codec, environment={...}) registered, or the process's environment
scratch_dir=, rm_scratch_dir= gone: each calculation's scratch directory is made on first use and removed
collect_logs= gone: external programs' logs are always in output.logs
collect_files= gone for ProgramInput; a FileInput returns every file the command wrote
collect_wfn=, propagate_wfn= gone; a program's own session keeps its warm start between steps
options={"collect_rotamers": True} (CREST) the keyword {"output": {"rotamers": True}}
print_logs=, update_func=, update_interval= gone: logs arrive with the output; progress= receives the events programs emit while they run
max_workers= qccompute.Runner(threads=...), and threads on each input
compute_args(...) build a ProgramInput

Failures

0.22 raised its own exception classes (InputError, ExternalProgramError, ProgramNotFoundError, ProgramTimeoutError, ... from qccompute.exceptions) with the output as prog_output. 0.23 raises qcdata.ProgramError with the output as output, and the kind of failure in error.kind:

0.22 0.23: ProgramError with error.kind
InputError input (or unsupported for a calctype the program does not compute)
ProgramNotFoundError, CodecNotFoundError environment
ProgramTimeoutError timeout
ExternalProgramError internal, or the program's own kind
e.prog_output e.output
ComputeErrors from qccompute.exceptions, e.input_index, e.outputs qcdata.ProgramErrors; .results in input order
# 0.22
try:
    out = compute(inp)
except ExternalProgramError as e:
    logs = e.prog_output.logs

# 0.23
try:
    out = qccompute.compute(inp)
except qcdata.ProgramError as e:
    logs = e.output.logs

Lists

compute(list) shares the runner's threads among the inputs that run, instead of running max_workers at once. A program that evaluates many inputs at once gets them together; there is no batch_size or batch_index in execution.extras beyond what a program records, and the batch's wall time is execution.timings["batch"]. qccompute.submit(inp) returns a concurrent.futures.Future of one output, whose cancel() ends the calculation even while it runs; concurrent.futures.as_completed yields submitted futures as they finish. Submitted calculations start in the order submitted.

The runner

0.22 0.23
compute(..., max_workers=) qccompute.Runner(threads=, gpus=, isolation=)
a backend argument gone: a runner runs on this machine
GPUs shared between calculations each GPU goes to one calculation at a time; machine-learned potentials batch many inputs in one call

Sessions

qccompute.session(spec, structure, threads=..., **compute_options) is qccompute.session(inp, calctypes=None, threads=None, progress=None): build the input with ProgramInput.from_spec(spec, structure). compute_many now runs every request and then raises qcdata.ProgramErrors when any failed, with every frame in results. A session's requests share its thread count and hold it only while they run.

Programs

0.22 0.23
compute(self, inp, ctx) returned a failed output compute(self, inp, ctx=None) raises ProgramError (with output=)
local_context(...) for direct calls of a program with subprograms with ctx=None it returns qccompute.compute(inp)
Capabilities.driver gone: a program runs subprograms through ctx.compute and ctx.session
Capabilities.gpu gone: a calculation's GPUs are its plan's (plan.resources.gpus)
Resources.exclusive gone: the runner never gave a calculation the machine to itself; run it alone, or on a Runner of its own
RunContext(compute=..., open_session=..., make_scratch=..., scratch_dir=..., progress=...) runners make contexts; ctx.compute(), ctx.session(), ctx.scratch, ctx.timeout, ctx.progress (None unless the caller listens)
a program ran any program through its context ctx.compute and ctx.session run only programs the input names among its subprograms (kind input, code unnamed_subprogram)
compute_batch returns failures in place, refused inputs included
qccompute.get_program qccompute.program.find_program
qccompute.utils.available_programs qccompute.program.available_programs
check_program(..., children=...) register the subprograms; check_program also checks the thread count
thread counts from the caller every program accepts the shared threads keyword and runs on ctx.threads, at most; it may use fewer where more don't help (its own cap). Plans state no threads (Resources has no threads)

A program may declare numerics(spec), which a store uses to tell runs of different code apart; without it the version stands in. A FunctionProgram's version and numerics are a digest of its functions unless version= names them.

A program in a worker process (geomeTRIC, Sella) runs its subprograms in the caller's process, so a subprogram may be a program registered there (a FunctionProgram in a script).