ldes_options.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_SOLVERS_WRAPPERS_LDES_LDES_OPTIONS_H
#define LINE_SOLVERS_WRAPPERS_LDES_LDES_OPTIONS_H
 
/**
 * @file
 * @ingroup line_solvers
 * The option and result records of SolverLDES, the discrete-event simulator.
 *
 * SOURCE. `LDESOptions` transcribes `python/line_solver/solvers/wrappers/
 * solver_ldes/ldes_options.py` and the `ldesOpt` reads of
 * `@@SolverLDES/solveCli.m`; `LdesResult` transcribes the `ldes-result`
 * document `jline/io/LDESResultIO.java` writes, block for block. The two
 * subprocess clients that precede this one (MATLAB, native Python) parse a
 * SUBSET of that document; this record carries all of it, because a block that
 * is parsed nowhere is a block whose meaning drifts unnoticed.
 *
 * EVERY KNOB IS A CLI FLAG, and the defaults here are the ENGINE's, not this
 * port's: `ldes_flags` below emits a flag only when the value differs from the
 * default, exactly as `_build_flag_args` and `solveCli` do, so a default run
 * produces the minimal command line an older AOT native binary still parses. A
 * default that disagreed with `LdesCLI`'s would therefore be invisible in the
 * command line and change the answer -- which is why `seed` is the one
 * exception and is ALWAYS emitted: the CLI default is -1 (a random seed), not
 * 23000, so omitting it at the nominal seed would make the run irreproducible
 * and silently different from the MATLAB and Python clients.
 */
 
#include <cstddef>
#include <limits>
#include <map>
#include <string>
#include <vector>
 
#include "line/api/sim/sim_runlength.h"
#include "line/util/matrix.h"
#include "line/solvers/method_registry.h"
 
namespace line {
namespace ldes {
 
/**
 * Port of `SolverLDES.listValidMethods`.
 *
 * Two names, and only one engine behind them: 'parallel' asks the engine for
 * INDEPENDENT REPLICATIONS and the mean over them, which the client turns into
 * `--replications` (the caller's count when set, 8 otherwise). It is not a
 * second simulator, which is why the list is this short in all four codebases.
 * 'para' is its short spelling, as in SolverSSA.
 */
inline std::vector<std::string> list_valid_methods() {
    // the names and their order are this solver's row of the method registry (doc/line-methods.json)
    return ::line::method_registry::methods("LDES");
}
 
/**
 * The knobs of one LDES run.
 *
 * `samples` is an EVENT BUDGET (service completions), not a sample size in the
 * statistical sense, and `events` is the same budget under the name the newer
 * API uses: when set it overrides `samples`, as it does in both clients.
 */
struct LdesOptions {
    std::size_t samples = 200000;  ///< -s, service-completion budget
    std::size_t events = 0;        ///< 0 = not given; overrides `samples` when set
    long seed = 23000;             ///< --seed; -1 requests a random stream
    std::string method = "default";
 
    // ---- convergence-based stopping ----------------------------------------
    bool cnvgon = false;      ///< --cnvgon
    double cnvgtol = 0.05;    ///< --cnvgtol
    int cnvgbatch = 20;       ///< --cnvgbatch, batches before the first check
    int cnvgchk = 0;          ///< --cnvgchk, events between checks; 0 = samples/50
 
    // ---- warmup (transient) filter -----------------------------------------
    std::string tranfilter = "mser5";  ///< --tranfilter: mser5 | fixed | none
    int mserbatch = 5;                 ///< --mserbatch, MSER batch size
    double warmupfrac = 0.2;           ///< --warmupfrac, only for tranfilter=fixed
    /// --tranobs, equally spaced transient observation points over [t0,t1]; fixes the time grid only.
    /// 0 = not given: the engine default, 1000 in both the native and the JAR engine.
    int tranobs = 0;
 
