line::env Namespace Reference

Classes
struct	CacheBlendResult
	A mean-field solve, with the compression that produced it. More...
struct	EnvAnalyzerSolution
	What the ENV entry reports: the environment-blended metrics, and the whole result of whichever coupling produced them. More...
struct	EnvArc
	One arc of the environment process. More...
struct	EnvCompression
	Everything applyCompression computes, plus the compressed environment. More...
struct	EnvCompressOptions
	The knobs applyCompression reads out of options.config. More...
struct	EnvDecomp
	What SolverENV.ctmc_decompose returns: [p, eps, epsMax, q]. More...
class	Environment
struct	EnvLimitSolution
	What a limit solve reports. More...
struct	EnvMeanfieldSolution
struct	EnvOptions
	Options of SolverENV. More...
struct	EnvSolution
	What SolverENV reports. More...
struct	EnvStage
	One stage: a name, a category, and the model in force while it lasts. More...
struct	EnvStatevecOptions
	Options of the state-vector coupling. More...
struct	EnvStatevecSolution
	What the state-vector coupling reports. More...
struct	NodeFailure
	Environment.nodeFailures{k}: the declarative record of one node breakdown. More...
class	SolverEnv
	The environment solver. More...
class	SolverEnvLimit
	The limit solver. More...
class	SolverEnvStatevec
	The state-vector environment solver. More...

Typedefs
using	ResetMarginal = std::function<Matrix<double>(const Matrix<double>&)>
	The reset policy of a transition, resetFun in the reference.
template<class T>
using	ResetEnvRates
	resetEnvRatesFun in the reference: the state-dependent environment rate.
using	MacroPartition = std::vector<std::vector<std::size_t>>
	A partition of the stage indices 0..E-1 into macro-states, MATLAB's MS.
template<class T>
using	ResetStateVec = std::function<std::vector<T>(const std::vector<T>&)>
	resetStateFun{h,e} of the reference: the state distribution of stage h at the h -> e switch, mapped onto the state space of stage e.

Functions
ResetMarginal	env_reset_policy (const std::string &name)
	The two NAMED reset policies of Environment.resolveResetPolicy, which are the only ones the JSON interchange can carry (a function handle is written as custom and warned about by both writers, never reloaded).
template<class T>
qn::NetworkStruct< T >	env_degraded_model (const qn::NetworkStruct< T > &base, const std::string &node_name, const lang::Distrib< T > &down_service)
	The DOWN stage network of addNodeBreakdown: the base network with ONE node's service replaced by its degraded distribution, for EVERY class.
std::vector< std::string >	env_list_valid_methods ()
	Port of SolverENV.listValidMethods.
void	env_check_method (const std::string &method)
	Port of runAnalyzerChecks' method gate: an unlisted method is refused.
template<class T>
EnvAnalyzerSolution< T >	solver_env (Environment< T > &e, const EnvOptions &o)
	SolverENV.init's analyzer selection: solve the environment with the coupling o.method names.
template<class T>
EnvAnalyzerSolution< T >	solver_env (Environment< T > &e, const EnvOptions &o, const EnvCompressOptions &c)
	The same, on a COMPRESSED environment: aggregate the stages first, then run the coupling over the macro-states.
ln::LnOptions	env_default_lqn_options ()
	LnOptions as a LAYERED environment stage is solved with.
template<class T>
EnvLimitSolution	solver_env_limit (Environment< T > &e, const EnvOptions &o)
	solveEnvLimit on the original stages.
template<class T>
EnvDecomp< T >	env_ctmc_decompose (const Matrix< T > &Q, const MacroPartition &MS, const EnvCompressOptions &opt)
	Port of SolverENV.ctmc_decompose: one NCD decomposition, by whichever kernel options.config.da names.
template<class T>
Matrix< T >	env_rate_matrix (const Environment< T > &e)
	E0, the environment's rate matrix: E0(e,h) = env{e,h}.getRate().
