# brainets/hoi architecture

> Architecture diagram of the GitHub repository brainets/hoi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainets/hoi
- Repository: https://github.com/brainets/hoi

## Overview

1. **What this repo is**  
   HOI is a Python scientific library for computing higher-order information-theoretic measures: not just pairwise dependence, but interactions among 2+ variables. The package is designed as a computation-oriented library, not a service or application.

2. **Top-level architecture**  
   The codebase is organized into a small set of domain-focused packages: `hoi.core` for mathematical primitives, `hoi.metrics` for user-facing HOI measures, `hoi.simulation` for synthetic data generation, `hoi.plot` for visualization, and `hoi.utils` for shared helpers.

3. **Core mathematical layer**  
   `hoi.core` contains the low-level building blocks used throughout the library: combinatorial subset handling, entropy estimation, mutual information, and redundancy-related primitives. This is the most fundamental dependency layer; the rest of the package composes these functions rather than reimplementing them.

4. **Metric implementations as the main public API**  
   `hoi.metrics` is the main feature layer. It includes implementations of many HOI measures such as total correlation, dual total correlation, O-information, S-information, redundancy/synergy metrics, PID/phiID atoms, pairwise MI, information topology, and transfer entropy. `base_hoi.py` suggests a shared abstraction or base class used by multiple metric modules.

5. **Data flow for a typical computation**  
   A user passes data into a metric class/function in `hoi.metrics`. That metric then relies on `hoi.core` to enumerate variable combinations and compute entropies or mutual information, and finally returns the higher-order score(s). In other words: raw data → core information primitives → derived HOI metric.

6. **Simulation subsystem**  
   `hoi.simulation.simulate_hoi_gauss` provides synthetic Gaussian data for experiments, demonstrations, and validation. This is important because many examples and tests likely depend on controlled synthetic datasets to verify metric behavior.

7. **Visualization subsystem**  
   `hoi.plot.landscape` provides plotting utilities for analyzing metric landscapes and interaction structure. This layer is separate from the computation layer, so visualization is treated as an output/analysis concern rather than part of the metric algorithms.

8. **Shared utilities**  
   `hoi.utils` holds cross-cutting helpers such as logging, multi-core support, progress bars, and statistical utilities. These are infrastructure-like concerns that support long-running metric computations and reproducible analysis without being specific to any one measure.

9. **JAX-centered runtime model**  
   The package is built on JAX, which is a key architectural choice: it enables accelerated numerical computation on CPU or GPU and shapes how the numerical kernels are written. NumPy/SciPy remain part of the broader scientific stack, while JAX is the execution backend that distinguishes this library.

10. **Examples and documentation as architecture validation**  
   The `examples/` tree is grouped by use case: tutorial-style usage, information-theoretic computations, metric-specific examples, statistics, and miscellaneous demos. The `docs/` tree mirrors the package structure with API pages, theory, installation, and quickstart material, so documentation is tightly aligned with the code architecture.

11. **Testing and quality boundaries**  
   Each major code area has its own tests under `hoi/core/tests`, `hoi/metrics/tests`, `hoi/simulation/tests`, and `hoi/utils/tests`. This indicates a modular boundary: core math, metric logic, synthetic data generation, and utilities are validated independently.

12. **Packaging and release pipeline**  
   The repository is a standard Python package with `pyproject.toml`, `setup.py`, and CI workflows for linting, tests, docs, and PyPI publishing. That means the main architectural boundary is the library API itself; build and release concerns are kept outside the runtime package.

