pybopu 0.1.0__py3-none-any.whl

pybopu/__init__.py

@@ -0,0 +1,329 @@
+"""pybopu: Organoid Processing Unit for Python.
+
+A modular, type-annotated biocomputing framework for simulating, programming,
+and interfacing with 3D neural organoids, in vitro wetware, and digital twins.
+"""
+
+from pybopu.config import Config, PhysicalUnits, UNITS, default_config
+from pybopu.opu import BOPU, OPU
+from pybopu.types import SpikeArray, StimulusPacket, VoltageTrace
+from pybopu.backends.base import BaseBackend
+from pybopu.backends.cpu import CPUBackend
+from pybopu.backends.gpu import GPUBackend
+from pybopu.backends.fpga import FPGABackend, FPGADriver, FPGAProtocol
+from pybopu.backends.maxwell import (
+    MaxOneDriver,
+    MaxTwoDriver,
+    MaxWellReplayEngine,
+    MaxWellBackend,
+)
+from pybopu.backends.cloud import (
+    ClusterNodeInfo,
+    CorticalLabsAdapter,
+    FinalSparkAdapter,
+    IncubatorChamber,
+    LifeSupportTelemetry,
+    MotorReadout,
+    OaaSBackend,
+    OaaSClient,
+    OaaSServer,
+    OrganoidBank,
+    get_dashboard_html,
+)
+from pybopu.tissue.models import AdExModel, BaseNeuronModel, IzhikevichModel, LIFModel
+from pybopu.tissue.neurons import BaseNeuron, PyramidalNeuron, PVInterneuron, SSTInterneuron
+from pybopu.tissue.synapses import (
+    BaseSynapse,
+    AMPASynapse,
+    NMDASynapse,
+    DualExcitatorySynapse,
+    GABAASynapse,
+    GABABSynapse,
+    DualInhibitorySynapse,
+    BasePlasticity,
+    TsodyksMarkramSTP,
+    STDPPlasticity,
+    RewardModulatedSTDP,
+)
+from pybopu.tissue.glia import (
+    BaseGlia,
+    Astrocyte,
+    Oligodendrocyte,
+    Microglia,
+)
+from pybopu.tissue.network import NetworkGraph
+from pybopu.tissue.profile import (
+    BaseGeometry,
+    SphereGeometry,
+    EllipsoidGeometry,
+    CylinderGeometry,
+    BaseDistanceKernel,
+    ExponentialDistanceKernel,
+    GaussianDistanceKernel,
+    ConnectionRule,
+    PopulationSpec,
+    TissueProfile,
+)
+from pybopu.tissue.assembloid import (
+    AxonTunnel,
+    AssembloidRegion,
+    Assembloid,
+)
+from pybopu.interfaces import (
+    BaseInterface,
+    MEAInterface,
+    OpsinKinetics,
+    OptoInterface,
+    HybridInterface,
+)
+from pybopu.stimulation import (
+    SHANNON_SAFETY_LIMIT_K,
+    BiphasicPulse,
+    check_shannon_criterion,
+    create_biphasic_pulse,
+    create_biphasic_train,
+    BaseEncoder,
+    RateEncoder,
+    TTFSEncoder,
+    PopulationVectorEncoder,
+    DeltaEncoder,
+    AudioTransducer,
+    VisualTransducer,
+)
+from pybopu.signals import (
+    ButterworthBandpass,
+    NotchFilter,
+    filter_trace,
+    extract_lfp,
+    compute_psd,
+    compute_band_powers,
+    SpectralBands,
+    SpikeDetector,
+    SignalProcessor,
+    estimate_quiroga_noise_std,
+    BaseSpikeSorter,
+    PCASpikeSorter,
+    SpikeSortResult,
+    compute_cluster_snr,
+    compute_refractory_violations,
+    compute_isolation_distance,
+    BurstEvent,
+    NetworkBurstEvent,
+    BurstDetector,
+    NetworkSynchronyDetector,
+    compute_fano_factor,
+    compute_synchrony_index,
+    plot_raster,
+    plot_sorted_waveforms,
+    plot_pca_features,
+    plot_network_burst_profile,
+    BaseElectrophysiologyStorage,
+    NWBStorage,
+    HDF5Storage,
+    save_to_nwb,
+    load_from_nwb,
+)
+from pybopu.metrics import (
+    AvalancheEvent,
+    CriticalityEvaluator,
+    InfoTheory,
+    JaegerMemoryEvaluator,
+    active_information_storage,
+    bin_spike_train,
+    compute_avalanche_distributions,
+    compute_branching_ratio,
+    compute_memory_capacity,
+    compute_nonlinear_memory_capacity,
+    compute_transfer_entropy_matrix,
+    conditional_entropy,
+    detect_avalanches,
+    discretize_multi_channel,
+    fit_power_law,
+    joint_entropy,
+    mutual_information,
+    shannon_entropy,
+    transfer_entropy,
+)
+from pybopu.gym import (
+    ActiveInferenceController,
+    DishBrainPongEnv,
+    ElectrophysiologyObservationSpace,
+    FreeEnergyMetrics,
+    OPUEnv,
+    SensoryMotorPartition,
+    StimulusActionSpace,
+    VariationalFreeEnergyEstimator,
+)
+from pybopu.robotics import (
+    BaseMotorDecoder,
+    DifferentialDriveDecoder,
+    GeorgopoulosPopulationDecoder,
+    HybrotArenaSimulator,
+    LaserScanPacket,
+    LeakyIntegratorTorqueDecoder,
+    LidarSensoryTransducer,
+    OPURos2ControllerNode,
+    OdometryState,
+    VelocityCommand,
+)
+
+__version__ = "0.1.0"
+
+
+__all__ = [
+    "__version__",
+    "OPU",
+    "BOPU",
+    "Config",
+    "PhysicalUnits",
+    "UNITS",
+    "default_config",
+    "SpikeArray",
+    "VoltageTrace",
+    "StimulusPacket",
+    "BaseBackend",
+    "CPUBackend",
+    "GPUBackend",
+    "FPGABackend",
+    "FPGADriver",
+    "FPGAProtocol",
+    "MaxOneDriver",
+    "MaxTwoDriver",
+    "MaxWellReplayEngine",
+    "MaxWellBackend",
+    "OaaSBackend",
+    "OaaSServer",
+    "ClusterNodeInfo",
+    "IncubatorChamber",
+    "OrganoidBank",
+    "get_dashboard_html",
+    "OaaSClient",
+    "FinalSparkAdapter",
+    "CorticalLabsAdapter",
+    "LifeSupportTelemetry",
+    "MotorReadout",
+    "BaseNeuronModel",
+    "LIFModel",
+    "AdExModel",
+    "IzhikevichModel",
+    "BaseNeuron",
+    "PyramidalNeuron",
+    "PVInterneuron",
+    "SSTInterneuron",
+    "BaseSynapse",
+    "AMPASynapse",
+    "NMDASynapse",
+    "DualExcitatorySynapse",
+    "GABAASynapse",
+    "GABABSynapse",
+    "DualInhibitorySynapse",
+    "BasePlasticity",
+    "TsodyksMarkramSTP",
+    "STDPPlasticity",
+    "RewardModulatedSTDP",
+    "BaseGlia",
+    "Astrocyte",
+    "Oligodendrocyte",
+    "Microglia",
+    "NetworkGraph",
+    "BaseGeometry",
+    "SphereGeometry",
+    "EllipsoidGeometry",
+    "CylinderGeometry",
+    "BaseDistanceKernel",
+    "ExponentialDistanceKernel",
+    "GaussianDistanceKernel",
+    "ConnectionRule",
+    "PopulationSpec",
+    "TissueProfile",
+    "AxonTunnel",
+    "AssembloidRegion",
+    "Assembloid",
+    "BaseInterface",
+    "MEAInterface",
+    "OpsinKinetics",
+    "OptoInterface",
+    "HybridInterface",
+    "SHANNON_SAFETY_LIMIT_K",
+    "BiphasicPulse",
+    "check_shannon_criterion",
+    "create_biphasic_pulse",
+    "create_biphasic_train",
+    "BaseEncoder",
+    "RateEncoder",
+    "TTFSEncoder",
+    "PopulationVectorEncoder",
+    "DeltaEncoder",
+    "AudioTransducer",
+    "VisualTransducer",
+    "ButterworthBandpass",
+    "NotchFilter",
+    "filter_trace",
+    "extract_lfp",
+    "compute_psd",
+    "compute_band_powers",
+    "SpectralBands",
+    "SpikeDetector",
+    "SignalProcessor",
+    "estimate_quiroga_noise_std",
+    "BaseSpikeSorter",
+    "PCASpikeSorter",
+    "SpikeSortResult",
+    "compute_cluster_snr",
+    "compute_refractory_violations",
+    "compute_isolation_distance",
+    "BurstEvent",
+    "NetworkBurstEvent",
+    "BurstDetector",
+    "NetworkSynchronyDetector",
+    "compute_fano_factor",
+    "compute_synchrony_index",
+    "plot_raster",
+    "plot_sorted_waveforms",
+    "plot_pca_features",
+    "plot_network_burst_profile",
+    "BaseElectrophysiologyStorage",
+    "NWBStorage",
+    "HDF5Storage",
+    "save_to_nwb",
+    "load_from_nwb",
+    "InfoTheory",
+    "AvalancheEvent",
+    "CriticalityEvaluator",
+    "JaegerMemoryEvaluator",
+    "active_information_storage",
+    "bin_spike_train",
+    "compute_avalanche_distributions",
+    "compute_branching_ratio",
+    "compute_memory_capacity",
+    "compute_nonlinear_memory_capacity",
+    "compute_transfer_entropy_matrix",
+    "conditional_entropy",
+    "detect_avalanches",
+    "discretize_multi_channel",
+    "fit_power_law",
+    "joint_entropy",
+    "mutual_information",
+    "shannon_entropy",
+    "transfer_entropy",
+    "OPUEnv",
+    "DishBrainPongEnv",
+    "SensoryMotorPartition",
+    "StimulusActionSpace",
+    "ElectrophysiologyObservationSpace",
+    "ActiveInferenceController",
+    "VariationalFreeEnergyEstimator",
+    "FreeEnergyMetrics",
+    "VelocityCommand",
+    "BaseMotorDecoder",
+    "DifferentialDriveDecoder",
+    "GeorgopoulosPopulationDecoder",
+    "LeakyIntegratorTorqueDecoder",
+    "LaserScanPacket",
+    "OdometryState",
+    "LidarSensoryTransducer",
+    "OPURos2ControllerNode",
+    "HybrotArenaSimulator",
+]
+
+

