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

5.3 KiB
Raw Blame History

Детерминизм

Результат симуляции не зависит от железа, числа потоков и ОС. Без этого нет воспроизводимых багов, перемотки и 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. Запрещено: менять модели или шаг от устройства.