https://github.com/basisresearch/effectful
An experimental library for metaprogramming with algebraic effects and handlers
https://github.com/basisresearch/effectful
Last synced: 4 months ago
JSON representation
An experimental library for metaprogramming with algebraic effects and handlers
- Host: GitHub
- URL: https://github.com/basisresearch/effectful
- Owner: BasisResearch
- License: apache-2.0
- Created: 2024-06-03T17:32:53.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2025-05-04T03:55:27.000Z (about 1 year ago)
- Last Synced: 2025-05-04T04:27:15.669Z (about 1 year ago)
- Language: Python
- Homepage: https://basisresearch.github.io/effectful/
- Size: 840 KB
- Stars: 6
- Watchers: 4
- Forks: 2
- Open Issues: 24
-
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE.md
Awesome Lists containing this project
README
.. index-inclusion-marker
Effectful
=========
Effectful is an algebraic effect system for Python, intended for use in the
implementation of probabilistic programming languages. It is a core component of
the `ChiRho `_
causal modeling language.
Installation
------------
Install From Source
^^^^^^^^^^^^^^^^^^^^
.. code:: sh
git clone git@github.com:BasisResearch/effectful.git
cd effectful
git checkout master
pip install -e .[pyro]
Install With Optional PyTorch/Pyro Support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``effectful`` has optional support for:
- `PyTorch `_ (tensors with named dimensions)
- `Pyro `_ (wrappers for Pyro effects)
- `Jax `_ (tensors with named dimensions)
- `Numpyro `_ (operations for Numpyro distributions)
To enable PyTorch support:
.. code:: sh
pip install effectful[torch]
Pyro support (which includes PyTorch support):
.. code:: sh
pip install effectful[pyro]
Jax support:
.. code:: sh
pip install effectful[jax]
Numpyro support (which includes Jax support):
.. code:: sh
pip install effectful[numpyro]
Getting Started
---------------
Here's an example demonstrating how ``effectful`` can be used to implement a simple DSL that performs arithmetic on terms with free variables.
.. code:: python
import functools
from effectful.ops.types import Term
from effectful.ops.syntax import defdata, defop
from effectful.ops.semantics import handler, evaluate, coproduct, fwd
add = defdata.dispatch(int).__add__
def beta_add(x: int, y: int) -> int:
match x, y:
case int(), int():
return x + y
case _:
return fwd()
def commute_add(x: int, y: int) -> int:
match x, y:
case Term(), int():
return y + x
case _:
return fwd()
def assoc_add(x: int, y: int) -> int:
match x, y:
case _, Term(op, (a, b)) if op == add:
return (x + a) + b
case _:
return fwd()
beta_rules = {add: beta_add}
commute_rules = {add: commute_add}
assoc_rules = {add: assoc_add}
eager_mixed = functools.reduce(coproduct, (beta_rules, commute_rules, assoc_rules))
We can represent free variables as operations with no arguments, generated using ``defop``:
.. code:: python
>>> x = defop(int, name="x")
>>> y = defop(int, name="y")
If we evaluate an expression containing free variables, we get a term:
.. code:: python
>>> e = 1 + 1 + (x() + 1) + (5 + y())
>>> print(e)
add(2, add(add(x(), 1), add(5, y())))
We can make the evaluation strategy smarter by taking advantage of the commutativity and associativity of addition, as expressed by the ``commute_add`` and ``assoc_add`` handlers.
.. code:: python
>>> with handler(eager_mixed):
>>> print(evaluate(e))
add(8, add(x(), y()))
Learn More
----------
More examples and API documentation can be found in the `docs `_.