bond_update_bug: symmetry-native Basis-Update & Galerkin time integrator (+ TDVP2)

docs/api/bond-update-bug/index.md

@@ -0,0 +1,40 @@
+# bond_update_bug
+
+Alice's bond_update_bug (Basis-Update & Galerkin) integrator evolves an MPS in real or imaginary time under a nearest-neighbour Hamiltonian. It is the rank-adaptive BUG of Ceruti, Kusch & Lubich ([arXiv:2304.05660](https://arxiv.org/abs/2304.05660)): commuting even/odd Trotter sweeps of *local* K/L/S bond updates. Each update augments the left frame from the evolved **K** factor, augments the right frame from the evolved **L** factor, evolves the small core **S** in the augmented bases (Galerkin), then truncates with an SVD — so the bond dimension adapts to the growing entanglement (the basis augmentation). The local substeps exponentiate the *projected* effective Hamiltonian internally (Krylov `expv`); no pre-formed propagator gate is applied, and the update is exact at full rank.
+
+The bond Hamiltonians are reused directly from the [AutoMPO](../interaction/build-interaction.md) interaction list, so any nearest-neighbour model and symmetry that `build_interaction` supports works unchanged.
+
+## API
+
+| Symbol | Description |
+|--------|-------------|
+| [Options](options.md) | Run options: time step, steps, Trotter order, bond dimension |
+| [Summary](summary.md) | Output: evolved MPS, time/norm history, kept and augmented bond dims |
+| [run](run.md) | Top-level entry point |
+
+## Usage Pattern
+
+```python
+from alice import build_interaction, init_mps
+from alice.algorithm import bond_update_bug
+
+interactions, spc, geo = build_interaction("config.toml")
+mps  = init_mps(geo.L, spc, Op, config=[0, 1] * (geo.L // 2), target_qn=0)
+opts = bond_update_bug.Options(dt=0.05, n_steps=40, order='strang', max_bond=128)
+
+summary = bond_update_bug.run(mps, interactions, opts)
+print(summary.max_bond_dims)  # kept bond dimension per step
+print(summary.aug_dims)       # proposed (pre-truncation) augmentation per step
+```
+
+## Trotter Orders
+
+| Name | Alias | Description |
+|------|-------|-------------|
+| `'strang'` | `'second'`, `'2'` | Symmetric second-order step `U_even(dt/2) U_odd(dt) U_even(dt/2)` |
+| `'lie'` | `'first'`, `'1'` | First-order step `U_even(dt) U_odd(dt)` |
+
+## See Also
+
+- [bond_update_bug.run](run.md) — full parameter reference.
+- [build_interaction](../interaction/build-interaction.md) — build the `interactions` argument.

docs/api/bond-update-bug/options.md

@@ -0,0 +1,38 @@
+# Options
+
+bond_update_bug run options.
+
+::: alice.algorithm.bond_update_bug.Options
+    options:
+      heading_level: 2
+
+## TOML Loading
+
+`Options` can be loaded directly from an `[algorithm]` TOML section:
+
+```python
+import tomllib
+from alice.algorithm import bond_update_bug
+
+with open("config.toml", "rb") as f:
+    cfg = tomllib.load(f)
+
+opts = bond_update_bug.Options.from_toml(cfg["heisenberg"]["algorithm"])
+```
+
+Example TOML block:
+
+```toml
+[heisenberg.algorithm]
+dt              = 0.05
+n_steps         = 40
+order           = "strang"
+max_bond        = 128
+trunc_thresh    = 1e-12
+imaginary_time  = false
+```
+
+## See Also
+
+- [Summary](summary.md) — output dataclass.
+- [run](run.md) — pass `Options` here.

docs/api/bond-update-bug/run.md

@@ -0,0 +1,13 @@
+# Launch
+
+Evolve an MPS under a nearest-neighbour Hamiltonian with the bond_update_bug integrator.
+
+::: alice.algorithm.bond_update_bug.run
+    options:
+      heading_level: 2
+
+## See Also
+
+- [Options](options.md) — configure the run.
+- [Summary](summary.md) — interpret the output.
+- [build_interaction](../interaction/build-interaction.md) — create the `interactions` argument.

docs/api/bond-update-bug/summary.md

@@ -0,0 +1,12 @@
+# Summary
+
+bond_update_bug output.
+
+::: alice.algorithm.bond_update_bug.Summary
+    options:
+      heading_level: 2
+
+## See Also
+
+- [Options](options.md) — configure the run.
+- [run](run.md) — produces this dataclass.

docs/api/index.md

