Кампанії

Один сценарій відповідає на одне запитання про одну ситуацію. Місія — це послідовність ситуацій, а дослідження проєкту — їхня родина. Вид сценарію campaign компонує наявні види в один прогін, не реалізуючи жодного з них наново: кожен учасник — це звичайна таблиця сценарію з власним kind, що диспетчеризується через api::run_toml саме так, як її запустив би kshana <file>.toml, а кампанія лише зчитує числа з документів результатів.

Кампанія — MODELLED. Її тотожності композиції перевіряються (нижче), але зчеплення фаз — вибір моделювання, і кожна фаза настільки добра, наскільки добрий вид, що її запустив.

Запустіть її, як будь-який інший сценарій:

kshana scenarios/campaign-jam-spoof-holdover-integrity.toml
# writes .result.json, .chart.svg, .report.html and .report.json next to the file

Кампанія може містити будь-яку комбінацію чотирьох розділів; та, що не має жодного, запускається, а її підсумок повідомляє, що вона нічого не скомпонувала.

`[[phases]]`: зчеплена місія на одній часовій шкалі#

Кожна фаза запускає один або кілька сценаріїв у вікні спільної часової шкали місії, наприклад годинник у holdover та інерціальну навігаційну систему (INS), що одночасно рухається за інерцією. Виходи кожного прогону зчитуються в іменовані канали, розміщуються на час початку фази й передискретизуються на спільну сітку ([timeline] step_s) утриманням нульового порядку: час сітки бере останній відлік прогону відповідної фази, що не пізніший за нього, і дорівнює null там, де жоден прогін цієї фази не надає каналу.

Канал	Одиниця	Що це	Джерело пресета
`time_error_ns`	нс	похибка часу годинника	`clock`: `<side>.series[].error_ns`; `spoof`: `<side>.series[].offset_ns`
`guard_ns`	нс	запобіжник похибки часу	власний `threshold_ns` прогону
`cn0_dbhz`	dB-Hz	середнє ефективне відношення несівної до густини шуму (C/N0) за видимими супутниками	`jamming`: середнє від `epochs[].sats[].cn0_effective_dbhz`
`cn0_floor_dbhz`	dB-Hz	поріг втрати відстеження	`jamming`: `tracking_threshold_dbhz` сценарію, якщо він його задає
`tracking`	кількість	супутники, що ще відстежуються	`jamming`: `epochs[].tracking`
`protection_level_m`	m	вертикальний рівень захисту	`integrity`: `epochs[].vpl_m`
`alert_limit_m`	m	вертикальна межа тривоги	`integrity`: `al_v_m`
`position_error_m`	m	похибка положення	`gnss-ins`: `<side>.series[].error_m`
`position_threshold_m`	m	поріг похибки положення	`gnss-ins`: `threshold_m`
`alarm`	1	1, поки спрацьовує будь-який монітор фази	див. нижче

<side> — це classical, якщо прогін не задає side = "quantum". Будь-яка інша величина зчитується явним записом [[phases.runs.series]]: часовий шлях з одним [], що називає рядки (epochs[].t), шлях значення, що ділить ті самі рядки, або скаляр, розповсюджений на кожен рядок (префікс input: зчитує сценарій прогону, а не його результат), необов'язкове згортання (mean, min, max, count) для кількох значень під одним рядком, масштаб і одиниця для каналу, якого кампанія не знає.

Тривоги надходять із трьох джерел, що поєднуються логічним АБО в межах фази:

прапорці пресета, зчитані з прогону: jamming сигналізує, поки відстежується менше чотирьох супутників (власне визначення доступності); integrity сигналізує на епохах, які позначає як недоступні;
правила пресета на каналах фази, що обчислюються після carry: clock сигналізує, поки абсолютна похибка часу перевищує guard_ns; gnss-ins — поки похибка положення перевищує position_threshold_m; явні правила розміщуються в [[phases.runs.alarms]];
події-тривоги: spoof породжує одну на detect_time_s свого монітора з допомогою годинника; spoof-detect породжує одну на початку фази, коли його злите рішення сигналізує.

Стан передається далі між фазами трьома явними способами:

carry = ["time_error_ns"] додає значення каналу на кінець попередньої фази до значень цього каналу в цій фазі. Фаза годинника, яку зсунув спуфер, — це місце, звідки починається holdover. Додавання зсуву точне для фази годинника, що інтегрує частоту; для похибки положення воно припускає, що дві похибки колінеарні, — песимістичний випадок.
[[phases.handoff]] записує число з попередньої фази (channel:<name> для кінцевого значення каналу або будь-який шлях результату попереднього прогону) у ключ із крапками сценарію цієї фази перед його запуском, з необов'язковими масштабом і зсувом.
end_at = "<result path>" завершує фазу в момент, обчислений прогоном, з обмеженням duration_s. Вбудована місія завершує свою фазу спуфінгу на classical.detect_time_s.

skip_s відкидає перші секунди власної часової шкали прогону (прогрів) до нульового часу фази.

Вбудована місія#