    // ---- confidence intervals ----------------------------------------------
    std::string cimethod = "obm";  ///< --cimethod: obm | bm | spectral | none
    double obmoverlap = 0.5;       ///< --obmoverlap; 0 reduces OBM to plain batch means
    int ciminbatch = 10;           ///< --ciminbatch
    int ciminobs = 100;            ///< --ciminobs, below which no CI is reported
    /**
     * Confidence level of the reported half-widths.
     *
     * `LDESOptions` sets 0.95 where the shared `SolverOptions` leaves it at 0
     * (disabled), so the LDES default is intervals ON. It is not a CLI flag:
     * the engine reads it from the options object, so the subprocess client
     * has no way to vary it and the native engine keeps the same default.
     */
    double confint = 0.95;
    double spectral_low_freq_frac = 0.25;  ///< --spectrallowfreqfrac
    /**
     * `options.config.runLengthPlan`: ask for the run length this run SHOULD
     * have had, for a target relative precision.
     *
     * Non-positive leaves the plan uncomputed. The half-widths above pin the
     * ASYMPTOTIC variance of each estimator -- not its stationary variance,
     * which on M/M/1 differs from it by a factor blowing up like (1-rho)^-2 --
     * and `sim_runlength_plan` turns that into the run length that reaches this
     * precision. The plan lands in `LdesResult::run_length_plan`.
     */
    double run_length_plan_precision = 0.0;
 
    // ---- discrete time ------------------------------------------------------
    bool slotted = false;      ///< --slotted, run on the slot lattice
    double slot_length = 1.0;  ///< --slotlength
 
    // ---- busy periods -------------------------------------------------------
    /**
     * --busyperiod: highest busy period order measured, 0 disabling the
     * measurement. A busy period of order n for a set of stations runs from the
     * instant an arrival raises the jobs it holds to n up to the instant it
     * falls back below n (Daduna, J. ACM 35(3), 1988). When positive the orders
     * 1..busy_period_orders are measured for every station, for every
     * station-class pair, and for every set in `busy_period_subnets`.
     */
    int busy_period_orders = 0;
    /** --busyperiod-subnet, zero-based station indexes, one flag per set. */
    std::vector<std::vector<std::size_t>> busy_period_subnets;
 
    // ---- replication --------------------------------------------------------
    int replications = 0;  ///< --replications; 0 = not given (one path)
    int numthreads = 0;    ///< --numthreads; 0 = not given
 
    // ---- horizon and budget --------------------------------------------------
    bool has_timespan = false;  ///< true when [t0,t1] was set: a TRANSIENT run
    double t0 = 0.0;
    double t1 = 0.0;
    /** --maxtime, a COOPERATIVE wall-clock budget the event loop polls. */
    double timeout = std::numeric_limits<double>::infinity();
 
    /**
     * --initsol, the warm-start placement as a STATION-MAJOR vector
     * [st0_cl0, st0_cl1, ..., stM-1_clK-1]. Empty = the engine's own default
     * (closed jobs at their reference stations).
     */
    std::vector<double> init_sol;
 
    /**
     * --initjobs, the JOB-LEVEL initial state, one row per job:
     * [station, class, remaining, elapsed, qage, sage, order, id].
     *
     * Unlike `init_sol`, which gives counts only and so restarts every job with
     * a fresh service draw, each row carries the job's residual work, so a run
     * continues exactly where an earlier one stopped (`LdesResult::finalJobs` is
     * written in this layout). remaining > 0 is used as given, -1 draws a full
     * service time and -2 draws the residual given the attained service
     * `elapsed`. qage and sage are the time already spent at the station and in
     * the system; `order` ranks the jobs of a station (the first ones take the
     * servers) and `id` (optional, -1 untagged) is echoed in `finalJobs` and
     * `jobDepartures`. Takes precedence over `init_sol`. Supported at FCFS
     * queues, the PS family and Delays.
     */
    Matrix<double> init_jobs;
    /** --trackjobs: fill `finalJobs` and `jobDepartures`; implied by `init_jobs`. */
    bool track_jobs = false;
 