Main entry points: [`hoi/metrics/__init__.py`](https://github.com/brainets/hoi/blob/main/hoi/metrics/__init__.py) (Metrics), [`hoi/core/__init__.py`](https://github.com/brainets/hoi/blob/main/hoi/core/__init__.py) (Core), [`docs/api/modules.rst`](https://github.com/brainets/hoi/blob/main/docs/api/modules.rst) (API refs), [`hoi/__init__.py`](https://github.com/brainets/hoi/blob/main/hoi/__init__.py) (hoi)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Library"]
  node_hoi_pkg["hoi<br/>[__init__.py]"]
  node_hoi_core["Core<br/>math primitives<br/>[__init__.py]"]
  node_core_comb["Combinatory<br/>subset enumeration<br/>[combinatory.py]"]
  node_core_ent["Entropies<br/>entropy kernels<br/>[entropies.py]"]
  node_core_mi["MI<br/>mutual info<br/>[mi.py]"]
  node_core_red["Redundancies<br/>redundancy primitives<br/>[redundancies.py]"]
  node_hoi_metrics["Metrics<br/>HOI measures<br/>[__init__.py]"]
  node_metrics_base["Base HOI<br/>metric base<br/>[base_hoi.py]"]
  node_metrics_oinfo["O-info<br/>metric<br/>[oinfo.py]"]
  node_metrics_sinfo["S-info<br/>metric<br/>[sinfo.py]"]
  node_metrics_tc["TC / DTC<br/>metrics<br/>[tc.py]"]
  node_metrics_pid["PID atoms<br/>decomposition<br/>[pid_atoms.py]"]
  node_metrics_phiid["phiID atoms<br/>decomposition<br/>[phiid_atoms.py]"]
  node_metrics_infotopo["InfoTopo<br/>topology metric<br/>[infotopo.py]"]
  node_metrics_te["Transfer Entropy<br/>temporal metric"]
  node_sim_gauss["Gaussian Sim<br/>synthetic data"]
  node_plot_landscape["Landscape Plot<br/>visualization<br/>[landscape.py]"]
  node_utils["Utils<br/>helpers<br/>[__init__.py]"]
end

subgraph group_docs["Docs"]
  node_docs_index["Docs<br/>documentation<br/>[index.rst]"]
  node_docs_api["API refs<br/>docs<br/>[modules.rst]"]
end

subgraph group_examples["Examples"]
  node_examples_root["Examples<br/>[README.txt]"]
end

subgraph group_tooling["Tooling"]
  node_ci["CI / Release<br/>tooling<br/>[test_doc.yml]"]
end

node_hoi_pkg -->|"imports"| node_hoi_core
node_hoi_pkg -->|"imports"| node_hoi_metrics
node_hoi_pkg -->|"imports"| node_sim_gauss
node_hoi_pkg -->|"imports"| node_plot_landscape
node_hoi_pkg -->|"imports"| node_utils
node_hoi_metrics -->|"shared base"| node_metrics_base
node_hoi_metrics -->|"contains"| node_metrics_oinfo
node_hoi_metrics -->|"contains"| node_metrics_sinfo
node_hoi_metrics -->|"contains"| node_metrics_tc
node_hoi_metrics -->|"contains"| node_metrics_pid
node_hoi_metrics -->|"contains"| node_metrics_phiid
node_hoi_metrics -->|"contains"| node_metrics_infotopo
node_hoi_metrics -->|"contains"| node_metrics_te
node_metrics_oinfo -->|"uses core"| node_hoi_core
node_metrics_tc -->|"uses core"| node_hoi_core
node_metrics_pid -->|"uses core"| node_hoi_core
node_metrics_phiid -->|"uses core"| node_hoi_core
node_metrics_infotopo -->|"uses core"| node_hoi_core
node_metrics_te -->|"uses core"| node_hoi_core
node_sim_gauss -->|"feeds"| node_hoi_metrics
node_plot_landscape -->|"visualizes"| node_hoi_metrics
node_docs_index -->|"organizes"| node_docs_api
node_docs_api -->|"documents"| node_hoi_core
node_docs_api -->|"documents"| node_hoi_metrics
node_docs_api -->|"documents"| node_sim_gauss
node_docs_api -->|"documents"| node_plot_landscape
node_docs_api -->|"documents"| node_utils
node_examples_root -->|"demonstrates"| node_hoi_metrics
node_examples_root -->|"demonstrates"| node_sim_gauss
node_ci -->|"builds/tests"| node_hoi_pkg
node_ci -->|"docs"| node_docs_index

click node_hoi_pkg "https://github.com/brainets/hoi/blob/main/hoi/__init__.py"
click node_hoi_core "https://github.com/brainets/hoi/blob/main/hoi/core/__init__.py"
click node_core_comb "https://github.com/brainets/hoi/blob/main/hoi/core/combinatory.py"
click node_core_ent "https://github.com/brainets/hoi/blob/main/hoi/core/entropies.py"
click node_core_mi "https://github.com/brainets/hoi/blob/main/hoi/core/mi.py"
click node_core_red "https://github.com/brainets/hoi/blob/main/hoi/core/redundancies.py"
click node_hoi_metrics "https://github.com/brainets/hoi/blob/main/hoi/metrics/__init__.py"
click node_metrics_base "https://github.com/brainets/hoi/blob/main/hoi/metrics/base_hoi.py"
click node_metrics_oinfo "https://github.com/brainets/hoi/blob/main/hoi/metrics/oinfo.py"
click node_metrics_sinfo "https://github.com/brainets/hoi/blob/main/hoi/metrics/sinfo.py"
click node_metrics_tc "https://github.com/brainets/hoi/blob/main/hoi/metrics/tc.py"
click node_metrics_pid "https://github.com/brainets/hoi/blob/main/hoi/metrics/pid_atoms.py"
click node_metrics_phiid "https://github.com/brainets/hoi/blob/main/hoi/metrics/phiid_atoms.py"
click node_metrics_infotopo "https://github.com/brainets/hoi/blob/main/hoi/metrics/infotopo.py"
click node_metrics_te "https://github.com/brainets/hoi/blob/main/hoi/metrics/transfer_entropy.py"
click node_sim_gauss "https://github.com/brainets/hoi/blob/main/hoi/simulation/simulate_hoi_gauss.py"
click node_plot_landscape "https://github.com/brainets/hoi/blob/main/hoi/plot/landscape.py"
click node_utils "https://github.com/brainets/hoi/blob/main/hoi/utils/__init__.py"
click node_docs_index "https://github.com/brainets/hoi/blob/main/docs/index.rst"
click node_docs_api "https://github.com/brainets/hoi/blob/main/docs/api/modules.rst"
click node_examples_root "https://github.com/brainets/hoi/blob/main/examples/README.txt"
click node_ci "https://github.com/brainets/hoi/blob/main/.github/workflows/test_doc.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hoi_pkg,node_hoi_core,node_core_comb,node_core_ent,node_core_mi,node_core_red,node_hoi_metrics,node_metrics_base,node_metrics_oinfo,node_metrics_sinfo,node_metrics_tc,node_metrics_pid,node_metrics_phiid,node_metrics_infotopo,node_metrics_te,node_sim_gauss,node_plot_landscape,node_utils toneBlue
class node_docs_index,node_docs_api toneAmber
class node_examples_root toneMint
class node_ci toneRose
```

## Components

### Library

Core importable HOI package and its main subsystems.

- [hoi](https://github.com/brainets/hoi/blob/main/hoi/__init__.py): package · Top-level HOI package entry point. · `hoi/__init__.py`
- [Core](https://github.com/brainets/hoi/blob/main/hoi/core/__init__.py): math primitives · Lowest-level information-theoretic building blocks. · `hoi/core/__init__.py`
- [Combinatory](https://github.com/brainets/hoi/blob/main/hoi/core/combinatory.py): subset enumeration · Variable subset and combination handling. · `hoi/core/combinatory.py`
- [Entropies](https://github.com/brainets/hoi/blob/main/hoi/core/entropies.py): entropy kernels · Entropy estimation and related primitives. · `hoi/core/entropies.py`
- [MI](https://github.com/brainets/hoi/blob/main/hoi/core/mi.py): mutual info · Mutual information computations used by metrics. · `hoi/core/mi.py`
- [Redundancies](https://github.com/brainets/hoi/blob/main/hoi/core/redundancies.py): redundancy primitives · Redundancy-related information primitives. · `hoi/core/redundancies.py`
- [Metrics](https://github.com/brainets/hoi/blob/main/hoi/metrics/__init__.py): HOI measures · User-facing higher-order information measures. · `hoi/metrics/__init__.py`
- [Base HOI](https://github.com/brainets/hoi/blob/main/hoi/metrics/base_hoi.py): metric base · Shared abstraction for metric implementations. · `hoi/metrics/base_hoi.py`
- [O-info](https://github.com/brainets/hoi/blob/main/hoi/metrics/oinfo.py): metric · O-information and related decompositions. · `hoi/metrics/oinfo.py`
- [S-info](https://github.com/brainets/hoi/blob/main/hoi/metrics/sinfo.py): metric · S-information measure implementation. · `hoi/metrics/sinfo.py`
- [TC / DTC](https://github.com/brainets/hoi/blob/main/hoi/metrics/tc.py): metrics · Total correlation and dual total correlation. · `hoi/metrics/tc.py`
- [PID atoms](https://github.com/brainets/hoi/blob/main/hoi/metrics/pid_atoms.py): decomposition · Partial information decomposition atoms. · `hoi/metrics/pid_atoms.py`
- [phiID atoms](https://github.com/brainets/hoi/blob/main/hoi/metrics/phiid_atoms.py): decomposition · PhiID atom computation and redundancy variants. · `hoi/metrics/phiid_atoms.py`
- [InfoTopo](https://github.com/brainets/hoi/blob/main/hoi/metrics/infotopo.py): topology metric · Information topology analysis utilities. · `hoi/metrics/infotopo.py`
- [Transfer Entropy](https://github.com/brainets/hoi/blob/main/hoi/metrics/transfer_entropy.py): temporal metric · Transfer entropy computation. · `hoi/metrics/transfer_entropy.py`
- [Gaussian Sim](https://github.com/brainets/hoi/blob/main/hoi/simulation/simulate_hoi_gauss.py): synthetic data · Synthetic Gaussian HOI data generation. · `hoi/simulation/simulate_hoi_gauss.py`
- [Landscape Plot](https://github.com/brainets/hoi/blob/main/hoi/plot/landscape.py): visualization · Plotting for metric landscapes and interaction structure. · `hoi/plot/landscape.py`
- [Utils](https://github.com/brainets/hoi/blob/main/hoi/utils/__init__.py): helpers · Shared logging, parallelism, progress, and stats helpers. · `hoi/utils/__init__.py`

### Docs

Documentation and usage material aligned with the package structure.

- [Docs](https://github.com/brainets/hoi/blob/main/docs/index.rst): documentation · Documentation hub and theory/usage guides. · `docs/index.rst`
- [API refs](https://github.com/brainets/hoi/blob/main/docs/api/modules.rst): docs · API reference pages for core, metrics, plot, simulation, and utils. · `docs/api/modules.rst`

### Examples

Executable examples organized by use case.

- [Examples](https://github.com/brainets/hoi/blob/main/examples/README.txt): examples · Example entry points and grouped demos. · `examples/README.txt`

### Tooling

Packaging, CI, and repository-level build/release support.

- [CI / Release](https://github.com/brainets/hoi/blob/main/.github/workflows/test_doc.yml): tooling · Packaging, linting, testing, and PyPI publishing workflows. · `.github/workflows/test_doc.yml`

## Connections

- hoi → Core: imports · Top-level package exposes the core layer.
- hoi → Metrics: imports · Top-level package exposes the metrics API.
- hoi → Gaussian Sim: imports · Top-level package exposes simulation utilities.
- hoi → Landscape Plot: imports · Top-level package exposes plotting utilities.
- hoi → Utils: imports · Top-level package exposes shared helpers.
- Metrics → Base HOI: shared base · Metric modules share a common abstraction.
- Metrics → O-info: contains · Main HOI measure implementations.
- Metrics → S-info: contains · Main HOI measure implementations.
- Metrics → TC / DTC: contains · Main HOI measure implementations.
- Metrics → PID atoms: contains · Main HOI measure implementations.
- Metrics → phiID atoms: contains · Main HOI measure implementations.
- Metrics → InfoTopo: contains · Main HOI measure implementations.
- Metrics → Transfer Entropy: contains · Main HOI measure implementations.
- O-info → Core: uses core · Derived metrics depend on entropy and combinatorics.
- TC / DTC → Core: uses core · Core primitives power correlation-style measures.
- PID atoms → Core: uses core · Decomposition metrics depend on low-level primitives.
- phiID atoms → Core: uses core · Decomposition metrics depend on low-level primitives.
- InfoTopo → Core: uses core · Topology metrics are built on core information routines.
- Transfer Entropy → Core: uses core · Temporal information measures use the same primitives.
- Gaussian Sim → Metrics: feeds · Synthetic data supports metric experiments and validation.
- Landscape Plot → Metrics: visualizes · Plots analyze metric outputs and landscapes.
- Docs → API refs: organizes · Documentation hub points to the API reference.
- API refs → Core: documents · Reference mirrors the core package.
- API refs → Metrics: documents · Reference mirrors the metrics package.
- API refs → Gaussian Sim: documents · Reference mirrors the simulation package.
- API refs → Landscape Plot: documents · Reference mirrors the plot package.
- API refs → Utils: documents · Reference mirrors the utilities package.
- Examples → Metrics: demonstrates · Examples showcase metric usage.
- Examples → Gaussian Sim: demonstrates · Examples use synthetic data generation.
- CI / Release → hoi: builds/tests · Workflows validate the library package.
- CI / Release → Docs: docs · Workflows build and validate documentation.
