ferrotorch/distributions-parity-v1

---

  license: apache-2.0
  tags:
  - test-fixtures
  - distributions
  - pytorch
  ---

  # ferrotorch / distributions-parity-v1

  Reference fixtures for ferrotorch-distributions's parity vs
  `torch.distributions`, generated under `torch.manual_seed(42)`
  with `N=10000` samples per config plus fixed test points
  for log_prob / entropy / KL divergence.

  Phase G.1 of real-artifact-driven development (#1167). Companion
  to:
    * `scripts/pin_pretrained_distributions_fixtures.py` (this pin)
    * `scripts/verify_distributions_inference.py` (the harness)
    * `ferrotorch-distributions/examples/distributions_dump.rs`
    * `ferrotorch-distributions/tests/conformance_torch_parity.rs`

  ## Why moment-based sample comparison

  ferrotorch's tensor PRNG (`ferrotorch_core::creation::rand` /
  `randn`) is a time-seeded xorshift, not `torch.Generator`'s
  Philox. Sample sequences cannot byte-match across the two PRNGs.
  The harness therefore compares *sample moments* (mean, variance)
  with a Monte-Carlo noise budget at N=10000:
    * sample mean: max_abs <= 0.05
    * sample var:  max_abs <= 0.1
  Analytic outputs (`log_prob`, `entropy`, KL) are deterministic
  and use tight tolerances (max_abs <= 1e-4).

  ## Configurations

  ### Distributions
    * `normal_standard` — `Normal(loc=0.0, scale=1.0)`

• normal_shifted — Normal(loc=2.0, scale=0.5)

• beta_25 — Beta(concentration1=2.0, concentration0=5.0)

• gamma_21 — Gamma(concentration=2.0, rate=1.0)

• cauchy_standard — Cauchy(loc=0.0, scale=1.0)

• exponential_1p5 — Exponential(rate=1.5)

• uniform_neg2_3 — Uniform(low=-2.0, high=3.0)

• lognormal_0_p5 — LogNormal(loc=0.0, scale=0.5)

• laplace_0_1 — Laplace(loc=0.0, scale=1.0)

• halfnormal_1 — HalfNormal(scale=1.0)

• studentt_df5 — StudentT(df=5.0, loc=0.0, scale=1.0)

• bernoulli_p3 — Bernoulli(probs=0.3)

• poisson_3 — Poisson(rate=3.0)

• categorical_k4 — Categorical(probs=[0.1, 0.3, 0.4, 0.2])

• dirichlet_k4 — Dirichlet(concentration=[1.0, 2.0, 3.0, 4.0])

• mvn_3d — MultivariateNormal(loc=[0.0, 0.0, 0.0], covariance_matrix=[[1.0, 0.5, 0.2], [0.5, 1.0, 0.3], [0.2, 0.3, 1.0]])

• multinomial_k3_n20 — Multinomial(total_count=20, probs=[0.2, 0.3, 0.5])

  ### KL pairs
    * `kl_normal_normal` — KL = `0.443147`
  

• kl_bernoulli_bernoulli — KL = 0.082283

• kl_uniform_uniform — KL = 0.693147

• kl_categorical_categorical — KL = 0.106440

• kl_laplace_laplace — KL = 0.246413

• kl_exponential_exponential — KL = 0.072132

• kl_gamma_gamma — KL = 0.190921

• kl_poisson_poisson — KL = 0.467523

  ## Layout
  
  One subfolder per config:
  
  ```
  <config_name>/
    params.json
    test_points.bin     # fixed test points where log_prob is evaluated
    sample.bin          # [N, *event_shape] torch reference samples
    log_prob.bin        # [M] reference log_prob at test_points
    entropy.bin         # [1 or B] reference entropy (some skip)
    ref_moments.json    # sample mean + variance of the torch sample
  ```
  
  For KL configs:
  ```
  <kl_config_name>/
    params.json
    kl.bin              # reference KL divergence
  ```
  
  ## Binary format
  
  ```
  [u32 ndim] [u32 * ndim shape] [f32 * prod(shape)]
  ```
  
  Little-endian single-tensor.
  
  ## License
  
  Apache 2.0. Synthetic fixtures generated by this repo's pin
  script; no upstream weights / data.