api.da

da_cacheqn_itemprob(cacheinfo, ci)

ITEMPROB = DA_CACHEQN_ITEMPROB(CACHEINFO, CI)

Per-item occupancy [nitems x (lists+1)] of cache CI from the converged access factors returned by da_cacheqn; column 1 is the miss probability, columns 2..end the per-list ones. Returns [] when the cache carries no access factors.

This is the EMBEDDED (per-request) occupancy: it is the stationary law of the cache-content chain seen at request instants, which coincides with the time-stationary one only under PASTA. SolverCTMC reports the time-weighted counterpart instead.

The RR/FIFO exact recursion is skipped past 10 items and NaN reported, since an approximation of it is not a distribution; see _kb/09-ldes-and-cache.md.

da_cacheqn_retrieval(sn, netfun, options)

[RES,HITPROB,MISSPROB,DELAYEDPROB,IT,SN] = DA_CACHEQN_RETRIEVAL(SN, NETFUN, OPTIONS)

Decomposition-aggregation driver for a CLOSED integrated cache-queueing model whose Cache node has a delayed-hit retrieval system (Cache.setRetrievalSystem). Adapts da_cacheqn: the cache is relabelled as a ClassSwitch (read -> hit / miss) and the finite-population delayed-hit coalescing is made to emerge from the closed AMVA by giving the retrieval (fetch) station a load-dependent COALESCING service rate. With k would-be-miss jobs at the fetch station spanning d(k) = n_eff*(1-(1-1/n_eff)^k) distinct uncached items (n_eff = nitems - totalcapacity), the single fetch server releases a whole coalesced batch per fetch, so the job-completion rate is mu(k) = (1/F)*k/d(k), i.e. lldscaling(fetch,k) = k/d(k). The distinct-fetch (backend) throughput then saturates at 1/F and the delayed-hit fraction = would-be-miss - fetcher/X emerges from the finite population, rather than from an open-arrival closed form.

Returns the netsolve result RES, and per-cache hitprob/missprob/delayedprob (1 x nclasses on the read class), the iteration count IT and the mutated SN.

LIMITATIONS (FURTHER WORK NEEDED - EXPERIMENTAL):

hitprob/missprob are the true cache probabilities (hit = P(item cached), miss = 1 - hit) and are accurate (uniform: exact m/n; validated vs LDES). delayedprob is returned as 0: the finite-population delayed-hit FRACTION is NOT recovered analytically (it folds into miss). Deriving the exact closed-population coalescing split remains an open problem.
The coalescing THROUGHPUT benefit is captured only in DIRECTION and is UNDERSTATED: vs LDES it recovers the right sign of the throughput gain but a smaller magnitude (e.g. LN ~+21% where LDES shows ~+31%). The load-dependent lldscaling(k)=k/d(k) closure is calibrated for small closed populations (the LN sublayer regime) and drifts for large N.
Absolute LCQ throughput may carry the pre-existing LN(MVA) approximation error for backend-bottleneck models (present with or without retrieval).
Single fetch station (single-backend) only.
NO CLOSED-RETRIEVAL EXAMPLE ships in the suite: every retrieval_* example is OPEN. On a hand-built closed model this driver readily hits a reducible / singular routing and a zero read-rate denominator, so a plain closed model can return an empty or unreliable table. Treat the closed path as experimental and validate any closed model against LDES before trusting it. The counterpart is ported to Python (api/da/cacheqn_retrieval.py), the JAR (Da_cacheqn_retrieval) and C++ (cpp/include/line/api/da/ da_cacheqn_retrieval.h), which share the same caveats. Both C++ solver-level analyzers are now in as well: solver_nc_cacheqn_retrieval.h and solver_mva_cacheqn_retrieval.h, the latter wired into mvaDispatch branch 2 on the no-Source test. Verified 2026-07-29 that the closed MVA path agrees with the closed NC path to 1e-9 on the Delay->Cache->Fetch fixture, which is the check that closed the SolverMVA refusal.

da_traffic_superpos(lambda, a2)

D2 = DA_TRAFFIC_SUPERPOS(LAMBDA, A2)

Asymptotic-method superposition of independent flows with rates LAMBDA and squared coefficients of variation A2: returns the rate-weighted SCV mixture of the merged flow (Whitt’s QNA stationary-interval formula). Entries with non-finite rates are ignored.

da_fpi(iterfun, x0, options)

[X,IT,CONVERGED] = DA_FPI(ITERFUN, X0, OPTIONS)

Generic damped successive-substitution driver for decomposition- aggregation (DA) fixed-point iterations. Each call to ITERFUN performs one DA sweep: solve the isolated submodels given the current coupling iterate X, exchange flows or rates, and return the updated iterate.

ITERFUN: function handle [XNEW, XREF] = ITERFUN(X, IT) evaluating one DA: sweep from iterate X at iteration count IT. XREF is the baseline for the convergence test; return XREF = X for a standard successive-substitution test, or a mid-sweep checkpoint when the method compares against a renormalized iterate.

X0: initial iterate (any numeric array). OPTIONS: solver options struct; uses iter_max and iter_tol, plus the

optional fields config.da_damping in (0,1] (default 1, i.e. undamped), config.da_norm (function handle mapping the iterate difference to a scalar, default @(d) max(abs(d(:))); a two- argument handle is called as da_norm(xnew, xref) instead, e.g. for relative-difference tests), config.da_miniter (default 1): convergence is not tested before this sweep count, and config.da_nanstop (default false): when true, a NaN convergence measure terminates the iteration, replicating legacy while-loop drivers whose “continue while delta > tol” test exits on NaN; when false a NaN measure keeps iterating, as in legacy “break if delta < tol” drivers.

Returns the final iterate X, the number IT of sweeps executed, and a CONVERGED flag (false if the iteration stopped at iter_max).

da_cacheqn(sn, missfun, netfun, options)

[RES,HITPROB,MISSPROB,IT,SN,CACHEINFO] = DA_CACHEQN(SN, MISSFUN, NETFUN, OPTIONS)

Shared decomposition-aggregation driver for integrated cache-queueing models. Alternates between (i) the solution of each cache in isolation, given the current per-class arrival rates, and (ii) the solution of the surrounding queueing network with the caches replaced by class switches routing according to the hit/miss probabilities, until the cache arrival rates reach a fixed point (driven by da_fpi with the 1-norm).

SN: NetworkStruct; mutated in place (cache nodes relabeled as: ClassSwitch, routing and visits refreshed) and returned.
MISSFUN: MISSRATE = MISSFUN(GAMMA, M, LAMBDA_CACHE, CH) solves the: isolated cache and returns the per-class miss rates (1 x nclasses); CH is the cache node parameter struct (sn.nodeparam), e.g. to select the algorithm by replacement strategy.
NETFUN: RES = NETFUN(SN) solves the surrounding queueing network; the: returned struct must include the field XN (1 x nclasses system throughputs); all other fields are passed through to the caller.

OPTIONS: solver options struct (iter_max, iter_tol).

Returns the last NETFUN result RES, the per-cache hit/miss probabilities (length(caches) x nclasses, rows ordered as find(sn.nodetype==Cache)), the iteration count IT, the mutated SN, and CACHEINFO with the converged isolated-cache inputs per cache (fields node, gamma, m, lambda_cache, Rcost, strat) for per-item occupancy reporting.

da_cache_isolate(ch, lambda)

[GAMMA, LAMBDA_CACHE, RCOST] = DA_CACHE_ISOLATE(CH, LAMBDA)

Isolated-cache input construction for DA methods: builds the per-class, per-item, per-list arrival rates LAMBDA_CACHE and the access cost matrices RCOST from the cache node parameters CH (sn.nodeparam of the cache node) and the current class arrival rates LAMBDA (1 x nclasses), then computes the access factors GAMMA via cache_gamma_lp.