PROMISE-GPU

PROMISE-GPU is an open-source research prototype for GPU mixed-precision exploration through user-defined precision groups, Delta Debugging, and DSA-inspired stochastic numerical validation.

It is inspired by the ideas of PROMISE and stochastic arithmetic / CADNA-style validation, but it is an independent implementation and does not claim CADNA compatibility.

Why FP64 Is Not Ground Truth

Double precision is a precision level, not a correctness certificate. PROMISE-GPU can validate the all-FP64 baseline with a DSA-inspired oracle before allowing that output to become a deterministic reference. If the FP64 baseline fails the configured stochastic criterion, the experiment is marked UNSTABLE_BASELINE, the FP64 output is not trusted as a reference, and Delta Debugging stops by default.

Kernel vs Precision Group

The CUDA kernel is the compilation, execution, and benchmark boundary. Precision groups are the search dimensions exposed by the programmer, such as input, product, accumulator, and output.

Those group names are examples only. Users can mark any number of variables or code regions as tunable precision groups; role is metadata for reporting and future policies, not a required schema.

Modular CUDA Sources

For modular CUDA code, source.files follows the same practical shape used by tools like Kernel Tuner: the first file is the main translation unit and the remaining files are helper headers or auxiliary sources included by it.

source:
  files: [kernel.cu, precision_policy.cuh, pipeline_ops.cuh]
  kernel: modular_pipeline_kernel

PROMISE-GPU hashes every listed file, so changing a helper invalidates cached candidate results. The bundled examples/modular_pipeline shows this layout. Separate .cu files that require independent compilation and linking still need a project-specific build/runner.

Delta Debugging

PROMISE-GPU uses multi-level Delta Debugging only. It starts from the highest permitted precision configuration, tries subset demotions such as FP64 -> FP32, then refines complements and partitions until it reaches a DD-minimal feasible assignment. This is a local minimality guarantee under the tested subsets, not a claim of global optimality.

DSA

PROMISE-GPU's preferred stochastic path uses the bundled gpu-cadna dependency for FP32/FP64 CADNA GPU types and effective-digit checks. The independent promise_gpu::stochastic<T> type remains as a fallback research sandbox, not as a claimed CADNA-compatible replacement.

Performance

Native and stochastic builds are separated on purpose. Native kernels are the only source of reported runtime and speedup numbers; stochastic kernels exist for numerical validation and may be much slower.

Limitations

• CUDA launch/execution remains a project-specific integration point beyond the MockBackend.
• FP16 stochastic semantics are an extension point rather than a fully validated claim.
• Delta Debugging reports the fastest valid configuration it encountered, but it does not run a second performance-only search.

Install

python3 -m pip install -e .

No NVIDIA GPU is required for the Python tests or MockBackend demos. The bundled examples run without PyYAML; install .[yaml] if you want the full PyYAML parser.

Full documentation is configured for ReadTheDocs via .readthedocs.yaml. To build it locally:

python3 -m pip install -e ".[docs]"
sphinx-build -b html docs docs/_build/html

For real CUDA stochastic validation, build the bundled gpu-cadna dependency and provide an application-specific cadna_runner:

cd gpu-cadna
cp C/rnd_x86_00_64.s C/cadna_rounding_64.s
make cpu
make gpu
cd ..

Then configure:

backend:
  name: cuda
  stochastic_impl: cadna_gpu
  cadna_gpu_dir: gpu-cadna
  cadna_runner: ./build/run_cadna_case

The full CADNA-GPU setup, linker flags, runner JSON protocol, and reference-result modes are documented in docs/installation.rst and docs/configuration.rst.

Experiment Pipeline

Paper-oriented automation lives in experiments/:

./experiments/prepare_data.sh
python3 experiments/run_benchmarks.py
python3 experiments/plot_results.py

The runner writes experiments/results/summary.json and experiments/results/summary.csv; the plotting script produces publication-style PDF/PNG figures with shared font sizes, axis labels, legend styling, and tick styling.

First Demo

promise-gpu tune examples/dot_product/experiment.yaml

The unstable baseline demonstration is:

promise-gpu tune examples/unstable_cancellation/experiment.yaml

That command intentionally exits with status 2 after reporting UNSTABLE_BASELINE.

A sharper FP64-is-not-ground-truth demonstration is:

promise-gpu tune examples/fp64_not_ground_truth/experiment.yaml

It models (1e16 + 1.0) - 1e16: the mathematical result is 1.0, but double precision computes 0.0, so CADNA/DSA-style validation marks the baseline as unusable and stops DD.

Precision Annotation Syntax

#include <promise_gpu/promise_gpu.cuh>

PROMISE_GPU_PRECISION_GROUP(input_t, input, FP64, FP16, FP32, FP64);
PROMISE_GPU_PRECISION_GROUP(accum_t, accumulator, FP64, FP32, FP64);

