Metadata-Version: 2.4
Name: pybopu
Version: 0.1.1
Summary: Python Brain Organoid Processing Unit (BOPU / OPU): Biocomputing, In Vitro Wetware, and Neural Organoid Simulation Framework
Author-email: Luciano Silva <luciano.silva@neurohil.io>
Maintainer-email: NeuroHIL <luciano.silva@neurohil.io>
License: Apache-2.0
Project-URL: Homepage, https://github.com/neurohil/pybopu
Project-URL: Repository, https://github.com/neurohil/pybopu.git
Project-URL: Organization, https://github.com/neurohil
Keywords: biocomputing,organoid-computing,wetware,neuromorphic,brain-organoids,hd-mea,computational-neuroscience
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: Apache Software License
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Provides-Extra: simulation
Requires-Dist: numba>=0.58.0; extra == "simulation"
Provides-Extra: ml
Requires-Dist: torch>=2.0.0; extra == "ml"
Requires-Dist: scikit-learn>=1.3.0; extra == "ml"
Requires-Dist: gymnasium>=0.29.0; extra == "ml"
Provides-Extra: data
Requires-Dist: pynwb>=2.6.0; extra == "data"
Requires-Dist: h5py>=3.9.0; extra == "data"
Requires-Dist: matplotlib>=3.7.0; extra == "data"
Provides-Extra: cloud
Requires-Dist: fastapi>=0.110.0; extra == "cloud"
Requires-Dist: uvicorn>=0.28.0; extra == "cloud"
Requires-Dist: requests>=2.31.0; extra == "cloud"
Requires-Dist: httpx2>=2.16.0; extra == "cloud"
Provides-Extra: all
Requires-Dist: pybopu[cloud,data,dev,ml,simulation]; extra == "all"
Dynamic: license-file

# pybopu: Python Brain Organoid Processing Unit (BOPU / OPU)

