priorities 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
priorities/__init__.py ADDED
@@ -0,0 +1,47 @@
1
+ """Probability distributions as Equinox records.
2
+
3
+ A distribution gives a log density against ``d(value)``, draws, and, where it has one,
4
+ a map to and from the unit cube. The free functions ``to_real``, ``from_real``
5
+ and ``real_log_prob`` add the default transform to unconstrained coordinates.
6
+ """
7
+
8
+ try:
9
+ from priorities._version import __version__
10
+ except ImportError: # pragma: no cover - source tree without a generated version file
11
+ try:
12
+ from importlib.metadata import PackageNotFoundError, version
13
+
14
+ __version__ = version("priorities")
15
+ except PackageNotFoundError:
16
+ __version__ = "0.0.0+unknown"
17
+
18
+ from priorities._composite import Mixture, MultivariateNormal, TruncatedDistribution
19
+ from priorities._distribution import AbstractDistribution
20
+ from priorities._records import (
21
+ Beta,
22
+ HalfNormal,
23
+ LogNormal,
24
+ LogUniform,
25
+ Normal,
26
+ Rayleigh,
27
+ Uniform,
28
+ )
29
+ from priorities._transform import from_real, real_log_prob, to_real
30
+
31
+ __all__ = [
32
+ "AbstractDistribution",
33
+ "Beta",
34
+ "HalfNormal",
35
+ "LogNormal",
36
+ "LogUniform",
37
+ "Mixture",
38
+ "MultivariateNormal",
39
+ "Normal",
40
+ "Rayleigh",
41
+ "TruncatedDistribution",
42
+ "Uniform",
43
+ "__version__",
44
+ "from_real",
45
+ "real_log_prob",
46
+ "to_real",
47
+ ]
@@ -0,0 +1,257 @@
1
+ """Records built on other distributions or on one event axis."""
2
+
3
+ from typing import ClassVar
4
+
5
+ import equinox as eqx
6
+ import jax
7
+ import jax.numpy as jnp
8
+ from jax import Array
9
+ from jax.scipy.linalg import solve_triangular
10
+ from jax.scipy.special import logsumexp, ndtr, ndtri
11
+
12
+ from priorities._distribution import (
13
+ AbstractDistribution,
14
+ as_float,
15
+ debug_check,
16
+ finish,
17
+ is_valid,
18
+ quantile,
19
+ unit_draws,
20
+ )
21
+ from priorities._records import _LOG_SQRT_2PI
22
+
23
+ _BOUNDS = {
24
+ (False, False): "real",
25
+ (True, False): "lower",
26
+ (False, True): "upper",
27
+ (True, True): "interval",
28
+ }
29
+ _solve_lower = jnp.vectorize(
30
+ lambda cholesky, rhs: solve_triangular(cholesky, rhs, lower=True),
31
+ signature="(d,d),(d)->(d)",
32
+ )
33
+
34
+
35
+ def _optional(x):
36
+ return None if x is None else as_float(x)
37
+
38
+
39
+ class TruncatedDistribution(AbstractDistribution):
40
+ """A scalar distribution conditioned on ``low <= value <= high``.
41
+
42
+ Which sides are cut is static: a side left as ``None`` is not cut and adds
43
+ no leaf, so the uncut distribution keeps its own gradients and its own draw. The
44
+ support is closed at a finite cut. Cuts far in a tail lose precision,
45
+ because the normalizer is a difference of distribution-function values.
46
+
47
+ A truncated ``Beta`` is not differentiable in the Beta shapes (see
48
+ ``Beta``). Taking a gradient with respect to a pytree that holds one
49
+ raises ``ValueError`` even if those gradients are unused, so keep such a
50
+ distribution out of the differentiated partition.
51
+
52
+ Attributes:
53
+ base: Scalar distribution with an inverse CDF.
54
+ low: Lower cut, or ``None``.
55
+ high: Upper cut, or ``None``.
56
+ """
57
+
58
+ base_dist: AbstractDistribution
59
+ low: Array | None = eqx.field(default=None, converter=_optional)
60
+ high: Array | None = eqx.field(default=None, converter=_optional)
61
+ event_dim: ClassVar[int] = 0
62
+ has_icdf: ClassVar[bool] = True
63
+
64
+ def __check_init__(self):
65
+ if self.base_dist.event_dim != 0 or not self.base_dist.has_icdf:
66
+ raise ValueError(
67
+ "TruncatedDistribution needs a scalar base_dist with an inverse CDF"
68
+ )
69
+
70
+ @property
71
+ def bounds(self) -> str:
72
+ """Bounded sides of the support: those of the base plus the cuts."""
73
+ lower = self.low is not None or self.base_dist.bounds in ("lower", "interval")
74
+ upper = self.high is not None or self.base_dist.bounds in ("upper", "interval")
75
+ return _BOUNDS[lower, upper]
76
+
77
+ def _mass(self):
78
+ """Base probability below the lower cut, and between the cuts."""
79
+ below = 0.0 if self.low is None else self.base_dist.cdf(self.low)
80
+ above = 1.0 if self.high is None else self.base_dist.cdf(self.high)
81
+ return below, above - below
82
+
83
+ def support(self):
84
+ low, high = self.base_dist.support()
85
+ low = low if self.low is None else jnp.maximum(low, self.low)
86
+ high = high if self.high is None else jnp.minimum(high, self.high)
87
+ valid = self._mass()[1] > 0
88
+ low, high = (jnp.where(valid, bound, jnp.nan) for bound in (low, high))
89
+ return tuple(jnp.broadcast_arrays(low, high))
90
+
91
+ def log_prob(self, value):
92
+ low, high = self.support()
93
+ out = self.base_dist.log_prob(value) - jnp.log(self._mass()[1])
94
+ return finish(self, out, value, (value >= low) & (value <= high), -jnp.inf)
95
+
96
+ def sample(self, key, sample_shape=()):
97
+ return self.icdf(unit_draws(self, key, sample_shape))
98
+
99
+ def cdf(self, value):
100
+ low, high = self.support()
101
+ below, mass = self._mass()
102
+ out = (self.base_dist.cdf(jnp.clip(value, low, high)) - below) / mass
103
+ out = jnp.where(value >= high, 1.0, jnp.clip(out, 0.0, 1.0))
104
+ return finish(self, out, value)
105
+
106
+ def icdf(self, q):
107
+ below, mass = self._mass()
108
+ base_unit = jnp.clip(below + q * mass, 0.0, 1.0)
109
+ return quantile(self, self.base_dist.icdf(base_unit), q)
110
+
111
+
112
+ class MultivariateNormal(AbstractDistribution):
113
+ """Normal distribution over one event axis of length ``d``.
114
+
115
+ For an event distribution ``cdf`` and ``icdf`` map to and from the unit
116
+ cube rather than computing the joint distribution function: ``cdf``
117
+ applies the standard normal distribution function to
118
+ ``solve(scale_tril, value - loc)``, and ``icdf`` inverts it.
119
+
120
+ Attributes:
121
+ loc: Mean, shape ``(..., d)``.
122
+ scale_tril: Lower-triangular factor of the covariance with a positive
123
+ diagonal, shape ``(..., d, d)``.
124
+ """
125
+
126
+ loc: Array = eqx.field(converter=as_float)
127
+ scale_tril: Array = eqx.field(converter=as_float)
128
+ event_dim: ClassVar[int] = 1
129
+ bounds: ClassVar[str] = "real"
130
+ has_icdf: ClassVar[bool] = True
131
+
132
+ def __check_init__(self):
133
+ size = self.loc.shape[-1:]
134
+ if self.loc.ndim < 1 or self.scale_tril.shape[-2:] != size + size:
135
+ raise ValueError("loc must be (..., d) and scale_tril (..., d, d)")
136
+
137
+ def _diagonal(self):
138
+ return jnp.diagonal(self.scale_tril, axis1=-2, axis2=-1)
139
+
140
+ def support(self):
141
+ triangular = jnp.all(jnp.triu(self.scale_tril, 1) == 0, (-2, -1))
142
+ valid = triangular & jnp.all(self._diagonal() > 0, -1)
143
+ shape = jnp.broadcast_shapes(self.loc.shape, self.scale_tril.shape[:-1])
144
+ high = jnp.broadcast_to(jnp.where(valid[..., None], jnp.inf, jnp.nan), shape)
145
+ return -high, high
146
+
147
+ def _status(self, arg):
148
+ """Batch mask: 0 if usable, -inf if invalid, NaN for a NaN input."""
149
+ nan = jnp.isnan(arg).any(-1) | jnp.isnan(self.loc).any(-1)
150
+ nan = nan | jnp.isnan(self.scale_tril).any((-2, -1))
151
+ status = jnp.where(is_valid(self), 0.0, -jnp.inf)
152
+ return jnp.where(nan, jnp.nan, debug_check(self, status))
153
+
154
+ def _mask(self, out, arg):
155
+ return jnp.where(self._status(arg)[..., None] == 0, out, jnp.nan)
156
+
157
+ def _whiten(self, value):
158
+ return _solve_lower(self.scale_tril, value - self.loc)
159
+
160
+ def _color(self, noise):
161
+ return self.loc + jnp.einsum("...ij,...j->...i", self.scale_tril, noise)
162
+
163
+ def log_prob(self, value):
164
+ z = self._whiten(value)
165
+ log_det = jnp.sum(jnp.log(self._diagonal()), -1)
166
+ out = -0.5 * jnp.sum(z**2, -1) - log_det - z.shape[-1] * _LOG_SQRT_2PI
167
+ status = self._status(value)
168
+ return jnp.where(status == 0, out, status)
169
+
170
+ def sample(self, key, sample_shape=()):
171
+ sample_shape = tuple(sample_shape) + self.support()[0].shape
172
+ dtype = jnp.result_type(self.loc, self.scale_tril)
173
+ noise = jax.random.normal(key, sample_shape, dtype)
174
+ return self._mask(self._color(noise), noise)
175
+
176
+ def cdf(self, value):
177
+ return self._mask(ndtr(self._whiten(value)), value)
178
+
179
+ def icdf(self, q):
180
+ inside = jnp.where((q >= 0) & (q <= 1), q, jnp.nan)
181
+ return self._mask(self._color(ndtri(inside)), q)
182
+
183
+
184
+ class Mixture(AbstractDistribution):
185
+ """Weighted mixture of ``K`` distributions of one family.
186
+
187
+ The components are one distribution whose batch has a last axis of length ``K``,
188
+ for example ``Normal(loc, scale)`` with parameters of shape ``(K,)``. A
189
+ scalar mixture has a distribution function (``cdf``) but no quantile,
190
+ so ``has_icdf`` is false and ``icdf`` raises.
191
+
192
+ Attributes:
193
+ mixing_logits: Unnormalized log weights, shape ``(..., K)``. They are
194
+ normalized internally.
195
+ components: Distribution holding the ``K`` components.
196
+ """
197
+
198
+ mixing_logits: Array = eqx.field(converter=as_float)
199
+ component_distribution: AbstractDistribution
200
+ has_icdf: ClassVar[bool] = False
201
+
202
+ @property
203
+ def event_dim(self) -> int:
204
+ """Event rank of the components."""
205
+ return self.component_distribution.event_dim
206
+
207
+ @property
208
+ def bounds(self) -> str:
209
+ """Bounded sides of the components."""
210
+ return self.component_distribution.bounds
211
+
212
+ def _log_mix(self):
213
+ return jax.nn.log_softmax(self.mixing_logits, -1)
214
+
215
+ def _per_component(self, value):
216
+ """Insert the component axis in front of the event axes."""
217
+ return jnp.expand_dims(value, -1 - self.event_dim)
218
+
219
+ def _over_event(self, mask):
220
+ return mask[..., None] if self.event_dim else mask
221
+
222
+ def support(self):
223
+ low, high = self.component_distribution.support()
224
+ axis = -1 - self.event_dim
225
+ valid = jnp.isfinite(logsumexp(self.mixing_logits, -1))
226
+ valid = self._over_event(valid)
227
+ low = jnp.where(valid, low.min(axis), jnp.nan)
228
+ return low, jnp.where(valid, high.max(axis), jnp.nan)
229
+
230
+ def log_prob(self, value):
231
+ parts = self.component_distribution.log_prob(self._per_component(value))
232
+ terms = self._log_mix() + parts
233
+ some = jnp.any(terms > -jnp.inf, -1) & is_valid(self)
234
+ out = logsumexp(jnp.where(some[..., None], terms, 0.0), -1)
235
+ out = jnp.where(some, debug_check(self, out), -jnp.inf)
236
+ nan = jnp.isnan(parts).any(-1) | jnp.isnan(self.mixing_logits).any(-1)
237
+ return jnp.where(nan, jnp.nan, out)
238
+
239
+ def sample(self, key, sample_shape=()):
240
+ key_index, key_draw = jax.random.split(key)
241
+ draws = self.component_distribution.sample(key_draw, sample_shape)
242
+ lead = draws.shape[: draws.ndim - 1 - self.event_dim]
243
+ index = jax.random.categorical(key_index, self.mixing_logits, shape=lead)
244
+ index = self._over_event(index[..., None])
245
+ out = jnp.take_along_axis(draws, index, -1 - self.event_dim)
246
+ out = out.squeeze(-1 - self.event_dim)
247
+ return jnp.where(self._over_event(is_valid(self)), out, jnp.nan)
248
+
249
+ def cdf(self, value):
250
+ if self.event_dim:
251
+ raise NotImplementedError("a Mixture over an event axis has no cdf")
252
+ parts = self.component_distribution.cdf(self._per_component(value))
253
+ out = jnp.sum(jnp.exp(self._log_mix()) * parts, -1)
254
+ return jnp.where(is_valid(self), debug_check(self, out), jnp.nan)
255
+
256
+ def icdf(self, q):
257
+ raise NotImplementedError("Mixture has no quantile; has_icdf is False")
@@ -0,0 +1,158 @@
1
+ """The distribution interface and the helpers shared by the scalar records."""
2
+
3
+ import os
4
+ from abc import abstractmethod
5
+
6
+ import equinox as eqx
7
+ import jax
8
+ import jax.numpy as jnp
9
+ from jax import Array
10
+
11
+ # Read once at import. When on, a distribution evaluated with parameters outside their
12
+ # domain raises through eqx.error_if instead of returning -inf or NaN.
13
+ DEBUG_CHECKS = os.environ.get("PRIORITIES_DEBUG_CHECKS", "0") == "1"
14
+
15
+
16
+ class AbstractDistribution(eqx.Module):
17
+ """A probability distribution: a density against ``d(value)`` with its draws.
18
+
19
+ A distribution is a record of array parameters. It is elementwise (``event_dim``
20
+ 0) or has one event axis (``event_dim`` 1). Shapes follow one rule: a
21
+ value is ``sample + batch + event``, where ``batch`` is the broadcast of
22
+ the parameter shapes. The output dtype is the promotion of the argument
23
+ and the parameters, so a distribution built from Python floats returns the dtype
24
+ of its argument.
25
+
26
+ Subclass this directly when the mathematics is new. A named distribution that only
27
+ fixes defaults of an existing record is a function returning that record.
28
+
29
+ Attributes:
30
+ event_dim: Number of event axes, 0 or 1. Static.
31
+ bounds: Which sides of the support are bounded: ``"real"``,
32
+ ``"lower"``, ``"upper"`` or ``"interval"``. Static, so the default
33
+ transform is chosen before tracing.
34
+ has_icdf: Whether ``cdf`` and ``icdf`` form a bijection
35
+ between the support and the unit cube. Static; test it before
36
+ building a sampler that needs the map.
37
+ """
38
+
39
+ event_dim: eqx.AbstractVar[int]
40
+ bounds: eqx.AbstractVar[str]
41
+ has_icdf: eqx.AbstractVar[bool]
42
+
43
+ def __check_init__(self):
44
+ """Refuse concrete parameters outside their domain; skip tracers."""
45
+ valid = is_valid(self)
46
+ if not isinstance(valid, jax.core.Tracer) and not bool(jnp.all(valid)):
47
+ raise ValueError(f"parameters outside their domain: {self}")
48
+
49
+ @abstractmethod
50
+ def support(self) -> tuple[Array, Array]:
51
+ """Return the bounds ``(low, high)`` of the support.
52
+
53
+ Each has shape ``batch + event`` and is infinite on an unbounded side.
54
+ An endpoint belongs to the support when the density there is finite.
55
+ Both are NaN where the parameters are outside their domain.
56
+ """
57
+
58
+ @abstractmethod
59
+ def log_prob(self, value: Array) -> Array:
60
+ """Return the log density against ``d(value)``, reduced over the event.
61
+
62
+ The result is exactly ``-inf`` outside the support, with a zero
63
+ gradient there, and for parameters outside their domain. It is NaN
64
+ when the value or a parameter is NaN.
65
+ """
66
+
67
+ @abstractmethod
68
+ def sample(self, key: Array, sample_shape: tuple[int, ...] = ()) -> Array:
69
+ """Draw values of shape ``sample_shape + batch + event``.
70
+
71
+ The dtype is the promotion of the parameters. Draws are NaN for
72
+ parameters outside their domain.
73
+ """
74
+
75
+ @abstractmethod
76
+ def cdf(self, value: Array) -> Array:
77
+ """Map a value to the unit cube of the event shape.
78
+
79
+ For a scalar distribution this is the cumulative distribution function. NaN for
80
+ parameters outside their domain. Raises ``NotImplementedError`` when
81
+ the distribution has no such function.
82
+ """
83
+
84
+ @abstractmethod
85
+ def icdf(self, q: Array) -> Array:
86
+ """Map a point of the unit cube to a value: uniform in, the distribution out.
87
+
88
+ For a scalar distribution this is the quantile function. It returns the support
89
+ endpoints at 0 and 1 and NaN outside ``[0, 1]`` or for parameters
90
+ outside their domain. Raises ``NotImplementedError`` when
91
+ ``has_icdf`` is false.
92
+ """
93
+
94
+
95
+ def as_float(x) -> Array:
96
+ """Convert a parameter to a floating array, keeping weak types."""
97
+ x = jnp.asarray(x)
98
+ return x if jnp.issubdtype(x.dtype, jnp.inexact) else x * 1.0
99
+
100
+
101
+ def is_valid(dist: AbstractDistribution) -> Array:
102
+ """Return the batch-shaped mask of parameters inside their domain."""
103
+ low, high = dist.support()
104
+ invalid = jnp.isnan(low) | jnp.isnan(high)
105
+ return ~(invalid.any(-1) if dist.event_dim else invalid)
106
+
107
+
108
+ def debug_check(dist: AbstractDistribution, out: Array) -> Array:
109
+ """Raise at run time for invalid parameters when the debug flag is on."""
110
+ if DEBUG_CHECKS:
111
+ message = f"{type(dist).__name__}: parameters outside their domain"
112
+ out = eqx.error_if(out, ~is_valid(dist), message)
113
+ return out
114
+
115
+
116
+ def draw_spec(dist: AbstractDistribution, shape: tuple[int, ...]):
117
+ """Return the shape ``shape + batch`` and dtype of scalar-distribution draws."""
118
+ leaves = jax.tree_util.tree_leaves(dist)
119
+ batch = jnp.broadcast_shapes(*(leaf.shape for leaf in leaves))
120
+ return tuple(shape) + batch, jnp.result_type(*leaves)
121
+
122
+
123
+ def bounded(dist: AbstractDistribution, valid, low, high) -> tuple[Array, Array]:
124
+ """Broadcast scalar-distribution bounds over the batch; NaN where not ``valid``."""
125
+ shape, _ = draw_spec(dist, ())
126
+ low, high = (jnp.where(valid, bound, jnp.nan) for bound in (low, high))
127
+ return jnp.broadcast_to(low, shape), jnp.broadcast_to(high, shape)
128
+
129
+
130
+ def finish(
131
+ dist: AbstractDistribution, out, arg=0.0, inside=True, fill=jnp.nan
132
+ ) -> Array:
133
+ """Mask the result of a scalar distribution.
134
+
135
+ ``fill`` replaces ``out`` outside ``inside`` and for invalid parameters;
136
+ NaN replaces it where ``arg`` or a parameter is NaN.
137
+ """
138
+ inputs = (arg, *jax.tree_util.tree_leaves(dist))
139
+ nan = sum(jnp.isnan(x) for x in inputs) > 0
140
+ out = jnp.where(is_valid(dist) & inside, debug_check(dist, out), fill)
141
+ # Adding typed zeros promotes to the inputs' dtype and keeps weak types.
142
+ return jnp.where(nan, jnp.nan, out) + sum(jnp.zeros_like(x) for x in inputs)
143
+
144
+
145
+ def unit_draws(dist: AbstractDistribution, key: Array, shape: tuple[int, ...]) -> Array:
146
+ """Draw uniforms on the open unit interval for a quantile-based sample."""
147
+ shape, dtype = draw_spec(dist, shape)
148
+ tiny = jnp.finfo(dtype).tiny
149
+ return jax.random.uniform(key, shape, dtype, minval=tiny)
150
+
151
+
152
+ def quantile(dist: AbstractDistribution, out, unit) -> Array:
153
+ """Finish a scalar ``icdf``: exact endpoints, NaN off ``[0, 1]``."""
154
+ low, high = dist.support()
155
+ out = jnp.where(
156
+ unit <= 0, low, jnp.where(unit >= 1, high, jnp.clip(out, low, high))
157
+ )
158
+ return finish(dist, out, unit, (unit >= 0) & (unit <= 1))
priorities/_records.py ADDED
@@ -0,0 +1,335 @@
1
+ """Elementwise records: one distribution per class, array parameters only."""
2
+
3
+ import math
4
+ from typing import ClassVar
5
+
6
+ import equinox as eqx
7
+ import jax
8
+ import jax.numpy as jnp
9
+ from jax import Array
10
+ from jax.custom_derivatives import SymbolicZero
11
+ from jax.scipy.special import betainc, betaln, erf, erfinv, ndtr, ndtri
12
+
13
+ from priorities._distribution import (
14
+ AbstractDistribution,
15
+ as_float,
16
+ bounded,
17
+ draw_spec,
18
+ finish,
19
+ quantile,
20
+ unit_draws,
21
+ )
22
+
23
+ _LOG_SQRT_2PI = 0.5 * math.log(2 * math.pi)
24
+ _SQRT_2 = math.sqrt(2.0)
25
+
26
+
27
+ class Uniform(AbstractDistribution):
28
+ """Uniform distribution on the closed interval ``[low, high]``.
29
+
30
+ Attributes:
31
+ low: Lower bound, finite.
32
+ high: Upper bound, finite and above ``low``.
33
+ """
34
+
35
+ low: Array = eqx.field(converter=as_float)
36
+ high: Array = eqx.field(converter=as_float)
37
+ event_dim: ClassVar[int] = 0
38
+ bounds: ClassVar[str] = "interval"
39
+ has_icdf: ClassVar[bool] = True
40
+
41
+ def support(self):
42
+ valid = (self.low < self.high) & jnp.isfinite(self.high - self.low)
43
+ return bounded(self, valid, self.low, self.high)
44
+
45
+ def log_prob(self, value):
46
+ inside = (value >= self.low) & (value <= self.high)
47
+ return finish(self, -jnp.log(self.high - self.low), value, inside, -jnp.inf)
48
+
49
+ def sample(self, key, sample_shape=()):
50
+ return self.icdf(unit_draws(self, key, sample_shape))
51
+
52
+ def cdf(self, value):
53
+ clipped = jnp.clip(value, self.low, self.high)
54
+ return finish(self, (clipped - self.low) / (self.high - self.low), value)
55
+
56
+ def icdf(self, q):
57
+ return quantile(self, self.low + q * (self.high - self.low), q)
58
+
59
+
60
+ class LogUniform(AbstractDistribution):
61
+ """Distribution with density proportional to ``1 / value`` on ``[low, high]``.
62
+
63
+ Attributes:
64
+ low: Lower bound, positive.
65
+ high: Upper bound, finite and above ``low``.
66
+ """
67
+
68
+ low: Array = eqx.field(converter=as_float)
69
+ high: Array = eqx.field(converter=as_float)
70
+ event_dim: ClassVar[int] = 0
71
+ bounds: ClassVar[str] = "interval"
72
+ has_icdf: ClassVar[bool] = True
73
+
74
+ def support(self):
75
+ valid = (self.low > 0) & (self.low < self.high) & jnp.isfinite(self.high)
76
+ return bounded(self, valid, self.low, self.high)
77
+
78
+ def _log_ratio(self):
79
+ return jnp.log(self.high / self.low)
80
+
81
+ def log_prob(self, value):
82
+ inside = (value >= self.low) & (value <= self.high)
83
+ safe = jnp.where(inside, value, 1.0)
84
+ out = -jnp.log(safe) - jnp.log(self._log_ratio())
85
+ return finish(self, out, value, inside, -jnp.inf)
86
+
87
+ def sample(self, key, sample_shape=()):
88
+ return self.icdf(unit_draws(self, key, sample_shape))
89
+
90
+ def cdf(self, value):
91
+ clipped = jnp.clip(value, self.low, self.high)
92
+ return finish(self, jnp.log(clipped / self.low) / self._log_ratio(), value)
93
+
94
+ def icdf(self, q):
95
+ return quantile(self, self.low * jnp.exp(q * self._log_ratio()), q)
96
+
97
+
98
+ class Normal(AbstractDistribution):
99
+ """Normal distribution.
100
+
101
+ Attributes:
102
+ loc: Mean.
103
+ scale: Standard deviation, positive.
104
+ """
105
+
106
+ loc: Array = eqx.field(converter=as_float)
107
+ scale: Array = eqx.field(converter=as_float)
108
+ event_dim: ClassVar[int] = 0
109
+ bounds: ClassVar[str] = "real"
110
+ has_icdf: ClassVar[bool] = True
111
+
112
+ def support(self):
113
+ return bounded(self, self.scale > 0, -jnp.inf, jnp.inf)
114
+
115
+ def log_prob(self, value):
116
+ z = (value - self.loc) / self.scale
117
+ out = -0.5 * z**2 - jnp.log(self.scale) - _LOG_SQRT_2PI
118
+ return finish(self, out, value, fill=-jnp.inf)
119
+
120
+ def sample(self, key, sample_shape=()):
121
+ noise = jax.random.normal(key, *draw_spec(self, sample_shape))
122
+ return finish(self, self.loc + self.scale * noise)
123
+
124
+ def cdf(self, value):
125
+ return finish(self, ndtr((value - self.loc) / self.scale), value)
126
+
127
+ def icdf(self, q):
128
+ return quantile(self, self.loc + self.scale * ndtri(q), q)
129
+
130
+
131
+ class LogNormal(AbstractDistribution):
132
+ """Distribution of ``exp(x)`` for a normal ``x``, on ``(0, inf)``.
133
+
134
+ Attributes:
135
+ loc: Mean of ``log(value)``.
136
+ scale: Standard deviation of ``log(value)``, positive.
137
+ """
138
+
139
+ loc: Array = eqx.field(converter=as_float)
140
+ scale: Array = eqx.field(converter=as_float)
141
+ event_dim: ClassVar[int] = 0
142
+ bounds: ClassVar[str] = "lower"
143
+ has_icdf: ClassVar[bool] = True
144
+
145
+ def support(self):
146
+ return bounded(self, self.scale > 0, 0.0, jnp.inf)
147
+
148
+ def _z(self, value):
149
+ """Standardized ``log(value)`` and the log itself, safe off-support."""
150
+ log_value = jnp.log(jnp.where(value > 0, value, 1.0))
151
+ return (log_value - self.loc) / self.scale, log_value
152
+
153
+ def log_prob(self, value):
154
+ z, log_value = self._z(value)
155
+ out = -0.5 * z**2 - jnp.log(self.scale) - _LOG_SQRT_2PI - log_value
156
+ return finish(self, out, value, value > 0, -jnp.inf)
157
+
158
+ def sample(self, key, sample_shape=()):
159
+ noise = jax.random.normal(key, *draw_spec(self, sample_shape))
160
+ return finish(self, jnp.exp(self.loc + self.scale * noise))
161
+
162
+ def cdf(self, value):
163
+ return finish(self, jnp.where(value > 0, ndtr(self._z(value)[0]), 0.0), value)
164
+
165
+ def icdf(self, q):
166
+ return quantile(self, jnp.exp(self.loc + self.scale * ndtri(q)), q)
167
+
168
+
169
+ class HalfNormal(AbstractDistribution):
170
+ """Distribution of ``|x|`` for a zero-mean normal ``x``, on ``[0, inf)``.
171
+
172
+ Attributes:
173
+ scale: Standard deviation of the underlying normal, positive.
174
+ """
175
+
176
+ scale: Array = eqx.field(converter=as_float)
177
+ event_dim: ClassVar[int] = 0
178
+ bounds: ClassVar[str] = "lower"
179
+ has_icdf: ClassVar[bool] = True
180
+
181
+ def support(self):
182
+ return bounded(self, self.scale > 0, 0.0, jnp.inf)
183
+
184
+ def log_prob(self, value):
185
+ z = jnp.maximum(value, 0.0) / self.scale
186
+ out = math.log(2.0) - 0.5 * z**2 - jnp.log(self.scale) - _LOG_SQRT_2PI
187
+ return finish(self, out, value, value >= 0, -jnp.inf)
188
+
189
+ def sample(self, key, sample_shape=()):
190
+ noise = jax.random.normal(key, *draw_spec(self, sample_shape))
191
+ return finish(self, self.scale * jnp.abs(noise))
192
+
193
+ def cdf(self, value):
194
+ z = jnp.maximum(value, 0.0) / self.scale
195
+ return finish(self, erf(z / _SQRT_2), value)
196
+
197
+ def icdf(self, q):
198
+ return quantile(self, self.scale * _SQRT_2 * erfinv(q), q)
199
+
200
+
201
+ class Rayleigh(AbstractDistribution):
202
+ """Rayleigh distribution on ``(0, inf)``; the density vanishes at zero.
203
+
204
+ Attributes:
205
+ scale: Mode of the density, positive.
206
+ """
207
+
208
+ scale: Array = eqx.field(converter=as_float)
209
+ event_dim: ClassVar[int] = 0
210
+ bounds: ClassVar[str] = "lower"
211
+ has_icdf: ClassVar[bool] = True
212
+
213
+ def support(self):
214
+ return bounded(self, self.scale > 0, 0.0, jnp.inf)
215
+
216
+ def log_prob(self, value):
217
+ inside = (value > 0) & (value < jnp.inf)
218
+ safe = jnp.where(inside, value, 1.0)
219
+ out = jnp.log(safe) - 2 * jnp.log(self.scale) - 0.5 * (safe / self.scale) ** 2
220
+ return finish(self, out, value, inside, -jnp.inf)
221
+
222
+ def sample(self, key, sample_shape=()):
223
+ return self.icdf(unit_draws(self, key, sample_shape))
224
+
225
+ def cdf(self, value):
226
+ z = jnp.maximum(value, 0.0) / self.scale
227
+ return finish(self, -jnp.expm1(-0.5 * z**2), value)
228
+
229
+ def icdf(self, q):
230
+ return quantile(self, self.scale * jnp.sqrt(-2 * jnp.log1p(-q)), q)
231
+
232
+
233
+ def _beta_log_kernel(a, b, value):
234
+ """Beta log density at ``value`` in ``[0, 1]``, finite off the open interval."""
235
+ log_low = jnp.log(jnp.where(value > 0, value, 1.0))
236
+ log_high = jnp.log1p(-jnp.where(value < 1, value, 0.0))
237
+ # betaln may drop the weak type of Python-number shapes, which would
238
+ # promote a float32 value to float64; cast it to the promoted dtype.
239
+ log_norm = betaln(a, b).astype(jnp.result_type(a, b, value))
240
+ return (a - 1) * log_low + (b - 1) * log_high - log_norm
241
+
242
+
243
+ @jax.custom_jvp
244
+ def _beta_quantile(a, b, unit):
245
+ """Solve ``betainc(a, b, x) = unit`` by bisection on ``log(x)``.
246
+
247
+ Bisecting the logarithm keeps relative accuracy in the lower tail, where
248
+ ``x`` spans many decades for a shape below one. The iteration count is
249
+ static: twice the bit width closes the bracket from ``log(tiny)`` to
250
+ adjacent floats anywhere in ``(0, 1)``.
251
+ """
252
+ dtype = jnp.result_type(a, b, unit)
253
+ finfo = jnp.finfo(dtype)
254
+ a, b, unit = jnp.broadcast_arrays(a, b, jnp.asarray(unit, dtype))
255
+
256
+ def halve(_, bracket):
257
+ low, high = bracket
258
+ middle = 0.5 * (low + high)
259
+ below = betainc(a, b, jnp.exp(middle)) < unit
260
+ return jnp.where(below, middle, low), jnp.where(below, high, middle)
261
+
262
+ bracket = (jnp.full(unit.shape, jnp.log(finfo.tiny)), jnp.zeros(unit.shape, dtype))
263
+ low, high = jax.lax.fori_loop(0, 2 * finfo.bits, halve, bracket)
264
+ return jnp.exp(0.5 * (low + high))
265
+
266
+
267
+ def _beta_quantile_jvp(primals, tangents):
268
+ """Differentiate the quantile in ``unit`` only: ``dx/du = 1 / pdf(x)``."""
269
+ a, b, unit = primals
270
+ a_dot, b_dot, unit_dot = tangents
271
+ if not (isinstance(a_dot, SymbolicZero) and isinstance(b_dot, SymbolicZero)):
272
+ raise ValueError("the Beta quantile is not differentiable in its shapes")
273
+ root = _beta_quantile(a, b, unit)
274
+ if isinstance(unit_dot, SymbolicZero):
275
+ return root, jnp.zeros_like(root)
276
+ return root, unit_dot * jnp.exp(-_beta_log_kernel(a, b, root))
277
+
278
+
279
+ _beta_quantile.defjvp(_beta_quantile_jvp, symbolic_zeros=True)
280
+
281
+
282
+ class Beta(AbstractDistribution):
283
+ """Beta distribution on ``(0, 1)``.
284
+
285
+ An endpoint is in the support only when its shape is exactly one, where
286
+ the density there is finite and positive. The density is differentiable in
287
+ the shapes. The distribution function and the quantile are not: JAX has no
288
+ derivative of ``betainc`` in its shapes, so differentiating ``cdf`` or
289
+ ``icdf`` in ``a`` or ``b`` raises ``ValueError``. The quantile is
290
+ differentiable in its argument.
291
+
292
+ Attributes:
293
+ a: First shape, positive.
294
+ b: Second shape, positive.
295
+ """
296
+
297
+ concentration1: Array = eqx.field(converter=as_float)
298
+ concentration0: Array = eqx.field(converter=as_float)
299
+ event_dim: ClassVar[int] = 0
300
+ bounds: ClassVar[str] = "interval"
301
+ has_icdf: ClassVar[bool] = True
302
+
303
+ def support(self):
304
+ return bounded(
305
+ self, (self.concentration1 > 0) & (self.concentration0 > 0), 0.0, 1.0
306
+ )
307
+
308
+ def log_prob(self, value):
309
+ low = (value > 0) | ((value == 0) & (self.concentration1 == 1))
310
+ high = (value < 1) | ((value == 1) & (self.concentration0 == 1))
311
+ out = _beta_log_kernel(self.concentration1, self.concentration0, value)
312
+ return finish(self, out, value, low & high, -jnp.inf)
313
+
314
+ def sample(self, key, sample_shape=()):
315
+ sample_shape, dtype = draw_spec(self, sample_shape)
316
+ # The gamma rejection sampler behind the draw needs positive shapes.
317
+ a, b = (
318
+ jnp.where(shape_ > 0, shape_, 1.0)
319
+ for shape_ in (self.concentration1, self.concentration0)
320
+ )
321
+ return finish(self, jax.random.beta(key, a, b, sample_shape, dtype))
322
+
323
+ def cdf(self, value):
324
+ return finish(
325
+ self,
326
+ betainc(
327
+ self.concentration1, self.concentration0, jnp.clip(value, 0.0, 1.0)
328
+ ),
329
+ value,
330
+ )
331
+
332
+ def icdf(self, q):
333
+ return quantile(
334
+ self, _beta_quantile(self.concentration1, self.concentration0, q), q
335
+ )
@@ -0,0 +1,86 @@
1
+ """The default transform between a distribution's support and the real line."""
2
+
3
+ import jax
4
+ import jax.numpy as jnp
5
+ from jax import Array
6
+
7
+ from priorities._distribution import AbstractDistribution
8
+
9
+
10
+ def _check_bounds(dist: AbstractDistribution) -> str:
11
+ if dist.bounds not in ("real", "lower", "upper", "interval"):
12
+ raise ValueError(f"unknown bounds {dist.bounds!r} on {type(dist).__name__}")
13
+ return dist.bounds
14
+
15
+
16
+ def to_real(dist: AbstractDistribution, value: Array) -> Array:
17
+ """Map a value in the support of ``dist`` to unconstrained coordinates.
18
+
19
+ The transform follows ``dist.bounds``: identity for ``"real"``,
20
+ ``log(value - low)`` for ``"lower"``, ``log(high - value)`` for
21
+ ``"upper"`` and the logit of the fractional position for ``"interval"``.
22
+ It is elementwise, also for a distribution with an event axis.
23
+
24
+ Args:
25
+ dist: The distribution whose support is mapped.
26
+ value: Values inside the support.
27
+
28
+ Returns:
29
+ Unconstrained coordinates of the shape of ``value``.
30
+ """
31
+ bounds = _check_bounds(dist)
32
+ low, high = dist.support()
33
+ if bounds == "real":
34
+ return value
35
+ if bounds == "lower":
36
+ return jnp.log(value - low)
37
+ if bounds == "upper":
38
+ return jnp.log(high - value)
39
+ return jnp.log(value - low) - jnp.log(high - value)
40
+
41
+
42
+ def from_real(dist: AbstractDistribution, x: Array) -> tuple[Array, Array]:
43
+ """Map unconstrained coordinates to a value in the support of ``dist``.
44
+
45
+ This inverts ``to_real``: identity, ``low + exp(x)``, ``high - exp(x)`` or
46
+ ``low + (high - low) * sigmoid(x)``.
47
+
48
+ Args:
49
+ dist: The distribution whose support is the target.
50
+ x: Unconstrained coordinates.
51
+
52
+ Returns:
53
+ The value and ``log_volume``, the log of ``|d value / d x|``, summed
54
+ over the event axis when the distribution has one.
55
+ """
56
+ bounds = _check_bounds(dist)
57
+ low, high = dist.support()
58
+ if bounds == "real":
59
+ value, log_volume = x, jnp.zeros_like(x)
60
+ elif bounds == "lower":
61
+ value, log_volume = low + jnp.exp(x), x
62
+ elif bounds == "upper":
63
+ value, log_volume = high - jnp.exp(x), x
64
+ else:
65
+ width = high - low
66
+ value = low + width * jax.nn.sigmoid(x)
67
+ log_volume = jnp.log(width) + jax.nn.log_sigmoid(x) + jax.nn.log_sigmoid(-x)
68
+ log_volume = jnp.broadcast_to(log_volume, value.shape)
69
+ return value, log_volume.sum(-1) if dist.event_dim else log_volume
70
+
71
+
72
+ def real_log_prob(dist: AbstractDistribution, x: Array) -> Array:
73
+ """Return the log density of ``dist`` against ``d(x)``.
74
+
75
+ This is ``dist.log_prob(value) + log_volume`` for the default transform,
76
+ the density a gradient sampler reads in unconstrained coordinates.
77
+
78
+ Args:
79
+ dist: The distribution to evaluate.
80
+ x: Unconstrained coordinates.
81
+
82
+ Returns:
83
+ The log density, reduced over the event axis.
84
+ """
85
+ value, log_volume = from_real(dist, x)
86
+ return dist.log_prob(value) + log_volume
priorities/_version.py ADDED
@@ -0,0 +1,24 @@
1
+ # file generated by vcs-versioning
2
+ # don't change, don't track in version control
3
+ from __future__ import annotations
4
+
5
+ __all__ = [
6
+ "__version__",
7
+ "__version_tuple__",
8
+ "version",
9
+ "version_tuple",
10
+ "__commit_id__",
11
+ "commit_id",
12
+ ]
13
+
14
+ version: str
15
+ __version__: str
16
+ __version_tuple__: tuple[int | str, ...]
17
+ version_tuple: tuple[int | str, ...]
18
+ commit_id: str | None
19
+ __commit_id__: str | None
20
+
21
+ __version__ = version = '0.1.0'
22
+ __version_tuple__ = version_tuple = (0, 1, 0)
23
+
24
+ __commit_id__ = commit_id = None
priorities/testing.py ADDED
@@ -0,0 +1,147 @@
1
+ """Contract checks for a distribution, for this library's tests and for subclass owners.
2
+
3
+ ``check_distribution`` ties ``sample``, ``cdf`` and ``icdf`` to ``log_prob``
4
+ without restating any formula, so it applies unchanged to a new subclass of
5
+ ``AbstractDistribution``. The absolute scale of ``log_prob`` is not covered here: pin
6
+ it against an independent reference.
7
+ """
8
+
9
+ import jax
10
+ import jax.numpy as jnp
11
+ from jax import Array
12
+
13
+ from priorities._distribution import AbstractDistribution
14
+ from priorities._transform import from_real, real_log_prob, to_real
15
+
16
+ # sup-norm quantile of the Kolmogorov distribution: P(sqrt(n) D > 2.69) = 1e-6.
17
+ KS_SCALE = 2.69
18
+
19
+
20
+ def ks_distance(dist: AbstractDistribution, draws: Array) -> Array:
21
+ """Return the Kolmogorov-Smirnov distance of draws to ``dist.cdf``.
22
+
23
+ Args:
24
+ dist: A distribution whose ``cdf`` is a distribution function (scalar)
25
+ or a map to independent uniforms (event distribution with an inverse CDF).
26
+ draws: Values of shape ``(n,) + event``.
27
+
28
+ Returns:
29
+ The largest distance between the empirical and the uniform
30
+ distribution functions of ``cdf(draws)``, over the coordinates.
31
+ """
32
+ count = draws.shape[0]
33
+ unit = jnp.sort(dist.cdf(draws).reshape(count, -1), axis=0)
34
+ rank = jnp.arange(count)[:, None]
35
+ return jnp.max(jnp.maximum((rank + 1) / count - unit, unit - rank / count))
36
+
37
+
38
+ def icdf_round_trip(dist: AbstractDistribution, dtype=None, ulps: float = 4.0) -> Array:
39
+ """Return the scaled error of ``cdf(icdf(u))`` over both tails.
40
+
41
+ The grid is logarithmic in ``u`` from 1e-30 to 0.5 and in ``1 - u`` from
42
+ 0.5 down to the resolution of the dtype. The error is divided by
43
+ ``min(u, 1 - u)`` after removing what the inputs cannot resolve:
44
+ ``ulps`` units in the last place of ``u`` and of the value (the latter
45
+ mapped through the density). An absolute tolerance cannot see a lost tail;
46
+ this one can.
47
+
48
+ Args:
49
+ dist: A scalar distribution with an inverse CDF.
50
+ dtype: Floating dtype of the grid; the default float when ``None``.
51
+ ulps: Allowance for the representation of ``u`` and of the value.
52
+
53
+ Returns:
54
+ The relative error at each grid point, to compare with a tolerance.
55
+ """
56
+ dtype = jnp.zeros((), dtype).dtype
57
+ eps = jnp.finfo(dtype).eps
58
+ lower = jnp.logspace(-30.0, jnp.log10(0.5), 61, dtype=dtype)
59
+ upper = 1 - jnp.logspace(jnp.log10(1e4 * eps), jnp.log10(0.5), 25, dtype=dtype)
60
+ unit = jnp.concatenate([lower, upper])
61
+ value = dist.icdf(unit)
62
+ floor = ulps * eps * (unit + jnp.abs(value) * jnp.exp(dist.log_prob(value)))
63
+ error = jnp.abs(dist.cdf(value) - unit)
64
+ return jnp.maximum(error - floor, 0.0) / jnp.minimum(unit, 1 - unit)
65
+
66
+
67
+ def _check_support(dist, low, high):
68
+ grad = jax.vmap(jax.grad(dist.log_prob))
69
+ finfo = jnp.finfo(jnp.result_type(low, high))
70
+ # One spacing beyond each bound, kept a normal float: subnormals can flush.
71
+ step = jnp.maximum(finfo.eps * jnp.abs(jnp.stack([low, high])), finfo.tiny)
72
+ outside = jnp.stack([low - 1.0, low - step[0], high + step[1], high + 1.0])
73
+ outside = outside[jnp.isfinite(outside)]
74
+ assert bool(jnp.all(dist.log_prob(outside) == -jnp.inf)), "density off support"
75
+ assert bool(jnp.all(grad(outside) == 0.0)), "gradient off support"
76
+ assert bool(jnp.isnan(dist.log_prob(jnp.nan))), "NaN value must give NaN"
77
+
78
+
79
+ def _check_normalization(dist, tol, half_width=40.0, count=8001):
80
+ x = jnp.linspace(-half_width, half_width, count)
81
+ total = jnp.sum(jnp.exp(real_log_prob(dist, x))) * (x[1] - x[0])
82
+ assert abs(float(total) - 1.0) < tol, f"density integrates to {total}"
83
+
84
+
85
+ def check_distribution(
86
+ dist: AbstractDistribution,
87
+ key: Array,
88
+ *,
89
+ n_draws: int = 200_000,
90
+ rtol: float = 1e-10,
91
+ unit_rtol: float = 1e-11,
92
+ ) -> None:
93
+ """Assert that the methods of an unbatched distribution agree with its density.
94
+
95
+ The checks, in order:
96
+
97
+ - draws lie in the support and survive the default transform round trip;
98
+ - a scalar distribution is exactly ``-inf`` with zero gradient outside its support
99
+ and NaN at NaN;
100
+ - a scalar distribution without a distribution function integrates to one over
101
+ the unconstrained axis (trapezoid rule on ``[-40, 40]``);
102
+ - otherwise ``cdf`` is 0 and 1 at the support ends and its derivative
103
+ is ``exp(log_prob)`` at 33 quantiles of the draws;
104
+ - with an inverse CDF, ``cdf(icdf(u))`` returns ``u`` to ``unit_rtol``
105
+ relative to ``min(u, 1 - u)`` (see ``icdf_round_trip``);
106
+ - the draws follow ``cdf``: the Kolmogorov-Smirnov distance stays
107
+ below ``2.69 / sqrt(n_draws)``, a false-rejection rate of 1e-6 per
108
+ coordinate.
109
+
110
+ The defaults are for float64. An event distribution without an inverse CDF gets the
111
+ first check only.
112
+
113
+ Args:
114
+ dist: The distribution to check, with an empty batch shape.
115
+ key: PRNG key for the draws.
116
+ n_draws: Number of draws. A deviation of 5 percent in a scale needs
117
+ 200,000 draws to be rejected; fewer suffice when ``sample`` is the
118
+ quantile of uniforms.
119
+ rtol: Relative tolerance of the derivative and normalization checks.
120
+ unit_rtol: Relative tolerance of the unit round trip.
121
+
122
+ Raises:
123
+ AssertionError: If a check fails.
124
+ """
125
+ low, high = dist.support()
126
+ draws = dist.sample(key, (n_draws,))
127
+ assert bool(jnp.all(jnp.isfinite(dist.log_prob(draws)))), "draw off support"
128
+ back, _ = from_real(dist, to_real(dist, draws[:64]))
129
+ assert bool(jnp.allclose(back, draws[:64], rtol=rtol, atol=0.0)), "transform"
130
+ if dist.event_dim == 0:
131
+ _check_support(dist, low, high)
132
+ try:
133
+ ends = dist.cdf(jnp.stack([low, high]))
134
+ except NotImplementedError:
135
+ return _check_normalization(dist, rtol)
136
+ assert bool(jnp.all(ends == jnp.array([0.0, 1.0]))), "cdf at the ends"
137
+ points = jnp.quantile(draws, jnp.linspace(0.01, 0.99, 33))
138
+ slope = jax.vmap(jax.grad(dist.cdf))(points)
139
+ density = jnp.exp(dist.log_prob(points))
140
+ assert bool(jnp.allclose(slope, density, rtol=rtol, atol=0.0)), "d cdf"
141
+ elif not dist.has_icdf:
142
+ return None
143
+ if dist.has_icdf and dist.event_dim == 0:
144
+ worst = float(jnp.max(icdf_round_trip(dist)))
145
+ assert worst < unit_rtol, f"unit round trip off by {worst}"
146
+ distance = float(ks_distance(dist, draws))
147
+ assert distance < KS_SCALE / n_draws**0.5, f"draws: KS distance {distance}"
@@ -0,0 +1,195 @@
1
+ Metadata-Version: 2.5
2
+ Name: priorities
3
+ Version: 0.1.0
4
+ Summary: Probability distributions as Equinox records: densities, draws, inverse CDFs and default transforms in JAX
5
+ Project-URL: Homepage, https://github.com/CoreySpohn/priorities
6
+ Project-URL: Issues, https://github.com/CoreySpohn/priorities/issues
7
+ Author-email: Corey Spohn <corey.a.spohn@nasa.gov>
8
+ License: MIT License
9
+
10
+ Copyright (c) 2026 Corey Spohn
11
+
12
+ Permission is hereby granted, free of charge, to any person obtaining a copy
13
+ of this software and associated documentation files (the "Software"), to deal
14
+ in the Software without restriction, including without limitation the rights
15
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
16
+ copies of the Software, and to permit persons to whom the Software is
17
+ furnished to do so, subject to the following conditions:
18
+
19
+ The above copyright notice and this permission notice shall be included in all
20
+ copies or substantial portions of the Software.
21
+
22
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
27
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28
+ SOFTWARE.
29
+ License-File: LICENSE
30
+ Keywords: Equinox,JAX,distribution,prior,probability
31
+ Classifier: Development Status :: 2 - Pre-Alpha
32
+ Classifier: Intended Audience :: Science/Research
33
+ Classifier: License :: OSI Approved :: MIT License
34
+ Classifier: Programming Language :: Python :: 3
35
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
36
+ Requires-Python: >=3.12
37
+ Requires-Dist: equinox>=0.13.2
38
+ Requires-Dist: jax>=0.8.1
39
+ Provides-Extra: dev
40
+ Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
41
+ Provides-Extra: test
42
+ Requires-Dist: hypothesis>=6.79.1; extra == 'test'
43
+ Requires-Dist: ineedvalidation>=1.0; extra == 'test'
44
+ Requires-Dist: pytest-fail-slow>=0.1.0; extra == 'test'
45
+ Requires-Dist: pytest-markdown-docs>=0.5.0; extra == 'test'
46
+ Requires-Dist: pytest-testmon>=2.0.7; extra == 'test'
47
+ Requires-Dist: pytest-timeout>=1.3.1; extra == 'test'
48
+ Requires-Dist: pytest-xdist>=3.8.0; extra == 'test'
49
+ Requires-Dist: pytest>=7.3.2; extra == 'test'
50
+ Requires-Dist: scipy>=1.15; extra == 'test'
51
+ Description-Content-Type: text/markdown
52
+
53
+ # priorities
54
+
55
+ <p align="center">
56
+ <a href="https://github.com/CoreySpohn/priorities/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/CoreySpohn/priorities/ci.yml?branch=main&style=flat-square&logo=github&label=tests" alt="Tests"/></a>
57
+ <a href="https://github.com/CoreySpohn/priorities/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License"/></a>
58
+ <a href="https://github.com/CoreySpohn/priorities/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat-square&logo=python" alt="Python 3.12+"/></a>
59
+ </p>
60
+
61
+ Probability distributions as [Equinox](https://docs.kidger.site/equinox/) records for
62
+ JAX: a density, its draws and its map to the unit cube, held as array
63
+ parameters that jit, vmap and differentiate like any other pytree. The
64
+ runtime dependencies are `jax` and `equinox`.
65
+
66
+ ## Example
67
+
68
+ ```python
69
+ import jax
70
+
71
+ jax.config.update("jax_enable_x64", True)
72
+
73
+ import jax.numpy as jnp
74
+ import priorities as pr
75
+
76
+ # An eccentricity prior: a Beta distribution cut at 0.95.
77
+ prior = pr.TruncatedDistribution(pr.Beta(0.867, 3.03), high=0.95)
78
+
79
+ draws = prior.sample(jax.random.key(0), (1000,))
80
+ assert draws.shape == (1000,)
81
+ assert float(draws.max()) <= 0.95
82
+
83
+ # The density, exactly -inf outside the support.
84
+ assert jnp.isfinite(prior.log_prob(0.2))
85
+ assert prior.log_prob(0.97) == -jnp.inf
86
+
87
+ # The inverse CDF: uniform in, the distribution out, and back.
88
+ value = prior.icdf(0.25)
89
+ assert jnp.allclose(prior.cdf(value), 0.25)
90
+
91
+ # An unconstrained coordinate for a gradient-based sampler. real_log_prob
92
+ # is the density of that coordinate, including the volume term.
93
+ z = pr.to_real(prior, value)
94
+ back, log_volume = pr.from_real(prior, z)
95
+ assert jnp.allclose(back, value)
96
+ gradient = jax.grad(lambda z: pr.real_log_prob(prior, z))(z)
97
+ assert jnp.isfinite(gradient)
98
+
99
+ # Parameters are leaves: one compiled function serves every value.
100
+ score = jax.jit(jax.grad(lambda dist: dist.log_prob(0.2)))(pr.Beta(0.867, 3.03))
101
+ assert jnp.isfinite(score.concentration1)
102
+ ```
103
+
104
+ ## What it holds
105
+
106
+ | Record | Support | `icdf` |
107
+ | --- | --- | --- |
108
+ | `Uniform(low, high)` | `[low, high]` | yes |
109
+ | `LogUniform(low, high)` | `[low, high]`, `low > 0` | yes |
110
+ | `Normal(loc, scale)` | the real line | yes |
111
+ | `LogNormal(loc, scale)` | `(0, inf)` | yes |
112
+ | `HalfNormal(scale)` | `[0, inf)` | yes |
113
+ | `Rayleigh(scale)` | `(0, inf)` | yes |
114
+ | `Beta(concentration1, concentration0)` | `(0, 1)` | yes |
115
+ | `TruncatedDistribution(base_dist, low, high)` | the cut of a scalar distribution | yes |
116
+ | `MultivariateNormal(loc, scale_tril)` | vectors | yes |
117
+ | `Mixture(mixing_logits, component_distribution)` | union of the components | no |
118
+
119
+ Every record implements five methods: `support`, `log_prob`, `sample`,
120
+ `cdf` and `icdf`. Three free functions work on any distribution:
121
+ `to_real`, `from_real` and `real_log_prob`, the default change of variable to
122
+ an unconstrained coordinate, chosen from the static `bounds` of the distribution.
123
+
124
+ Names follow NumPyro: `sample(key, sample_shape)`, `log_prob`, `cdf`, `icdf(q)`,
125
+ `Beta(concentration1, concentration0)`, `MultivariateNormal(loc, scale_tril)`,
126
+ `TruncatedDistribution(base_dist, low, high)`. The differences are deliberate:
127
+ `support()` is a method returning the bounds as arrays rather than a
128
+ constraint object, `bounds` names the bounded sides statically, `has_icdf`
129
+ says before tracing whether `icdf` exists, and `Mixture(mixing_logits,
130
+ component_distribution)` takes its weights as logits rather than a
131
+ categorical distribution.
132
+
133
+ ## Conventions
134
+
135
+ - **Shapes.** A value has shape `sample + batch + event`, where `batch` is
136
+ the broadcast of the parameter shapes. A distribution is elementwise or has one
137
+ event axis. The components of a `Mixture` are one distribution whose batch has a
138
+ last axis of length `K`.
139
+ - **Precision.** The output dtype is the promotion of the argument and the
140
+ parameters. A distribution built from Python numbers follows its argument, so it
141
+ serves float32 and float64 pipelines alike. Nothing is built at import:
142
+ enable x64 before constructing a distribution, not before importing the package.
143
+ - **Off the support.** `log_prob` is exactly `-inf` outside the support,
144
+ with a zero gradient, and NaN for a NaN value.
145
+ - **Invalid parameters.** A distribution built from concrete parameters outside their
146
+ domain raises `ValueError`. Under a transformation the parameters are
147
+ traced and cannot be inspected, so `log_prob` returns `-inf` and the other
148
+ methods return NaN: a sampler that proposes an invalid parameter rejects
149
+ it. Set `PRIORITIES_DEBUG_CHECKS=1` before import to raise at run time
150
+ instead.
151
+ - **Truncation.** Which sides are cut is static: `None` leaves a side open.
152
+ The mass of the cut is computed from the base distribution's `cdf`, so a cut
153
+ far in a tail loses relative precision.
154
+ - **Beta shapes.** The Beta density is differentiable in its shapes. Its
155
+ distribution function and quantile are not, and differentiating them in
156
+ `a` or `b` raises instead of returning a wrong number.
157
+ - **Mixture.** A scalar mixture has a distribution function (`cdf`) but
158
+ no quantile: `has_icdf` is false and `icdf` raises.
159
+
160
+ ## Adding a distribution
161
+
162
+ Subclass `AbstractDistribution` when the mathematics is new, and implement the five
163
+ methods. A named prior that only fixes the parameters of an existing record
164
+ is a function returning that record, not a class:
165
+
166
+ ```python
167
+ import priorities as pr
168
+
169
+
170
+ def kipping_eccentricity():
171
+ """Short-period eccentricity distribution of Kipping (2013)."""
172
+ return pr.Beta(0.867, 3.03)
173
+
174
+
175
+ assert isinstance(kipping_eccentricity(), pr.Beta)
176
+ ```
177
+
178
+ `priorities.testing.check_distribution(distribution, key)` checks that the draws, the inverse CDF
179
+ and the support of a distribution agree with its density without restating any
180
+ formula, so it applies unchanged to a new subclass. It needs no reference
181
+ code; pin the absolute scale of `log_prob` against one separately.
182
+
183
+ ## Scope
184
+
185
+ The package stays small on purpose. It holds distributions and the three functions
186
+ above. Samplers, inference, parameter trees, bijector objects and
187
+ domain-specific priors belong to the packages that use it. A test holds the
188
+ source to its line budget and to `jax` and `equinox` as the only runtime
189
+ dependencies.
190
+
191
+ ## Installation
192
+
193
+ ```bash
194
+ pip install priorities
195
+ ```
@@ -0,0 +1,11 @@
1
+ priorities/__init__.py,sha256=dvO-4qNq0nbgtv4H_-NTvbazxXLkQ3kvxSBYoluhMkE,1272
2
+ priorities/_composite.py,sha256=NskSsC2whTsDQWHPEcnSpYGjeHB-1TXlZHfZjB6_TjY,10032
3
+ priorities/_distribution.py,sha256=vJhORiKItJKG6Qe5WSw5_rKkIwBqK99G3KiucEGaQdI,6492
4
+ priorities/_records.py,sha256=PmMoC364vyiKTy1fEFcb7KoISh0A8J9rpnbs-ZHtJ54,11540
5
+ priorities/_transform.py,sha256=QfSLCwRsp-FijEO-Bp2ObSuyO0at9RhjLYyjzRfDMOs,3000
6
+ priorities/_version.py,sha256=n_5vdJsPNu7wZ57LGuRL585uvll-hiuvZUBWzdG0RQU,520
7
+ priorities/testing.py,sha256=C0v2xSicJ6AIVSivltvF_Okccp1VIoTKEEkmXz7pw3E,6510
8
+ priorities-0.1.0.dist-info/METADATA,sha256=E1JtrqpiLmnyMjreQGSjnKI_vIduc1c_5qZgZPEKWc8,8974
9
+ priorities-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
10
+ priorities-0.1.0.dist-info/licenses/LICENSE,sha256=66ed08OMdjt-G3WoW0mfxmaAt-zqSwZ2A0kvPklkwwQ,1068
11
+ priorities-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Corey Spohn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.