qccodec

A library for parsing Quantum Chemistry output files into structured data objects and converting structured input objects into program-native input files. Uses data structures from qcio.

qccodec works in harmony with a suite of other quantum chemistry tools for fast, structured, and interoperable quantum chemistry.

The QC Suite of Programs

• qcconst - Physical constants, conversion factors, and a periodic table with clear source information for every value.
• qcio - Beautiful and user friendly data structures for quantum chemistry.
• qccodec - A library for efficient parsing of quantum chemistry data into structured qcio objects and conversion of qcio input objects to program-native input files.
• qcop - A package for operating quantum chemistry programs using qcio standardized data structures. Compatible with TeraChem, 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.

✨ Basic Usage

• Installation:

  python -m pip install qccodec

• Parse QC program outputs into structured data files with a single line of code.

  from pathlib import Path
  from qcio import CalcType
  from qccodec import decode
  
  stdout = Path("tc.out").read_text()
  results = decode("terachem", CalcType.gradient, stdout=stdout)

• The results object will be a qcio object, either SinglePointResults, OptimizationResults, or ConformerSearchResults depending on the calctype. Run dir(results) inside a Python interpreter to see the various values you can access. A few prominent values are shown here as an example:

  from pathlib import Path
  from qcio import CalcType
  from qccodec import decode
  
  stdout = Path("tc.out").read_text()
  results = decode("terachem", CalcType.hessian, stdout=stdout)
  
  results.energy
  results.gradient # If a gradient calc
  results.hessian # If a hessian calc
  results.calcinfo_nmo # Number of molecular orbitals

• Parsed values can be written to disk like this:

  with open("results.json", "w") as f:
      f.write(result.model_dumps_json())

• And read from disk like this:

  from qcio import SinglePointResults
  
  results = SinglePointResults.open("results.json")

• You can also run qccodec from the command line like this:

  qccodec -h # Get help message for cli
  
  qccodec terachem hessian tests/data/terachem/water.frequencies.out > results.json # Parse TeraChem stdout to json

• More complex parsing can be accomplished by passing the directory containing the scratch files to decode and optionally the input data used to generate the calculation (usually done from qcop which uses structure data):

  from pathlib import Path
  from qcio import CalcType, ProgramInput
  from qccodec import decode
  
  stdout = Path("tc.out").read_text()
  directory = Path(".") / "scr.geom"
  input_data = ProgramInput.open("prog_inp.json")
  
  results = decode("terachem", CalcType.hessian, stdout=stdout, directory=directory, input_data=input_data)

💻 Contributing

Please see the contributing guide for details on how to contribute new parsers to this project :)

If there's data you'd like parsed from output files or want to support input files for a new program, please open an issue in this repo explaining the data items you'd like parsed and include an example output file containing the data, like this.