Add Arnoldi documentation

docs/algorithms/arnoldi.rst

@@ -0,0 +1,55 @@
+.. _alg_arnoldi:
+
+*******************************
+Restarted Arnoldi iteration
+*******************************
+
+This is a Krylov method whose update rule expands the function in a Krylov basis 
+:math:`\mathcal{K}_L = \mathrm{lin}\{\ket{\psi_k}, H\ket{\psi_{k}},\ldots,H^{L-1}\ket{\psi_{k}}\}`,
+
+.. math::
+    \psi_{k+1} = \sum_{i=0}^{L-1} c_i H^i \psi_k.
+
+This Arnoldi method estimates the energy functional using two matrices, `A` and `N`---included due to MPS finite-precision---, containing 
+the matrix elements of `H` and the identity computed in the Krylov basis
+
+.. math::
+    E[\chi] = E(\boldsymbol{v}) = \frac{\boldsymbol{v}^\dagger A \boldsymbol{v}}{\boldsymbol{v}^\dagger N \boldsymbol{v}}.
+
+This is the cost function for the optimization, whose critical points
+
+.. math::
+    \frac{\delta E}{\delta \boldsymbol{v}^*} = \frac{1}{\boldsymbol{v}^\dagger N \boldsymbol{v}}\left(A \boldsymbol{v} - E(\boldsymbol{v}) N\boldsymbol{v}\right) = 0.
+
+This leads to the generalized eigenvalue equation
+
+.. math::
+  A \boldsymbol{v} = \lambda N \boldsymbol{v},
+
+where the minimum eigenvalue :math:`\lambda = E(\boldsymbol{v})` gives the optimal energy for the $k$-th step, and the associated direction 
+:math:`\mathbf{v}` provides the steepest descent on the plane.
+
+This procedure could be enhanced with additional approaches. We introdce a specific restart method, 
+which halts the expansion of the Krylov basis when either the maximum desired size $n_v$ is attained, or when the condition number of 
+the scalar product matrix $N$ exceeds a certain threshold. This occurs when there is a risk of adding a vector that is linearly dependent 
+on the previous ones. In such a scenario, we can solve the generalized eigenvalue problem to obtain 
+the next best estimate in a smaller basis. Another approach to enhance the convergence of eigenvalues is to extrapolate the next vector 
+based on previous estimates, using the formula :math:`|{\xi_{k+1}}\rangle=(1-\gamma)|{\psi_{k+1}}\rangle+|{\psi_k}\rangle`, with the 
+memory factor :math:`\gamma=-0.75`.
+
+
+The rule in :ref:`alg_descent` is a particular case of the Arnoldi iteration with a Krylov basis with  $L=2$.
+
+This algorithm can be used both in a context of global optimazation and evolution.
+
+.. autosummary::
+    :toctree: generated/
+
+    ~seemps.optimization.arnoldi
+    ~seemps.evolution.arnoldi
+
+
+
+
+
+

docs/algorithms/generated/seemps.evolution.arnoldi.rst

@@ -0,0 +1,11 @@
+
+
+seemps.evolution.arnoldi
+========================
+
+.. currentmodule:: seemps.evolution
+
+
+
+.. autofunction:: seemps.evolution.arnoldi
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.H.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.H
+======================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.H
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.N.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.N
+======================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.N
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.V.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.V
+======================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.V
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.add_vector.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.add\_vector
+================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+method
+
+.. automethod:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.add_vector
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.build_Krylov_basis.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.build\_Krylov\_basis
+=========================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+method
+
+.. automethod:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.build_Krylov_basis
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.eigenvector.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.eigenvector
+================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+method
+
+.. automethod:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.eigenvector
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.empty.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.empty
+==========================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.empty
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.energy_and_variance.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.energy\_and\_variance
+==========================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+method
+
+.. automethod:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.energy_and_variance
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.exponential.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.exponential
+================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+method
+
+.. automethod:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.exponential
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.gamma.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.gamma
+==========================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.gamma
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.operator.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.operator
+=============================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.operator
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.orthogonalize.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.orthogonalize
+==================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.orthogonalize
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.restart_with_ground_state.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.restart\_with\_ground\_state
+=================================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+method
+
+.. automethod:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.restart_with_ground_state
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.restart_with_vector.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.restart\_with\_vector
+==========================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+method
+
+.. automethod:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.restart_with_vector
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.rst

@@ -0,0 +1,39 @@
+seemps.optimization.arnoldi.MPSArnoldiRepresentation
+====================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+.. autoclass:: MPSArnoldiRepresentation
+
+
+
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+         :toctree:
+      
+         MPSArnoldiRepresentation.add_vector
+         MPSArnoldiRepresentation.build_Krylov_basis
+         MPSArnoldiRepresentation.eigenvector
+         MPSArnoldiRepresentation.energy_and_variance
+         MPSArnoldiRepresentation.exponential
+         MPSArnoldiRepresentation.restart_with_ground_state
+         MPSArnoldiRepresentation.restart_with_vector
+
+
+
+   
+
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+         :toctree:
+      
+         MPSArnoldiRepresentation.empty
+         MPSArnoldiRepresentation.operator
+         MPSArnoldiRepresentation.H
+         MPSArnoldiRepresentation.N
+         MPSArnoldiRepresentation.V
+         MPSArnoldiRepresentation.strategy
+         MPSArnoldiRepresentation.tol_ill_conditioning
+         MPSArnoldiRepresentation.gamma
+         MPSArnoldiRepresentation.orthogonalize
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.strategy.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.strategy
+=============================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.strategy
+

docs/algorithms/generated/seemps.optimization.arnoldi.MPSArnoldiRepresentation.tol_ill_conditioning.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+seemps.optimization.arnoldi.MPSArnoldiRepresentation.tol\_ill\_conditioning
+===========================================================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+attribute
+
+.. autoattribute:: seemps.optimization.arnoldi.MPSArnoldiRepresentation.tol_ill_conditioning
+

docs/algorithms/generated/seemps.optimization.arnoldi.arnoldi_eigh.rst

@@ -0,0 +1,11 @@
+
+
+seemps.optimization.arnoldi.arnoldi\_eigh
+=========================================
+
+.. currentmodule:: seemps.optimization.arnoldi
+
+
+
+.. autofunction:: seemps.optimization.arnoldi.arnoldi_eigh
+

docs/algorithms/generated/seemps.optimization.arnoldi.rst

@@ -0,0 +1,37 @@
+seemps.optimization.arnoldi
+===========================
+
+.. automodule:: seemps.optimization.arnoldi
+
+
+
+
+
+
+
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree:
+
+      arnoldi_eigh
+
+
+
+
+
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree:
+
+      MPSArnoldiRepresentation
+
+
+
+
+
+
+
+
+

docs/algorithms/index.rst

@@ -9,5 +9,6 @@ Index of algorithms
    tensor_split
    mps_simplification
    gradient_descent
+   arnoldi
    dmrg
    tebd_evolution

docs/seemps_analysis.rst

@@ -9,6 +9,7 @@ Quantum numerical analysis
    :maxdepth: 1
 
    seemps_analysis_spaces
+   seemps_analysis_operators
    seemps_analysis_differentiation
    seemps_analysis_integration
    seemps_analysis_interpolation