Initial commit: Fabrilis docs, rules and deterministic core

Docs (architecture, decisions, coupling, determinism, UI, references), code rules enforced by tools/limits, deterministic core with units, time, math, sched, snapshot, vec and rng, plus smoke tests. ref/ stays out of git.
This commit is contained in:
Loki 2026-11-16 19:09:10 +01:00
commit 79928b645b
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
222 changed files with 5335 additions and 0 deletions

131
docs/REFERENCES.md Normal file
View file

@ -0,0 +1,131 @@
# Что читать
Не копировать целиком и не тянуть в зависимости, а искать конкретные алгоритмы и
решения. Ссылки проверены 16.11.2026.
Ориентиры по режимам: **Renode** ближе всего к Bench, **MuJoCo** — к World,
**SOFA** — к Lab и FEM.
## Локальные клоны
Исходники этих проектов лежат в `ref/` — папка в `.gitignore` и не проверяется
правилами кода. Клоны неполные (история не нужна): читаем код, не собираем.
Создать или дополнить: `tools/fetch_refs.sh`. Обновить один проект:
`git -C ref/<имя> pull`. Удалить: `rm -rf ref/<имя>`.
| Категория | В `ref/` |
|---|---|
| Эмуляция железа | `renode`, `mini-rv32ima` |
| Физика | `mujoco`, `jolt`, `box2d` |
| FEM и прочность | `calculix`, `sofa`, `scikit-fem` |
| Электроника | `ngspice`, `circuitjs` |
| Мир и сенсоры | `gazebo` |
| Робототехника и сценарии | `cheetah`, `opencat`, `carla-scenario-runner` |
| UI и форматы | `imgui`, `egui`, `openscad` |
Библиотеки, которые мы используем (Rapier, wgpu, winit, rhai, fontdue), сюда не
клонируются: их исходники и так лежат в `~/.cargo/registry`.
## Первая очередь
- **Renode** — виртуальное железо, периферия, временная модель, сценарии.
- **MuJoCo** — динамика механизмов, контакты, культура воспроизводимости.
- **SOFA** — FEM и компонентная архитектура.
- **Rapier** — наша текущая физика.
- **QEMU** — CPU, MMU, SoC и устройства.
- **ngspice** — MNA и всё, что вокруг transient-анализа.
## Связь подсистем и эмуляция железа
- [Renode](https://github.com/renode/renode): эмуляция SoC, периферия, временная
модель, сценарии. Ближайший аналог режима Bench.
- [FMI](https://fmi-standard.org/): стандарт co-simulation; словарь для `bridge`
и точек синхронизации.
- [OpenModelica](https://openmodelica.org/): мультидоменная модель уравнениями;
полезно понять, где граница между нами и «системой уравнений».
- [QEMU](https://github.com/qemu/qemu): RISC-V target, MMU, исключения, virtio.
Обязательное чтение перед M8 и M11.
- [TinyEMU](https://bellard.org/tinyemu/): RV32/RV64, Linux и virtio в малом объёме
кода; главный референс для этапов CPU и Linux.
- [mini-rv32ima](https://github.com/cnlohr/mini-rv32ima): крошечный RV32, удобен для
эмуляции МК по тактам.
- [Spike](https://github.com/riscv-software-src/riscv-isa-sim) и
[riscv-tests](https://github.com/riscv-software-src/riscv-tests): эталонная модель
ISA и тесты для дифференциальной проверки.
- [xv6-riscv](https://github.com/mit-pdos/xv6-riscv): простая ОС для интеграционных
тестов до полноценного Linux.
- [Verilator](https://github.com/verilator/verilator): на будущее, если дойдём до
логического уровня.
- [Wokwi](https://wokwi.com/): UX-референс «МК + схема + симуляция в одном месте».
## Физика и детерминизм
- [MuJoCo](https://github.com/google-deepmind/mujoco): динамика механизмов,
articulated bodies, контакты, воспроизводимость.
- [Jolt Physics](https://github.com/jrouwe/JoltPhysics): режим детерминизма и его
тесты в CI — образец оформления golden-тестов физики.
- [Box2D](https://github.com/erincatto/box2d): солвер ограничений, эталон читаемости
перед своим backend'ом.
- [Rapier](https://github.com/dimforge/rapier) и
[руководство по детерминизму](https://rapier.rs/docs/user_guides/rust/determinism):
границы `enhanced-determinism`, поведение f32.
- [Project Chrono](https://github.com/projectchrono/chrono): многотельная механика и
мехатроника.
- [Rigs of Rods](https://github.com/RigsOfRods/rigs-of-rods) и идея BeamNG: модель
«узлы и балки» для разрушения в World.
- [Fix Your Timestep](https://gafferongames.com/post/fix_your_timestep/): фиксированный
шаг и интерполяция рендера.
- Overwatch GDC 2017: ECS, реплей и перемотка — схема, близкая к нашим снимкам.
## FEM и прочность
- [SOFA](https://github.com/sofa-framework/sofa): компонентная архитектура
деформируемых моделей.
- [CalculiX](http://www.dhondt.de/): балки, тетраэдры, контакт; смотреть постановки
и верификационные кейсы.
- [FreeCAD FEM](https://github.com/FreeCAD/FreeCAD): инженерный workflow
«геометрия → сетка → условия → решатель → результат».
- [scikit-fem](https://github.com/kinnala/scikit-fem): маленькая FEM-библиотека,
которую можно прочитать целиком.
- [anastruct](https://github.com/ritchie46/anastruct) и
[PyNite](https://github.com/oliehood/PyNite): рамные и балочные расчёты — масштаб,
который реально осилить.
- [Gmsh](https://gmsh.info/): генерация сеток и форматы.
- [fTetWild](https://github.com/wildmeshing/fTetWild) и
[TetGen](https://wias-berlin.de/software/tetgen/): оценить, сколько стоит
тетраэдризация меша.
- [OpenFOAM](https://www.openfoam.com/): CFD и граничные условия, если дойдём до
честных воздушных потоков.
## Электроника
- [ngspice](https://ngspice.sourceforge.io/): штампы MNA, Newton, контроль шага,
breakpoints, gmin и source stepping.
- [CircuitJS](https://github.com/sharpie7/circuitjs1): читаемая реализация MNA.
- [ahkab](https://github.com/ahkab/ahkab): компактный SPICE на Python.
- [KiCad](https://www.kicad.org/): плата как данные; посмотреть текстовые форматы
до того, как замораживать свои RON-схемы.
## Мир и рендер
- [CDLOD](http://www.cdlod.com/): статья и код Strugar'а; clipmap-террейн проще
понимать через CDLOD.
- [Gazebo](https://gazebosim.org/): как разведены мир, сенсоры и контроллер.
- [Webots](https://cyberbotics.com/): архитектура сенсоров, плагинов и миров.
- [Bevy](https://github.com/bevyengine/bevy): ECS, asset pipeline и организация
рендера; движок не берём, идеи смотрим.
## Робототехника и сценарии
- [Cheetah-Software](https://github.com/mit-biomimetics/Cheetah-Software): открытый
стек походки и стабилизации.
- [Stanford Doggo](https://github.com/stanfordroboticsclub/StanfordDoggoProject):
реальные массы и моменты для приводов.
- [Open Dynamic Robot Initiative](https://github.com/open-dynamic-robot-initiative):
открытые приводы и ноги как источник реалистичных цифр и BOM.
- [Petoi OpenCat](https://github.com/PetoiCamp/OpenCat): «МК + серво + четвероногое»
в масштабе, близком к Bench и World.
- [CARLA scenario_runner](https://github.com/carla-simulator/scenario-runner): DSL
сценариев, метрики и pass/fail — почти наша задача «сценарий как опыт».
## UI и данные
- **ShapeUI blueprint** (локальная копия `ref/shapeui-blueprint_v0.2_revised_ru.md`):
контракты shape-aware UI. Берём только идеи — event-driven redraw, command list,
glyph atlas, capability-модель (см. UI.md), не архитектуру.
- [Dear ImGui](https://github.com/ocornut/imgui): ID-стеки, клиппинг, батчинг —
минимальная архитектура виджетов перед своим UI.
- [egui](https://github.com/emilk/egui): только читать, зависимость не берём (D20).
- [OpenSCAD](https://openscad.org/): конструкция как параметризованные данные —
посмотреть на текстовый формат.