    /**
     * --export-histogram and --trajectory: the joint-state residence-time law
     * and the state path.
     *
     * A TRANSIENT run fills both unconditionally, because it has to walk the
     * state to produce QNt at all. In STEADY STATE they are opt-in: the
     * histogram costs a map lookup per event and the trajectory grows one row
     * per event, which on a million-completion run is a million rows nobody
     * asked for.
     */
    bool export_histogram = false;
    bool export_trajectory = false;
 
    /**
     * --respt-samples: every per-visit response time, not just its mean.
     *
     * It is the input to an EMPIRICAL CDF, which a mean cannot stand in for, and
     * it costs one push per completion, so it is opt-in like the two above.
     */
    bool export_respt = false;
 
    /**
     * Base URL of an LDES REST server (the imperialqore/ldes container). When
     * set the model is POSTed to `<url>/api/v1/solve` instead of being handed to
     * a local binary; the wire format is the same on both sides, so a fixed
     * seed gives the same numbers.
     */
    std::string rest_url;
 
    bool verbose = false;  ///< echo the resolved command line before running it
};
 
/** Per-cache hit/miss/latency, as the `cacheMetrics` block carries them. */
struct LdesCacheMetrics {
    Matrix<double> hit;       ///< (1 x nclasses) hit probability
    Matrix<double> delayed;   ///< (1 x nclasses) delayed-hit probability
    Matrix<double> miss;      ///< (1 x nclasses) miss probability
    Matrix<double> latency;   ///< (1 x nclasses) expected retrieval latency
    Matrix<double> hitList;   ///< (nclasses x nlists) hit probability by list
    Matrix<double> itemProb;  ///< (nitems x nlists+1) item position law
    Matrix<double> listCost;  ///< (1 x nlists) mean storage cost held per list
};
 
/**
 * One `ldes-result` document, parsed.
 *
 * A metric the engine did not report stays EMPTY rather than becoming a matrix
 * of zeros: zero is a measurement and absence is not, and the tables below
 * distinguish them.
 */
struct LdesResult {
    // ---- dimensions and labels ----------------------------------------------
    std::size_t nstations = 0;
 
    /** The jobs present at the end of the run, in the `init_jobs` layout (track_jobs). */
    Matrix<double> finalJobs;
    /** [id, station, class, time] of every departure of a tagged init_jobs job (track_jobs). */
    Matrix<double> jobDepartures;
    std::size_t nclasses = 0;
    std::size_t nchains = 0;
    std::size_t nregions = 0;
    std::vector<std::string> station_names;
    std::vector<std::string> class_names;
 
    // ---- means, (nstations x nclasses) --------------------------------------
    Matrix<double> QN, UN, RN, TN, AN, WN;
    Matrix<double> CN, XN;          ///< (1 x nclasses), per-class visits and system tput
    Matrix<double> DropRateJoin;    ///< quorum-Join sibling drops, Join rows only
 
    // ---- fork-join sections, (npairs x nclasses): the ldes-result "forkJoin" block ----------------------------
    /** Fork and Join node NAMES of each pair, ordered by fork node then join node; empty without a pair. */
    std::vector<std::string> fj_forks, fj_joins;
    Matrix<double> FJQLen, FJRespT, FJTput;  ///< getAvgFJ, FJQLen = FJTput * FJRespT
 
    // ---- confidence intervals and relative precision -------------------------
    Matrix<double> QNCI, UNCI, RNCI, TNCI, ANCI, WNCI;
    /**
     * `options.config.runLengthPlan`: the run length the caller would need for
     * the precision they asked for, from the half-widths above. Empty unless
     * `LdesOptions::run_length_plan_precision` is positive.
     */
    bool has_run_length_plan = false;
    sim::RunLengthPlan<double> run_length_plan;
    Matrix<double> QNRelPrec, UNRelPrec, RNRelPrec, TNRelPrec;
    Matrix<double> QNSamples, UNSamples, RNSamples, TNSamples;
 
