.. 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 <https://basisresearch.github.io/chirho/getting_started.html>`_
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 <https://pytorch.org/>`_ (tensors with named dimensions)
- `Pyro <https://pyro.ai/>`_ (wrappers for Pyro effects)
- `Jax <https://docs.jax.dev/en/latest/index.html>`_ (tensors with named dimensions)
- `Numpyro <https://num.pyro.ai>`_ (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 <https://basisresearch.github.io/effectful/index.html>`_.
Raw data
{
"_id": null,
"home_page": null,
"name": "effectful",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.12",
"maintainer_email": null,
"keywords": "machine learning, statistics, probabilistic programming, bayesian modeling, pytorch",
"author": "Basis",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1a/d7/01e8b85d87f4214abce87898a18b37f124a9dc6e57b5ec04cfbc4ccd9690/effectful-0.2.3.tar.gz",
"platform": null,
"description": ".. index-inclusion-marker\n\nEffectful\n=========\n\nEffectful is an algebraic effect system for Python, intended for use in the\nimplementation of probabilistic programming languages. It is a core component of\nthe `ChiRho <https://basisresearch.github.io/chirho/getting_started.html>`_\ncausal modeling language.\n\nInstallation\n------------\n\nInstall From Source\n^^^^^^^^^^^^^^^^^^^^\n.. code:: sh\n\n git clone git@github.com:BasisResearch/effectful.git\n cd effectful\n git checkout master\n pip install -e .[pyro]\n\nInstall With Optional PyTorch/Pyro Support\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n``effectful`` has optional support for:\n\n- `PyTorch <https://pytorch.org/>`_ (tensors with named dimensions)\n- `Pyro <https://pyro.ai/>`_ (wrappers for Pyro effects)\n- `Jax <https://docs.jax.dev/en/latest/index.html>`_ (tensors with named dimensions)\n- `Numpyro <https://num.pyro.ai>`_ (operations for Numpyro distributions)\n\nTo enable PyTorch support:\n\n.. code:: sh\n\n pip install effectful[torch]\n\nPyro support (which includes PyTorch support):\n\n.. code:: sh\n\n pip install effectful[pyro]\n\nJax support:\n\n.. code:: sh\n\n pip install effectful[jax]\n\nNumpyro support (which includes Jax support):\n\n.. code:: sh\n\n pip install effectful[numpyro]\n\nGetting Started\n---------------\n\nHere's an example demonstrating how ``effectful`` can be used to implement a simple DSL that performs arithmetic on terms with free variables.\n\n.. code:: python\n\n import functools\n\n from effectful.ops.types import Term\n from effectful.ops.syntax import defdata, defop\n from effectful.ops.semantics import handler, evaluate, coproduct, fwd\n\n add = defdata.dispatch(int).__add__\n\n def beta_add(x: int, y: int) -> int:\n match x, y:\n case int(), int():\n return x + y\n case _:\n return fwd()\n\n def commute_add(x: int, y: int) -> int:\n match x, y:\n case Term(), int():\n return y + x\n case _:\n return fwd()\n\n def assoc_add(x: int, y: int) -> int:\n match x, y:\n case _, Term(op, (a, b)) if op == add:\n return (x + a) + b\n case _:\n return fwd()\n\n beta_rules = {add: beta_add}\n commute_rules = {add: commute_add}\n assoc_rules = {add: assoc_add}\n\n eager_mixed = functools.reduce(coproduct, (beta_rules, commute_rules, assoc_rules))\n\nWe can represent free variables as operations with no arguments, generated using ``defop``:\n\n.. code:: python\n\n >>> x = defop(int, name=\"x\")\n >>> y = defop(int, name=\"y\")\n\nIf we evaluate an expression containing free variables, we get a term:\n\n.. code:: python\n\n >>> e = 1 + 1 + (x() + 1) + (5 + y())\n >>> print(e)\n add(2, add(add(x(), 1), add(5, y())))\n\nWe 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.\n\n.. code:: python\n\n >>> with handler(eager_mixed):\n >>> print(evaluate(e))\n add(8, add(x(), y()))\n\nLearn More\n----------\n\nMore examples and API documentation can be found in the `docs <https://basisresearch.github.io/effectful/index.html>`_.\n",
"bugtrack_url": null,
"license": null,
"summary": "Metaprogramming infrastructure",
"version": "0.2.3",
"project_urls": {
"Bug Tracker": "https://github.com/BasisResearch/effectful/issues",
"Homepage": "https://www.basis.ai/",
"Source": "https://github.com/BasisResearch/effectful"
},
"split_keywords": [
"machine learning",
" statistics",
" probabilistic programming",
" bayesian modeling",
" pytorch"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "89b6753f5aca697798b6f3339d067f1bec8b9621d0e638e69824cb36d29b945f",
"md5": "68dce8bf70a94aabb2cdf75df856f1f1",
"sha256": "029a499f91d8774fe5fdd6094ffe3e80a01cab3f3268da3586a5fb7a1cd9514a"
},
"downloads": -1,
"filename": "effectful-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68dce8bf70a94aabb2cdf75df856f1f1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.12",
"size": 64861,
"upload_time": "2025-10-20T18:26:37",
"upload_time_iso_8601": "2025-10-20T18:26:37.144171Z",
"url": "https://files.pythonhosted.org/packages/89/b6/753f5aca697798b6f3339d067f1bec8b9621d0e638e69824cb36d29b945f/effectful-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1ad701e8b85d87f4214abce87898a18b37f124a9dc6e57b5ec04cfbc4ccd9690",
"md5": "7d2fb48098aa807a8878449c64f0ad01",
"sha256": "203f8ea86a0b2aa982efd38f58c0fa5ed81cf3eb3db248ef4b04bc5ec4f22e74"
},
"downloads": -1,
"filename": "effectful-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "7d2fb48098aa807a8878449c64f0ad01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.12",
"size": 98158,
"upload_time": "2025-10-20T18:26:38",
"upload_time_iso_8601": "2025-10-20T18:26:38.350227Z",
"url": "https://files.pythonhosted.org/packages/1a/d7/01e8b85d87f4214abce87898a18b37f124a9dc6e57b5ec04cfbc4ccd9690/effectful-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 18:26:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BasisResearch",
"github_project": "effectful",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "effectful"
}
JSON
