[lkdvos]

FiniteEnvironments now caches the prepared left and right halves of the AC and AC2 effective Hamiltonians, so finite algorithms stop re-preparing the same operator halves at every local update.

Changes

• Cached halves. lefthalf/righthalf(Val(N), envs, site, ψ) sit on top of leftenv/rightenv. Each half is prepared lazily and rebuilt when the environment it came from is replaced. AC_hamiltonian/AC2_hamiltonian with prepare = true assemble the operator from the cached halves through hamiltonian_from_halves whenever the environments provide them.
• Generic MPO derivatives are split into prepare_operator_left/prepare_operator_right halves, joined by assemble_operator_halves.
• Jordan MPO derivatives.
  • When the operator is prepared, each half folds its onsite, not-started and finished terms into its own largest term when it is built, so prepare_operator!! only prepares the continuing term. Unprepared derivatives are applied only once, so they skip the folding.
  • Fresh and cached construction share jordan_hamiltonian_left/jordan_hamiltonian_right.
  • Bra and ket no longer have to be equal: when they differ, the boundary environments are kept as explicit tensors.
• Galerkin error in DMRG.
  • calc_galerkin takes prepare = false. With prepare = true, it builds the derivative from the cached halves, which the effective Hamiltonian built afterwards at the same site reuses. Single-site DMRG without bond expansion uses this, so the error costs no separate projection.
  • With OptimalExpand, the single-site derivative is the two-site projection the expansion forms anyway, contracted with the isometry on the other site of the bond. changebond! for OptimalExpand is split into AC2_projection and expand_from_projection!, and DMRG feeds one projection to both the error and the expansion.
  • Other expansions compute the error unprepared, as before, since the expansion would leave the prepared halves stale.
• Tests. test/hamiltonian/derivatives.jl checks that effective Hamiltonians built from the cached halves match unprepared ones while the state changes, and that derivatives are correct for a bra different from the ket. groundstate.jl and approximate.jl cover DMRG on a three-site model and approximate with an MPOHamiltonian.

Performance

Finite DMRG and DMRG2 with the default (adaptive) eigensolver, main at 76a58d7 against this PR, both with BlockTensorKit 0.3.22.

• Rusty: exclusive genoa nodes (AMD EPYC 9474F), single-threaded, Julia 1.13.3, one node per model with the variants in shuffled order.
• Four sweeps from a random state at χ = 256. Times are the mean per sweep over sweeps 2–4, median over 2 runs.
• Energies agree with main to 1e-12.

Models:

• large sparse: transverse-field Ising (h = 1.3) plus 150 random four-site strings, L = 24.
• gapped sparse: the same with h = 4.
• chemistry: a spinless-fermion surrogate with all-pairs hopping and all four-orbital interactions, L = 18.
• gapped chemistry: the same with staggered orbital energies ±4.

model	kind	main	this PR	allocated per sweep
large sparse	DMRG	42.5 s	39.2 s (0.92×)	15.3 → 7.9 GiB
	DMRG2	80.8 s	75.8 s (0.94×)	17.2 → 11.8 GiB
gapped sparse	DMRG	56.9 s	53.3 s (0.94×)	15.3 → 7.9 GiB
	DMRG2	112.1 s	106.6 s (0.95×)	17.2 → 11.8 GiB
chemistry	DMRG	85.2 s	83.7 s (0.98×)	12.1 → 6.6 GiB
	DMRG2	119.6 s	115.2 s (0.96×)	14.2 → 7.7 GiB
gapped chemistry	DMRG	40.1 s	39.0 s (0.97×)	12.1 → 6.5 GiB
	DMRG2	60.2 s	55.4 s (0.92×)	14.1 → 7.6 GiB

In DMRG2, a right sweep rebuilds the left half at every bond, since its environment has just been replaced, but reuses the right half and the operator products of the pair. This cuts the time spent building effective Hamiltonians by about a third (for example 14.6 → 9.9 s per sweep for gapped chemistry). The overall gain is bounded by the eigensolver, which takes 3–9× as long as building the operators even at 2–4 matvecs per update.

Trade-offs

• Peak memory. Keeping the halves costs up to about 3.6 GiB of extra peak memory at χ = 256 for MPOs with many terms (+35–80% over main). It is negligible for nearest-neighbour models.
• Unprepared derivatives (AC_projection, AC2_projection, calc_galerkin) do the same contractions as on main. With BlockTensorKit ≥ 0.3.22 they allocate the same, and their run time agrees with main to within the benchmark's resolution. Older BlockTensorKit versions allocated a full set of blocks for every slice of an environment, which costs about 15% extra allocation here because the halves slice each environment separately.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 94.06780% with 21 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../algorithms/derivatives/hamiltonian_derivatives.jl	94.11%	16 Missing ⚠️
src/algorithms/derivatives/mpo_derivatives.jl	88.88%	4 Missing ⚠️
src/environments/finite_envs.jl	95.65%	1 Missing ⚠️

Files with missing lines	Coverage Δ
src/algorithms/changebonds/optimalexpand.jl	98.90% <100.00%> (+0.02%)	⬆️
src/algorithms/groundstate/dmrg.jl	93.10% <100.00%> (+0.65%)	⬆️
src/algorithms/toolbox.jl	97.91% <100.00%> (+0.02%)	⬆️
src/environments/finite_envs.jl	97.50% <95.65%> (+2.76%)	⬆️
src/algorithms/derivatives/mpo_derivatives.jl	80.46% <88.88%> (+0.99%)	⬆️
.../algorithms/derivatives/hamiltonian_derivatives.jl	93.65% <94.11%> (-4.61%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.