Skip to main content

Crate tpt_math_prob_markov

Crate tpt_math_prob_markov 

Source
Expand description

Markov chain and hidden-Markov-model primitives.

Two small, dependency-light building blocks sit on top of the Rng and Distribution traits from tpt_math_prob_core:

  • MarkovChain — a finite, time-homogeneous chain: build a transition matrix, normalize it, find its stationary distribution by power iteration, and simulate trajectories from any Rng.
  • Hmm (alias HiddenMarkovModel) — a discrete hidden Markov model with Viterbi decoding, a scaled forward pass for filtering and likelihoods, and generative sampling.

Matrices are plain Vec<Vec<f64>> — row i is the outgoing distribution of state i — so models can be written out literally, and nothing here needs a linear-algebra backend. Every sampling entry point is generic over Rng, so seeding with SplitMix64 makes a whole simulation reproducible.

§Examples

A two-state chain, its stationary distribution, and a simulated walk:

use tpt_math_prob_core::SplitMix64;
use tpt_math_prob_markov::MarkovChain;

let mut chain = MarkovChain::new(2);
chain.set_transition(0, 0, 0.9);
chain.set_transition(0, 1, 0.1);
chain.set_transition(1, 0, 0.5);
chain.set_transition(1, 1, 0.5);

let pi = chain.stationary();
assert!((pi[0] - 5.0 / 6.0).abs() < 1e-9);

let mut rng = SplitMix64::seed_from_u64(42);
let path = chain.run(&mut rng, 0, 1_000);
assert_eq!(path.len(), 1_000);

Decoding a hidden sequence with Viterbi:

use tpt_math_prob_markov::Hmm;

// Hidden: 0 = healthy, 1 = fever. Observed: 0 = normal, 1 = cold, 2 = dizzy.
let model = Hmm::from_parts(
    vec![0.6, 0.4],
    vec![vec![0.7, 0.3], vec![0.4, 0.6]],
    vec![vec![0.5, 0.4, 0.1], vec![0.1, 0.3, 0.6]],
)
.unwrap();

assert_eq!(model.viterbi(&[0, 1, 2]), vec![0, 0, 1]);

§Conventions

  • States are usize indices into 0..states; observation symbols are usize indices into 0..observations.
  • Reading a probability out of range yields 0.0 instead of panicking, so partially built models stay inspectable.
  • Every operation that can fail on malformed input has a checked try_* (or validate) form returning MarkovError; the plain form either falls back to a documented default or panics on a caller mistake such as an out-of-range index.

Re-exports§

pub use chain::MarkovChain;
pub use chain::DEFAULT_STATIONARY_MAX_ITER;
pub use chain::DEFAULT_STATIONARY_TOLERANCE;
pub use error::MarkovError;
pub use hmm::HiddenMarkovModel;
pub use hmm::Hmm;
pub use tpt_math_prob_core;

Modules§

chain
Discrete-time, finite-state Markov chains.
error
The error type shared by the checked entry points of this crate.
hmm
Hidden Markov models: decoding, likelihood, and generation.

Structs§

SplitMix64
SplitMix64: a tiny, fast, deterministic 64-bit PRNG.
Standard
The standard uniform distribution over the type’s natural range.

Constants§

PROBABILITY_TOLERANCE
How far a row sum may drift from 1 before validate calls it an error.

Traits§

Distribution
A distribution that can produce samples of type T.
Rng
A source of pseudo-random bits.
Sampler
Bulk sampling for any Distribution.

Functions§

sample_categorical
Draw an index from weights, treated as relative (not necessarily normalized) probabilities.