template<class T>
MacroPartition	env_find_best_partition (const Matrix< T > &Eutil, const EnvCompressOptions &opt)
	Port of findBestPartition, the small-environment search.
template<class T>
MacroPartition	env_beam_search_partition (const Matrix< T > &Eutil, const EnvCompressOptions &opt)
	Port of beamSearchPartition, the large-environment search: repeatedly merge two blocks, keeping the beam_width cheapest partitions at each depth.
template<class T>
EnvCompression< T >	env_compress (const Environment< T > &e0, const EnvCompressOptions &opt)
	Port of applyCompression: pick a partition, decompose, and build the macro-state environment.
template<class T>
void	env_apply_macro_probabilities (Environment< T > &e, const EnvCompression< T > &c)
	probEnv = pMacro and probOrig = newEmbweight, the two quantities applyCompression overwrites on the environment.
template<class T>
EnvMeanfieldSolution< T >	solver_env_meanfield (Environment< T > &e, const EnvOptions &o)
	The mean-field solve on the original stages, with no compression.
template<class T>
EnvMeanfieldSolution< T >	solver_env_meanfield (Environment< T > &e, const EnvOptions &o, const EnvCompressOptions &c)
	The compressed mean-field solve: aggregate the environment, then run the mean-field fixed point over the macro-states.
template<class T>
EnvStatevecSolution< T >	solver_env_statevec (Environment< T > &e, const EnvStatevecOptions< T > &o)
	Solve in one call, for a caller with no use for the solver object.

Typedef Documentation

MacroPartition

using line::env::MacroPartition = std::vector<std::vector<std::size_t>>

A partition of the stage indices 0..E-1 into macro-states, MATLAB's MS.

Definition at line 100 of file solver_env_meanfield.h.

ResetEnvRates

template<class T>

using line::env::ResetEnvRates

Initial value:

 
std::function<lang::Distrib<T>(const lang::Distrib<T>&, const Matrix<double>&,
                               const Matrix<double>&, const Matrix<double>&)>

resetEnvRatesFun in the reference: the state-dependent environment rate.

It is given the arc's CURRENT transition distribution and the exit metrics of the stage the arc leaves – mean queue lengths, utilizations and throughputs, averaged over when that arc fires – and returns the distribution the arc should carry next. It is what makes the environment process depend on the network it modulates, and method = "statedep" is what applies it.

Definition at line 173 of file environment.h.

ResetMarginal

using line::env::ResetMarginal = std::function<Matrix<double>(const Matrix<double>&)>

The reset policy of a transition, resetFun in the reference.

It maps the mean queue lengths at the moment of the switch onto the mean queue lengths the next stage starts from. Identity means the jobs are simply carried over; zero means the buffer is flushed on the switch.

Definition at line 84 of file environment.h.

ResetStateVec

template<class T>

using line::env::ResetStateVec = std::function<std::vector<T>(const std::vector<T>&)>

resetStateFun{h,e} of the reference: the state distribution of stage h at the h -> e switch, mapped onto the state space of stage e.

This is NOT ResetMarginal, which acts on the (nstations x nclasses) mean queue lengths the mean-field coupling carries. The two coexist because the couplings carry different objects, and a policy expressed on means has no canonical lift to a joint distribution.

Definition at line 118 of file solver_env_statevec.h.

Function Documentation

env_apply_macro_probabilities()

template<class T>

void line::env::env_apply_macro_probabilities	(	Environment< T > &	e,
		const EnvCompression< T > &	c )

probEnv = pMacro and probOrig = newEmbweight, the two quantities applyCompression overwrites on the environment.

ORDER MATTERS: SolverEnv<T>'s constructor calls Environment::init(), which recomputes both from the macro arcs, so this must be applied AFTER the solver is constructed and BEFORE solve() is called. solver_env_meanfield below does exactly that, and is the reason to prefer it over wiring the two calls by hand.

