merge online to main

1 files changed, 84 insertions, 40 deletions

diff --git a/README.md b/README.md
index 77b3246..b5787fd 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,94 @@
-# benchmark_suite_IREU
-A benchmark suite for memristive and memcapacitive crossbar computing systems
+# MemDevice Benchmark
+
+A benchmark suite for memristive and memcapacitive crossbar computing systems.
 
 ## Research question
-How does a chosen device subcircuit affect the same computing system? 
 
-The memristive computing field lacks standardized benchmarks that control for 
-workload characteristics, expose device-type differences, and report results 
-comparable to conventional CMOS hardware. This project designs, implements, and 
-releases a benchmark suite targeting memristive and memcapacitive crossbar 
-architectures on CMOS substrates.
+How does a chosen device subcircuit affect the same computing system?
+
+The memristive-computing field lacks standardized benchmarks that control for
+workload characteristics, expose device-level differences, and produce results
+that can be compared across implementations. MemDevice Benchmark evaluates
+different SPICE device models while keeping the reservoir, crossbar topology,
+training procedure, and workload fixed.
+
+## Architecture
+
+The SPICE crossbar replaces the software readout layer of a SPIRES reservoir
+computer. Ridge regression first trains the readout weights in software. Those
+signed weights are mapped to differential positive and negative conductances,
+which become the initial resistances of the crossbar devices. Reservoir states
+are scaled into crossbar row voltages, and the simulated column voltages are
+decoded back into software-scale predictions.
+
+The benchmark supports two execution modes:
+
+- **Online mode (default):** SPIRES produces one reservoir state at a time and
+  passes it directly to a persistent shared-ngspice simulation. Ngspice runs on
+  a background worker thread, allowing crossbar timestep `t` to overlap with
+  reservoir timestep `t+1`. The pipeline has one timestep of output latency and
+  uses bounded backpressure instead of dropping or reordering states.
+- **Offline mode:** SPIRES runs the complete input series first and stores every
+  reservoir state. The stored states are written as PWL voltage sources in a
+  batch SPICE netlist. Ngspice is launched as a separate process, and its output
+  data file is parsed after the simulation completes.
+
+Online mode uses a main SPIRES thread and a background ngspice thread. The
+operating system may schedule them on separate CPU cores, but the benchmark does
+not enforce CPU affinity. OpenMP or BLAS dependencies may also create additional
+threads.
+
+## Dependencies
+
+- A C11 compiler with OpenMP support
+- [SPIRES](https://github.com/txmastin/spires)
+- ngspice, including the shared library and development headers
+- PLplot
+- OpenBLAS and LAPACKE
+- POSIX threads
+
+Build SPIRES in the repository's `spires` directory before building this
+benchmark. Install the remaining development packages using the package manager
+for your operating system.
+
+## Build and run
+
+From the project root:
+
+```bash
+make
+```
+
+Run the default online benchmark:
+
+```bash
+make run
+```
 
-## abstract
-MemDevice Benchmark is a benchmarking framework for simulated memristor crossbar's 
-using reservoir computing tasks as standardized workloads with the goal of revealing 
-unique device model effects. The framework evaluates memristor devices under the 
-same circuit, network, and workload characteristics. In the proposed architecture 
-the SPICE crossbar is implemented as the readout layer for a reservoir computer.
-Ridge regressiong training is done on a software reservoir, training the software 
-weights. An input series is given to the reservoir, the resulting temporal states 
-are  converted into voltage signals applied to the crossbar rows. The trained readout 
-weights are converted into equivalent resistances to serve as the initial device 
-values. The crossbar columns are read and mapped back to human readable data that 
-prove task prediciton capability.
+Select a mode explicitly:
 
-Because the reservoir, crossbar, training procedure and benchmark tasks remain fixed, 
-different SPICE device models can be hot swapped and benchmarked in one continous 
-process, making fair comparisons possible and observing how device model choice 
-affects the same computing system
+```bash
+make run MODE=online
+make run MODE=offline
+```
 
-## Setup
-**Download Spires:**   
-git clone https://github.com/txmastin/spires.git   
-cd spires   
-make   
+The benchmark prints the mean squared error for each device model and writes
+generated netlists, simulation data, and SVG plots under `output/`.
 
-**Download plplot:**   
-git clone git://git.code.sf.net/p/plplot/plplot plplot.git   
-cd plplot.git   
-mkdir build   
-cd build   
-make   
-sudo make install   
+## Embedded deployment
 
-**Other dependencies may be required for the listed libraries**
+The shared-ngspice backend targets a general-purpose computer. Typical
+microcontrollers do not have the memory, numerical libraries, filesystem, or
+operating-system services required to run ngspice.
 
-**from the projects root directory (~/MemDevice_Benchmark/)**    
-make run   
+For an embedded deployment, a small SPIRES reservoir (for example, up to 16
+neurons) can run on a microcontroller and transmit each state vector to a host
+computer. The host runs the persistent ngspice crossbar and returns the decoded
+prediction. A fixed-size binary protocol should include a timestep number, the
+state values, and integrity checking so missing or reordered messages can be
+detected.
 
-## 
+The producer/consumer pipeline remains useful in that configuration, but the
+concurrency spans the microcontroller and host. The two-thread local
+implementation is primarily useful when both the software reservoir and ngspice
+readout run on the same general-purpose computer.