Struct MultinomialLogitLikelihood 

pub struct MultinomialLogitLikelihood {
    pub active_classes: usize,
    pub row_weights: Option<Array1<f64>>,
}

Multinomial-logit (softmax) likelihood with explicit reference class.

Conventions:

• K is the total number of classes; the linear predictor has M = K - 1 columns corresponding to the active classes. Class K - 1 is the reference class with η_{K-1} ≡ 0 (so the gauge is fixed by construction and no additional sum-to-zero projection is required at the η level).
• y is the categorical response with shape (N, K). Each row must be a point on the probability simplex (y_c ≥ 0, Σ_c y_c = 1): a one-hot indicator for hard-label classification, or a label-smoothed probability vector. The row weight w_n scales the whole row’s likelihood contribution and is independent of the row mass — it is not the row sum. Callers enforce the simplex precondition via [validate_multinomial_simplex] at every construction boundary; under it the residual gradient y_a − p_a and Fisher block p_a δ_ab − p_a p_b below are the exact derivatives of the log-likelihood Σ_c y_c log p_c.
• eta is the active linear predictor with shape (N, M = K - 1).

Softmax with baseline:

    p_a   = exp(η_a) / (1 + Σ_b exp(η_b))           for a ∈ [0, K-1)
    p_{K-1} = 1 / (1 + Σ_b exp(η_b))

Log-likelihood (rows with weight w_n, default 1.0):

    log L = Σ_n w_n · ( Σ_{a < K-1} y_{n,a} · η_{n,a} − log(1 + Σ_b exp(η_{n,b})) )
          = Σ_n w_n · Σ_{c ∈ [0, K)} y_{n,c} · log p_{n,c}

Per-row gradient w.r.t. the active η is the canonical Bernoulli/softmax residual:

    ∂ log L / ∂η_{n,a} = w_n · (y_{n,a} − p_{n,a})       for a ∈ [0, K-1)

Per-row Fisher (= observed, since logit is canonical for the multinomial) information block, shape (M, M):

    H_{n,a,b} = w_n · ( p_{n,a} · δ_{ab} − p_{n,a} · p_{n,b} )

This is the standard reference-coded multinomial-logit GLM. The dense per-row block flows through VectorLikelihood::hess_block into gam_solve::pirls::dense_block_xtwx, which builds the stacked XᵀWX in output-major coefficient ordering β = [β_0; β_1; …; β_{K-2}] with each per-class block of size (P, P).

Fields

active_classes: usize

Number of active classes M = K − 1. Cached for shape checks.

row_weights: Option<Array1<f64>>

Optional row weights (length N), or None for uniform 1.0.

Implementations

impl MultinomialLogitLikelihood

pub fn with_classes(total_classes: usize) -> Result<Self, EstimationError>

Construct from the total number of classes K ≥ 2.

pub fn with_row_weights(self, w: Array1<f64>) -> Result<Self, EstimationError>

Attach per-row weights (length N, finite and non-negative).

pub fn total_classes(&self) -> usize

Total class count K = M + 1.

pub fn softmax_with_baseline(eta_active: &[f64], out: &mut [f64])

Numerically-stable softmax with implicit reference column (η_{K-1} = 0).

Writes K probabilities into out (length M + 1). The shift uses max(0, max(eta_active)) so the reference class is included in the max and the denominator stays bounded. This is the canonical reference implementation; the FFI surface and any direct matrix-free callers route through this method rather than carrying their own softmax.

pub fn probabilities(&self, eta: ArrayView2<'_, f64>) -> Array2<f64>

Convenience: compute the full (N, K) probability matrix from (N, K-1) active linear predictor. This is the multinomial inverse link used by prediction.

Trait Implementations

impl Clone for MultinomialLogitLikelihood

fn clone(&self) -> MultinomialLogitLikelihood

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MultinomialLogitLikelihood

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl VectorLikelihood for MultinomialLogitLikelihood

fn log_lik(&self, eta: ArrayView2<'_, f64>, y: ArrayView2<'_, f64>) -> f64

log p(Y | η).

fn grad_eta( &self, eta: ArrayView2<'_, f64>, y: ArrayView2<'_, f64>, ) -> Array2<f64>

∂ log p(Y | η) / ∂ η, shape (N, M).

fn hess_diag( &self, eta: ArrayView2<'_, f64>, y: ArrayView2<'_, f64>, ) -> Array2<f64>

Diagonal of the per-row Hessian −∂² log p / ∂ η ∂ η, shape (N, M). This is the per-row block consumed by solver/arrow_schur.rs.

fn hess_block( &self, eta: ArrayView2<'_, f64>, y: ArrayView2<'_, f64>, ) -> Array3<f64>

Per-row dense Hessian block −∂² log p / ∂η_a ∂η_b, shape (N, M, M).