odatse.algorithm.ttopt module

class odatse.algorithm.ttopt.Algorithm(info: Info, runner: Runner | None = None, domain: Region | None = None, run_mode: str = 'initial')

Bases: AlgorithmBase

Tensor-Train Optimization (TTOpt) algorithm implementation.

This class implements the TTOpt algorithm. It is an optimization method that searches for function minima by considering an implicit tensor-train decomposition of a large tensor whose elements correspond to evaluation of the target function at various points in the parameter space.

bounds

Lower and upper bounds along each dimension. It is constructed from a Domain object based on the min_list and max_list parameters.

Type:

np.ndarray

p_points

The number of coarse modes in the parameter space for each dimension (default: [2]*n_dim). Each dimension is effectively discretized into p^q uniformly-spaced points. It is recommended to have p=2 along each dimension.

Type:

np.ndarray

q_points

The number of fine submodes in the parameter space for each dimension (default: [1]*n_dim). Each dimension is effectively discretized into p^q uniformly-spaced points. This parameter determines the fineness of each mode.

Type:

np.ndarray

r_max

The maximum rank of the implicit tensor-train decomposition (default: 4).

Type:

int

max_f_eval

The maximum number of function evaluations (default: 10000).

Type:

int

maxvol_tol

The tolerance needed for early stopping in the maxvol subroutine. Meaningful values are larger than 1 (default: 1.001).

Type:

float

maxvol_max_it

The maximum number of maxvol iterations each time the maxvol subroutine is called (default: 1000).

Type:

int

save_eval_history

If True, stream ttopt_eval_history.txt under the output directory while running (rank 0 only; default: True). Rows are flushed when the in-memory buffer reaches eval_history_buffer_rows points.

Type:

bool

eval_history_buffer_rows

Number of evaluation rows to buffer in memory before appending to disk (default: 256).

Type:

int

init_points

Initial points in physical coordinates to evaluate at the start of optimization. (default: None).

Type:

Optional[np.ndarray]

xopt

The optimal solution.

Type:

Optional[np.ndarray]

fopt

The optimal function value.

Type:

Optional[float]

Initialize the Algorithm class.

Parameters:

• info (odatse.Info) – Information object containing algorithm parameters.

• runner (odatse.Runner, optional) – Runner object for executing the algorithm.

• run_mode (str, optional) – Mode to run the algorithm in, by default “initial”.

__init__(info: Info, runner: Runner | None = None, domain: Region | None = None, run_mode: str = 'initial') → None

Initialize the Algorithm class.

Parameters:

• info (odatse.Info) – Information object containing algorithm parameters.

• runner (odatse.Runner, optional) – Runner object for executing the algorithm.

• run_mode (str, optional) – Mode to run the algorithm in, by default “initial”.

_apply_state(data: dict, mode: str = 'resume', restore_rng: bool = True) → None

Restore algorithm state from a checkpoint snapshot.

Validates the MPI configuration and structural consistency (n_q_dims), optionally restores the RNG, then applies all fields listed in _checkpoint_attrs. The structural fields rebuilt by _setup_structure() (grids, n_points, etc.) are not restored from the checkpoint because they are deterministic functions of the configuration parameters.

Must be called after _setup_structure() so that self.n_q_dims reflects the current configuration and can be compared with the saved value.

Parameters:

• data (dict) – Snapshot previously produced by __getstate__.

• mode (str) – "resume" or "continue"; TTOpt treats them identically.

• restore_rng (bool) – When True, restore the RNG state from data.

_init_counters() → None

Reset evaluation counters and the eval-history file handle.

Called on every run mode so that the history file is opened fresh.

_init_poi() → None

Evaluate init_points and initialize poi/tt_ranks via maxvol.

Called only for fresh runs (mode "initial"). On resume the poi and tt_ranks are restored from the checkpoint instead.

_initialize()

Set up initial algorithm state for a fresh run (init mode).

Called by prepare() when mode starts with "init". Must not use the runner (evaluation happens later in _run()).

_load_state(filename, mode='resume', restore_rng=True) → None

Read a checkpoint file and defer applying it until _prepare().

The snapshot is not applied here: _prepare() first rebuilds the deterministic structural fields (which would otherwise clobber the restored poi/tt_ranks/counters), and only then calls _apply_state.

Parameters:

• filename (str) – Path to the checkpoint file.

• mode (str, optional) – "resume" or "continue". TTOpt does not distinguish between them: the evaluation budget max_f_eval is re-read from the input file on every run and is deliberately not checkpointed, while f_eval_count is. Raising max_f_eval and restarting therefore extends the search in either mode.

• restore_rng (bool, optional) – Whether the RNG state should be restored when the snapshot is applied.

_post() → dict

Collect the best solution across ranks.

_prepare() → None

Prepare the TT decomposition structure and (for fresh runs) the initial poi.

The deterministic structural fields are always rebuilt from config and the counters reset. On resume the checkpoint snapshot (already read by prepare()’s dispatch into self._resume_data) is applied here, after the structural rebuild, so that the restored poi/tt_ranks/counters are not clobbered by _setup_structure()/_init_counters(). For a fresh run the initial poi is built from init_points instead.

_run() → None

Execute the main algorithm loop.

For init mode, perform the initial evaluation here before entering the main loop. Call _save_state() at the appropriate points inside the loop.

_save_state(filename) → None

Save the current algorithm state to a checkpoint file.

_setup_structure() → None

Set up structural fields derived from config parameters.

Called on every run mode (init and resume). These fields are deterministic functions of the configuration and do not need to be checkpointed, but they must exist before _run() can use them.