# Пошаговое руководство по курсу > **Для кого:** инженеры, которым нужны физически-вдохновлённые примитивы — консенсус, маршрутизация, выборка, риск, термодинамика — в виде готовых к вызову оракулов AIMarket. > **Язык лаб:** `COURSE_LANG=en|ru|es|fr|zh` · строки UI в `i18n/` · этот гайд на русском. > [English](step-by-step.md) · [Español](step-by-step.es.md) · [Français](step-by-step.fr.md) · [中文](step-by-step.zh.md) --- ## Сверка с текущей экосистемой Перед живым вызовом используйте [поиск Hub](https://modelmarket.dev/ai-market/v2/search?intent=murmuration&limit=6) и проверьте идентификатор возможности, источник и заявленную цену. Сохраните точный вход воспроизводимой лабораторной. Разделяйте результат математической проверки алгоритма и подписанную квитанцию, если её выдал живой вызов. Пустой поиск означает, что по этому запросу на момент проверки не нашлось совпадений. --- ## Зачем этот курс Большинство «AI»-курсов заканчиваются на промптах. Здесь же учат **детерминированным, физически-вдохновлённым вычислениям**, которые можно проверить, сертифицировать и тарифицировать — примитивам, что лежат *под* агентом, а не над ним. Каждый модуль оборачивает реальный оракул AIMarket: - **Murmuration** — робастный роевой консенсус, устойчивый к выбросам. - **Colony** — маршруты TSP с *допустимым сертификатом зазора оптимальности*. - **Turing** — синий шум для равномерных, но нерегулярных множеств точек. - **Ablation** — системный риск как каскад в самоорганизованно-критической песочной модели. - **Landauer** — термодинамический порог (kT·ln2) энергозатрат необратимых вычислений. Каждая лаба **воспроизводима** (фиксированный seed, без LLM по умолчанию) и печатает блок `Trace`, который можно изучить. К концу вы сможете вызвать любой из пяти оракулов, прочитать вывод и получить сертификат курса. --- ## Содержание 1. [Выбор трека](#выбор-трека) 2. [Установка (10 минут)](#установка-10-минут) 3. [M1 — Консенсус Murmuration](#m1--консенсус-murmuration) 4. [M2 — Сертификат TSP для Colony](#m2--сертификат-tsp-для-colony) 5. [M3 — Синий шум Turing](#m3--синий-шум-turing) 6. [M4 — Каскадный риск Ablation](#m4--каскадный-риск-ablation) 7. [M5 — Термодинамический аудит Landauer (продвинутый)](#m5--термодинамический-аудит-landauer-продвинутый) 8. [Трейс в каждой лабе](#трейс-в-каждой-лабе) 9. [Упражнения и сертификат](#упражнения-и-сертификат) 10. [Мост: от курса к AIMarket](#мост-от-курса-к-aimarket) 11. [Чеклист самопроверки](#чеклист-самопроверки) 12. [Типичные проблемы](#типичные-проблемы) --- ## Выбор трека | Трек | Модули | Время | NumPy | LLM | |------|--------|-------|-------|-----| | **Базовый** | M1 → M2 → M3 → M4 | ~2 ч | Да (`[oracles]`) | Нет | | **Продвинутый** | Базовый + M5 | +45 мин | Да | Нет | Все лабы детерминированы — в курсе **нет LLM**. «Интеллект» — в физике: робастная статистика, комбинаторные границы, критичность, термодинамика. После каждой лабы читайте раздел [Трейс](#трейс-в-каждой-лабе) — каждый скрипт печатает блок `Trace`. --- ## Установка (10 минут) ### Шаг 1 — Клон и установка ```bash git clone https://github.com/alexar76/aimarket-courses.git cd aimarket-courses/physics-inspired-computing-course pip install -e ".[oracles,dev]" ``` Extra `[oracles]` тянет **NumPy** (единственная зависимость времени выполнения); `[dev]` добавляет pytest. Требуется Python **3.11+**. > **Внутри монорепозитория aicom?** Колёса оракулов можно не ставить — лабы находят `murmuration`, `colony`, `turing`, `ablation` и `landauer` напрямую из `oracles/oracles/*` через `courselib/oracle_paths.py`. Вне монорепозитория именно `[oracles]` заставляет импорты работать. ### Шаг 2 — Тесты ```bash pytest -q ``` **Ожидается:** все тесты проходят (паритет i18n по `en/ru/es/fr/zh`, мосты к оракулам, сертификат, упражнения). ### Шаг 3 — Язык интерфейса лаб (опционально) ```bash export COURSE_LANG=ru # или es, по умолчанию en python labs/lab01_murmuration_consensus.py ``` `COURSE_LANG` переключает печатаемые строки каждой лабы (заголовки, концепции, метки) через `courselib/i18n.py`. Числа, имена оракулов и виды событий трейса не меняются — локализуется только текст. Неизвестные значения откатываются к английскому и не роняют лабу. ### Шаг 4 — Google Colab 1. Откройте [сайт курса](https://alexar76.github.io/aimarket-courses/physics-inspired-computing-course/) → **Open in Colab** на любой лабе. 2. Выполните setup-ячейку (clone + `pip install -e ".[oracles,dev]"`). 3. При необходимости задайте `os.environ["COURSE_LANG"] = "ru"` в setup-ячейке. 4. Запустите ячейку лабы. --- ## M1 — Консенсус Murmuration **Концепция:** робастный консенсус DeGroot и агрегация Tukey-biweight по зашумлённым оценкам агентов. **Лаба:** `labs/lab01_murmuration_consensus.py` · **Оракул:** Murmuration · **~15 мин** · **трек:** базовый ### Шаги 1. Прочитайте docstring в начале файла лабы (отрасли: *роевой интеллект, робастная статистика*). 2. Запустите: `python labs/lab01_murmuration_consensus.py` 3. Лаба подаёт шесть оценок — пять около `2.0` плюс один дикий выброс `50.0` — и печатает `median`, `trimmed_mean`, `biweight`, сошедшееся значение `converged` и число итераций DeGroot, а в конце — блок `Trace`. 4. Заметьте: `biweight` ≈ 2.0, хотя обычное среднее было бы ~10 — выброс **подавлен**, а не усреднён. 5. Просмотрите `courselib/physics.py::murmuration_aggregate` и `murmuration.consensus.aggregate`. ### Что это доказывает Один плохой датчик (или вредоносный агент) не сдвигает консенсус. Оценка biweight занижает вес далёких точек, и рой сходится к истине, а не к шуму. ### Самопроверка - [ ] Объясняете, почему `biweight` < среднего для этого входа - [ ] Понимаете, зачем лаба детерминирована (без LLM, фиксированные данные) --- ## M2 — Сертификат TSP для Colony **Концепция:** маршрут «ближайший сосед» + 2-opt с **допустимой границей зазора оптимальности**. **Лаба:** `labs/lab02_colony_tsp.py` · **Оракул:** Colony · **~20 мин** · нужен M1 ### Шаги 1. Запустите: `python labs/lab02_colony_tsp.py` 2. Лаба решает маршрут на 6 городов и печатает `tour` (порядок обхода), `length`, `lower_bound` (доказуемый нижний предел оптимальной длины) и `gap` в процентах — насколько маршрут *может* быть хуже оптимума. 3. Прочитайте блок `Trace` — событие `tsp` логирует `length` и `gap`. 4. Ключевая идея: всегда `length ≥ lower_bound`, поэтому `gap` — это **сертификат**. Вы поставляете маршрут *вместе* с гарантией качества. ### Что это доказывает Чтобы действовать, точный оптимум не нужен — малый `gap` (скажем, < 5%) часто и есть достаточно хороший ответ с приложенным числом. Так эвристики становятся подотчётными. ### Самопроверка - [ ] По `gap` говорите: «этот маршрут не более чем на X% хуже оптимума» - [ ] Понимаете, почему `length` никогда не ниже `lower_bound` --- ## M3 — Синий шум Turing **Концепция:** выборка по лучшему кандидату (Mitchell) для равномерных, но нерегулярных множеств точек. **Лаба:** `labs/lab03_turing_bluenoise.py` · **Оракул:** Turing · **~20 мин** · нужен M1 ### Шаги 1. Запустите: `python labs/lab03_turing_bluenoise.py` 2. Лаба запрашивает 64 точки (`candidates=12`, `seed=2026`) и печатает `count`, `min_distance` (минимальный зазор между любыми двумя точками), `seed` и его `seed_source`, а также `sample` из 3 координат. 3. Сравните со случайным равномерным разбросом: синий шум **максимизирует минимальное расстояние**, поэтому нет ни сгустков, ни пустот. 4. Перезапустите с другим `seed` (правкой лабы) — раскладка меняется, но `min_distance` остаётся высоким. ### Что это доказывает Синий шум превосходит наивную случайную выборку для Monte Carlo, дизеринга и процедурного размещения: равномерное покрытие без видимой структуры. ### Самопроверка - [ ] Объясняете, почему цель — высокий `min_distance` - [ ] Видите, что `seed` делает выборку воспроизводимой --- ## M4 — Каскадный риск Ablation **Концепция:** абелева песочная модель самоорганизованной критичности — степенное распределение размеров лавин и хвостовой риск. **Лаба:** `labs/lab04_ablation_cascade.py` · **Оракул:** Ablation · **~20 мин** · нужен M1 ### Шаги 1. Запустите: `python labs/lab04_ablation_cascade.py` 2. Лаба строит небольшой направленный **граф подверженности** (`demo_exposure_graph()` — банки A→D плюс сток), сбрасывает 1200 зёрен и печатает `tau` (степенной показатель распределения размеров лавин), `max_avalanche` (крупнейший наблюдённый каскад), `cvar95` (95% условный VaR — ожидаемый размер худших 5% каскадов) и `topple_total`. 3. Прочитайте блок `Trace` — событие `cascade` логирует `tau` и `max_avalanche`. 4. Интуиция: в критической системе малые возмущения иногда запускают **общесистемные** каскады. `tau` и `cvar95` количественно описывают этот хвост. ### Что это доказывает Среднее поведение скрывает опасность. Тяжёлый хвост (управляемый `tau`) означает, что редкие, но огромные каскады доминируют в риске — это и есть режим отказа взаимосвязанных финансовых или инфраструктурных сетей. ### Самопроверка - [ ] Объясняете, почему *средний* размер лавины занижает риск - [ ] Знаете, что измеряет `cvar95` против простого среднего --- ## M5 — Термодинамический аудит Landauer (продвинутый) **Концепция:** энергетический порог стирания бита kT·ln2 на DAG операций. **Лаба:** `labs/lab05_landauer_audit.py` · **Оракул:** Landauer · **~30 мин** · **трек:** продвинутый ### Шаги 1. Запустите: `python labs/lab05_landauer_audit.py` 2. Лаба проверяет небольшую необратимую схему (`demo_circuit_ops()` — два входа, гейт AND, выход) при `temperature_k=300.0` и печатает `irreversible_bits` (биты, уничтоженные логикой), `energy_floor_j` (порог Ландауэра в джоулях, kT·ln2 на стёртый бит), `efficiency` и `circuit_commitment` — хеш, фиксирующий проверяемую схему. 3. Прочитайте блок `Trace` — событие `landauer` логирует `bits` и `floor_j`. 4. Физика: стирание одного бита при температуре T стоит **не менее** kT·ln2 джоулей. Гейт AND уничтожает информацию (два входа → один выход), поэтому его порог ненулевой. ### Что это доказывает Существует жёсткий, зависящий от температуры нижний предел энергии, которую любое необратимое вычисление обязано рассеять. Аудит превращает этот физический закон в число, привязываемое к схеме, а `circuit_commitment` делает аудит защищённым от подделки. ### Самопроверка - [ ] Называете порог kT·ln2 и смысл каждого члена - [ ] Понимаете, почему у гейта AND `irreversible_bits ≥ 1` --- ## Трейс в каждой лабе **Концепция:** каждая лаба логирует `Trace`, чтобы её поведение можно было изучить, а не принимать как магию. **Где:** во всех пяти лабах · **~5 мин после каждой лабы** Каждый скрипт строит `courselib.trace.Trace` и вызывает `trace.log(kind, **fields)`. Лаба печатает число записанных `events`; `kind` (`consensus`, `tsp`, `bluenoise`, `cascade`, `landauer`) указывает, какой физический примитив сработал, а поля фиксируют ключевые числа. ### Шаги (после каждой лабы) 1. Прокрутите к строке `trace` / `events` в конце вывода. 2. Сопоставьте `kind` и поля с только что прочитанным блоком результата. 3. Воспринимайте трейс как «лог юнит-теста» лабы — в production это становится чеками тарификации и записями аудита. ### Самопроверка - [ ] Сопоставляете каждое событие трейса с напечатанным результатом - [ ] Видите трейс как мост от вывода лабы к проверяемому чеку --- ## Упражнения и сертификат После лаб запустите DIY-проверки: ```bash python labs/run_exercises.py ``` Это прогоняет упражнения всех пяти модулей (`m1`–`m5`) и печатает `✓`/`✗` по каждому. Во время итераций запускайте по одному: ```bash python labs/run_exercises.py --module m4 ``` Каждое упражнение утверждает свойство, которому учит лаба — например, `m1` проверяет, что `biweight` устойчив к выбросу, `m2` — что `length ≥ lower_bound`, `m4` — что `tau > 0.5`. Когда все пять пройдены, получите сертификат: ```bash python labs/run_exercises.py --certificate "Иван Петров" --lang ru ``` Создаётся `certificate.html` (используйте `--lang en` или `--lang es` для другой локали). Откройте его в браузере и **Print → Save as PDF**. ID сертификата — это хеш имени и даты, поэтому он стабилен и проверяем. Флаг `--skip-check` передавайте, только если нужен HTML без повторного прогона упражнений. --- ## Мост: от курса к AIMarket Пять оракулов, которые вы вызывали локально, — это те же пакеты, что live-обслуживаются в экосистеме AIMarket. Чтобы перейти от «я запустил лабу» к «я вызвал размещённый оракул»: | Курс (локальная лаба) | AIMarket (размещённый оракул) | |-----------------------|-------------------------------| | M1 `murmuration_aggregate` | Оракул Murmuration — capability консенсуса | | M2 `colony_tsp` | Оракул Colony — маршрутизация + сертификат | | M3 `turing_bluenoise` | Оракул Turing — capability выборки | | M4 `ablation_cascade` | Оракул Ablation — capability системного риска | | M5 `landauer_audit` | Оракул Landauer — термодинамический аудит | | Лаба `Trace` | Чек invoke + provenance на хосте | `circuit_commitment` (M5) и сертификат `gap` (M2) — это ровно тот проверяемый вывод, что позволяет покупателю доверять ответу оракула, не пересчитывая его. --- ## Чеклист самопроверки После **базового** трека вы должны уметь: - [ ] Запускать lab01–lab04 локально и в Colab - [ ] Объяснить робастный консенсус (M1) и почему выброс подавлен - [ ] Читать сертификат `gap` для TSP (M2) как гарантию качества - [ ] Сказать, почему синий шум (M3) лучше равномерного случайного покрытия - [ ] Описать, что `tau`/`cvar95` говорят о каскадном риске (M4) - [ ] Прочитать блок `Trace` и сопоставить каждое событие с результатом После **продвинутого** трека добавьте: - [ ] Запустить lab05 и сформулировать порог kT·ln2 словами - [ ] Пройти все пять упражнений и получить сертификат --- ## Типичные проблемы | Проблема | Решение | |----------|---------| | `ModuleNotFoundError: courselib` | Запуск из корня репозитория; лабы добавляют родительскую папку в `sys.path` | | `ImportError: Oracle package '…' not installed` | Выполните `pip install -e ".[oracles]"` или запускайте из монорепозитория aicom, где находится `oracles/oracles/*` | | `ModuleNotFoundError: numpy` | Extra `[oracles]` ставит NumPy — повторите `pip install -e ".[oracles,dev]"` | | Ошибка версии Python | Курсу нужен **Python 3.11+** | | Пустые / английские строки при другом языке | Задайте `COURSE_LANG`; проверьте ключ в `i18n/ru.json` / `i18n/es.json` | | Падение паритета i18n в pytest | Добавьте недостающий ключ во **все три** файла `i18n/en.json`, `ru.json`, `es.json` | | Сертификат не создаётся | Сначала должны пройти упражнения; запустите `python labs/run_exercises.py` или передайте `--skip-check` | | Colab выполняет старый код | Перезапустите setup-ячейку; зафиксируйте ветку `main` | --- ## Обновление сайта и ноутбуков После правок лаб или `i18n/`: ```bash python3 scripts/build_course_assets.py ``` Гайды в `docs/` правятся вручную — сначала EN, затем зеркала RU/ES.