Installation

Core install

pip install tailwater

The base install pulls in everything needed for the three workflow layers — HTTP client, subspace projection, and post-processing — including the heavy ML stack (torch, torch-geometric, e3nn, tbmodels) and the structural plumbing (pymatgen, scipy, matplotlib, tqdm, h5py).

Optional extras

A few small features depend on extra packages that aren’t pulled in by default. Install with the bracket syntax:

pip install "tailwater[scatter]"     # torch-scatter, only if missing
pip install "tailwater[seekpath]"    # auto k-path for bulk_band_structure
pip install "tailwater[dev]"         # pytest, ruff, build, twine

Extra	Adds	When you need it
scatter	torch-scatter>=2	Your torch / torch-geometric install doesn’t already ship torch_scatter and you hit an ImportError during fine-tuning.
seekpath	seekpath>=2	You want bulk_band_structure(..., auto=True, structure=...) to auto-derive the high-symmetry k-path.
dev	pytest, ruff, build, twine	You’re working on tailwater itself.

Tight-binding-library converters (separate packages)

The converters to other tight-binding libraries — to_pb / tb_model.load(...).to_pb() (and subspace_projection, which writes a projected HDF5 via pybinding), to_pythtb, and to_kwant — each need their target package. They are imported lazily, so the base install stays light; install the one(s) you need:

pip install pybinding-dev              # pybinding  (not a tailwater extra)
pip install pythtb                     # PythTB
conda install -c conda-forge kwant     # Kwant

as_tbmodels / to_hr_dat / to_hdf5 need only tbmodels, which is a core dependency (installed automatically). Calling a converter without its package installed raises a clear ImportError pointing back here.

Supported Python

Python 3.9 – 3.12. The package is pure Python; all heavy compute is delegated to the dependencies.

Verifying the install

import tailwater
print(tailwater.__version__)

from tailwater import tw_api_call, subspace_projection, BulkDOS
print(tw_api_call.__doc__.splitlines()[0])

Getting API access

By default, tw_api_call(...) talks to the hosted Tailwater API at https://api.tailwater.io — no configuration required beyond a username and password issued by the Tailwater team. Authentication is HTTP Basic; every successful inference call decrements your credit balance by one.

To request an account, email the Tailwater team. To check your balance without spending a credit:

from tailwater import remaining_credits
print(remaining_credits("user", "pw"))     # -> int