surd 1.1.0__tar.gz

surd-1.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.ipynb_checkpoints/
+.DS_Store
+# Packaging and tests
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+# Data generated by the example notebooks
+data/*.npy

surd-1.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 1.1.0 (2026-10-30)
+
+- `surd` is an installable package with a `src/` layout and a
+  `pyproject.toml`. `pip install .` works from a clone. The public functions
+  keep their names, signatures and results: `surd.surd`, `surd.surd_hd`,
+  `surd.run`, `surd.run_parallel`, `surd.run_multiple_lags`, `surd.plot`,
+  `surd.plot_nlabels`, `surd.plot_multiple_lags` and `surd.nice_print`.
+- `it_tools`, `analytic_eqs` and `transport_map` are submodules
+  (`surd.it_tools`, `surd.analytic_eqs`, `surd.transport_map`). The last
+  two load on first access, so `import surd` does not need `mpart` and
+  does not seed the NumPy random generator.
+- Optional extras: `parallel` (pymp-pypi, Linux and macOS), `transport`
+  (mpart) and `examples` (jupyterlab).
+- `utils/` keeps working for scripts that add it to `sys.path`. Its files
+  now load the package.
+- The example notebooks import the installed package and fall back to
+  `../src` from a plain clone.
+- Test suite (`pytest`) with the logic gates of example E01, the benchmark
+  systems of E02, the information-theoretic tools, bounds of the terms and
+  the causality leak, `surd.run_parallel` with and without pymp, and the
+  equivalence between the `utils/` import path and the package.
+- Continuous integration on Linux, macOS and Windows with Python 3.9 and
+  3.12, and a release workflow that builds and publishes to PyPI.
+- `CITATION.cff` with the Nature Communications paper as preferred
+  citation.
+- Portable `environment.yml` (only the packages the code uses) and a
+  `requirements.txt` for pip.
+- pymp is optional. Without it, `surd.run_parallel` runs the targets one
+  after another and returns the same result. This makes the code run on
+  Windows.
+- README rewritten: installation, quick start, table of examples and the
+  main functions.
+
+## 1.0.1 (2024-09-11)
+
+- Fixes: file names of the turbulent boundary layer data (example E10) and
+  README corrections.
+
+## 1.0.0 (2024-09-03)
+
+- Initial release.

surd-1.1.0/CITATION.cff

@@ -0,0 +1,46 @@
+cff-version: 1.2.0
+message: "If you use SURD, please cite the paper below (preferred-citation)."
+type: software
+title: "SURD: Synergistic-Unique-Redundant Decomposition of causality"
+version: 1.1.0
+date-released: 2026-10-30
+license: MIT
+repository-code: "https://github.com/ALD-Lab/SURD"
+url: "https://github.com/ALD-Lab/SURD"
+abstract: >-
+  Python package that measures the information that past observations of a
+  set of variables carry about the future of a target variable and decomposes
+  it into redundant, unique and synergistic contributions, together with the
+  causality leak from unobserved variables.
+keywords:
+  - causality
+  - causal inference
+  - information theory
+  - synergy
+  - redundancy
+  - time series
+authors:
+  - family-names: "Martínez-Sánchez"
+    given-names: "Álvaro"
+  - family-names: "Arranz"
+    given-names: "Gonzalo"
+  - family-names: "Lozano-Durán"
+    given-names: "Adrián"
+preferred-citation:
+  type: article
+  title: "Decomposing causality into its synergistic, unique, and redundant components"
+  authors:
+    - family-names: "Martínez-Sánchez"
+      given-names: "Álvaro"
+    - family-names: "Arranz"
+      given-names: "Gonzalo"
+    - family-names: "Lozano-Durán"
+      given-names: "Adrián"
+  journal: "Nature Communications"
+  year: 2024
+  month: 11
+  volume: 15
+  issue: 1
+  start: 9296
+  issn: "2041-1723"
+  doi: "10.1038/s41467-024-53373-4"

surd-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MIT Computational Turbulence Group
+
+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.

surd-1.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: surd
+Version: 1.1.0
+Summary: Synergistic-Unique-Redundant Decomposition of causality for time series
+Project-URL: Repository, https://github.com/ALD-Lab/SURD
+Project-URL: Paper, https://doi.org/10.1038/s41467-024-53373-4
+Project-URL: Changelog, https://github.com/ALD-Lab/SURD/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ALD-Lab/SURD/issues
+Author: Álvaro Martínez-Sánchez, Gonzalo Arranz, Adrián Lozano-Durán
+License-Expression: MIT
+License-File: LICENSE
+Keywords: causal inference,causality,information theory,mutual information,redundancy,synergy,time series,turbulence
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: tqdm
+Provides-Extra: examples
+Requires-Dist: jupyterlab; extra == 'examples'
+Provides-Extra: parallel
+Requires-Dist: pymp-pypi; (platform_system != 'Windows') and extra == 'parallel'
+Provides-Extra: transport
+Requires-Dist: mpart; extra == 'transport'
+Description-Content-Type: text/markdown
+
+# SURD: Synergistic-Unique-Redundant Decomposition of causality
+
+[![tests](https://github.com/ALD-Lab/SURD/actions/workflows/tests.yml/badge.svg)](https://github.com/ALD-Lab/SURD/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/surd.svg)](https://pypi.org/project/surd/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Paper](https://img.shields.io/badge/Nat.%20Commun.-10.1038%2Fs41467--024--53373--4-blue)](https://doi.org/10.1038/s41467-024-53373-4)
+
+SURD is a method for causal inference in time series. It measures the information that past observations of a set of variables carry about the future of a target variable and splits it into redundant, unique and synergistic contributions. The method also quantifies the causality leak, the part of the future of the target that the observed variables cannot explain. SURD needs only pairs of past and future events, so it applies to simulations and experiments alike. It handles several variables, dependencies at different time lags and instantaneous links. The method is described in Martínez-Sánchez, Arranz & Lozano-Durán, *Nature Communications* 15, 9296 (2024).
+
+![SURD diagram](https://github.com/user-attachments/assets/937fa18d-1179-4cfe-ae5a-e262582614a0)
+
+## Installation
+
+From PyPI:
+```sh
+pip install surd
+```
+
+From a clone of this repository:
+```sh
+git clone https://github.com/ALD-Lab/SURD.git
+cd SURD
+pip install .
+```
+
+With conda, the environment file installs the dependencies and the package:
+```sh
+conda env create -f environment.yml
+conda activate surd
+```
+
+SURD depends on NumPy, SciPy, Matplotlib and tqdm and runs on Python 3.9 or newer, on Linux, macOS and Windows. Three optional extras exist:
+
+- `pip install "surd[parallel]"` adds `pymp-pypi`, which runs the loop over target variables of `surd.run_parallel` in parallel (Linux and macOS). Without it the targets run one after another with the same result.
+- `pip install "surd[transport]"` adds `mpart` for density estimation with transport maps (example E07). On `osx-arm64` use `pip install mpart`, since the conda package does not exist for that platform. See the [MParT documentation](https://measuretransport.github.io/MParT/).
+- `pip install "surd[examples]"` adds JupyterLab to run the notebooks.
+
+The cost of SURD grows with the number of variables and bins, since it estimates joint probability distributions. The examples run on a laptop with 16 GB of RAM.
+
+## Quick start
+
+Two independent bits and a target equal to their XOR one step later. Each bit alone says nothing about the target, so the information is synergistic.
+
+```python
+import numpy as np
+import surd
+
+rng = np.random.default_rng(0)
+q1, q2 = rng.integers(0, 2, size=(2, 200_000))    # two independent bits in time
+target = np.roll(q1 ^ q2, 1)                      # their XOR, one step later
+Y = np.vstack([target[1:], q1[:-1], q2[:-1]])     # future of the target first, sources after
+hist, _ = np.histogramdd(Y.T, bins=2)
+I_R, I_S, MI, info_leak = surd.surd(hist)
+surd.nice_print(I_R, I_S, MI, info_leak)
+```
+
+```
+    Redundant (R):
+        (1, 2)      : 0.0000
+    Unique (U):
+        (1,)        : 0.0000
+        (2,)        : 0.0000
+    Synergystic (S):
+        (1, 2)      : 1.0000
+    Information Leak:  0.00%
+```
+
+## How to use the method
+
+The input is a histogram of the joint distribution of the future of the target and the present of the sources. Axis 0 is the target and axes 1 to N are the sources. The outputs are dictionaries keyed by tuples of source indices, counted from 1.
+
+| Function | What it does |
+|---|---|
+| `surd.surd(p)` | Decomposition of the histogram `p`. Returns `I_R` (redundant terms, with the unique terms under the one-element keys), `I_S` (synergistic terms), `MI` (mutual information of each subset of sources with the target) and `info_leak`, the causality leak in [0, 1]. |
+| `surd.surd_hd(Y, nbins, max_combs)` | Same decomposition from the signals `Y` (target first) for systems with many variables. Synergies are computed up to `max_combs` sources at a time. Returns `I_R`, `I_S` and `MI`. |
+| `surd.run(X, nvars, nlag, nbins, axs)` | Runs `surd.surd` with each of the `nvars` signals of `X` as target at lag `nlag`, prints and plots the result. |
+| `surd.run_parallel(...)` | Same as `surd.run`, with the targets in parallel when `pymp` is available. |
+| `surd.run_multiple_lags(X, nvars, nlag, nbins, max_combs, axs)` | Same as `surd.run` with all lags from 1 to `nlag` as sources. |
+| `surd.nice_print(I_R, I_S, MI, info_leak)` | Prints the terms normalized by the mutual information of the full set of sources and the leak in percent. |
+| `surd.plot(I_R, I_S, info_leak, axs, nvars, threshold)` | Bar chart of the normalized terms (blue redundant, red unique, orange synergistic) and a separate bar for the leak. |
+
+`surd.it_tools` has the entropies, conditional entropies, mutual information and transfer entropy used by the method. `surd.analytic_eqs` has the benchmark systems of the paper. `surd.transport_map` estimates densities with transport maps and needs `mpart`.
+
+Scripts written for the previous layout, which added `utils/` to `sys.path` and imported `surd`, `it_tools`, `analytic_eqs` and `transport_map` as top-level modules, keep working. The files in `utils/` load the package.
+
+## Examples
+
+The notebooks in [`examples/`](examples) reproduce the cases of the paper. Run them from the `examples` folder. They import the installed package and fall back to `../src` from a plain clone.
+
+| Notebook | What it shows |
+|---|---|
+| [E01](examples/E01_logic_gates.ipynb) | Logic gates. A duplicated source is redundant, a copied source is unique, an XOR is synergistic. |
+| [E02](examples/E02_building_blocks.ipynb) | Building blocks of causal interactions: mediator, confounder, synergistic collider and redundant collider. |
+| [E03](examples/E03_energy_cascade.ipynb) | Energy cascade in isotropic turbulence. Causality between the energy transfer at four scales from a direct numerical simulation. |
+| [E04](examples/E04_lagged_dependencies.ipynb) | Stochastic systems with dependencies at several time lags, linear and nonlinear. |
+| [E05](examples/E05_Moran_effect.ipynb) | Moran effect. Two populations driven by a common environmental forcing that is not observed. |
+| [E06](examples/E06_logistic_system.ipynb) | Coupled logistic maps with one-way and two-way coupling. |
+| [E07](examples/E07_transport_map.ipynb) | Density estimation with transport maps instead of histograms (needs `mpart`). |
+| [E08](examples/E08_eight_species.ipynb) | System with eight interacting species. Decomposition with synergies truncated at a given order. |
+| [E09](examples/E09_contemporaneous.ipynb) | Systems with contemporaneous links on top of mediator, confounder and synergistic interactions. |
+| [E10](examples/E10_inner_outer.ipynb) | Experimental data from a turbulent boundary layer. Causality between inner-layer and outer-layer velocity motions as a function of the time lag. |
+
+The data for E03 and E10 are in [`data/`](data). E02 writes the signals it generates to `data/` on the first run.
+
+## Citation
+
+If you use SURD in your research or software, please cite the paper:
+
+```bibtex
+@article{surd,
+author={Mart{\'\i}nez-S{\'a}nchez, {\'A}lvaro and Arranz, Gonzalo and Lozano-Dur{\'a}n, Adri{\'a}n},
+title={Decomposing causality into its synergistic, unique, and redundant components},
+journal={Nature Communications},
+year={2024},
+month={Nov},
+day={01},
+volume={15},
+number={1},
+pages={9296},
+issn={2041-1723},
+doi={10.1038/s41467-024-53373-4}
+}
+```
+
+The file [`CITATION.cff`](CITATION.cff) carries the same reference in machine-readable form.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

surd-1.1.0/README.md

@@ -0,0 +1,129 @@
+# SURD: Synergistic-Unique-Redundant Decomposition of causality
+
+[![tests](https://github.com/ALD-Lab/SURD/actions/workflows/tests.yml/badge.svg)](https://github.com/ALD-Lab/SURD/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/surd.svg)](https://pypi.org/project/surd/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Paper](https://img.shields.io/badge/Nat.%20Commun.-10.1038%2Fs41467--024--53373--4-blue)](https://doi.org/10.1038/s41467-024-53373-4)
+
+SURD is a method for causal inference in time series. It measures the information that past observations of a set of variables carry about the future of a target variable and splits it into redundant, unique and synergistic contributions. The method also quantifies the causality leak, the part of the future of the target that the observed variables cannot explain. SURD needs only pairs of past and future events, so it applies to simulations and experiments alike. It handles several variables, dependencies at different time lags and instantaneous links. The method is described in Martínez-Sánchez, Arranz & Lozano-Durán, *Nature Communications* 15, 9296 (2024).
+
+![SURD diagram](https://github.com/user-attachments/assets/937fa18d-1179-4cfe-ae5a-e262582614a0)
+
+## Installation
+
+From PyPI:
+```sh
+pip install surd
+```
+
+From a clone of this repository:
+```sh
+git clone https://github.com/ALD-Lab/SURD.git
+cd SURD
+pip install .
+```
+
+With conda, the environment file installs the dependencies and the package:
+```sh
+conda env create -f environment.yml
+conda activate surd
+```
+
+SURD depends on NumPy, SciPy, Matplotlib and tqdm and runs on Python 3.9 or newer, on Linux, macOS and Windows. Three optional extras exist:
+
+- `pip install "surd[parallel]"` adds `pymp-pypi`, which runs the loop over target variables of `surd.run_parallel` in parallel (Linux and macOS). Without it the targets run one after another with the same result.
+- `pip install "surd[transport]"` adds `mpart` for density estimation with transport maps (example E07). On `osx-arm64` use `pip install mpart`, since the conda package does not exist for that platform. See the [MParT documentation](https://measuretransport.github.io/MParT/).
+- `pip install "surd[examples]"` adds JupyterLab to run the notebooks.
+
+The cost of SURD grows with the number of variables and bins, since it estimates joint probability distributions. The examples run on a laptop with 16 GB of RAM.
+
+## Quick start
+
+Two independent bits and a target equal to their XOR one step later. Each bit alone says nothing about the target, so the information is synergistic.
+
+```python
+import numpy as np
+import surd
+
+rng = np.random.default_rng(0)
+q1, q2 = rng.integers(0, 2, size=(2, 200_000))    # two independent bits in time
+target = np.roll(q1 ^ q2, 1)                      # their XOR, one step later
+Y = np.vstack([target[1:], q1[:-1], q2[:-1]])     # future of the target first, sources after
+hist, _ = np.histogramdd(Y.T, bins=2)
+I_R, I_S, MI, info_leak = surd.surd(hist)
+surd.nice_print(I_R, I_S, MI, info_leak)
+```
+
+```
+    Redundant (R):
+        (1, 2)      : 0.0000
+    Unique (U):
+        (1,)        : 0.0000
+        (2,)        : 0.0000
+    Synergystic (S):
+        (1, 2)      : 1.0000
+    Information Leak:  0.00%
+```
+
+## How to use the method
+
+The input is a histogram of the joint distribution of the future of the target and the present of the sources. Axis 0 is the target and axes 1 to N are the sources. The outputs are dictionaries keyed by tuples of source indices, counted from 1.
+
+| Function | What it does |
+|---|---|
+| `surd.surd(p)` | Decomposition of the histogram `p`. Returns `I_R` (redundant terms, with the unique terms under the one-element keys), `I_S` (synergistic terms), `MI` (mutual information of each subset of sources with the target) and `info_leak`, the causality leak in [0, 1]. |
+| `surd.surd_hd(Y, nbins, max_combs)` | Same decomposition from the signals `Y` (target first) for systems with many variables. Synergies are computed up to `max_combs` sources at a time. Returns `I_R`, `I_S` and `MI`. |
+| `surd.run(X, nvars, nlag, nbins, axs)` | Runs `surd.surd` with each of the `nvars` signals of `X` as target at lag `nlag`, prints and plots the result. |
+| `surd.run_parallel(...)` | Same as `surd.run`, with the targets in parallel when `pymp` is available. |
+| `surd.run_multiple_lags(X, nvars, nlag, nbins, max_combs, axs)` | Same as `surd.run` with all lags from 1 to `nlag` as sources. |
+| `surd.nice_print(I_R, I_S, MI, info_leak)` | Prints the terms normalized by the mutual information of the full set of sources and the leak in percent. |
+| `surd.plot(I_R, I_S, info_leak, axs, nvars, threshold)` | Bar chart of the normalized terms (blue redundant, red unique, orange synergistic) and a separate bar for the leak. |
+
+`surd.it_tools` has the entropies, conditional entropies, mutual information and transfer entropy used by the method. `surd.analytic_eqs` has the benchmark systems of the paper. `surd.transport_map` estimates densities with transport maps and needs `mpart`.
+
+Scripts written for the previous layout, which added `utils/` to `sys.path` and imported `surd`, `it_tools`, `analytic_eqs` and `transport_map` as top-level modules, keep working. The files in `utils/` load the package.
+
+## Examples
+
+The notebooks in [`examples/`](examples) reproduce the cases of the paper. Run them from the `examples` folder. They import the installed package and fall back to `../src` from a plain clone.
+
+| Notebook | What it shows |
+|---|---|
+| [E01](examples/E01_logic_gates.ipynb) | Logic gates. A duplicated source is redundant, a copied source is unique, an XOR is synergistic. |
+| [E02](examples/E02_building_blocks.ipynb) | Building blocks of causal interactions: mediator, confounder, synergistic collider and redundant collider. |
+| [E03](examples/E03_energy_cascade.ipynb) | Energy cascade in isotropic turbulence. Causality between the energy transfer at four scales from a direct numerical simulation. |
+| [E04](examples/E04_lagged_dependencies.ipynb) | Stochastic systems with dependencies at several time lags, linear and nonlinear. |
+| [E05](examples/E05_Moran_effect.ipynb) | Moran effect. Two populations driven by a common environmental forcing that is not observed. |
+| [E06](examples/E06_logistic_system.ipynb) | Coupled logistic maps with one-way and two-way coupling. |
+| [E07](examples/E07_transport_map.ipynb) | Density estimation with transport maps instead of histograms (needs `mpart`). |
+| [E08](examples/E08_eight_species.ipynb) | System with eight interacting species. Decomposition with synergies truncated at a given order. |
+| [E09](examples/E09_contemporaneous.ipynb) | Systems with contemporaneous links on top of mediator, confounder and synergistic interactions. |
+| [E10](examples/E10_inner_outer.ipynb) | Experimental data from a turbulent boundary layer. Causality between inner-layer and outer-layer velocity motions as a function of the time lag. |
+
+The data for E03 and E10 are in [`data/`](data). E02 writes the signals it generates to `data/` on the first run.
+
+## Citation
+
+If you use SURD in your research or software, please cite the paper:
+
+```bibtex
+@article{surd,
+author={Mart{\'\i}nez-S{\'a}nchez, {\'A}lvaro and Arranz, Gonzalo and Lozano-Dur{\'a}n, Adri{\'a}n},
+title={Decomposing causality into its synergistic, unique, and redundant components},
+journal={Nature Communications},
+year={2024},
+month={Nov},
+day={01},
+volume={15},
+number={1},
+pages={9296},
+issn={2041-1723},
+doi={10.1038/s41467-024-53373-4}
+}
+```
+
+The file [`CITATION.cff`](CITATION.cff) carries the same reference in machine-readable form.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

surd-1.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "surd"
+dynamic = ["version"]
+description = "Synergistic-Unique-Redundant Decomposition of causality for time series"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [
+    { name = "Álvaro Martínez-Sánchez" },
+    { name = "Gonzalo Arranz" },
+    { name = "Adrián Lozano-Durán" },
+]
+keywords = [
+    "causality",
+    "causal inference",
+    "information theory",
+    "mutual information",
+    "synergy",
+    "redundancy",
+    "time series",
+    "turbulence",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy",
+    "scipy",
+    "matplotlib",
+    "tqdm",
+]
+
+[project.optional-dependencies]
+# Parallel loop over target variables in surd.run_parallel (not on Windows).
+parallel = ["pymp-pypi; platform_system != 'Windows'"]
+# Density estimation with transport maps (surd.transport_map, example E07).
+transport = ["mpart"]
+# Running the example notebooks.
+examples = ["jupyterlab"]
+
+[project.urls]
+Repository = "https://github.com/ALD-Lab/SURD"
+Paper = "https://doi.org/10.1038/s41467-024-53373-4"
+Changelog = "https://github.com/ALD-Lab/SURD/blob/main/CHANGELOG.md"
+Issues = "https://github.com/ALD-Lab/SURD/issues"
+
+[tool.hatch.version]
+path = "src/surd/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/surd"]
+
+[tool.hatch.build.targets.sdist]
+# The data files and the executed notebooks are large and stay in the
+# repository; the source distribution carries only the package and its tests.
+only-include = [
+    "src/surd",
+    "tests",
+    "CHANGELOG.md",
+    "CITATION.cff",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+filterwarnings = [
+    "ignore::DeprecationWarning:pymp",
+]

surd-1.1.0/src/surd/__init__.py

@@ -0,0 +1,77 @@
+"""SURD: Synergistic-Unique-Redundant Decomposition of causality.
+
+SURD measures the information that past observations of a set of source
+variables carry about the future of a target variable and splits it into
+redundant, unique and synergistic contributions. The remaining uncertainty
+is the causality leak from unobserved variables.
+
+Reference: Martínez-Sánchez, Arranz & Lozano-Durán, "Decomposing causality
+into its synergistic, unique, and redundant components", Nature
+Communications 15, 9296 (2024). https://doi.org/10.1038/s41467-024-53373-4
+
+Typical use::
+
+    import numpy as np
+    import surd
+
+    hist, _ = np.histogramdd(Y.T, bins)      # Y[0] target, Y[1:] sources
+    I_R, I_S, MI, info_leak = surd.surd(hist)
+    surd.nice_print(I_R, I_S, MI, info_leak)
+
+Submodules:
+
+- ``surd.it_tools``: entropies, mutual information and transfer entropy
+  on discrete distributions.
+- ``surd.analytic_eqs``: the stochastic benchmark systems of the paper
+  (mediator, confounder, synergistic and redundant colliders).
+- ``surd.transport_map``: density estimation with triangular transport
+  maps. Imported on first access and needs the optional ``mpart`` package.
+"""
+
+import importlib
+
+from . import it_tools
+from .core import (
+    nice_print,
+    plot,
+    plot_multiple_lags,
+    plot_nlabels,
+    run,
+    run_multiple_lags,
+    run_parallel,
+    surd,
+    surd_hd,
+)
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "surd",
+    "surd_hd",
+    "run",
+    "run_parallel",
+    "run_multiple_lags",
+    "plot",
+    "plot_nlabels",
+    "plot_multiple_lags",
+    "nice_print",
+    "it_tools",
+    "analytic_eqs",
+    "transport_map",
+    "__version__",
+]
+
+# Submodules loaded on first access. ``analytic_eqs`` seeds NumPy's global
+# random generator when imported, and ``transport_map`` needs ``mpart``,
+# so neither is imported by a plain ``import surd``.
+_LAZY_SUBMODULES = ("analytic_eqs", "transport_map")
+
+
+def __getattr__(name):
+    if name in _LAZY_SUBMODULES:
+        return importlib.import_module(f"{__name__}.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_SUBMODULES))

surd-1.1.0/src/surd/analytic_eqs.py

@@ -0,0 +1,39 @@
+import numpy as np
+np.random.seed(10)
+
+def mediator(N):
+    q1, q2, q3 = np.zeros(N), np.zeros(N), np.zeros(N)
+    W1, W2, W3 = np.random.normal(0, 1, N), np.random.normal(0, 1, N), np.random.normal(0, 1, N)
+    for n in range(N-1):
+        q1[n+1] = np.sin(q2[n]) + 0.001*W1[n]
+        q2[n+1] = np.cos(q3[n]) + 0.01*W2[n]
+        q3[n+1] = 0.5*q3[n] + 0.1*W3[n]
+    return q1, q2, q3
+
+def confounder(N):
+    q1, q2, q3 = np.zeros(N), np.zeros(N), np.zeros(N)
+    W1, W2, W3 = np.random.normal(0, 1, N), np.random.normal(0, 1, N), np.random.normal(0, 1, N)
+    for n in range(N-1):
+        q1[n+1] = np.sin(q1[n] + q3[n]) + 0.01*W1[n]
+        q2[n+1] = np.cos(q2[n] - q3[n]) + 0.01*W2[n]
+        q3[n+1] = 0.5*q3[n] + 0.1*W3[n]
+    return q1, q2, q3
+
+def synergistic_collider(N):
+    q1, q2, q3 = np.zeros(N), np.zeros(N), np.zeros(N)
+    W1, W2, W3 = np.random.normal(0, 1, N), np.random.normal(0, 1, N), np.random.normal(0, 1, N)
+    for n in range(N-1):
+        q1[n+1] = np.sin(q2[n] * q3[n]) + 0.001*W1[n]
+        q2[n+1] = 0.5*q2[n] + 0.1*W2[n]
+        q3[n+1] = 0.5*q3[n] + 0.1*W3[n]
+    return q1, q2, q3
+
+def redundant_collider(N):
+    q1, q2, q3 = np.zeros(N), np.zeros(N), np.zeros(N)
+    W1, W2, W3 = np.random.normal(0, 1, N), np.random.normal(0, 1, N), np.random.normal(0, 1, N)
+    for n in range(N-1):
+        # q1[n+1] = 0.3*q1[n] + 0.7*(np.sin(q2[n]*q3[n]) + 0.1*W1[n])
+        q1[n+1] = 0.3*q1[n] + (np.sin(q2[n]*q3[n]) + 0.001*W1[n])
+        q2[n+1] = 0.5*q2[n] + 0.1*W2[n]
+        q3[n+1] = q2[n+1]
+    return q1, q2, q3