The two are consistent rather than contradictory: for an exponential environment Environment::init() derives probEnv as the stationary law of the macro generator, and aggregating a chain by its exact conditional distributions reproduces the block sums of the original stationary law exactly. So this overwrite replaces one estimate of the same quantity by another, and the gap between them is a second reading of the decomposition error alongside eps.

Definition at line 571 of file solver_env_meanfield.h.

References env_apply_macro_probabilities(), line::InputError::InputError(), line::env::EnvCompression< T >::MS, line::env::Environment< T >::nstages(), line::env::EnvCompression< T >::pmacro, line::env::Environment< T >::prob_env, line::env::EnvCompression< T >::prob_orig, and line::env::Environment< T >::prob_orig.

Referenced by env_apply_macro_probabilities(), solver_env(), and solver_env_meanfield().

env_beam_search_partition()

template<class T>

MacroPartition line::env::env_beam_search_partition	(	const Matrix< T > &	Eutil,
		const EnvCompressOptions &	opt )

Port of beamSearchPartition, the large-environment search: repeatedly merge two blocks, keeping the beam_width cheapest partitions at each depth.

THE COST AND THE INCUMBENT ARE NOT THE SAME QUANTITY, in the reference. The incumbent bestEps is seeded with the raw eps of the singleton partition, and thereafter compared against childEps - childEpsMax + alpha * depth, which is a penalized score and not an eps at all. A merge is therefore adopted partly on the strength of its epsMAX and of how deep it sits, against a threshold that measured neither. This is ported literally rather than repaired: the search is a heuristic whose output is checked afterwards against eps <= epsMAX, so the comparison decides which candidate is tried and not whether the result is admissible.

Definition at line 328 of file solver_env_meanfield.h.

References env_beam_search_partition(), env_ctmc_decompose(), line::env::EnvDecomp< T >::eps, line::env::EnvDecomp< T >::epsMAX, and line::Matrix< T >::rows().

Referenced by env_beam_search_partition(), and env_compress().

env_check_method()

void line::env::env_check_method ( const std::string & method )

inline

Port of runAnalyzerChecks' method gate: an unlisted method is refused.

Definition at line 227 of file env_dispatch.h.

References env_check_method(), env_list_valid_methods(), and line::UnsupportedError::UnsupportedError().

Referenced by env_check_method().

env_compress()

template<class T>

EnvCompression< T > line::env::env_compress	(	const Environment< T > &	e0,
		const EnvCompressOptions &	opt )

Port of applyCompression: pick a partition, decompose, and build the macro-state environment.

WHY THE MACRO SERVICE RATES ARE A pmicro-WEIGHTED AVERAGE. Within a macro-state the environment switches fast compared with the network, so the network sees the group's rates averaged over the CONDITIONAL distribution of being in each micro-stage given the group – which is exactly pmicro. That average is over rates and not over distributions, so a phase-type service collapses to an exponential of the same mean: the compression keeps the first moment and discards the SCV, as the reference's Exp(rateSum) does.

Definition at line 401 of file solver_env_meanfield.h.

References line::env::Environment< T >::arc(), line::env::EnvCompression< T >::compressible, line::mc::ctmc_makeinfgen(), line::lang::Delay, line::env::EnvCompression< T >::E0, line::env::EnvCompression< T >::env, env_beam_search_partition(), env_compress(), env_ctmc_decompose(), env_find_best_partition(), env_rate_matrix(), line::env::EnvCompression< T >::eps, line::env::EnvDecomp< T >::eps, line::env::EnvCompression< T >::epsMAX, line::env::EnvDecomp< T >::epsMAX, line::env::EnvCompression< T >::Eutil, line::lang::EXP, line::lang::Distrib< T >::exp_rate(), line::InputError::InputError(), line::env::EnvCompression< T >::macro_rate, line::Matrix< T >::Matrix(), line::env::EnvCompression< T >::MS, line::env::Environment< T >::name(), line::env::Environment< T >::nstages(), line::env::EnvCompression< T >::p, line::env::EnvDecomp< T >::p, line::env::EnvCompression< T >::pmacro, line::env::EnvCompression< T >::pmicro, line::env::EnvCompression< T >::prob_orig, line::env::EnvCompression< T >::q, line::env::EnvDecomp< T >::q, line::lang::Queue, line::env::Environment< T >::reject_lqn_stages(), line::env::Environment< T >::stage(), and line::UnsupportedError::UnsupportedError().

