Metadata-Version: 2.5
Name: qccompute
Version: 0.23.0a3
Summary: Run quantum chemistry programs on qcdata inputs: one input or many, in process or in workers, with a calculation store. External programs come with qccompute[qccodec].
Project-URL: Homepage, https://github.com/atomsforhumanity/qccompute
Project-URL: Source, https://github.com/atomsforhumanity/qccompute
Project-URL: Repository, https://github.com/atomsforhumanity/qccompute
Project-URL: Changelog, https://github.com/atomsforhumanity/qccompute/blob/master/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/atomsforhumanity/qccompute/issues
Project-URL: Documentation, https://qccompute.docs.afh.org
Author-email: Colton Hicks <github@coltonhicks.com>
License: The MIT License (MIT)
        
        Copyright (c) 2021 Colton Hicks
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: qcdata>=0.24.0a4
Provides-Extra: qccodec
Requires-Dist: qccodec>=0.22.0a1; extra == 'qccodec'
Provides-Extra: testing
Requires-Dist: jsonschema>=4.18; extra == 'testing'
Description-Content-Type: text/markdown

# qccompute

[![image](https://img.shields.io/pypi/v/qccompute.svg)](https://pypi.python.org/pypi/qccompute)
[![image](https://img.shields.io/pypi/l/qccompute.svg)](https://pypi.python.org/pypi/qccompute)
[![image](https://img.shields.io/pypi/pyversions/qccompute.svg)](https://pypi.python.org/pypi/qccompute)
[![CI](https://github.com/atomsforhumanity/qccompute/actions/workflows/ci.yaml/badge.svg)](https://github.com/atomsforhumanity/qccompute/actions/workflows/ci.yaml)

Runs quantum chemistry programs on [qcdata](https://github.com/atomsforhumanity/qcdata) inputs: one input or many, in this process or in worker processes, with an optional calculation store. Every program, whether written in Python for the protocol or an external program brought in by [qccodec](https://github.com/atomsforhumanity/qccodec), runs the same way.

**Documentation: [qccompute.docs.afh.org](https://qccompute.docs.afh.org)**

## Install

The new runner is in alpha. Install the alpha line with its matching packages pinned (a plain `pip install qccompute` resolves the previous stable release):

```sh
uv pip install --prerelease=allow "qcdata==0.24.0a2" "qccompute[qccodec]==0.23.0a1" "qcstore==0.1.0a1"
```

`qccompute` alone is the runner, for programs that implement its protocol; the `qccodec` extra adds external programs (xtb, ORCA, Psi4, CREST, ...) and `qcstore` is the calculation store.

## One way to run things

```python
import qccompute
from qcdata import CalcType, Model, ProgramInput, Structure

water = Structure(
    symbols=["O", "H", "H"],
    geometry=[[0.0, 0.0, 0.0], [0.524, 1.687, 0.48], [1.146, -0.45, -1.354]],  # bohr
)
inp = ProgramInput(
    program="xtb", calctype=CalcType.gradient, structure=water, model=Model(method="gfn2")
)

out = qccompute.compute(inp)                 # one input -> ProgramOutput
outs = qccompute.compute([inp] * 8)          # a list runs side by side -> list
with qccompute.session(inp) as s:            # one molecule at many geometries
    frame = s.compute(water.geometry * 1.01)
```

- **Failures raise.** A failed calculation raises `qcdata.ProgramError`; its `output` is the failed `ProgramOutput`, with partial results and logs. A list runs everything first, then raises one `qcdata.ProgramErrors` group whose `results` holds every output in order. `raise_exc=False` returns failures in place.
- **A store, if you want one.** `compute(inputs, store=store, tags=[...])` looks each input up first and stores what it ran, with the identities of the programs that made it; a run is reused only when those are the programs that would run now.
- **Threads per calculation.** Each calculation gets the threads it asks for: its `threads` keyword, else its program's plan (1 unless the program states more, or all of the runner's for a program that scales), at most the runner's.
- **A share of the machine.** `qccompute.compute` and `qccompute.session` belong to the default runner: every core and GPU this process may use. A `Runner` of your own takes a share and closes its worker processes when done:

```python
with qccompute.Runner(threads=16, gpus=["0"], isolation="process") as runner:
    for out in runner.as_completed(inputs, timeout=3600):
        print(out.success, out.results.energy)
```

## Programs

A program is any object with `name`, `version()`, `capabilities()`, `settings_schema()`, `record_schema()`, `plan(inp)` and `compute(inp, ctx=None)`, registered under the `qccompute.programs` entry points (or with `qccompute.register_program` in a script). The protocol is structural, so a program without subprograms imports only qcdata. `qccompute.program.FunctionProgram` turns Python functions of the positions into a program, and `qccompute.testing.check_program` checks one against the contract.

```python
from qccompute.program import FunctionProgram

def harmonic(x):  # positions (bohr) -> energy (Eh), gradient (Eh/bohr)
    return float((x**2).sum()), 2 * x

qccompute.register_program(FunctionProgram("harmonic", harmonic))
```

## The QC Suite

- [qcref](https://github.com/atomsforhumanity/qcref) - Reference data: physical constants, conversion factors, a periodic table, solvents, each value with its source.
- [qcdata](https://github.com/atomsforhumanity/qcdata) - Data structures for quantum chemistry inputs and results. [Documentation](https://qcdata.docs.afh.org)
- [qcinf](https://github.com/atomsforhumanity/qcinf) - Cheminformatics algorithms and structure utilities for qcdata structures.
- [qccodec](https://github.com/atomsforhumanity/qccodec) - External programs as programs qccompute runs: their input files, output parsers, and execution. [Documentation](https://qccodec.docs.afh.org)
- [qccompute](https://github.com/atomsforhumanity/qccompute) - Runs programs on qcdata inputs. [Documentation](https://qccompute.docs.afh.org)

## Support

Questions and bug reports: [GitHub issues](https://github.com/atomsforhumanity/qccompute/issues).
