mam_types.h

Go to the documentation of this file.

/*
 * Copyright (c) 2012-2026, QORE Lab, Imperial College London
 * All rights reserved.
 */
#ifndef LINE_SOLVERS_MAM_MAM_TYPES_H
#define LINE_SOLVERS_MAM_MAM_TYPES_H
 
/**
 * @file
 * @ingroup line_solvers
 * The option and result types SolverMAM shares with its analyzers.
 *
 * The solution type IS `mva::MvaSolution<T>`: the MAM analyzers return the same
 * [Q,U,R,T,C,X] tuple, and `@@NetworkSolver/getAvg` applies the same
 * solver-independent metric filter afterwards, so reusing it is what keeps the
 * two runners from drifting apart.
 */
 
#include <cstddef>
#include <limits>
#include <optional>
#include <string>
 
#include "line/solvers/mva/mva_types.h"
 
namespace line {
namespace mam {
 
/** The options SolverMAM reads. Defaults are SolverOptions('MAM'). */
struct MamOptions {
    std::string method = "default";
    double tol = 1e-4;
    /** SolverOptions('MAM') lowers this from the global 1000 to 100. */
    int iter_max = 100;
    /**
     * `options.config.space_max`: the order budget of the per-station arrival
     * superposition, handed to mmap_super_safe. `dec.poisson` is exactly this
     * set to 1, which collapses every stream to marked Poisson.
     */
    std::size_t space_max = 128;
    /**
     * `options.config.preserveDet`: keep a Det service as Det so the exact
     * MAP/D/c solver can claim it, instead of Erlang-approximating it.
     *
     * EMPTY MEANS NOT GIVEN, which is the whole point of the optional. The
     * reference defaults the field only when the caller left it unset
     * (`solver_mam_analyzer.m:43-47`), and the default it picks is
     * METHOD-DEPENDENT, so a plain `= true` here is not the same thing: it
     * cannot say "on unless bgchain" and cannot let an explicit request win.
     */
    std::optional<bool> preserve_det;
    /**
     * `options.config.nonmkvorder`: the phase budget `sn_nonmarkov_toph` spends
     * replacing a non-Markovian service law. The reference default is 20.
     */
    std::size_t nonmkv_order = 20;
    /**
     * `options.config.nonmkv`: 'bernstein' (default) runs `sn_nonmarkov_toph`,
     * 'none' skips it; any other name is refused (`api::nonmkv_enabled`).
     */
    std::string nonmkv = "bernstein";
    /**
     * `options.config.phfit`: true selects the two-moment concentrated-ME fit
     * (the reference default), false the Bernstein density fit. MAM consumes a
     * matrix exponential happily, so the default stands here.
     */
    bool phfit_cme = true;
    /**
     * `options.config.num_cdf_pts`: how many points the response-time CDF is
     * evaluated at. The GLOBAL default is 200, not the 100 that
     * `solver_mam_passage_time.m`'s own fallback names -- the fallback is dead,
     * because SolverOptions always sets the field. Measured: MATLAB returns 200
     * rows for a model whose `options.config` was never touched.
     */
    std::size_t num_cdf_pts = 200;
    /**
     * `options.cutoff`: the level truncation `getProb` / `getProbMarg` use for
     * an OPEN model, where the queue length is unbounded. 0 selects the
     * reference's default of 100.
     */
    std::size_t cutoff = 0;
    /**
     * `options.config.bgstates_max`: the cap on the number of states of the
     * bgchain background chain, which enumerates the closed-class population
     * vector and so grows as nchoosek(N+Mc-1,Mc-1) per background class. 0
     * selects the default of 20000. Exceeding it is a named error, not a silent
     * degradation.
     */
    std::size_t bgstates_max = 0;
    /**
     * `options.config.bgaggr`: the number G of AGGREGATE background classes the
     * bgchain method carries, so the chain has 1 + G classes. G = 1 is the
     * classic tagged/aggregate pair and the default; G >= R-1 aggregates nothing
     * and carries every closed chain exactly. 0 selects the default of 1.
     */
    std::size_t bgaggr = 0;
    /**
     * `options.config.qbdphases_max`: the cap on the phase count of one bgchain
     * station QBD, the product (arrival order) x (environment states) x (service
     * phases). 0 selects the default of 500.
     */
    std::size_t qbdphases_max = 0;
    /**
     * `options.config.fj_accuracy`: the FJ_codes truncation C of the
     * queue-length DIFFERENCE between the two fork-join branches. Larger is
     * more accurate and costs (C + 1) m^2 ma in every matrix dimension; the
     * reference default is 100.
     */
    std::size_t fj_accuracy = 100;
    /**
     * `options.config.fj_tmode`: which route `computeT.m` takes to the T
     * matrix, 'NARE' (Riccati, the reference default) or 'Sylvester' (the
     * fixed-point iteration of Section 5.1).
     */
    std::string fj_tmode = "NARE";
    /**
     * `options.config.sync_phases`: the synchronous phase expansion of the
     * 'sync.faster' / 'sync.slower' methods. 0 (the default) solves the
     * synchronous approximation without expansion; N >= 1 splits a
     * deterministic service into N phases and tightens both bounds.
     */
    std::size_t sync_phases = 0;
    /**
     * `options.config.mapmsg_quantization`: the number of regimes the MAP/M/s+G
     * reneging analyzer quantizes the patience CDF into (solver_mam_reneging.h).
     * The reference default is 81; fewer than 2 leaves no grid and is refused.
     */
    std::size_t mapmsg_quantization = 81;
    /**
     * `options.config.timescale`: "auto", "discrete" or "continuous". "auto"
     * lets the distributions decide whether the model is slotted; the other two
     * force the reading and raise when the model does not admit it.
     */
    std::string timescale = "auto";
    /** `options.config.slotlength`: the slot in model time units. */
    double slotlength = 1.0;
    /**
     * `options.timespan`: the transient horizon. SolverOptions('MAM') defaults
     * it to [Inf, Inf], i.e. steady state only, and `runAnalyzer` treats a
     * finite upper bound as the request for a transient solve.
     */
    double timespan_start = 0.0;
    double timespan_end = std::numeric_limits<double>::infinity();
 
    /**
     * `preserve_det` with the reference's method-dependent default applied,
     * and the ONLY spelling any analyzer should read.
     *
     * 'bgchain' builds a phase-type MIXTURE of the open service laws and has
     * no deterministic-service branch at all, so a Det that survives to it
     * arrives with no (D0,D1) pair to mix. It therefore needs the Det FITTED
     * to PH, which is what `solver_mam_analyzer.m:47` says by defaulting
     * `preserveDet` to `~strcmpi(options.method,'bgchain')`. Every other
     * method wants the Det preserved so the exact MAP/D/c branch can claim it.
     *
     * The method name is compared exactly, not case-insensitively as the
     * reference's `strcmpi` does, because `check_method` has already refused
     * anything that is not one of `list_valid_methods`' lowercase names by the
     * time an analyzer reads this.
     */
    bool preserve_det_resolved() const {
        return preserve_det.value_or(method != "bgchain");
    }
};
 
/** What the MAM dispatch returns: the metrics plus the algorithm that ran. */
template <class T>
struct MamSolution {
    mva::MvaSolution<T> sol;
    /** The concrete algorithm, as the reference's `actualmethod`. */
    std::string actualmethod;
};
 
}  // namespace mam
}  // namespace line
 
#endif  // LINE_SOLVERS_MAM_MAM_TYPES_H