Referenced by env_compress(), solver_env(), and solver_env_meanfield().

env_ctmc_decompose()

template<class T>

EnvDecomp< T > line::env::env_ctmc_decompose	(	const Matrix< T > &	Q,
		const MacroPartition &	MS,
		const EnvCompressOptions &	opt )

Port of SolverENV.ctmc_decompose: one NCD decomposition, by whichever kernel options.config.da names.

The uniformization rate the three iterative kernels report is the reference's 1.05 * max(max(abs(Q))) rather than anything the kernel itself derived, which is why it is recomputed here instead of read back off the result.

Definition at line 204 of file solver_env_meanfield.h.

References line::Matrix< T >::cols(), line::mc::ctmc_courtois(), line::mc::ctmc_kms(), line::mc::ctmc_multi(), line::mc::ctmc_takahashi(), env_ctmc_decompose(), line::env::EnvDecomp< T >::eps, line::mc::CourtoisResult< T >::eps, line::mc::KmsResult< T >::eps, line::mc::MultiResult< T >::eps, line::mc::TakahashiResult< T >::eps, line::env::EnvDecomp< T >::epsMAX, line::mc::CourtoisResult< T >::epsMAX, line::mc::KmsResult< T >::epsMAX, line::mc::MultiResult< T >::epsMAX, line::mc::TakahashiResult< T >::epsMAX, line::num_abs(), line::env::EnvDecomp< T >::p, line::mc::CourtoisResult< T >::p, line::mc::KmsResult< T >::p, line::mc::MultiResult< T >::p, line::mc::TakahashiResult< T >::p, line::env::EnvDecomp< T >::q, line::mc::CourtoisResult< T >::q, line::Matrix< T >::rows(), and line::UnsupportedError::UnsupportedError().

Referenced by env_beam_search_partition(), env_compress(), env_ctmc_decompose(), and env_find_best_partition().

env_default_lqn_options()

ln::LnOptions line::env::env_default_lqn_options ( )

inline

LnOptions as a LAYERED environment stage is solved with.

Only the layer engine differs from the SolverLN default, and it differs because the mean-field coupling has no use for a stage it cannot integrate: see EnvOptions::lqn.

Definition at line 103 of file solver_env.h.

References env_default_lqn_options(), and line::ln::LnOptions::layer_solver.

Referenced by env_default_lqn_options().

env_degraded_model()

template<class T>

qn::NetworkStruct< T > line::env::env_degraded_model	(	const qn::NetworkStruct< T > &	base,
		const std::string &	node_name,
		const lang::Distrib< T > &	down_service )

The DOWN stage network of addNodeBreakdown: the base network with ONE node's service replaced by its degraded distribution, for EVERY class.

Every class, and not only the ones that were enabled there, is what the reference does (for c = 1:length(classes), nodes{nodeIdx}.setService(...)), so a class that was disabled at the node while it was up is served at the degraded rate while it is down. The whole refresh chain is rerun afterwards because rates, scv and the chain-derived tables are all read off the service table; editing the table alone would leave the struct describing the UP stage and the solver reading the DOWN one.

Definition at line 199 of file environment.h.

References line::lang::dist_refresh_moments(), env_degraded_model(), line::InputError::InputError(), line::lang::Distrib< T >::is_prior(), and line::lang::prior_refresh_moments().

Referenced by line::env::Environment< T >::add_node_breakdown(), and env_degraded_model().

env_find_best_partition()

template<class T>

