cclib: Computational Chemistry Parsers

1.8.1 · active · verified Thu Apr 16

cclib is an open-source Python library designed for parsing and interpreting output files from various computational chemistry packages. It provides a consistent interface to extract data like geometries, energies, orbitals, and vibrational modes, facilitating the implementation of package-independent algorithms. The current stable version is 1.8.1, with a major version 2.0 actively in alpha development, which is expected to introduce significant architectural and API changes.

Common errors

```
AttributeError: 'FileInput' object has no attribute 'next'
```
cause In older versions (e.g., cclib 1.5 with Python 3.6), `cclib.io.ccread` did not correctly handle a list of file paths as input, despite its docstring suggesting it should. This led to errors when attempting to parse multiple files simultaneously.

fix Instead of passing a list of files to `ccread`, iterate over the list and call `ccread` for each file individually: `for log_file in log_files: data = cclib.io.ccread(log_file)`.
```
AttributeError: 'ccData' object has no attribute 'some_missing_attribute'
```
cause This error occurs when you try to access a data attribute (e.g., `data.vibdisps`) that was not present in the logfile, or the specific parser for your program/version does not support extracting that attribute.

fix Check the logfile to confirm the data is actually present. Consult the cclib documentation's 'Parsed data' section to see which attributes are supported for your specific computational chemistry program and its version. Use `hasattr(data, 'attribute_name')` or a `try-except AttributeError` block for robust code.
```
ImportError: cannot import name 'Gaussian' from 'cclib.parser'
```
cause This usually happens when trying to import a specific parser class (like `Gaussian`) incorrectly, or if `cclib` itself isn't properly installed or accessible in the Python environment.

fix Ensure `cclib` is installed (`pip install cclib`). If attempting a direct parser import, verify the exact module path. The recommended way to parse is using `from cclib.io import ccread` which handles parser selection automatically.

Warnings

breaking cclib dropped support for Python 2 starting with version 1.7. Users on Python 2.x must upgrade to Python 3.x.
Fix: Upgrade your Python environment to 3.7 or newer. For projects dependent on cclib, ensure your `requirements.txt` specifies `python_version >= '3.7'`.
breaking SciPy became a hard dependency for cclib starting with version 1.7. If you previously installed cclib without SciPy and relied on limited functionality, it will now fail without SciPy installed.
Fix: Ensure SciPy is installed in your environment: `pip install scipy`.
breaking Version 2.0 (currently in alpha) introduces significant breaking changes to the API, including a formalized intermediate data representation, a new parser organization, and attributes as extensible objects. Existing code written for 1.x will require adjustments.
Fix: Refer to the official cclib 2.0 documentation and changelog (once released) for migration guides. Expect changes in how data is accessed and structured.
gotcha All indices in cclib, including for attributes like `homos` (highest occupied molecular orbital), are 0-based following Python conventions. This means `data.homos[0]` refers to the index of the HOMO, not the count of occupied orbitals.
Fix: Always remember that array indices in cclib are 0-based. Adjust calculations and data access accordingly.

Install

pip install cclib Install stable version

Imports

ccread
```
from cclib.io import ccread
```
The primary function for parsing logfiles, automatically detecting the file format.
ccopen
```
from cclib.io import ccopen
```
Used to open a logfile and return a parser object, which then calls .parse(). Often used alongside `ccread`.
Gaussian
wrong:
```
import cclib.parser.Gaussian
```
correct:
```
from cclib.parser import Gaussian
```
While direct import is possible for specific parsers, `ccread` or `ccopen` are generally preferred for automatic format detection. If directly importing, ensure the correct path.

Quickstart

This quickstart demonstrates how to use `cclib.io.ccread` to parse a computational chemistry output file. It creates a simple dummy logfile, parses it, and then accesses common attributes like the number of atoms, SCF energy, and atom coordinates from the returned `ccData` object.

import cclib
import os

# Create a dummy logfile for demonstration
dummy_logfile_content = """
 Program: Gaussian
 # hf/sto-3g Opt

 Energy: -76.0357878
 Nuclear Repulsion Energy: 22.1898
 Number of atoms: 3
 Atom 1: H   0.000000   0.000000   0.000000
 Atom 2: O   0.000000   0.000000   0.969000
 Atom 3: H   0.880000   0.000000   1.239000
"""

with open("water.log", "w") as f:
    f.write(dummy_logfile_content)

try:
    # Parse the logfile using ccread
    data = cclib.io.ccread("water.log")

    # Access parsed data attributes
    print(f"Number of atoms: {data.natom}")
    print(f"Electronic energy (eV): {data.scfenergies[-1]:.2f}")
    print(f"Atom coordinates (Angstrom):\n{data.atomcoords[-1]}")

except Exception as e:
    print(f"Error parsing file: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists("water.log"):
        os.remove("water.log")

view raw JSON →