NeRArchSim

NeRArchSim is a small, self-contained simulator for neural rendering accelerators. Given an execution DAG (.pkl), it maps operators to a configurable hardware model, schedules them, and writes PPA report.

Recent changes: See CHANGES.md for new accelerator support (Lumina), new workload support (4DGS), memory modeling improvements, and bug fixes added in the ISCA 2026 revision.

Interactive GUI: Prefer a UI over the command line? Launch NeRArch-Sim Studio with ./nerarch_sim gui --build (then ./nerarch_sim gui) to visually build hardware, run the simulator with live progress, and explore results. See WebApp/README.md. The CLI below remains fully supported.

Overview

Instrumentation: collect traces with Nerfstudio and transform to realistic operators (see Instrumentation and Operators)
Mapping: map operators to hardware units (see Scheduler)
Scheduling and PPA: system-level scheduling with optional PPA estimation (see Scheduler and Hardware)
Reporting: interactive analysis report and visuals (see Visualization)

Folder structure

CLI/: command-line entry points
Scheduler/: mapping and scheduling (C++ and Python)
Instrumentation/: helpers to inspect/transform DAGs
Operators/: operator taxonomy, plotting, and integration (see Operators/README.md)
Hardware/: accelerator configs, scripts, and examples (see Hardware/README.md)
Visualization/: schedule Gantt, operator graph, and PPA dashboard (see Visualization/README.md)
tests/: end-to-end, mapping, scheduler, latency, and PPA tests

Requirements

Python 3.8+
C++17 compiler and CMake 3.16+
Nerfstudio environment to collect real traces

Install and build

# Use local environment (recommended) or global environment
conda create --prefix $PWD/nerarchsim python=3.8 -y
conda activate $PWD/nerarchsim
pip install --upgrade pip setuptools
pip install matplotlib
pip install torch==2.1.2+cu118 torchvision==0.16.2+cu118 --extra-index-url https://download.pytorch.org/whl/cu118
conda install -c nvidia/label/cuda-11.8.0 cuda-toolkit -y
pip install ninja git+https://github.com/NVlabs/tiny-cuda-nn/#subdirectory=bindings/torch
conda install -c conda-forge graphviz python-graphviz nlohmann_json -y
pip install -e .
# Initialize submodules (Ramulator 2.0)
git submodule update --init --recursive

# Get Ramulator
cd Hardware/
git clone https://github.com/CMU-SAFARI/ramulator2.git ramulator2
cd ..

./build_cpp.sh
chmod +x ./nerarch_sim

For detailed environment setup, training, and multi-model eval (vanilla-nerf, instant-ngp, splatfacto), see Instrumentation/README.md.

Quick setup (Nerfstudio + tracing)

git clone https://github.com/nerfstudio-project/nerfstudio.git
cd nerfstudio && git checkout 50e0e3c70c775e89333256213363badbf074f29d && pip install -e . && cd ..

# Copy vendor reference files (tracing, eval, trace_config) into your checkout
mkdir nerfstudio/nerfstudio/instrumentation/
cp -f Instrumentation/nerfstudio_vendor/instrumentation/tracing.py nerfstudio/nerfstudio/instrumentation/ || true
cp -f Instrumentation/nerfstudio_vendor/instrumentation/trace_config.json nerfstudio/nerfstudio/instrumentation/ || true
cp -f Instrumentation/nerfstudio_vendor/scripts/eval.py nerfstudio/nerfstudio/scripts/ || true
cp -f Instrumentation/nerfstudio_vendor/scripts/train.py nerfstudio/nerfstudio/scripts/train_instrumented.py || true
cp -f Instrumentation/nerfstudio_vendor/utils/eval_utils.py nerfstudio/nerfstudio/utils/ || true
cp -f Instrumentation/nerfstudio_vendor/utils/train_utils.py nerfstudio/nerfstudio/utils/ || true
cd nerfstudio && pip install -e . && cd ..

Collect a trace with Nerfstudio (ns-eval)

Quick example with vanilla-nerf:

# If you have already trained vanilla-nerf, locate its config
CONFIG=$(find output_result -path "*vanilla-nerf*/*/config.yml" | head -n1)
echo "$CONFIG"  # should be something like output_result/.../vanilla-nerf/.../config.yml

# Evaluate one image with tracing enabled (writes execution_dag.pkl)
OUT=traces/vanilla_traces
mkdir -p "$OUT"
DISABLE_TRACE_PLOT=1 \
ns-eval \
  --load-config "$CONFIG" \
  --render-output-path "$OUT" \
  --enable-trace \
  --trace-config-path nerfstudio/nerfstudio/instrumentation/trace_config.json \
  --eval-image-indices 0
# Trace: $OUT/execution_dag.pkl

