# kthtda/stablebear architecture

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

- Interactive diagram: https://gitdiagram.com/kthtda/stablebear
- Repository: https://github.com/kthtda/stablebear

## Overview

stablebear is a Python package with C++ and optional CUDA backends for scalable computation on piecewise-constant functions and topological data analysis. The principal workflow is to create typed tensor, point-cloud, or distance-matrix inputs; apply functional or similarity operations, or compute persistence-related outputs; and consume results through Python objects or serialization. The graph preserves the documented reductions, kernels, persistence statistics, sampling, and point-process capabilities. Some subsystem links are based on README statements rather than inspected implementation excerpts; those are marked dashed.

Main entry points: [`stablebear/_sb_cpp.py`](https://github.com/kthtda/stablebear/blob/main/stablebear/_sb_cpp.py) (Backend selection), [`stablebear/distance_matrix.py`](https://github.com/kthtda/stablebear/blob/main/stablebear/distance_matrix.py) (Distance matrices), [`stablebear/__init__.py`](https://github.com/kthtda/stablebear/blob/main/stablebear/__init__.py) (Package facade), [`stablebear/point_cloud.py`](https://github.com/kthtda/stablebear/blob/main/stablebear/point_cloud.py) (Point clouds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python API"]
  node_facade["Package facade<br/>[__init__.py]"]
  node_io["Serialization and IO<br/>[io.py]"]
end

subgraph group_data["Data and functions"]
  node_tensorbase["Tensor operations<br/>[_tensor_base.py]"]
  node_typed["Typed tensors<br/>[base_tensor.py]"]
  node_creation["Tensor creation<br/>[tensor_create.py]"]
  node_pcf["PCF functions<br/>[pcf.py]"]
  node_nested["Nested tensors<br/>[nested_tensor.py]"]
  node_pointcloud["Point clouds<br/>[point_cloud.py]"]
end

subgraph group_analysis["Analysis"]
  node_distmat["Distance matrices<br/>[distance_matrix.py]"]
  node_similarity["Similarity operations<br/>[distance.py]"]
  node_reductions["Reductions and norms<br/>[reductions.py]"]
  node_random["Random sampling<br/>[subsample.py]"]
  node_pointprocess["Point processes<br/>[poisson.py]"]
end

subgraph group_runtime["Compute runtime"]
  node_backend["Backend selection<br/>[_sb_cpp.py]"]
  node_bindings["Python C++ bindings<br/>[py_tensor.hpp]"]
  node_cppcore["C++ compute core<br/>[tensor.hpp]"]
  node_cpppcf["C++ PCF algorithms<br/>[pcf.hpp]"]
  node_cpuhomology["C++ persistence algorithms"]
end

subgraph group_persistence["Persistent homology"]
  node_homology["Homology computations<br/>[homology.py]"]
  node_kernel["Homological kernel"]
  node_barcode["Barcode results<br/>[ph_tensor.py]"]
end

node_user(("Python user"))

node_user -->|"uses"| node_facade
node_facade -->|"exports"| node_tensorbase
node_facade -->|"exports"| node_pointcloud
node_facade -->|"exports"| node_distmat
node_facade -->|"exports"| node_io
node_tensorbase -->|"calls"| node_backend
node_tensorbase -->|"builds on"| node_typed
node_creation -->|"constructs"| node_typed
node_creation -->|"constructs"| node_nested
node_creation -->|"constructs"| node_pointcloud
node_pcf -->|"calls"| node_backend
node_pointcloud -->|"wraps"| node_typed
node_distmat -->|"calls"| node_backend
node_similarity -.->|"computes matrices"| node_distmat
node_reductions -.->|"reduces"| node_typed
node_random -->|"samples with"| node_backend
node_random -->|"accepts"| node_pointcloud
node_random -->|"accepts"| node_distmat
node_pointprocess -->|"generates with"| node_backend
node_homology -->|"dispatches to"| node_backend
node_homology -->|"accepts"| node_distmat
node_kernel -->|"spawns task"| node_backend
node_kernel -.->|"writes output"| node_barcode
node_kernel -->|"accepts"| node_distmat
node_io -.->|"uses binary IO"| node_backend
node_backend -.->|"loads extension"| node_bindings
node_bindings -->|"binds tensor API"| node_cppcore
node_cpppcf -->|"uses tensor algorithms"| node_cppcore
node_cpuhomology -.->|"provides computation"| node_backend

click node_facade "https://github.com/kthtda/stablebear/blob/main/stablebear/__init__.py"
click node_tensorbase "https://github.com/kthtda/stablebear/blob/main/stablebear/_tensor_base.py"
click node_typed "https://github.com/kthtda/stablebear/blob/main/stablebear/base_tensor.py"
click node_creation "https://github.com/kthtda/stablebear/blob/main/stablebear/tensor_create.py"
click node_pcf "https://github.com/kthtda/stablebear/blob/main/stablebear/functional/pcf.py"
click node_nested "https://github.com/kthtda/stablebear/blob/main/stablebear/nested_tensor.py"
click node_pointcloud "https://github.com/kthtda/stablebear/blob/main/stablebear/point_cloud.py"
click node_distmat "https://github.com/kthtda/stablebear/blob/main/stablebear/distance_matrix.py"
click node_similarity "https://github.com/kthtda/stablebear/blob/main/stablebear/distance.py"
click node_reductions "https://github.com/kthtda/stablebear/blob/main/stablebear/reductions.py"
click node_random "https://github.com/kthtda/stablebear/blob/main/stablebear/random/subsample.py"
click node_pointprocess "https://github.com/kthtda/stablebear/blob/main/stablebear/point_process/poisson.py"
click node_homology "https://github.com/kthtda/stablebear/blob/main/stablebear/persistence/homology.py"
click node_kernel "https://github.com/kthtda/stablebear/blob/main/stablebear/persistence/homological_kernel.py"
click node_barcode "https://github.com/kthtda/stablebear/blob/main/stablebear/persistence/ph_tensor.py"
click node_io "https://github.com/kthtda/stablebear/blob/main/stablebear/io.py"
click node_backend "https://github.com/kthtda/stablebear/blob/main/stablebear/_sb_cpp.py"
click node_bindings "https://github.com/kthtda/stablebear/blob/main/src/python/py_tensor.hpp"
click node_cppcore "https://github.com/kthtda/stablebear/blob/main/include/sbear/tensor.hpp"
click node_cpppcf "https://github.com/kthtda/stablebear/blob/main/include/sbear/functional/pcf.hpp"
click node_cpuhomology "https://github.com/kthtda/stablebear/blob/main/include/sbear/persistence/compute_homological_kernel.hpp"

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_facade,node_io,node_user toneBlue
class node_tensorbase,node_typed,node_creation,node_pcf,node_nested,node_pointcloud toneAmber
class node_distmat,node_similarity,node_reductions,node_random,node_pointprocess toneMint
class node_backend,node_bindings,node_cppcore,node_cpppcf,node_cpuhomology toneRose
class node_homology,node_kernel,node_barcode toneIndigo
```

## Components

### Python API

- [Package facade](https://github.com/kthtda/stablebear/blob/main/stablebear/__init__.py): `stablebear/__init__.py`
- [Serialization and IO](https://github.com/kthtda/stablebear/blob/main/stablebear/io.py): `stablebear/io.py`

### Data and functions

- [Tensor operations](https://github.com/kthtda/stablebear/blob/main/stablebear/_tensor_base.py): `stablebear/_tensor_base.py`
- [Typed tensors](https://github.com/kthtda/stablebear/blob/main/stablebear/base_tensor.py): `stablebear/base_tensor.py`
- [Tensor creation](https://github.com/kthtda/stablebear/blob/main/stablebear/tensor_create.py): `stablebear/tensor_create.py`
- [PCF functions](https://github.com/kthtda/stablebear/blob/main/stablebear/functional/pcf.py): `stablebear/functional/pcf.py`
- [Nested tensors](https://github.com/kthtda/stablebear/blob/main/stablebear/nested_tensor.py): `stablebear/nested_tensor.py`
- [Point clouds](https://github.com/kthtda/stablebear/blob/main/stablebear/point_cloud.py): `stablebear/point_cloud.py`

### Analysis

- [Distance matrices](https://github.com/kthtda/stablebear/blob/main/stablebear/distance_matrix.py): `stablebear/distance_matrix.py`
- [Similarity operations](https://github.com/kthtda/stablebear/blob/main/stablebear/distance.py): `stablebear/distance.py`
- [Reductions and norms](https://github.com/kthtda/stablebear/blob/main/stablebear/reductions.py): `stablebear/reductions.py`
- [Random sampling](https://github.com/kthtda/stablebear/blob/main/stablebear/random/subsample.py): `stablebear/random/subsample.py`
- [Point processes](https://github.com/kthtda/stablebear/blob/main/stablebear/point_process/poisson.py): `stablebear/point_process/poisson.py`

### Compute runtime

- [Backend selection](https://github.com/kthtda/stablebear/blob/main/stablebear/_sb_cpp.py): `stablebear/_sb_cpp.py`
- [Python C++ bindings](https://github.com/kthtda/stablebear/blob/main/src/python/py_tensor.hpp): `src/python/py_tensor.hpp`
- [C++ compute core](https://github.com/kthtda/stablebear/blob/main/include/sbear/tensor.hpp): `include/sbear/tensor.hpp`
- [C++ PCF algorithms](https://github.com/kthtda/stablebear/blob/main/include/sbear/functional/pcf.hpp): `include/sbear/functional/pcf.hpp`
- [C++ persistence algorithms](https://github.com/kthtda/stablebear/blob/main/include/sbear/persistence/compute_homological_kernel.hpp): `include/sbear/persistence/compute_homological_kernel.hpp`

### Persistent homology

- [Homology computations](https://github.com/kthtda/stablebear/blob/main/stablebear/persistence/homology.py): `stablebear/persistence/homology.py`
- [Homological kernel](https://github.com/kthtda/stablebear/blob/main/stablebear/persistence/homological_kernel.py): `stablebear/persistence/homological_kernel.py`
- [Barcode results](https://github.com/kthtda/stablebear/blob/main/stablebear/persistence/ph_tensor.py): `stablebear/persistence/ph_tensor.py`

### Other components

- **Python user**

## Connections

- Python user → Package facade: uses (evidence: `README.md`)
- Package facade → Tensor operations: exports (evidence: `stablebear/__init__.py`)
- Package facade → Point clouds: exports (evidence: `stablebear/__init__.py`)
- Package facade → Distance matrices: exports (evidence: `stablebear/__init__.py`)
- Package facade → Serialization and IO: exports (evidence: `stablebear/__init__.py`)
- Tensor operations → Backend selection: calls (evidence: `stablebear/_tensor_base.py`)
- Tensor operations → Typed tensors: builds on (evidence: `stablebear/base_tensor.py`)
- Tensor creation → Typed tensors: constructs (evidence: `stablebear/tensor_create.py`)
- Tensor creation → Nested tensors: constructs (evidence: `stablebear/tensor_create.py`)
- Tensor creation → Point clouds: constructs (evidence: `stablebear/tensor_create.py`)
- PCF functions → Backend selection: calls (evidence: `stablebear/functional/pcf.py`)
- Point clouds → Typed tensors: wraps (evidence: `stablebear/point_cloud.py`)
- Distance matrices → Backend selection: calls (evidence: `stablebear/distance_matrix.py`)
- Similarity operations → Distance matrices: computes matrices
- Reductions and norms → Typed tensors: reduces
- Random sampling → Backend selection: samples with (evidence: `stablebear/random/subsample.py`)
- Random sampling → Point clouds: accepts (evidence: `stablebear/random/subsample.py`)
- Random sampling → Distance matrices: accepts (evidence: `stablebear/random/subsample.py`)
- Point processes → Backend selection: generates with (evidence: `stablebear/point_process/poisson.py`)
- Homology computations → Backend selection: dispatches to (evidence: `stablebear/persistence/homology.py`)
- Homology computations → Distance matrices: accepts (evidence: `stablebear/persistence/homology.py`)
- Homological kernel → Backend selection: spawns task (evidence: `stablebear/persistence/homological_kernel.py`)
- Homological kernel → Barcode results: writes output (evidence: `stablebear/persistence/homological_kernel.py`)
- Homological kernel → Distance matrices: accepts (evidence: `stablebear/persistence/homological_kernel.py`)
- Serialization and IO → Backend selection: uses binary IO
- Backend selection → Python C++ bindings: loads extension
- Python C++ bindings → C++ compute core: binds tensor API (evidence: `src/python/py_tensor.hpp`)
- C++ PCF algorithms → C++ compute core: uses tensor algorithms (evidence: `include/sbear/functional/pcf.hpp`)
- C++ persistence algorithms → Backend selection: provides computation