pybopu/backends/__init__.py

@@ -0,0 +1,61 @@
+"""Execution backends: CPU digital twin, GPU batches, FPGA, MaxWell HD-MEA, and Cloud OaaS."""
+
+from pybopu.backends.base import BaseBackend
+from pybopu.backends.cpu import CPUBackend
+from pybopu.backends.gpu import GPUBackend, HAS_TORCH
+from pybopu.backends.fpga import FPGABackend, FPGADriver, FPGAProtocol
+from pybopu.backends.maxwell import (
+    MaxOneDriver,
+    MaxTwoDriver,
+    MaxWellReplayEngine,
+    MaxWellBackend,
+)
+from pybopu.backends.cloud import (
+    ClusterNodeInfo,
+    CorticalLabsAdapter,
+    FinalSparkAdapter,
+    IncubatorChamber,
+    LifeSupportTelemetry,
+    MotorReadout,
+    OaaSAuthenticationError,
+    OaaSBackend,
+    OaaSClient,
+    OaaSConnectionError,
+    OaaSServer,
+    OaaSTimeoutError,
+    OrganoidBank,
+    SessionInfo,
+    get_dashboard_html,
+)
+from pybopu.backends.jit_kernels import HAS_NUMBA
+
+__all__ = [
+    "BaseBackend",
+    "CPUBackend",
+    "GPUBackend",
+    "FPGABackend",
+    "FPGADriver",
+    "FPGAProtocol",
+    "MaxOneDriver",
+    "MaxTwoDriver",
+    "MaxWellReplayEngine",
+    "MaxWellBackend",
+    "OaaSBackend",
+    "OaaSServer",
+    "ClusterNodeInfo",
+    "IncubatorChamber",
+    "OrganoidBank",
+    "get_dashboard_html",
+    "OaaSClient",
+    "FinalSparkAdapter",
+    "CorticalLabsAdapter",
+    "LifeSupportTelemetry",
+    "MotorReadout",
+    "SessionInfo",
+    "OaaSConnectionError",
+    "OaaSAuthenticationError",
+    "OaaSTimeoutError",
+    "HAS_NUMBA",
+    "HAS_TORCH",
+]
+