python Instrumentation/plot_transformed_operators.py "$OUT/execution_dag.pkl"

If you have not trained yet, follow the training section in Instrumentation/README.md first.

See Instrumentation/README.md for ns-eval flags and environment variables (including DISABLE_TRACE_PLOT).

End-to-end with ICARUS PPA

Default analyze runs the full /Operators transform and invokes PPA (Ramulator). To skip PPA, add --no-ppa.
Ensure you pass your hardware JSON explicitly so scheduling and PPA use the intended config.
Optimization behavior is explicit and config-driven:
- optimizations are enabled when --optimization-config <json> is provided
- if --optimization-config is omitted, optimizations are disabled
- if enabled optimization techniques are incompatible with the selected hardware, the run fails with an assertion.

# Generate trace with ns-eval (from section above) so $OUT/execution_dag.pkl exists

# Run end-to-end (map → schedule → report) with ICARUS
./nerarch_sim analyze "$OUT/execution_dag.pkl" output_icarus_ppa \
  --hardware Hardware/examples/hardware_configs/icarus_config.json \
  --report-format html

Running steps separately

If you prefer to run scheduling directly, pass the hardware config explicitly (new flag):

# Map (produces output_icarus/mapping/mapped_ir.json)
./nerarch_sim map "$OUT/execution_dag.pkl" Hardware/examples/hardware_configs/icarus_config.json \
  -o output_icarus/mapping/mapped_ir.json

# Schedule (with PPA) — note the required --hardware flag
./nerarch_sim schedule output_icarus/mapping/mapped_ir.json \
  -o output_icarus/scheduling/scheduled_ir.json \
  --hardware Hardware/examples/hardware_configs/icarus_config.json

# Report
./nerarch_sim report output_icarus/scheduling/scheduled_ir.json \
  -o output_icarus/reports/analysis_report.html --format html

Notes

The first PPA run builds Ramulator automatically under Hardware/ramulator2/.
Full /Operators transform is the default. For faster fallback parsing, use --basic-parser (reduced fidelity).
If you see placeholder PPA fields (zeros), re-run analyze without --no-ppa and ensure --hardware is provided (analyze now passes it through to scheduling).
Optimization configs live under Scheduler/optimization/configs/. Start with:
- Scheduler/optimization/configs/icarus_baseline_config.json
- Scheduler/optimization/configs/standard_neural_rendering_config.json
- Scheduler/optimization/configs/encoding_field_only_config.json
For strict SRAM modeling (memory_model_version: 2), hardware configs must define:
- memory_bindings per op type (read/write SRAM block IDs)
- per-block SRAM timing/bandwidth fields in sram_blocks (read_bw_gbps, write_bw_gbps, read_latency_cycles, write_latency_cycles)
- missing required bindings/fields will fail fast during scheduling.

Interactive topology viewer

Generate an interactive topology/utilization HTML from an existing analysis output:

./nerarch_sim topo output_icarus_ppa

Default output:

output_icarus_ppa/reports/topology_view.html

Validate the operator graph

Validate that the captured/transformed operator graph is structurally sound and functionally faithful to the nerfstudio render. Accepts a DAG .pkl or a directory containing execution_dag.pkl:

./nerarch_sim validate traces/vanilla_traces
# or with explicit thresholds:
./nerarch_sim validate traces/vanilla_traces/execution_dag.pkl \
  --psnr-threshold 35 --ablation-margin 10

What it checks:

Structural — DAG acyclicity, taxonomy-stage coverage/order (SAMPLING → ENCODING → FIELD_COMPUTATION → BLENDING), renderer source wiring, and a non-degenerate op-type histogram. Works with no capture data.
Functional replay — replays the captured per-sample field outputs into an image and compares it three ways against nerfstudio's reference montage (eval_img_*.png = cat([ground_truth, rgb_coarse, rgb_fine])):
- replay vs nerfstudio render — extraction fidelity, and the metric that gates the verdict. The headline number is the forced-recompute PSNR, which ignores captured weights and recomputes them from captured density + sample geometry (anti-cheat: it proves the sampling→field→blending chain rather than replaying final pixels).
- replay vs ground truth — our render quality (informational; capped by the trained model, e.g. ~27 dB, regardless of extraction correctness).
- nerfstudio render vs ground truth — nerfstudio's own quality (reference).
- GT parity — requires |replay-vs-GT − nerfstudio-vs-GT| ≤ margin (default 1 dB), confirming our replay does not lose quality versus nerfstudio.
Stage ablation — zeroes/perturbs each stage and requires PSNR to drop by ≥ margin, proving every stage materially contributes.

Outputs (next to the DAG, or at --output-prefix):

