Struct InverseGaussian 

pub struct InverseGaussian { /* private fields */ }

Represents an Inverse Gaussian (IG) distribution.

Example Usage

// Create a new InverseGaussian instance with a seed
let mut inverse_gaussian = rand_simple::InverseGaussian::new([1192u32, 765u32, 1543u32]);
assert_eq!(format!("{inverse_gaussian}"), "IG(Mean, Shape) = IG(1, 1)");
println!(
    "Generate a random number from the standard Inverse Gaussian distribution with mean μ = 1 and shape parameter λ = 1 -> {}",
    inverse_gaussian.sample()
);

// Modify the distribution parameters
let mean: f64 = 1.5f64;
let shape: f64 = 2f64;
let result: Result<(f64, f64), &str> = inverse_gaussian.try_set_params(mean, shape);
assert_eq!(format!("{inverse_gaussian}"), "IG(Mean, Shape) = IG(1.5, 2)");
println!(
    "Generate a random number from the Inverse Gaussian distribution with mean μ = {}, shape λ = {} -> {}",
    mean, shape, inverse_gaussian.sample()
);

Implementations

impl InverseGaussian

pub fn new(seeds: [u32; 3]) -> Self

Constructs a new InverseGaussian instance.

Parameters

• seeds: An array of three u32 values used to initialize the random number generator states. To ensure good randomness and avoid duplicate seeds, the constructor internally adjusts these values.

Notes

• The mean parameter is initialized to 1.0.
• The shape parameter is initialized to 1.0.
• Internal state variables (xyzuv_u, xyzuv_hn_0, xyzuv_hn_1) are derived from the adjusted seeds.

pub fn sample(&mut self) -> f64

Generates a random number following the inverse Gaussian distribution.

Algorithm

Implements Algorithm 3.94 for generating samples from the inverse Gaussian distribution.

Steps

1. Preprocessing: Calculate intermediate values p and q based on the distribution’s parameters.
2. Generate a standard normal random variable z. If z is zero, return the mean as the result.
3. Compute candidate value x_1 based on the adjusted mean and shape parameters.
4. Acceptance-Rejection Step:
   • Generate a uniform random variable u.
   • Depending on the relationship between u, x_1, and the mean, decide whether to accept x_1 or use an alternative value.
5. Return the final value as the sample.

pub fn try_set_params( &mut self, mean: f64, shape: f64, ) -> Result<(f64, f64), &str>

Updates the parameters of the inverse Gaussian random variable.

Parameters

• mean: The mean parameter (μ) of the distribution. Must be positive.
• shape: The shape parameter (λ) of the distribution. Must be positive.

Returns

• Ok((mean, shape)): If both parameters are valid, the new values are set, and they are returned as a tuple.
• Err(&str): If either parameter is invalid, an error message is returned, and the previous parameter values are retained.

Validations

• mean > 0: Ensures the mean is strictly positive. If this condition is violated, an error is returned.
• shape > 0: Ensures the shape parameter is strictly positive. If this condition is violated, an error is returned.

Example

let mut inverse_gaussian = rand_simple::InverseGaussian::new([1192u32, 765u32, 1543u32]);
assert_eq!(format!("{inverse_gaussian}"), "IG(Mean, Shape) = IG(1, 1)");

// Attempt to update with valid parameters.
let result = inverse_gaussian.try_set_params(1.5, 2.0);
assert!(result.is_ok());
assert_eq!(format!("{inverse_gaussian}"), "IG(Mean, Shape) = IG(1.5, 2)");

// Attempt to update with an invalid mean.
let result = inverse_gaussian.try_set_params(-1.0, 2.0);
assert!(result.is_err());
println!("{}", result.unwrap_err()); // Output: "平均が0以下です..."

Trait Implementations

impl Display for InverseGaussian

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formatter for displaying in functions like println! macro

• Mean
• Standard deviation