1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
/*
* SPDX-License-Identifier: MIT
* Copyright (c) 2023 - 2026. The DeepCausality Authors and Contributors. All Rights Reserved.
*/
//! Descriptive and information statistics over slices, generic in the scalar.
//!
//! # Why this crate exists
//!
//! Not to remove duplication. It adds more source than it removes, and says so in its own change
//! notes. It exists because shipped implementations of the same statistic disagree about what they
//! compute.
//!
//! Shannon entropy is the case that decides it. Three implementations in this workspace differ on
//! three axes at once — the base, whether the input is normalised, and where the cutoff for a
//! negligible entry sits. Two of them return answers in different units for the same input: one in
//! bits, one in nats, a factor of `ln 2` apart. That is not a rounding difference to be tidied
//! away, it is a semantic disagreement, and one parameterised function that can reproduce each is
//! the resolution.
//!
//! So the parameters here are not configurability for its own sake. Each combination named in
//! [`EntropyConfig`] has a caller in this workspace today.
//!
//! # Scope
//!
//! The crate implements only functions something calls. That rule is what keeps a new crate from
//! becoming a survey of the field, and it excludes several things a statistics library
//! conventionally carries: cross-entropy, mutual information, Kullback–Leibler divergence,
//! Jensen–Shannon divergence, the Hellinger distance and a general Bhattacharyya coefficient.
//!
//! Mutual information is the one that most invites an exception, because the causal-discovery
//! code computes information quantities. What it computes is specific mutual information and
//! information leak over marginalised tensor axes, which is not the slice-shaped general function;
//! building the general one would leave that version in place beside it. The Bhattacharyya case is
//! the same shape: the quantum crate computes the two-outcome Bernoulli coefficient in bits,
//! inline, which is not the general slice coefficient.
//!
//! Each is a short addition whenever a caller appears.
//!
//! # Why the distributions live here
//!
//! A distribution is mathematics. `Normal`, `Exponential`, `Cauchy` and the rest are defined by
//! their densities and their moments, and every one of those is a statistic — which is what this
//! crate is for. Putting them beside the densities is what makes importance sampling, sequential
//! Monte Carlo and MCMC diagnostics short to write: each needs a sampler and a density in the same
//! place, and separating them by a crate boundary is what made them long.
//!
//! The entropy crate below keeps what is genuinely entropy: generators, the raw machine word, the
//! Boolean draw, the Sobol sequence and the range sampler. It makes no claim about how a number is
//! distributed beyond "uniform over the bits", and it does not name a density anywhere. The
//! dependency runs `stats -> rand`, downhill, so nothing circles back.
//!
//! # A lazy sampler is Arrow-shaped, not witness-shaped
//!
//! A carrier that *stores* a sampling closure — draw-on-demand rather than draw-now — cannot take
//! the container traits in `deep_causality_haft`, and the reason is worth recording so it is not
//! rediscovered as a gap.
//!
//! Those traits carry no `'static` bound: zero occurrences across `Functor`, `Pure`, `Applicative`,
//! `Monad`, `Traversable` and `LaxMonoidal`. That absence is deliberate. A functor receives a
//! function, applies it and drops it, so the function never outlives the call. `Profunctor`, which
//! does store its functions, carries `'static` on every parameter.
//!
//! A stored closure needs bounds the container traits do not provide, and an implementation cannot
//! add them — `error[E0276]: impl has stricter requirements than trait`. The container traits are
//! for data. A lazy sampler is a program, and `haft`'s home for programs is the `Arrow` layer.
//!
//! An ensemble of *realised* draws has no such problem: it is a `Vec` with a witness, which
//! `CausalTensor` already is, and drawing into one is an ordinary generic function needing no
//! witness of its own.
//!
//! # Precision
//!
//! Functions are generic over their scalar under the algebra tower's bounds, with the exceptions
//! below.
//!
//! Four signatures name a concrete float. The unit coordinate of an inverse-CDF transform is `f64`
//! because it is a position on `[0, 1)` rather than a value in the caller's scalar, and rounding it
//! into a narrow scalar before the transform is destructive at the endpoints — see
//! [`standard_normal_inverse_cdf_at`]. Beside it, [`standard_normal_inverse_cdf`] and
//! [`standard_normal_inverse_cdf_f106`] are the same transform at one fixed precision each.
//! [`bernoulli_inverse_cdf`] compares an `f64` coordinate with an `f64` probability.
//!
//! Three generic paths pass through `f64` internally. [`Bernoulli::new`] lowers `p` to `f64` and
//! quantises it to a multiple of `2^-64`, and [`Bernoulli::p`] returns that value through `f64`, so
//! probability detail finer than `f64` is lost at `Float106`. [`Poisson::new`] lowers the rate to
//! `f64` only to compare it with [`MAX_RATE`]; the stored rate stays in the caller's scalar.
//! [`bernoulli_proportion`] divides in the caller's scalar when both counts are exact there, and
//! otherwise divides in `f64` and rounds the quotient once into the scalar.
//!
//! # Shape
//!
//! The surface is over slices. Anything with axes — marginalising a joint distribution, reducing a
//! tensor — belongs with the container that has them, and this crate sits below those containers
//! so they can delegate to it without a cycle.
// Unconditional, matching `deep_causality_linear`. Bazel does not read Cargo features, so a
// feature-gated `extern crate alloc` is absent under `bazel test` and every `alloc::` path in the
// crate fails to resolve.
extern crate alloc;
extern crate core;
// Test fixtures, public because Bazel test targets cannot reach the `tests` tree, hidden because
// they are not API.
pub use crate;
pub use crate;
pub use crate;
pub use crategaussian_log_density;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
pub use crateEntropyConfig;
pub use crateLogBase;
pub use crateLogisticConfig;
pub use crateLogisticFit;
pub use crateMeanAccumulator;
pub use crateNormalisation;
pub use cratePenalisation;
pub use crateRidgeConfig;
pub use crateRidgeFit;
pub use crateZeroPolicy;
// ---------------------------------------------------------------------------------------------
// Distributions
// ---------------------------------------------------------------------------------------------
//
// The mathematics of a random quantity, beside the densities that describe it. The machine words
// these consume come from `deep_causality_rand`; what they mean is a statement about a real field.
pub use crateBernoulliDistributionError;
pub use crateNormalDistributionError;
pub use crateBernoulli;
pub use crateCategorical;
pub use crateCauchy;
pub use crateExponential;
pub use crateLogNormal;
pub use crateNormal;
pub use crateStandardNormal;
pub use crate;
pub use crateUniformInt;
pub use crateStandardUniform;
pub use crateWeibull;
pub use crate;
pub use crate;
// The generator bridge, re-exported **by name** so a crate that wants only distributions needs no
// second dependency to spell the bound. Named, never a glob: a `pub use` is an alias to the same
// trait item, so a bound written against either path is satisfied by the same implementations,
// whereas a second trait of the same shape would be a different item entirely.
pub use crateRandomExt;
pub use ;