Package org.loudouncodes.randkit.discrete

Class NormalInt

java.lang.Object
org.loudouncodes.randkit.discrete.NormalInt
All Implemented Interfaces:
DiscreteDistribution
public final class NormalInt extends Object implements DiscreteDistribution
A discrete normal (rounded-normal) distribution on the integers.

This distribution is constructed by sampling a continuous normal X ~ Normal(mean, sigma^2) and returning the integer Y = round(X) (nearest-even rounding via Math.rint(double)). It therefore places probability mass on all integers (unless truncated).

Probability functions

For the untruncated rounded-normal, the probability mass function (PMF) and cumulative distribution function (CDF) are exact: 


 pmf(k) = Φ((k + 0.5 - mean)/sigma) - Φ((k - 0.5 - mean)/sigma)
 cdf(k) = Φ((k + 0.5 - mean)/sigma)
where Φ is the standard normal CDF.

For the truncated variant on [lower, upper] (inclusive), mass is re-normalized to that interval: 


 Z = Φ((upper + 0.5 - mean)/sigma) - Φ((lower - 0.5 - mean)/sigma)
 pmf_trunc(k) = pmf(k) / Z     for k in [lower, upper], else 0
 cdf_trunc(k) = (Φ((k + 0.5 - mean)/sigma) - Φ((lower - 0.5 - mean)/sigma)) / Z

Sampling

Sampling uses the Marsaglia polar (Box–Muller) method to draw a standard normal, then scales/shifts and applies nearest-even rounding. When truncated, out-of-range draws are rejected and re-sampled (efficient unless the window is deep in the tails).

Numerics

  • Φ is computed via an erf approximation (Abramowitz & Stegun 7.1.26), with max absolute error ≈ 1.5e−7.
  • Untruncated mean/variance are computed by summing the PMF over a wide ±8σ window (extended until the remaining tail mass is negligible).

Determinism & threading

Given the same seed, parameters, and JDK RNG algorithm, sequences are repeatable. Instances are not synchronized; prefer one instance per thread or supply thread-local RNGs.

Examples


 // Untruncated discrete normal centered near 2, σ = 1.5
 var d1 = new NormalInt(2.0, 1.5);
 int x = d1.sample();

 // Seeded and truncated to [-3, +3]
 var d2 = new NormalInt(1234L, 0.0, 2.0, -3, 3);
 double p0 = d2.pmf(0);      // probability at 0
 double F2 = d2.cdf(2);      // P(Y <= 2)
