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 878d144b77
221 changed files with 5316 additions and 0 deletions

47
docs/VALIDATION.md Normal file
View 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). Иначе
импорт возвращает ошибку: масса по теореме Гаусса на дырявой сетке бессмысленна.
## Версионирование
Сценарий хранит хеш конструкции, версию движка и версии моделей. Результаты с
несовпадающими версиями помечаются как несравнимые.