{"id":8888,"library":"cclib","title":"cclib: Computational Chemistry Parsers","description":"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.","status":"active","version":"1.8.1","language":"en","source_language":"en","source_url":"https://github.com/cclib/cclib","tags":["computational chemistry","parser","quantum chemistry","cheminformatics","logfile","data extraction"],"install":[{"cmd":"pip install cclib","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for execution","package":"python","version":">=3.7"},{"reason":"Hard dependency for various computational methods and data processing since cclib v1.7","package":"scipy","optional":false}],"imports":[{"note":"The primary function for parsing logfiles, automatically detecting the file format.","symbol":"ccread","correct":"from cclib.io import ccread"},{"note":"Used to open a logfile and return a parser object, which then calls .parse(). Often used alongside `ccread`.","symbol":"ccopen","correct":"from cclib.io import ccopen"},{"note":"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.","wrong":"import cclib.parser.Gaussian","symbol":"Gaussian","correct":"from cclib.parser import Gaussian"}],"quickstart":{"code":"import cclib\nimport os\n\n# Create a dummy logfile for demonstration\ndummy_logfile_content = \"\"\"\n Program: Gaussian\n # hf/sto-3g Opt\n\n Energy: -76.0357878\n Nuclear Repulsion Energy: 22.1898\n Number of atoms: 3\n Atom 1: H   0.000000   0.000000   0.000000\n Atom 2: O   0.000000   0.000000   0.969000\n Atom 3: H   0.880000   0.000000   1.239000\n\"\"\"\n\nwith open(\"water.log\", \"w\") as f:\n    f.write(dummy_logfile_content)\n\ntry:\n    # Parse the logfile using ccread\n    data = cclib.io.ccread(\"water.log\")\n\n    # Access parsed data attributes\n    print(f\"Number of atoms: {data.natom}\")\n    print(f\"Electronic energy (eV): {data.scfenergies[-1]:.2f}\")\n    print(f\"Atom coordinates (Angstrom):\\n{data.atomcoords[-1]}\")\n\nexcept Exception as e:\n    print(f\"Error parsing file: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(\"water.log\"):\n        os.remove(\"water.log\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or newer. For projects dependent on cclib, ensure your `requirements.txt` specifies `python_version >= '3.7'`.","message":"cclib dropped support for Python 2 starting with version 1.7. Users on Python 2.x must upgrade to Python 3.x.","severity":"breaking","affected_versions":"<1.7"},{"fix":"Ensure SciPy is installed in your environment: `pip install scipy`.","message":"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.","severity":"breaking","affected_versions":">=1.7"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0a1"},{"fix":"Always remember that array indices in cclib are 0-based. Adjust calculations and data access accordingly.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`.","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.","error":"AttributeError: 'FileInput' object has no attribute 'next'"},{"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.","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.","error":"AttributeError: 'ccData' object has no attribute 'some_missing_attribute'"},{"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.","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.","error":"ImportError: cannot import name 'Gaussian' from 'cclib.parser'"}]}