Linus/one baseline file

README.md

@@ -77,6 +77,31 @@ make run-bench
 
 Compiles and runs benchmark measurements.
 
+All build commands accept a `VARIANT` parameter to select an optimization variant:
+
+```bash
+make run-bench VARIANT=v1_cutoff N_P=100 N_ITER=10000
+```
+
+The default is `VARIANT=baseline`. Each variant compiles its own binary (`main_baseline`, `main_v1_cutoff`, etc.).
+
+```bash
+make bench-suite
+```
+
+Compiles once and runs benchmarks across multiple pedestrian counts (default: 50, 100, 200, 500, 1000, 2000, 5000, 10000 with 1000 iterations each). Redirect output to save results:
+
+```bash
+make bench-suite > benchmarks/baseline.txt
+make bench-suite VARIANT=v1_cutoff > benchmarks/v1_cutoff.txt
+```
+
+Both `BENCH_SIZES` and `BENCH_ITER` can be overridden:
+
+```bash
+make bench-suite BENCH_SIZES="100 500 1000" BENCH_ITER=500
+```
+
 ```bash
 make test
 ```
@@ -121,6 +146,7 @@ N_ITER=4000
 CSV=positions.csv
 MP4=simulation.mp4
 RANDOM_SEED=0
+VARIANT=baseline
 ```
 
 They can be overridden from the shell. Parameters can be provided selectively and in any order.
@@ -170,7 +196,7 @@ make main
 This produces the executable:
 
 ```text
-main
+main_baseline (or main_<variant>)
 ```
 
 The Makefile uses the following compiler flags:
@@ -202,13 +228,16 @@ This compiles the code and runs the simulation with the default parameters. It p
 You can also run the executable manually after compiling:
 
 ```bash
-./main <number_of_pedestrians> <number_of_iterations> [csv_output_path]
+./main_baseline <number_of_pedestrians> <number_of_iterations> [csv_output_path]
+./main_<variant> <number_of_pedestrians> <number_of_iterations> [csv_output_path]
 ```
 
 Example:
 
 ```bash
-./main 60 4000 positions.csv
+./main_baseline 60 4000 positions.csv
+./main_<variant> 60 4000 positions.csv
+
 ```
 
 The third argument is optional. If it is provided, simulation states are written to the given CSV file.
@@ -292,9 +321,50 @@ make run-bench N_P=100 N_ITER=5000
 ```
 
 The benchmark output includes estimated work, operational intensity, measured cycles, and estimated performance in flops per cycle.
-
 ---
 
+## Optimization Variants
+
+The project supports multiple optimization variants through the `VARIANT` Makefile parameter. Each variant provides its own implementation of the force computations and simulation loop while sharing the same interface, benchmark harness, and test suite.
+
+The default variant is `baseline`:
+
+```bash
+make run-bench                          # uses baseline
+make run-bench VARIANT=baseline         # equivalent
+make run-bench VARIANT=v1_cutoff        # uses a different variant
+
+```
+### File naming convention
+Each variant consists of a single file in the project root:
+
+```bash
+variant_<name>.cpp              # force computations and simulation loop
+```
+The file must implement the interfaces defined in `forces.hpp` and `social_force.hpp`. The baseline implementation is `variant_baseline.cpp`.
+
+### Creating a new variant
+1. Copy the baseline file:
+ ```text
+cp variant_baseline.cpp variant_v1_cutoff.cpp
+```
+2. Edit the new file with your optimization.
+
+3. Build and test:
+```bash
+make test VARIANT=v1_cutoff
+make run-bench VARIANT=v1_cutoff N_P=100 N_ITER=10000
+```
+### Verifying correctness
+A reference CSV is stored in reference/baseline_n60_i4000.csv. To verify that a variant produces the same simulation output:
+```bash
+make run VARIANT=v1_cutoff N_P=60 N_ITER=4000 CSV=test_output.csv
+diff reference/baseline_n60_i4000.csv test_output.csv
+```
+If the variant changes numerical results (e.g., distance cutoff skipping negligible forces), use a tolerance-based comparison instead of exact diff and justify the deviation.
+
+
+---
 ## Tests
 
 Run all unit tests with:
@@ -311,7 +381,7 @@ The test target compiles and runs the unit tests for the simulation components.
 
 ## Assembly generation
 
-To generate assembly files:
+To generate assembly files for the currently selected VARIANT:
 
 ```bash
 make asm
@@ -362,7 +432,7 @@ make clean
 This deletes files such as:
 
 ```text
-main
+main_*
 sizes
 run_tests
 *.o
@@ -378,7 +448,7 @@ make clean-all
 This deletes:
 
 ```text
-main
+main_*
 sizes
 run_tests
 *.o