# Funsor
Funsor is a tensor-like library for functions and distributions.
See
[Functional tensors for probabilistic programming](https://arxiv.org/abs/1910.10775)
for a system description.
## Installing
**Install using pip:**
Funsor supports Python 3.7+.
```sh
pip install funsor
```
**Install from source:**
```sh
git clone git@github.com:pyro-ppl/funsor.git
cd funsor
git checkout master
pip install .
```
## Using funsor
Funsor can be used through a number of interfaces:
- Funsors can be used directly for probabilistic computations, using PyTorch
optimizers in a standard training loop. Start with these examples:
[discrete_hmm](examples/discrete_hmm.py),
[eeg_slds](examples/eeg_slds.py),
[kalman_filter](examples/kalman_filter.py),
[pcfg](examples/pcfg.py),
[sensor](examples/sensor.py),
[slds](examples/slds.py), and
[vae](examples/vae.py).
- Funsors can be used to implement custom inference algorithms within Pyro,
using custom elbo implementations in standard
[pyro.infer.SVI](http://docs.pyro.ai/en/stable/inference_algos.html#pyro.infer.svi.SVI)
training. See these examples:
[mixed_hmm](examples/mixed_hmm/model.py) and
[bart forecasting](https://github.com/pyro-ppl/sandbox/blob/master/2019-08-time-series/bart/forecast.py).
- [funsor.pyro](https://funsor.readthedocs.io/en/latest/pyro.html) provides a
number of Pyro-compatible (and PyTorch-compatible) distribution classes
that use funsors under the hood, as well
[utilities](https://funsor.readthedocs.io/en/latest/pyro.html#module-funsor.pyro.convert)
to convert between funsors and distributions.
- [funsor.minipyro](https://funsor.readthedocs.io/en/latest/minipyro.html)
provides a limited alternate backend for the Pyro probabilistic programming
language, and can perform some ELBO computations exactly.
## Design
See [design doc](https://docs.google.com/document/d/1NVlfQnNQ0Aebg8vfIGcJKsnSqAhB4bbClQrb5dwm2OM).
The goal of this library is to generalize [Pyro](http://pyro.ai)'s delayed
inference algorithms from discrete to continuous variables, and to create
machinery to enable partially delayed sampling compatible with universality. To
achieve this goal this library makes three orthogonal design choices:
1. Open terms are objects. Funsors generalize the tensor interface
to also cover arbitrary functions of multiple variables ("inputs"), where
variables may be integers, real numbers, or real tensors. Function
evaluation / substitution is the basic operation, generalizing tensor
indexing. This allows probability distributions to be first-class Funsors
and make use of existing tensor machinery, for example we can generalize
tensor contraction to computing analytic integrals in conjugate
probabilistic models.
2. Support nonstandard interpretation. Funsors support user-defined
interpretations, including, eager, lazy, mixed eager+lazy, memoized (like
opt\_einsum's sharing), and approximate interpretations like Monte Carlo
approximations of integration operations (e.g. `.sum()` over a funsor
dimension).
3. Named dimensions. Substitution is the most basic operation of Funsors. To
avoid the difficulties of broadcasting and advanced indexing in
positionally-indexed tensor libraries, all Funsor dimensions are named.
Indexing uses the `.__call__()` method and can be interpreted as
substitution (with well-understood semantics). Funsors are viewed as
algebraic expressions with one algebraic free variable per dimension. Each
dimension is either covariant (an output) or contravariant (an input).
Using `funsor` we can easily implement Pyro-style
[delayed sampling](http://pyro.ai/examples/enumeration.html), roughly:
```py
trace_log_prob = 0.
def pyro_sample(name, dist, obs=None):
assert isinstance(dist, Funsor)
if obs is not None:
value = obs
elif lazy:
# delayed sampling (like Pyro's parallel enumeration)
value = funsor.Variable(name, dist.support)
else:
value = dist.sample('value')[0]['value']
# save log_prob in trace
trace_log_prob += dist(value)
return value
# ...later during inference...
loss = -trace_log_prob.reduce(logaddexp) # collapses delayed variables
```
See [funsor/minipyro.py](funsor/minipyro.py) for complete implementation.
## Related projects
- Pyro's [ops.packed](https://github.com/uber/pyro/blob/dev/pyro/ops/packed.py),
[ops.einsum](https://github.com/uber/pyro/blob/dev/pyro/ops/einsum), and
[ops.contract](https://github.com/uber/pyro/blob/dev/pyro/ops/contract.py)
- [Birch](https://birch-lang.org/)'s [delayed sampling](https://arxiv.org/abs/1708.07787)
- [autoconj](https://arxiv.org/abs/1811.11926)
- [dyna](http://www.cs.jhu.edu/~nwf/datalog20-paper.pdf)
- [PSI solver](https://psisolver.org)
- [Hakaru](https://hakaru-dev.github.io)
- [sympy](https://www.sympy.org/en/index.html)
- [namedtensor](https://github.com/harvardnlp/namedtensor)
## Citation
If you use Funsor, please consider citing:
```
@article{obermeyer2019functional,
author = {Obermeyer, Fritz and Bingham, Eli and Jankowiak, Martin and
Phan, Du and Chen, Jonathan P},
title = {{Functional Tensors for Probabilistic Programming}},
journal = {arXiv preprint arXiv:1910.10775},
year = {2019}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/pyro-ppl/funsor",
"name": "funsor",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "probabilistic machine learning bayesian statistics pytorch jax",
"author": "Uber AI Labs",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/1b/5f/41b2584c91c611dfa109cd88356c9ff3d09da2768563b0d0f9ac4b5a7db8/funsor-0.4.5.tar.gz",
"platform": null,
"description": "# Funsor\n\nFunsor is a tensor-like library for functions and distributions.\n\nSee\n[Functional tensors for probabilistic programming](https://arxiv.org/abs/1910.10775)\nfor a system description.\n\n## Installing\n\n**Install using pip:**\n\nFunsor supports Python 3.7+.\n\n```sh\npip install funsor\n```\n\n**Install from source:**\n```sh\ngit clone git@github.com:pyro-ppl/funsor.git\ncd funsor\ngit checkout master\npip install .\n```\n\n## Using funsor\n\nFunsor can be used through a number of interfaces:\n\n- Funsors can be used directly for probabilistic computations, using PyTorch\n optimizers in a standard training loop. Start with these examples:\n [discrete_hmm](examples/discrete_hmm.py),\n [eeg_slds](examples/eeg_slds.py),\n [kalman_filter](examples/kalman_filter.py),\n [pcfg](examples/pcfg.py),\n [sensor](examples/sensor.py),\n [slds](examples/slds.py), and\n [vae](examples/vae.py).\n- Funsors can be used to implement custom inference algorithms within Pyro,\n using custom elbo implementations in standard\n [pyro.infer.SVI](http://docs.pyro.ai/en/stable/inference_algos.html#pyro.infer.svi.SVI)\n training. See these examples:\n [mixed_hmm](examples/mixed_hmm/model.py) and\n [bart forecasting](https://github.com/pyro-ppl/sandbox/blob/master/2019-08-time-series/bart/forecast.py).\n- [funsor.pyro](https://funsor.readthedocs.io/en/latest/pyro.html) provides a\n number of Pyro-compatible (and PyTorch-compatible) distribution classes\n that use funsors under the hood, as well\n [utilities](https://funsor.readthedocs.io/en/latest/pyro.html#module-funsor.pyro.convert)\n to convert between funsors and distributions.\n- [funsor.minipyro](https://funsor.readthedocs.io/en/latest/minipyro.html)\n provides a limited alternate backend for the Pyro probabilistic programming\n language, and can perform some ELBO computations exactly.\n\n## Design\n\nSee [design doc](https://docs.google.com/document/d/1NVlfQnNQ0Aebg8vfIGcJKsnSqAhB4bbClQrb5dwm2OM). \n\nThe goal of this library is to generalize [Pyro](http://pyro.ai)'s delayed\ninference algorithms from discrete to continuous variables, and to create\nmachinery to enable partially delayed sampling compatible with universality. To\nachieve this goal this library makes three orthogonal design choices:\n\n1. Open terms are objects. Funsors generalize the tensor interface\n to also cover arbitrary functions of multiple variables (\"inputs\"), where\n variables may be integers, real numbers, or real tensors. Function\n evaluation / substitution is the basic operation, generalizing tensor\n indexing. This allows probability distributions to be first-class Funsors\n and make use of existing tensor machinery, for example we can generalize\n tensor contraction to computing analytic integrals in conjugate\n probabilistic models.\n\n2. Support nonstandard interpretation. Funsors support user-defined\n interpretations, including, eager, lazy, mixed eager+lazy, memoized (like\n opt\\_einsum's sharing), and approximate interpretations like Monte Carlo\n approximations of integration operations (e.g. `.sum()` over a funsor\n dimension).\n\n3. Named dimensions. Substitution is the most basic operation of Funsors. To\n avoid the difficulties of broadcasting and advanced indexing in\n positionally-indexed tensor libraries, all Funsor dimensions are named.\n Indexing uses the `.__call__()` method and can be interpreted as\n substitution (with well-understood semantics). Funsors are viewed as\n algebraic expressions with one algebraic free variable per dimension. Each\n dimension is either covariant (an output) or contravariant (an input).\n\nUsing `funsor` we can easily implement Pyro-style\n[delayed sampling](http://pyro.ai/examples/enumeration.html), roughly:\n\n```py\ntrace_log_prob = 0.\n\ndef pyro_sample(name, dist, obs=None):\n assert isinstance(dist, Funsor)\n if obs is not None:\n value = obs\n elif lazy:\n # delayed sampling (like Pyro's parallel enumeration)\n value = funsor.Variable(name, dist.support)\n else:\n value = dist.sample('value')[0]['value']\n\n # save log_prob in trace\n trace_log_prob += dist(value)\n\n return value\n\n# ...later during inference...\nloss = -trace_log_prob.reduce(logaddexp) # collapses delayed variables\n```\nSee [funsor/minipyro.py](funsor/minipyro.py) for complete implementation.\n\n## Related projects\n\n- Pyro's [ops.packed](https://github.com/uber/pyro/blob/dev/pyro/ops/packed.py),\n [ops.einsum](https://github.com/uber/pyro/blob/dev/pyro/ops/einsum), and\n [ops.contract](https://github.com/uber/pyro/blob/dev/pyro/ops/contract.py)\n- [Birch](https://birch-lang.org/)'s [delayed sampling](https://arxiv.org/abs/1708.07787)\n- [autoconj](https://arxiv.org/abs/1811.11926)\n- [dyna](http://www.cs.jhu.edu/~nwf/datalog20-paper.pdf)\n- [PSI solver](https://psisolver.org)\n- [Hakaru](https://hakaru-dev.github.io)\n- [sympy](https://www.sympy.org/en/index.html)\n- [namedtensor](https://github.com/harvardnlp/namedtensor)\n\n## Citation\n\nIf you use Funsor, please consider citing:\n```\n@article{obermeyer2019functional,\n author = {Obermeyer, Fritz and Bingham, Eli and Jankowiak, Martin and\n Phan, Du and Chen, Jonathan P},\n title = {{Functional Tensors for Probabilistic Programming}},\n journal = {arXiv preprint arXiv:1910.10775},\n year = {2019}\n}\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "A tensor-like library for functions and distributions",
"version": "0.4.5",
"split_keywords": [
"probabilistic",
"machine",
"learning",
"bayesian",
"statistics",
"pytorch",
"jax"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c29206ba28f04d94b758ab9066e916f12198f17b8b0a85f248e6439a43993233",
"md5": "a868896dd355a3e9390b90add99636f4",
"sha256": "b99a2b5ddb26a93b5e9d28b82dbc8f36efc686c37da2f71086bfa5bc7f45726d"
},
"downloads": -1,
"filename": "funsor-0.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a868896dd355a3e9390b90add99636f4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 174915,
"upload_time": "2023-01-23T08:31:00",
"upload_time_iso_8601": "2023-01-23T08:31:00.786134Z",
"url": "https://files.pythonhosted.org/packages/c2/92/06ba28f04d94b758ab9066e916f12198f17b8b0a85f248e6439a43993233/funsor-0.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b5f41b2584c91c611dfa109cd88356c9ff3d09da2768563b0d0f9ac4b5a7db8",
"md5": "8644e6029ee83fa2ebf6dae9abd0d6ba",
"sha256": "08b77e5de04d7cf5213b4013a08a2e756ab52572a48bef6774a0c70664d4fe31"
},
"downloads": -1,
"filename": "funsor-0.4.5.tar.gz",
"has_sig": false,
"md5_digest": "8644e6029ee83fa2ebf6dae9abd0d6ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 222913,
"upload_time": "2023-01-23T08:31:02",
"upload_time_iso_8601": "2023-01-23T08:31:02.922166Z",
"url": "https://files.pythonhosted.org/packages/1b/5f/41b2584c91c611dfa109cd88356c9ff3d09da2768563b0d0f9ac4b5a7db8/funsor-0.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-23 08:31:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "pyro-ppl",
"github_project": "funsor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "funsor"
}
JSON
