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

46
docs/COUPLING.md Normal file
View 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 (электроника): сильные связи и откат шага.
## Открыто
Выбор коэффициента релаксации и предельного числа делений шага.