Overview

Calculations are run by calling the qccompute.compute() function with the relevant arguments and keywords like this:

from qcdata import Structure, ProgramInput
from qccompute import compute

# Create the Structure
structure = Structure(
    symbols=["O", "H", "H"],
    geometry=[  # type: ignore
        [0.0, 0.0, 0.0],
        [0.52421003, 1.68733646, 0.48074633],
        [1.14668581, -0.45032174, -1.35474466],
    ],
)

# Define the program input
prog_input = ProgramInput(
    program="terachem",
    structure=structure,
    calctype="energy",
    model={"method": "wb97xd3", "basis": "def2-svp"},
    keywords={"purify": "no", "restricted": False},
)

# Run the calculation; will return a ProgramOutput or raise an exception
result = compute(prog_input, collect_files=True)

The compute function resolves a codec and executes its native invocation. It also accepts an explicit local codec=. The available arguments are:

qccompute.main.compute(input_data: InputType | Sequence[InputType], *, codec: qccodec.Codec | None = None, environment: Mapping[str, str] | None = None, scratch_dir: StrOrPath | None = None, rm_scratch_dir: bool = True, collect_logs: bool = True, collect_files: bool = False, collect_wfn: bool = False, update_func: Callable[..., None] | None = None, update_interval: float | None = None, print_logs: bool = False, raise_exc: bool = True, propagate_wfn: bool = False, options: Mapping[str, Any] | None = None, timeout: float | None = None, executables: Mapping[str, str] | None = None, max_workers: int | None = None) -> ProgramOutput[InputType, Data] | list[ProgramOutput[InputType, Data]]

Compute one input, or a list of inputs in parallel, with a local runner.

A single input returns a single ProgramOutput. A list (or tuple) returns a list of outputs in input order; its inputs may be for different programs, and every other argument applies to each of them. Calculations that run as programs (ORCA, xtb, Psi4, ...) run side by side in threads. Calculations that run in Python (geomeTRIC, tblite) take over a process's output streams while they run, so two or more of them run side by side in worker processes, which start with the numerical libraries' thread counts set to their share. All of them draw on the max_workers budget. Inputs a codec can evaluate together (machine-learned potentials sharing a model) run in batches in this process, one call per batch of up to codec.max_batch; execution.extras records batch_size and batch_index.

Parameters:

Name	Type	Description	Default
input_data	InputType | Sequence[InputType]	A qcdata input object, such as ProgramInput or FileInput, or a list of them.	required
codec	Codec | None	The qccodec.Codec translating this program's inputs and outputs. If None, resolve one with qccodec.get_codec(input_data): a codec registered with qccodec.register, a built-in, or one installed by another package.	None
environment	Mapping[str, str] | None	Process environment overrides mapping strings to strings. Applied after the inherited environment and codec defaults. Subprocess overrides affect only the child. Python calls temporarily change the current process's environment, working directory, and output streams; use separate processes for parallel Python calculations. Environment settings must be applied before the relevant native library initializes.	None
scratch_dir	StrOrPath | None	The calculation directory, not its parent; not accepted with a list of inputs. If None, create a directory in the system's temporary directory. Each concurrent call needs its own directory. This directory, including any existing contents, is deleted when rm_scratch_dir is True.	None
rm_scratch_dir	bool	Delete the calculation directory after execution, decoding, and file collection finish, including on failure.	True
collect_logs	bool	Retain merged stdout/stderr in ProgramOutput.logs. Available logs are always retained for failed calculations.	True
collect_files	bool	Collect files from the calculation directory, excluding files supplied in input_data.files. FileInput always collects these files. Decoders can access generated files regardless of this setting.	False
collect_wfn	bool	Collect wavefunction files identified by the codec. Not every codec supports this. Ignored when collect_files is True, which retains all generated files including wavefunction files.	False
update_func	Callable[..., None] | None	Callback accepting (all_logs, new_logs), both strings. Subprocess updates arrive during execution; Python output is delivered after invocation. No callback is made for empty output. For a list of inputs it receives (index, all_logs, new_logs), where index is the input's position, and is called from the threads running the calculations, so it must be thread-safe.	None
update_interval	float | None	Minimum seconds between subprocess log updates; defaults to 0.5. Updates are line-based, and final output is delivered without waiting for this interval. Has no effect on Python calls.	None
print_logs	bool	Print merged stdout/stderr using the update callback. Ignored when update_func is supplied. Python logs print after invocation. For a list, each line is prefixed with its input's index, e.g. [3].	False
raise_exc	bool	Raise a qccompute exception on calculation failure, with the completed ProgramOutput attached as .prog_output. If False, return the failed output instead. Partial results and diagnostics are retained when available. For a list, every calculation runs first; then ComputeErrors (an ExceptionGroup) is raised if any failed, holding each failure's exception and every output in .outputs.	True
propagate_wfn	bool	For integrations that request child calculations, such as geometry optimization, use the child codec's restart support to prepare each input from the previous result. Requires a child-calculation integration and support for collecting and restarting from wavefunctions.	False
options	Mapping[str, Any] | None	Program-specific decode options passed to the codec, such as {"collect_rotamers": True} for CREST. Each codec declares the options it accepts in codec.options; unknown keys are rejected.	None
timeout	float | None	Seconds each external program may run before it and the processes it started are killed, raising ProgramTimeoutError with any partial results attached. Applies to every subprocess, including child calculations of Python integrations such as geomeTRIC; a Python callable itself is not interrupted.	None
executables	Mapping[str, str] | None	Executables to run, keyed by program name, such as {"orca": "/opt/orca/orca"}. Child calculations of Python integrations such as geomeTRIC use the same mapping; entries for programs that do not run are ignored. Without an entry, the environment variable QCCOMPUTE_<PROGRAM>_EXECUTABLE (for example QCCOMPUTE_ORCA_EXECUTABLE) is used, and otherwise the program is found on PATH. Bare names are looked up on PATH; the program always runs by its absolute path, recorded in execution.extras["executable"].	None
max_workers	int | None	For a list of inputs, the CPU threads program calculations may use at once. Defaults to the number of CPU cores this process may use. Each calculation counts the threads its codec declares (ORCA pal, Psi4 -n, CREST threads; one otherwise), and each GPU calculation gets its own devices through CUDA_VISIBLE_DEVICES. Ignored for a single input.	None

