Matrix Product States
=====================

Matrix product states (MPS) are compact tensor-network representations for
one-dimensional quantum many-body states. PyQED uses MPS ideas for lattice
models, vibrational problems, quantum chemistry DMRG prototypes, and
time-dependent simulations.

MPS Ansatz
----------

For a chain of ``L`` sites with local basis states ``sigma_i``, an MPS writes
the wavefunction as

.. math::

   |\Psi\rangle =
   \sum_{\sigma_1\cdots\sigma_L}
   A^{\sigma_1}_1 A^{\sigma_2}_2 \cdots A^{\sigma_L}_L
   |\sigma_1\cdots\sigma_L\rangle.

Each ``A_i`` is a rank-3 tensor with one physical index and two virtual bond
indices. The maximum virtual dimension ``D`` controls the expressive power:
larger ``D`` captures more entanglement but increases cost.

The Schmidt decomposition across a bond is

.. math::

   |\Psi\rangle =
   \sum_{\alpha=1}^{\chi}
   s_\alpha
   |\alpha_L\rangle |\alpha_R\rangle,

where the number of significant singular values determines the required bond
dimension. Low-entanglement states are therefore efficient in MPS form.

Canonical Forms
---------------

MPS algorithms rely on canonical gauges. A left-canonical tensor satisfies

.. math::

   \sum_\sigma (A^\sigma)^\dagger A^\sigma = I,

while a right-canonical tensor satisfies

.. math::

   \sum_\sigma A^\sigma (A^\sigma)^\dagger = I.

Mixed-canonical form places an orthogonality center on one site or bond. This
is the preferred representation for local optimization, expectation values,
and stable time evolution.

Matrix Product Operators
------------------------

Operators can be represented as matrix product operators (MPOs):

.. math::

   \hat{O} =
   \sum_{\sigma,\sigma'}
   W^{\sigma_1\sigma'_1}_1
   W^{\sigma_2\sigma'_2}_2
   \cdots
   W^{\sigma_L\sigma'_L}_L
   |\sigma_1\cdots\sigma_L\rangle
   \langle\sigma'_1\cdots\sigma'_L|.

For lattice models, compact MPOs are often available analytically. For quantum
chemistry, the Hamiltonian contains long-range two-electron terms and requires
careful MPO construction or complementary-operator factorizations.

DMRG
----

The density matrix renormalization group (DMRG) variationally minimizes

.. math::

   E = \frac{\langle\Psi|H|\Psi\rangle}
            {\langle\Psi|\Psi\rangle}

within the MPS manifold. In a one-site or two-site sweep, all tensors except a
local block are held fixed, producing an effective eigenvalue problem:

.. math::

   H_\mathrm{eff} x = E x.

Sweeping repeatedly through the chain relaxes the MPS toward the ground state
or targeted low-lying states.

Quantum Chemistry DMRG
----------------------

In quantum chemistry, each spatial orbital or spin orbital is mapped to a site.
The electronic Hamiltonian is

.. math::

   H =
   \sum_{pq} h_{pq} a_p^\dagger a_q
   + \frac{1}{2}\sum_{pqrs} (pq|rs)
     a_p^\dagger a_r^\dagger a_s a_q.

DMRG is useful when the active space is too large for full CI but the
entanglement structure is still moderate. It can be used as a CASCI solver or
as the active-space solver inside DMRG-SCF/CASSCF workflows.

Symmetries
----------

Symmetry-adapted MPS implementations reduce cost by block-sparsifying tensors.
Common symmetries include particle number, spin projection, point group labels,
and total spin. PyQED contains both Abelian and prototype non-Abelian/SU(2)
development paths.

For SU(2)-adapted quantum chemistry, tensors store reduced multiplet data
rather than all spin components. This requires explicit Clebsch-Gordan and
fusion-tree bookkeeping, but can substantially reduce the number of states
needed for spin-adapted calculations.

Time-Dependent MPS
------------------

Time evolution applies

.. math::

   |\Psi(t+\Delta t)\rangle
   \approx e^{-iH\Delta t}|\Psi(t)\rangle.

MPS time evolution can be implemented with TEBD, TDVP-like updates, Krylov
local propagation, or problem-specific MPO exponentials. PyQED includes
time-dependent MPS examples for model and quantum chemistry workflows.

Package Map
-----------

The MPS-related code is split across several namespaces:

* ``pyqed.mps`` contains general MPS, MPO, TEBD, DMRG, symmetry, and AutoMPO
  utilities.
* ``pyqed.mps.autompo`` contains automatic MPO construction helpers.
* ``pyqed.mps.nonabelian`` contains prototype SU(2)/non-Abelian tensor and DMRG
  components.
* ``pyqed.qchem.dmrg`` contains quantum-chemistry DMRG and DMRG-SCF-facing
  code.
* ``pyqed.dmrg`` contains older/simple DMRG examples and prototypes.

Examples
--------

Useful example entry points:

* ``examples/mps/autompo.py``
* ``examples/mps/autompo_boson.py``
* ``examples/mps/hydrogen_chain.py``
* ``examples/mps/nonabelian_hubbard_chain_benchmark.py``
* ``examples/mps/nonabelian_hubbard_solver_scaling.py``
* ``examples/qchem/dmrgscf.py``
* ``examples/qchem/mps_domain_wall_q_tdmps.py``
* ``examples/qchem/mps_three_electrons_q_dmrg.py``
* ``examples/qchem/tddmrg_h2_threeway_compare.py``

Related Pages
-------------

* :doc:`qchem`
* :doc:`examples`
* :doc:`nonabelian_dmrg_design`