scenarios/campaign-jam-spoof-holdover-integrity.toml запускає 18 сценаріїв-учасників у шести фазах на сітці 10 с:

Фаза	Прогони	Що показує часова шкала
номінально, 600 с	`clock`, `jamming` (без глушника), `integrity`	похибка часу 0 нс; C/N0 43,0 dB-Hz проти порогу 25 dB-Hz; вертикальний рівень захисту від 9,1 до 21,6 м проти межі тривоги 50 м
глушіння, 600 с	те саме, глушник на -30 dBW, 1 км	C/N0 падає до 27,7 dB-Hz, усі 8 супутників досі відстежуються
спуфінг, завершений на 370 с за допомогою `end_at`	`spoof` (лінійний дрейф часу 0,1 нс/с), `spoof-detect`, `jamming`	похибка часу зростає до 36 нс; радіочастотний детектор сигналізує на початку фази, монітор з допомогою годинника — на 370 с
holdover, 1800 с	`clock` (відмовлений, переносить 37,0 нс), `gnss-ins` (тактичний блок, що рухається за інерцією), `jamming` на 10 dBW	втрачено всі супутники (C/N0 приблизно -12 dB-Hz); похибка часу від 36,4 до 62,7 нс проти запобіжника 50 нс; похибка положення до 24 км
integrity-alarm, 600 с	`clock` (переносить 59,6 нс), `jamming` і `integrity` з маскою 25 град	відстежується 5 супутників; рівень захисту від 19 до 135 м, відсутній у 18 із 60 моментів сітки; перенесена похибка часу, від 52,1 до 61,7 нс, лишається вище запобіжника 50 нс, тож тривога триває протягом усієї фази
відновлення, 600 с	`clock`, `jamming` (без глушника), `integrity`	похибка часу повернулася до 0 нс; тривога вщухла

Прогони цілісності використовують власну трасу користувача з прикладу integrity (кругова траса на висоті 0,4 км), а не фіксований пункт приймача глушіння, а маска 25 град заступає частково відкрите небо приймача, що повторно захоплює сигнал. Це вибори сценарію, зазначені у файлі.

Місія, керована спектром L-діапазону#

scenarios/campaign-spectrum-holdover-integrity.toml запускає 8 сценаріїв-учасників у трьох фазах на сітці 1 с, причому C/N0 для GPS L1 C/A і Galileo E1 зчитується з виду spectrum (див. SPECTRUM.md), а не з таблиці за супутниками виду jamming. Глушники — ті, що в scenarios/l-band-waterfall-jamming.toml.

Фаза	Прогони	Що показує часова шкала
початок, завершений на 10 с за допомогою `end_at`	`clock`, `spectrum` (чирп від 10 с), `integrity`	L1 C/A 43,48 і E1 44,73 dB-Hz; фаза завершується на першій втраті L1 C/A у власному прогоні спектра (`timeline.bands[0].first_loss_t_s`); рівень захисту 21,6 м проти 50 м
holdover, 600 с	`clock` (відмовлений, переносить похибку початку, тут 0 нс), `spectrum` (чирп увімкнено)	L1 C/A 3,38 і E1 4,44 dB-Hz, обидва нижче порогу 25 dB-Hz; похибка часу від -0.07 до 5,06 нс проти запобіжника 50 нс; тривога триває
galileo-fallback, 300 с	`clock` (повторно синхронізований), `spectrum` (тон CW на несівній L1), `integrity` на Walker 24/3/1 типу Galileo	L1 C/A утримується на 17,98 dB-Hz, E1 повернувся до 44,73 dB-Hz; рівень захисту від 6,1 до 17,7 м; тривога вщухла

Відновлення E1 під тоном CW ґрунтується на обробці безперервного спектра у виді «спектр»: тон потрапляє в нуль спектра MBOC і нічого не зв'язує. Реальний тон зв'язувався б через спектральні лінії коду; це зазначено у файлі та в SPECTRUM.md.

`[sweep]`: сітка параметрів для будь-якого виду#

Від одного до трьох ключів сценарію з крапками, кожен у лінійному або логарифмічному діапазоні, на тих самих значеннях осі, що й вид sweep-nd. Кожна вісь має назву й одиницю; кожна метрика має назву та шлях результату, а її одиницю зчитано з власного блоку одиниць досліджуваного виду, якщо кампанія не оголошує іншу. За runs > 1 кожен вузол — це засіяний ансамбль Монте-Карло (реалізація k на зерні вузла плюс k), який подається зі статистикою нижче. scenarios/campaign-sweep-jammer-power.toml перебирає глушник на 1 км від приймача від -50 до +10 dBW: середнє відношення глушника до сигналу змінюється рівно на 1 dB на dB (від 12,2 до 72,2 dB), а доступність падає від 1 до 0 між -30 і -25 dBW.

Ключ із крапками може індексувати масив таблиць за позицією: system.2.sisre_m — це sisre_m третьої таблиці [[system]], а case.0.system.0.shell.0.altitude_km сягає на три рівні вглиб.

