solver_options.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_SOLVERS_SOLVER_OPTIONS_H
#define LINE_SOLVERS_SOLVER_OPTIONS_H
 
/**
 * @file
 * @ingroup line_solvers
 * @ingroup line_public
 * The keyword arguments a solver takes, as one struct.
 *
 * Python builds a solver as `MVA(model, method='lin')` or
 * `CTMC(model, cutoff=3, seed=23000)` -- one shared keyword surface across
 * every solver, narrowed per solver by which keywords it reads. This is that
 * surface: a field per keyword, and a fluent `set_*` per field so a C++ call
 * reads like the Python one it was ported from.
 *
 *     SolverOptions().set_cutoff(3).set_seed(23000)
 *
 * A field left at its default is NOT forwarded, so the engine's own default
 * stands: that is what the negative/empty sentinels below mean. This mirrors
 * MATLAB's `Solver.defaultOptions` merge rather than overwriting it.
 */
 
#include <cstddef>
#include <string>
#include <vector>
 
#include "line/util/matrix.h"
 
namespace line {
 
/** The knobs a solver reads; a negative or empty field keeps the engine default. */
struct SolverOptions {
    std::string method = "default";
    double tol = -1.0;
    double iter_tol = -1.0;
    int iter_max = -1;
    std::size_t samples = 0;
    unsigned long seed = 0;
    /** CTMC `options.cutoff`, scalar or per class. */
    double cutoff = -1.0;
    std::vector<std::size_t> cutoff_vec;
    /** CTMC refusal threshold on the state-space size. */
    std::size_t state_max = 0;
    /** Fluid `options.timespan(2)` and warm start. */
    double timespan_end = -1.0;
    std::vector<double> init_sol;
    bool stiff = false;
    /** The `options.config` fields of the MVA / NC / fluid families. */
    std::string multiserver;
    std::string highvar;
    std::string np_priority;
    /** MVA / NC `options.config.fork_join`: 'default'/'mmt'/'fjt' or 'ht'. */
    std::string fork_join;
    /** SSA `options.config.state_space_gen`. */
    std::string state_space_gen;
    /**
     * `options.config.symbolic`: the computer-algebra backend to resolve.
     *
     * Empty keeps the engine default, which is `auto`. Other values are a URL,
     * an image name, or `none` to stay local. Hoisted out of `config` like
     * every other field here: this struct is flat by design.
     */
    std::string symbolic;
    /**
     * `options.config.symbolic_timeout`, seconds per symbolic request.
     *
     * Non-positive keeps the engine default of 300. It is a real knob and not
     * a formality: a symbolic solve grows superpolynomially in the state count,
     * and the fluid equilibria of a smoothed softmin drift are transcendental
     * in exp(-pstar*x) and outrun 300 s on models that are otherwise ordinary.
     */
    int symbolic_timeout = -1;
    /**
     * `options.config.map_env`: `"auto"` (or `"default"`) lets a model whose ONLY unsupported
     * features are non-renewal processes fall back to its random-environment
     * image, `"off"` keeps the plain rejection.
     *
     * CALLER-FACING ONLY, and deliberately not on `MvaOptions`, `NcSolverOptions`
     * or `FluidOptions`: no `runAnalyzer` reads it in the reference either. The
     * fallback happens ABOVE the runner, in `getAvg`'s place, because the runner
     * must go on refusing the model it cannot consume.
     */
    std::string map_env;
    /** `options.config.map_env_method`: `auto`, `meanfield`, `dec` or `avg`. */
    std::string map_env_method;
    /** `options.config.map_env_maxstages`: 0 keeps `map2renv`'s own cap of 64. */
    std::size_t map_env_maxstages = 0;
    /** SolverBA `options.level`. */
    int level = 2;
    /**
     * JMT `options.config.replications`: the independent JSIM runs the transient ensemble of
     * `default` averages over a finite timespan. Non-positive keeps the engine default of 10.
     */
    int replications = -1;
    /**
     * `options.cache`: reuse the solved tables on later calls to the same solver object.
     *
     * True, the reference default, returns the stored result from `avg_table` and everything
     * built on it; false re-runs the analysis on every call, as MATLAB's and the JAR's getAvg
     * do under `~options.cache`, so edits to the model are picked up without `reset()`.
     */
    bool cache = true;
    /** JMT `options.keep`: leave the scratch directory in place after the solve. */
    bool keep = false;
    bool verbose = false;
    /** `options.force`: CTMC downgrades its memory pre-gate refusal to a warning. */
    bool force = false;
    /** `options.timestep`: CTMC fixed transient output step, fluid diffusion step; <= 0 keeps the default. */
    double timestep = -1.0;
    /** `options.timeout`, seconds: the cooperative wall-clock budget LDES polls; <= 0 keeps none. */
    double timeout = -1.0;
    /** `options.events`: the SSA / LDES event budget, overriding `samples` when set; 0 = not given. */
    std::size_t events = 0;
    /**
     * `options.confint`: the confidence level of the half-widths JMT and LDES report, in (0,1).
     *
     * 0 is the reference's `false`: no interval columns in `AvgTable`. A level fills `QLenCI` and
     * its siblings, which `AvgTable::print` shows as `mean +- half-width`. SSA reports no interval.
     */
    double confint = 0.0;
    /** LDES `options.cimethod`: obm | bm | spectral | none; empty keeps obm. */
    std::string cimethod;
    /** LDES `options.ciminbatch` / `ciminobs`; negative keeps the engine's 10 / 100. */
    int ciminbatch = -1;
    int ciminobs = -1;
    /** LDES `options.obmoverlap`, in [0,1]; negative keeps 0.5. */
    double obmoverlap = -1.0;
    /** LDES `options.spectralLowFreqFrac`, in (0,1]; non-positive keeps 0.25. */
    double spectral_low_freq_frac = -1.0;
    /** LDES `options.tranfilter`: mser5 | fixed | none; empty keeps mser5. */
    std::string tranfilter;
    /** LDES `options.mserbatch`; non-positive keeps 5. */
    int mserbatch = -1;
    /** `options.warmupfrac`, in [0,1): LDES under tranfilter=fixed, and SSA's discarded prefix. */
    double warmupfrac = -1.0;
    /**
     * LDES `options.init_jobs`: one row per job, [station, class, remaining, elapsed, qage, sage,
     * order, id] with 0-based indexes; takes precedence over the model state and `init_sol`.
     */
    Matrix<double> init_jobs;
    /** LDES `options.track_jobs`: return the end-of-run job state; implied by `init_jobs`. */
    bool track_jobs = false;
    /** LDES convergence stopping: `cnvgon`, `cnvgtol`, `cnvgbatch`, `cnvgchk`; negative keeps the default. */
    bool cnvgon = false;
    double cnvgtol = -1.0;
    int cnvgbatch = -1;
    int cnvgchk = -1;
 