operator_graph_validation_report.json / .md — full results + PASS/FAIL verdict
*_ground_truth.png, *_nerfstudio_render.png, *_replay.png (the 3-way strip), and *_ablation_<stage>.png

Verdict: PASS iff structural PASS and replay-vs-render PSNR ≥ threshold (default 35 dB, fidelity) and every ablation drop ≥ margin (default 10 dB) and GT parity holds (default 1 dB; disable with --no-gt-parity, tune with --gt-parity-margin). Returns exit 0 on PASS, 1 on FAIL. A trace without render_capture/ yields a clear structural-only result (--strict makes that exit 1). Requires capture_renderer_values: true during tracing for the functional/ablation checks. NeRF (volumetric) replay only this iteration; 3DGS/splatfacto alpha-blend replay is a documented follow-up. Validation is also available in the GUI (a "Validate operator graph after run" toggle and a standalone "Validate graph" action in the Run panel), which shows the verdict, all three PSNRs, the GT-parity result, and the ground-truth / nerfstudio-render / operator-graph-replay image strip side by side.

Reconstruct + validate multiple scenes

For a reproducible end-to-end run across several scenes (train → instrumented ns-eval trace → transform → validate, with a combined summary), use the driver:

scripts/run_scene_validation.sh
# subset / overrides:
SCENES="lego kitchen" ITERS=30000 scripts/run_scene_validation.sh

It writes per-scene reports under traces/<scene>_traces/ and an aggregate traces/scene_validation_summary.md.

Outputs

Outputs in the chosen directory:

mapped_ir.json: operator mapping from the traced DAG to standardized operator types and hardware module types
scheduled_ir.json: scheduled intermediate representation (per-op dependencies, start/end times, and resource assignments)
analysis_report.html: interactive HTML report with pipeline breakdown, schedule timeline, and bottleneck analysis
summary.md: short human-readable summary of key metrics (ops, memory, utilization) and run configuration

Modular Design

The project follows modular design. See component guides: Scheduler, Instrumentation, Hardware.

Citation

If you use NeRArch-Sim in your research, please cite our ISCA 2026 paper:

Cheng-Jhih Shih, Chaojian Li, Chihao Yu, Hsuan-Chen Fang, Sixu Li, Wei-Po Hsin, Lexington Whalen, Hyewon Suh, Greg Eisenhauer, Ling Liu, and Yingyan (Celine) Lin. "NeRArch-Sim: A Unified Simulator for Benchmarking and DSE of Neural Rendering Accelerators." In Proceedings of the 53rd Annual International Symposium on Computer Architecture (ISCA), 2026.

@inproceedings{shih2026nerarchsim,
  title     = {{NeRArch-Sim}: A Unified Simulator for Benchmarking and {DSE} of Neural Rendering Accelerators},
  author    = {Shih, Cheng-Jhih and Li, Chaojian and Yu, Chihao and Fang, Hsuan-Chen and Li, Sixu and Hsin, Wei-Po and Whalen, Lexington and Suh, Hyewon and Eisenhauer, Greg and Liu, Ling and Lin, Yingyan (Celine)},
  booktitle = {Proceedings of the 53rd Annual International Symposium on Computer Architecture (ISCA)},
  year      = {2026},
  organization = {IEEE}
}

License

NeRArchSim is released under the MIT License. See LICENSE for details. Note that third-party components set up during installation (e.g. Nerfstudio and Ramulator 2.0) are distributed under their own licenses.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

NeRArchSim

Table of Contents

Overview

Folder structure

Requirements

Install and build

Quick setup (Nerfstudio + tracing)

Collect a trace with Nerfstudio (ns-eval)

End-to-end with ICARUS PPA

Running steps separately

Notes

Interactive topology viewer

Validate the operator graph

Reconstruct + validate multiple scenes

Outputs

Modular Design

Citation

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
CLI		CLI
Figures		Figures
Hardware		Hardware
Instrumentation		Instrumentation
Operators		Operators
Scheduler		Scheduler
Visualization		Visualization
WebApp		WebApp
scripts		scripts
tests		tests
.gitignore		.gitignore
CHANGES.md		CHANGES.md
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
build_cpp.sh		build_cpp.sh
modular_design.png		modular_design.png
nerarch_sim		nerarch_sim
nerarchsim.png		nerarchsim.png
pyproject.toml		pyproject.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

NeRArchSim

Table of Contents

Overview

Folder structure

Requirements

Install and build

Quick setup (Nerfstudio + tracing)

Collect a trace with Nerfstudio (ns-eval)

End-to-end with ICARUS PPA

Running steps separately

Notes

Interactive topology viewer

Validate the operator graph

Reconstruct + validate multiple scenes

Outputs

Modular Design

Citation

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages