The High-Throughput Toolkit (httk)

The High-Throughput Toolkit (httk) is a toolkit for preparing and running calculations, analyzing the results, and storing results in global and/or personalized databases. httk is presently targeted at atomistic calculations in materials science and electronic structure, but aims to be extended into a library useful also outside those areas.

httk was created in 2014. This site describes httk₂, the current main version.

Looking for httk v1? The legacy version has its own website at httk.org/v1, documentation at olddocs.httk.org, and source code at github.com/httk/httk. Note that httk v1 and httk₂ cannot be installed in the same Python environment.

httk₂ is a rewrite of httk as a modular toolkit: instead of a single monolithic package, its functionality is split across independent module repositories that share a common, PEP 420 native httk.* namespace (httk.core, httk.atomistic, httk.store, and more). This lets you install and depend on only the parts you need, while httk.core provides the shared plugin, loading, and view/backend machinery the other modules build on.

Installation

httk₂ requires Python 3.12 or newer. The httk2 metapackage installs the complete standard set of httk₂ modules, each with its recommended default features, in one step:

pip install httk2

We recommend installing into a virtual environment. Pick your preferred tool:

python3 --version  # check that you have Python 3.12 or newer
python3 -m venv .venv
source .venv/bin/activate
pip install httk2

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install httk2

conda create -n httk2 python=3.12 pip
conda activate httk2
python -m pip install httk2

Individual modules can also be installed on their own, e.g., pip install httk-atomistic; see the httk2 README for the list of modules.

Quickstart

A few short general httk code examples follow in sections below.
Quickstarts covering specific functionalities are available for working with:

A few simple usage examples

Load a structure file

With httk-atomistic installed, httk.core.load loads CIF, POSCAR, and CONTCAR files (including compressed variants such as CONTCAR.bz2) directly into httk₂ structure objects:

from httk.core import load

structure = load("example.cif")

print("Formula:", structure.formula)
print("Volume:", float(structure.cell.volume))

A CIF loads as an ASUStructure (the file's native symmetry representation); POSCAR/CONTCAR load as a UnitcellStructure. Converting between representations is done by constructing a view, e.g. UnitcellStructureView(structure) for the full expanded cell.

Create structures in code

In httk₂, a UnitcellStructure is created from an explicit cell, a list of sites in reduced coordinates, and a per-site list of species. Coordinates given as strings, such as "1/2" or "5.64", are kept exact — httk₂ does all structure algebra in exact arithmetic. Here is a conventional cubic rock-salt (NaCl) cell:

from httk.atomistic import UnitcellStructure

structure = UnitcellStructure(
    cell=[["5.64", 0, 0], [0, "5.64", 0], [0, 0, "5.64"]],
    sites=[
        [0, 0, 0], ["1/2", "1/2", 0], ["1/2", 0, "1/2"], [0, "1/2", "1/2"],
        ["1/2", "1/2", "1/2"], [0, 0, "1/2"], [0, "1/2", 0], ["1/2", 0, 0],
    ],
    species_at_sites=["Na", "Na", "Na", "Na", "Cl", "Cl", "Cl", "Cl"],
)

print("Formula:", structure.formula)
print("Species:", [s.name for s in structure.species])
print("Number of sites:", len(structure.sites))
print("Volume:", structure.cell.volume, "=", float(structure.cell.volume))

Running this generates the output:

Formula: ClNa
Species: ['Na', 'Cl']
Number of sites: 8
Volume: (2803221/15625) = 179.406144

See the structures quickstart for saving, supercells, and interoperability with ASE and pymatgen.

Databases

httk-store provides relational storage and querying over SQLite and DuckDB. Structures — and your own frozen dataclasses — are stored exactly and can be queried back:

from httk.atomistic import StructureEntry, UnitcellStructureRecord
from httk.store import Backend, EntryIdScheme, SqlStore

store = SqlStore(
    Backend.sqlite("example.sqlite"),
    entry_records={StructureEntry: UnitcellStructureRecord},
    entry_ids=EntryIdScheme("example", "structures"),
)
sid = store.save(structure)

See the databases quickstart and the database documentation.

Query materials databases over OPTIMADE

The same query interface reaches remote databases that speak the OPTIMADE API:

from httk.store.optimade import OptimadeStore

with OptimadeStore("https://alexandria.icams.rub.de/pbe") as store:
    search = store.searcher()
    s = search.variable(store.entry_type("structures"))
    search.add(s.elements.has("Na") & s.elements.has("Cl") & (s.nelements == 2))
    print("Matching structures:", search.count())

See the OPTIMADE client quickstart.

Reporting bugs

Please file bugs at the issue tracker of the relevant module repository within the httk GitHub organization (please search first to check if it is already reported):

https://github.com/httk

Citing httk in scientific works

This is presently the preferred citation:

R. Armiento et al., The High-Throughput Toolkit (httk), http://httk.org/; Armiento R. (2020) Database-Driven High-Throughput Calculations and Machine Learning Models for Materials Design. In: Schütt K., Chmiela S., von Lilienfeld O., Tkatchenko A., Tsuda K., Müller KR. (eds) Machine Learning Meets Quantum Physics. Lecture Notes in Physics, vol 968. Springer, Cham. https://doi.org/10.1007/978-3-030-40245-7_17

Since httk may call upon many other pieces of software quite transparently, it may not be initially obvious what other software should be cited. httk₂ therefore keeps track of the functionality your program actually used and can print the corresponding citation list on request. Ask for it at the end of your program, or when it produces a report:

import httk.core

print(httk.core.credits)

The output lists what the running program ought to cite and why, including the httk reference above and the references registered by the modules and external programs that were used. See the credits documentation for details, including how to register citations for your own modules.

Contribute

Contributions are very welcome. We are happy to accept issues and pull requests to the respective httk-<module> repositories in the httk GitHub organization.

The httk2 metapackage repository doubles as a development helper environment: clone it and use its Makefile targets to check out all module repositories and install them into a virtual environment in one step:

git clone https://github.com/httk/httk2.git

See Developing httk₂ in the httk2 README for the details.