Beautiful and user friendly data structures for quantum chemistry.
Project description
Quantum Chemistry I/O
Beautiful and user friendly data structures for quantum chemistry.
Inspired by QCElemental. Built for consistency and rapid development.
qcio
works in harmony with a suite of other quantum chemistry tools for fast, structured, and interoperable quantum chemistry.
The QC Suite of Programs
- qcio - Beautiful and user friendly data structures for quantum chemistry.
- qcparse - A library for efficient parsing of quantum chemistry data into structured
qcio
objects. - qcop - A package for operating quantum chemistry programs using
qcio
standardized data structures. Compatible withTeraChem
,psi4
,QChem
,NWChem
,ORCA
,Molpro
,geomeTRIC
and many more. - BigChem - A distributed application for running quantum chemistry calculations at scale across clusters of computers or the cloud. Bring multi-node scaling to your favorite quantum chemistry program.
ChemCloud
- A web application and associated Python client for exposing a BigChem cluster securely over the internet.
Installation
pip install qcio
Quickstart
qcio
is built around a simple mental model: Input
objects are used to define inputs for a quantum chemistry program, and Output
objects are used to capture the outputs from a quantum chemistry program.
All qcio
objects can be serialized and saved to disk by calling .save("filename.json")
and loaded from disk by calling .open("filename.json")
. qcio
supports json
, yaml
, and toml
file formats. Binary data will be automatically base64 encoded and decoded when saving and loading.
Input Objects
ProgramInput - Core input object for a single QC program.
from qcio import Structure, ProgramInput
# xyz files or saved Structure objects can be opened from disk
caffeine = Structure.open("caffeine.xyz")
# Define the program input
prog_input = ProgramInput(
structure=caffeine,
calctype="energy",
keywords={"purify": "no", "restricted": False},
model={"method": "hf", "basis": "sto-3g"},
extras={"comment": "This is a comment"}, # Anything extra not in the schema
)
# Binary or other files used as input can be added
prog_input.open_file("wfn.dat")
prog_input.keywords["initial_guess"] = "wfn.dat"
# Save the input to disk in json, yaml, or toml format
prog_input.save("input.json")
# Open the input from disk
prog_input = ProgramInput.open("input.json")
Structure
objects can be opened from and saved as xyz files or saved to disk as .json
, .yaml
, or .toml
formats by changing the extension of the file. For .xyz
files precision can be controlled by passing the precision
argument to the save
method.
caffeine = Structure.open("caffeine.xyz")
caffeine.save("caffeine2.json", precision=6)
caffeine.save("caffeine.toml")
DualProgramInput - Input object for a workflow that uses multiple QC programs.
DualProgramInput
objects can be used to power workflows that require multiple QC programs. For example, a geometry optimization workflow might use geomeTRIC
to power the optimization and use terachem
to compute the energies and gradients.
from qcio import Structure, DualProgramInput
# xyz files or saved Structure objects can be opened from disk
caffeine = Structure.open("caffeine.xyz")
# Define the program input
prog_input = DualProgramInput(
structure=caffeine,
calctype="optimization",
keywords={"maxiter": 250},
subprogram="terachem",
subprogram_args = {
"model": {"method": "hf", "basis": "sto-3g"},
"keywords": {"purify": "no", "restricted": False},
},
extras={"comment": "This is a comment"}, # Anything extra not in the schema
)
FileInput - Input object for a QC programs using native file formats.
qcio
also supports the native file formats of each QC program with a FileInput
object. Assume you have a directory like this with your input files for psi4
:
psi4/
input.dat
geometry.xyz
wfn.dat
You can collect these native files and any associated command line arguments needed to specify a calculation into a FileInput
object like this:
from qcio import FileInput
psi4_input = FileInput.from_directory("psi4")
# All input files will be loaded into the `files` attribute
psi4_input.files
# {'input.dat': '...', 'geometry.xyz': '...', 'wfn.dat': '...'}
# Add psi4 command line args to the input
psi4_input.cmdline_args.extend(["-n", "4"])
# Files can be dumped to a directory for a calculation
psi4_input.save_files("psi4")
Modifying Input Objects
Objects are immutable by default so if you want to modify an object cast it to a dictionary, make the desired modification, and then instantiate a new object. This prevents accidentally modifying objects that may already be referenced in other calculations--perhaps as .input_data
on an Output
object.
# Cast to a dictionary and modify
new_input_dict = prog_input.model_dumps()
new_input_dict["model"]["method"] = "b3lyp"
# Instantiate a new object
new_prog_input = ProgramInput(**new_input_dict)
Output Objects
SinglePointOutput and OptimizationOutput
Currently supported Output
objects include SinglePointOutput
for energy, gradient, and hessian calculations; and OptimizationOutput
for optimization and transition state calculations. All Output
objects have the same basic API:
output.input_data # Input data used by the QC program
output.success # Whether the calculation succeeded
output.results # All structured results from the calculation
output.stdout # Stdout log from the calculation
output.pstdout # Shortcut to print out the stdout in human readable format
output.files # Any files returned by the calculation
output.provenance # Provenance information about the calculation
output.extras # Any extra information not in the schema
The only difference between a SinglePointOutput
and an OptimizationOutput
is the results
attribute. SinglePointOutput
objects have a SinglePointResults
object, and OptimizationOutput
objects have an OptimizationResults
object. Available attributes for each result type can be found by calling dir()
on the object.
dir(output.results)
Results can be saved to disk in json, yaml, or toml format by calling .save("filename.{json/yaml/toml}")
and loaded from disk by calling .open("filename.{json/yaml/toml}")
.
ProgramFailure
Failed calculations are represented by a ProgramFailure
object. This object has the same API as Output
objects but also has a .traceback
attribute that captures the stack trace.
output.traceback # Stack trace from the failed calculation
output.ptraceback # Shortcut to print out the traceback in human readable format
Support
If you have any issues with qcio
or would like to request a feature, please open an issue.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.