    SolverOptions& set_method(const std::string& v) { method = v; return *this; }
    SolverOptions& set_tol(double v) { tol = v; return *this; }
    SolverOptions& set_iter_tol(double v) { iter_tol = v; return *this; }
    SolverOptions& set_iter_max(int v) { iter_max = v; return *this; }
    SolverOptions& set_replications(int v) { replications = v; return *this; }
    SolverOptions& set_samples(std::size_t v) { samples = v; return *this; }
    SolverOptions& set_seed(unsigned long v) { seed = v; return *this; }
    SolverOptions& set_cutoff(double v) { cutoff = v; return *this; }
    SolverOptions& set_cutoff_vec(const std::vector<std::size_t>& v) { cutoff_vec = v; return *this; }
    SolverOptions& set_state_max(std::size_t v) { state_max = v; return *this; }
    SolverOptions& set_timespan_end(double v) { timespan_end = v; return *this; }
    SolverOptions& set_init_sol(const std::vector<double>& v) { init_sol = v; return *this; }
    SolverOptions& set_stiff(bool v) { stiff = v; return *this; }
    SolverOptions& set_multiserver(const std::string& v) { multiserver = v; return *this; }
    SolverOptions& set_highvar(const std::string& v) { highvar = v; return *this; }
    SolverOptions& set_np_priority(const std::string& v) { np_priority = v; return *this; }
    SolverOptions& set_fork_join(const std::string& v) { fork_join = v; return *this; }
    SolverOptions& set_state_space_gen(const std::string& v) { state_space_gen = v; return *this; }
    SolverOptions& set_symbolic(const std::string& v) { symbolic = v; return *this; }
    SolverOptions& set_symbolic_timeout(int v) { symbolic_timeout = v; return *this; }
    SolverOptions& set_map_env(const std::string& v) { map_env = v; return *this; }
    SolverOptions& set_map_env_method(const std::string& v) { map_env_method = v; return *this; }
    SolverOptions& set_map_env_maxstages(std::size_t v) { map_env_maxstages = v; return *this; }
    SolverOptions& set_level(int v) { level = v; return *this; }
    SolverOptions& set_cache(bool v) { cache = v; return *this; }
    SolverOptions& set_keep(bool v) { keep = v; return *this; }
    SolverOptions& set_verbose(bool v) { verbose = v; return *this; }
    SolverOptions& set_force(bool v) { force = v; return *this; }
    SolverOptions& set_timestep(double v) { timestep = v; return *this; }
    SolverOptions& set_timeout(double v) { timeout = v; return *this; }
    SolverOptions& set_events(std::size_t v) { events = v; return *this; }
    SolverOptions& set_confint(double v) { confint = v; return *this; }
    SolverOptions& set_cimethod(const std::string& v) { cimethod = v; return *this; }
    SolverOptions& set_ciminbatch(int v) { ciminbatch = v; return *this; }
    SolverOptions& set_ciminobs(int v) { ciminobs = v; return *this; }
    SolverOptions& set_obmoverlap(double v) { obmoverlap = v; return *this; }
    SolverOptions& set_spectral_low_freq_frac(double v) { spectral_low_freq_frac = v; return *this; }
    SolverOptions& set_tranfilter(const std::string& v) { tranfilter = v; return *this; }
    SolverOptions& set_mserbatch(int v) { mserbatch = v; return *this; }
    SolverOptions& set_warmupfrac(double v) { warmupfrac = v; return *this; }
    SolverOptions& set_init_jobs(const Matrix<double>& v) { init_jobs = v; return *this; }
    SolverOptions& set_track_jobs(bool v) { track_jobs = v; return *this; }
    SolverOptions& set_cnvgon(bool v) { cnvgon = v; return *this; }
    SolverOptions& set_cnvgtol(double v) { cnvgtol = v; return *this; }
    SolverOptions& set_cnvgbatch(int v) { cnvgbatch = v; return *this; }
    SolverOptions& set_cnvgchk(int v) { cnvgchk = v; return *this; }
};
 
}  // namespace line
 
#endif  // LINE_SOLVERS_SOLVER_OPTIONS_H