fabrilis/docs/REFERENCES.md
loki5512344 878d144b77 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.
2026-11-16 23:06:29 +01:00

131 lines
9.1 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.

# Что читать
Не копировать целиком и не тянуть в зависимости, а искать конкретные алгоритмы и
решения. Ссылки проверены 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/): конструкция как параметризованные данные —
посмотреть на текстовый формат.