Skip to main content

gamlss_bayes/
lib.rs

1#![forbid(unsafe_code)]
2//! Bayesian potential-energy wrappers kept separate from distribution families.
3//!
4//! This crate deliberately starts with one small, statistically explicit
5//! vertical slice: normalized Gaussian priors on predictor coefficients plus
6//! the summed, unpenalized compiled likelihood. It contains no sampler,
7//! autodiff backend, chain storage, or implicit conversion from fitting
8//! penalties to priors.
9
10use gamlss_core::{
11    Family, Gamlss, GamlssBlocks, ModelError, ModelWorkspace, Objective, ObservationView,
12};
13
14/// Common imports for the Bayesian vertical slice.
15pub mod prelude {
16    pub use crate::{
17        CoefficientPrior, GaussianCoefficientPrior, PosteriorPotential, WorkspacePosteriorPotential,
18    };
19}
20
21const HALF_LOG_TWO_PI: f64 = 0.918_938_533_204_672_7;
22
23/// Independent normalized Gaussian priors on predictor coefficients.
24#[derive(Debug, Clone, PartialEq)]
25pub struct GaussianCoefficientPrior {
26    means: Vec<f64>,
27    standard_deviations: Vec<f64>,
28}
29
30impl GaussianCoefficientPrior {
31    /// Creates a diagonal Gaussian prior after validating its parameters.
32    pub fn try_new(means: Vec<f64>, standard_deviations: Vec<f64>) -> Result<Self, ModelError> {
33        if means.len() != standard_deviations.len() {
34            return Err(ModelError::InvalidParameter {
35                parameter: "Gaussian prior",
36                expected: "equal mean and standard-deviation lengths",
37            });
38        }
39        if means.iter().any(|value| !value.is_finite()) {
40            return Err(ModelError::InvalidParameter {
41                parameter: "Gaussian prior mean",
42                expected: "finite",
43            });
44        }
45        if standard_deviations
46            .iter()
47            .any(|value| !value.is_finite() || *value <= 0.0)
48        {
49            return Err(ModelError::InvalidParameter {
50                parameter: "Gaussian prior standard deviation",
51                expected: "finite and positive",
52            });
53        }
54        Ok(Self {
55            means,
56            standard_deviations,
57        })
58    }
59
60    /// Creates an isotropic normalized Gaussian prior.
61    pub fn isotropic(
62        dimension: usize,
63        mean: f64,
64        standard_deviation: f64,
65    ) -> Result<Self, ModelError> {
66        Self::try_new(vec![mean; dimension], vec![standard_deviation; dimension])
67    }
68
69    /// Prior means in coefficient order.
70    #[must_use]
71    pub fn means(&self) -> &[f64] {
72        &self.means
73    }
74
75    /// Prior standard deviations in coefficient order.
76    #[must_use]
77    pub fn standard_deviations(&self) -> &[f64] {
78        &self.standard_deviations
79    }
80}
81
82impl CoefficientPrior for GaussianCoefficientPrior {
83    fn dimension(&self) -> usize {
84        self.means.len()
85    }
86
87    fn negative_log_density(&self, coefficients: &[f64]) -> f64 {
88        debug_assert_eq!(coefficients.len(), self.dimension());
89        coefficients
90            .iter()
91            .zip(&self.means)
92            .zip(&self.standard_deviations)
93            .map(|((&coefficient, &mean), &standard_deviation)| {
94                let standardized = (coefficient - mean) / standard_deviation;
95                (0.5 * standardized).mul_add(standardized, standard_deviation.ln())
96                    + HALF_LOG_TWO_PI
97            })
98            .sum()
99    }
100
101    fn add_gradient(&self, coefficients: &[f64], gradient: &mut [f64]) {
102        debug_assert_eq!(coefficients.len(), self.dimension());
103        debug_assert_eq!(gradient.len(), self.dimension());
104        for (((gradient, coefficient), mean), standard_deviation) in gradient
105            .iter_mut()
106            .zip(coefficients)
107            .zip(&self.means)
108            .zip(&self.standard_deviations)
109        {
110            *gradient += (coefficient - mean) / standard_deviation.powi(2);
111        }
112    }
113
114    fn negative_log_density_and_add_gradient(
115        &self,
116        coefficients: &[f64],
117        gradient: &mut [f64],
118    ) -> f64 {
119        debug_assert_eq!(coefficients.len(), self.dimension());
120        debug_assert_eq!(gradient.len(), self.dimension());
121        let mut value = 0.0;
122        for (((gradient, coefficient), mean), standard_deviation) in gradient
123            .iter_mut()
124            .zip(coefficients)
125            .zip(&self.means)
126            .zip(&self.standard_deviations)
127        {
128            let standardized = (coefficient - mean) / standard_deviation;
129            value += (0.5 * standardized).mul_add(standardized, standard_deviation.ln())
130                + HALF_LOG_TWO_PI;
131            *gradient += standardized / standard_deviation;
132        }
133        value
134    }
135}
136
137/// Potential energy `summed weighted NLL - log p(beta)`.
138///
139/// Local fitting penalties and [`gamlss_core::ObjectiveScale`] are ignored:
140/// the wrapper always calls the model's summed unpenalized likelihood API.
141/// Non-unit observation weights therefore have explicit power-likelihood
142/// semantics. The [`Objective`] implementation is an allocating convenience;
143/// repeated sampler or optimizer calls should use
144/// [`Self::into_workspace_objective`].
145#[derive(Debug, Clone)]
146pub struct PosteriorPotential<F, Blocks, Obs, Prior> {
147    model: Gamlss<F, Blocks, Obs>,
148    prior: Prior,
149}
150
151impl<F, Blocks, Obs, Prior> PosteriorPotential<F, Blocks, Obs, Prior>
152where
153    F: Family,
154    Blocks: GamlssBlocks<F>,
155    for<'obs> Obs: ObservationView<'obs, Observation = F::Observation<'obs>>,
156    Prior: CoefficientPrior,
157{
158    /// Creates a posterior potential whose prior covers the full beta vector.
159    pub fn try_new(model: Gamlss<F, Blocks, Obs>, prior: Prior) -> Result<Self, ModelError> {
160        if prior.dimension() != model.nparams() {
161            return Err(ModelError::InvalidParameter {
162                parameter: "coefficient prior dimension",
163                expected: "equal to compiled model parameter dimension",
164            });
165        }
166        Ok(Self { model, prior })
167    }
168
169    /// Borrow the compiled likelihood model.
170    #[must_use]
171    pub const fn model(&self) -> &Gamlss<F, Blocks, Obs> {
172        &self.model
173    }
174
175    /// Borrow the normalized coefficient prior.
176    #[must_use]
177    pub const fn prior(&self) -> &Prior {
178        &self.prior
179    }
180
181    /// Consumes the wrapper and returns its model and prior.
182    #[must_use]
183    pub fn into_parts(self) -> (Gamlss<F, Blocks, Obs>, Prior) {
184        (self.model, self.prior)
185    }
186
187    /// Converts this potential into an objective with reusable model buffers.
188    #[must_use]
189    pub fn into_workspace_objective(self) -> WorkspacePosteriorPotential<F, Blocks, Obs, Prior> {
190        let workspace = self.model.gradient_workspace();
191        WorkspacePosteriorPotential {
192            potential: self,
193            workspace,
194        }
195    }
196
197    /// Evaluates posterior potential energy for the full coefficient vector.
198    ///
199    /// # Errors
200    ///
201    /// Returns [`ModelError`] when the coefficient length is incompatible with
202    /// the compiled model.
203    pub fn try_value(&self, coefficients: &[f64]) -> Result<f64, ModelError> {
204        Ok(self.model.try_likelihood_value(coefficients)?
205            + self.prior.negative_log_density(coefficients))
206    }
207
208    /// Workspace-reusing variant of [`Self::try_value`].
209    pub fn try_value_into_workspace(
210        &self,
211        coefficients: &[f64],
212        workspace: &mut ModelWorkspace<F>,
213    ) -> Result<f64, ModelError> {
214        Ok(self
215            .model
216            .try_likelihood_value_into_workspace(coefficients, workspace)?
217            + self.prior.negative_log_density(coefficients))
218    }
219
220    /// Evaluates posterior potential energy and writes its analytical gradient.
221    ///
222    /// # Errors
223    ///
224    /// Returns [`ModelError`] when the coefficient or gradient length is
225    /// incompatible with the compiled model.
226    pub fn try_value_gradient_into(
227        &self,
228        coefficients: &[f64],
229        gradient: &mut [f64],
230    ) -> Result<f64, ModelError> {
231        let likelihood = self
232            .model
233            .try_likelihood_value_gradient_into(coefficients, gradient)?;
234        Ok(likelihood
235            + self
236                .prior
237                .negative_log_density_and_add_gradient(coefficients, gradient))
238    }
239
240    /// Evaluates posterior potential energy and gradient with reusable model buffers.
241    pub fn try_value_gradient_into_workspace(
242        &self,
243        coefficients: &[f64],
244        gradient: &mut [f64],
245        workspace: &mut ModelWorkspace<F>,
246    ) -> Result<f64, ModelError> {
247        let likelihood = self.model.try_likelihood_value_gradient_into_workspace(
248            coefficients,
249            gradient,
250            workspace,
251        )?;
252        Ok(likelihood
253            + self
254                .prior
255                .negative_log_density_and_add_gradient(coefficients, gradient))
256    }
257
258    /// Writes raw pointwise log-likelihood values for WAIC/LOO-style tooling.
259    ///
260    /// Observation weights are deliberately excluded. This is the usual input
261    /// when rows remain the pointwise units of the predictive diagnostic.
262    pub fn raw_pointwise_log_likelihood_into(
263        &self,
264        coefficients: &[f64],
265        out: &mut [f64],
266    ) -> Result<(), ModelError> {
267        self.model
268            .try_pointwise_log_likelihood_into(coefficients, out)
269    }
270
271    /// Writes power-likelihood contributions including observation weights.
272    ///
273    /// Use this variant only when the chosen diagnostic intentionally treats
274    /// weights as likelihood powers or replication counts.
275    pub fn weighted_pointwise_log_likelihood_into(
276        &self,
277        coefficients: &[f64],
278        out: &mut [f64],
279    ) -> Result<(), ModelError> {
280        self.model
281            .try_weighted_pointwise_log_likelihood_into(coefficients, out)
282    }
283
284    /// Alias for [`Self::raw_pointwise_log_likelihood_into`].
285    pub fn pointwise_log_likelihood_into(
286        &self,
287        coefficients: &[f64],
288        out: &mut [f64],
289    ) -> Result<(), ModelError> {
290        self.raw_pointwise_log_likelihood_into(coefficients, out)
291    }
292}
293
294impl<F, Blocks, Obs, Prior> Objective for PosteriorPotential<F, Blocks, Obs, Prior>
295where
296    F: Family,
297    Blocks: GamlssBlocks<F>,
298    for<'obs> Obs: ObservationView<'obs, Observation = F::Observation<'obs>>,
299    Prior: CoefficientPrior,
300{
301    type Error = ModelError;
302
303    fn dim(&self) -> usize {
304        self.model.nparams()
305    }
306
307    fn value(&mut self, coefficients: &[f64]) -> Result<f64, Self::Error> {
308        self.try_value(coefficients)
309    }
310
311    fn value_gradient(
312        &mut self,
313        coefficients: &[f64],
314        gradient: &mut [f64],
315    ) -> Result<f64, Self::Error> {
316        self.try_value_gradient_into(coefficients, gradient)
317    }
318}
319
320/// Posterior potential with reusable likelihood buffers.
321///
322/// This is the primary objective adapter for repeated HMC, VI, or optimizer
323/// evaluations. It preserves the simple beta-only posterior semantics of
324/// [`PosteriorPotential`] while avoiding a fresh model workspace per call.
325pub struct WorkspacePosteriorPotential<F: Family, Blocks, Obs, Prior> {
326    potential: PosteriorPotential<F, Blocks, Obs, Prior>,
327    workspace: ModelWorkspace<F>,
328}
329
330impl<F, Blocks, Obs, Prior> WorkspacePosteriorPotential<F, Blocks, Obs, Prior>
331where
332    F: Family,
333    Blocks: GamlssBlocks<F>,
334    for<'obs> Obs: ObservationView<'obs, Observation = F::Observation<'obs>>,
335    Prior: CoefficientPrior,
336{
337    /// Borrows the underlying posterior definition.
338    #[must_use]
339    pub const fn potential(&self) -> &PosteriorPotential<F, Blocks, Obs, Prior> {
340        &self.potential
341    }
342
343    /// Borrows the reusable likelihood workspace.
344    #[must_use]
345    pub const fn workspace(&self) -> &ModelWorkspace<F> {
346        &self.workspace
347    }
348
349    /// Borrows the reusable likelihood workspace mutably.
350    pub const fn workspace_mut(&mut self) -> &mut ModelWorkspace<F> {
351        &mut self.workspace
352    }
353
354    /// Consumes the wrapper and returns its posterior definition and workspace.
355    #[must_use]
356    pub fn into_parts(self) -> (PosteriorPotential<F, Blocks, Obs, Prior>, ModelWorkspace<F>) {
357        (self.potential, self.workspace)
358    }
359
360    /// Writes raw pointwise log-likelihood values while reusing flat buffers.
361    pub fn raw_pointwise_log_likelihood_into(
362        &mut self,
363        coefficients: &[f64],
364        out: &mut [f64],
365    ) -> Result<(), ModelError> {
366        self.potential
367            .model
368            .try_pointwise_log_likelihood_into_workspace(coefficients, out, &mut self.workspace)
369    }
370
371    /// Writes observation-weighted power-likelihood contributions while reusing buffers.
372    pub fn weighted_pointwise_log_likelihood_into(
373        &mut self,
374        coefficients: &[f64],
375        out: &mut [f64],
376    ) -> Result<(), ModelError> {
377        self.potential
378            .model
379            .try_weighted_pointwise_log_likelihood_into_workspace(
380                coefficients,
381                out,
382                &mut self.workspace,
383            )
384    }
385}
386
387impl<F, Blocks, Obs, Prior> Objective for WorkspacePosteriorPotential<F, Blocks, Obs, Prior>
388where
389    F: Family,
390    Blocks: GamlssBlocks<F>,
391    for<'obs> Obs: ObservationView<'obs, Observation = F::Observation<'obs>>,
392    Prior: CoefficientPrior,
393{
394    type Error = ModelError;
395
396    fn dim(&self) -> usize {
397        self.potential.model.nparams()
398    }
399
400    fn value(&mut self, coefficients: &[f64]) -> Result<f64, Self::Error> {
401        self.potential
402            .try_value_into_workspace(coefficients, &mut self.workspace)
403    }
404
405    fn gradient(&mut self, coefficients: &[f64], gradient: &mut [f64]) -> Result<(), Self::Error> {
406        self.value_gradient(coefficients, gradient).map(|_| ())
407    }
408
409    fn value_gradient(
410        &mut self,
411        coefficients: &[f64],
412        gradient: &mut [f64],
413    ) -> Result<f64, Self::Error> {
414        self.potential.try_value_gradient_into_workspace(
415            coefficients,
416            gradient,
417            &mut self.workspace,
418        )
419    }
420}
421
422/// A normalized prior defined with respect to the flat coefficient vector.
423pub trait CoefficientPrior {
424    /// Number of coefficients covered by this prior.
425    fn dimension(&self) -> usize;
426
427    /// Negative normalized log-density at `coefficients`.
428    ///
429    /// Callers must pass exactly [`Self::dimension`] coefficients.
430    fn negative_log_density(&self, coefficients: &[f64]) -> f64;
431
432    /// Adds the negative-log-density gradient to `gradient`.
433    ///
434    /// Both slices must have length [`Self::dimension`]. Existing gradient
435    /// entries are preserved and incremented rather than overwritten.
436    fn add_gradient(&self, coefficients: &[f64], gradient: &mut [f64]);
437
438    /// Computes the negative log-density and adds its gradient in one operation.
439    ///
440    /// The default composes the separate value and gradient operations.
441    /// Implementations can override it when both share intermediate work.
442    fn negative_log_density_and_add_gradient(
443        &self,
444        coefficients: &[f64],
445        gradient: &mut [f64],
446    ) -> f64 {
447        let value = self.negative_log_density(coefficients);
448        self.add_gradient(coefficients, gradient);
449        value
450    }
451
452    /// Checked negative log-density evaluation for direct prior use.
453    fn try_negative_log_density(&self, coefficients: &[f64]) -> Result<f64, ModelError> {
454        if coefficients.len() != self.dimension() {
455            return Err(ModelError::BetaLength {
456                expected: self.dimension(),
457                actual: coefficients.len(),
458            });
459        }
460        Ok(self.negative_log_density(coefficients))
461    }
462
463    /// Checked gradient addition for direct prior use.
464    fn try_add_gradient(
465        &self,
466        coefficients: &[f64],
467        gradient: &mut [f64],
468    ) -> Result<(), ModelError> {
469        if coefficients.len() != self.dimension() {
470            return Err(ModelError::BetaLength {
471                expected: self.dimension(),
472                actual: coefficients.len(),
473            });
474        }
475        if gradient.len() != self.dimension() {
476            return Err(ModelError::GradientLength {
477                expected: self.dimension(),
478                actual: gradient.len(),
479            });
480        }
481        self.add_gradient(coefficients, gradient);
482        Ok(())
483    }
484
485    /// Checked fused value/gradient operation for direct prior use.
486    fn try_negative_log_density_and_add_gradient(
487        &self,
488        coefficients: &[f64],
489        gradient: &mut [f64],
490    ) -> Result<f64, ModelError> {
491        if coefficients.len() != self.dimension() {
492            return Err(ModelError::BetaLength {
493                expected: self.dimension(),
494                actual: coefficients.len(),
495            });
496        }
497        if gradient.len() != self.dimension() {
498            return Err(ModelError::GradientLength {
499                expected: self.dimension(),
500                actual: gradient.len(),
501            });
502        }
503        Ok(self.negative_log_density_and_add_gradient(coefficients, gradient))
504    }
505}
506
507#[cfg(test)]
508mod tests {
509    use approx::assert_relative_eq;
510    use gamlss_core::{
511        DenseDesign, Gamlss, ModelError, Mu, NoPenalty, Objective, ParameterBlock, ParameterBlocks,
512        Sigma,
513    };
514    use gamlss_family::NormalMuSigma;
515
516    use super::{CoefficientPrior, GaussianCoefficientPrior, PosteriorPotential};
517
518    #[test]
519    fn normalized_gaussian_prior_includes_constant_and_gradient() {
520        let prior = GaussianCoefficientPrior::try_new(vec![0.0, 1.0], vec![1.0, 2.0]).unwrap();
521        let coefficients = [0.5, -1.0];
522        let mut gradient = [0.0; 2];
523        prior.add_gradient(&coefficients, &mut gradient);
524        let mut fused_gradient = [0.0; 2];
525        let fused_value = prior
526            .try_negative_log_density_and_add_gradient(&coefficients, &mut fused_gradient)
527            .unwrap();
528
529        assert_relative_eq!(gradient[0], 0.5);
530        assert_relative_eq!(gradient[1], -0.5);
531        for (actual, expected) in fused_gradient.iter().zip(gradient) {
532            assert_relative_eq!(*actual, expected);
533        }
534        let expected_value = 2.0_f64.mul_add(super::HALF_LOG_TWO_PI, 0.125 + 0.5) + 2.0_f64.ln();
535        assert_relative_eq!(prior.negative_log_density(&coefficients), expected_value);
536        assert_relative_eq!(fused_value, expected_value);
537
538        assert_eq!(
539            prior.try_negative_log_density(&[0.0]).unwrap_err(),
540            ModelError::BetaLength {
541                expected: 2,
542                actual: 1,
543            }
544        );
545        assert_eq!(
546            prior
547                .try_add_gradient(&coefficients, &mut [0.0])
548                .unwrap_err(),
549            ModelError::GradientLength {
550                expected: 2,
551                actual: 1,
552            }
553        );
554    }
555
556    #[test]
557    fn posterior_uses_summed_unpenalized_likelihood_and_matches_finite_difference() {
558        let y = [0.0, 1.0, 2.0];
559        let blocks = ParameterBlocks::new((
560            ParameterBlock::<Mu, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
561            ParameterBlock::<Sigma, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
562        ));
563        let model = Gamlss::try_new(NormalMuSigma::new(), blocks, &y).unwrap();
564        let prior = GaussianCoefficientPrior::isotropic(model.nparams(), 0.0, 2.0).unwrap();
565        let mut potential = PosteriorPotential::try_new(model, prior).unwrap();
566        let coefficients = [0.2, -0.1];
567        let mut gradient = [0.0; 2];
568        let value = potential
569            .value_gradient(&coefficients, &mut gradient)
570            .unwrap();
571
572        for index in 0..coefficients.len() {
573            let mut plus = coefficients;
574            let mut minus = coefficients;
575            plus[index] += 1.0e-6;
576            minus[index] -= 1.0e-6;
577            let finite_difference =
578                (potential.value(&plus).unwrap() - potential.value(&minus).unwrap()) / 2.0e-6;
579            assert_relative_eq!(gradient[index], finite_difference, epsilon = 1.0e-6);
580        }
581
582        let mut pointwise = [0.0; 3];
583        potential
584            .pointwise_log_likelihood_into(&coefficients, &mut pointwise)
585            .unwrap();
586        let likelihood_nll = -pointwise.iter().sum::<f64>();
587        assert_relative_eq!(
588            value,
589            likelihood_nll + potential.prior().negative_log_density(&coefficients)
590        );
591    }
592
593    #[test]
594    fn workspace_posterior_reuses_buffers_and_exposes_weighted_pointwise_values() {
595        let y = [0.0, 1.0, 2.0];
596        let weights = [2.0, 0.5, 0.0];
597        let blocks = ParameterBlocks::new((
598            ParameterBlock::<Mu, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
599            ParameterBlock::<Sigma, _, _>::linear(DenseDesign::intercept(y.len()), NoPenalty, 0),
600        ));
601        let model = Gamlss::try_new_weighted(NormalMuSigma::new(), blocks, &y, &weights).unwrap();
602        let prior = GaussianCoefficientPrior::isotropic(model.nparams(), 0.0, 2.0).unwrap();
603        let potential = PosteriorPotential::try_new(model, prior).unwrap();
604        let coefficients = [0.2, -0.1];
605        let mut expected_gradient = [0.0; 2];
606        let expected_value = potential
607            .try_value_gradient_into(&coefficients, &mut expected_gradient)
608            .unwrap();
609
610        let mut raw = [f64::NAN; 3];
611        let mut weighted = [f64::NAN; 3];
612        potential
613            .raw_pointwise_log_likelihood_into(&coefficients, &mut raw)
614            .unwrap();
615        potential
616            .weighted_pointwise_log_likelihood_into(&coefficients, &mut weighted)
617            .unwrap();
618        for ((weighted, raw), weight) in weighted.iter().zip(raw).zip(weights) {
619            assert_relative_eq!(*weighted, weight * raw);
620        }
621
622        let mut workspace_potential = potential.into_workspace_objective();
623        for _ in 0..2 {
624            let mut gradient = [f64::NAN; 2];
625            assert_relative_eq!(
626                workspace_potential
627                    .value_gradient(&coefficients, &mut gradient)
628                    .unwrap(),
629                expected_value
630            );
631            for (actual, expected) in gradient.iter().zip(expected_gradient) {
632                assert_relative_eq!(*actual, expected);
633            }
634            assert_relative_eq!(
635                workspace_potential.value(&coefficients).unwrap(),
636                expected_value
637            );
638        }
639
640        let mut workspace_weighted = [f64::NAN; 3];
641        workspace_potential
642            .weighted_pointwise_log_likelihood_into(&coefficients, &mut workspace_weighted)
643            .unwrap();
644        for (actual, expected) in workspace_weighted.iter().zip(weighted) {
645            assert_relative_eq!(*actual, expected);
646        }
647        assert_relative_eq!(
648            -weighted.iter().sum::<f64>()
649                + workspace_potential
650                    .potential()
651                    .prior()
652                    .negative_log_density(&coefficients),
653            expected_value
654        );
655    }
656}