Overview

The Quantum Thermochemical API provides programmatic access to a collection of quantum chemistry computational resources based on the W4-11 dataset. It enables researchers to:

• Retrieve basis sets used for high-accuracy quantum thermochemical computations.
• Submit and query research results related to molecular ground state energy calculations.
• Explore community-contributed results, including accuracy metrics and metadata.

The API is designed to facilitate reproducible computational chemistry research and allow comparison of different algorithmic approaches to molecular energy computation. Key features include:

• Basis Retrieval: Access curated computational basis sets for W4-11 benchmark calculations.
• User Submissions: Submit algorithmic results and retrieve public research submissions.
• Flexible Queries: Search by DOI, page, or submission date and aggregate results.

Endpoints

1. Fetching Basis SetsGET /entries/:basis_name

• Description: Retrieves the specified basis set as a downloadable file
• Parameters: The name of the requested dataset to be downloaded. A comprehensive list can be found at BasisSetExchange.org , but to find if a specific basis is offered, please refer to our supported bases.
• Response: Returns a basis file containing corresponding information formatted as following:
  • Each line of the file is formatted as an individual json object
  • The first line contains the basis name formatted as {$basis: "basis_name"}
  • The rest of the file consists of json objects representing the information of each of the 152 supported species:
    {name: String, ecore: int, nelecas: int, ncas: int, h1e: tensor, h2e: tensor, cct2: tensor}
    • name: String - identifier for the molecule
    • ecore: int - number of electrons in the core
    • nelecas: int - number of active electrons
    • ncas: int - number of configuration state functions
    • h1e: Tensor - one-electron integrals (kinetic + nuclear attraction)
    • h2e: Tensor - two-electron integrals (Coulomb repulsion)
    • cct2: Tensor - two-particle contraction tensor
  • All tensor information is flat mapped and encoded in base-64, returned as a struct containing and integer list representing the shape of the tensor and a b64 string of its information: {shape: int[], data: String}

2. User Submissions

POST /submission

• Description: Submit research results for review
• Request Body: Contains the DOI, email and ground state energy data computed: {doi: String, email: String, data: {...species: float}}
  • DOI - Valid digital object identifier available for cross-reference on Crossref REST API
  • Email - A valid email to be contacted for submission confirmation and subsequent notifications
  • Data - Map of string-float key value pairs, containing every species in the provided data set and its computed ground state energy
• Response: JSON message on completion of submission verification and confirmation email

GET /submission/fetch?...

• Description: Multipurpose endpoint for querying public submission data
• Query Parameters: There are 2 primary types of requests:
  • SINGLE - Fetches individual submission data based on their DOI identifiers.
    • Request: GET /submission/fetch?type=single&doi=x,y,z,...
    • Description: Returns a json list of entries with doi's matching x, y, or z, containing the doi and submission info, containing the data on submission and its accuracy. The data is formatted as a map of species to float tuple, such that the first index contains the value and the second is the error from precomputed ground state energies
    • Response: [{doi: String, info: {data: { ...species: [value, absolute-error] }, accuracy: mean-absolute-error}}, ...]
  • PAGE - Fetches submissions in bulk, responding with doi, data and accuracy information. The max number of submissions per page is 200, and both pages and limit must be positive integer values.
    • Request: GET /submission/fetch?type=page&page=x&limit=y
    • Description: Returns a struct containing the page number x, the limit of submissions per page y, the total number of submissions, the total number of pages for y entries per page, and the result for the x'th page of y entries as a list of submissions.
    • Response: {page: int, limit: int, total: int, totalPages: int, results: [ same format as single query ]}
  • SORT & FILTER - Provided query functionality for searching and filtering for specific submissions by page.
    • Fields: The following fields are supported for both sorting and filtering:
      • DOI
      • Date
      • Accuracy
    • Sorting: Queries can be sorted with comma separated fields, in the order provided. The order is specified with either :asc or :desc suffix on their respective field.
      Example: ?type=page&sort=date:desc,accuracy:desc yields pages sorted first by submission time, then by accuracy.
    • Filtering: Queries can be filtered
• Defaults:
  • An unspecified query to "/submission/fetch" is equivalent to "type=page&page=1&limit=15"
  • A partially specified query to "/submission/fetch?type=single" will always throw a 404 with no items found
  • A partially specified query to "/submission/fetch?type=page" will default to page 1 of 15 entries

Examples

Overview

Usage

from w4benchmark import W4Decorators, Molecule, W4

@W4Decorators.process(basis="sto6g", debug=logging.DEBUG)
def compute_energy(name: str, mol: Molecule):
    # Replace with real computation

@W4Decorators.analyze(basis="sto6g")
def analyze_results(name: str, mol: Molecule):
    # Replace with real analytics
                            

Advanced

from w4benchmark import W4

if __name__ == '__main__':
    W4.parameters.basis = "sto6g"  # Set runtime parameters
    W4.init() # manual execution requires the .init() function to be called

    # Example usage
    for name, mol in W4:
        print(f"{name}: spin = {mol.spin}, charge = {mol.charge}")
                            

from w4benchmark import W4Decorators, Molecule
import math

centroid = {}

@W4Decorators.process()
def process_a(species: str, mol: Molecule):
    coords = [pos for _, pos in mol.geom]
    centroid[species] = tuple(sum(values) / len(coords) for values in zip(*coords))

def dist2(a, b):
    return sum((ai - bi) ** 2 for ai, bi in zip(a, b))

@W4Decorators.process()
def process_b(species: str, mol: Molecule):
    dist_sq = [dist2(pos, centroid[species]) for _, pos in mol.geom]
    rms_radius = math.sqrt(sum(dist_sq) / len(dist_sq))
    print(f'species: "{species}", centroid: {centroid[species]}, rms: {rms_radius}')