OUxInfo is a high-performance Shannon entropy estimator for Python, powered by a C++ backend. It is designed for fast and scalable entropy estimation, particularly for causal inference.

Features

• Fast Shannon entropy estimator (C++ backend)
• Python interface via pybind11
• Information-theoretic quantities for causal inference (e.g., transfer entropy, backward transfer entropy, information flow)

Installation

Requirements

• Python >= 3.10 (3.12 recommended)
• GCC >= 11 (>= 13 recommended)
• OpenMP support (-fopenmp)

With pip

pip install ouxinfo

With conda-forge

conda install -c conda-forge ouxinfo

With mamba

mamba install -c conda-forge ouxinfo

With pixi

pixi add ouxinfo

Dependencies

Python packages (installed automatically)

• pybind11
• numpy
• scipy
• matplotlib
• joblib
• tqdm

C++ dependencies

• Boost C++ Libraries (Boost Software License, included in this repository)
• nanoflann (BSD License, included in this repository)

Usage (example)

import numpy as np
from ouxinfo import shannon_entropy

x = np.random.normal(0.e0, 1.e0, 10000)
H = shannon_entropy(x.reshape(-1,1), k=5)

Related Publication

This repository contains the implementation used in the following publication:

Jun Hatayama, Kento Tanaka, and Toshinori Kouchi. "Nonlinear causal relationship between separation bubbles and reflected shock wave in shock wave/turbulent boundary layer interaction based on information theory." Computers & Fluids (2026): 107016.

@article{hatayama2026nonlinear,
  title={Nonlinear causal relationship between separation bubbles and reflected shock wave in shock wave/turbulent boundary layer interaction based on information theory},
  author={Hatayama, Jun and Tanaka, Kento and Kouchi, Toshinori},
  journal={Computers \& Fluids},
  pages={107016},
  year={2026},
  publisher={Elsevier}
}

The repository was made publicly available after publication to improve reproducibility. However, this version may differ slightly from the version used in the paper.

License

This project is released under MIT license.

Third-party licenses

This project depends on the following libraries;

nanoflann (BSD License)

• Copyright 2008-2009 Marius Muja (mariusm@cs.ubc.ca). All rights reserved.
• Copyright 2008-2009 David G. Lowe (lowe@cs.ubc.ca). All rights reserved.
• Copyright 2011-2025 Jose Luis Blanco (joseluisblancoc@gmail.com). Redistribution and use in source and binary forms are permitted under the BSD License. Full text: third_party/nanoflann/LICENSE.

Boost C++ Libraries (Boost Software License 1.0)

• Copyright John Maddock 2006, 2007.
• Copyright Paul A. Bristow 2006, 2007, 2009, 2010. Use, modification and distribution are subject to the Boost Software License, Version 1.0. Full text: third_party/boost/LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt

Boost is bundled in third_party/boost/ and nanoflann in third_party/nanoflann/; both are used automatically during build.

pybind11 (BSD License)

Used for Python bindings.

NumPy, SciPy, Matplotlib, Numba

These libraries are installed via pip and are subject to their respective licenses.

Validation Dataset Acknowledgement

The validation dataset included in this repository is based on data provided by: SURD We gratefully acknowledge the authors for making the dataset publicly available under the MIT License.

AI-Assisted Development

Development during 2025 was primarily conducted by the project owners.
Starting in 2026, the project expanded its contributor base and introduced AI-assisted "vibe coding" workflows using Claude Code.

To maintain transparency, we aim to clearly distinguish which parts of the codebase and development workflow involve AI-generated content or AI-assisted modifications. In addition, as part of our effort to share practical knowledge on AI-assisted development in the community, we provide Claude Code plan files under ./docs/plans.