---
name: gpu_reduce
kind: function
lang: cpp
domain: gfx
version: "1.0.0"
purity: impure
signature: "GpuReduce gpu_reduce_create(int max_n_samples); float gpu_reduce_run(GpuReduce&, ReduceOp op, const Ssbo& samples, int count); float gpu_reduce_mean(GpuReduce&, const Ssbo& samples, int count); void gpu_reduce_destroy(GpuReduce&)"
description: "Reduccion paralela sobre SSBO float[]: sum, min, max, mean. Workgroup-shared tree reduction (local 256). Cada workgroup escribe un partial; reduccion final CPU-side sobre N/256 partials."
tags: [opengl, compute, reduce, parallel, gpu, gfx, pendiente-usar]
uses_functions: ["gl_loader_cpp_gfx", "gpu_ssbo_cpp_gfx", "gpu_compute_program_cpp_gfx", "gpu_dispatch_cpp_gfx"]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [GL/gl.h, GL/glext.h, vector, algorithm, limits]
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/gfx/gpu_reduce.cpp"
framework: opengl
params:
  - name: max_n_samples
    desc: "Cota maxima del N que se reducira. Dimensiona el SSBO de partials a ceil(N/256) floats."
  - name: op
    desc: "ReduceOp::Sum, Min o Max."
  - name: samples
    desc: "Ssbo float[count] (binding 0)."
  - name: count
    desc: "Numero efectivo de elementos a reducir (<= max_n_samples)."
output: "Escalar reducido. Bloquea (incluye readback de los ~N/256 partials a CPU). Para N=10^6, partials = 4096 floats = 16 KB readback (microscopico)."
---

# gpu_reduce

Reduccion paralela GPU + finalizacion CPU. Util para metrics resumen sobre un SSBO de samples sin tener que leer todo el buffer a CPU.

## Patron

```cpp
auto r = fn::gfx::gpu_reduce_create(/*max_n=*/10'000'000);

// Tras un dispatch que llena samples_ssbo:
float total = fn::gfx::gpu_reduce_run(r, fn::gfx::ReduceOp::Sum,  samples, N);
float lo    = fn::gfx::gpu_reduce_run(r, fn::gfx::ReduceOp::Min,  samples, N);
float hi    = fn::gfx::gpu_reduce_run(r, fn::gfx::ReduceOp::Max,  samples, N);
float mean  = fn::gfx::gpu_reduce_mean(r, samples, N);

fn::gfx::gpu_reduce_destroy(r);
```

## Performance

Workgroup-shared tree reduction: cada workgroup procesa 256 elementos en `log2(256) = 8` pasos sobre shared memory (sin atomics). Para N = 10^7 son 39062 workgroups y readback de 39062 floats (152 KB) — total ~2 ms en RTX 3070.

## Notas

- El readback es sincrono. Si llamas multiples reduce sobre el mismo SSBO en sucesion (sum, min, max), cada uno cuesta el round-trip. Para metrics multiple-output considerar un kernel custom que las calcule en una sola pasada.
- No incluye variance / std — depende de mean, asi que requiere dos passes. Implementarlo como funcion custom encima de este reduce.
- `count <= 0` o partials vacios devuelven identidad (Sum=0, Min=+inf, Max=-inf).
- Para reducciones de uint (counts de histograma) este modulo no aplica — usar gpu_histogram_1d/2d que ya emiten counts directamente.