fabrilis/docs/DETERMINISM.md
loki5512344 190ef9cc4b Add design persistence, world rendering, metrics overlay and logs
M3: STL/OBJ import with mesh validation, mass/COM/inertia, material database, RON scene with content-addressed blobs and v0->v1 migration. M4: deterministic heightmap terrain, trimesh colliders, wgpu renderer with instancing and depth, winit app with 1 kHz physics, fly camera, on-screen metrics overlay and per-frame CSV/dev logs. Docs: UI, logging, network and headless CLI plans.
2026-11-16 23:40:39 +01:00

61 lines
5.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Детерминизм
Результат симуляции не зависит от железа, числа потоков и ОС. Без этого нет
воспроизводимых багов, перемотки и golden-тестов.
## Уровни гарантии
| Уровень | Что гарантирует | Где проверяется |
|---|---|---|
| **D1** | Повтор на той же машине, той же сборке, том же числе потоков даёт тот же результат | каждый коммит, golden-хеш |
| **D2** | То же при любом числе потоков | автоматический прогон с 1, 2, 8 и 24 потоками |
| **D3** | Разные ОС и архитектуры (Linux x86-64, Windows, macOS ARM) дают одинаковый хеш | прогон на трёх ОС, один хеш в репозитории |
D1 нужен для отладки, D2 — для параллельных развёрток, D3 — для «у меня не
воспроизводится». Гарантия относится только к авторитетному состоянию симуляции;
рендер, UI и отладочные счётчики в хеш не входят.
## Правила
1. **Время** — `u64` наносекунды, не float.
2. **Математика**: `+ − × ÷` и `sqrt` по IEEE 754 одинаковы везде. `sin`, `cos`,
`exp`, `pow` и т.п. из `std` вызывают системный libm, у которого результаты
различаются в последних битах. Поэтому в crate'ах симуляции они запрещены
(`clippy.toml`, `disallowed_methods`); вместо них `fabrilis_core::math` поверх
чистого Rust-`libm`.
3. **Нет fast-math**; `mul_add` использовать осознанно (результат одинаков, но на
части CPU медленнее).
4. **Потоки**: порядок обхода и редукции фиксированы, результат не зависит от
числа потоков. Разбиение на блоки зависит от данных, а не от числа ядер.
5. **Коллекции**: `HashMap/HashSet` запрещены (порядок обхода), берём `BTreeMap`
или индексированные структуры.
6. **RNG** только seeded, состояние входит в снимок.
7. **GPU** не участвует в авторитетной симуляции, только в рендере и визуальных
расчётах.
8. **Часы**: `Instant::now` и `SystemTime::now` запрещены в симуляции (`clippy.toml`);
время только `SimTime`. Исключения точечные: `platform` (бенчмарки) и `app`
(темп кадров).
9. **Векторы**: свои `Vec3`, `Mat3`, `Quat` в `core::vec` на `f64` через `core::math`
(`glam` и `nalgebra` считают тригонометрию через системный libm).
10. **Инструменты**: версия компилятора зафиксирована `rust-toolchain.toml`;
авторитетная сборка идёт с базовым `target-cpu` (без `native`), прогон дополнительно
собирает с `native` и сверяет хеши.
11. **SIMD**: только явные ядра с фиксированным порядком операций. Обычная
автовекторизация допустима: она не меняет порядок сложений и не включает
fast-math. Ручные SIMD-ядра проверяются отдельным golden-тестом.
12. **Rhai** выполняет сценарии через `core::math`: `sin`, `cos`, `exp` и `pow`
движка отключены, иначе скрипт приносит системный libm в симуляцию.
## Rapier
Берём `rapier3d-f64` (вариант на `f64`) с фичей `enhanced-determinism`: границы
`f32` на стыке с нашей математикой нет. Пока Rapier в авторитетном пути, гарантия —
D1 и D2 для конкретной сборки; хеши физических сцен хранятся по платформе. D3 для
физики проверяем отдельно и обещаем только после своего backend'а
(`PhysicsBackend`), остальные подсистемы уже дают D3.
## Проверка
Golden-тест: хеш состояния после N тактов совпадает на Linux/Windows/macOS и при
1, 2, 8 и 24 потоках. Хеш хранится в репозитории. При расхождении прогон печатает
первую подсистему, чей подснимок разошёлся (COUPLING.md).
## Адаптация под железо (`platform`)
Разрешено: раскладка потоков (критический путь на P-ядрах, фон на E-ядрах),
качество рендера, место culling. Запрещено: менять модели или шаг от устройства.