@@ -67,6 +67,27 @@ Ground-state DMRG algorithm.
 | [Summary](dmrg/summary.md) | DMRG output dataclass |
 | [run](dmrg/run.md) | Top-level DMRG entry point |
 
+## bond_update_bug
+
+Rank-adaptive Basis-Update & Galerkin time integrator (the discarded-projector
+K/L/S sweep; real and imaginary time).
+
+| Symbol | Description |
+|--------|-------------|
+| [Options](bond-update-bug/options.md) | bond_update_bug run options |
+| [Summary](bond-update-bug/summary.md) | bond_update_bug output dataclass |
+| [run](bond-update-bug/run.md) | Top-level bond_update_bug entry point |
+
+## Two-Site TDVP
+
+Rank-adaptive two-site TDVP time integrator (real and imaginary time).
+
+| Symbol | Description |
+|--------|-------------|
+| [Options](tdvp2/options.md) | TDVP run options |
+| [Summary](tdvp2/summary.md) | TDVP output dataclass |
+| [run](tdvp2/run.md) | Top-level TDVP entry point |
+
 ## Logging
 
 | Symbol | Description |

docs/api/tdvp2/index.md

@@ -0,0 +1,48 @@
+# Two-Site TDVP
+
+Alice's two-site TDVP (Time-Dependent Variational Principle) integrator evolves an MPS in real or imaginary time under a Hamiltonian MPO. It is the projector-splitting scheme of Haegeman et al. ([arXiv:1408.5056](https://arxiv.org/abs/1408.5056)) with a two-site update so the bond dimension adapts. A forward half-sweep evolves each two-site block forward in time and the carried one-site tensor backward in time (the inverse-free backward correction that removes the double counting of the shared bond); a reverse half-sweep mirrors it; a symmetric step composes the two halves for second-order accuracy. The local substeps exponentiate the *effective Hamiltonian* — the MPS tensor bracketed by the left/right MPO environments — with a Hermitian Krylov `expv`.
+
+TDVP needs the full effective Hamiltonian, so it takes a Hamiltonian MPO built by [`build_hamiltonian`](../hamiltonian/build-hamiltonian.md) — exactly like [DMRG](../dmrg/index.md). It reuses the DMRG environment machinery and effective-Hamiltonian contractions.
+
+## API
+
+| Symbol | Description |
+|--------|-------------|
+| [Options](options.md) | Run options: time step, steps, bond dimension, real/imaginary time |
+| [Summary](summary.md) | Output: evolved MPS, time/norm history, kept bond dims |
+| [run](run.md) | Top-level entry point |
+
+## Usage Pattern
+
+```python
+from alice import build_interaction, build_hamiltonian, init_mps
+from alice.algorithm import tdvp2
+
+interactions, spc, geo = build_interaction("config.toml")
+mpo  = build_hamiltonian(interactions, geo.L, spc)
+mps  = init_mps(geo.L, spc, Op, config=[0, 1] * (geo.L // 2), target_qn=0)
+opts = tdvp2.Options(dt=0.05, n_steps=40, max_bond=128)
+
+summary = tdvp2.run(mps, mpo, opts)
+print(summary.max_bond_dims)  # kept bond dimension per step
+print(summary.norms)          # norm per step (≈1 for real time; decays for imaginary)
+```
+
+## Real vs. Imaginary Time
+
+| `imaginary_time` | Propagator | Use |
+|------------------|------------|-----|
+| `False` (default) | `exp(-i dt H)` | unitary real-time dynamics; the norm is conserved |
+| `True` | `exp(-dt H)` | imaginary-time cooling toward the ground state (pair with `normalize=True`) |
+
+!!! note "Convergence at fixed bond dimension"
+    At fixed or adaptively-capped bond dimension, two-site TDVP's error is a
+    *manifold-projection* error that does not vanish as `dt → 0` — it plateaus —
+    rather than the `O(dt²)` state error of a full-rank propagator. Refine the bond
+    dimension (`max_bond`) to reduce the plateau.
+
+## See Also
+
+- [tdvp2.run](run.md) — full parameter reference.
+- [build_hamiltonian](../hamiltonian/build-hamiltonian.md) — build the `mpo` argument.
+- [DMRG](../dmrg/index.md) — ground-state search sharing the same MPO/environment core.

docs/api/tdvp2/options.md

