Skip to content

run

Top-level XTRG entry point.

run 

run(
    state: Artifact, opts: Optional[Options] = None
) -> Tuple[Summary, Artifact]

Run XTRG starting from a given thermal density matrix state.

Repeatedly squares state.rho using variational MPO-MPO compression to reach β_max = 2^n_steps × τ₀, starting at state.step and continuing to opts.n_steps. Building ρ(τ₀) (e.g. via thermal_mpo) and wrapping it in an Artifact at step=0 is the caller's responsibility. Resuming an interrupted run, or continuing a finished one under new options, is calling run() again with the Artifact loaded from xtrg.ckpt or from any archived artifacts/step_XX.ckpt; the matching β/log Z history is recovered automatically from thermal.ckpt in opts.checkpoint_dir.

When that history reaches past state.step — the case when restarting from an earlier archived step to re-cool a segment at, say, a larger max_bond — the later entries are truncated (with a warning), then recomputed by this run and overwritten on disk, together with their step_XX.ckpt archives.

Thermodynamic observables (f, u, c_V, S) are computed from log Z at each step using log-β finite differences for uniform accuracy across the exponential temperature grid.

Parameters:

Name Type Description Default
state Artifact

Starting density matrix, paired with its beta and step. step=0 for a fresh run; step > 0 to resume or continue.

 required
opts Optional[Options]

XTRG run options. Defaults to Options() if None. n_steps counts cooling steps from τ₀, so it is the absolute step index to stop at — not a number of additional steps to perform.

 None

Returns:

Type Description
Summary

Thermodynamic history (β grid, log Z, derived observables). Written to thermal.ckpt under the checkpoint directory.
Artifact

Final density matrix ρ(β_max) with its beta and step.

Raises:

Type Description
ValueError

If opts.scheme is not a recognized scheme, if state.step is past opts.n_steps, or if state.step > 0 and the thermal.ckpt found in opts.checkpoint_dir is inconsistent with state — because it stops before state.step, because its β there disagrees with state.beta, or because it was built with a different τ₀.
NotImplementedError

If opts.scheme is recognized but not yet implemented.
FileNotFoundError

If state.step > 0 and no thermal.ckpt exists in opts.checkpoint_dir to recover the β/log Z history from.

See Also