MeanFi

MeanFi solves self-consistent tight-binding models with density-density interactions, at zero or finite temperature, including superconducting BdG models. Define the Hamiltonian and interaction, supply an initial mean field, and solve:

import numpy as np
import meanfi

# A spinful chain: nearest-neighbor hopping and on-site repulsion.
hopping = -np.eye(2)
h_0 = {(0,): np.zeros((2, 2)), (1,): hopping, (-1,): hopping.T.conj()}
h_int = {(0,): np.array([[0., 1.], [1., 0.]])}
model = meanfi.Model(h_0, h_int, filling=1, kT=0.2)

guess = model.random_meanfield(rng=0, scale=0.1)
result = meanfi.solver(model, guess)
assert result.converged
h_mf = model.hamiltonian_from_meanfield(result.mean_field)
print(result.internal_energy)

Dictionary keys are lattice displacements; each value is an orbital matrix. EnergyDIIS() is the default solver and mixes densities using internal energy. SCF iterations and EDIIS use internal energy only. Entropy and free energy are optional: pass compute_free_energy=True to evaluate them after SCF terminates.

Final results report energies and entropy per cell per physical orbital, with entropy in units of Boltzmann's constant: free_energy = internal_energy - kT * entropy. Filling counts electrons per cell. A BdG Hamiltonian of size 2N still has N physical orbitals.

See the tutorials and API walkthrough for densities, observables, reference subtraction, restarts, BdG, sparse calculations, and Kwant conversion. The theory and algorithms explain the physics and numerical methods.

Integration

Normal zero-temperature calculations default to FermiSimplex(), backed by FermiSimplex. Dense finite-temperature calculations default to UniformGrid() with direct diagonalization and coarse/fine grid refinement.

# Choose a total point count or request accuracy-controlled integration.
integration = meanfi.UniformGrid(nk=4096)
integration = meanfi.UniformGrid(initial_nk=256)
result = meanfi.solver(model, guess, integration=integration, tol=1e-5)

An explicit nk fixes the mesh; integration targets then do not apply. For example, nk=4096 gives 64² periodic points in 2D. Prescribed meshes do not estimate integration error. initial_nk chooses a starting mesh for refinement, using the same total-point units; it cannot be combined with nk. The solver's tol still controls filling and SCF convergence. Zero-temperature UniformGrid supports fixed-mu evaluation only, with explicit nk for periodic systems. Its fixed-filling searches (including SCF) raise NotImplementedError; use FermiSimplex for normal zero-temperature models. FermiSimplex starts at an exact dyadic initial_grid_level (default 2); level L has 2**L+1 vertices per axis and is reported in the result statistics. For individual targets, pass an ErrorTolerances record as tol; method objects contain mesh, backend and resource settings only.

Sparse finite-temperature calculations use UniformGrid(nk=..., matrix_function=RationalFOE()). AAA approximates the Fermi function using selected inverse entries from MUMPS. The default tolerance policy uses fixed fractions of tol, independent of orbital count. result.errors.matrix_function_error reports the achieved approximation estimate (or None for methods without this estimate). See the accuracy and integration guide for supported combinations, mesh rounding, and changes from previous APIs.

Installation

This development revision supports Python 3.11–3.13. Use Pixi to install the pinned dependencies and native compiler:

git clone https://gitlab.kwant-project.org/qt/meanfi.git
cd meanfi
pixi install --locked
pixi run python -c "import meanfi; print(meanfi.__version__)"

FermiSimplex builds from a pinned Git revision and includes its own AdaptiveSimplex mesh engine. Installing this checkout with pip install . also works when Git and a suitable C++ compiler are available. See the development guide for native requirements and the remaining PyPI release prerequisite.

Optional extras are pip install ".[sparse]" for MUMPS and pip install ".[kwant]" for conversion helpers. The test-sparse Pixi environment supplies both packages and their native libraries. The default dense and FermiSimplex paths do not require MUMPS.

pixi run -e test-py312 tests
pixi run benchmark
pixi run -e docs docs-build

The design document describes the code's structure and contracts; AGENTS.md records the coding guidelines.

Citing MeanFi

@misc{meanfi,
  author = {Vilkelis, Kostas and Zijderveld, R. Johanna and Akhmerov, Anton R. and Manesco, Antonio L.R.},
  doi = {10.5281/zenodo.11149850},
  month = {5},
  title = {MeanFi},
  year = {2024}
}