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:
commit
79928b645b
222 changed files with 5335 additions and 0 deletions
81
docs/ARCHITECTURE.md
Normal file
81
docs/ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
# Архитектура
|
||||
|
||||
## Принципы
|
||||
- Cargo workspace из маленьких crate'ов. Симуляция — чистый Rust без GPU и без Bevy.
|
||||
- Зависимости идут только вниз. Подсистемы друг о друге не знают; их соединяют
|
||||
`bridge` и планировщик из `core`.
|
||||
- Одно приложение, три режима — пресеты `Fidelity` (см. MODES.md).
|
||||
- Рендер только читает снимок состояния и не влияет на симуляцию.
|
||||
|
||||
## Слои и crate'ы
|
||||
| Слой | Crate | Роль | Зависит от |
|
||||
|---|---|---|---|
|
||||
| Ядро | `core` | СИ-единицы, время (u64 нс), планировщик, Fidelity, снимки, `math`, `vec` (Vec3/Mat3/Quat/Transform) | — |
|
||||
| | `platform` | топология P/E-ядер, GPU, бенчмарки, регулятор | core |
|
||||
| | `storage` | форматы, миграции, blob по хешу, папка проекта | core |
|
||||
| Данные | `materials` | материалы, масса/инерция по мешу, прочность | core |
|
||||
| | `scene` | сцена и конструкция, импорт мешей | core, materials, storage |
|
||||
| | `parts` | библиотека деталей (данные + плагины), BOM | core, materials, scene |
|
||||
| Физика | `physics` | трейт `PhysicsBackend`, Rapier, шарниры, трение | core |
|
||||
| | `structure` | балки, FEM, напряжения, разрушение | core, materials |
|
||||
| | `thermal` | тепло, вентиляция | core, materials |
|
||||
| | `aero` | аэродинамика, ветер | core |
|
||||
| | `actuators` | мышцы, серво, моторы | core |
|
||||
| Электроника | `analog` | MNA-решатель схем | core |
|
||||
| | `wiring` | жгуты проводов | core, analog, thermal |
|
||||
| | `cpu` | трейт `Cpu`, RISC-V (потом arm/avr) | core |
|
||||
| | `soc` | шина, периферия, device tree, virtio | core, cpu |
|
||||
| | `sensors` | IMU, энкодеры, токовые датчики, модели шума и задержки | core |
|
||||
| | `bridge` | пины ↔ схема ↔ приводы ↔ физика | core, soc, analog, actuators, physics |
|
||||
| Мир | `worldgen` | шум, высотная карта, чанки | core |
|
||||
| Верх | `scripting` | Rhai, сценарии опытов | core |
|
||||
| | `analysis` | описания опытов, развёрток, Monte Carlo и метрик устойчивости; исполняет их `app` через трейт `Experiment` | core |
|
||||
| | `modes` | Bench / Lab / World | почти все |
|
||||
| | `render` | wgpu: clipmap, инстансинг, режимы вида | core |
|
||||
| | `ui` | свой immediate-mode UI на нашем рендере: редактор, инспектор, графики, event-driven redraw | core, render |
|
||||
| | `app` | winit, главный цикл | core, platform, storage, modes, render, ui |
|
||||
|
||||
## Поток данных за такт
|
||||
1. Планировщик (`core::sched`) делит время на эпохи по наибольшему периоду.
|
||||
2. Внутри эпохи подсистемы делают свои шаги с фиксированным порядком; шаг режется
|
||||
ближайшим событием из очереди (COUPLING.md).
|
||||
3. Обмен только в точках синхронизации через `bridge` (защёлкнутые значения);
|
||||
сильные связи решаются совместно, а не запаздыванием.
|
||||
4. В конце эпохи пишется `Snapshot`: набор подснимков, по одному от подсистемы.
|
||||
5. `render` и `ui` читают снимок; `storage` сохраняет по запросу.
|
||||
|
||||
`analysis` не запускает симуляцию сам: он описывает опыт (параметры, seeds,
|
||||
проверки) и метрики, а прогон выполняет `app` через трейт `Experiment`. Иначе
|
||||
`analysis` пришлось бы тянуть вверх все подсистемы и получить цикл слоёв.
|
||||
|
||||
## Бюджет производительности
|
||||
Эталонная сцена — паук: 24 тела, 32 шарнира, 8 аналоговых узлов, 12 датчиков,
|
||||
физика 1 кГц. Цель — RTF ≥ 1 на машине с RX 470 (AMD, 2016) при 60 кадрах.
|
||||
Бюджет такта World: 0.5 мс на физику, 0.2 мс на электронику и датчики, остальное
|
||||
на подготовку снимка. Бюджет проверяется бенчмарком в CI; выход за него — повод
|
||||
переходить на `ash` (D24) или упрощать World, но не менять шаг.
|
||||
|
||||
## Адаптация под устройство
|
||||
`platform` определяет ядра (P/E), SIMD, RAM, GPU и кеширует профиль. Адаптируется
|
||||
только то, что не влияет на результат: число потоков, раскладка по ядрам, качество
|
||||
рендера, место culling. Модели (Fidelity) от железа не зависят. Подробно: DETERMINISM.md.
|
||||
|
||||
## Расширяемость
|
||||
Новая деталь = данные (RON) + при необходимости плагин с трейтом из `parts::plugin`.
|
||||
Ядро править не нужно.
|
||||
|
||||
## Структура репозитория
|
||||
```
|
||||
fabrilis/
|
||||
├── Cargo.toml, rustfmt.toml, clippy.toml, rust-toolchain.toml, LICENSE (MIT), TODO.md
|
||||
├── docs/ документация (не подпадает под правила кода)
|
||||
├── crates/ 24 crate'а симуляции, рендера и приложения
|
||||
├── tools/limits/ проверка правил (CODE_RULES.md), вызывается из build.rs
|
||||
├── tools/measure_deps.py замер веса кандидатов в зависимости
|
||||
├── examples/ эталонные конструкции (первый: мех-паук)
|
||||
├── ref/ клоны чужих проектов для чтения (gitignored, не проверяются)
|
||||
├── .githooks/ pre-commit: правила, fmt, clippy
|
||||
└── .github/ CI на Linux, Windows, macOS
|
||||
```
|
||||
Слои зависимостей закодированы в `tools/limits/src/rules/layers.rs`; новый crate
|
||||
нужно внести туда, иначе сборка падает.
|
||||
108
docs/CODE_RULES.md
Normal file
108
docs/CODE_RULES.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
# Правила кода
|
||||
|
||||
Правила проверяются автоматически, а не на честном слове. Главный инструмент —
|
||||
crate `tools/limits` (`fabrilis-limits`). У каждого crate'а есть `build.rs`, который
|
||||
вызывает его, поэтому **нарушение жёсткого правила ломает любую сборку**
|
||||
(`cargo build`, `check`, `clippy`, `test`). Весь репозиторий проверяется командой
|
||||
`cargo run -p fabrilis-limits`; она же стоит в pre-commit (`.githooks/`) и в CI.
|
||||
|
||||
Правила касаются только нашего кода. `docs/`, `*.md` и `ref/` (локальные клоны
|
||||
чужих проектов, см. REFERENCES.md) не проверяются.
|
||||
|
||||
## Проверяет `fabrilis-limits` (ошибка сборки)
|
||||
|
||||
| Правило | Подробности |
|
||||
|---|---|
|
||||
| Размер файла | больше **350** строк — предупреждение, больше **500** — ошибка; на тестовые файлы не распространяется |
|
||||
| Файлов в директории | не больше **4** файлов кода (`.rs`, `.wgsl`, `.rhai`, `.sh`) в одной директории, и так в каждой директории отдельно, на любой глубине; подпапки в счёт не идут, тестовые файлы не считаются |
|
||||
| Комментарии на английском | кириллица в `//`, `///`, `//!`, `/* */` запрещена; строки и литералы не проверяются |
|
||||
| Без маркеров работы | `TODO`, `FIXME`, `HACK`, `XXX` в комментариях запрещены; открытая работа живёт в `TODO.md` |
|
||||
| Тесты отдельно от кода | см. ниже |
|
||||
| Без файлов-свалок | имена `utils`, `util`, `helpers`, `helper`, `common`, `misc`, `stuff`, `shared` для файлов и папок запрещены: файл называется по тому, что в нём лежит |
|
||||
| Слои crate'ов | зависимости идут только вниз; симуляция не зависит от `render`, `ui`, `app`; новый crate нужно внести в таблицу `tools/limits/src/rules/layers.rs`, иначе сборка падает |
|
||||
|
||||
### Тесты отдельно от кода
|
||||
В файле с кодом нет ни одного теста: ни `#[test]`, ни `#[cfg(test)] mod x { ... }`,
|
||||
ни `#[cfg(test)]`-хелперов. Допустимо только:
|
||||
- **модульные тесты:** в коде одна строка `#[cfg(test)] mod tests;`, а сами тесты лежат
|
||||
в `tests.rs` той же директории (`foo/mod.rs` → `foo/tests.rs`, `foo/bar.rs` → тоже
|
||||
`foo/tests.rs`);
|
||||
- **интеграционные тесты и бенчи:** папки `tests/` и `benches/` в crate'е;
|
||||
- общие помощники для тестов лежат в `tests/<имя>/mod.rs` (не `common`).
|
||||
|
||||
Тестовые файлы (`tests.rs`, всё в `tests/` и `benches/`) **не считаются** в лимит
|
||||
четырёх файлов на директорию и **не ограничены** по размеру: один `tests.rs` может
|
||||
быть длинным. Разносить тесты по подпапкам ради лимитов не нужно — весь модуль
|
||||
тестируется одним файлом рядом.
|
||||
|
||||
## Проверяют rustfmt и clippy (pre-commit и CI с `-D warnings`)
|
||||
|
||||
| Правило | Чем задано |
|
||||
|---|---|
|
||||
| Отступы только табами | `rustfmt.toml`: `hard_tabs = true` |
|
||||
| `unsafe` запрещён | `Cargo.toml`: `unsafe_code = "deny"` |
|
||||
| Детерминизм: нет `sin/cos/exp/pow` из `std`, `HashMap/HashSet`, `Instant::now`, `SystemTime::now` | `clippy.toml`: `disallowed-methods`, `disallowed-types`; `platform` и `app` могут разрешить время точечно |
|
||||
| Нет `unwrap`, `expect`, `panic!`, `todo!`, `unimplemented!`, `dbg!` в обычном коде | `Cargo.toml`: lints; в тестах разрешено (`clippy.toml`) |
|
||||
| Индексация только с доказанной границей | см. «Паники и индексация» |
|
||||
| Функция не длиннее 60 строк, не больше 5 аргументов, сложность ≤ 15 | `clippy.toml`: пороги |
|
||||
| Каждое `#[allow]` объясняется: `#[allow(lint, reason = "...")]` | `allow_attributes_without_reason` |
|
||||
|
||||
Исключения оформляются точечно, с причиной, и не на весь crate без необходимости.
|
||||
|
||||
### Паники и индексация
|
||||
`unwrap`, `expect`, `panic!`, `todo!`, `unimplemented!` и `dbg!` в библиотечном
|
||||
коде запрещены, в тестах разрешены. Индексация (`v[i]`) паникует сама, и линтер её
|
||||
не ловит, поэтому: **индексировать можно только там, где граница доказана
|
||||
структурой** — фиксированный массив, срез, полученный в этой же функции с
|
||||
проверкой, индекс из конструктора. Иначе — итераторы, `get`, `chunks`.
|
||||
Паника допустима лишь как утверждение «сюда нельзя попасть» в месте, куда данные
|
||||
из файла или из сети не доходят; в тестах это проверяется отдельным тестом.
|
||||
|
||||
### Лимиты и как их держать
|
||||
Списка исключений для файлов кода нет: если файл упирается в лимит, он делится на
|
||||
подмодули по смыслу. Декодер RISC-V, MNA-матрица и FEM собираются из маленьких
|
||||
модулей (по шагам ISA, по типам элементов, по решателям), а не из одного
|
||||
«большого» файла. Если подпапки не помогают, это повод пересмотреть структуру,
|
||||
а не завести исключение.
|
||||
|
||||
Лимит четырёх файлов действует на каждую директорию независимо: в `src/` может
|
||||
лежать 4 файла и 6 подпапок, и в каждой подпапке снова 4 файла и свои подпапки,
|
||||
без ограничения глубины. Тесты в этот счёт не входят, поэтому `mod.rs`, три
|
||||
модуля и `tests.rs` — это нормальная директория, а не пять файлов.
|
||||
|
||||
### Dev-зависимости
|
||||
`proptest` и `criterion` разрешены как dev-зависимости (D26): в продуктовую
|
||||
сборку они не входят. Свои тесты на seeded `core::rng` остаются основой, потому
|
||||
что тот же генератор нужен Monte Carlo.
|
||||
|
||||
## Принципы
|
||||
- **KISS**: самое простое решение, которое работает; без заглушек «на будущее».
|
||||
- **DRY**: одно знание — одно место (device tree из карты памяти, единицы в `core`).
|
||||
- **SOLID**: один модуль — одна причина меняться; зависимости через трейты
|
||||
(`PhysicsBackend`, `Cpu`, `Device`); зависимости только вниз по слоям.
|
||||
|
||||
## Правила проекта (проверяются ревью)
|
||||
- В движке нет кода под конкретную конструкцию: всё через данные, детали-плагины и
|
||||
сценарии; конструкции лежат в `examples/`.
|
||||
- Crate'ы симуляции не зависят от GPU, окна и Bevy.
|
||||
- Единицы СИ через newtype из `core::units`, без голых `f64` в публичных API физики.
|
||||
- Новая внешняя зависимость обосновывается записью в `DECISIONS.md` (мы пишем своё,
|
||||
где это разумно).
|
||||
- Архитектурное изменение сопровождается записью в `DECISIONS.md`.
|
||||
|
||||
## Идеи на потом (пока не включены)
|
||||
Каждый пункт можно включить отдельным шагом, когда проект дорастёт.
|
||||
|
||||
| Идея | Зачем |
|
||||
|---|---|
|
||||
| `cargo-deny` (лицензии, уязвимости, дубли версий, запрещённые crate'ы) | гигиена зависимостей |
|
||||
| `cargo-machete` | неиспользуемые зависимости |
|
||||
| `missing_docs`, `missing_errors_doc`, `missing_panics_doc` для нижних слоёв | документированный публичный API |
|
||||
| Касты `cast_possible_truncation`, `cast_precision_loss` в crate'ах симуляции | потеря точности между `u64` нс и `f64` |
|
||||
| `float_cmp`: сравнение `f64` через допуск, а не `==` | корректная численная логика |
|
||||
| Фаззинг (`cargo-fuzz`) для импорта мешей, форматов RON, декодера RISC-V | парсеры устойчивы к мусору |
|
||||
| Мутационное тестирование (`cargo-mutants`) и покрытие (`cargo-llvm-cov`) для `core`, `analog`, `cpu` | тесты реально ловят ошибки |
|
||||
| Порог регрессии бенчмарков в CI (своя утилита замеров) | скорость не падает незаметно |
|
||||
| Conventional Commits и `commit-msg` хук | читаемая история |
|
||||
| Проверка, что каждый crate описан в `ARCHITECTURE.md` | документация не отстаёт |
|
||||
| Лимит на число `unsafe`-блоков и место (только `cpu`, с обоснованием) | контроль рисков |
|
||||
37
docs/COORDINATES.md
Normal file
37
docs/COORDINATES.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
# Системы координат и единицы
|
||||
|
||||
## Мировая система
|
||||
Правая, Z вверх, X вперёд, Y влево (как в робототехнике, ROS REP-103). Единицы СИ.
|
||||
Углы в радианах (`Radians`); градусы только в интерфейсе и при импорте.
|
||||
|
||||
## Системы
|
||||
| Система | Назначение |
|
||||
|---|---|
|
||||
| world | неподвижная система мира |
|
||||
| body | связана с деталью; для инерции начало в центре масс |
|
||||
| joint | ось шарнира направлена вдоль локальной Z |
|
||||
| sensor | датчик, задаётся преобразованием от body |
|
||||
| render | только для рендера, получается в конце цепочки |
|
||||
|
||||
Преобразования это `Transform` (кватернион и вектор, f64). Сцена хранит цепочку как
|
||||
граф; матрицы для рендера собираются в конце.
|
||||
|
||||
## Вращения
|
||||
Единичные кватернионы с контролем дрейфа нормы. Углы Эйлера только для ввода и
|
||||
вывода. Нормализация около нуля и вырожденные матрицы обрабатываются явно: ошибка,
|
||||
а не NaN.
|
||||
|
||||
## Импорт: единицы и оси
|
||||
| Формат | Единицы | Оси | Политика |
|
||||
|---|---|---|---|
|
||||
| STL | не заданы | не заданы | проект задаёт единицы (по умолчанию мм) |
|
||||
| OBJ | не заданы | не заданы | проект задаёт единицы |
|
||||
| glTF | метры | Y вверх, правая | оси пересчитываются в Z вверх |
|
||||
|
||||
Материалы: плотность в кг/м³, прочность в Па; в файлах материалов единицы указаны
|
||||
явно суффиксом и конвертируются при импорте. Единицы источника записываются в
|
||||
конструкцию.
|
||||
|
||||
## Большие миры
|
||||
Симуляция в f64. Для рендера и f32-компонентов начало координат переносится (origin
|
||||
rebasing).
|
||||
46
docs/COUPLING.md
Normal file
46
docs/COUPLING.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# Связь подсистем (co-simulation)
|
||||
|
||||
Типичная замкнутая цепь: МК выдаёт PWM, драйвер питает мотор, мотор двигает ногу,
|
||||
нагрузка поднимает ток, ток просаживает питание и греет провод, нагрев меняет
|
||||
сопротивление, и мотор теряет момент. Подсистемы считаются разными решателями, и
|
||||
от способа обмена между ними зависит, будет ли поведение верным. Словарь заимствован
|
||||
из стандарта FMI: master algorithm, communication step, event iteration, rollback.
|
||||
|
||||
## Классы связей
|
||||
| Класс | Пример | Способ обмена |
|
||||
|---|---|---|
|
||||
| Односторонняя | физика → рендер; ток → нагрев провода (медленно) | снимок, без итераций |
|
||||
| Слабая двусторонняя | МК ↔ периферия; температура ↔ сопротивление | обмен в точках синхронизации, запаздывание на шаг допустимо, значение удерживается (zero-order hold) |
|
||||
| Сильная | мотор: напряжение, ток, обратная ЭДС, момент, скорость; контакт стопы с землёй | один решатель на всю связку или итерации внутри шага (Гаусс-Зейдель с релаксацией) и критерий сходимости |
|
||||
|
||||
Каждая связь в коде объявляется с классом. Сильные связи нельзя решать запаздыванием:
|
||||
модель мотора живёт внутри аналогового решателя, а механическая нагрузка входит в неё
|
||||
как состояние (момент, скорость) и обновляется на каждом аналоговом шаге.
|
||||
|
||||
## Контракт подсистемы
|
||||
Входы, выходы, период, направление связи, допустимое запаздывание и поддержка отката
|
||||
(`save` и `restore` состояния). Контракт проверяется при сборке сцены.
|
||||
|
||||
## События
|
||||
Очередь событий с метками времени в нс: фронты PWM, прерывания МК, перегорание
|
||||
предохранителя, обрыв провода. Событие делит шаг: аналоговый решатель ставит
|
||||
breakpoint в момент события. Внутри эпохи события обрабатываются в порядке (время,
|
||||
приоритет, номер подсистемы). Между событиями значения удерживаются; интерполяция
|
||||
нужна только для вывода.
|
||||
|
||||
## Шаг и ошибка
|
||||
Аналоговый шаг адаптивный и ограничен максимумом режима (Bench: 1 мкс, World: крупный
|
||||
квант) и ближайшим событием. Если итерации сильной связи не сошлись, шаг делится
|
||||
пополам и повторяется с отката. Если после N делений сходимости нет, это диагностика
|
||||
в отчёт (VALIDATION.md), а не тихое продолжение.
|
||||
|
||||
## Снимок
|
||||
Снимок состоит из подснимков подсистем, и каждая подсистема сама сериализует своё
|
||||
состояние. Это нужно для отката шага, перемотки и сохранения.
|
||||
|
||||
## План внедрения
|
||||
- Срез 1: слабые связи с запаздыванием на шаг и очередь событий.
|
||||
- Срез 4 (электроника): сильные связи и откат шага.
|
||||
|
||||
## Открыто
|
||||
Выбор коэффициента релаксации и предельного числа делений шага.
|
||||
51
docs/DECISIONS.md
Normal file
51
docs/DECISIONS.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
# Решения
|
||||
|
||||
| # | Решение | Почему |
|
||||
|---|---|---|
|
||||
| D1 | Multi-crate workspace, симуляция без GPU/Bevy | тесты без окна, CI, детерминизм |
|
||||
| D2 | Без Bevy; свой рендер на wgpu (Vulkan); без общего ECS, данные SoA внутри crate'ов | RX 470 слабая, нужен контроль; рендер заменяем |
|
||||
| D3 | Физика: гибрид. `PhysicsBackend` + `rapier3d-f64` с `enhanced-determinism` на старте, нужное заменяем своим | быстрый старт без потери контроля и без границы f32 |
|
||||
| D4 | Механика: жёсткие тела + нагрузки на шарниры (World); балки и FEM (Lab); разрушение | точность там, где нужна |
|
||||
| D5 | ISA: RISC-V первым (RV32IMAC, RV64GC), остальные через трейт `Cpu` | пользователь знает RISC-V, Linux, открытая ISA |
|
||||
| D6 | Электроника в два слоя: цифровая эмуляция SoC + аналоговый MNA + bridge | запуск реального Linux/прошивок + реальное питание |
|
||||
| D7 | Один бинарник, режимы Bench/Lab/World — пресеты Fidelity | один паук и детали во всех режимах |
|
||||
| D8 | Детерминизм: целое время, свой `math`, порядок независим от потоков | воспроизводимость, перемотка, golden-тесты |
|
||||
| D9 | Управление временем отдельно от Fidelity: dt не меняется | замедление ничего не огрубляет |
|
||||
| D10 | Адаптация под железо: P/E-ядра, GPU только для неавторитетного | одинаковый результат у всех |
|
||||
| D11 | Сохранения: папка проекта, RON, снимки отдельно, настройки в XDG | git-friendly, командная работа |
|
||||
| D12 | Скрипты: Rhai | чистый Rust, песочница, без C-зависимостей |
|
||||
| D13 | Лимиты: файл >350 строк — предупреждение, >500 — ошибка сборки; ≤4 файла кода в каждой директории (подпапки не считаются, вложенность любая). Тестовые файлы (`tests.rs`, `tests/`, `benches/`) не считаются и по размеру не ограничены | см. CODE_RULES.md |
|
||||
| D14 | Террейн: высотная карта + clipmap, без вокселей; генерация на CPU | одна карта для рендера и коллайдеров |
|
||||
| D15 | Деталь = данные + плагин; из конструкции экспортируется BOM | цель: собрать конструкцию в реальности |
|
||||
| D16 | Цель проекта: универсальная платформа проектирования любых механизмов; паук — эталонный проект в `examples/`, в движке нет кода под него | расширяемость, любые будущие конструкции |
|
||||
| D17 | Сценарии и анализ — часть ядра платформы: crate `analysis` (развёртки, Monte Carlo, метрики устойчивости, отказы) и `sensors` (IMU, энкодеры, шум) | проверка стабилизации и работы контроллеров |
|
||||
| D18 | Правила репозитория проверяются кодом (`tools/limits` в `build.rs` каждого crate'а): размеры, комментарии на английском, тесты отдельно, слои crate'ов | нарушение ломает сборку, правила не держатся на дисциплине |
|
||||
| D19 | Лицензия MIT: код можно брать и менять, но нужно сохранять упоминание авторов; правообладатель и автор: loki | простая разрешающая лицензия с обязательной атрибуцией |
|
||||
| D20 | UI свой, на нашем рендере (прямоугольники, текст, виджеты, графики); egui и другие готовые UI-библиотеки не берём | пользователь их не любит; мы всё равно владеем рендером |
|
||||
| D21 | Векторная математика своя в `core` (Vec3, Mat3, Quat, Transform на f64 через `core::math`); `glam` и `nalgebra` в симуляции не используем | детерминизм: их тригонометрия идёт через системный libm |
|
||||
| D22 | Импорт мешей свой: STL и OBJ пишем сами, glTF сначала минимальным своим читателем | `gltf` тянет 37 crate'ов ради простого формата |
|
||||
| D23 | Крупные зависимости: `wgpu`, `winit`, `rapier3d-f64`, `rhai` принимаем пока, остальное своё; `proptest` и `criterion` — только dev-зависимости (D26) | см. DEPENDENCIES.md |
|
||||
| D24 | Рендер на `wgpu`; запасной вариант — `ash` (Vulkan напрямую). Переход, если сборка `wgpu` (61 crate) или размер станут проблемой | рендер скрыт за crate'ом `render`, замена не заденет симуляцию |
|
||||
| D25 | Название проекта: Fabrilis (лат. fabrilis, «относящийся к мастеру, ремесленнику»); автор: loki; префикс crate'ов `fabrilis-` | свободно на crates.io; латынь по вкусу автора |
|
||||
| D26 | `proptest` и `criterion` разрешены как dev-зависимости; основные тесты — свои на seeded `core::rng` | в продуктовую сборку dev-зависимости не входят, экономить на них незачем; свой генератор всё равно нужен для Monte Carlo |
|
||||
| D27 | Этапы — вертикальные срезы с критерием готовности (DoD); каждая веха даёт демонстрируемый результат | горизонтальный план даёт годы без рабочего инструмента |
|
||||
| D28 | Детерминизм в трёх уровнях: D1 повтор на машине, D2 при любом числе потоков, D3 на разных ОС и архитектурах. Авторитетная сборка — базовый `target-cpu`, SIMD только явными ядрами | честная граница гарантии вместо одного невыполнимого обещания |
|
||||
| D29 | Шаг физики World — 1 кГц (1 мс); Bench и Lab не огрубляются, а замедляются | 250 Гц разъезжается по фазе с контактом стопы и жёстким шарниром |
|
||||
| D30 | Проект публичный, но до 0.6.0 API плагинов и форматов нестабилен; обратная совместимость не обещается | ещё рано замораживать интерфейсы, а публичность задаёт планку документации |
|
||||
| D31 | Углы — newtype `Radians`; градусы только в интерфейсе и при импорте | градусы и радианы иначе путаются молча |
|
||||
| D32 | Очередь событий с метками в нс в планировщике: событие делит шаг подсистемы | фронты PWM и прерывания нельзя привязывать к эпохам |
|
||||
| D33 | Версия компилятора зафиксирована `rust-toolchain.toml`; CI собирает базовую и `native` сборки и сверяет хеши | разные LLVM могут разойтись в последних битах |
|
||||
| D34 | UI — свой immediate-mode слой на нашем `wgpu`-рендере с event-driven redraw; retained-дерево только по профилировке. ShapeUI blueprint — источник контрактов, не фундамент | редактору нужны панели, дерево и графики, а не окна произвольной формы; UI-фреймворк на годы остановил бы проект |
|
||||
|
||||
## Открытые вопросы
|
||||
- FEM: тетраэдры для всей детали или балки + локальные тетраэдры в узлах.
|
||||
- Модель разрушения: порог по напряжению, трещины, усталость.
|
||||
- Воздушные потоки: сеть каналов (быстро) или CFD-lite (точно).
|
||||
- Сходимость MNA: набор приёмов (gmin stepping, source stepping, breakpoints) и
|
||||
предельное число делений шага.
|
||||
- Коллизии: `parry` оставляем навсегда или пишем свой узкий слой после своего
|
||||
физического backend'а.
|
||||
- Когда переходить с `wgpu` на `ash` (D24): после M4 по времени сборки и RTF.
|
||||
- Shaping и IME для текстовых полей: `cosmic-text` или `Parley`; решаем на M10.
|
||||
- Нужен ли retained-слой UI: решаем по профилировке M10.
|
||||
- Конкретная целевая плата и список реальных компонентов.
|
||||
56
docs/DEPENDENCIES.md
Normal file
56
docs/DEPENDENCIES.md
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
# Зависимости
|
||||
|
||||
Правило: пишем своё, где это разумно; берём готовое, только когда оно отлично
|
||||
работает и писать самим слишком дорого. Каждая внешняя зависимость обосновывается
|
||||
записью в DECISIONS.md.
|
||||
|
||||
## Замеры (16.11.2026, версии по умолчанию из crates.io)
|
||||
«Crate'ов на Linux» — зависимости, которые реально собираются на Linux.
|
||||
Размер исходников и строки считаны для всех платформ (включая Windows и macOS),
|
||||
поэтому завышены; для оценки скорости сборки смотри число crate'ов.
|
||||
|
||||
| Библиотека | Crate'ов на Linux | Исходники, МБ | Строк Rust | Решение |
|
||||
|---|---|---|---|---|
|
||||
| `libm` | 1 | 0.6 | 20 тыс. | берём (детерминированная математика) |
|
||||
| `serde` | 7 | 4.2 | 119 тыс. | берём (форматы) |
|
||||
| `ron` | 10 | 5.2 | 149 тыс. | берём (форматы сцен и конструкций) |
|
||||
| `rayon` | 6 | 1.8 | 53 тыс. | берём позже (развёртки, Monte Carlo) |
|
||||
| `fontdue` | 8 | 3.2 | 86 тыс. | берём для текста в своём UI; позже можно заменить своим растеризатором |
|
||||
| `rhai` | 25 | 25.6 | 669 тыс. | берём (скрипты) |
|
||||
| `rapier3d-f64` | 46 | 55.0 | 1757 тыс. | временно, пока не напишем свой backend (D3); вариант на f64 + `enhanced-determinism` |
|
||||
| `wgpu` | 61 | 209.1 | 4163 тыс. | берём; самый тяжёлый, см. ниже |
|
||||
| `winit` | 72 | 234.7 | 4163 тыс. | берём (окна и ввод на трёх ОС писать самим слишком дорого) |
|
||||
| `gltf` | 37 | 19.3 | 541 тыс. | не берём сейчас: свой минимальный читатель; возьмём, только если glTF станет обязательным |
|
||||
| `nalgebra` | 19 | 36.4 | 1289 тыс. | не берём в симуляции (свой `core::vec`) |
|
||||
| `glam` | 1 | 6.4 | 250 тыс. | не берём в симуляции (свой `core::vec`) |
|
||||
| `egui` | 54 | 35.1 | 944 тыс. | не берём (D20) |
|
||||
| `proptest` | 26 | 54.5 | 1441 тыс. | dev-зависимость, берём для property-тестов (D26) |
|
||||
| `criterion` | 51 | 166.7 | 1643 тыс. | dev-зависимость, берём для бенчмарков (D26) |
|
||||
| `ash` (Vulkan напрямую) | 3 | 5.0 | 131 тыс. | запасной вариант вместо `wgpu` |
|
||||
|
||||
## Что пишем сами
|
||||
Планировщик, единицы, векторная математика, эмулятор CPU и SoC, аналоговый
|
||||
решатель, балки и FEM, тепло, аэродинамика, мышцы, мир, рендер-слой, UI, импорт
|
||||
STL/OBJ и минимальный glTF, физический backend (после старта на Rapier).
|
||||
|
||||
## Тяжёлые, которые оставляем пока
|
||||
- **`wgpu`** (61 crate): самый тяжёлый, но скрыт за crate'ом `render`. Если время
|
||||
сборки или размер начнут мешать, переходим на `ash` (3 crate'а): придётся
|
||||
написать свой менеджер памяти, swapchain и синхронизацию, а шейдеры
|
||||
компилировать заранее. Минус `ash`: macOS только через MoltenVK.
|
||||
- **`winit`** (72 crate'а): окна на Wayland, X11, Windows и macOS вручную — слишком
|
||||
большая работа без пользы для цели проекта.
|
||||
- **`rapier3d-f64`**: вариант Rapier на `f64` (тот же набор crate'ов) плюс фича
|
||||
`enhanced-determinism`; нужен для быстрого старта и не вносит границу `f32`.
|
||||
Авторитетные результаты со временем считает свой backend.
|
||||
- **`rhai`**: заменить своим языком возможно, но это отдельный большой проект.
|
||||
|
||||
## UI
|
||||
Свой UI на нашем рендере (D20, D34): immediate-mode список команд, панели, текст,
|
||||
кнопки, ползунки, графики, дерево деталей, таблица свойств, окно 3D-вида, потом
|
||||
редактор схем и жгутов. Растеризация шрифта через `fontdue`; shaping/IME для
|
||||
текстовых полей — кандидаты `cosmic-text`/`Parley`, решение на M10 (UI.md).
|
||||
Сначала оверлей отладки (M4), полноценный редактор в M10.
|
||||
Отвергнуты: `egui` (не нравится), `iced` (тяжёлый), `slint` (лицензия GPL/коммерческая
|
||||
несовместима с MIT), `xilem` (молодой). Blueprint ShapeUI — источник контрактов,
|
||||
не фундамент (UI.md).
|
||||
61
docs/DETERMINISM.md
Normal file
61
docs/DETERMINISM.md
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
# Детерминизм
|
||||
|
||||
Результат симуляции не зависит от железа, числа потоков и ОС. Без этого нет
|
||||
воспроизводимых багов, перемотки и golden-тестов.
|
||||
|
||||
## Уровни гарантии
|
||||
| Уровень | Что гарантирует | Где проверяется |
|
||||
|---|---|---|
|
||||
| **D1** | Повтор на той же машине, той же сборке, том же числе потоков даёт тот же результат | каждый коммит, golden-хеш |
|
||||
| **D2** | То же при любом числе потоков | CI, прогон с 1, 2, 8 и 24 потоками |
|
||||
| **D3** | Разные ОС и архитектуры (Linux x86-64, Windows, macOS ARM) дают одинаковый хеш | матрица CI, один хеш в репозитории |
|
||||
|
||||
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`), CI дополнительно
|
||||
собирает с `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 потоках. Хеш хранится в репозитории. При расхождении CI печатает
|
||||
первую подсистему, чей подснимок разошёлся (COUPLING.md).
|
||||
|
||||
## Адаптация под железо (`platform`)
|
||||
Разрешено: раскладка потоков (критический путь на P-ядрах, фон на E-ядрах),
|
||||
качество рендера, место culling. Запрещено: менять модели или шаг от устройства.
|
||||
34
docs/ELECTRONICS.md
Normal file
34
docs/ELECTRONICS.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
# Электроника
|
||||
|
||||
Цель: те же ELF-файлы, образы и драйверы, что и на реальном железе, без изменений.
|
||||
|
||||
## Цифровой слой
|
||||
- `cpu`: трейт `Cpu` (`step(бюджет_тактов)`, `reset`, линии IRQ). Реализации:
|
||||
RV32IMAC (микроконтроллеры), RV64GC с режимами M/S/U и MMU Sv39 (Linux).
|
||||
Позже arm и avr через тот же трейт.
|
||||
- Два режима выполнения: точный по тактам (Bench) и пачками (World).
|
||||
- `soc`: шина с трейтом `Device` (чтение/запись по адресу, `tick`, IRQ), карта
|
||||
памяти как данные, **device tree генерируется из неё**. Периферия: UART, GPIO,
|
||||
I2C, SPI, PWM, ADC, таймеры, virtio (диск, консоль).
|
||||
|
||||
## Аналоговый слой
|
||||
- `analog`: метод узловых потенциалов. Элемент добавляет «штамп» в матрицу.
|
||||
Нелинейные элементы решаются Newton; сходимость обеспечивают gmin stepping,
|
||||
source stepping и breakpoints. Шаг адаптивный, ограничен максимумом режима
|
||||
(Bench и Lab 1 мкс, World 50 мкс) и ближайшим событием (COUPLING.md).
|
||||
Если шаг не сходится после N делений, это диагностика в отчёт (VALIDATION.md),
|
||||
а не тихое продолжение.
|
||||
- Элементы: R, C, L, источники, диоды, транзисторы, батарея (с внутренним
|
||||
сопротивлением), драйверы, датчики.
|
||||
- `wiring` добавляет провода и разъёмы как элементы со связью с `thermal`.
|
||||
|
||||
## Мост (`bridge`)
|
||||
- GPIO — источник напряжения с выходным сопротивлением.
|
||||
- ADC читает напряжение узла; фронты PWM попадают в аналоговый шаг в точный момент.
|
||||
- Мотор и мышца — сильная связь: модель мотора с обратной ЭДС живёт внутри
|
||||
аналогового решателя, механическая нагрузка входит в неё как состояние и
|
||||
обновляется на каждом аналоговом шаге (COUPLING.md). Слабое запаздывание на шаг
|
||||
здесь недопустимо.
|
||||
|
||||
## Плата как данные
|
||||
RON описывает SoC и подключённую схему. Образ прошивки хранится по хешу.
|
||||
43
docs/MODES.md
Normal file
43
docs/MODES.md
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
# Режимы и Fidelity
|
||||
|
||||
Один бинарник, одна конструкция, три пресета. Режим задаёт периоды подсистем и
|
||||
выбор моделей (`Fidelity`), всё остальное общее.
|
||||
|
||||
| Режим | Что это | Точность |
|
||||
|---|---|---|
|
||||
| **Bench** | Плата без мира: SoC, периферия, схема, питание | МК по тактам, аналоговый шаг до 1 мкс |
|
||||
| **Lab** | Одна деталь на стенде: нагрузка, ток, температура | FEM, подробные мышцы, тепло, аналоговый шаг до 1 мкс |
|
||||
| **World** | Паук в мире: поляна, горы, ветер | физика 1 кГц (1 мс), аналоговый шаг до 50 мкс, МК пачками |
|
||||
|
||||
Деталь из World можно «вынуть» в Lab, плату — в Bench, конструкция та же.
|
||||
|
||||
Шаг физики 1 кГц выбран под ходьбу: при 250 Гц контакт стопы и жёсткий шарнир
|
||||
разъезжаются по фазе. 1 мс — целое число наносекунд (1 000 000 нс), поэтому
|
||||
делится без остатка. Если эталонная сцена не тянет real-time, World замедляется,
|
||||
а не огрубляется (см. бюджет в ARCHITECTURE.md).
|
||||
|
||||
## Fidelity (примеры)
|
||||
| Подсистема | Высокая | Низкая |
|
||||
|---|---|---|
|
||||
| Мышца | модель Хилла + тепло | простой привод |
|
||||
| Электроника | transient MNA, шаг до 1 мкс | идеальные элементы, шаг до 50 мкс |
|
||||
| Механика | балки/FEM | жёсткие тела + нагрузки на шарниры |
|
||||
| Аэродинамика | панельный метод | таблицы коэффициентов |
|
||||
| МК | по тактам | пачки по 1000 тактов, квантованные прерывания |
|
||||
|
||||
Fidelity — набор независимых полей, а не единый переключатель: можно взять точную
|
||||
механику и простую электронику. Режимы — только пресеты этих полей.
|
||||
|
||||
## События
|
||||
Шаг подсистемы ограничен не только периодом, но и ближайшим событием в очереди:
|
||||
фронт PWM, прерывание МК, отказ. Событие делит шаг в момент своего наступления
|
||||
(COUPLING.md). Между событиями входы удерживаются.
|
||||
|
||||
## Управление временем (отдельно от Fidelity)
|
||||
- Масштабируется только показ; шаг симуляции `dt` не меняется.
|
||||
- Пауза; шаг на такт, квант или (Bench) инструкцию МК.
|
||||
- Замедление 0.01×–1×; ускорение ограничено real-time factor.
|
||||
- Перемотка назад: ближайший снимок + досчёт вперёд (возможна из-за детерминизма).
|
||||
- Рендер интерполирует между снимками.
|
||||
- Bench и Lab никогда не огрубляются: если железо не тянет, симуляция идёт медленнее
|
||||
реального времени (показывается RTF). Только World может снижать визуальное качество.
|
||||
36
docs/PHYSICS_SCOPE.md
Normal file
36
docs/PHYSICS_SCOPE.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# Физика: объём и цели
|
||||
|
||||
Цель — спроектировать любую конструкцию на 100% так, чтобы её можно было собрать
|
||||
в реальности. Движок универсален; мех-паук — только первый пример.
|
||||
|
||||
## Импорт и материалы
|
||||
Меш (glTF/STL/OBJ) + материал → объём, масса, центр масс, тензор инерции (по
|
||||
дивергенции), коллайдер. Параметры материала: плотность, модуль Юнга, предел
|
||||
текучести и прочности, трение, теплопроводность, теплоёмкость, удельное
|
||||
сопротивление. Заполнение (infill/полость) задаёт эффективную плотность.
|
||||
|
||||
## Механика (`physics`, `structure`)
|
||||
- Жёсткие тела, шарниры, ограничения, контакты (Rapier на старте).
|
||||
- Трение: статическое и кинетическое, переключаемая модель (Кулон, с вязкой частью).
|
||||
- Балочные и FEM-элементы для Lab: поле напряжений, деформации, усталость.
|
||||
- Разрушение: при превышении прочности деталь ломается (разделение по сечению).
|
||||
|
||||
## Тепло и вентиляция (`thermal`)
|
||||
Теплопроводность, конвекция, излучение; источники: мышцы, моторы, провода,
|
||||
микросхемы. Вентиляция: потоки воздуха через корпус, обдув радиаторов. Метод
|
||||
(сеть каналов или CFD-lite) решаем перед этим этапом.
|
||||
|
||||
## Проводка (`wiring`)
|
||||
Жгуты: сечение AWG, длина, сопротивление, падение напряжения, нагрев током и его
|
||||
обратная связь в `thermal`, разъёмы, предохранители.
|
||||
|
||||
## Аэродинамика (`aero`)
|
||||
Панельный метод для Lab, таблицы коэффициентов для World; ветер.
|
||||
|
||||
## Режимы вида (`render::views`)
|
||||
Переключаемые цветовые карты по деталям: напряжение (запас до разрушения),
|
||||
деформация, температура, ток, давление/поток воздуха, трение/контакт.
|
||||
|
||||
## Выход в реальность (`parts::bom`)
|
||||
Из конструкции экспортируется BOM: детали, материалы, массы, крепёж, провода,
|
||||
компоненты платы. Допуски и реальные размеры учитываются в сцене.
|
||||
22
docs/PLUGINS.md
Normal file
22
docs/PLUGINS.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Плагины деталей
|
||||
|
||||
Деталь это данные (RON) плюс при необходимости плагин (Rust-код).
|
||||
|
||||
## Правила до версии 1.0
|
||||
- Только статическая регистрация через Rust API при сборке. Динамические библиотеки
|
||||
не поддерживаем.
|
||||
- Идентификатор `автор.имя` и версия semver. Зависимости от других плагинов и от
|
||||
версии ядра объявляются явно; несовместимость это ошибка загрузки.
|
||||
- Плагин получает доступ только к трейтам подсистем (порты: механический,
|
||||
электрический, тепловой), а не к их внутренним данным.
|
||||
- Состояние плагина сериализуется через serde и входит в подснимок; после загрузки
|
||||
снимка плагин восстанавливается из него.
|
||||
- Плагин детерминирован и подчиняется правилам DETERMINISM.md.
|
||||
|
||||
## Жизненный цикл
|
||||
`register` → `validate` (данные и версии) → `instantiate` (на сцену) → `step` (по
|
||||
периоду) → `snapshot` и `restore` → `drop`.
|
||||
|
||||
## Стабильность
|
||||
Проект публичный, но до версии 0.6.0 API плагинов может ломаться без предупреждения
|
||||
(D26). К 0.6.0 API стабилизируется и дальше подчиняется semver.
|
||||
39
docs/README.md
Normal file
39
docs/README.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
# Fabrilis — документация
|
||||
|
||||
Платформа полного проектирования механизмов: подробная физика + электроника +
|
||||
код + управление. Цель — спроектировать любую конструкцию целиком (механика,
|
||||
материалы, проводка, плата, прошивка), проверить её на сценариях работы,
|
||||
стабилизацию, отказы, нагрузки, тепло и окружение, а затем собрать в реальности.
|
||||
|
||||
Мех-паук — первый эталонный проект (`examples/`), а не часть движка: в движке
|
||||
нет кода под конкретную конструкцию.
|
||||
|
||||
| Документ | О чём |
|
||||
|---|---|
|
||||
| [ARCHITECTURE.md](ARCHITECTURE.md) | crate'ы, слои, поток данных, бюджет производительности |
|
||||
| [DECISIONS.md](DECISIONS.md) | принятые решения и открытые вопросы |
|
||||
| [MODES.md](MODES.md) | режимы Bench / Lab / World, Fidelity, время, события |
|
||||
| [UI.md](UI.md) | свой UI: модель, текст, event-driven redraw, что берём из ShapeUI |
|
||||
| [PHYSICS_SCOPE.md](PHYSICS_SCOPE.md) | механика, FEM, трение, тепло, вентиляция, проводка, виды |
|
||||
| [SCENARIOS.md](SCENARIOS.md) | сценарии, стабилизация, отказы, развёртки, метрики |
|
||||
| [ELECTRONICS.md](ELECTRONICS.md) | эмуляция CPU/SoC, аналоговая схема, мост |
|
||||
| [COUPLING.md](COUPLING.md) | связь подсистем: классы связей, события, откат шага |
|
||||
| [DETERMINISM.md](DETERMINISM.md) | уровни D1/D2/D3 и правила одинакового результата |
|
||||
| [COORDINATES.md](COORDINATES.md) | системы координат, единицы, оси |
|
||||
| [STORAGE.md](STORAGE.md) | проекты, конструкции, снимки, миры |
|
||||
| [TESTING.md](TESTING.md) | стратегия тестов |
|
||||
| [VALIDATION.md](VALIDATION.md) | verification, validation, qualification |
|
||||
| [DEPENDENCIES.md](DEPENDENCIES.md) | библиотеки: что берём, что пишем сами, сколько весят |
|
||||
| [PLUGINS.md](PLUGINS.md) | деталь как данные и плагин, правила совместимости |
|
||||
| [REFERENCES.md](REFERENCES.md) | что читать и у кого подсматривать |
|
||||
| [CODE_RULES.md](CODE_RULES.md) | проверяемые правила кода (лимиты, тесты отдельно, слои) |
|
||||
|
||||
Лицензия: [MIT](../LICENSE).
|
||||
|
||||
План работ: [../TODO.md](../TODO.md).
|
||||
|
||||
Название: Fabrilis (лат. fabrilis, «относящийся к мастеру, ремесленнику»). Автор: loki.
|
||||
|
||||
Статус: готовы M0 (скелет, правила, CI) и M1 (ядро: единицы, время, математика,
|
||||
планировщик, Fidelity, снимки). Дальше M2 — один шарнир: своя векторная
|
||||
математика, seeded RNG, минимальная физика с мотором и датчиками.
|
||||
131
docs/REFERENCES.md
Normal file
131
docs/REFERENCES.md
Normal 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/): конструкция как параметризованные данные —
|
||||
посмотреть на текстовый формат.
|
||||
30
docs/SCENARIOS.md
Normal file
30
docs/SCENARIOS.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Сценарии и анализ
|
||||
|
||||
Проектирование не заканчивается сборкой модели: нужно доказать, что она работает
|
||||
в заданных условиях. Сценарий — воспроизводимый опыт (seed + входы + скрипт).
|
||||
|
||||
## Что проверяем
|
||||
- **Рабочие сценарии**: ходьба, подъём, перенос груза, взлёт, любые задачи конструкции.
|
||||
- **Стабилизация и управление**: устойчивость контроллера (PID, свой код на МК),
|
||||
реакция на возмущения (толчок, порыв ветра, неровность), задержки и шум датчиков.
|
||||
- **Отказы (fault injection)**: обрыв провода, просадка батареи, заклинивание
|
||||
привода, перегрев, отказ датчика, сбой прошивки, поломка детали.
|
||||
- **Нагрузки и ресурс**: пики напряжений, запас прочности, усталость, температура.
|
||||
- **Окружение**: ветер, поверхность, температура воздуха, наклон.
|
||||
|
||||
## Инструменты (`analysis`, `sensors`, `scripting`)
|
||||
- **Сценарии Rhai**: подготовка сцены, подача входов и возмущений, проверки (assert),
|
||||
запись метрик.
|
||||
- **Развёртки параметров**: перебор длины, массы, коэффициентов регулятора;
|
||||
параллельный прогон на ядрах, результат не зависит от числа потоков.
|
||||
- **Monte Carlo с допусками**: разброс размеров, материалов, номиналов, шума.
|
||||
- **Метрики устойчивости**: перерегулирование, время установления, запас по углу
|
||||
опрокидывания, энергопотребление, время до отказа.
|
||||
- **Датчики** (`sensors`): IMU, энкодеры, токовые датчики; шум, смещение, задержка,
|
||||
дискретизация; управление видит мир только через них.
|
||||
- **Позже**: линеаризация и частотный отклик контуров управления, запасы по
|
||||
амплитуде и фазе.
|
||||
|
||||
## Результат
|
||||
Отчёт по сценарию: графики, метрики, пройдено или нет, ссылка на хеш конструкции и
|
||||
версию движка. Хранится как сценарий опыта (STORAGE.md).
|
||||
20
docs/STORAGE.md
Normal file
20
docs/STORAGE.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# Сохранения
|
||||
|
||||
Программа и данные разделены. Данные лежат в **папке проекта**, которую можно
|
||||
целиком положить в git. Личные настройки лежат отдельно.
|
||||
|
||||
| Что | Формат | Заметка |
|
||||
|---|---|---|
|
||||
| Библиотека (меши, материалы, детали) | файлы + RON | переиспользуется между проектами |
|
||||
| Конструкция (детали, шарниры, проводка, схемы, ссылка на прошивку) | читаемый RON | версия схемы + миграции |
|
||||
| Прошивки, образы Linux | бинарники, ссылка по хешу | blob-хранилище |
|
||||
| Мир | seed + параметры + дельта правок | остальное генерируется |
|
||||
| Снимок симуляции | бинарный, сжатый | привязан к версии движка и хешу конструкции |
|
||||
| Сценарий опыта | RON + бинарник результатов | режим, конструкция, мир, скрипт, графики |
|
||||
| Настройки, профиль устройства | XDG (`~/.config`, `~/.local/share`) | у каждого свои |
|
||||
|
||||
## Правила
|
||||
- Каждый файл несёт `format_version`; `storage::migrate` умеет переводить вперёд.
|
||||
- Снимки не гарантируют совместимость между версиями; для долгого хранения
|
||||
используем сценарий (seed + входы), он воспроизводится детерминированно.
|
||||
- Крупные бинарные файлы хранятся один раз по хешу содержимого.
|
||||
30
docs/TESTING.md
Normal file
30
docs/TESTING.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Тесты
|
||||
|
||||
Тесты лежат отдельно от кода: `tests.rs` рядом с модулем или папка `tests/` (CODE_RULES.md).
|
||||
|
||||
1. **Юнит-тесты** в каждом crate.
|
||||
2. **Валидация по аналитике** (физика должна совпадать с формулами):
|
||||
- консольная балка: прогиб `δ = PL³ / 3EI`;
|
||||
- маятник, снаряд с сопротивлением;
|
||||
- RC-цепь: экспонента заряда;
|
||||
- одномерная теплопроводность;
|
||||
- масса и инерция меша: шар, куб, цилиндр.
|
||||
3. **Property-тесты** на seeded `core::rng` — основа (инварианты массы, инерции,
|
||||
симметрия тензора). `proptest` разрешён как dev-зависимость (D26) там, где нужен
|
||||
shrinking, но не заменяет свои тесты.
|
||||
4. **Детерминизм**: golden-хеши состояния на уровнях D1/D2/D3 (DETERMINISM.md):
|
||||
своя машина, 1/2/8/24 потока, три ОС. Хеш хранится в репозитории.
|
||||
5. **RISC-V**: официальные `riscv-tests` (rv32ui/rv64ui и др.) и дифференциальное
|
||||
тестирование против QEMU или Spike на случайных программах; загрузка Linux как
|
||||
медленный интеграционный тест.
|
||||
6. **Форматы**: snapshot-тесты сцены и миграции версий; проверка меша до расчёта
|
||||
массы (замкнутость, ориентация нормалей, единицы).
|
||||
7. **Производительность**: бенчмарки горячих путей в `benches/` (`criterion` как
|
||||
dev-зависимость, D26) плюс бюджет эталонной сцены в CI; регрессия видна как
|
||||
падение RTF.
|
||||
8. **Правила репозитория**: `fabrilis-limits` (в `build.rs` каждого crate'а,
|
||||
pre-commit и CI); тесты лежат в отдельных файлах (CODE_RULES.md).
|
||||
9. **Сценарии Rhai** служат функциональными тестами («подними паука, замерь нагрузку»).
|
||||
|
||||
Verification (правильность реализации) и validation (совпадение с реальной
|
||||
сборкой) — разные вещи, см. VALIDATION.md.
|
||||
88
docs/UI.md
Normal file
88
docs/UI.md
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
# UI
|
||||
|
||||
UI Fabrilis — это редактор и отладочный оверлей внутри приложения, а не отдельный
|
||||
UI-фреймворк и не библиотека для чужих программ. Окно обычное прямоугольное,
|
||||
управление окном и вводом — на `winit` (D24), рисование — на нашем `wgpu`-рендере,
|
||||
готовые UI-библиотеки не берём (D20).
|
||||
|
||||
## Модель
|
||||
|
||||
- **Immediate-mode на старте.** UI каждый кадр строит список команд рисования
|
||||
(прямоугольник, скруглённый прямоугольник, линия, текст, картинка, клип), рендер
|
||||
батчит их. Состояние виджетов живёт в приложении, а не в дереве UI.
|
||||
- **Retained-дерево только по доказанной нужде.** Если профилирование покажет, что
|
||||
пересборка команд дорога, вводим стабильные `NodeId`, dirty-флаги и кеш ресурсов.
|
||||
Reconciliation и анимационный граф заранее не пишем.
|
||||
- **Event-driven redraw.** Нет изменений — нет кадра. Каждый кадр имеет причину
|
||||
(`Input`, `Animation`, `Resize`, `SimulationTick`, `Debug`), счётчик причин виден
|
||||
в оверлее; в простое — 0 кадров/с.
|
||||
- **Кеш ресурсов.** Пайплайны кешируются по `shader + layout + format + blend`;
|
||||
текст — через общий glyph atlas, а не текстуру на надпись. Offscreen-проходы
|
||||
только там, где эффект этого требует.
|
||||
- **Capability-модель.** Вместо `bool` — `Available | Unavailable { reason } |
|
||||
Conditional { reason }`: «нет прозрачности», «fractional scale не поддержан»,
|
||||
«эффект недоступен на этом backend'е». Не выполнять молча.
|
||||
|
||||
## Что есть в M4 и M10
|
||||
|
||||
| Этап | UI |
|
||||
|---|---|
|
||||
| M4 | оверлей отладки: FPS/RTF, число тел, причины кадров, время подсистем; прямоугольники, текст, линии, клип |
|
||||
| M10 | панели и сплиттеры, дерево конструкции, таблица свойств, графики, 3D-вид, диалоги, текстовые поля |
|
||||
|
||||
Виджеты вводятся по одному и только под конкретную задачу редактора. Зоопарк
|
||||
«на будущее» запрещён (KISS).
|
||||
|
||||
## Текст
|
||||
|
||||
- Сейчас: `fontdue` только растеризует глифы, раскладку строк и переносы делаем сами.
|
||||
Для латиницы и кириллицы этого достаточно.
|
||||
- Текстовые поля требуют shaping и IME. Решение отложено до M10: кандидаты —
|
||||
`cosmic-text` или `Parley` (+ `glyphon` для wgpu). Берём только когда появляется
|
||||
настоящее поле ввода, с записью в DECISIONS.md.
|
||||
- Курсор, выделение, копирование и IME не эмулируем частично: либо полноценно, либо
|
||||
поле ввода не выпускаем.
|
||||
|
||||
## Что взято из ShapeUI blueprint
|
||||
|
||||
Локальная копия: `ref/shapeui-blueprint_v0.2_revised_ru.md` (в git не входит).
|
||||
Из него берём идеи, не архитектуру:
|
||||
|
||||
- event-driven redraw и счётчик причины кадра;
|
||||
- render command list и батчинг вместо draw call на виджет;
|
||||
- общий glyph atlas;
|
||||
- раздельные dirty-флаги (стиль, layout, текст, геометрия);
|
||||
- capability-модель вместо обещаний `bool`;
|
||||
- оверлей диагностики: PSS/RSS, draw calls, offscreen passes, кеши, причина кадра;
|
||||
- дисциплину «сначала панели/текст/ввод, потом виджеты».
|
||||
|
||||
## Что из ShapeUI не берём
|
||||
|
||||
- Окна произвольной формы, click-through, `wl_region`, `set_input_region`: у нас
|
||||
обычное окно, этим занимается `winit`.
|
||||
- Свой Wayland-backend и raw `wl_surface`: дублирует `winit`.
|
||||
- CPU-рендерер, Vello, несколько backend'ов, morphing, shader marketplace.
|
||||
- Собственный scene graph с реконсиляцией до доказанной необходимости.
|
||||
- Доступность (AccessKit) с первого дня; вернёмся к ней перед публичным релизом.
|
||||
|
||||
## Диагностика
|
||||
|
||||
Оверлей показывает то, что можно проверить:
|
||||
|
||||
```
|
||||
PSS / RSS 38.4 / 51.1 MiB (estimated)
|
||||
draw calls 6
|
||||
offscreen 1
|
||||
pipelines 5
|
||||
glyph atlas 2.1 MiB
|
||||
frames last 10s 0
|
||||
last frame Idle
|
||||
```
|
||||
|
||||
Числа не выдаются за «всю VRAM процесса»; приблизительные помечаются `estimated`.
|
||||
|
||||
## Открыто
|
||||
|
||||
- Shaping и IME для текстовых полей: `cosmic-text` или `Parley`, решаем на M10.
|
||||
- Нужен ли retained-слой: решаем по профилировке M10, не заранее.
|
||||
- Графики: своя простая отрисовка линий и областей; библиотеку не берём.
|
||||
47
docs/VALIDATION.md
Normal file
47
docs/VALIDATION.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
# Проверка достоверности
|
||||
|
||||
Результат, который красиво выглядит, не обязательно верен. Здесь три разных вопроса.
|
||||
|
||||
| Понятие | Вопрос | Чем отвечаем |
|
||||
|---|---|---|
|
||||
| Verification | правильно ли реализованы алгоритмы | аналитические задачи, golden-хеши, дифференциальные тесты CPU |
|
||||
| Validation | описывает ли модель реальный механизм | сравнение с измерениями реальной сборки |
|
||||
| Qualification | достаточно ли проверена модель для конкретного применения | область применимости каждой модели, записанная в её описании |
|
||||
|
||||
## Verification
|
||||
Консольная балка, маятник, RC-цепь, теплопроводность, масса и инерция простых тел
|
||||
(TESTING.md). Для CPU: `riscv-tests` и сравнение со Spike или QEMU. Для детерминизма:
|
||||
golden-хеши (DETERMINISM.md).
|
||||
|
||||
## Validation и калибровка
|
||||
1. Собрать реальный механизм или узел.
|
||||
2. Измерить массу, момент инерции, токи, напряжения, температуры, траектории.
|
||||
3. Прогнать то же самое в Fabrilis.
|
||||
4. Сравнить и записать расхождения.
|
||||
5. Подправить параметры модели (трение, КПД, сопротивления) и записать допуски.
|
||||
|
||||
Калибровка не заменяет Monte Carlo: Monte Carlo показывает разброс, а калибровка
|
||||
находит систематическое смещение.
|
||||
|
||||
## Неопределённость
|
||||
Допуски размеров, материалов, номиналов, шумов датчиков. Результат несёт оценку
|
||||
чувствительности к параметрам и оценку доверия, а не только число.
|
||||
|
||||
## Диагностика достоверности
|
||||
Движок сообщает, когда результату нельзя верить:
|
||||
- решатель не сошёлся;
|
||||
- меш не замкнут или не ориентирован;
|
||||
- модель работает вне области применимости (скорость, температура, деформация);
|
||||
- шаг был уменьшен откатом;
|
||||
- эффективный шаг больше допустимого.
|
||||
|
||||
Диагностика попадает в отчёт сценария, а не только в лог.
|
||||
|
||||
## Проверка меша перед расчётом массы
|
||||
Каждое ребро принадлежит двум треугольникам, ориентация согласована, вырожденных
|
||||
треугольников нет, объём положителен. Единицы заданы явно (COORDINATES.md). Иначе
|
||||
импорт возвращает ошибку: масса по теореме Гаусса на дырявой сетке бессмысленна.
|
||||
|
||||
## Версионирование
|
||||
Сценарий хранит хеш конструкции, версию движка и версии моделей. Результаты с
|
||||
несовпадающими версиями помечаются как несравнимые.
|
||||
Loading…
Add table
Add a link
Reference in a new issue