Skip to content

Algorithms overview

itis-sumo wraps the Dakota 6.20 engine (via the itis-dakota==1.5.9 PyPI wheel) behind a Python API. Every "algorithm" here is really a NIDR config composer (build the Dakota input block as a string) paired with a run + parse step (execute the wheel, read back its tabular/results output as a DataFrame). No Dakota binary is ever shelled out to — everything runs in-process through dakota.environment.study.

Pipeline shape

sampling / preprocess          config                core                evaluate
  (draw/prepare points)  ──▶  (compose NIDR   ──▶  (execute wheel  ──▶  (parse results,
                                input string)         in worker proc)     compute metrics)
  1. Sampling — draw design points (Latin Hypercube, grid, manual-UQ) or take user-supplied training data.
  2. Config — compose the Dakota NIDR input string for the requested study type (surrogate fit, cross-validation, MOGA, UQ propagation).
  3. Core — hand that string to dakota.environment.study(...) in a ProcessPoolExecutor worker, capture stdout/stderr, return the run directory.
  4. Evaluate — parse the run's .dat/tabular output back into a DataFrame, compute derived quantities (RMSE, R², prediction intervals, Pareto fronts, Sobol indices).

Two capabilities not part of that straight-line pipeline:

  • Sensitivity (Sobol) & UQ propagation — sits on top of evaluate_sumo: draws Saltelli/QMC sample sets or per-variable UQ distributions in pure Python, evaluates the already-built surrogate on them, and post-processes with scipy.stats.
  • Data preprocessing — an optional layer (DataPreprocessor) that normalizes/renames variables before training and inverse-transforms predictions after, independent of which study type ran.

Design invariants worth knowing

These are enforced by the test suite (see SPEC.md §V for the full, authoritative list):

  • No global RNG state — every sampling function takes an explicit seed (np.random.Generator), never reaches into numpy's or scipy's global random state (V3er).
  • No flask/oSPARC imports in core modules — core, config, data, sampling, evaluate have zero web-framework dependencies; test-enforced (V4ty). Only preprocess carries the pydantic job models that originated in the web layer.
  • Run directories are explicit paths — the only implicit os.chdir is scoped to the Dakota worker process via a context-manager guard, never left dangling on the caller's process (V2qw).
  • Variable names preserve literal - — sanitize_varnames treats hyphens as legal characters rather than substitution targets (V6op).
  • Malformed rows are healed-or-dropped with a trace, never silently wiped (V7as).