Written and maintained by CASRAI Editorial Board
Published
On this page
CatHub is the open-source Python package and command-line tool for the Surface Reactions database on Catalysis-Hub.org, a public collection of computed chemisorption and reaction energies for catalysis research. The name refers to the software, not to the database itself or to the web application: the package lets you query the database from Python or a terminal and prepare your own calculations for upload. Its source repository is maintained by the SUNCAT Center and licensed GPL-3.0.
What is CatHub?
Three things share the Catalysis-Hub name, and mixing them up is the most common source of confusion. The first is the database: the Surface Reactions collection described in a 2019 Scientific Data paper by Winther and colleagues (Sci Data 6:75, doi 10.1038/s41597-019-0081-y), which reports more than 100,000 chemisorption and reaction energies, covering roughly 700 distinct reactions, more than 100 adsorbed species and about 3,000 surfaces, drawn from more than 50 publications or datasets. The second is the web application at catalysis-hub.org, whose Surface Reactions app filters records by reactants, products, composition and facet. The third is CatHub, the Python package that the PyPI page describes as the “Python API for the Surface Reactions database on Catalysis-Hub.org”.
The paper lists four ways to reach the data: the web app, a GraphQL API that returns JSON, a Python CatHub module with a get_reactions function, and a command-line route through cathub ase. Structures can be downloaded as CIF, JSON, xyz, POSCAR, CASTEP cell and Quantum ESPRESSO input files. For background on the group that built it, see the guide to SUNCAT and its interface-science programme.
How the database behind CatHub is organised
According to the paper, the data sit in a PostgreSQL database hosted on Amazon Web Services, with three main tables: publications, reactions and structures. Structures follow the layout of the ASE database, and the schema uses PostgreSQL JSONB and ARRAY types for fields that hold nested or list-like values. The calculations in the database were produced with Quantum ESPRESSO, VASP and GPAW, using exchange-correlation functionals that include BEEF-vdW, RPBE and PBE+U. The authors present the resource as an effort to make computational catalysis data findable, accessible, interoperable and reusable; the FAIR Data Principles entry explains what those four words require of a dataset.
This structure explains how CatHub commands map onto the data. A “publication” record carries the bibliographic metadata, a “reaction” record carries an energy for a stated reaction on a stated surface, and a “structure” record carries the atomic geometry behind it. When you query by a publication identifier such as PengRole2020, you are selecting every reaction tied to one publication.
How CatHub is used in practice
Installing and discovering commands
The Catalysis-Hub documentation describes installing the package with pip from the SUNCAT-Center/CatHub repository on GitHub. Typing cathub lists the available subcommands, and cathub SUBCOMMAND --help shows the options for each one. The PyPI release page lists version 0.1.7, released 26 February 2021, under GPLv3 for Python 3.5 and later. The repository README and the documentation both refer readers to GitHub for the most current instructions.
Querying from the command line
The PyPI page gives a query example in the form cathub ase 'CuAg pub_id=PengRole2020', which selects records by a composition and a publication identifier using ASE-style search syntax. The paper names cathub ase as the command-line access route.
Querying from Python
Two interfaces are documented, and they differ by source. The PyPI description shows from cathub.cathubsql import CathubSQL, with CathubSQL() connecting to the online database and CathubSQL('file.db') opening a local database file. The GitHub README shows from cathub.query import CathubQuery: client.get_reactions(pub_id='PengRole2020') returns a DataFrame, and client.get_dataframe(pub_id=..., surface_composition='Cu', facet='100') filters by surface composition and facet. The README says the DataFrame uses snake_case columns such as chemical_composition, reaction_energy and pub_id, plus an equation column and list columns atoms_name and atoms_id.
The README also states that queries to api.catalysis-hub.org/graphql need an API key, passed as api_key or through the CATHUB_API_KEY environment variable. Because the PyPI text is dated 2021 and the README is the repository’s current documentation, a script written against one may not match the other, so pin the version you used.
CatHub commands and interfaces at a glance
The data table below sets out each documented CatHub command and Python entry point beside its role in the workflow, so you can see which ones read data and which ones prepare it for submission.
Choosing an access route
The paper lists four routes to the same records, and they suit different tasks. A short comparison of what each one is documented to provide follows.
| Route | What the sources say it does | Typical use |
|---|---|---|
| Surface Reactions web app | Filters records by reactants, products, composition and facet | Browsing and one-off lookups with no software installed |
| GraphQL API | Returns JSON; the README says queries need an API key | Programmatic access from any language |
| CatHub Python module | Query classes return reactions; the README documents DataFrame output | Analysis in Python, such as filtering by facet or composition |
cathub ase |
Command-line query using ASE-style search strings | Quick checks and shell scripts |
For a one-off check of a single publication’s numbers, the web app needs no installation. For a repeatable analysis, the Python module or the command line leaves a script that records exactly which publication identifiers, surfaces and facets were pulled, which is what a reviewer or a collaborator needs to rerun it. Downloaded structures arrive in several formats (CIF, JSON, xyz, POSCAR, CASTEP cell and Quantum ESPRESSO input), so the same entry can seed a new calculation in a different code from the one that produced it, subject to the comparability caveat below.
Submitting your own calculations through CatHub
The upload tutorial in the Catalysis-Hub documentation describes a pipeline that runs entirely through CatHub commands, and it works as a checklist for anyone preparing a dataset.
- Choose a layout command.
cathub organizeis for large systematic sets of calculations without reaction barriers; transition-state data are not handled by it.cathub make-folderscreates a folder structure from an editable template for the other cases. - Prepare readable structure files. Files must be readable by ASE and contain the total potential energy. The tutorial prefers
.trajfiles, and VASP output should be namedNAME.OUTCAR. File names must contain no spaces. - Complete the metadata. The publication record takes title, authors, journal, year, volume, number, pages, publisher, doi and email. The template adds fields for reactions, DFT_code, DFT_functionals, facets, crystal_structures and bulk_compositions.
- Build a local database.
cathub folder2db FOLDERwrites aDBNAME.dbfile and prints a summary of the reaction energies it computed, which is the moment to check them against your expectations. - Submit.
cathub db2serveruploads directly for SLAC affiliates; other contributors email the.dbfile to the contact named in the documentation. - Review and release. Uploaded data are held in moderation until approved. Afterwards you can review or delete them at catalysis-hub.org/upload and then release them.
The same steps record provenance: the code, functional, facet and publication stay attached to every energy. That is the property that the guide to data provenance treats as the core of documenting computational results.
Comparability caveats for CatHub data
The paper’s authors caution that energies calculated with different codes and different functionals are not always directly comparable. In practice that means a query that returns reaction energies for the same adsorbate on several surfaces may mix results from VASP, Quantum ESPRESSO and GPAW, or from BEEF-vdW and RPBE, unless you filter them. Retain the publication identifier, code and functional columns when you export data, and report them when you reuse the numbers. Treat basis-set and pseudopotential choices as part of the method too; the guide to the basis set in computational chemistry lists what to report. For the experimental and conceptual side of surface reactions, see how solid catalysts work.
Common misunderstandings about CatHub
CatHub is not the Catalysis-Hub website
The website and the database can be used with no installed software. CatHub is the Python package and command-line tool that automates queries and uploads.
CatHub is not the UK Catalysis Hub
The UK Catalysis Hub is a separate research consortium, described on its own site as made up of 46 universities, 15 companies, the STFC Harwell science facilities and 13 international partners, launched in April 2013 with a physical centre at the Research Complex at Harwell. It is a research network, not a database or software package.
CatHub does not hold the data itself
The package connects to the PostgreSQL-backed database or to a local .db file; the energies come from the contributed publications and datasets, not from the package.
The database paper does not state a content licence
The package is licensed GPL-3.0, but the 2019 paper does not state a licence for the database content, so check the terms on the Catalysis-Hub site before redistributing a downloaded dataset.
Sources
Data: CatHub commands and Python interfaces by workflow role
Compares the command-line subcommands, Python classes and API endpoint documented for the CatHub package, with the role each plays in querying or submitting Catalysis-Hub.org data. Compiled from the package README, PyPI page, upload tutorial and the 2019 Scientific Data paper.
| Interface item | Kind | Role in the workflow | Documented in |
|---|---|---|---|
| cathub ase | CLI subcommand | Query the database from the command line, for example 'CuAg pub_id=PengRole2020' | PyPI page; Winther et al. 2019 |
| cathub organize | CLI subcommand | Arrange large systematic sets of calculations without barriers or transition states before building a database | Upload tutorial; README |
| cathub make-folders | CLI subcommand | Create an editable template, then the folder structure for a dataset | Upload tutorial; README |
| cathub folder2db | CLI subcommand | Convert a folder of calculations into a local .db file and print a reaction-energy summary | Upload tutorial; README |
| cathub show-reactions | CLI subcommand | Inspect the reactions in a local .db file | README |
| cathub db2server | CLI subcommand | Upload a .db file to the Catalysis-Hub server (SLAC affiliates); others email the file | Upload tutorial; README |
| CathubSQL | Python class | Connect to the online database or open a local .db file | PyPI page |
| CathubQuery | Python class | get_reactions returns a DataFrame; get_dataframe filters by publication, composition and facet | README |
| api.catalysis-hub.org/graphql | GraphQL endpoint | Programmatic queries returning JSON; the README says an API key is required | README; Winther et al. 2019 |
Sources
- CatHub README (SUNCAT-Center) (accessed 2026-11-18)
- Cathub on PyPI (accessed 2026-11-17)
- Catalysis-Hub documentation: uploading data (accessed 2026-11-17)
- Winther et al., Catalysis-Hub.org, Scientific Data 6:75 (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







