ARCHITECTURE.md

Architecture

Overview

The project has two orthogonal compute layers:

1. Biophysical layer (continuous-time approximation)
2. Digital NAND layer (discrete Boolean logic)

These are intentionally independent so each can be evolved and tested without coupling risks.

Biophysical Layer

hodgkinhuxley.py

• HodgkinHuxleyNeuron models a single-compartment neuron.
• Uses forward Euler integration over membrane voltage and gating variables.
• Supports either constant or callable external drive (drive(t_ms)).
• Emits boolean spike events when membrane voltage crosses threshold upward.

connection.py

• Synapse models delayed, exponentially decaying event-driven synaptic current.
• NeuralNetwork orchestrates:
  • Neuron registration
  • Directed synaptic edges
  • Step-wise simulation with per-neuron current aggregation
  • Trace capture (V_*, spike_*, and time axis)

Data Flow

1. Gather synaptic currents for each postsynaptic neuron.
2. Step each neuron once with total current.
3. Advance synaptic state using presynaptic spike outputs.
4. Record voltage and spike traces.

Digital NAND Layer

nand_architectures.py

• NandFabric provides NAND primitive and NAND-derived gates (NOT, AND, OR, XOR, XNOR, NOR).
• Tracks operation cost using gate_count.
• NandBinaryAdder composes full adders into ripple-carry n-bit addition.
• NandComparator composes bitwise logic into n-bit gt/eq/lt.
• NandALU combines adder and comparator in one interface.

Composition Strategy

• All composite operations are expressed solely through NandFabric methods.
• Integer APIs convert to bit-vectors (LSB-first), operate, then map back to integers.

Execution Layer

main.py

• Provides demo entrypoint and CLI.
• Supports selective execution:
  • HH simulation/plot
  • NAND truth tables and scaling plot
• Optional figure saving for reproducible outputs.