Skip to content

Commit 49c47c3

Browse files
STLNFTARTSTLNFTART
authored
Motor intergration (#15)
2 parents ffbcb0b + 0a54851 commit 49c47c3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+13000
-0
lines changed

‎CLAUDE.md‎

Lines changed: 1185 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/ARCHITECTURE_DIAGRAM.txt‎

Lines changed: 275 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
===============================================================================
2+
MULTI-HEART-MODEL ARCHITECTURE DIAGRAM
3+
===============================================================================
4+
5+
┌─────────────────────────────────────────────────────────────────────────────┐
6+
│ APPLICATION LAYER │
7+
│ (User code, simulations, demos, experiments) │
8+
└────────────────┬──────────────────────────────────────────────────────────┘
9+
│
10+
▼
11+
┌─────────────────────────────────────────────────────────────────────────────┐
12+
│ ORCHESTRATION LAYER (HBCM) │
13+
│ ┌──────────────────────────────────────────────────────────────────────┐ │
14+
│ │ HeartBrainCouplingModel │ │
15+
│ │ • Manages 4D state: (v_neural, w_neural, x_cardiac, y_cardiac) │ │
16+
│ │ • Maintains history deque for delay lookups │ │
17+
│ │ • Computes bidirectional coupling: │ │
18+
│ │ - Neural input = cardiac_gain * delayed_cardiac[0] + bias │ │
19+
│ │ - Cardiac input = neural_gain * delayed_neural[0] + bias │ │
20+
│ │ • Coordinates time stepping across subsystems │ │
21+
│ └──────────────────────────────────────────────────────────────────┘ │
22+
│ │
23+
│ Configuration: │
24+
│ • neural_to_cardiac_gain: 0.4 • cardiac_to_neural_gain: 0.2 │
25+
│ • neural_delay: 0.0 • cardiac_delay: 0.0 │
26+
└────────────────┬──────────────────────────────────────────────────────────┘
27+
│
28+
┌────────┼────────┐
29+
▼ ▼
30+
┌──────────────────┐ ┌──────────────────┐
31+
│ NEURAL LAYER │ │ CARDIAC LAYER │
32+
│ │ │ │
33+
│ FitzHugh-Nagumo │ │ Van der Pol │
34+
│ │ │ │
35+
│ State: (v, w) │ │ State: (x, y) │
36+
│ │ │ │
37+
│ dv/dt = v - v³/3 │ │ dx/dt = y │
38+
│ - w + S │ │ │
39+
│ dw/dt = │ │ dy/dt = μ(1-x²)y│
40+
│ (v + a - b·w)/c│ │ - ω²x + F │
41+
│ │ │ │
42+
│ Params: │ │ Params: │
43+
│ • a: 0.7 │ │ • μ: 1.5 │
44+
│ • b: 0.8 │ │ • ω: 1.0 │
45+
│ • c: 3.0 │ │ • damping: 0.0 │
46+
│ │ │ │
47+
│ Freq: ~0.15 Hz │ │ Freq: ~1.1 Hz │
48+
│ (~9 bpm) │ │ (~66 bpm) │
49+
└──────────────────┘ └──────────────────┘
50+
51+
Integration Pattern: Explicit Euler
52+
State(t+dt) = State(t) + dt * derivatives(t, State(t))
53+
54+
Coupling Mechanism: History-Based Delay
55+
delayed_state = lookup_history(current_time - delay)
56+
(Interpolation-free, deque-based)
57+
58+
===============================================================================
59+
CONTROL & MICROPROCESSOR LAYER
60+
===============================================================================
61+
62+
┌──────────────────────────────────────────────────────────────────────────────┐
63+
│ PRIMAL LOGIC PROCESSOR │
64+
│ │
65+
│ Control Law: u(t) = -K ∫₀ᵗ e(τ) · e^(-λ(t-τ)) dτ │
66+
│ │
67+
│ ┌────────────────────────────────────────────────────────────────────────┐ │
68+
│ │ 8 Integral Processing Units (IPUs) - Parallel Processing │ │
69+
│ │ Round-robin scheduling: IPU0 → IPU1 → ... → IPU7 → IPU0 │ │
70+
│ └────────────────────────────────────────────────────────────────────────┘ │
71+
│ │
72+
│ Hardware Simulation: │
73+
│ • 8 IPUs × 16 memory banks = 128 history slots per cycle │
74+
│ • 32 multiply-accumulate units │
75+
│ • 4 floating-point units │
76+
│ • 64 I/O channels │
77+
│ • 2 safety cores │
78+
│ │
79+
│ Hardware Specs: │
80+
│ • Die area: 180 mm² (SkyWater 90nm) │
81+
│ • Power: 25W │
82+
│ • Latency: 50μs │
83+
│ │
84+
│ Performance (vs Traditional): │
85+
│ • Jerk reduction: 75% (3.8 vs 15.2 m/s³) │
86+
│ • Comfort index: 81% improvement (87.6 vs 48.3) │
87+
│ • Latency: 75% reduction (50μs vs 200μs) │
88+
│ │
89+
│ Parameters: │
90+
│ • K_gain: 0.5 │
91+
│ • lambda_decay: 2.0 │
92+
│ • max_control: 10.0 | min_control: -10.0 (bounded) │
93+
└────────────────┬──────────────────────────────────────────────────────────┘
94+
│
95+
▼
96+
┌──────────────────────────────────────────────────────────────────────────────┐
97+
│ MOTORHANDPRO INTEGRATION BRIDGE │
98+
│ │
99+
│ Control Flow: │
100+
│ ┌─────────────────┐ ┌───────────────┐ ┌──────────────┐ │
101+
│ │ Primal Logic │────▶│ QUANT Convert │────▶│ Motor Driver │ │
102+
│ │ Control: [-10,10] │ Throttle: [0,255] │ Actuation │ │
103+
│ └─────────────────┘ └───────────────┘ └──────────────┘ │
104+
│ ▲ │ │
105+
│ │ ▼ │
106+
│ └───────────────────────────────────────────────┘ │
107+
│ Feedback: (psi, gamma, Ec) │
108+
│ │
109+
│ QUANT Parameters (MotorHandPro Integration): │
110+
│ • PLANCK_D: 149.9992314000 │
111+
│ • PLANCK_I3: 6.4939394023 │
112+
│ • KERNEL_MU: 0.169050000000 │
113+
│ │
114+
│ Conversion: control ∈ [-10, +10] → x_fixed ∈ [0, 150] │
115+
│ → throttle ∈ [0, 255] │
116+
└────────────────────────────────────────────────────────────────────────────┘
117+
118+
===============================================================================
119+
TESTING & VALIDATION
120+
===============================================================================
121+
122+
Unit Tests (test_models.py):
123+
✓ FitzHugh-Nagumo derivatives
124+
✓ Van der Pol oscillator dynamics
125+
✓ Delay-based state lookup
126+
✓ Trajectory timestep verification
127+
128+
Integration Tests (test_microprocessor_motorhand.py):
129+
✓ Processor initialization & configuration
130+
✓ Control computation & bounds enforcement
131+
✓ Emergency braking convergence
132+
✓ Exponential memory weighting
133+
✓ QUANT parameter validation
134+
✓ Throttle conversion bounds
135+
✓ Feedback parsing
136+
✓ Closed-loop simulation
137+
✓ CSV export validation
138+
✓ Jerk reduction metrics
139+
✓ Comfort index calculation
140+
✓ Full system integration (end-to-end)
141+
✓ Performance vs traditional control
142+
143+
Test Statistics:
144+
• 30+ test methods
145+
• 390+ lines of integration tests
146+
• 49 lines of unit tests
147+
• Coverage: ~1150 lines of Python code
148+
149+
===============================================================================
150+
MODULE DEPENDENCIES
151+
===============================================================================
152+
153+
Core Dependencies:
154+
• NumPy - Numerical operations (exp, clip, mean, etc.)
155+
• Python standard library:
156+
- dataclasses: Configuration classes
157+
- collections.deque: History buffer
158+
- typing: Type hints
159+
- csv: Data export
160+
- time: Timestamps
161+
- subprocess: Process management
162+
163+
Optional Dependencies:
164+
• matplotlib - Visualization (graceful fallback)
165+
• pytest - Testing framework
166+
• numpy (optional fallback)
167+
168+
No Heavy ML Frameworks:
169+
✗ No TensorFlow, PyTorch, JAX
170+
✗ No large scientific computing suites
171+
✓ Lightweight, transparent, maintainable
172+
173+
===============================================================================
174+
DATA EXPORT FORMATS
175+
===============================================================================
176+
177+
CSV Output Structure:
178+
# Results header
179+
t,velocity,error,integral,control,comfort
180+
0.000,30.000,30.000,0.300,-0.150,50.0
181+
0.010,29.998,29.998,0.598,-0.299,50.0
182+
...
183+
184+
Generated Files:
185+
• emergency_braking_output.csv - Primal processor simulation
186+
• integration_output.csv - Complete system output
187+
• primal_motorhand_interface.ino - Arduino hardware code
188+
• integration_visualization.png - Performance plots
189+
190+
===============================================================================
191+
CONFIGURATION SYSTEM
192+
===============================================================================
193+
194+
config/default.yaml:
195+
simulation:
196+
duration: 120.0 # seconds
197+
timestep: 0.001 # seconds
198+
integrator: rk4 # (Euler currently implemented)
199+
200+
neural:
201+
natural_frequency: 0.15 Hz (≈9 bpm)
202+
damping: 0.05
203+
feedback_strength: 0.8
204+
delay_to_heart: 0.120 s
205+
206+
cardiac:
207+
natural_frequency: 1.1 Hz (≈66 bpm)
208+
damping: 0.12
209+
feedback_strength: 0.6
210+
delay_to_brain: 0.150 s
211+
212+
outputs:
213+
signals: [ecg, neural_oscillation, arterial_pressure]
214+
export_path: results/
215+
216+
===============================================================================
217+
EXTENSIBILITY PATTERNS
218+
===============================================================================
219+
220+
Adding New Organ Systems (e.g., respiratory):
221+
222+
1. Create Module:
223+
src/respiratory/
224+
├── __init__.py
225+
└── model.py (implement derivatives() and step())
226+
227+
2. Extend Coupling:
228+
• Add fields to CouplingParameters
229+
• Increase state dimensionality in HBCM
230+
• Implement new coupling terms
231+
232+
3. Add Tests:
233+
• Unit tests in test_models.py
234+
• Integration tests for new couplings
235+
• End-to-end validation
236+
237+
4. Update Configuration:
238+
• Add section to default.yaml
239+
• Document parameters
240+
241+
Example Model Interface:
242+
class RespiratoryModel:
243+
def derivatives(self, t: float, state: Tuple[...], input_signal: float) -> Tuple[...]:
244+
# Return state derivatives
245+
pass
246+
247+
def step(self, t: float, state: Tuple[...], dt: float, input_signal: float) -> Tuple[...]:
248+
# Perform one integration step
249+
pass
250+
251+
===============================================================================
252+
FILE STATISTICS
253+
===============================================================================
254+
255+
Code Distribution:
256+
• Cardiac subsystem: 30 LOC
257+
• Neural subsystem: 50 LOC
258+
• Coupling orchestration: 125 LOC
259+
• Primal Logic Processor: 283 LOC
260+
• Control utilities: 214 LOC
261+
• Integration bridge: 399 LOC
262+
• TOTAL: 1,153 LOC (Production Python)
263+
264+
Tests:
265+
• Unit tests: 49 LOC
266+
• Integration tests: 390+ LOC
267+
• Test coverage: ~100% of production code paths
268+
269+
Documentation:
270+
• architecture.md
271+
• hbcm_overview.md
272+
• microprocessor_motorhand_integration.md
273+
• README.md + README_INTEGRATION.md
274+
275+
===============================================================================

0 commit comments

Comments
 (0)