avg_table.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_SOLVERS_AVG_TABLE_H
#define LINE_SOLVERS_AVG_TABLE_H
 
/**
 * @file
 * @ingroup line_solvers
 * @ingroup line_public
 * The result tables a solver returns.
 *
 * `AvgTable` is what Python's `getAvgTable()` returns and what this port spells
 * `avg_table()`: one row per (station, class) that carries a metric, plus the
 * per-class system columns `getAvgSysTable()` reports. The columns are the
 * reference's own -- QLen, Util, RespT, ResidT, ArvR, Tput -- and a
 * (station, class) pair with no row is a zero, not a gap.
 *
 * THESE TYPES CARRY NO SOLVER MACHINERY ON PURPOSE. The solver templates are a
 * heavy instantiation, so this header stays free of them and every example,
 * test and CLI translation unit can name a result without paying for the stack
 * that produced it; `line/solvers/solver.h` declares the solvers themselves and
 * their bodies are compiled once into `line_mp_api`.
 */
 
#include <cstddef>
#include <iosfwd>
#include <string>
#include <vector>
 
namespace line {
 
class JobClass;
class Node;
 
/** `getAvgTable`, one row per (station, class) that carries a metric. */
struct AvgTable {
    std::vector<std::string> Station, JobClass;
    std::vector<double> QLen, Util, RespT, ResidT, ArvR, Tput;
    /** `getAvgSysTable`: system response time and throughput, per class. */
    std::vector<std::string> SysClass;
    std::vector<double> SysRespT, SysTput;
    std::string solver, method;
    int iter = 0;
    bool has_lognormconst = false;
    double lognormconst = 0.0;
    /** `getAvgCacheTable`'s ListCost column; empty on a model without item sizes. */
    std::vector<double> ListCost;
    /** The reference's own warning text, empty when it did not warn. */
    std::string warning;
    /**
     * Confidence half-widths of the six metric columns, row for row; EMPTY unless
     * `SolverOptions::confint` asked for them and the engine reports them (JMT, LDES).
     */
    std::vector<double> QLenCI, UtilCI, RespTCI, ResidTCI, ArvRCI, TputCI;
    /** Whether the half-width columns are filled. */
    bool has_ci() const { return !QLenCI.empty(); }
 
    /** One cell of the table, by station and class NAME; NaN when absent. */
    double get(const std::string& column, const std::string& station,
               const std::string& jobclass) const;
    /** A complete metric column. */
    std::vector<double> column(const std::string& column) const;
 
    /** Rows whose station or class has `name`, MATLAB's one-argument `filterBy`. */
    AvgTable filter_by(const std::string& name) const;
    /** Rows at one station for one class, MATLAB's two-argument `filterBy`. */
    AvgTable filter_by(const std::string& station, const std::string& jobclass) const;
    AvgTable filter_by(const Node& node) const;
    AvgTable filter_by(const ::line::JobClass& jobclass) const;
    AvgTable filter_by(const Node& node, const ::line::JobClass& jobclass) const;
    AvgTable filter_by(const ::line::JobClass& jobclass, const Node& node) const;
 
    /** MATLAB-compatible filtering aliases, preserving C++ snake-case naming. */
    AvgTable get(const Node& node) const;
    AvgTable get(const ::line::JobClass& jobclass) const;
    AvgTable get(const Node& node, const ::line::JobClass& jobclass) const;
    AvgTable get(const ::line::JobClass& jobclass, const Node& node) const;
    AvgTable tget(const Node& node) const;
    AvgTable tget(const ::line::JobClass& jobclass) const;
    AvgTable tget(const Node& node, const ::line::JobClass& jobclass) const;
    AvgTable tget(const ::line::JobClass& jobclass, const Node& node) const;
 
    /** Direct object indexing: `table(queue, jobs)`. */
    AvgTable operator()(const Node& node) const;
    AvgTable operator()(const ::line::JobClass& jobclass) const;
    AvgTable operator()(const Node& node, const ::line::JobClass& jobclass) const;
    AvgTable operator()(const ::line::JobClass& jobclass, const Node& node) const;
 
