Merge pull request #15 from SyntaxSpirits/docs/discrete-distribution-readme

docs: document discrete distribution examples

Author: kholdrex

README.md

@@ -9,7 +9,7 @@ A comprehensive Rust library for Bayesian inference with MCMC samplers, featurin
 ## Features
 
 - **MCMC Samplers**: Metropolis-Hastings, Gibbs, and Hamiltonian Monte Carlo (HMC)
-- **Statistical Distributions**: Normal, Multivariate Normal, Gamma, Beta, Exponential, Uniform, Student's t
+- **Statistical Distributions**: Normal, Multivariate Normal, Gamma, Beta, Exponential, Uniform, Student's t, Bernoulli, Binomial, Poisson
 - **MCMC Diagnostics**: Effective sample size, R-hat statistic, MCSE summaries, autocorrelation analysis, trace plots
 - **Multi-chain workflows**: Run multiple seeded chains with a shared warmup/sample schedule
 - **Best Practices**: Comprehensive error handling, extensive testing, performance benchmarks
@@ -180,6 +180,27 @@ let x = DVector::from_vec(vec![1.0, -1.0]);
 println!("Log PDF: {}", mvn.log_pdf(&x));
 ```
 
+### Discrete Distributions
+
+Use `DiscreteDistribution` for count-valued distributions with probability mass functions and seeded sampling. `Poisson::new(lambda)` requires `lambda` to be finite, positive, and no greater than `1e12`. Add `rand = "0.8"` to your application dependencies when using the seeded sampling example.
+
+```rust
+use bayes_rs::distributions::{Bernoulli, Binomial, DiscreteDistribution, Poisson};
+use rand::{rngs::StdRng, SeedableRng};
+
+let bernoulli = Bernoulli::new(0.3)?;
+let binomial = Binomial::new(10, 0.3)?;
+let poisson = Poisson::new(2.5)?;
+
+println!("Bernoulli P(X=1): {}", bernoulli.pmf(1));
+println!("Binomial log P(X=3): {}", binomial.log_pmf(3));
+println!("Poisson P(X=2): {}", poisson.pmf(2));
+
+let mut rng = StdRng::seed_from_u64(42);
+let draw = poisson.sample(&mut rng);
+println!("Seeded Poisson draw: {}", draw);
+```
+
 ## MCMC Diagnostics
 
 Comprehensive diagnostic tools to assess convergence and sample quality:
@@ -356,6 +377,15 @@ See the `examples/` directory for complete examples:
 ```bash
 # Bayesian linear regression example
 cargo run --example linear_regression
+
+# Discrete Bernoulli, Binomial, and Poisson distributions
+cargo run --example discrete_distributions
+
+# Conjugate Bayesian model examples
+cargo run --example conjugate_models
+
+# Serde-enabled diagnostics serialization example
+cargo run --features serde --example serde_diagnostics
 ```
 
 ## Contributing