pybopu/backends/base.py

@@ -0,0 +1,107 @@
+"""Abstract base execution backend for pybopu.
+
+This module formalizes the contract for all computational and physical execution
+engines in the pybopu ecosystem (CPU, GPU, FPGA, MaxWell HD-MEA, and Cloud OaaS).
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Tuple
+
+from pybopu.types import SpikeArray, StimulusPacket, VoltageTrace
+
+
+class BaseBackend(ABC):
+    """Abstract base class establishing the execution engine contract.
+
+    All backends must adhere to this uniform interface to allow seamless
+    interchangeability across CPU digital twins, GPU batches, FPGA hardware-in-the-loop,
+    and physical living wetware.
+
+    Parameters
+    ----------
+    name : str, default="BaseBackend"
+        Human-readable descriptor of the backend engine.
+    """
+
+    def __init__(self, name: str = "BaseBackend") -> None:
+        self._name: str = name
+        self._current_time_ms: float = 0.0
+        self._is_initialized: bool = False
+        self._step_count: int = 0
+
+    @property
+    def name(self) -> str:
+        """Return the unique backend name."""
+        return self._name
+
+    @property
+    def current_time_ms(self) -> float:
+        """Current biological simulation/recording clock in milliseconds."""
+        return self._current_time_ms
+
+    @property
+    def is_initialized(self) -> bool:
+        """Return True if the backend has been initialized with tissue and interface."""
+        return self._is_initialized
+
+    @property
+    def step_count(self) -> int:
+        """Total number of execution steps completed."""
+        return self._step_count
+
+    @abstractmethod
+    def initialize(self, tissue: Any = None, interface: Any = None) -> None:
+        """Initialize backend state variables, memory buffers, or hardware links.
+
+        Parameters
+        ----------
+        tissue : Any, optional
+            Tissue specifications (e.g., TissueProfile, NetworkGraph).
+        interface : Any, optional
+            Hardware probe configuration (e.g., MEAInterface, OptoInterface).
+        """
+        pass
+
+    @abstractmethod
+    def step(
+        self,
+        duration_ms: float,
+        stimulus: Optional[StimulusPacket] = None
+    ) -> Tuple[SpikeArray, VoltageTrace]:
+        """Execute a single simulation or acquisition step.
+
+        Parameters
+        ----------
+        duration_ms : float
+            Duration of the step to advance in milliseconds. Must be positive.
+        stimulus : Optional[StimulusPacket], default=None
+            Optional sensory or actuation stimulus to deliver during this step.
+
+        Returns
+        -------
+        spikes : SpikeArray
+            Spike occurrences recorded or simulated during this step.
+        voltages : VoltageTrace
+            Continuous local field potentials or extracellular voltages.
+        """
+        pass
+
+    @abstractmethod
+    def reset(self) -> None:
+        """Reset internal simulation clocks, synaptic weights, and dynamic state variables."""
+        pass
+
+    def get_status(self) -> Dict[str, Any]:
+        """Return an operational telemetry snapshot of the backend state.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Dictionary containing backend name, clock, initialization status, and step count.
+        """
+        return {
+            "name": self._name,
+            "current_time_ms": self._current_time_ms,
+            "is_initialized": self._is_initialized,
+            "step_count": self._step_count,
+        }

pybopu/backends/cloud/__init__.py

@@ -0,0 +1,39 @@
+"""Organoid as a Service (OaaS) cloud adapters and backends.
+
+Provides remote network connectivity and simulation adapters for cloud-hosted
+living neural organoids and in vitro wetware systems, including FinalSpark
+Neuroplatform and Cortical Labs CL1.
+"""
+
+from pybopu.backends.cloud.client import (
+    OaaSAuthenticationError,
+    OaaSClient,
+    OaaSConnectionError,
+    OaaSTimeoutError,
+    SessionInfo,
+)
+from pybopu.backends.cloud.finalspark import FinalSparkAdapter, LifeSupportTelemetry
+from pybopu.backends.cloud.corticallabs import CorticalLabsAdapter, MotorReadout
+from pybopu.backends.cloud.backend import OaaSBackend
+from pybopu.backends.cloud.cluster import IncubatorChamber, OrganoidBank
+from pybopu.backends.cloud.dashboard import get_dashboard_html
+from pybopu.backends.cloud.server import ClusterNodeInfo, OaaSServer
+
+__all__ = [
+    "OaaSClient",
+    "SessionInfo",
+    "OaaSConnectionError",
+    "OaaSAuthenticationError",
+    "OaaSTimeoutError",
+    "FinalSparkAdapter",
+    "LifeSupportTelemetry",
+    "CorticalLabsAdapter",
+    "MotorReadout",
+    "OaaSBackend",
+    "OaaSServer",
+    "ClusterNodeInfo",
+    "IncubatorChamber",
+    "OrganoidBank",
+    "get_dashboard_html",
+]
+