@@ -0,0 +1,37 @@
+# Options
+
+Two-site TDVP run options.
+
+::: alice.algorithm.tdvp2.Options
+    options:
+      heading_level: 2
+
+## TOML Loading
+
+`Options` can be loaded directly from an `[algorithm]` TOML section:
+
+```python
+import tomllib
+from alice.algorithm import tdvp2
+
+with open("config.toml", "rb") as f:
+    cfg = tomllib.load(f)
+
+opts = tdvp2.Options.from_toml(cfg["heisenberg"]["algorithm"])
+```
+
+Example TOML block:
+
+```toml
+[heisenberg.algorithm]
+dt              = 0.05
+n_steps         = 40
+max_bond        = 128
+cutoff          = 1e-12
+imaginary_time  = false
+```
+
+## See Also
+
+- [Summary](summary.md) — output dataclass.
+- [run](run.md) — pass `Options` here.

docs/api/tdvp2/run.md

@@ -0,0 +1,13 @@
+# Launch
+
+Evolve an MPS under a Hamiltonian MPO with the two-site TDVP integrator.
+
+::: alice.algorithm.tdvp2.run
+    options:
+      heading_level: 2
+
+## See Also
+
+- [Options](options.md) — configure the run.
+- [Summary](summary.md) — interpret the output.
+- [build_hamiltonian](../hamiltonian/build-hamiltonian.md) — create the `mpo` argument.

docs/api/tdvp2/summary.md

@@ -0,0 +1,12 @@
+# Summary
+
+Two-site TDVP output.
+
+::: alice.algorithm.tdvp2.Summary
+    options:
+      heading_level: 2
+
+## See Also
+
+- [Options](options.md) — configure the run.
+- [run](run.md) — produces this dataclass.