MacroPartition line::env::env_find_best_partition	(	const Matrix< T > &	Eutil,
		const EnvCompressOptions &	opt )

Port of findBestPartition, the small-environment search.

ITS COMMENT CLAIMS AN EXHAUSTIVE SEARCH OVER ALL PARTITIONS AND THE CODE DOES NOT DO THAT. It evaluates the singletons and then every single pairwise merge of them, so it explores E(E-1)/2 + 1 partitions out of the Bell number of them and can never return a macro-state of more than two stages. The port is literal, because the alternative is a different method wearing the reference's name; a caller who wants deeper merging has beam_above_stages and EnvCompressOptions::partition.

Definition at line 292 of file solver_env_meanfield.h.

References env_ctmc_decompose(), env_find_best_partition(), line::env::EnvDecomp< T >::eps, and line::Matrix< T >::rows().

Referenced by env_compress(), and env_find_best_partition().

env_list_valid_methods()

std::vector< std::string > line::env::env_list_valid_methods ( )

inline

Port of SolverENV.listValidMethods.

Every name here selects a COUPLING – what crosses an environment switch – and each is dispatched by this file or by SolverEnv's own ladder: default/meanfield carry the marginal means, statevec/blend the whole joint distribution, smp lifts the Markovian-arc check for a semi-Markov environment, statedep makes the transition depend on the state it leaves, and avg/dec are the closed-form fast/slow limits of solveEnvLimit.

default is the reference's spelling and meanfield this port's; both name the mean-field coupling and SolverEnv::init accepts either.

Definition at line 222 of file env_dispatch.h.

References env_list_valid_methods().

Referenced by env_check_method(), and env_list_valid_methods().

env_rate_matrix()

template<class T>

Matrix< T > line::env::env_rate_matrix

(

const Environment< T > &

e

)

E0, the environment's rate matrix: E0(e,h) = env{e,h}.getRate().

getRate() is the RECIPROCAL MEAN of the transition, so a general Markovian arc collapses to a single rate here and everything downstream treats the environment as a CTMC. That is the reference's own reading and it is why env_compress refuses a non-exponential environment by name: the collapse is harmless for the NCD diagnostics, which only ever look at Eutil, but it is not harmless once the macro arcs are rebuilt from it.

Definition at line 271 of file solver_env_meanfield.h.

References line::env::Environment< T >::arc(), env_rate_matrix(), and line::env::Environment< T >::nstages().

Referenced by env_compress(), and env_rate_matrix().

env_reset_policy()

ResetMarginal line::env::env_reset_policy ( const std::string & name )

inline

The two NAMED reset policies of Environment.resolveResetPolicy, which are the only ones the JSON interchange can carry (a function handle is written as custom and warned about by both writers, never reloaded).

keep resolves to the EMPTY function rather than to an explicit identity, because empty is how this port spells identity everywhere a reset is read: SolverEnv::post skips the call, and the compression's macro-arc fold compares resets only by whether one is PRESENT, so an explicit identity on one arc and nothing on another would be refused as a disagreement although the two mean the same thing.

Definition at line 98 of file environment.h.

References env_reset_policy(), and line::InputError::InputError().

Referenced by line::env::Environment< T >::add_node_breakdown(), line::env::Environment< T >::add_node_repair(), env_reset_policy(), and line::env::Environment< T >::register_node_failure().

solver_env() [1/2]

template<class T>

EnvAnalyzerSolution< T > line::env::solver_env	(	Environment< T > &	e,
		const EnvOptions &	o )

SolverENV.init's analyzer selection: solve the environment with the coupling o.method names.

An unknown method is refused by SolverEnv's ladder, which is reached because everything that is not the state-vector coupling IS the mean-field one in the reference – the else of its if, not a separate case.

Definition at line 242 of file env_dispatch.h.