    // ---- finite capacity regions, (nregions x nclasses) ----------------------
    Matrix<double> QNfcr, UNfcr, RNfcr, TNfcr, ANfcr, WNfcr;
    Matrix<double> WeightNfcr, MemOccNfcr, DropRateNfcr;
 
    // ---- impatience, (nstations x nclasses) ----------------------------------
    Matrix<double> renegedCustomers, avgRenegingWaitTime, renegingRate;
    Matrix<double> balkedCustomers, balkingProbability;
    Matrix<double> retriedCustomers, retrialDropped, avgOrbitSize;
 
    /** Per-cache metrics, keyed by the Cache NODE name. */
    std::map<std::string, LdesCacheMetrics> cache_metrics;
 
    /**
     * The exact joint-state residence-time histogram (--export-histogram).
     *
     * `histogram_space` is (nstates x nstations*nclasses) in the aggregate
     * layout `ctmc_state_space_aggr` builds and `histogram_time` the residence
     * time of each row, so E[r] = sum_s (t_s / sum t) r(state_s) is exact also
     * for a NONLINEAR reward. `traj_*` is the same encoding along the sampled
     * path, downsampled, and is what the transient reward reads.
     */
    Matrix<double> histogram_space;
    Matrix<double> histogram_time;
    Matrix<double> traj_space;
    Matrix<double> traj_time;
 
    /**
     * One measured busy period target (--busyperiod): a station, a
     * station-class pair, or a declared station set. `mean` and `count` are
     * indexed by order 1..K, and a mean whose count is zero is not an
     * observation. `job_class` is -1 when the target aggregates every class.
     */
    struct BusyPeriodTarget {
        std::string name;
        std::vector<std::size_t> stations;  ///< station indexes, zero-based
        int job_class = -1;
        std::vector<double> mean;
        std::vector<double> count;
    };
    std::vector<BusyPeriodTarget> busy_periods;
 
    // ---- transient trajectory (--timespan + --trajectory) --------------------
    std::vector<double> t;  ///< the time vector, empty on a steady-state run
    /**
     * [STATION][class] -> (npoints x 2), columns [value, time].
     *
     * THE OUTER INDEX IS THE STATION, not the stateful node: the engine builds
     * these as `result.QNt = new Matrix[numStations][numClasses]` and fills them
     * at `serviceStation` (`Solver_ssj.getTransientLDESResultBody`). The two
     * index spaces coincide only when every stateful node is a station, so on a
     * model holding a Router, a Cache or a Place the stateful index selects
     * another station's series or runs off the end. That is the defect recorded
     * as BUG-95 and fixed in the MATLAB and Python clients.
     *
     * THE VALUES ARE INTERVAL TIME-AVERAGES, not the integer states the path
     * visits: each entry is (integral of the queue length over the sampling
     * interval) / (interval length). They are a trajectory of MEANS, so they
     * must not be compared against a state to estimate a probability -- use
     * `histogram_space` / `histogram_time` for that.
     */
    std::vector<std::vector<Matrix<double>>> QNt, UNt, TNt;
    /** [station][class] -> the per-job response times the engine recorded. */
    std::vector<std::vector<std::vector<double>>> respTimeSamples;
 
    // ---- provenance -----------------------------------------------------------
    std::string method = "default";
    double runtime = 0.0;
    bool converged = false;
    /** convergence | max_events | max_sim_events | max_time. */
    std::string stopping_reason;
    /// ldes-result "warnings": what the engine warned on its own console, e.g. a
    /// parallel pool that timed out and averaged fewer replications than requested
    std::vector<std::string> warnings;
    long convergence_batches = 0;
    long long total_simulated_events = 0;
    /** True when the HARD subprocess bound fired, not the cooperative one. */
    bool timed_out = false;
    /** "native" or "jar": which runner produced these numbers. */
    std::string engine;
};
 
}  // namespace ldes
}  // namespace line
 
#endif  // LINE_SOLVERS_WRAPPERS_LDES_LDES_OPTIONS_H