`[monte_carlo]`: засіяний ансамбль#

Реалізація k запускає сценарій із ключем зерна, встановленим у base_seed + k, за конвенцією, яку вже використовує ансамбль годинників, тож ансамбль відтворюється точно. Кожна метрика повідомляє середнє, популяційне стандартне відхилення, перцентилі 5, 50 і 95 за методом найближчого рангу, 95-відсотковий довірчий інтервал для середнього, побудований перцентильним бутстрепом із фіксованим зерном (2000 перевибірок), і, типово, кожен відлік у порядку зерен. Шляхи результатів можуть індексувати масиви: classical.series[-1].error_ns — це останній відлік.

`[compose]`: кілька сценаріїв за спільних умов#

Іменовані спільні значення (число або масив чисел, з одиницею) записуються в кожного учасника за ключами, до яких він їх прив'язує, тож учасники не можуть розходитися щодо спільної умови. Кожен учасник запускається, а для кожної метрики зведений підсумок дає найменше, найбільше та середнє значення серед учасників із зазначенням найкращого й найгіршого. scenarios/campaign-shared-jammer-sea-road.toml ставить один глушник на 8 dBW між судном у Фінській затоці (приблизно 30 км) і автомобілем на прибережній дорозі Гельсінкі (приблизно 50 км): судно втрачає кожен супутник (середнє відношення глушника до сигналу 39,0 dB), тоді як автомобіль зберігає щонайменше чотири (34,6 dB).

`[optimize]`: найкраще значення однієї метрики#

Від одного до трьох ключів сценарію з крапками, кожен обмежений до [lo, hi] на шкалі lin або log, шукаються за найкращим значенням однієї метрики (goal = "minimize", "maximize" або "target", що мінімізує відстань від target).

Є два методи:

method = "grid" запускає кожен вузол сітки з steps на ключ, за значеннями осей перебору.
method = "nelder-mead" (типовий) запускає детермінований симплекс Нелдера–Міда в координатах, нормованих до [0, 1] на ключ. Пробні точки проєктуються на коробку. Розділ приймає max_evals, початковий step і допуски зупинки ftol та xtol.

Прогін, чия метрика відсутня або нескінченна, оцінюється найгірше і зберігається в трасі. За runs > 1 метрика — це середнє за тими самими зернами на кожному обчисленні. Результат містить best_coords, best_metric, best_score, evals, stop_reason і кожне обчислення в trace.

scenarios/campaign-optimize-link-budget.toml шукає дальність і швидкість передавання даних для запасу лінії зв'язку 3 dB. Оптимум є локальним щодо коробки та початку. Він MODELLED і ніколи не є глобальним твердженням.

Протокол і його попередньо зареєстровані пороги — у docs/design/evidence/cap32-optimize/. Тест — tests/campaign_optimize_reference.rs. Результати:

розв'язання цілі 1-D збігається із замкненою формою з точністю 6e-15;
метод сітки збігається побітово з незалежним циклом повного перебору;
симплекс працює щонайменше не гірше за сітку 41 × 41 приблизно за десяту частину її прогонів.

Поріг 1-D раунду 1 зафіксовано як NOT MET: попередньо зареєстрована коробка виключала розв'язок.

Відтворюваність#

Кожен результат кампанії містить scenario_hash, SHA-256 (Secure Hash Algorithm 2, 256-бітовий дайджест) канонічної форми JavaScript Object Notation (JSON) документа кампанії (порядок ключів і форматування на нього не впливають), і блок reproducibility із кількістю прогонів учасників та run_digest — SHA-256 за дайджестами результатів усіх учасників у порядку диспетчеризації. Два прогони з однаковим дайджестом дали побайтово ідентичні результати учасників. Кожен прогін фази також записує свій вид, власний scenario_hash, якщо в виду він є, і SHA-256 документа свого результату. Кожне число в документі має запис одиниць.

Ядро послідовне й не читає файлів, тож кампанія запускається без змін у збірці WebAssembly. Кампанії не можуть містити кампанії.

Експорт#

--export для кампанії записує кожного учасника-сценарій, що має геометрію, як власний набір файлів, з міткою учасника перед суфіксом формату: кожен прогін фази (<phase>, або <phase>-<k>, коли фаза має кілька прогонів), базовий сценарій перебору (sweep), сценарій Монте-Карло (monte-carlo) і кожен складений учасник (власна мітка, із записаними спільними значеннями, які він прив'язує). Учасник, ідентичний попередньому, записується один раз; передачі між фазами та значення перебору чи зерна, застосовані під час виконання, в експортованих сценаріях відсутні.

kshana scenarios/campaign-shared-jammer-sea-road.toml --export kml
# after the usual result, chart and report files:
# wrote scenarios/campaign-shared-jammer-sea-road.ship-strait.kml
# wrote scenarios/campaign-shared-jammer-sea-road.car-coast-road.kml

Формат, який не може описати жоден з учасників, відхиляється з указанням цієї причини. Таблицю для кожного сценарію наведено в INTEROP.md.