From 46797280edde01c8765d5a19580c874019717ac8 Mon Sep 17 00:00:00 2001
From: Antonio Manesco <am@antoniomanesco.org>
Date: Wed, 20 Dec 2023 15:25:05 +0100
Subject: [PATCH] add missing docstrings
---
codes/hf.py | 2 --
codes/model.py | 46 ++++++++++++++++++++++++++++-------
codes/utils.py | 65 ++++++++++++++++++++++++++++++++++++++++----------
3 files changed, 91 insertions(+), 22 deletions(-)
diff --git a/codes/hf.py b/codes/hf.py
index 3efe4de..01c6245 100644
--- a/codes/hf.py
+++ b/codes/hf.py
@@ -255,8 +255,6 @@ def kspace_solver(model, optimizer, optimizer_kwargs):
**optimizer_kwargs
)
-
-
def find_groundstate_ham(
model,
cutoff_Vk,
diff --git a/codes/model.py b/codes/model.py
index 7eeacda..0b55a6a 100644
--- a/codes/model.py
+++ b/codes/model.py
@@ -2,6 +2,28 @@ from . import utils
import numpy as np
class Model:
+ """
+ A period tight-binding model class.
+
+ Attributes
+ ----------
+ tb_model : dict
+ Non-interacting tight-binding model.
+ int_model : dict
+ Interacting tight-binding model.
+ Vk : function
+ Interaction potential V(k). Used if `int_model = None`.
+ guess : dict
+ Initial guess for self-consistent calculation.
+ dim : int
+ Number of translationally invariant real-space dimensions.
+ ndof : int
+ Number of internal degrees of freedom (orbitals).
+ hamiltonians_0 : nd-array
+ Non-interacting amiltonian evaluated on a k-point grid.
+ H_int : nd-array
+ Interacting amiltonian evaluated on a k-point grid.
+ """
def __init__(self, tb_model, int_model=None, Vk=None, guess=None):
self.tb_model = tb_model
@@ -23,6 +45,14 @@ class Model:
self.H_int = int_model[()]
def random_guess(self, vectors):
+ """
+ Generate random guess.
+
+ Parameters:
+ -----------
+ vectors : list of tuples
+ Hopping vectors for the mean-field corrections.
+ """
if self.int_model is None:
scale = 1
else:
@@ -34,6 +64,14 @@ class Model:
)
def kgrid_evaluation(self, nk):
+ """
+ Evaluates hamiltonians on a k-grid.
+
+ Parameters:
+ -----------
+ nk : int
+ Number of k-points along each direction.
+ """
self.hamiltonians_0, self.ks = utils.kgrid_hamiltonian(
nk=nk,
hk=self.hk,
@@ -46,11 +84,3 @@ class Model:
hk=utils.model2hk(self.guess),
dim=self.dim,
)
-
- def flatten_mf(self):
- flat = self.mf_k.flatten()
- return flat[:len(flat)//2] + 1j * flat[len(flat)//2:]
-
- def reshape_mf(self, mf_flat):
- mf_flat = np.concatenate((np.real(mf_flat), np.imag(mf_flat)))
- return mf_flat.reshape(*self.hamiltonians_0.shape)
diff --git a/codes/utils.py b/codes/utils.py
index 22e9f71..ea4e730 100644
--- a/codes/utils.py
+++ b/codes/utils.py
@@ -262,8 +262,10 @@ def build_interacting_syst(builder, lattice, func_onsite, func_hop, max_neighbor
def generate_guess(vectors, ndof, scale=0.1):
"""
- nk : int
- Number of k-points along each direction.
+ vectors : list
+ List of hopping vectors.
+ ndof : int
+ Number internal degrees of freedom (orbitals),
scale : float
The scale of the guess. Maximum absolute value of each element of the guess.
@@ -290,6 +292,20 @@ def generate_guess(vectors, ndof, scale=0.1):
def generate_vectors(cutoff, dim):
+ """
+ Generates hopping vectors up to a cutoff.
+
+ Parameters:
+ -----------
+ cutoff : int
+ Maximum distance along each direction.
+ dim : int
+ Dimension of the vectors.
+
+ Returns:
+ --------
+ List of hopping vectors.
+ """
return [*product(*([[*range(-cutoff, cutoff + 1)]] * dim))]
@@ -360,24 +376,49 @@ def calc_gap(vals, E_F):
emin = np.min(vals[vals > E_F])
return np.abs(emin - emax)
+
+def matrix_to_flat(matrix):
+ """
+ Flatten the upper triangle of a collection of matrices.
+
+ Parameters:
+ -----------
+ matrix : nd-array
+ Array with shape (..., n, n)
+ """
+ return matrix[..., *np.triu_indices(matrix.shape[-1])].flatten()
+
def flat_to_matrix(flat, shape):
+ """
+ Undo `matrix_to_flat`.
+
+ Parameters:
+ -----------
+ flat : 1d-array
+ Output from `matrix_to_flat`.
+ shape : 1d-array
+ Shape of the input from `matrix_to_flat`.
+ """
matrix = np.zeros(shape, dtype=complex)
- # if len(shape) > 2:
matrix[..., *np.triu_indices(shape[-1])] = flat.reshape(*shape[:-2], -1)
- # else:
- # matrix[*np.triu_indices(shape[-1])] = flat
indices = np.arange(shape[-1])
diagonal = matrix[..., indices, indices]
matrix += np.moveaxis(matrix, -1, -2).conj()
matrix[..., indices, indices] -= diagonal
return matrix
+def complex_to_real(z):
+ """
+ Split real and imaginary parts of a complex array.
-def matrix_to_flat(matrix):
- return matrix[..., *np.triu_indices(matrix.shape[-1])].flatten()
-
-def real_to_complex(z): # real vector of length 2n -> complex of length n
- return z[:len(z)//2] + 1j * z[len(z)//2:]
+ Parameters:
+ -----------
+ z : array
+ """
+ return np.concatenate((np.real(z), np.imag(z)))
-def complex_to_real(z): # complex vector of length n -> real of length 2n
- return np.concatenate((np.real(z), np.imag(z)))
\ No newline at end of file
+def real_to_complex(z):
+ """
+ Undo `complex_to_real`.
+ """
+ return z[:len(z)//2] + 1j * z[len(z)//2:]
\ No newline at end of file
--
GitLab