Each candidate is meant to be compiled with definitions such as:

-DPROMISE_GPU_INPUT_PRECISION=PROMISE_GPU_FP16
-DPROMISE_GPU_input_PRECISION=PROMISE_GPU_FP16
-DPROMISE_GPU_ACCUMULATOR_PRECISION=PROMISE_GPU_FP64
-DPROMISE_GPU_accumulator_PRECISION=PROMISE_GPU_FP64

No runtime if precision == ... branching is used for native performance measurement.

End-to-End Example: Install, Configure, Tune

This walks through a full precision-tuning cycle -- install, write an experiment config, and run tune -- using the bundled examples/precision_tuning_demo example. The full, runnable config and kernel live in that folder (examples/precision_tuning_demo/experiment.yaml and examples/precision_tuning_demo/kernel.cu) so you can copy them as a starting point for your own project.

1. Install PROMISE-GPU (no GPU required, MockBackend is CPU-only):

   python3 -m pip install -e .
   

2. Point at (or write) an experiment config, examples/precision_tuning_demo/experiment.yaml:

   project: precision_tuning_demo
   
   source:
     file: kernel.cu
     kernel: vector_add_kernel
   
   precision_groups:
     input:
       choices: [fp16, fp32, fp64]
       default: fp64
       role: input
     output:
       choices: [fp16, fp32, fp64]
       default: fp64
       role: output
   
   baseline:
     validate_with_dsa: true
     dsa:
       minimum_significant_digits: 10
       seed: 12345
     on_unstable:
       action: stop
   
   accuracy:
     dsa:
       enabled: true
       minimum_significant_digits: 8
     reference:
       enabled: true
       mode: cadna_stochastic
       metrics:
         significant_digits:
           min: 8
         relative_l2_max: 1.0e-6
     require: all
   
   delta_debugging:
     levels:
       - from: fp64
         to: fp32
       - from: fp32
         to: fp16
   
   backend:
     name: mock
     mock:
       baseline_significant_digits: 13
       baseline_runtime_us: 24
       group_digit_penalty:
         input:
           fp32: 1.0
           fp16: 3.0
         output:
           fp32: 1.0
           fp16: 3.5
   

3. Run the tuner against that config:

   promise-gpu tune examples/precision_tuning_demo/experiment.yaml
   

4. Read the report: PROMISE-GPU validates the FP64 baseline, then Delta Debugging demotes precision groups until it finds the DD-minimal configuration that still passes the accuracy checks.

   PROMISE-GPU report
   
   Baseline
     FP64 baseline DSA status: PASS
     Estimated significant digits: 13.00
     Runtime median: 24.000 us
   
   DD-minimal configuration
     input          FP16
     output         FP32
   
   Accuracy
     Status:           PASS
     Significant digits: 9.00
     Reference mode:   cadna_stochastic
     Relative L2:      4.595e-10
   
   Performance
     FP64 baseline:    24.000 us
     DD result:        15.600 us
     Speedup:          1.54x
   

   Here input was demoted all the way to FP16 while output stayed at FP32 -- the tightest mixed-precision configuration that still meets the minimum_significant_digits and relative_l2_max thresholds declared under accuracy. Tighten or loosen those thresholds in the config to explore different accuracy/performance trade-offs.

Commands

promise-gpu --help
promise-gpu validate examples/dot_product/experiment.yaml
promise-gpu tune examples/dot_product/experiment.yaml --resume
promise-gpu inspect examples/dot_product/results.db
promise-gpu report examples/dot_product/results.db

Tests

PYTHONPATH=python python3 -m unittest discover -s tests

CUDA hardware tests are not required for the MockBackend suite. The CudaBackend boundary exists for native/stochastic specialization and future project-specific launchers.

Is This CADNA/PROMISE?

PROMISE-GPU is deliberately similar in design direction: PROMISE-like Delta Debugging over user-marked precision groups, plus CADNA-inspired stochastic validation. It is not the official GPU version of PROMISE, does not copy CADNA/PROMISE code, and does not claim CADNA compatibility.

Reference Results

Candidate native output can be compared with a configured reference provider:

accuracy:
  reference:
    enabled: true
    mode: cadna_stochastic      # or double_precision / single_precision
    metrics:
      relative_l2_max: 1.0e-6

cadna_stochastic is the PROMISE-like default when DSA is enabled: the validated highest-precision CADNA/DSA run supplies the representative result used by later Delta Debugging comparisons. double_precision uses the validated highest-precision native baseline. single_precision computes an FP32 reference configuration where allowed. This is intentionally separate from the DSA oracle, because stochastic arithmetic can be a stability validator, a reference provider, or both.