GRADE-GS

GRADE-GS is the reference implementation of Gaussian-Wise Rendering with Adaptive Dependency-Ordered Execution. This repository contains two reproducible components:

• a dynamic 4D Gaussian rendering path that rejects records before geometry generation and requests appearance only for current-camera candidates; and
• an exact factorized search for workload-aware stage configurations.

The repository is intentionally self-contained at the algorithm level. It does not vendor datasets, checkpoints, CUDA rasterizers, or custom hardware tools.

Quick Start

Python 3.9 or newer is required.

git clone https://github.com/HAPPYPMN/GRADE-GS.git
cd GRADE-GS
python -m venv .venv

Activate the environment and install the package:

# Linux or macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -e ".[test]"
python -m pytest

Run the included configuration-search example:

grade-gs-search examples/search_problem.json

The command prints the globally optimal configuration for the selected objective. Input fields and objective definitions are documented in docs/CONFIGURATION_SEARCH.md.

Dynamic GPU Benchmark

The GPU adapter targets the public Fudan 4D Gaussian Splatting implementation. Use the dependencies, datasets, and trained checkpoints required by that project. A known-compatible upstream revision is d61f57df.

git clone https://github.com/fudan-zvg/4d-gaussian-splatting.git external/4d-gaussian-splatting
cd external/4d-gaussian-splatting
git checkout d61f57df
conda env create -f environment.yml
conda activate gaussian_splatting
cd ../..
python -m pip install -e .

On an offline cluster where the environment already contains the required packages, disable dependency downloads and build isolation:

python -m pip install -e . --no-deps --no-build-isolation

Run a short benchmark after preparing an upstream dataset and checkpoint:

python benchmarks/run_four_dgs.py \
  --four-dgs-root external/4d-gaussian-splatting \
  --source-path /path/to/dataset/scene \
  --model-path /path/to/trained/scene \
  --scene scene_name \
  --camera-prefixes cam01 \
  --frames 0-3 \
  --output results/scene_name.csv

python benchmarks/summarize.py results/scene_name.csv

The runner alternates the eager and GRADE execution order, uses CUDA events, and reports median latency, speedup, PSNR, maximum pixel error, and operation counts. It restores checkpoints after camera construction, so the upstream checkout does not need a source patch.

If an upstream JIT extension was built with a different CUDA toolkit, use an environment-specific TORCH_EXTENSIONS_DIR and set CUDA_HOME, PATH, and LD_LIBRARY_PATH consistently before running the benchmark. This avoids loading an incompatible extension from a shared cache.

Python API

from grade_gs.integrations import render_grade

result = render_grade(
    camera,
    gaussian_model,
    pipeline,
    background,
    threshold=1.0 / 255.0,
)

image = result.image
print(result.stats.as_dict())

The adapter requires a four-dimensional Gaussian model with 4D rotation enabled. Records with unsupported or uncertain metadata can be supplied through exact_mask; these records bypass temporal rejection and follow the exact current-camera path.

Repository Layout

grade_gs/runtime/       Framework-independent routing logic
grade_gs/integrations/  Dynamic 4DGS GPU adapter
grade_gs/search/        Exact factorized configuration search
benchmarks/             GPU benchmark and CSV summarizer
examples/               Search input example
tests/                  CPU unit and exactness tests
docs/                   Algorithm and evidence notes
tools/                  Release checks

Reproducibility Scope

This release supports algorithm inspection, GPU execution, image-equivalence checks, observable route counts, and exact search validation. It does not claim to reproduce custom-hardware area, power, cycle, or memory-system results. See docs/EVIDENCE_SCOPE.md before comparing numbers across implementations.

Citation

The accompanying paper is under review. Citation metadata will be added after publication.

License

The original code in this repository is released under the MIT License. The external renderer, datasets, and checkpoints remain subject to their own licenses. See THIRD_PARTY_NOTICES.md.