Skip to main content
v2026.11,986 entries · CC-BY 4.0

CatHub: Python Package and CLI for Catalysis-Hub.org

CatHub is the Python package and command-line tool for Catalysis-Hub.org: what it queries, its commands, how uploads work and what to check before reuse.

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.

  1. Choose a layout command. cathub organize is for large systematic sets of calculations without reaction barriers; transition-state data are not handled by it. cathub make-folders creates a folder structure from an editable template for the other cases.
  2. Prepare readable structure files. Files must be readable by ASE and contain the total potential energy. The tutorial prefers .traj files, and VASP output should be named NAME.OUTCAR. File names must contain no spaces.
  3. 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.
  4. Build a local database. cathub folder2db FOLDER writes a DBNAME.db file and prints a summary of the reaction energies it computed, which is the moment to check them against your expectations.
  5. Submit. cathub db2server uploads directly for SLAC affiliates; other contributors email the .db file to the contact named in the documentation.
  6. 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.

CatHub commands and Python interfaces by workflow role
Interface itemKindRole in the workflowDocumented in
cathub aseCLI subcommandQuery the database from the command line, for example 'CuAg pub_id=PengRole2020'PyPI page; Winther et al. 2019
cathub organizeCLI subcommandArrange large systematic sets of calculations without barriers or transition states before building a databaseUpload tutorial; README
cathub make-foldersCLI subcommandCreate an editable template, then the folder structure for a datasetUpload tutorial; README
cathub folder2dbCLI subcommandConvert a folder of calculations into a local .db file and print a reaction-energy summaryUpload tutorial; README
cathub show-reactionsCLI subcommandInspect the reactions in a local .db fileREADME
cathub db2serverCLI subcommandUpload a .db file to the Catalysis-Hub server (SLAC affiliates); others email the fileUpload tutorial; README
CathubSQLPython classConnect to the online database or open a local .db filePyPI page
CathubQueryPython classget_reactions returns a DataFrame; get_dataframe filters by publication, composition and facetREADME
api.catalysis-hub.org/graphqlGraphQL endpointProgrammatic queries returning JSON; the README says an API key is requiredREADME; Winther et al. 2019

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · full access

Ask about CatHub: Python Package and CLI for Catalysis-Hub.org

Full access: large monthly usage, up to 10 source passages behind each answer, and MCP and API access for Claude Code, Codex and other CLIs. Cancel any time.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →