2.1 Stage A: EnvelopeCentering() for dispersion2 and RSS_Post2

rIndepNormalGammaReg calls:

centering_out = EnvelopeCentering(y, x, mu, P, offset, wt, shape, rate, Gridtype, verbose)
dispersion2 = centering_out$dispersion
RSS_Post2   = centering_out$RSS_post

In implementation terms, EnvelopeCentering(): - initializes dispersion2 from a weighted residual variance computed from lm.wfit, - iteratively refines dispersion2 using a fixed-point style loop, and - updates the Gamma parameters using the expected posterior weighted RSS.

The key output for the dispersion-aware refinement is RSS_Post2, which drives the precision-rate update inside EnvelopeOrchestrator.

2.2 Stage B: Posterior mode (bstar) and Hessian (A1)

After centering, rIndepNormalGammaReg performs posterior mode optimization using R’s optim() with: - BFGS, - supplied functions f2 and f3 (negative log-posterior and its gradient), - hessian = TRUE to obtain a Hessian estimate A1.

The mode bstar and curvature A1 are then used to standardize the model into a form suitable for envelope construction.

2.3 Stage C: Standardization (glmb_Standardize_Model)

glmb_Standardize_Model() transforms the model so that the prior mean is zero and the posterior curvature is represented in a standardized coordinate system.

In implementation terms, the code extracts: - bstar2 (standardized mode), - A (standardized Hessian / precision contribution), - x2_std, mu2_std, P2_std (standardized design and prior components), - L2Inv, L3Inv (matrices used later to back-transform sampled coefficients).

For the full theoretical and implementation details of standardization, see Chapter A05.

2.4 Stage D: EnvelopeOrchestrator() - envelope + dispersion refinement

rIndepNormalGammaReg delegates the construction of the coefficient envelope and the dispersion-aware extension to EnvelopeOrchestrator.

It passes: - standardized mode and curvature objects (bstar2, A), - standardized design/prior terms (x2_std, mu2_std, P2_std), - offsets/weights (alpha, wt), - envelope grid controls (n, Gridtype, n_envopt), - Gamma prior hyperparameters (shape, rate), - and centering outputs (RSS_Post2, plus bounds / truncation controls).

The orchestrator returns: - Env (sorted envelope object including the PLSD component), - gamma_list (tilt parameters and dispersion bounds), - UB_list (the various constants used by the sampler accept-reject test), - and additional diagnostics including low / upp.

2.5 Stage E: Delegation to rIndepNormalGammaReg_std / _parallel

After envelope construction, the code selects: - serial sampler rIndepNormalGammaReg_std(...), or - parallel sampler rIndepNormalGammaReg_std_parallel(...), based on use_parallel and n.

This is where the accept-reject loop actually executes and where iters_out is recorded.

2.6 Stage F: Back-transform and return values

The standardized samples beta_out are mapped back to the original parameterization using: - the inverse standardization transforms (L2Inv, L3Inv), - and the prior mean shift (mu).

The returned structure mirrors the expected R-level contract: - samples (coefficients and dispersion), - plus runtime / iteration diagnostics (iters_out, weight_out).

3.1 Orchestrator inputs and internal Gamma anchoring

Inside EnvelopeOrchestrator, the Gamma posterior parameters for the dispersion precision are computed from: - the prior hyperparameters (shape, rate), - and the centering output RSS_Post2.

The implementation computes: - shape2 = shape + n_w/2, - rate3 = rate + RSS_Post2/2, - and the dispersion anchor: d1_star = rate3 / (shape2 - 1).

This anchor is used to rescale weights (wt2 = wt / d1_star) when building the coefficient envelope.

3.2 Step 1: EnvelopeBuild() call (coefficient-envelope)

The orchestrator calls EnvelopeBuild(...) in C++ with: - standardized mode (bstar2), - standardized curvature / precision object (A), - standardized design/prior pieces (x2, mu2, P2), - offsets (alpha) and weight scaling (wt2), - family/link fixed to Gaussian/identity.

Implementation detail worth noting: the orchestrator uses internal policy around grid size and sorting to avoid redundant work when followed by the dispersion-aware build.

3.3 Step 2 (Deep Dive): EnvelopeDispersionBuild() - dispersion-aware extension

This subsection focuses on EnvelopeDispersionBuild() as the extension-specific computational workhorse for dispersion.

3.4 Step 3: EnvelopeSort() (component reordering)

EnvelopeOrchestrator then calls the R function EnvelopeSort(...) to reorder components based on probability mass in a way that improves simulation runtime.

The sorted envelope and associated UB constants are carried forward into the accept-reject simulation.

4.1 Precomputation (Inv_f3_precompute_disp)

Before the per-draw loop, the sampler builds a cache once:

cache = Inv_f3_precompute_disp(cbars, y, x, mu, P, alpha, wt)

This cache is reused inside the accept-reject loop so that repeated evaluations at dispersion-dependent tangency points avoid rebuilding expensive matrices.

4.2 Proposal generation (per accepted draw)

For each draw index i, the sampler repeats a while loop until the proposal is accepted:

1. Select an envelope face (component)
   • Draw an index J from the discrete distribution defined by PLSD.
2. Propose regression coefficients beta on the restricted interval
   • For each coordinate j = 1,...,p, sample from the restricted normal using the envelope bounds loglt[J, ] and logrt[J, ].
   • The restricted normal is centered using the face-specific anchoring values -cbars(J, j).
3. Propose dispersion
   • Draw dispersion from the truncated proposal using: rinvgamma_ct_safe(shape3, rate2, disp_upper, disp_lower).
4. Update dispersion-dependent tangency quantities
   • With the proposed dispersion, recompute the dispersion-adjusted tangency point(s) by calling: Inv_f3_with_disp(cache, dispersion, cbars_small).
   • Evaluate the log-likelihood at both:
     • the updated tangency point (stored as LL_New2), and
     • the candidate beta (stored as LL_Test). The likelihood evaluations use weights adjusted as wt2 = wt / dispersion.

4.3 Accept-reject test statistic

With the proposal (beta, dispersion) and the chosen face J, the sampler computes the acceptance bound via four non-negative surplus terms:

• UB1: tangent-plane style surplus using LL_New2 and the dispersion-adjusted anchoring (cbars and tangency points).
• UB2: RSS-based surplus derived from rss_face_at_disp(...) and the global/per-face RSS minima RSS_Min and UB2min[J].
• UB3A: face-specific surplus term involving lg_prob_factor[J] and the function g1_face_at_disp(...).
• UB3B: dispersion-axis correction term involving the log-tilt components and precomputed maxima.

Implementation-wise, it forms:

test1 = LL_Test - UB1
test  = test1 - (UB2 + UB3A + UB3B)
test  = test - log_U2   (where U2 ~ Uniform(0,1))
accept if test >= 0

Equivalently, since log_U2 = log(U2):

accept iff  log(U2) <= (LL_Test - UB1) - (UB2 + UB3A + UB3B).

The implementation also enforces sign constraints expected from a valid dominating envelope:

• test1 <= 0,
• UB2 >= 0 (with extra tolerance/diagnostics when UB2 is numerically tiny),
• UB3A >= 0 and UB3B >= 0.

If any sign constraint is violated, the code throws a runtime error with context to help diagnose invalid envelope constants.

4.4 Record outputs

Once accepted:

The fields below are the ones from the envelope/UB structures that directly drive the sampler: - PLSD: selects the face index J; - loglt / logrt and cbars: define the restricted normal proposal for beta (and the face-centering); - shape3, rate2, disp_lower, disp_upper: define the dispersion proposal; - RSS_Min, UB2min, lg_prob_factor, lmc1, lmc2, and related precomputed maxima: define UB1-UB3B in the acceptance test.

• beta_out[i, ] stores the accepted coefficients,
• disp_out[i] stores the accepted dispersion draw,
• iters_out[i] records how many rejection attempts were needed for that accepted draw.

5.1 What the sampler reads from Env

The sampler reads from Env: - PLSD (mixture component selection weights), - loglt / logrt (restricted normal coordinate bounds), - logP / LLconst and related constants used internally, - cbars (face gradients used to center restricted normals).

5.2 What the sampler reads from gamma_list / UB_list

The sampler reads from:

• gamma_list:
  • shape3 / rate2 parameters,
  • disp_lower / disp_upper truncation parameters on the dispersion proposal.
• UB_list:
  • RSS_Min,
  • UB2min,
  • and the global constants used for computing UB3A and UB3B,
  • plus diagnostic maxima used in these corrections.

This is the key interface that ensures the dispersion-aware envelope dominates the target on the allowed truncation domain.

6.1 Tuning parameters

Key arguments affecting the internal workflow: - n (number of iid draws) - affects how often sorting / envelope sizing is amortized, - Gridtype and n_envopt - controls envelope grid complexity, - use_parallel and use_opencl - controls whether the sampling and/or envelope evaluation is parallelized / accelerated, - max_disp_perc and optional disp_lower / disp_upper - controls truncation interval tightness.

6.2 Interpreting iters_out

The vector iters_out captures the number of accept-reject attempts per accepted draw. Large values indicate a loose envelope (or expensive bounds), while values near 1 suggest a tight envelope and efficient acceptance.

6.3 Minimal examples

For runnable examples that exercise the envelope construction and sampler path, see: - Chapter A07 (independent Normal-Gamma extension theory), - Chapter A05 (fixed-dispersion envelope build), - and the inst/examples/ directory for end-to-end usage patterns.