Since:
0.1.0

  • Constructor Summary

    Constructors
    Constructor
    Description
    NormalInt(double mean, double sigma)
    Creates an untruncated discrete normal using the library's default RNG.
    NormalInt(double mean, double sigma, int lower, int upper)
    Creates a truncated discrete normal on the closed interval [lower, upper] using the library's default RNG.
    NormalInt(long seed, double mean, double sigma)
    Creates an untruncated discrete normal with a deterministic RNG built from seed.
    NormalInt(long seed, double mean, double sigma, int lower, int upper)
    Creates a truncated discrete normal on [lower, upper] with a deterministic RNG.
    NormalInt(RandomGenerator rng, double mean, double sigma)
    Creates an untruncated discrete normal with a caller-supplied RNG.
    NormalInt(RandomGenerator rng, double mean, double sigma, int lower, int upper)
    Creates a truncated discrete normal on [lower, upper] with a caller-supplied RNG.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    cdf(int k)
    Returns the cumulative distribution function at k, i.e., P(Y ≤ k).
    double
    mean()
    Returns the distribution mean (expected value).
    double
    pmf(int k)
    Returns the probability mass at k, i.e., P(Y = k).
    int
    sample()
    Draws a single sample Y from this distribution.
    DistributionSupport
    support()
    Reports the mathematical support (domain) of this distribution.
    double
    variance()
    Returns the distribution variance.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • NormalInt

      public NormalInt(double mean, double sigma)
      Creates an untruncated discrete normal using the library's default RNG.
      Parameters:
      mean - the mean μ of the underlying continuous normal (finite)
      sigma - the standard deviation σ of the underlying normal; must be > 0
      Throws:
      IllegalArgumentException - if mean is not finite or sigma <= 0 or not finite

    • NormalInt

      public NormalInt(long seed, double mean, double sigma)
      Creates an untruncated discrete normal with a deterministic RNG built from seed.
      Parameters:
      seed - RNG seed for reproducible sampling
      mean - the mean μ of the underlying continuous normal (finite)
      sigma - the standard deviation σ of the underlying normal; must be > 0
      Throws:
      IllegalArgumentException - if mean is not finite or sigma <= 0 or not finite

    • NormalInt

      public NormalInt(RandomGenerator rng, double mean, double sigma)
      Creates an untruncated discrete normal with a caller-supplied RNG.
      Parameters:
      rng - the random generator (must not be null)
      mean - the mean μ of the underlying continuous normal (finite)
      sigma - the standard deviation σ of the underlying normal; must be > 0
      Throws:
      NullPointerException - if rng is null
      IllegalArgumentException - if mean is not finite or sigma <= 0 or not finite

    • NormalInt

      public NormalInt(double mean, double sigma, int lower, int upper)
      Creates a truncated discrete normal on the closed interval [lower, upper] using the library's default RNG. Mass is re-normalized to the interval.
      Parameters:
      mean - the mean μ of the underlying continuous normal (finite)
      sigma - the standard deviation σ of the underlying normal; must be > 0
      lower - inclusive lower bound for the integer outcomes
      upper - inclusive upper bound for the integer outcomes; must be >= lower
      Throws:
      IllegalArgumentException - if parameters are invalid or lower > upper

    • NormalInt

      public NormalInt(long seed, double mean, double sigma, int lower, int upper)
      Creates a truncated discrete normal on [lower, upper] with a deterministic RNG.
      Parameters:
      seed - RNG seed for reproducible sampling
      mean - the mean μ of the underlying continuous normal (finite)
      sigma - the standard deviation σ of the underlying normal; must be > 0
      lower - inclusive lower bound for the integer outcomes
      upper - inclusive upper bound for the integer outcomes; must be >= lower
      Throws:
      IllegalArgumentException - if parameters are invalid or lower > upper

    • NormalInt

      public NormalInt(RandomGenerator rng, double mean, double sigma, int lower, int upper)
      Creates a truncated discrete normal on [lower, upper] with a caller-supplied RNG.
      Parameters:
      rng - the random generator (must not be null)
      mean - the mean μ of the underlying continuous normal (finite)
      sigma - the standard deviation σ of the underlying normal; must be > 0
      lower - inclusive lower bound for the integer outcomes
      upper - inclusive upper bound for the integer outcomes; must be >= lower
      Throws:
      NullPointerException - if rng is null
      IllegalArgumentException - if parameters are invalid or lower > upper

  • Method Details

    • sample

      public int sample()
      Draws a single sample Y from this distribution.

      For untruncated distributions, this value can be any integer (with quickly decaying tails). For truncated distributions, the result is guaranteed to lie in [lower, upper].

      Specified by:
      sample in interface DiscreteDistribution
      Returns:
      a random integer variate

    • pmf

      public double pmf(int k)
      Returns the probability mass at k, i.e., P(Y = k).
      Specified by:
      pmf in interface DiscreteDistribution
      Parameters:
      k - integer at which to evaluate the PMF
      Returns:
      the probability mass at k (zero if truncated and k is outside the bounds)

    • cdf

      public double cdf(int k)
      Returns the cumulative distribution function at k, i.e., P(Y ≤ k).
      Specified by:
      cdf in interface DiscreteDistribution
      Parameters:
      k - integer at which to evaluate the CDF
      Returns:
      the cumulative probability at k

    • mean

      public double mean()
      Returns the distribution mean (expected value).

      For the rounded-normal, this is close to mean, with a tiny quantization effect. For the truncated variant, this is the re-normalized mean over the interval.

      Specified by:
      mean in interface DiscreteDistribution
      Returns:
      E[Y]

    • variance

      public double variance()
      Returns the distribution variance.

      For the rounded-normal, this is close to sigma^2 plus a small quantization effect. For the truncated variant, this is the re-normalized variance over the interval.

      Specified by:
      variance in interface DiscreteDistribution
      Returns:
      Var[Y]

    • support

      public DistributionSupport support()
      Reports the mathematical support (domain) of this distribution.

      For untruncated instances the support is the unbounded integer line. For truncated instances it is the closed interval [lower, upper].

      Returns:
      a DistributionSupport describing the support (discrete)