Options

DMRG run options.

Options dataclass

Options(
    scheme: str = "1s",
    n_sweeps: int = 10,
    max_bond: Optional[int] = None,
    trunc_thresh: float = 1e-15,
    davidson_tol: float = 1e-10,
    davidson_max_iter: int = 100,
    davidson_max_subspace: int = 20,
    e_tol: float = 1e-08,
    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,
)

Bases: AlgorithmOptions

DMRG run options.

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

Parameters:

Name	Type	Description	Default
scheme	str	Per-site update scheme. Canonical values and their aliases: '1s' / '1-site' / 'one-site': 1-site DMRG. '2s' / '2-site' / 'two-site': 2-site DMRG. '1sp' / '1-site-plus' / 'one-site-plus': 1-site-plus / CBE.	'1s'
n_sweeps	int	Maximum number of full sweeps (one forward + one backward half-sweep each).	10
max_bond	Optional[int]	Maximum bond dimension kept at each QR step. None means no limit.	None
trunc_thresh	float	SVD truncation threshold forwarded to decomp at each canonical step.	1e-15
davidson_tol	float	Residual norm tolerance for the Davidson eigensolver.	1e-10
davidson_max_iter	int	Maximum Davidson iterations per site optimisation.	100
davidson_max_subspace	int	Maximum Krylov subspace size before a thick restart.	20
e_tol	float	Energy convergence criterion: DMRG stops when |E_new - E_old| < e_tol.	1e-08
env_cache_dir	Optional[str]	Directory for environment block cache files. When set, each block is serialised to {env_cache_dir}/left/{i:05d}.pt or {env_cache_dir}/right/{i:05d}.pt and evicted from memory once it exits the sliding window, keeping peak memory proportional to env_window rather than to chain length. None (default) keeps all blocks in memory. Stored as str for TOML compatibility.	None
env_async_io	bool	If True (default), environment block I/O is submitted to a background thread so it overlaps with the Davidson step. Only relevant when env_cache_dir is set.	True
env_window	int	Number of environment blocks kept in memory at once per direction (current + prefetched ahead). Defaults to 2. Only relevant when env_cache_dir is set.	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 bond dimension used when forming the cheap 2-site tensor Θ̃ = truncated SVD of M[i] ⊗ M[i+1] inside the CBE expansion. Only used when scheme = '1sp'. None keeps the full bond (no additional truncation beyond the existing bond dimension).	None
checkpoint_dir	Optional[str]	Directory to write checkpoint files into. A dmrg.ckpt file (PyTorch format, loadable via dmrg.Summary.load) is written after every full sweep using an atomic write: the data is first serialised to dmrg_lock.ckpt in the same directory, then renamed to dmrg.ckpt on success, so a failed write cannot corrupt the previous checkpoint. 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

TOML Loading

Options can be loaded directly from an [algorithm] TOML section:

import tomllib
from alice import dmrg

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

opts = dmrg.Options.from_toml(cfg["heisenberg"]["algorithm"])

Example TOML block:

[heisenberg.algorithm]
scheme        = "2s"
n_sweeps      = 30
max_bond      = 128
trunc_thresh  = 1e-10
e_tol         = 1e-8

See Also

• Summary — output dataclass.
• run — pass Options here.