priorities 0.1.0__tar.gz

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.
@@ -0,0 +1,4 @@
1
+ [codespell]
2
+ skip = .git,*.ipynb,uv.lock,*/_build,*.fits
3
+ # lod is the public lod_unit symbol for lambda/D.
4
+ ignore-words-list = lod,unser
@@ -0,0 +1,15 @@
1
+ root = true
2
+
3
+ [*]
4
+ charset = utf-8
5
+ end_of_line = lf
6
+ insert_final_newline = true
7
+ trim_trailing_whitespace = true
8
+ indent_style = space
9
+ indent_size = 4
10
+
11
+ [*.{yml,yaml,json,toml}]
12
+ indent_size = 2
13
+
14
+ [Makefile]
15
+ indent_style = tab
@@ -0,0 +1,10 @@
1
+ * text=auto eol=lf
2
+ *.ipynb text eol=lf linguist-documentation
3
+ docs/** linguist-documentation
4
+ *.fits binary
5
+ *.npy binary
6
+ *.npz binary
7
+ *.png binary
8
+ *.pdf binary
9
+ uv.lock linguist-generated -diff
10
+ CHANGELOG.md linguist-generated
@@ -0,0 +1,228 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+ docs/.build/
74
+
75
+ # PyBuilder
76
+ .pybuilder/
77
+ target/
78
+
79
+ # Jupyter Notebook
80
+ .ipynb_checkpoints
81
+
82
+ # IPython
83
+ profile_default/
84
+ ipython_config.py
85
+
86
+ # pyenv
87
+ # For a library or package, you might want to ignore these files since the code is
88
+ # intended to run in multiple environments; otherwise, check them in:
89
+ # .python-version
90
+
91
+ # pipenv
92
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
93
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
94
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
95
+ # install all needed dependencies.
96
+ # Pipfile.lock
97
+
98
+ # UV
99
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
100
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
101
+ # commonly ignored for libraries.
102
+ # uv.lock
103
+
104
+ # poetry
105
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
106
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
107
+ # commonly ignored for libraries.
108
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
109
+ # poetry.lock
110
+ # poetry.toml
111
+
112
+ # pdm
113
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
114
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
115
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
116
+ # pdm.lock
117
+ # pdm.toml
118
+ .pdm-python
119
+ .pdm-build/
120
+
121
+ # pixi
122
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
123
+ # pixi.lock
124
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
125
+ # in the .venv directory. It is recommended not to include this directory in version control.
126
+ .pixi
127
+
128
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
129
+ __pypackages__/
130
+
131
+ # Celery stuff
132
+ celerybeat-schedule
133
+ celerybeat.pid
134
+
135
+ # Redis
136
+ *.rdb
137
+ *.aof
138
+ *.pid
139
+
140
+ # RabbitMQ
141
+ mnesia/
142
+ rabbitmq/
143
+ rabbitmq-data/
144
+
145
+ # ActiveMQ
146
+ activemq-data/
147
+
148
+ # SageMath parsed files
149
+ *.sage.py
150
+
151
+ # Environments
152
+ .env
153
+ .envrc
154
+ .venv
155
+ env/
156
+ venv/
157
+ ENV/
158
+ env.bak/
159
+ venv.bak/
160
+
161
+ # Spyder project settings
162
+ .spyderproject
163
+ .spyproject
164
+
165
+ # Rope project settings
166
+ .ropeproject
167
+
168
+ # mkdocs documentation
169
+ /site
170
+
171
+ # mypy
172
+ .mypy_cache/
173
+ .dmypy.json
174
+ dmypy.json
175
+
176
+ # Pyre type checker
177
+ .pyre/
178
+
179
+ # pytype static type analyzer
180
+ .pytype/
181
+
182
+ # Cython debug symbols
183
+ cython_debug/
184
+
185
+ # PyCharm
186
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
187
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
188
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
189
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
190
+ # .idea/
191
+
192
+ # Abstra
193
+ # Abstra is an AI-powered process automation framework.
194
+ # Ignore directories containing user credentials, local state, and settings.
195
+ # Learn more at https://abstra.io/docs
196
+ .abstra/
197
+
198
+ # Visual Studio Code
199
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
200
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
201
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
202
+ # you could uncomment the following to ignore the entire vscode folder
203
+ # .vscode/
204
+ # Temporary file for partial code execution
205
+ tempCodeRunnerFile.py
206
+
207
+ # Ruff stuff:
208
+ .ruff_cache/
209
+
210
+ # PyPI configuration file
211
+ .pypirc
212
+
213
+ # Marimo
214
+ marimo/_static/
215
+ marimo/_lsp/
216
+ __marimo__/
217
+
218
+ # Streamlit
219
+ .streamlit/secrets.toml
220
+
221
+ # hatch-vcs generated version file
222
+ *_version.py
223
+
224
+ .claude/
225
+
226
+ .jax_cache/
227
+
228
+ .DS_Store
@@ -0,0 +1,28 @@
1
+ repos:
2
+ - repo: https://github.com/CoreySpohn/hwoutils
3
+ rev: 7ea5d77
4
+ hooks:
5
+ - id: no-internal-refs
6
+ - repo: https://github.com/pre-commit/pre-commit-hooks
7
+ rev: "v6.0.0"
8
+ hooks:
9
+ - id: trailing-whitespace
10
+ - id: name-tests-test
11
+ args: [--pytest-test-first]
12
+ - id: end-of-file-fixer
13
+ - repo: https://github.com/astral-sh/ruff-pre-commit
14
+ rev: v0.17.3
15
+ hooks:
16
+ - id: ruff-check
17
+ args: [--fix]
18
+ - id: ruff-format
19
+ - repo: https://github.com/codespell-project/codespell
20
+ rev: v2.4.3
21
+ hooks:
22
+ - id: codespell
23
+ - repo: https://github.com/compilerla/conventional-pre-commit
24
+ rev: v4.4.0
25
+ hooks:
26
+ - id: conventional-pre-commit
27
+ stages: [commit-msg]
28
+ args: []
@@ -0,0 +1,3 @@
1
+ {
2
+ ".": "0.1.0"
3
+ }
@@ -0,0 +1,13 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-19)
4
+
5
+
6
+ ### Features
7
+
8
+ * initial release of priorities ([27bac64](https://github.com/CoreySpohn/priorities/commit/27bac643499d868cd8f8644efc73ac1e099a4384))
9
+
10
+
11
+ ### Bug Fixes
12
+
13
+ * keep the Beta log density in its argument dtype when betaln drops weak types ([542f75b](https://github.com/CoreySpohn/priorities/commit/542f75b2b1bad33fd1fac088cfb92835b73bcafe))
@@ -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.
@@ -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,143 @@
1
+ # priorities
2
+
3
+ <p align="center">
4
+ <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>
5
+ <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>
6
+ <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>
7
+ </p>
8
+
9
+ Probability distributions as [Equinox](https://docs.kidger.site/equinox/) records for
10
+ JAX: a density, its draws and its map to the unit cube, held as array
11
+ parameters that jit, vmap and differentiate like any other pytree. The
12
+ runtime dependencies are `jax` and `equinox`.
13
+
14
+ ## Example
15
+
16
+ ```python
17
+ import jax
18
+
19
+ jax.config.update("jax_enable_x64", True)
20
+
21
+ import jax.numpy as jnp
22
+ import priorities as pr
23
+
24
+ # An eccentricity prior: a Beta distribution cut at 0.95.
25
+ prior = pr.TruncatedDistribution(pr.Beta(0.867, 3.03), high=0.95)
26
+
27
+ draws = prior.sample(jax.random.key(0), (1000,))
28
+ assert draws.shape == (1000,)
29
+ assert float(draws.max()) <= 0.95
30
+
31
+ # The density, exactly -inf outside the support.
32
+ assert jnp.isfinite(prior.log_prob(0.2))
33
+ assert prior.log_prob(0.97) == -jnp.inf
34
+
35
+ # The inverse CDF: uniform in, the distribution out, and back.
36
+ value = prior.icdf(0.25)
37
+ assert jnp.allclose(prior.cdf(value), 0.25)
38
+
39
+ # An unconstrained coordinate for a gradient-based sampler. real_log_prob
40
+ # is the density of that coordinate, including the volume term.
41
+ z = pr.to_real(prior, value)
42
+ back, log_volume = pr.from_real(prior, z)
43
+ assert jnp.allclose(back, value)
44
+ gradient = jax.grad(lambda z: pr.real_log_prob(prior, z))(z)
45
+ assert jnp.isfinite(gradient)
46
+
47
+ # Parameters are leaves: one compiled function serves every value.
48
+ score = jax.jit(jax.grad(lambda dist: dist.log_prob(0.2)))(pr.Beta(0.867, 3.03))
49
+ assert jnp.isfinite(score.concentration1)
50
+ ```
51
+
52
+ ## What it holds
53
+
54
+ | Record | Support | `icdf` |
55
+ | --- | --- | --- |
56
+ | `Uniform(low, high)` | `[low, high]` | yes |
57
+ | `LogUniform(low, high)` | `[low, high]`, `low > 0` | yes |
58
+ | `Normal(loc, scale)` | the real line | yes |
59
+ | `LogNormal(loc, scale)` | `(0, inf)` | yes |
60
+ | `HalfNormal(scale)` | `[0, inf)` | yes |
61
+ | `Rayleigh(scale)` | `(0, inf)` | yes |
62
+ | `Beta(concentration1, concentration0)` | `(0, 1)` | yes |
63
+ | `TruncatedDistribution(base_dist, low, high)` | the cut of a scalar distribution | yes |
64
+ | `MultivariateNormal(loc, scale_tril)` | vectors | yes |
65
+ | `Mixture(mixing_logits, component_distribution)` | union of the components | no |
66
+
67
+ Every record implements five methods: `support`, `log_prob`, `sample`,
68
+ `cdf` and `icdf`. Three free functions work on any distribution:
69
+ `to_real`, `from_real` and `real_log_prob`, the default change of variable to
70
+ an unconstrained coordinate, chosen from the static `bounds` of the distribution.
71
+
72
+ Names follow NumPyro: `sample(key, sample_shape)`, `log_prob`, `cdf`, `icdf(q)`,
73
+ `Beta(concentration1, concentration0)`, `MultivariateNormal(loc, scale_tril)`,
74
+ `TruncatedDistribution(base_dist, low, high)`. The differences are deliberate:
75
+ `support()` is a method returning the bounds as arrays rather than a
76
+ constraint object, `bounds` names the bounded sides statically, `has_icdf`
77
+ says before tracing whether `icdf` exists, and `Mixture(mixing_logits,
78
+ component_distribution)` takes its weights as logits rather than a
79
+ categorical distribution.
80
+
81
+ ## Conventions
82
+
83
+ - **Shapes.** A value has shape `sample + batch + event`, where `batch` is
84
+ the broadcast of the parameter shapes. A distribution is elementwise or has one
85
+ event axis. The components of a `Mixture` are one distribution whose batch has a
86
+ last axis of length `K`.
87
+ - **Precision.** The output dtype is the promotion of the argument and the
88
+ parameters. A distribution built from Python numbers follows its argument, so it
89
+ serves float32 and float64 pipelines alike. Nothing is built at import:
90
+ enable x64 before constructing a distribution, not before importing the package.
91
+ - **Off the support.** `log_prob` is exactly `-inf` outside the support,
92
+ with a zero gradient, and NaN for a NaN value.
93
+ - **Invalid parameters.** A distribution built from concrete parameters outside their
94
+ domain raises `ValueError`. Under a transformation the parameters are
95
+ traced and cannot be inspected, so `log_prob` returns `-inf` and the other
96
+ methods return NaN: a sampler that proposes an invalid parameter rejects
97
+ it. Set `PRIORITIES_DEBUG_CHECKS=1` before import to raise at run time
98
+ instead.
99
+ - **Truncation.** Which sides are cut is static: `None` leaves a side open.
100
+ The mass of the cut is computed from the base distribution's `cdf`, so a cut
101
+ far in a tail loses relative precision.
102
+ - **Beta shapes.** The Beta density is differentiable in its shapes. Its
103
+ distribution function and quantile are not, and differentiating them in
104
+ `a` or `b` raises instead of returning a wrong number.
105
+ - **Mixture.** A scalar mixture has a distribution function (`cdf`) but
106
+ no quantile: `has_icdf` is false and `icdf` raises.
107
+
108
+ ## Adding a distribution
109
+
110
+ Subclass `AbstractDistribution` when the mathematics is new, and implement the five
111
+ methods. A named prior that only fixes the parameters of an existing record
112
+ is a function returning that record, not a class:
113
+
114
+ ```python
115
+ import priorities as pr
116
+
117
+
118
+ def kipping_eccentricity():
119
+ """Short-period eccentricity distribution of Kipping (2013)."""
120
+ return pr.Beta(0.867, 3.03)
121
+
122
+
123
+ assert isinstance(kipping_eccentricity(), pr.Beta)
124
+ ```
125
+
126
+ `priorities.testing.check_distribution(distribution, key)` checks that the draws, the inverse CDF
127
+ and the support of a distribution agree with its density without restating any
128
+ formula, so it applies unchanged to a new subclass. It needs no reference
129
+ code; pin the absolute scale of `log_prob` against one separately.
130
+
131
+ ## Scope
132
+
133
+ The package stays small on purpose. It holds distributions and the three functions
134
+ above. Samplers, inference, parameter trees, bijector objects and
135
+ domain-specific priors belong to the packages that use it. A test holds the
136
+ source to its line budget and to `jax` and `equinox` as the only runtime
137
+ dependencies.
138
+
139
+ ## Installation
140
+
141
+ ```bash
142
+ pip install priorities
143
+ ```
@@ -0,0 +1,9 @@
1
+ # Security policy
2
+
3
+ This is research software maintained by one person. Please report a vulnerability, for
4
+ example a leaked credential, a malicious dependency, or a workflow that could be abused, through
5
+ GitHub private vulnerability reporting: use "Report a vulnerability" on the Security tab of this
6
+ repository. If that is unavailable, email corey.a.spohn@nasa.gov with "SECURITY" in the subject.
7
+
8
+ Expect an acknowledgement within a week. Only the latest release receives fixes. Incorrect
9
+ numerical results are not security issues; please open an ordinary issue for those.