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