API Reference

evolve!(psi, evolution)

Backend-dispatched in-place evolution entry point used throughout MPSToolkit.

Arguments

• psi: Mutable state to evolve. In this package that is typically an MPS, but custom backends used in tests or downstream extensions may define their own state types.
• evolution: Evolution configuration object describing how one logical evolution call should be carried out.

Returns

• The same psi object after in-place mutation.

Notes

• This fallback method exists only to provide a common dispatch point.
• Concrete methods are defined for LocalGateEvolution, DMTGateEvolution, and TDVPEvolution.

evolve!(psi, evo::LocalGateEvolution)

Run scheduled local-gate TEBD evolution on a finite MPS.

Arguments

• psi: State to mutate in place.
• evo: LocalGateEvolution describing gates, schedule, and truncation settings.

Returns

• The mutated psi.

Notes

• One call runs evo.nstep complete traversals of evo.schedule.
• This function is the implementation behind the generic evolve! dispatch for LocalGateEvolution.

evolve!(psi, evo::TDVPEvolution)

Dispatch finite-MPS evolution through the TDVP backend.

Arguments

• psi: State to evolve.
• evo: TDVPEvolution object.

Returns

• The mutated psi.

evolve!(psi, evo::DMTGateEvolution)

Dispatch operator-space evolution through the DMT backend.

energy_density(psi, op; kwargs...)

Backend-dispatched energy-density estimator.

Arguments

• psi: State whose energy density should be estimated.
• op: Observable representation understood by a concrete backend. In this package that is typically either a dense local operator matrix or an MPO.

Keyword Arguments

• kwargs...: Backend-specific options forwarded to the concrete method.

Returns

• A real-valued energy density.

Notes

• The fallback method throws a MethodError.

energy_density(psi, op; span=_operator_span(psi, op))

Estimate the finite-chain average energy density of an MPS for a dense local operator.

Arguments

• psi: Finite matrix-product state.
• op: Dense local operator acting on span consecutive sites.

Keyword Arguments

• span: Explicit support size of op. If omitted, the support is inferred from the local Hilbert-space dimension of psi.

Returns

• The arithmetic mean of the local expectation value of op over all valid windows.

Notes

• No translation invariance is assumed; the routine explicitly averages over all positions.

energy_density(psi, op::MPO)

Return the finite-chain average energy density of an MPS for an MPO.

Arguments

• psi: Finite matrix-product state.
• op: Hamiltonian or observable represented as an MPO.

Returns

• real(<psi|op|psi>) / length(psi).

bond_entropy(psi, bond)

Backend-dispatched bond entanglement entropy estimator.

Arguments

• psi: State whose bipartite entanglement should be measured.
• bond: Backend-specific bond selector. For finite MPS states, nothing means "use the default central bond".

Returns

• The von Neumann entropy associated with the selected cut.

bond_entropy(psi::MPS, bond)

Return the bond entropy for a finite MPS.

Arguments

• psi: Finite matrix-product state.
• bond: Bond index at which to cut the chain. If nothing, the middle bond is used.

Returns

• The von Neumann entropy associated with the Schmidt values across the selected cut.

Notes

• This method delegates spectrum extraction to entanglement_spectrum and then converts the normalized Schmidt probabilities back into amplitudes before evaluating the entropy.

entanglement_spectrum(psi, bond)

Backend-dispatched entanglement-spectrum estimator.

Arguments

• psi: State whose Schmidt spectrum should be extracted.
• bond: Backend-specific bond selector.

Returns

• A vector of normalized Schmidt probabilities.

entanglement_spectrum(psi::MPS, bond)

Return the normalized Schmidt probabilities for a finite MPS.

Arguments

• psi: Finite matrix-product state.
• bond: Bond index at which to cut. nothing selects the central bond.

Returns

• A vector of normalized Schmidt probabilities.

Notes

• Out-of-range bonds return an empty vector rather than throwing.
• The state is copied before orthogonalization, so the input psi is not mutated.

fidelity_distance(psi, reference_state)

Return a selector-friendly fidelity distance.

Arguments

• psi: Candidate state.
• reference_state: Reference state against which fidelity should be measured.

Returns

• 1 - |⟨reference_state|psi⟩|, so lower values correspond to higher fidelity.

Notes

• This helper is intentionally phrased as a distance because ScarFinder selectors minimize their score.

spinhalf_matrices(; include_identity=true)

Return dense spin-1/2 matrices in the (I, Sx, Sy, Sz) convention.

Keyword Arguments

• include_identity: If true, include the identity matrix as field I.

Returns

• A named tuple of dense 2 x 2 matrices where Sx = σx / 2, Sy = σy / 2, and Sz = σz / 2.

spinhalf_xyz_bond_hamiltonian(; Jx=0.0, Jy=0.0, Jz=0.0)

Return the dense two-site spin-1/2 XYZ bond Hamiltonian Jx Sx⊗Sx + Jy Sy⊗Sy + Jz Sz⊗Sz.

Keyword Arguments

• Jx, Jy, Jz: Coupling strengths multiplying the corresponding spin-spin terms.

Returns

• A dense 4 x 4 matrix acting on two spin-1/2 sites.

spinhalf_tfim_bond_hamiltonian(nsites, bond; J=1.0, g=1.0)

Return the dense two-site TFIM bond Hamiltonian with open-boundary field splitting: -J Sz⊗Sz - g (w_left Sx⊗I + w_right I⊗Sx).

Arguments

• nsites: Number of sites in the open chain.
• bond: Bond index of the two-site term, satisfying 1 <= bond < nsites.

Keyword Arguments

• J: Ising coupling.
• g: Transverse-field strength.

Returns

• A dense 4 x 4 matrix suitable for TEBD helper constructors.

Notes

• The transverse field is split evenly between neighboring bonds in the bulk and assigned fully on the edges, which makes the sum over bond Hamiltonians reproduce the standard open-chain TFIM Hamiltonian.