docs/getting-started/changelog.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## [Unreleased]
+
+**Two-Site BUG Time Integrator**
+
+Adds `alice.algorithm.bond_update_bug`, the rank-adaptive bond_update_bug
+(Basis-Update & Galerkin) integrator of Ceruti, Kusch & Lubich
+([arXiv:2304.05660](https://arxiv.org/abs/2304.05660)) for real- and
+imaginary-time evolution of an MPS under a nearest-neighbour Hamiltonian. The
+Alice-facing driver is built on the existing Alice/Nicole stack — `MPS`, the
+AutoMPO interaction list, and the PyTorch backend; the symmetry-aware KLS
+local kernel is vendored, Nicole-native, in a private `_kernel` subpackage.
+
+### `alice.algorithm.bond_update_bug`
+
+- **`run(mps, interactions, opts)`** evolves the state with commuting even/odd
+  Trotter sweeps of *local* K/L/S bond updates: each update augments the left and
+  right frames from the evolved K and L factors, evolves the small core in the
+  augmented bases (Galerkin), and truncates with an SVD so the bond dimension
+  adapts (the basis augmentation). The local substeps exponentiate the projected
+  effective Hamiltonian internally (Krylov `expv`) — exact at full rank. Supports
+  first-order (`'lie'`) and symmetric second-order (`'strang'`) steps and
+  imaginary-time cooling.
+- **Bond Hamiltonians** are reused from the AutoMPO interaction list: the leading
+  and terminal MPO tensors of each nearest-neighbour `Interaction2Site` are
+  contracted over their operator channel to form the bare two-site term fed to the
+  KLS kernel. The kernel is symmetry-aware (works with the U(1) charge sectors of
+  the MPS).
+- **`Options`** (TOML-loadable) and **`Summary`** mirror the DMRG interface. The
+  summary records, per step, the kept bond dimension and the *proposed* augmented
+  dimension, so the rank growth and the discarded augmentation are both visible.
+- Validated against exact diagonalization (state fidelity, exact norm
+  conservation, U(1) charge conservation, and second-order Trotter convergence).
+
+**Discarded-Projector BUG Variant**
+
+Adds `alice.algorithm.discarded_bug`, the MPS specialisation of the Lubich
+tree-tensor-network BUG (Ceruti–Lubich–Walach,
+[arXiv:2304.05660](https://arxiv.org/abs/2304.05660)). Like two-site TDVP and DMRG
+it takes a Hamiltonian **MPO** and exponentiates the two-site effective Hamiltonian
+with the left/right MPO environments, reusing the DMRG environment machinery; it is
+inverse-free (no backward substep, no overlap-matrix inverse).
+
+### `alice.algorithm.discarded_bug`
+
+- **`run(mps, mpo, opts)`** evolves the state by **recursive bisection** of the
+  chain — the MPS realisation of the reference's balanced-binary-tree `Step` (whose
+  tree is built by recursive bisection of the 1D modes). Each step updates the
+  central bisection bond, then recurses into the two half-chains, until every bond —
+  every tree node — has had its two-site node update. Because every bond is a node,
+  the bond dimension grows along the whole chain (the full ballistic light cone) as
+  a domain wall melts, matching the bond growth of forward two-site TDVP.
+- **Node update.** At each bisection bond the two-site block is evolved once,
+  `Θ1 = exp(τ H₂) Θ0` (Hermitian → tensor Lanczos); the K-step and L-step grow the
+  left/right frames with the **discarded** projector — `qr([Θ1_left | U0])` /
+  `qr([Θ1_right ; V0])`, the direct sum of the old frame with the evolved block's
+  column/row space — with **no** augmented overlap matrices; the Galerkin core is
+  the projection `Û† Θ1 V̂†` of the already-evolved block, SVD-truncated to set the
+  rank. The frames are read off the *evolved* block so a product-state interface
+  grows its genuine rank-2 entanglement (a frozen-neighbour generator would project
+  it out). Everything stays in the U(1) block-sparse Nicole representation, so the
+  kept bond dimension respects the charge sectors.
+- The step is first order in `dt` (no backward substep); the validated property is
+  the rank growth / light-cone spread. A second-order symmetric composition is left
+  to future work.
+- **`Options`** (TOML-loadable) and **`Summary`** mirror the DMRG interface; the
+  summary records the kept bond dimension per step and the final bond dimensions
+  (the light cone).
+- Validated against exact diagonalization (full light-cone growth tracking forward
+  two-site TDVP, first-order single-step convergence, exact norm and U(1) charge
+  conservation, imaginary-time energy descent).
+
+**Two-Site TDVP Time Integrator**
+
+Adds `alice.algorithm.tdvp2`, a rank-adaptive two-site Time-Dependent Variational
+Principle integrator (Haegeman et al., [arXiv:1408.5056](https://arxiv.org/abs/1408.5056))
+for real- and imaginary-time evolution of an MPS under a Hamiltonian MPO. It is
+built on the shared MPS/MPO core and reuses the DMRG environment machinery and
+effective-Hamiltonian contractions, so it depends only on `alice.network` and
+`alice.algorithm.dmrg`.
+
+### `alice.algorithm.tdvp2`
+
+- **`run(mps, mpo, opts)`** evolves the state with symmetric (Strang) steps: a
+  forward half-sweep evolves each two-site block forward in time and the carried
+  one-site tensor backward in time (the inverse-free backward correction that
+  removes the shared-bond double counting), and a reverse half-sweep mirrors it.
+  The local substeps exponentiate the *effective Hamiltonian* — the MPS tensor
+  bracketed by the left/right MPO environments — with a Hermitian Krylov `expv`.
+  The per-bond SVD truncation makes the bond dimension adapt; real and imaginary
+  time (ground-state cooling) are both supported.
+- Takes a Hamiltonian **MPO** (from `build_hamiltonian`), like DMRG, and reuses
+  the DMRG `Environment` blocks, transfer-matrix steps, and the 1-/2-site
+  effective-Hamiltonian contractions. The local Krylov exponential and the
+  evolution-prefactor handling are self-contained in the package.
+- **`Options`** (TOML-loadable) and **`Summary`** mirror the DMRG interface; the
+  summary records the kept bond dimension and the norm per step.
+- Validated against exact diagonalization on the Heisenberg chain (state fidelity,
+  exact norm conservation, U(1) total-Sz conservation, imaginary-time cooling
+  toward the ground state, and bond-dimension growth as a domain wall melts).
+
 ## [0.1.6] - 2026-06-10
 
 **MPS Initialization for Odd Chains**

mkdocs.yml

@@ -103,6 +103,16 @@ nav:
       - Options: api/dmrg/options.md
       - Summary: api/dmrg/summary.md
       - Launch: api/dmrg/run.md
+    - bond_update_bug:
+      - Overview: api/bond-update-bug/index.md
+      - Options: api/bond-update-bug/options.md
+      - Summary: api/bond-update-bug/summary.md
+      - Launch: api/bond-update-bug/run.md
+    - Two-Site TDVP:
+      - Overview: api/tdvp2/index.md
+      - Options: api/tdvp2/options.md
+      - Summary: api/tdvp2/summary.md
+      - Launch: api/tdvp2/run.md
   - Examples:
     - Overview: examples/index.md
     - DMRG:

pyproject.toml

@@ -80,6 +80,12 @@ markers = [
 line-length = 100
 target-version = "py311"
 
+[tool.ruff.lint.per-file-ignores]
+# Vendored, Nicole-native bond_update_bug kernel — kept close to its upstream form.
+# Several modules re-export helpers consumed by sibling kernel modules, so the
+# unused-import rule would force churn that breaks those re-exports.
+"src/alice/algorithm/bond_update_bug/_kernel/**" = ["F401"]
+
 [tool.mypy]
 python_version = "3.11"
 check_untyped_defs = true