[![Version](https://img.shields.io/badge/version-0.1.1-blue.svg)](https://semver.org)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-310%20passing-brightgreen.svg)](#testing--quality-assurance)
[![Docs](https://img.shields.io/badge/docs-Sphinx%20%2F%20ReadTheDocs-informational.svg)](#documentation)
[![Organization](https://img.shields.io/badge/org-NeuroHIL-purple.svg)](https://github.com/neurohil)

**`pybopu`** (**Py**thon **B**rain **O**rganoid **P**rocessing **U**nit) is a clean-slate, fully type-annotated ([PEP 484](https://peps.python.org/pep-0484/)), modular biocomputing framework for simulating, programming, and interfacing with 3D cerebral organoids, *in vitro* neural wetware, and hardware-in-the-loop digital twins.

> **Terminology Note — BOPU vs. OPU:**  
> To distinguish 3D neural organoid bioprocessors from non-neural biological organoids and photonic/optical co-processors, the package is formally named **`pybopu`** (*Brain Organoid Processing Unit*). Throughout the API and documentation, the primary orchestrating facade is concisely named **`OPU`** (`pybopu.OPU`), with **`BOPU`** (`pybopu.BOPU`) provided as a first-class alias.

---

## Key Architectural Pillars

1. **Unified Facade Pattern (`pybopu.OPU` / `pybopu.BOPU`):** A single hardware-agnostic entry point parameterized by three decoupled domains: `Tissue`, `Interface`, and `Backend`.
2. **Biophysically Grounded Cytology & First-Class Glia:** Explicit point-neuron ODE solvers (`LIFModel`, `AdExModel`, `IzhikevichModel`), cortical phenotypes (`PyramidalNeuron`, `PVInterneuron`, `SSTInterneuron`), dual-receptor conductances (`AMPA`, voltage-gated `NMDA`, `GABA-A`, `GABA-B`), three-factor plasticity (`STDP`, `TsodyksMarkramSTP`, `RewardModulatedSTDP`), and dedicated glial subsystems (`Astrocyte`, `Oligodendrocyte`, `Microglia`).
3. **3D Spatial Topologies & Modular Assembloids:** Declarative `TissueProfile` geometries (`SphereGeometry`, `EllipsoidGeometry`, `CylinderGeometry`), distance-dependent connectivity kernels, and multi-regional `Assembloid` fusions linked by unidirectional/bidirectional microfluidic `AxonTunnel` highways.
4. **Multi-Modal Transduction & Electrophysiology:** High-density 1024-channel CMOS microelectrode arrays (`MEAInterface`), optogenetic DMD/micro-LED probes (`OptoInterface`, `HybridInterface`), Shannon-safe charge-balanced biphasic stimulation (`BiphasicPulse`), digital IIR filtering, LFP spectral decomposition, Quiroga adaptive spike detection, PCA spike sorting, NWB 2.0 HDF5 storage, Transfer Entropy, Criticality Avalanches, and Jaeger Memory Capacity.
5. **Interchangeable Execution Backends:** Run identical biocomputing pipelines across:
   - **`CPUBackend`**: Vectorized NumPy / Numba JIT engine with sub-millisecond step latency.
   - **`GPUBackend`**: Massively parallel multi-organoid batch engine (PyTorch / CPU fallback).
   - **`FPGABackend`**: Low-latency Gigabit Ethernet UDP driver for the Sipeed Tang Mega 138K FPGA.
   - **`MaxWellBackend`**: Live MaxWell Biosystems CMOS HD-MEA drivers (`MaxOneDriver`, `MaxTwoDriver`) and deterministic HDF5 `MaxWellReplayEngine`.
   - **`OaaSBackend` & `OaaSServer`**: Distributed *Organoid as a Service* cloud gateway (FastAPI + Uvicorn + WebSockets), interactive SPA Cluster Dashboard (`/dashboard`), and microfluidic life-support kinetics (`OrganoidBank`, `IncubatorChamber`).
6. **Closed-Loop Cybernetics & Bio-Robotic Embodiment:** Native **Farama Gymnasium** environments (`OPUEnv`, `DishBrainPongEnv`), Karl Friston's **Free Energy Principle / Active Inference** controllers (`ActiveInferenceController`, `VariationalFreeEnergyEstimator`), and **ROS 2** bio-robotic controllers (`OPURos2ControllerNode`, `HybrotArenaSimulator`, `DifferentialDriveDecoder`, `GeorgopoulosPopulationDecoder`, `LeakyIntegratorTorqueDecoder`).

```text
+========================================================================================+
|                     pybopu: BRAIN ORGANOID PROCESSING UNIT FRAMEWORK                   |
+========================================================================================+
|                                                                                        |
|                    Unified Master Facade: pybopu.OPU (alias: BOPU)                     |
|                         opu = pybopu.OPU(tissue, interface, backend)                   |
|                                           |                                            |
|             +-----------------------------+-----------------------------+              |
|             |                             |                             |              |
|             v                             v                             v              |
|   +-------------------+         +-------------------+         +-------------------+    |
|   |   pybopu.tissue   |         | pybopu.interfaces |         |  pybopu.backends  |    |
|   +-------------------+         +-------------------+         +-------------------+    |
|   * Models: LIF, AdEx,|         * MEAInterface      |         * CPUBackend (Numba)|    |
|     Izhikevich        |           (1024-ch CMOS)    |         * GPUBackend (Batch)|    |
|   * Neurons: Pyramidal|         * OptoInterface     |         * FPGABackend (UDP) |    |
|     PV+, SST+         |           (ChR2 / NpHR)     |         * MaxWellBackend    |    |
|   * Synapses: AMPA,   |         * HybridInterface   |           (MaxOne / MaxTwo) |    |
|     NMDA, GABA, STDP, |                             |         * OaaSBackend/Server|    |
|     STP, R-STDP       |         +-------------------+           (Cloud Wetware)   |    |
|   * Glia: Astrocytes, |         | pybopu.stimulation|                             |    |
|     Oligo, Microglia  |         |  & pybopu.signals |         +-------------------+    |
|   * 3D TissueProfile  |         +-------------------+         |   pybopu.gym &    |    |
|     & Assembloids     |         * Biphasic Pulses   |         |  pybopu.robotics  |    |
|   +-------------------+         * Rate/TTFS/Pop Enc.|         +-------------------+    |
|                                 * Bandpass, LFP,    |         * OPUEnv (Gymnasium)|    |
|   +-------------------+           Spike Sorting, NWB|         * DishBrainPongEnv  |    |
|   |  pybopu.metrics   |         +-------------------+         * Active Inference  |    |
|   +-------------------+                                       * OPURos2Controller |    |
|   * Transfer Entropy, Criticality Avalanches, Memory Capacity * Hybrot Simulators |    |
+========================================================================================+
```

---

## Module Organization

The package is organized under `src/pybopu/` into clean, domain-specific subpackages:

```text
pybopu/
├── __init__.py                    # Top-level exports (__version__, OPU, BOPU, all submodules)
├── opu.py                         # Master Facade: pybopu.OPU & pybopu.BOPU
├── config.py                      # Global settings, physical constants & units (mV, pA, ms, uV)
├── types.py                       # Core data structures (SpikeArray, VoltageTrace, StimulusPacket)
│
├── tissue/                        # Biological Neural & Glial Substrate
│   ├── models/                    # Point-neuron ODE solvers (LIFModel, AdExModel, IzhikevichModel)
│   ├── neurons/                   # Cellular phenotypes (PyramidalNeuron, PVInterneuron, SSTInterneuron)
│   ├── synapses/                  # Conductance (AMPA, NMDA, GABA) & Plasticity (STDP, STP, R-STDP)
│   ├── glia/                      # Dedicated Glia (Astrocyte, Oligodendrocyte, Microglia)
│   ├── profile.py                 # Declarative 3D geometries, distance kernels & TissueProfile
│   ├── network.py                 # 3D spatial placement, sparse weights & conduction delays
│   └── assembloid.py              # Multi-regional Assembloids & microfluidic AxonTunnels
│
├── interfaces/                    # Hardware & Virtual Transduction Probes
│   ├── mea.py                     # 1024-channel CMOS HD-MEA, volume conduction & Johnson noise
│   ├── opto.py                    # Micro-LED / DMD optical stimulation & 4-state opsin kinetics
│   └── hybrid.py                  # Simultaneous electrical recording & optogenetic actuation
│
├── stimulation/                   # Neural Coding & Sensory Transduction
│   ├── pulses.py                  # Biphasic charge-balanced pulses & Shannon safety criterion
│   ├── encoders.py                # RateEncoder, TTFSEncoder, PopulationVectorEncoder, DeltaEncoder
│   └── sensory.py                 # AudioTransducer (spectrograms) & VisualTransducer (receptive fields)
│
├── signals/                       # Electrophysiological Signal Processing & I/O
│   ├── filters.py                 # Zero-phase Butterworth bandpass (300-3000 Hz) & 50/60 Hz Notch
│   ├── lfp.py                     # Local Field Potential extraction & Welch PSD band powers
│   ├── detectors.py               # Quiroga MAD adaptive thresholding & TKEO spike detectors
│   ├── sorting.py                 # Real-time PCA feature extraction & K-Means spike sorting
│   ├── bursts.py                  # Single-channel burst & network synchrony avalanche detection
│   ├── visual.py                  # Publication-grade raster plots, waveforms & PCA cluster plots
│   └── io.py                      # Neurodata Without Borders (NWB 2.0) & HDF5 serialization
│
├── metrics/                       # Information Theory & Dynamical Systems Analytics
│   ├── info_theory.py             # Shannon entropy, Mutual Information, Transfer Entropy, AIS
│   ├── criticality.py             # Neuronal avalanches, branching ratio (sigma) & power-law fits
│   └── memory_capacity.py         # Jaeger linear & Legendre polynomial non-linear memory capacity
│
├── backends/                      # Interchangeable Execution Engines
│   ├── cpu.py                     # Vectorized NumPy & Numba JIT engine (1024-ch real-time twin)
│   ├── gpu.py                     # Parallel multi-organoid batch tensor engine (PyTorch / CPU)
│   ├── fpga/                      # Gigabit Ethernet UDP protocol & driver (Sipeed Tang Mega 138K)
│   ├── maxwell/                   # MaxOne, MaxTwo HD-MEA drivers & offline HDF5 replay engine
│   └── cloud/                     # OaaS FastAPI Server, Web Dashboard, OrganoidBank & OaaSClient
│
├── gym/                           # Farama Gymnasium & Active Inference (Closed-Loop)
│   ├── spaces.py                  # SensoryMotorPartition, StimulusActionSpace & Observation adapters
│   ├── active_inference.py        # VariationalFreeEnergyEstimator & ActiveInferenceController
│   └── env.py                     # OPUEnv & DishBrainPongEnv (Closed-Loop Pong in Wetware)
│
└── robotics/                      # Bio-Robotic Embodiment (Hybrots & ROS 2)
    ├── decoders.py                # DifferentialDrive, GeorgopoulosPopulation & LeakyIntegrator
    └── ros2_node.py               # LidarSensoryTransducer, OPURos2ControllerNode & HybrotArenaSimulator
```

---

## Installation

### 1. Standard Installation from PyPI

```bash
pip install pybopu
```

### 2. Installation with Optional Extras

`pybopu` provides modular dependency groups depending on your workload:

```bash
# Install everything (Numba JIT, PyTorch, Gymnasium, NWB/HDF5, FastAPI/Uvicorn, Pytest)
pip install "pybopu[all]"

# Or install specific feature sets:
pip install "pybopu[simulation]"   # Numba JIT acceleration
pip install "pybopu[ml]"           # PyTorch, scikit-learn, Farama Gymnasium
pip install "pybopu[data]"         # PyNWB, h5py, Matplotlib
pip install "pybopu[cloud]"        # FastAPI, Uvicorn, Requests, httpx2 (OaaS Cloud)
```

### 3. Editable Installation from Source (Development)

```bash
git clone https://github.com/neurohil/pybopu.git
cd pybopu
pip install -e ".[all]"
```

---

## Getting Started

### Example 1: Simulating a 3D Cortical Organoid on a 1024-Channel HD-MEA

```python
import pybopu as bopu
from pybopu import (
    Astrocyte,
    CPUBackend,
    MEAInterface,
    Microglia,
    Oligodendrocyte,
    PVInterneuron,
    PopulationSpec,
    PyramidalNeuron,
    SSTInterneuron,
    SphereGeometry,
    TissueProfile,
)

# 1. Define a 3D cortical spheroid with E/I heterogeneity and tripartite glial subsystems
profile = TissueProfile(
    name="Cortical_Spheroid_v1",
    geometry=SphereGeometry(radius_um=400.0),
    populations=[
        PopulationSpec("Exc_Pyramidal", PyramidalNeuron, count=70, is_excitatory=True),
        PopulationSpec("Inh_PV", PVInterneuron, count=15, is_excitatory=False),
        PopulationSpec("Inh_SST", SSTInterneuron, count=15, is_excitatory=False),
    ],
    astrocyte=Astrocyte(tau_ca_ms=1200.0),
    oligodendrocyte=Oligodendrocyte(base_velocity_m_s=1.5),
    microglia=Microglia(pruning_threshold=0.05),
)

# 2. Configure a 1024-channel CMOS High-Density Microelectrode Array
interface = MEAInterface(channels=1024, pitch_um=17.5, thermal_noise_uv=4.5)

# 3. Instantiate the Brain Organoid Processing Unit (OPU / BOPU)
opu = bopu.OPU(
    tissue=profile,
    interface=interface,
    backend=CPUBackend(channels=1024, use_numba=True, seed=42),
)

# 4. Deliver a charge-balanced biphasic stimulus on channel 12 and step 20 ms
spikes, lfp_trace = opu.step(duration_ms=20.0, stimulation_map={12: (45.0, 1.0)})
print(f"Clock: {opu.time_ms:.1f} ms | Detected Spikes: {len(spikes)} | LFP Shape: {lfp_trace.values_uv.shape}")
```

### Example 2: Closed-Loop Active Inference Pong (`pybopu.gym`)

```python
from pybopu import CPUBackend, DishBrainPongEnv, OPU

# Couple a 64-channel OPU to the DishBrain Pong environment with Free Energy Principle feedback
env = DishBrainPongEnv(
    opu=OPU(backend=CPUBackend(channels=64, seed=42)),
    max_steps=200,
    enable_active_inference=True,
)

obs, info = env.reset(seed=42)
for _ in range(200):
    obs, reward, terminated, truncated, step_info = env.step()
    if truncated:
        break

print(f"Hits: {env.hits} | Misses: {env.misses} | Final VFE: {step_info['variational_free_energy']:.3f} nats")
```

### Example 3: Bio-Robotic Hybrot & ROS 2 Control (`pybopu.robotics`)

```python
from pybopu import CPUBackend, HybrotArenaSimulator, OPU, OPURos2ControllerNode

arena = HybrotArenaSimulator(arena_size_m=(6.0, 6.0), right_wheel_efficiency=0.75)
ros2_node = OPURos2ControllerNode(
    opu=OPU(backend=CPUBackend(channels=64, seed=42)),
    enable_wear_adaptation=True,
)

pose = arena.reset(x_m=0.8, y_m=3.0, theta_rad=0.0)
for step_idx in range(100):
    scan = arena.compute_lidar_scan(timestamp_ms=step_idx * 20.0)
    cmd_vel = ros2_node.spin_once(scan=scan, actual_angular_w_rad_s=pose.angular_w_rad_s)
    pose = arena.step_physics(cmd_vel, dt_s=0.05)

print("ROS 2 Diagnostics:", ros2_node.get_diagnostics())
```

---

## Pedagogical Notebooks (`notebooks/`)

The `notebooks/` directory contains **23 self-contained, executable Jupyter tutorials** spanning all nine phases of organoid computing. Every notebook combines theoretical derivations, LaTeX equations, architectural schematics, publication-grade visualizations, and a 4-cell hands-on coding challenge with a collapsible reference solution and automated validation:

| Phase | # | Notebook File | Core Topics & `pybopu` Modules Covered |
| :--- | :-: | :--- | :--- |
| **Phase I: Foundations & Core Dynamics** | 01 | [`01_core_architecture_and_facade.ipynb`](notebooks/01_core_architecture_and_facade.ipynb) | OPU/BOPU paradigm, `Config`, `SpikeArray`, `VoltageTrace`, `StimulusPacket`, `OPU` facade |
| | 02 | [`02_neuron_models_and_phase_planes.ipynb`](notebooks/02_neuron_models_and_phase_planes.ipynb) | `LIFModel`, `AdExModel`, `IzhikevichModel`, F-I curves, phase-plane bifurcations |
| | 03 | [`03_neuronal_heterogeneity_and_ei_balance.ipynb`](notebooks/03_neuronal_heterogeneity_and_ei_balance.ipynb) | `PyramidalNeuron`, `PVInterneuron`, `SSTInterneuron`, cortical E/I balance |
| **Phase II: Synapses & Dedicated Glia** | 04 | [`04_synaptic_transmission_and_conductance.ipynb`](notebooks/04_synaptic_transmission_and_conductance.ipynb) | `AMPASynapse`, `NMDASynapse` ($Mg^{2+}$ block), `GABAASynapse`, `GABABSynapse` |
| | 05 | [`05_synaptic_plasticity_and_learning.ipynb`](notebooks/05_synaptic_plasticity_and_learning.ipynb) | `STDPPlasticity`, `TsodyksMarkramSTP`, 3-factor dopaminergic `RewardModulatedSTDP` |
| | 06 | [`06_glial_subsystems_and_timescales.ipynb`](notebooks/06_glial_subsystems_and_timescales.ipynb) | Tripartite `Astrocyte` $Ca^{2+}$ waves, `Oligodendrocyte` delays, `Microglia` pruning |
| **Phase III: Spatial Topology & Assembloids** | 07 | [`07_3d_spatial_tissue_and_connectivity.ipynb`](notebooks/07_3d_spatial_tissue_and_connectivity.ipynb) | 3D `SphereGeometry`, distance kernels, `TissueProfile`, `NetworkGraph` |
| | 08 | [`08_assembloids_and_modular_circuits.ipynb`](notebooks/08_assembloids_and_modular_circuits.ipynb) | Multi-regional `Assembloid` circuits & directional microfluidic `AxonTunnel` highways |
| **Phase IV: Transduction & Stimulation** | 09 | [`09_hd_mea_interfacing_and_biophysics.ipynb`](notebooks/09_hd_mea_interfacing_and_biophysics.ipynb) | 1024-ch `MEAInterface`, volume conduction, thermal noise & artifact blanking |
| | 10 | [`10_optical_and_hybrid_interfacing.ipynb`](notebooks/10_optical_and_hybrid_interfacing.ipynb) | `OptoInterface`, Beer-Lambert attenuation, ChR2/NpHR kinetics, `HybridInterface` |
| | 11 | [`11_neural_encoding_and_stimulation.ipynb`](notebooks/11_neural_encoding_and_stimulation.ipynb) | Shannon safety limit, `BiphasicPulse`, Rate/TTFS/Population encoders, `AudioTransducer` |
| **Phase V: Electrophysiology & Signals** | 12 | [`12_filtering_lfp_and_spike_detection.ipynb`](notebooks/12_filtering_lfp_and_spike_detection.ipynb) | `ButterworthBandpass`, `NotchFilter`, `extract_lfp`, Welch PSD, Quiroga `SpikeDetector` |
| | 13 | [`13_spike_sorting_bursts_and_nwb.ipynb`](notebooks/13_spike_sorting_bursts_and_nwb.ipynb) | `PCASpikeSorter`, `BurstDetector`, `NetworkSynchronyDetector`, `NWBStorage` (NWB 2.0) |
| **Phase VI: Information Theory & Criticality** | 14 | [`14_information_theory_and_entropy.ipynb`](notebooks/14_information_theory_and_entropy.ipynb) | `shannon_entropy`, `mutual_information`, `transfer_entropy`, `active_information_storage` |
| | 15 | [`15_criticality_and_memory_capacity.ipynb`](notebooks/15_criticality_and_memory_capacity.ipynb) | `CriticalityEvaluator`, branching ratio $\sigma \approx 1$, `JaegerMemoryEvaluator` |
| **Phase VII: Digital Twin Backends** | 16 | [`16_vectorized_cpu_digital_twin.ipynb`](notebooks/16_vectorized_cpu_digital_twin.ipynb) | Numba JIT `CPUBackend`, CSR synaptic sparsity, 1024-channel hard real-time benchmarks |
| | 17 | [`17_gpu_batch_simulation.ipynb`](notebooks/17_gpu_batch_simulation.ipynb) | `GPUBackend` parallel multi-organoid batch execution & hyperparameter sweeps |
| **Phase VIII: Hardware-in-the-Loop & Wetware** | 18 | [`18_fpga_hardware_in_the_loop.ipynb`](notebooks/18_fpga_hardware_in_the_loop.ipynb) | `FPGABackend`, `FPGAProtocol`, Gigabit UDP frames for Sipeed Tang Mega 138K |
| | 19 | [`19_maxwell_hd_mea_wetware.ipynb`](notebooks/19_maxwell_hd_mea_wetware.ipynb) | `MaxOneDriver`, `MaxTwoDriver`, `MaxWellReplayEngine` & 26,400-electrode CMOS routing |
| | 20 | [`20_cloud_gateway_and_dashboard.ipynb`](notebooks/20_cloud_gateway_and_dashboard.ipynb) | `OaaSServer` FastAPI microservice gateway, OpenAPI & interactive Web Cluster Dashboard |
| | 21 | [`21_distributed_oaas_wetware.ipynb`](notebooks/21_distributed_oaas_wetware.ipynb) | `OrganoidBank`, `IncubatorChamber` pH/thermal homeostasis, `OaaSClient` & WebSockets |
| **Phase IX: Embodiment & Cybernetics** | 22 | [`22_closed_loop_active_inference_pong.ipynb`](notebooks/22_closed_loop_active_inference_pong.ipynb) | `OPUEnv`, `DishBrainPongEnv`, `VariationalFreeEnergyEstimator` & predictability feedback |
| | 23 | [`23_biorobotic_embodiment_hybrot.ipynb`](notebooks/23_biorobotic_embodiment_hybrot.ipynb) | `OPURos2ControllerNode`, `HybrotArenaSimulator`, motor decoders & wheel wear adaptation |

---

## Testing & Quality Assurance

Run the full unit and integration test suite (310 tests) with `pytest`:

```bash
pytest -v
```

## Documentation

Build the Sphinx HTML API documentation locally with strict warning-as-error checking (`-W`):

```bash
sphinx-build -W -b html docs docs/_build/html
```

---

## Semantic Versioning (SemVer)

`pybopu` adheres strictly to [Semantic Versioning 2.0.0](https://semver.org/) (`MAJOR.MINOR.PATCH`). Current release: **`0.1.1`**.

## License

Distributed under the **Apache License 2.0**. See [`LICENSE`](LICENSE) for full details.