    /** Print the labelled station-class table. */
    void print(std::ostream& out) const;
    void print() const;
    /** The number of rows the table carries. */
    std::size_t size() const { return Station.size(); }
    bool empty() const { return Station.empty(); }
};
 
std::ostream& operator<<(std::ostream& out, const AvgTable& table);
 
/**
 * `getAvgQLenTable()`, `getAvgUtilTable()`, `getAvgRespTTable()`, `getAvgTputTable()`: the Station and
 * JobClass columns of `getAvgTable` with ONE metric column, row for row, as `getAvgMetricTable.m` builds them.
 */
struct AvgMetricTable {
    std::vector<std::string> Station, JobClass;
    /** The metric's values, aligned with the rows; `metric` names the column (QLen, Util, RespT, Tput). */
    std::vector<double> Value;
    std::string metric;
    std::size_t size() const { return Station.size(); }
    bool empty() const { return Station.empty(); }
};
 
/** The one-metric view of `table`, keeping every row of it. */
inline AvgMetricTable avg_metric_view(const AvgTable& table, const std::string& metric) {
    AvgMetricTable v;
    v.Station = table.Station;
    v.JobClass = table.JobClass;
    v.Value = table.column(metric);
    v.metric = metric;
    return v;
}
 
/**
 * `getAvgSysTable()`: one row per CHAIN, the cycle time and the completing throughput at
 * the chain's reference station, as `@NetworkSolver/getAvgSysTable.m` reports them.
 */
struct AvgSysTable {
    std::vector<std::string> Chain, JobClasses;
    std::vector<double> SysRespT, SysTput;
    /** Print the chain table. */
    void print(std::ostream& out) const;
    void print() const;
    std::size_t size() const { return Chain.size(); }
    bool empty() const { return Chain.empty(); }
};
 
std::ostream& operator<<(std::ostream& out, const AvgSysTable& table);
 
/**
 * `getAvgChainTable`: the station table aggregated by CHAIN, one row per (station, chain),
 * row-major over (station, chain) and with no row filter, as `@NetworkSolver/getAvgChainTable.m`.
 */
struct AvgChainTable {
    std::vector<std::string> Station, Chain, JobClasses;
    std::vector<double> QLen, Util, RespT, ResidT, ArvR, Tput;
    /** Print the station-chain table. */
    void print(std::ostream& out) const;
    void print() const;
    std::size_t size() const { return Station.size(); }
    bool empty() const { return Station.empty(); }
};
 
std::ostream& operator<<(std::ostream& out, const AvgChainTable& table);
 
/**
 * `getAvgFJTable()`: one row per (Fork/Join pair, class) with a nonzero metric, the fork-join SECTION
 * metrics of `fjFixedPoint.m` (MVA, NC, Fluid), JMT and LDES. FJRespT is the time from the Fork to the
 * matching Join, FJTput the throughput through the pair, FJQLen the jobs inside it. Empty on a model
 * without a Fork/Join pair and for a solver that does not compute them.
 */
struct AvgFJTable {
    std::vector<std::string> Fork, Join, JobClass;
    std::vector<double> FJQLen, FJRespT, FJTput;
    /** Print the labelled pair-class table. */
    void print(std::ostream& out) const;
    void print() const;
    std::size_t size() const { return Fork.size(); }
    bool empty() const { return Fork.empty(); }
};
 
std::ostream& operator<<(std::ostream& out, const AvgFJTable& table);
 
/** `SolverBA(model, method).getBoundsTable()`. */
struct BoundsTable {
    std::vector<std::string> Station, JobClass;
    std::vector<double> Qlower, Qupper, Tlower, Tupper;
    std::string method;
};
 
/** One response-time CDF curve: `F` the CDF value, `t` the time it is reached. */
struct CdfCurve {
    std::vector<double> F, t;
};
 
/**
 * `getSymbolicSolution`: the stationary law as a function of the rate symbols.
 *
 * The entries are expression strings, not numbers, and are NOT comparable with
 * another codebase's by text: the symbol numbering x1..xE follows event
 * enumeration order and the printed normal form depends on the engine version.
 * Substitute rates and compare numbers instead.
 */
struct SymbolicSolution {
    std::vector<std::string> pi;       ///< stationary probability of each state
    std::vector<std::string> num;      ///< numerator of each entry over `den`
    std::string den = "1";             ///< common denominator of the vector
    std::vector<std::string> symbols;  ///< x1..xE, empty where an event has no positive rate
    std::vector<double> rate0;         ///< nominal value of each symbol
    std::string engine;                ///< backend that answered, e.g. "sage"
};
 
/** `getTranAvg`: the transient mean queue length per (station, class). */
struct TranAvg {
    std::vector<double> t;                    ///< the time axis
    std::vector<std::vector<double> > QNt;    ///< [step][station*class]
    std::vector<std::string> label;           ///< the (station, class) of each column
};
 
/**
 * `sampleSysAggr` / `sampleAggr`: ONE simulated trajectory, not a mean.
 *
 * It has the shape of a `TranAvg` and is deliberately a type of its own,
 * because the two must never be read for each other: `TranAvg` is E[N](t)
 * estimated over independent runs, this is a single sample path, and averaging
 * a column of `state` over `t` is a time average rather than an ensemble one.
 */
struct SamplePath {
    std::vector<double> t;                      ///< event times, ascending
    std::vector<std::vector<double> > state;    ///< [step][column]
    std::vector<std::string> label;             ///< what each column counts
};
 
}  // namespace line
 
#endif  // LINE_SOLVERS_AVG_TABLE_H