# GPU SPH Dolum Planı — Position Based Fluids (PBF)

> fikatia-local döküm dolum simülasyonu. CPU SPH (SPlisHSPlasH DFSPH,
> `sph_dolum.*`) interaktif-dışı yavaş (40 mm / ~5-20 k partikül CPU'da
> 180 sn'de bitmiyor). Bu belge GPU (Vulkan compute) yolun tasarım kararlarını
> kaydeder. CPU yol DEĞİŞMEDİ — GPU ayrı dosya (`sph_gpu.*`), aynı çıktı
> sözleşmesi (`SphDolumSonuc`).

## Yöntem seçimi: PBF (Macklin & Müller 2013), DFSPH/WCSPH DEĞİL

| Kriter | PBF | DFSPH | WCSPH |
|--------|-----|-------|-------|
| Basınç çözümü | Yok (yoğunluk kısıtı λ) | Poisson (matris-serbest CG) | Durum denklemi + küçük dt |
| GPU kararlılığı | Yüksek (position-based) | Orta (iteratif solver GPU'da zor) | Düşük (dt << CFL) |
| Büyük substep | Evet | Kısmen | Hayır |
| GPU'ya taşıma | En kolay | Zor | Kolay ama kararsız |

**Seçim: PBF.** Basınç Poisson'u yok → yoğunluk kısıtı `C_i = ρ_i/ρ0 − 1` +
iteratif konum düzeltmesi (Jacobi). Position-based → hız konum değişiminden
türetilir (`v = (x − x0)/dt`), büyük substep'te patlamaz. GPU'da atomik hash +
paralel kernel'lerle doğrudan eşlenir. Kaynak: Macklin & Müller, *"Position
Based Fluids"*, ACM SIGGRAPH 2013, denklem (1),(2),(9),(11),(12),(13),(14).

## Komşuluk: h-boyutlu uniform hash grid (GPU counting sort)

Support yarıçapı `h = 4r` boyutunda kartezyen grid (kafes voxel'inden BAĞIMSIZ).
Kare başına: `sph_hash_say` (atomik hücre-sayacı) → CPU prefix-sum → `sph_hash_dagit`
(atomik counting sort → hücre-gruplu partikül dizisi). Yoğunluk/kuvvet/entegre
3×3×3 hücre tarar. (Prefix-sum küçük uint dizisi CPU'da; GPU prefix-sum sonraki
optimizasyon dalgası.)

## Sınır: voxel kafes metal-dışı hücre projeksiyonu

`kuvvet` shader'ında düzeltilmiş konum kafes metal-dışı hücreye düşerse, adım-başı
konum (`x0`, metal içi) ile arasında ikili arama (8 iter) → metal yüzeyine it.
Kafes tip lookup SSBO (0=Dış, 1=İç, 2=Sınır). SPlisHSPlasH Akinci statik sınır
partikülü YERİNE analitik kafes projeksiyonu (GPU'da ucuz, partikül üretmez).

## Komut zinciri (kare başına, N substep)

```
emit (CPU) → yaz(SSBO)
  tahmin (entegre faz=0: x0=x, v+=g·dt, x+=v·dt)
  hashSay → prefix(CPU) → hashDagit
  ×pbfIter: yogunluk(λ) → kuvvet(Δp + sınır)
  finalize (entegre faz=1: v=(x−x0)/dt + XSPH)
readback → voxel bin (CPU) → SphDolumSonuc
```

## Çıktı sözleşmesi (CPU sphDolumCoz ile BİREBİR)

`sphGpuCoz(vb, kafes, kurulum, alasim, ayar, ilerleme) → SphDolumSonuc`:
- `dolum.varisZamani` — hücre dolum anı [s] (ilk eşik aşımı, histerezis)
- `kareler[]` — u8 doluluk kare serisi (scrubber animasyonu)
- `hizOrt`/`hizMaks`/`maksHiz` — hücre-başı hız (Campbell denetimi)
- `oksit`/`oksitliPartikul` — bifilm izleme (hız > kritik)
- `partikulSayi`/`partikulKutleKg`/`cozumSuresiSn`

Sınır (kabuk) hücrelere varış komşu iç hücreden yayılır (zincir sözleşmesi
`Ic + Sinir = döküm bölgesi` korunur). **GPU ısı kuplajı + cold-shut sonraki
dalga** (`varisT = dokumSicaklik` sabiti; CPU yolun tam ısı zincirinden farkı).

## UI kontratı

`dokum_penceresi` combo (`kFizikAd = {"Hızlı cephe (sn)", "Gerçek SPH (dk)"}`) →
üçüncü seçenek **"Gerçek SPH (GPU)"** eklenmeli; seçilince `sphGpuCoz(*vb, ...)`
çağrılır. Dönüş `hazir=false` (GPU yok/aygıt kayıp/dispatch başarısız) → CPU
`sphDolumCoz`'a düş (fallback kontratı). `dokum_penceresi.cpp` bu dalgada
DEĞİŞTİRİLMEDİ (kapsam dışı) — combo bağlama sonraki UI dalgası.

## Shader derleme kontratı

5 compute shader `motor/render/shader/sph_*.comp` + ortak include
`sph_ortak.glsl`. `uygulama/fikocad/CMakeLists.txt` SPV foreach listesine
eklendi: `sph_hash_say sph_hash_dagit sph_yogunluk sph_kuvvet sph_entegre`
(ortak `.glsl` include, foreach'e EKLENMEZ). SPIR-V `shader/*.comp.spv`
çalışma dizinine göre yüklenir (kutuk SDF motoruyla aynı kalıp).

## Kalan / riskler

- **GPU ısı kuplajı + cold-shut**: partikül-başı T iletimi (Cleary-Monaghan) +
  duvar Robin GPU'ya taşınmadı (CPU yolun zenginliği). Ayrı compute shader dalgası.
- **Determinizm**: atomik hash sırası → best-effort (testler istatistiksel tolerans).
- **Prefix-sum CPU'da**: kare başına küçük readback; GPU scan optimizasyonu kaldı.
- **Zero-readback**: konum SSBO doğrudan nokta-render (partikül görselleştirme)
  sonraki dalga; şimdilik CPU binning readback.