tailwater

Getting started

  • Installation
    • Core install
    • Optional extras
    • Tight-binding-library converters (separate packages)
    • Supported Python
    • Verifying the install
    • Getting API access
  • Quick start
    • 1. Get the artifacts from the API
    • 2. (Optional) Fine-tune the heads to fit a near-Fermi window
    • 3. Analyze the model
  • Examples

Guides

  • Fermi alignment for semiconductors and insulators
    • Why this matters
    • Quick start
    • Inspecting the band edges first
    • How VBM is identified
    • Metals
    • Overriding the auto-detection
    • Worked patterns
    • Implementation note
    • API reference
  • Fermi arcs and 2D surface spectral maps
    • When to use FermiArcMap vs SurfaceGreensFunction
    • Quick start
    • What you get back
    • Choosing the energy
    • Choosing the surface
    • Performance tips
    • End-to-end example: Bi2Se3 Dirac cone at the VBM
    • API reference
  • Exporting models: sparse .npz, HDF5, _hr.dat, pybinding, PythTB, Kwant
    • The sparse .npz format (SparseHR)
    • Convert the .npz to any format (one call, auto-detecting the input)
    • Staying sparse: pybinding, Kwant, and built-in solvers
    • Why maintaining sparsity matters for large systems
    • Working with the dense tbmodels.Model
    • Writing an _hr.dat file
    • Converting to a pybinding Lattice
      • Computing a full band structure
      • Convention notes
      • Overriding the lattice vectors
      • Filtering tiny hops
    • Converting to a PythTB tb_model
      • Computing a band structure with PythTB’s built-in helper
      • Slabs and wires
    • Converting to a Kwant Builder
      • What .to_kwant() returns
      • Computing a band structure with Kwant
    • Using the model with WannierBerri
    • Round-trip: HDF5 → pybinding → HDF5
    • Building a model from raw head predictions (advanced)
    • API reference
      • Sparse Hamiltonian + format-detecting converters
      • Dense (tbmodels) converters
  • Speeding up surface-state calculations
    • TL;DR
    • How much faster?
    • n_jobs — k-point parallelism
    • chunk_size — energy-axis batching
    • Choosing what to set
    • Implementation note

API reference

  • HTTP client + HDF5 loader
    • tw_api_call()
    • remaining_credits()
    • k_cart_from_frac()
    • tb_model
      • tb_model.load()
  • Subspace fine-tuning
    • Loss modes
    • Outputs (written to save_path)
    • subspace_projection()
  • Model assembly and hr-file I/O
    • write_hr_output()
    • build_hr_model()
    • build_hr_model_fast()
  • Post-processing: bands, DOS, surface states, Fermi arcs
    • Calculator classes
      • BulkDOS
      • SurfaceSpectralDensity
      • SurfaceGreensFunction
      • FermiArcMap
      • BandStructure
    • Convenience function
      • bulk_band_structure()
    • Result dataclasses
      • BulkDOSResult
      • SurfaceSpectralDensityResult
      • SurfaceGreensFunctionResult
      • FermiArcMapResult
      • BandStructureResult
    • k-path helper
      • generate_k_path()
    • Fermi / band-edge alignment
      • compute_band_edges()
      • align_to_vbm()
  • Surface charge density
    • Quick example
    • API
      • surface_charge_density()
      • load_hr()
      • supercell_self_check()
  • Constants
tailwater
  • Overview: module code

All modules for which code is available

  • tailwater.client
  • tailwater.convert
  • tailwater.finetune_heads
  • tailwater.hr_export
  • tailwater.sparse
  • tailwater.surface_charge
  • tailwater.wannier_wizard

© Copyright 2026, Tailwater.