Metadata-Version: 2.4
Name: promise-gpu
Version: 0.1.0
Summary: GPU precision exploration with Delta Debugging and DSA-inspired validation
Author: PROMISE-GPU contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/chenxinye/promise-gpu
Project-URL: Repository, https://github.com/chenxinye/promise-gpu
Project-URL: Issues, https://github.com/chenxinye/promise-gpu/issues
Project-URL: Documentation, https://promise-gpu.readthedocs.io
Keywords: gpu,cuda,mixed-precision,delta-debugging,numerical-validation,stochastic-arithmetic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: yaml
Requires-Dist: PyYAML>=6.0; extra == "yaml"
Provides-Extra: docs
Requires-Dist: PyYAML>=6.0; extra == "docs"
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == "plot"
Provides-Extra: test
Dynamic: license-file

# 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.

```yaml
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

```bash
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:

```bash
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`:

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

Then configure:

```yaml
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/`:

```bash
./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

```bash
promise-gpu tune examples/dot_product/experiment.yaml
```

The unstable baseline demonstration is:

```bash
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:

```bash
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

```cpp
#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:

```bash
-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):

   ```bash
   python3 -m pip install -e .
   ```

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

   ```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:

   ```bash
   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.

   ```text
   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

```bash
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

```bash
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:

```yaml
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.
