wrap up package references

docs/source/documentation/pymf.md

 # Package reference
 
+## Interactive problem definition
+
+To define the interactive problem, we use the following class:
+
+```{eval-rst}
+.. autoclass:: pymf.model.Model
+   :members: mfield
+```
+
+## Mean-field and density matrix
+
+```{eval-rst}
+.. automodule:: pymf.mf
+   :members: meanfield, construct_density_matrix, construct_density_matrix_kgrid, fermi_on_grid
+   :show-inheritance:
+```
+
+## Observables
+
+```{eval-rst}
+.. automodule:: pymf.observables
+   :members: expectation_value
+   :show-inheritance:
+```
+
+## Solvers
+
+```{eval-rst}
+.. automodule:: pymf.solvers
+   :members: solver, cost
+   :show-inheritance:
+```
+
+## Tight-binding dictionary
+
+### Manipulation
+
+```{eval-rst}
+.. automodule:: pymf.tb.tb
+   :members: add_tb, scale_tb
+   :show-inheritance:
+```
+
+### Brillouin zone transformations
+
+```{eval-rst}
+.. automodule:: pymf.tb.transforms
+   :members:
+   :show-inheritance:
+```
+
+### Parametrisation
+
+```{eval-rst}
+.. automodule:: pymf.params.rparams
+   :members:
+   :show-inheritance:
+```
+
+### Utility functions
+
+```{eval-rst}
+.. automodule:: pymf.tb.utils
+   :members:
+   :show-inheritance:
+```
+
+## `kwant` interface
+
 ```{eval-rst}
-.. automodule:: pymf
+.. automodule:: pymf.kwant_helper.utils
    :members:
    :show-inheritance:
 ```

pymf/kwant_helper/utils.py

@@ -5,14 +5,16 @@ from typing import Callable
 from pymf.tb.tb import tb_type
 
 import kwant
+import kwant.lattice
+import kwant.builder
 import numpy as np
 from scipy.sparse import coo_array
 
 
 def builder_to_tb(
-    builder: kwant.Builder, params: dict = {}, return_data: bool = False
+    builder: kwant.builder.Builder, params: dict = {}, return_data: bool = False
 ) -> tb_type:
-    """Construct a tight-binding dictionary from a `kwant.Builder` system.
+    """Construct a tight-binding dictionary from a `kwant.builder.Builder` system.
 
     Parameters
     ----------
@@ -25,9 +27,9 @@ def builder_to_tb(
 
     Returns
     -------
-    h_0 :
+    :
         Tight-binding dictionary that corresponds to the builder.
-    data :
+    :
         Data with sites and number of orbitals. Only if `return_data=True`.
     """
     builder = copy(builder)
@@ -129,19 +131,19 @@ def builder_to_tb(
 
 
 def build_interacting_syst(
-    builder: kwant.Builder,
-    lattice: kwant.lattice,
+    builder: kwant.builder.Builder,
+    lattice: kwant.lattice.Polyatomic,
     func_onsite: Callable,
     func_hop: Callable,
     max_neighbor: int = 1,
-) -> kwant.Builder:
+) -> kwant.builder.Builder:
     """
     Construct an auxiliary `kwant` system that encodes the interactions.
 
     Parameters
     ----------
     builder :
-        Non-interacting `kwant` system.
+        Non-interacting `kwant.builder.Builder` system.
     lattice :
         Lattice of the system.
     func_onsite :
@@ -154,10 +156,12 @@ def build_interacting_syst(
 
     Returns
     -------
-    int_builder :
-        Auxiliary `kwant.Builder` that encodes the interactions of the system.
+    :
+        Auxiliary `kwant.builder.Builder` that encodes the interactions of the system.
     """
-    int_builder = kwant.Builder(kwant.TranslationalSymmetry(*builder.symmetry.periods))
+    int_builder = kwant.builder.Builder(
+        kwant.lattice.TranslationalSymmetry(*builder.symmetry.periods)
+    )
     int_builder[builder.sites()] = func_onsite
     for neighbors in range(max_neighbor):
         int_builder[lattice.neighbors(neighbors + 1)] = func_hop

pymf/mf.py

@@ -38,7 +38,7 @@ def construct_density_matrix_kgrid(
 def construct_density_matrix(
     h: tb_type, filling: float, nk: int
 ) -> Tuple[tb_type, float]:
-    """Compute the density matrix in real-space tight-binding format.
+    """Compute the real-space density matrix tight-binding dictionary.
 
     Parameters
     ----------
@@ -78,15 +78,19 @@ def meanfield(density_matrix: tb_type, h_int: tb_type) -> tb_type:
         Density matrix tight-binding dictionary.
     h_int :
         Interaction hermitian Hamiltonian tight-binding dictionary.
-        The interaction must be of density-density type, h_int[R][i, j] * c_i^dagger(R) c_j^dagger(0) c_j(0) c_i(R).
-        For example in 1D system with ndof internal degrees of freedom,
-        h_int[(2,)] = U * np.ones((ndof, ndof)) is a Coulomb repulsion interaction
-        with strength U between unit cells separated by 2 lattice vectors, where
-        the interaction is the same between all internal degrees of freedom.
     Returns
     -------
     :
         Mean-field correction tight-binding dictionary.
+
+    Notes
+    -----
+
+    The interaction h_int must be of density-density type.
+    For example in 1D system with ndof internal degrees of freedom,
+    h_int[(2,)] = U * np.ones((ndof, ndof)) is a Coulomb repulsion interaction
+    with strength U between unit cells separated by 2 lattice vectors, where
+    the interaction is the same between all internal degrees of freedom.
     """
     n = len(list(density_matrix)[0])
     local_key = tuple(np.zeros((n,), dtype=int))

pymf/model.py

@@ -44,14 +44,17 @@ class Model:
         Non-interacting hermitian Hamiltonian tight-binding dictionary.
     h_int :
         Interaction hermitian Hamiltonian tight-binding dictionary.
-        The interaction must be of density-density type, h_int[R][i, j] * c_i^dagger(R) c_j^dagger(0) c_j(0) c_i(R).
-        For example in 1D system with ndof internal degrees of freedom,
-        h_int[(2,)] = U * np.ones((ndof, ndof)) is a Coulomb repulsion interaction
-        with strength U between unit cells separated by 2 lattice vectors, where
-        the interaction is the same between all internal degrees of freedom.
     filling :
         Number of particles in a unit cell.
         Used to determine the Fermi level.
+
+    Notes
+    -----
+    The interaction h_int must be of density-density type.
+    For example in 1D system with ndof internal degrees of freedom,
+    h_int[(2,)] = U * np.ones((ndof, ndof)) is a Coulomb repulsion interaction
+    with strength U between unit cells separated by 2 lattice vectors, where
+    the interaction is the same between all internal degrees of freedom.
     """
 
     def __init__(self, h_0: tb_type, h_int: tb_type, filling: float) -> None:

pymf/tb/utils.py

@@ -53,7 +53,8 @@ def generate_tb_keys(cutoff: int, dim: int) -> list[tuple[None] | tuple[int, ...
 
     Returns
     -------
-    List of generated tight-binding dictionary keys up to a cutoff.
+    :
+        List of generated tight-binding dictionary keys up to a cutoff.
     """
     return [*product(*([[*range(-cutoff, cutoff + 1)]] * dim))]