Options

XTRG run options.

Options dataclass

Options(
    scheme: str = "2s",
    tau_0: float = 2**-12,
    n_steps: int = 20,
    taylor_order: int = 10,
    max_bond: Optional[int] = None,
    trunc_thresh: float = 1e-15,
    n_sweeps: int = 4,
    z_tol: float = 1e-10,
    env_cache_dir: Optional[str] = None,
    env_async_io: bool = True,
    env_window: int = 2,
    expand_k: int = 4,
    expand_alpha: Optional[int] = None,
    checkpoint_dir: Optional[str] = None,
    artifacts_dir: Optional[str] = None,
    save_artifacts: bool = True,
    save_artifacts_since: int = 0,
)

Bases: AlgorithmOptions

XTRG run options.

All fields have sensible defaults so Options() is a valid minimal configuration. Use Options.from_toml to load from a TOML section, or Options.load_toml to read directly from a file.

Parameters:

Name	Type	Description	Default
scheme	str	Update scheme per squaring step. Canonical values and aliases: '1s' / '1-site' / 'one-site': 1-site direct contraction. '2s' / '2-site' / 'two-site': 2-site SVD with truncation. '1sp' / '1-site-plus' / 'one-site-plus': 1-site-plus / CBE.	'2s'
tau_0	float	Initial inverse temperature ≈ 2⁻¹² ≈ 2.44 × 10⁻⁴. Should be small enough that the Taylor expansion converges, and is doubled at each step: β_n = 2^n × τ₀.	2 ** -12
n_steps	int	Number of doubling steps. The final inverse temperature is β_max = 2^n_steps × τ₀.	20
taylor_order	int	Truncation order of the Taylor series for ρ(τ₀) = e^{-τ₀ H}. Higher order increases accuracy and bond dimension of the initial ρ.	10
max_bond	Optional[int]	Maximum bond dimension of the compressed ρ. None means unlimited (meaningful for 2-site and 1-site-plus, where SVD truncation controls growth; a no-op for 1-site beyond the initial compaction, since its local update never changes bond dimension).	None
trunc_thresh	float	Singular value truncation threshold (relative to the largest singular value per charge sector).	1e-15
n_sweeps	int	Maximum number of full variational sweeps (forward + backward) per squaring step. A sweep may stop early once z_tol is satisfied.	4
z_tol	float	Convergence tolerance for the inner variational fit: sweeping stops early once |‖C‖ − ‖C_prev‖| < z_tol, where ‖C‖ is the Frobenius norm of the compressed density matrix (proportional to the partition function Z) measured at the orthogonality center after each full sweep. Plays the same structural role as DMRG's e_tol, but tracks fit convergence via ‖C‖ rather than energy, since the local update here is an exact least-squares projection (no eigenproblem): at that optimum ⟨C, A·B⟩ = ‖C‖², so ‖C − A·B‖²_F = ‖A·B‖² − ‖C‖² and ‖A·B‖ is fixed across sweeps, making ‖C‖ convergence equivalent to residual convergence.	1e-10
env_cache_dir	Optional[str]	Root directory for environment disk caching. When set, run() creates a unique subdirectory inside it (first 8 hex characters of a UUID4, e.g. {env_cache_dir}/a1b2c3d4/) so that concurrent runs sharing the same config do not overwrite each other's blocks. Inside that subdirectory, xtrg_left/{i:05d}.pt and xtrg_right/{i:05d}.pt files are written, and are reused across all squaring steps of the run. The unique subdirectory is removed automatically when run() returns (or raises). None (default) keeps all blocks in memory. Useful for large chains where environments do not fit in RAM. Stored as str for TOML compatibility.	None
env_async_io	bool	If True (default), disk writes are submitted asynchronously so they overlap with computation. Has no effect when env_cache_dir is None.	True
env_window	int	Number of environment blocks to keep in memory at once when disk caching is enabled.	2
expand_k	int	Maximum number of complement vectors added to each bond end per CBE step. Only used when scheme = '1sp'. Larger values give a richer expanded space at higher cost; 4 is a typical starting point.	4
expand_alpha	Optional[int]	Internal connector-bond dimension used by the cheap per-operand SVD compression inside the CBE expansion (Eq. 13 of arXiv:2510.25022). Only used when scheme = '1sp'. None skips compression (uses the exact factor-MPO tensors, at the cost of a full 2-site-scale join). The paper recommends expand_alpha ≈ expand_k ≈ round(sqrt(max_bond)).	None
checkpoint_dir	Optional[str]	Directory for checkpoint files. After every cooling step a thermal.ckpt file (PyTorch format, loadable via xtrg.Summary.load) is written using an atomic write (thermal_lock.ckpt → rename). Mid-run progress is stored as xtrg.ckpt (an Artifact) and removed when run() finishes successfully. None (default) resolves to Path.cwd() at the time run() is called, mirroring .logging. Pass an explicit path string to write elsewhere. Stored as str for TOML compatibility.	None
artifacts_dir	Optional[str]	Directory for per-step Artifact files (step_XX.ckpt), written when save_artifacts is True. None (default) resolves to artifacts/ under checkpoint_dir. Pass an explicit path string to archive artifacts elsewhere, independent of checkpoint_dir. Stored as str for TOML compatibility.	None
save_artifacts	bool	If True (default), write per-step Artifact files under artifacts_dir for every step with index >= save_artifacts_since. Step 0 is after Taylor init (ρ(τ₀)); step k (1 … n_steps) is after the k-th squaring.	True
save_artifacts_since	int	First step index (inclusive) at which step_XX.ckpt files are written under artifacts_dir when save_artifacts is True. Must be >= 0.	0

TOML Loading

Options can be loaded directly from a TOML section:

import tomllib
from alice.algorithm import xtrg

with open("config.toml", "rb") as f:
    cfg = tomllib.load(f)

opts = xtrg.Options.from_toml(cfg["free_fermion"]["algorithm"])

Example TOML block:

[free_fermion.algorithm]
scheme       = "2s"
tau_0        = 0.000244140625   # 2^{-12}
n_steps      = 20
max_bond     = 64
trunc_thresh = 1e-12
n_sweeps     = 4

See Also

• Summary — thermodynamic history.
• Artifact — density-matrix snapshots.
• run — pass Options here.