NeuroOptic is a research-grade visual oscillator for brainwave entrainment: configurable 1-120 Hz frequencies, hardware-aware safety limits and drift-free phase accumulation.
Archived: Retired by owner request after final delivery: validation unification, sham-seed reproducibility and Nyquist fail-loudly preflight shipped; all commits pushed (archived 2026-11-16). This project is read-only; its GitHub repository is archived.
- Runtime Prerequisites: Python 3.10+ with
glfw,PyOpenGL,numpyandcustomtkinter(seerequirements.txt). - Canonical Regression Shield Gate:
python -m unittest discover
| Role | Command |
|---|---|
| Status, task and gates | python aikit.py status NeuroOptic |
| Phase 4: every gate | python aikit.py check NeuroOptic |
| Repair memory and map, then check | python aikit.py fix NeuroOptic |
| Resume an interrupted task | python aikit.py resume NeuroOptic |
NeuroOptic/
├── .gitignore <- transient AIKit state excluded
├── README.md
├── assets/
├── COMMERCIAL.md
├── core/ <- decoupled protocol mechanics & safety gates (ADR-271)
├── LICENSE
├── LICENSES/ <- REUSE license texts
├── REUSE.toml <- Machine-readable SPDX metadata
├── entrainment_engine.py <- GLFW/OpenGL entrainment engine and CLI
├── launcher.py <- customtkinter GUI controller
├── requirements.txt
├── start.bat <- 1-click Windows batch launcher (PRINCIPLE-011)
├── start.py <- 1-click starter with safe defaults & dry-run
├── test_entrainment_engine.py <- unit tests for the engine's pure logic
├── test_launcher.py <- automated headless tests for the controller
├── test_mechanics.py <- unit tests for headless protocol mechanics
├── test_start.py <- unit tests for one-click starter
└── .aikit/ <- this project's memory: record, ledger, decisions, map
NeuroOptic is a research-grade visual oscillator designed for precise brainwave entrainment. It supports configurable frequencies (1–120 Hz) with hardware-aware safety limits and drift-free phase accumulation.
- Precision Oscillator: 0.01 Hz resolution using a monotonic high-resolution clock.
- Hardware-Aware: Automatically detects monitor refresh rates and enforces Nyquist safety limits (e.g., Max 30Hz on a 60Hz screen).
- Waveforms:
- Sine: Physiological oscillatory mimicry (Default).
- Square: Strong entrainment (Binary On/Off).
- Triangle: Linear fade in/out.
- AM Carrier: High-frequency carrier modulated at target frequency.
- Stimulation Modes:
- Full Screen: Standard entrainment.
- Split Hemifield: Independent Left/Right control for binocular beats or lateralized stimulation.
- Peripheral Ring: Foveal sparing stimulation.
- Quadrants: Retinotopic mapping support (Top-Left, Bottom-Right, etc.).
- Research & Sham Control:
- Detune: Frequency drifts slightly to prevent entrainment.
- Low Amp: Sub-threshold intensity.
- Jitter: Randomized phase timing.
- Static: Non-flickering control (0.5 hold, SINE phase 0).
- Tech Stack: Python, GLFW, OpenGL (VSync enabled).
- Install dependencies:
pip install -r requirements.txt
Launch NeuroOptic instantly with verified bio-safe presets (PRINCIPLE-011):
# Windows: double-click start.bat or run:
start.bat
# Multi-platform 1-click launch to GUI:
python start.py
# 1-click start safe 40Hz Gamma entrainment directly (5s ramp):
# fails with a Why/Fix remediation on displays under 85 Hz (Nyquist: 40 Hz needs refresh >= 85 Hz)
python start.py --quick
# 1-click start safe 10Hz Alpha entrainment directly (5s ramp, valid on every display):
python start.py --alpha
# Headless parameter & dependency validation (checks against your detected refresh rate):
python start.py --dry-runLaunch the GUI controller:
python launcher.pyRun the engine via command line:
# Default (40Hz Gamma, Sine wave)
python entrainment_engine.py
# Custom Frequency (e.g., 10Hz Alpha)
python entrainment_engine.py --freq 10.0
# Square Wave (Strong entrainment)
python entrainment_engine.py --freq 40.0 --waveform square
# Amplitude Modulated
python entrainment_engine.py --freq 40.0 --waveform am
# Split Hemifield (Binocular Beats: Left 10Hz, Right 11Hz)
python entrainment_engine.py --mode split --freq 10.0 --freq-right 11.0
# Research Mode (Sham: Detuned Frequency)
python entrainment_engine.py --freq 40.0 --sham detune
# Session Control (10 min session, 5s ramp-up)
python entrainment_engine.py --duration 600 --ramp 5.0
# Declarative Protocol Execution (Subagent & Research automation)
python entrainment_engine.py --protocol protocol.json
# Headless Protocol Validation (Dry-run without display)
python entrainment_engine.py --protocol protocol.json --dry-runAI-Generated Brand Artwork. The banner and logo are AI-generated brand assets. They are illustrative and may not literally depict every feature or the full project scope.
Free for personal use under the Aegean License 1.1 (AL-1.1); see LICENSE. Any commercial use needs the Aegean Commercial License 1.0 (ACL-1.0); see COMMERCIAL.md.
commit bff3d7b · 2026-11-16
commit bff3d7b · 2026-11-16
commit 36f9038 · 2026-11-03



