Metadata-Version: 2.4
Name: neurosim
Version: 0.1.0
Summary: A Gymnasium platform for reinforcement learning in brain-computer interfaces
Project-URL: Repository, https://github.com/HassDhia/neurosim
Project-URL: Documentation, https://github.com/HassDhia/neurosim#readme
Author-email: Hass Dhia <partners@smarttechinvest.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT 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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: gymnasium>=0.29
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.11
Provides-Extra: all
Requires-Dist: mne>=1.6; extra == 'all'
Requires-Dist: moabb>=1.0; extra == 'all'
Requires-Dist: mypy; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff; extra == 'all'
Requires-Dist: stable-baselines3>=2.0; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Provides-Extra: data
Requires-Dist: mne>=1.6; extra == 'data'
Requires-Dist: moabb>=1.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: surrogate
Requires-Dist: torch>=2.0; extra == 'surrogate'
Provides-Extra: train
Requires-Dist: stable-baselines3>=2.0; extra == 'train'
Requires-Dist: torch>=2.0; extra == 'train'
Description-Content-Type: text/markdown

# NeuroSim

**A Gymnasium Platform for Reinforcement Learning in Brain-Computer Interfaces**

![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Tests](https://img.shields.io/badge/tests-158%20passing-brightgreen.svg)
[![PyPI version](https://img.shields.io/pypi/v/neurosim.svg)](https://pypi.org/project/neurosim/)

---

NeuroSim is a Gymnasium-compatible reinforcement learning environment suite for brain-computer interfaces. It provides three environments modeling motor imagery decoding, intracortical cursor control, and P300 speller stimulus selection. The package includes pluggable signal models (electrode drift, fatigue, co-adaptation, noise), a conditional VAE neural surrogate, CSP+LDA classical baseline, PPO RL baseline, and a five-tier benchmark suite for reproducible evaluation across drift conditions and subject variability.

## Installation

```bash
pip install neurosim              # Core (numpy, scipy, gymnasium)
pip install neurosim[train]       # + SB3, PyTorch for RL training
pip install neurosim[data]        # + MNE, MOABB for real EEG data
pip install neurosim[surrogate]   # + PyTorch for neural surrogate
pip install neurosim[all]         # Everything
```

Development install:

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

## Quick Start

```python
import gymnasium as gym
import neurosim

env = gym.make("neurosim/DecoderAdapt-v0")
obs, info = env.reset(seed=42)
for _ in range(100):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    if terminated or truncated:
        obs, info = env.reset()
env.close()
```

## Environments

| Environment | Paradigm | Observation | Action | Key Challenge |
|---|---|---|---|---|
| `DecoderAdapt-v0` | Motor imagery | 55-dim (neural + confidence + drift) | Dict: classify, recalibrate, adapt | When to recalibrate under electrode drift |
| `CursorControl-v0` | Intracortical | 96x5 neural state + cursor + target | Box(2) velocity | Continuous control through neural noise |
| `SpellerNav-v0` | P300 speller | 36-posterior + ERP history | Dict: stimulus group, commit | Balance evidence vs communication speed |

## Signal Models

NeuroSim implements pluggable signal degradation models that simulate real-world BCI non-stationarity:

- **Electrode drift** -- impedance degradation over session time, modeled as monotonic SNR reduction per channel
- **Fatigue drift** -- exponential saturation of motor imagery signal quality with sustained use
- **Feature shift** -- sudden and continuous distributional shifts in the neural feature space
- **Co-adaptation** -- bidirectional user-decoder coupling where the user's neural patterns change in response to decoder behavior
- **Noise injection** -- pink (1/f) noise, EMG artifact, blink artifact, and 50/60 Hz line noise at configurable intensities

## Benchmark Tiers

| Tier | Condition | Drift Sources |
|---|---|---|
| T1 | Stationary -- no drift, low noise | None |
| T2 | Mild -- electrode drift, medium noise | Electrode |
| T3 | Full -- all drift, medium noise | Electrode, fatigue, feature, co-adaptation |
| T4 | Cross-subject -- multi-subject, high noise | All |
| T5 | Adversarial -- sudden shifts, high noise | All + sudden |

## Training Agents

Train a PPO agent and run the benchmark suite from the command line:

```bash
neurosim-train --env DecoderAdapt-v0 --steps 100000
neurosim-benchmark --tier T1 --episodes 50
```

Or use Stable-Baselines3 directly:

```python
from stable_baselines3 import PPO
import gymnasium as gym
import neurosim

env = gym.make("neurosim/DecoderAdapt-v0")
model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=100_000)
model.save("ppo_decoder_adapt")
```

## Citation

If you use NeuroSim in your research, please cite:

```bibtex
@software{neurosim2026,
  author = {Dhia, Hass},
  title = {NeuroSim: A Gymnasium Platform for RL in Brain-Computer Interfaces},
  year = {2026},
  url = {https://github.com/HassDhia/neurosim},
}
```

## License

MIT -- see [LICENSE](LICENSE) for details.