References line::env::EnvAnalyzerSolution< T >::limit, line::env::EnvAnalyzerSolution< T >::meanfield, line::env::EnvOptions::method, solver_env(), solver_env_limit(), solver_env_meanfield(), solver_env_statevec(), and line::env::EnvAnalyzerSolution< T >::statevec.

Referenced by solver_env(), and solver_env().

solver_env() [2/2]

template<class T>

EnvAnalyzerSolution< T > line::env::solver_env	(	Environment< T > &	e,
		const EnvOptions &	o,
		const EnvCompressOptions &	c )

The same, on a COMPRESSED environment: aggregate the stages first, then run the coupling over the macro-states.

The mean-field path delegates to solver_env_meanfield, which already owns the construct-then-apply-then-solve order that env_apply_macro_probabilities requires. The state-vector path repeats that order here rather than reaching for a wrapper of its own: SolverEnvStatevec's constructor calls Environment::init(), which recomputes probEnv and probOrig from the macro arcs, so the macro probabilities have to be written back AFTER it and BEFORE solve(), exactly as on the mean-field side.

Definition at line 272 of file env_dispatch.h.

References line::env::EnvAnalyzerSolution< T >::compressed, line::env::EnvAnalyzerSolution< T >::compression, env_apply_macro_probabilities(), env_compress(), line::env::EnvAnalyzerSolution< T >::limit, line::env::EnvAnalyzerSolution< T >::meanfield, line::env::EnvOptions::method, line::env::SolverEnvLimit< T >::solve(), line::env::SolverEnvStatevec< T >::solve(), solver_env(), solver_env_meanfield(), and line::env::EnvAnalyzerSolution< T >::statevec.

solver_env_limit()

template<class T>

EnvLimitSolution line::env::solver_env_limit	(	Environment< T > &	e,
		const EnvOptions &	o )

solveEnvLimit on the original stages.

Definition at line 254 of file solver_env_limit.h.

References line::env::SolverEnvLimit< T >::solve(), and solver_env_limit().

Referenced by solver_env(), and solver_env_limit().

solver_env_meanfield() [1/2]

template<class T>

EnvMeanfieldSolution< T > line::env::solver_env_meanfield	(	Environment< T > &	e,
		const EnvOptions &	o )

The mean-field solve on the original stages, with no compression.

Definition at line 820 of file solver_env_meanfield.h.

References line::env::EnvMeanfieldSolution< T >::avg, line::env::EnvMeanfieldSolution< T >::cache, line::env::SolverEnv< T >::solve(), and solver_env_meanfield().

Referenced by solver_env(), solver_env(), solver_env_meanfield(), and solver_env_meanfield().

solver_env_meanfield() [2/2]

template<class T>

EnvMeanfieldSolution< T > line::env::solver_env_meanfield	(	Environment< T > &	e,
		const EnvOptions &	o,
		const EnvCompressOptions &	c )

The compressed mean-field solve: aggregate the environment, then run the mean-field fixed point over the macro-states.

The compressed environment is kept alive by the returned structure, which is what SolverEnv held a reference to; reading .avg out of the result and discarding the rest is safe, but the compression it came from travels with it so that eps and epsMAX can be checked against the numbers they produced.

Definition at line 839 of file solver_env_meanfield.h.

References line::env::EnvMeanfieldSolution< T >::avg, line::env::EnvMeanfieldSolution< T >::cache, line::env::EnvMeanfieldSolution< T >::compressed, line::env::EnvMeanfieldSolution< T >::compression, env_apply_macro_probabilities(), env_compress(), line::env::SolverEnv< T >::solve(), and solver_env_meanfield().

solver_env_statevec()

template<class T>

EnvStatevecSolution< T > line::env::solver_env_statevec	(	Environment< T > &	e,
		const EnvStatevecOptions< T > &	o )

Solve in one call, for a caller with no use for the solver object.

Definition at line 775 of file solver_env_statevec.h.

References solver_env_statevec(), and line::env::SolverEnvStatevec< T >::SolverEnvStatevec().

Referenced by solver_env(), and solver_env_statevec().