1#![forbid(unsafe_code)]
2use gamlss_core::{
11 Family, Gamlss, GamlssBlocks, ModelError, ModelWorkspace, Objective, ObservationView,
12};
13
14pub 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#[derive(Debug, Clone, PartialEq)]
25pub struct GaussianCoefficientPrior {
26 means: Vec<f64>,
27 standard_deviations: Vec<f64>,
28}
29
30impl GaussianCoefficientPrior {
31 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 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 #[must_use]
71 pub fn means(&self) -> &[f64] {
72 &self.means
73 }
74
75 #[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#[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 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 #[must_use]
171 pub const fn model(&self) -> &Gamlss<F, Blocks, Obs> {
172 &self.model
173 }
174
175 #[must_use]
177 pub const fn prior(&self) -> &Prior {
178 &self.prior
179 }
180
181 #[must_use]
183 pub fn into_parts(self) -> (Gamlss<F, Blocks, Obs>, Prior) {
184 (self.model, self.prior)
185 }
186
187 #[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 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 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 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 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 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 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 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
320pub 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 #[must_use]
339 pub const fn potential(&self) -> &PosteriorPotential<F, Blocks, Obs, Prior> {
340 &self.potential
341 }
342
343 #[must_use]
345 pub const fn workspace(&self) -> &ModelWorkspace<F> {
346 &self.workspace
347 }
348
349 pub const fn workspace_mut(&mut self) -> &mut ModelWorkspace<F> {
351 &mut self.workspace
352 }
353
354 #[must_use]
356 pub fn into_parts(self) -> (PosteriorPotential<F, Blocks, Obs, Prior>, ModelWorkspace<F>) {
357 (self.potential, self.workspace)
358 }
359
360 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 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
422pub trait CoefficientPrior {
424 fn dimension(&self) -> usize;
426
427 fn negative_log_density(&self, coefficients: &[f64]) -> f64;
431
432 fn add_gradient(&self, coefficients: &[f64], gradient: &mut [f64]);
437
438 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 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 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 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}