# 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-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
```

Select a mode explicitly:

```bash
make run MODE=online
make run MODE=offline
```

The benchmark prints the mean squared error for each device model and writes
generated netlists, simulation data, and SVG plots under `output/`.

## Embedded deployment

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.

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.