Returns:

Type	Description
ProgramOutput[InputType, Data] | list[ProgramOutput[InputType, Data]]	A ProgramOutput containing scientific results, execution metadata, and the
ProgramOutput[InputType, Data] | list[ProgramOutput[InputType, Data]]	requested logs and files, or a list of them in input order for a list of
ProgramOutput[InputType, Data] | list[ProgramOutput[InputType, Data]]	inputs. Failed calculations may contain partial results.

Raises:

Type	Description
CodecNotFoundError	No codec is available for the requested program.
InputError	Inputs or compute options are unsupported or invalid.
ProgramNotFoundError	The executable cannot be found, or a codec explicitly reports an unavailable dependency.
ProgramTimeoutError	A program exceeded timeout.
ExternalProgramError	Execution, decoding, artifact collection, or cleanup fails. Unexpected codec exceptions also use this category.
ComputeErrors	For a list of inputs, some calculations failed.

Calculation exceptions are raised only when raise_exc is True.

Source code in src/qccompute/main.py

def compute(
    input_data: InputType | Sequence[InputType],
    *,
    codec: qccodec.Codec | None = None,
    environment: Mapping[str, str] | None = None,
    scratch_dir: StrOrPath | None = None,
    rm_scratch_dir: bool = True,
    collect_logs: bool = True,
    collect_files: bool = False,
    collect_wfn: bool = False,
    update_func: Callable[..., None] | None = None,
    update_interval: float | None = None,
    print_logs: bool = False,
    raise_exc: bool = True,
    propagate_wfn: bool = False,
    options: Mapping[str, Any] | None = None,
    timeout: float | None = None,
    executables: Mapping[str, str] | None = None,
    max_workers: int | None = None,
) -> ProgramOutput[InputType, Data] | list[ProgramOutput[InputType, Data]]:
    """Compute one input, or a list of inputs in parallel, with a local runner.

    A single input returns a single ``ProgramOutput``. A list (or tuple) returns a
    list of outputs in input order; its inputs may be for different programs, and
    every other argument applies to each of them. Calculations that run as programs
    (ORCA, xtb, Psi4, ...) run side by side in threads. Calculations that run in
    Python (geomeTRIC, tblite) take over a process's output streams while they run,
    so two or more of them run side by side in worker processes, which start with the
    numerical libraries' thread counts set to their share. All of them draw on the
    ``max_workers`` budget. Inputs a codec can evaluate together (machine-learned
    potentials sharing a model) run in batches in this process, one call per batch
    of up to ``codec.max_batch``; ``execution.extras`` records ``batch_size`` and
    ``batch_index``.

    Args:
        input_data: A qcdata input object, such as ProgramInput or FileInput, or a
            list of them.
        codec: The ``qccodec.Codec`` translating this program's inputs and outputs.
            If None, resolve one with ``qccodec.get_codec(input_data)``: a codec
            registered with ``qccodec.register``, a built-in, or one installed by
            another package.
        environment: Process environment overrides mapping strings to strings.
            Applied after the inherited environment and codec defaults. Subprocess
            overrides affect only the child. Python calls temporarily change the
            current process's environment, working directory, and output streams;
            use separate processes for parallel Python calculations. Environment
            settings must be applied before the relevant native library initializes.
        scratch_dir: The calculation directory, not its parent; not accepted with a
            list of inputs. If None, create a
            directory in the system's temporary directory. Each concurrent call
            needs its own directory. This directory, including any existing
            contents, is deleted when rm_scratch_dir is True.
        rm_scratch_dir: Delete the calculation directory after execution, decoding,
            and file collection finish, including on failure.
        collect_logs: Retain merged stdout/stderr in ProgramOutput.logs. Available
            logs are always retained for failed calculations.
        collect_files: Collect files from the calculation directory, excluding files
            supplied in input_data.files. FileInput always collects these files.
            Decoders can access generated files regardless of this setting.
        collect_wfn: Collect wavefunction files identified by the codec. Not every
            codec supports this. Ignored when collect_files is True, which retains
            all generated files including wavefunction files.
        update_func: Callback accepting (all_logs, new_logs), both strings.
            Subprocess updates arrive during execution; Python output is delivered
            after invocation. No callback is made for empty output. For a list of
            inputs it receives (index, all_logs, new_logs), where index is the
            input's position, and is called from the threads running the
            calculations, so it must be thread-safe.
        update_interval: Minimum seconds between subprocess log updates; defaults
            to 0.5. Updates are line-based, and final output is delivered without
            waiting for this interval. Has no effect on Python calls.
        print_logs: Print merged stdout/stderr using the update callback. Ignored
            when update_func is supplied. Python logs print after invocation. For a
            list, each line is prefixed with its input's index, e.g. ``[3]``.
        raise_exc: Raise a qccompute exception on calculation failure, with the
            completed ProgramOutput attached as .prog_output. If False, return
            the failed output instead. Partial results and diagnostics are retained
            when available. For a list, every calculation runs first; then
            ``ComputeErrors`` (an ``ExceptionGroup``) is raised if any failed, holding
            each failure's exception and every output in ``.outputs``.
        propagate_wfn: For integrations that request child calculations, such as
            geometry optimization, use the child codec's restart support to prepare
            each input from the previous result. Requires a child-calculation
            integration and support for collecting and restarting from wavefunctions.
        options: Program-specific decode options passed to the codec, such as
            ``{"collect_rotamers": True}`` for CREST. Each codec declares the
            options it accepts in ``codec.options``; unknown keys are rejected.
        timeout: Seconds each external program may run before it and the processes
            it started are killed, raising ``ProgramTimeoutError`` with any partial
            results attached. Applies to every subprocess, including child
            calculations of Python integrations such as geomeTRIC; a Python
            callable itself is not interrupted.
        executables: Executables to run, keyed by program name, such as
            ``{"orca": "/opt/orca/orca"}``. Child calculations of Python
            integrations such as geomeTRIC use the same mapping; entries for programs
            that do not run are ignored. Without an entry, the environment variable
            ``QCCOMPUTE_<PROGRAM>_EXECUTABLE`` (for example
            ``QCCOMPUTE_ORCA_EXECUTABLE``) is used, and otherwise the program is
            found on ``PATH``. Bare names are looked up on ``PATH``; the program
            always runs by its absolute path, recorded in
            ``execution.extras["executable"]``.
        max_workers: For a list of inputs, the CPU threads program calculations may
            use at once. Defaults to the number of CPU cores this process may use.
            Each calculation counts the threads its codec declares (ORCA ``pal``,
            Psi4 ``-n``, CREST ``threads``; one otherwise), and each GPU calculation
            gets its own devices through ``CUDA_VISIBLE_DEVICES``. Ignored for a
            single input.

    Returns:
        A ProgramOutput containing scientific results, execution metadata, and the
        requested logs and files, or a list of them in input order for a list of
        inputs. Failed calculations may contain partial results.

    Raises:
        CodecNotFoundError: No codec is available for the requested program.
        InputError: Inputs or compute options are unsupported or invalid.
        ProgramNotFoundError: The executable cannot be found, or a codec explicitly
            reports an unavailable dependency.
        ProgramTimeoutError: A program exceeded ``timeout``.
        ExternalProgramError: Execution, decoding, artifact collection, or cleanup
            fails. Unexpected codec exceptions also use this category.

        ComputeErrors: For a list of inputs, some calculations failed.

    Calculation exceptions are raised only when raise_exc is True.
    """
    if isinstance(input_data, Sequence) and not isinstance(input_data, str | bytes):
        return compute_list(
            _compute_one,
            input_data,
            compute_batch=_compute_batch,
            max_workers=max_workers,
            raise_exc=raise_exc,
            update_func=update_func,
            print_logs=print_logs,
            options={
                "codec": codec,
                "environment": environment,
                "scratch_dir": scratch_dir,
                "rm_scratch_dir": rm_scratch_dir,
                "collect_logs": collect_logs,
                "collect_files": collect_files,
                "collect_wfn": collect_wfn,
                "update_interval": update_interval,
                "propagate_wfn": propagate_wfn,
                "options": options,
                "timeout": timeout,
                "executables": executables,
            },
        )
    return _compute_one(
        input_data,
        codec=codec,
        environment=environment,
        scratch_dir=scratch_dir,
        rm_scratch_dir=rm_scratch_dir,
        collect_logs=collect_logs,
        collect_files=collect_files,
        collect_wfn=collect_wfn,
        update_func=update_func,
        update_interval=update_interval,
        print_logs=print_logs,
        raise_exc=raise_exc,
        propagate_wfn=propagate_wfn,
        options=options,
        timeout=timeout,
        executables=executables,
    )

Examples for each program

Complete, runnable scripts for every program and calculation type, with every common option shown and the program's quirks explained, are on the qccodec program pages. The examples here cover qccompute itself: running a program from your own input files and defining a codec for a program qccodec doesn't support.