tensorlogic-quantrs-hooks 0.1.0

Probabilistic graphical model and message-passing interoperability for QuantRS2
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

//! Variational Message Passing (VMP) for conjugate exponential families.
//!
//! This module implements the algorithm of Winn & Bishop (2005) for the three
//! families shipped in the v0.2.0 research preview — Gaussian (mean-unknown,
//! precision-known), Categorical, and Dirichlet — along with their conjugate
//! factor relationships (Gaussian observation, Gaussian step, Dirichlet-Categorical,
//! Categorical observation).
//!
//! All updates happen in natural-parameter space. The engine drives a
//! coordinate-ascent loop that monotonically increases the evidence lower bound
//! (ELBO) until either |ΔELBO| or the L∞ residual of the natural-parameter
//! vectors falls below the configured tolerance. Divergence (an ELBO decrease
//! beyond `divergence_tolerance`) surfaces as a [`crate::PgmError::ConvergenceFailure`]
//! so a numerically broken run never silently returns a garbage posterior.
//!
//! # Module map
//!
//! | Submodule             | Purpose                                                    |
//! |-----------------------|------------------------------------------------------------|
//! | [`exponential_family`]| Trait contract every VMP-compatible distribution satisfies |
//! | [`distributions`]     | `GaussianNP`, `CategoricalNP`, `DirichletNP` + KL helpers  |
//! | [`messages`]          | `VmpMessage` / `MessageDirection` primitives               |
//! | [`engine`]            | `VmpConfig` + `VariationalMessagePassing` coordinate engine|
//! | [`special`]           | Local `ln_gamma` / `digamma` (scirs2-core free)            |
//!
//! # Minimal example
//!
//! ```
//! use tensorlogic_quantrs_hooks::vmp::{
//!     VariationalMessagePassing, VmpConfig, VmpFactor,
//! };
//!
//! // y ~ N(μ, 1) with one observation y = 3, prior μ ~ N(0, 1).
//! let config = VmpConfig::new()
//!     .with_gaussian("mu", 0.0, 1.0).expect("register mu")
//!     .with_factor(VmpFactor::GaussianObservation {
//!         target: "mu".to_string(),
//!         observation: 3.0,
//!         precision: 1.0,
//!     })
//!     .with_limits(50, 1e-8);
//!
//! let mut engine = VariationalMessagePassing::new(config).expect("engine");
//! let result = engine.run().expect("run");
//! assert!(result.converged);
//! ```
//!
//! # References
//!
//! - Winn, J. M. & Bishop, C. M. (2005). *Variational Message Passing*.
//!   Journal of Machine Learning Research 6, 661-694.

pub mod beta;
pub mod distributions;
pub mod engine;
pub mod exponential_family;
pub mod gamma;
pub mod messages;
pub mod special;

#[cfg(test)]
mod tests;

pub use beta::{BetaBernoulliObservation, BetaNP};
pub use distributions::{
    categorical_kl, dirichlet_kl, gaussian_kl, gaussian_kl_fixed_precision, CategoricalNP,
    DirichletNP, GaussianNP,
};
pub use engine::{
    Family, VariationalMessagePassing, VariationalState, VmpConfig, VmpFactor, VmpResult,
};
pub use exponential_family::ExponentialFamily;
pub use gamma::{GammaNP, GammaPoissonObservation};
pub use messages::{MessageDirection, VmpMessage};