# SpikeTransOps

**Repository Path**: Locat1on/SpikeTransOps

## Basic Information

- **Project Name**: SpikeTransOps
- **Description**: A GPU-accelerated data conversion operator library, efficiently implementing tensor-stream to spike-stream data conversion.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: TransOps
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 44
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpikeTransOps

`SpikeTransOps` is a CUDA research prototype for studying a lightweight inference pipeline that combines:

1. dynamic spike generation from dense activations,
2. bitwise spike encoding for compact temporal representation,
3. group-wise INT8 weight quantization for the GEMM path.

The repository is intentionally small and kernel-focused. Its main purpose today is to make the implementation and benchmarking of these kernels easy to inspect, build, run, and profile.

## Highlights

- Optimized dynamic-spikes kernel for a fixed input width of `3584`
- GPU-assisted preprocessing for spike encoding:
  - min/max detection,
  - optional offset or half-up transform,
  - transformed absolute-max reduction
- Bitwise spike encoding with configurable directional mode
- Group-wise symmetric INT8 weight quantization with GPU scale computation
- Batch-size sweep scripts that write CSV benchmark summaries
- Nsight Compute helper scripts for kernel profiling

## Repository Status

This project should currently be treated as a research prototype rather than a production-ready library.

- The default executable uses synthetic input, weight, and bias tensors generated in `src/main.cu`.
- The active execution path is benchmark-oriented and focuses on timing kernel stages plus end-to-end runtime.
- The reconstruction and GEMM kernels are present in the codebase, but they are disabled in the default main flow.
- The optimized dynamic-spikes path assumes `in_f == 3584`.
- The default `Makefile` targets `sm_89`.

Those constraints are intentional to keep the repository compact and reproducible for kernel experiments.

## Requirements

- Linux
- NVIDIA GPU
- CUDA toolkit with `nvcc`
- A GPU architecture compatible with the `Makefile` setting
  - default: `sm_89`

The Nsight Compute helper scripts currently assume:

```bash
/usr/local/cuda-12.8/bin/ncu
```

## Build

```bash
make
```

Or use:

```bash
./run.sh
```

## Run

The executable accepts:

```text
./spike_quant_gemm <num_runs> <batch_size>
```

Example:

```bash
./spike_quant_gemm 10 1024
```

The program prints timing for:

- `dynamic_spikes_kernel`
- `Spike Bitwise Encoding - Kernel Only`
- `Spike Bitwise Encoding - Total`
- `Weight Quantization`
- overall average and total runtime across repeated runs

## Benchmark Scripts

The `benchmark/` directory contains batch-size sweep helpers:

- `run_perf.sh`: end-to-end timing summary
- `run_perf_dynamic_spikes.sh`: dynamic-spikes timing summary
- `run_perf_spike_encoding.sh`: spike-encoding timing summary
- `run_perf_spike_encoding_total.sh`: spike encoding versus total runtime
- `run_perf_weight_quant.sh`: weight quantization versus total runtime

Typical usage:

```bash
cd benchmark
bash run_perf.sh
```

CSV results are written under `statistics/`.

## Configuration Knobs

The main compile-time knobs are in `src/config.h`:

- `is_bidirectional`
- `is_two_complement`
- `w_group_size`

The current default configuration is:

- unidirectional spike encoding
- non-two's-complement mode
- weight quantization group size `128`

## Reproducibility Notes

The benchmark uses synthetic tensors initialized directly in `src/main.cu`:

- `x[i] = i + 1`
- `w[i] = 0.1 * (i + 1)`
- `b[i] = 0.5`

That keeps the repository self-contained, but it also means the current measurements are for a fixed synthetic workload rather than a model-integrated real input pipeline.

## Contributing

If you want to contribute improvements, please see [CONTRIBUTING.md](CONTRIBUTING.md).