cclib

library1.8.1pypypi✓ verified 35d ago

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.

data

github ↗package ↗homepage ↗docs ↗changelog ↗

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

The primary function for parsing logfiles, automatically detecting the file format.

from cclib.io import ccread

Used to open a logfile and return a parser object, which then calls .parse(). Often used alongside `ccread`.

from cclib.io import ccopen

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.

from cclib.parser import Gaussian

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")

Debug

Known footguns

breakingcclib dropped support for Python 2 starting with version 1.7. Users on Python 2.x must upgrade to Python 3.x.

breakingSciPy 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.

breakingVersion 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.

gotchaAll 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.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

0 hits · last 30 days

No traffic data recorded yet.

Resources

githubhttps://github.com/cclib/cclib ↗

packagehttps://pypi.org/project/cclib/ ↗

homepagehttps://cclib.github.io ↗

docshttp://cclib.github.io/ ↗

changeloghttps://github.com/cclib/cclib/blob/master/doc/sphinx/changelog.rst ↗