sparc-pc 0.5.3__tar.gz

sparc_pc-0.5.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian Ciotinga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sparc_pc-0.5.3/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md pyproject.toml setup.py
+recursive-include sparc *.pyx *.pxd
+include sparc/py.typed

sparc_pc-0.5.3/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: sparc-pc
+Version: 0.5.3
+Summary: SparC: fast, modular sparse probabilistic circuits in Cython (CPU-only)
+Author: Adrian Ciotinga
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aciotinga/sparc
+Project-URL: Documentation, https://sparc-docs.readthedocs.io
+Project-URL: Repository, https://github.com/aciotinga/sparc
+Project-URL: Issues, https://github.com/aciotinga/sparc/issues
+Keywords: probabilistic-circuits,sum-product-networks,cython,wasserstein,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Cython
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Provides-Extra: gurobi
+Requires-Dist: gurobipy>=11.0; extra == "gurobi"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-randomly>=3.15; extra == "dev"
+Requires-Dist: scipy>=1.7; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: Cython>=3.0; extra == "docs"
+Requires-Dist: numpy>=1.20; extra == "docs"
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings-python; extra == "docs"
+Requires-Dist: mkdocs-gen-files; extra == "docs"
+Requires-Dist: mkdocs-literate-nav; extra == "docs"
+Requires-Dist: mkdocs-section-index; extra == "docs"
+Dynamic: license-file
+
+# SparC
+
+[![PyPI](https://img.shields.io/pypi/v/sparc-pc)](https://pypi.org/project/sparc-pc/)
+
+**Spar**se **C**ircuits — a fast, modular, CPU-only library for probabilistic
+circuits (PCs) written in Cython.
+
+Documentation: [https://sparc-docs.readthedocs.io](https://sparc-docs.readthedocs.io)
+(build locally with `pip install -e ".[docs]" && mkdocs serve`).
+
+## Highlights
+
+- **Speed**: typed Cython with C++ STL containers, `nogil` inner loops, and a
+  compiled/batched evaluation path.
+- **Modularity**: nodes dispatch through a C-level vtable, and all pairwise
+  queries share one tape/gradient engine. New leaf types and new queries are
+  added without editing existing files.
+- **Minimal deps**: `numpy` only at runtime. Transportation and assignment
+  problems are solved by built-in pure-Cython solvers.
+
+## Supported queries
+
+| Query | Math | Gradients w.r.t. | Docs |
+|-------|------|------------------|------|
+| CW | $W_p^p$ (Circuit-Wasserstein objective) | circuit2 | [queries](docs/guides/queries.md) |
+| GCW cross-term | Gromov-Circuit-Wasserstein cross-term | circuit2 | [queries](docs/guides/queries.md) |
+| Expectation | $E_Q[P(X)]$ | both circuits | [queries](docs/guides/queries.md) |
+| Log expectation | $\log E_Q[P(X)]$ | both circuits | [queries](docs/guides/queries.md) |
+| ESD | $E[d(X,X')^p]$ (two i.i.d. draws) | single circuit | [queries](docs/guides/queries.md) |
+
+CW and GCW gradient variants return gradients with respect to the **second**
+circuit only. Expectation queries return gradients for both circuits.
+
+## Supported structures
+
+| Constructor | Description | Docs |
+|-------------|-------------|------|
+| `HMM` / `GeneralizedHMM` | Latent-chain sequence models | [structures](docs/guides/structures.md) |
+| `HCLT` | Hidden tree from data (MI + MST) | [structures](docs/guides/structures.md) |
+| `PD` / `PDHCLT` | Recursive grid decompositions | [structures](docs/guides/structures.md) |
+| `RAT_SPN` | Randomized tensorized sum-product network | [structures](docs/guides/structures.md) |
+| `EmbeddingBuilder` | Random recursive PC with node reuse | [builders](docs/guides/builders.md) |
+
+Import structures from `sparc.structures` and builders from `sparc.builders`.
+
+## Install
+
+Prebuilt wheels are available for Linux, Windows, and macOS (Python 3.10–3.14):
+
+```bash
+pip install sparc-pc
+```
+
+The PyPI package name is `sparc-pc`; import as `sparc`:
+
+```python
+import sparc
+from sparc import Circuit
+```
+
+### From source (developers)
+
+SparC ships Cython/C++17 extensions, so a C++ compiler is required when
+installing from source or in editable mode:
+
+```bash
+pip install -e .            # build extensions in place
+pip install -e ".[dev]"     # + pytest, scipy, build tools
+pip install -e ".[docs]"    # + MkDocs documentation builder
+pip install -e ".[gurobi]"  # optional Gurobi extra (unused by core library)
+```
+
+See [Releasing](docs/releasing.md) for maintainer release steps.
+
+## Quick start
+
+```python
+import numpy as np
+from sparc import CategoricalInputNode, SumNode, ProductNode, Circuit
+
+x0 = CategoricalInputNode(id=0, scope_var=0, probabilities=[0.7, 0.3])
+x1 = CategoricalInputNode(id=1, scope_var=1, probabilities=[0.5, 0.5])
+prod = ProductNode(id=2, children=[x0, x1])
+root = SumNode(id=3, children=[prod], parameters=[1.0])
+
+circuit = Circuit(root)
+point = np.array([0, 1], dtype=np.int32)
+circuit.log_likelihood(point)
+circuit.sample(5, seed=0)  # ndarray (5, max_var+1)
+
+data = np.random.randint(0, 2, size=(1000, 2)).astype(np.int32)
+circuit.compile().log_likelihood(data)
+```
+
+### Training
+
+```python
+from sparc.optim import MLETrainer
+
+trainer = MLETrainer(circuit, lr=0.5)
+trainer.fit(dataset, epochs=100)
+```
+
+### Circuit distances
+
+```python
+from sparc import cw_distance, gcw_crossterm, gcw_coupling_circuit, PNormMetric
+
+cw_distance(p, q, metric=PNormMetric(p=2.0, scale=1.0))
+gcw_crossterm(circuit1, circuit2)
+gcw_coupling_circuit(circuit1, circuit2).sample(1000)
+```
+
+See the [documentation](docs/index.md) for compatibility rules, all leaf types,
+and extension points.
+
+## Package layout
+
+```
+sparc/
+  circuit.py       # high-level Circuit wrapper
+  nodes.pyx        # CircuitNode / Sum / Product / leaf nodes (+ vtable)
+  eval.pyx         # likelihood / sampling + CompiledCircuit
+  grad.pyx         # GradBundle + mean_log_likelihood_and_grad
+  metrics.pyx      # GroundMetric, PNormMetric
+  solvers/         # transport, assignment, northwest
+  queries/         # CW, GCW, expectation, ESD
+  builders/        # region graphs, embedding builders
+  structures/      # HMM, HCLT, PD, RAT-SPN, ...
+  io/              # gcw-circuit-v1 JSON serializer
+  optim.py         # simplex_step, apply_grads, MLETrainer
+docs/              # MkDocs site (guides, handbook, API reference)
+examples/          # runnable demo scripts
+tests/
+```
+
+## Examples
+
+```bash
+PYTHONPATH=. python examples/mle.py
+PYTHONPATH=. python examples/cw_minimization.py
+PYTHONPATH=. python examples/gcw_optimization.py --direction max
+PYTHONPATH=. python examples/dro.py
+```
+
+Full list: [docs/examples/overview.md](docs/examples/overview.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+
+pip install -e ".[docs]"
+mkdocs serve        # browse docs at http://127.0.0.1:8000
+mkdocs build        # static site in site/
+```
+
+## License
+
+MIT

sparc_pc-0.5.3/README.md

@@ -0,0 +1,161 @@
+# SparC
+
+[![PyPI](https://img.shields.io/pypi/v/sparc-pc)](https://pypi.org/project/sparc-pc/)
+
+**Spar**se **C**ircuits — a fast, modular, CPU-only library for probabilistic
+circuits (PCs) written in Cython.
+
+Documentation: [https://sparc-docs.readthedocs.io](https://sparc-docs.readthedocs.io)
+(build locally with `pip install -e ".[docs]" && mkdocs serve`).
+
+## Highlights
+
+- **Speed**: typed Cython with C++ STL containers, `nogil` inner loops, and a
+  compiled/batched evaluation path.
+- **Modularity**: nodes dispatch through a C-level vtable, and all pairwise
+  queries share one tape/gradient engine. New leaf types and new queries are
+  added without editing existing files.
+- **Minimal deps**: `numpy` only at runtime. Transportation and assignment
+  problems are solved by built-in pure-Cython solvers.
+
+## Supported queries
+
+| Query | Math | Gradients w.r.t. | Docs |
+|-------|------|------------------|------|
+| CW | $W_p^p$ (Circuit-Wasserstein objective) | circuit2 | [queries](docs/guides/queries.md) |
+| GCW cross-term | Gromov-Circuit-Wasserstein cross-term | circuit2 | [queries](docs/guides/queries.md) |
+| Expectation | $E_Q[P(X)]$ | both circuits | [queries](docs/guides/queries.md) |
+| Log expectation | $\log E_Q[P(X)]$ | both circuits | [queries](docs/guides/queries.md) |
+| ESD | $E[d(X,X')^p]$ (two i.i.d. draws) | single circuit | [queries](docs/guides/queries.md) |
+
+CW and GCW gradient variants return gradients with respect to the **second**
+circuit only. Expectation queries return gradients for both circuits.
+
+## Supported structures
+
+| Constructor | Description | Docs |
+|-------------|-------------|------|
+| `HMM` / `GeneralizedHMM` | Latent-chain sequence models | [structures](docs/guides/structures.md) |
+| `HCLT` | Hidden tree from data (MI + MST) | [structures](docs/guides/structures.md) |
+| `PD` / `PDHCLT` | Recursive grid decompositions | [structures](docs/guides/structures.md) |
+| `RAT_SPN` | Randomized tensorized sum-product network | [structures](docs/guides/structures.md) |
+| `EmbeddingBuilder` | Random recursive PC with node reuse | [builders](docs/guides/builders.md) |
+
+Import structures from `sparc.structures` and builders from `sparc.builders`.
+
+## Install
+
+Prebuilt wheels are available for Linux, Windows, and macOS (Python 3.10–3.14):
+
+```bash
+pip install sparc-pc
+```
+
+The PyPI package name is `sparc-pc`; import as `sparc`:
+
+```python
+import sparc
+from sparc import Circuit
+```
+
+### From source (developers)
+
+SparC ships Cython/C++17 extensions, so a C++ compiler is required when
+installing from source or in editable mode:
+
+```bash
+pip install -e .            # build extensions in place
+pip install -e ".[dev]"     # + pytest, scipy, build tools
+pip install -e ".[docs]"    # + MkDocs documentation builder
+pip install -e ".[gurobi]"  # optional Gurobi extra (unused by core library)
+```
+
+See [Releasing](docs/releasing.md) for maintainer release steps.
+
+## Quick start
+
+```python
+import numpy as np
+from sparc import CategoricalInputNode, SumNode, ProductNode, Circuit
+
+x0 = CategoricalInputNode(id=0, scope_var=0, probabilities=[0.7, 0.3])
+x1 = CategoricalInputNode(id=1, scope_var=1, probabilities=[0.5, 0.5])
+prod = ProductNode(id=2, children=[x0, x1])
+root = SumNode(id=3, children=[prod], parameters=[1.0])
+
+circuit = Circuit(root)
+point = np.array([0, 1], dtype=np.int32)
+circuit.log_likelihood(point)
+circuit.sample(5, seed=0)  # ndarray (5, max_var+1)
+
+data = np.random.randint(0, 2, size=(1000, 2)).astype(np.int32)
+circuit.compile().log_likelihood(data)
+```
+
+### Training
+
+```python
+from sparc.optim import MLETrainer
+
+trainer = MLETrainer(circuit, lr=0.5)
+trainer.fit(dataset, epochs=100)
+```
+
+### Circuit distances
+
+```python
+from sparc import cw_distance, gcw_crossterm, gcw_coupling_circuit, PNormMetric
+
+cw_distance(p, q, metric=PNormMetric(p=2.0, scale=1.0))
+gcw_crossterm(circuit1, circuit2)
+gcw_coupling_circuit(circuit1, circuit2).sample(1000)
+```
+
+See the [documentation](docs/index.md) for compatibility rules, all leaf types,
+and extension points.
+
+## Package layout
+
+```
+sparc/
+  circuit.py       # high-level Circuit wrapper
+  nodes.pyx        # CircuitNode / Sum / Product / leaf nodes (+ vtable)
+  eval.pyx         # likelihood / sampling + CompiledCircuit
+  grad.pyx         # GradBundle + mean_log_likelihood_and_grad
+  metrics.pyx      # GroundMetric, PNormMetric
+  solvers/         # transport, assignment, northwest
+  queries/         # CW, GCW, expectation, ESD
+  builders/        # region graphs, embedding builders
+  structures/      # HMM, HCLT, PD, RAT-SPN, ...
+  io/              # gcw-circuit-v1 JSON serializer
+  optim.py         # simplex_step, apply_grads, MLETrainer
+docs/              # MkDocs site (guides, handbook, API reference)
+examples/          # runnable demo scripts
+tests/
+```
+
+## Examples
+
+```bash
+PYTHONPATH=. python examples/mle.py
+PYTHONPATH=. python examples/cw_minimization.py
+PYTHONPATH=. python examples/gcw_optimization.py --direction max
+PYTHONPATH=. python examples/dro.py
+```
+
+Full list: [docs/examples/overview.md](docs/examples/overview.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+
+pip install -e ".[docs]"
+mkdocs serve        # browse docs at http://127.0.0.1:8000
+mkdocs build        # static site in site/
+```
+
+## License
+
+MIT

sparc_pc-0.5.3/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["setuptools>=61", "wheel", "Cython>=3.0", "numpy>=1.20"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sparc-pc"
+version = "0.5.3"
+description = "SparC: fast, modular sparse probabilistic circuits in Cython (CPU-only)"
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Adrian Ciotinga" }]
+keywords = [
+    "probabilistic-circuits",
+    "sum-product-networks",
+    "cython",
+    "wasserstein",
+    "machine-learning",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Cython",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "numpy>=1.20",
+]
+
+[project.optional-dependencies]
+gurobi = ["gurobipy>=11.0"]
+dev = [
+    "build>=1.0",
+    "pytest>=7.0",
+    "pytest-randomly>=3.15",
+    "scipy>=1.7",
+    "twine>=4.0",
+]
+docs = [
+    "Cython>=3.0",
+    "numpy>=1.20",
+    "mkdocs>=1.6,<2",
+    "mkdocs-material>=9.5,<10",
+    "mkdocstrings-python",
+    "mkdocs-gen-files",
+    "mkdocs-literate-nav",
+    "mkdocs-section-index",
+]
+
+[project.urls]
+Homepage = "https://github.com/aciotinga/sparc"
+Documentation = "https://sparc-docs.readthedocs.io"
+Repository = "https://github.com/aciotinga/sparc"
+Issues = "https://github.com/aciotinga/sparc/issues"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sparc*"]
+
+[tool.setuptools.package-data]
+"sparc" = ["*.pyx", "*.pxd", "py.typed"]
+
+[tool.cibuildwheel]
+build = "cp310-* cp311-* cp312-* cp313-* cp314-*"
+skip = "*-musllinux_* cp*t-*"
+test-command = "python -c \"import sparc; from sparc import Circuit; print(sparc.__version__)\""
+
+[tool.cibuildwheel.macos]
+archs = ["x86_64", "arm64"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "gurobi: requires gurobipy and a valid Gurobi license",
+    "gcw: GCW coupling / materialization tests (order- and platform-sensitive)",
+    "gcw_stress: heap/order stress tests for GCW memoization isolation",
+    "solver: direct unit tests for OT / assignment solvers",
+    "metrics: ground metric and metric-driven query behavior",
+    "eval: likelihood, sampling, and compiled batched evaluation",
+    "optim: simplex_step, apply_grads, MLETrainer",
+    "circuit: Circuit wrapper (clone, save/load, normalization)",
+    "queries: CW / GCW / exp / log_exp query behavior",
+    "integration: cross-module leaf-type integration tests",
+    "property: cross-cutting invariants (normalization, determinism)",
+    "nodes: node construction and validation",
+    "no_dual_path: opt out of object-graph vs compiled parametrization",
+]
+filterwarnings = [
+    "error::pytest.PytestUnraisableExceptionWarning",
+]

sparc_pc-0.5.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sparc_pc-0.5.3/setup.py

@@ -0,0 +1,73 @@
+import os
+import sys
+import sysconfig
+
+import numpy as np
+from Cython.Build import cythonize
+from setuptools import Extension, setup
+
+_fast_build = os.environ.get("SPARC_FAST_BUILD", "").lower() in ("1", "true", "yes")
+
+_cc = sysconfig.get_config_var("CC") or ""
+_is_msvc = (
+    sys.platform == "win32"
+    and "gcc" not in _cc.lower()
+    and "clang" not in _cc.lower()
+)
+
+if _is_msvc:
+    extra_compile_args = ["/std:c++17", "/Ox", "/fp:fast"]
+    extra_link_args = []
+    if not _fast_build:
+        extra_compile_args.append("/GL")
+        extra_link_args.append("/LTCG")
+else:
+    # Avoid -ffast-math: it breaks log-sum-exp guards (isfinite(-inf), -inf
+    # comparisons) and causes log_exp_query to return -1 instead of -inf on Linux.
+    extra_compile_args = ["-std=c++17", "-O3", "-funroll-loops"]
+    extra_link_args = []
+    if not _fast_build:
+        extra_compile_args.append("-flto")
+        extra_link_args.append("-flto")
+
+_numpy_include = np.get_include()
+
+# Every Cython extension module in SparC. All are C++ (libcpp containers,
+# C++ <random>, etc.).
+_pyx_modules = [
+    "sparc.nodes",
+    "sparc._graph",
+    "sparc.eval",
+    "sparc.grad",
+    "sparc.metrics",
+    "sparc.solvers.northwest",
+    "sparc.solvers.transport",
+    "sparc.solvers.assignment",
+    "sparc.queries._engine",
+    "sparc.queries.esd",
+    "sparc.queries.expectation",
+    "sparc.queries.cw",
+    "sparc.queries.gcw",
+]
+
+
+def _to_path(dotted: str) -> str:
+    return dotted.replace(".", "/") + ".pyx"
+
+
+ext_modules = cythonize(
+    [
+        Extension(
+            name,
+            [_to_path(name)],
+            language="c++",
+            include_dirs=[_numpy_include],
+            extra_compile_args=extra_compile_args,
+            extra_link_args=extra_link_args,
+        )
+        for name in _pyx_modules
+    ],
+    compiler_directives={"language_level": "3", "embedsignature": True},
+)
+
+setup(ext_modules=ext_modules)

sparc_pc-0.5.3/sparc/__init__.py

@@ -0,0 +1,114 @@
+"""SparC: fast, modular sparse probabilistic circuits in Cython (CPU-only).
+
+SparC implements probabilistic circuits (PCs) with typed Cython evaluation,
+differentiable Wasserstein-type queries, and composable structure builders.
+Import the high-level :class:`~sparc.circuit.Circuit` wrapper and query
+functions from this package; see subpackages :mod:`sparc.optim`,
+:mod:`sparc.builders`, :mod:`sparc.structures`, and :mod:`sparc.io` for
+training, random construction, built-in structures, and serialization.
+
+Install from PyPI with ``pip install sparc-pc`` (import name: ``sparc``).
+Full documentation: https://sparc-docs.readthedocs.io
+"""
+
+from __future__ import annotations
+
+import importlib
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("sparc-pc")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"
+
+__all__ = [
+    "Circuit",
+    "CircuitNode",
+    "SumNode",
+    "ProductNode",
+    "InputNode",
+    "FiniteDiscreteInputNode",
+    "CategoricalInputNode",
+    "BernoulliInputNode",
+    "IndicatorInputNode",
+    "LiteralInputNode",
+    "DiscreteLogisticInputNode",
+    "Evidence",
+    "RandomState",
+    "likelihood",
+    "log_likelihood",
+    "sample",
+    "CompiledCircuit",
+    "mean_log_likelihood_and_grad",
+    "GradBundle",
+    "GroundMetric",
+    "PNormMetric",
+    "CircuitSerializer",
+    "load_learned_pc",
+    "cw_distance",
+    "cw_distance_and_grad",
+    "expected_squared_distance",
+    "expected_squared_distance_and_grad",
+    "exp_query",
+    "exp_query_and_grad",
+    "log_exp_query",
+    "log_exp_query_and_grad",
+    "gcw_crossterm",
+    "gcw_crossterm_and_grad",
+    "gcw_coupling_circuit",
+]
+
+_LAZY_EXPORTS = {
+    "Circuit": ("sparc.circuit", "Circuit"),
+    "CompiledCircuit": ("sparc._graph", "CompiledCircuit"),
+    "likelihood": ("sparc.eval", "likelihood"),
+    "log_likelihood": ("sparc.eval", "log_likelihood"),
+    "sample": ("sparc.eval", "sample"),
+    "GradBundle": ("sparc.grad", "GradBundle"),
+    "mean_log_likelihood_and_grad": ("sparc.grad", "mean_log_likelihood_and_grad"),
+    "CircuitSerializer": ("sparc.io", "CircuitSerializer"),
+    "load_learned_pc": ("sparc.io", "load_learned_pc"),
+    "GroundMetric": ("sparc.metrics", "GroundMetric"),
+    "PNormMetric": ("sparc.metrics", "PNormMetric"),
+    "CircuitNode": ("sparc.nodes", "CircuitNode"),
+    "SumNode": ("sparc.nodes", "SumNode"),
+    "ProductNode": ("sparc.nodes", "ProductNode"),
+    "InputNode": ("sparc.nodes", "InputNode"),
+    "FiniteDiscreteInputNode": ("sparc.nodes", "FiniteDiscreteInputNode"),
+    "CategoricalInputNode": ("sparc.nodes", "CategoricalInputNode"),
+    "BernoulliInputNode": ("sparc.nodes", "BernoulliInputNode"),
+    "IndicatorInputNode": ("sparc.nodes", "IndicatorInputNode"),
+    "LiteralInputNode": ("sparc.nodes", "LiteralInputNode"),
+    "DiscreteLogisticInputNode": ("sparc.nodes", "DiscreteLogisticInputNode"),
+    "Evidence": ("sparc.nodes", "Evidence"),
+    "RandomState": ("sparc.nodes", "RandomState"),
+    "cw_distance": ("sparc.queries", "cw_distance"),
+    "cw_distance_and_grad": ("sparc.queries", "cw_distance_and_grad"),
+    "expected_squared_distance": ("sparc.queries", "expected_squared_distance"),
+    "expected_squared_distance_and_grad": (
+        "sparc.queries",
+        "expected_squared_distance_and_grad",
+    ),
+    "exp_query": ("sparc.queries", "exp_query"),
+    "exp_query_and_grad": ("sparc.queries", "exp_query_and_grad"),
+    "log_exp_query": ("sparc.queries", "log_exp_query"),
+    "log_exp_query_and_grad": ("sparc.queries", "log_exp_query_and_grad"),
+    "gcw_crossterm": ("sparc.queries", "gcw_crossterm"),
+    "gcw_crossterm_and_grad": ("sparc.queries", "gcw_crossterm_and_grad"),
+    "gcw_coupling_circuit": ("sparc.queries", "gcw_coupling_circuit"),
+}
+
+
+def __getattr__(name: str):
+    spec = _LAZY_EXPORTS.get(name)
+    if spec is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attr_name = spec
+    module = importlib.import_module(module_name)
+    value = getattr(module, attr_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))