Theoretically informed deep learning model complexity estimation — библиотека и экспериментальный стенд для сопоставимой оценки сложности моделей глубокого обучения.

Документация проекта содержит установку, архитектуру, методы, демонстрации, протокол экспериментов и автоматически собираемый API. Руководство prequential coding подробно разбирает blockwise, online/replay и калибровку. Документация пользователя сохраняет быстрый старт и выбор методов. В руководстве разобраны вызовы, формулы и ограничения, в справочнике API — публичные сигнатуры и параметры. Карта исходников описывает модули и базовые интерфейсы.

Из корня репозитория, Python 3.11+:

python -m pip install -e ".[test,docs]"
python examples/prequential_demo.py
python -m sphinx -b html -W --keep-going docs docs/_build/html

HTML-сайт с навигацией, поиском и API открывается из docs/_build/html/index.html. Подробности установки для PowerShell и Linux/macOS, проверки и CI — в инструкции.

Число параметров плохо объясняет, почему сильно перепараметризованные нейросети способны обобщать. Проект рассматривает сложность как стоимость описания модели и данных либо как приближение байесовского evidence. Его задача — реализовать несколько теоретически обоснованных оценок под единым интерфейсом и проверить, какие из них лучше предсказывают качество обобщения нейросетей.

Основной исследовательский вопрос: насколько значение и ранжирование оценок сложности согласуются с test NLL, generalization gap и устойчивостью модели при изменении размера выборки, архитектуры и регуляризации?

Все кодовые длины должны возвращаться в nats и/или bits, а также в нормированном виде на один объект. Вместе с числом метод обязан сохранять допущения, составляющие оценки, время вычисления и конфигурацию эксперимента. AIC/BIC-подобные критерии нельзя считать универсальной «истинной сложностью» нейросети: проект сравнивает приближения и явно указывает область применимости каждого из них.

Граница ответственности включает формулу и допущения метода, реализацию общего интерфейса, минимальный воспроизводимый пример и unit-тесты своей ветки. Сложные методы сначала реализуются для небольших MLP/CNN; масштабирование не должно задерживать PoC.

flowchart LR
    A[Model + data + training artifacts] --> B[Estimator API]
    B --> C[Classical / MDL]
    B --> D[Bayesian]
    B --> E[Prequential]
    B --> F[Compression]
    C & D & E & F --> G[ComplexityResult: value, unit, components, metadata]
    G --> H[Benchmark runner]
    H --> I[Tables, plots and report]

Текущий стек: Python 3.11+, PyTorch, pytest, Sphinx/MyST и тема Read the Docs. NumPy/SciPy, pandas, scikit-learn и измерение coverage относятся к дальнейшему экспериментальному стенду. Для кривизны допускается KFAC/Laplace-бэкенд, но публичный API проекта не должен зависеть от конкретной реализации.

Бенчмарк фиксирует seed, split и бюджет обучения и сравнивает семейство MLP/CNN разной ширины, глубины и регуляризации сначала на синтетике, затем на MNIST/Fashion-MNIST. Отчёт содержит complexity score, test NLL, generalization gap, время и память, а также ранговую корреляцию сложности с качеством обобщения.

Каждый участник делает минимум одно cross-review чужой ветки. Предлагаемый цикл ревью: Алябушев → Дементьев → Курдюков → Чирков → Алябушев.

1. Tech meeting 1: утвердить формулы, единицы, API, датасеты и план экспериментов.
2. Tech meeting 2: показать end-to-end PoC на общем интерфейсе, промежуточную документацию, блог-пост и техотчёт.
3. Checkpoint: собрать методы в устанавливаемый пакет и провести cross-review.
4. Tech meeting 3: запустить общие бенчмарки, добиться coverage > 90%, показать демо и представить итоговые выводы.

Индекс первоисточников и локальные PDF находятся в literature/.

В tests/ находятся обычные pytest-тесты, включая проверки на простых моделях с независимо известным ответом. Они входят в репозиторий и исходный пакет (sdist), не требуют внешних отчётов, скачивания данных или обучения большой сети.

• test_analytical_criteria.py — MLE нормальной и Bernoulli-моделей, OLS, AIC/BIC/HQIC и WAIC с точным дискретным posterior;
• test_analytical_bayesian.py — Gaussian evidence, KFAC-Laplace, VI и WBIC;
• test_analytical_codes_bounds.py — последовательные коды, реальный codec, pruning/low-rank/quantization и реализованная часть Arora;
• test_analytical_integration.py — checkpoint, нормы и аналитические производные.

Из корня проекта в окружении с зависимостями из pyproject.toml:

python -m pytest -q
python -m pytest -q -k analytical

Краткие теоретические расчёты, численные значения, допуски и карта остальных файлов — в tests/README.md. Проверки разделены по методам и охватывают численные значения, формы тензоров и публичные вызовы. Метрики обучения на случайной выборке не заменяют аналитический эталон.

Тесты различают точные формулы, WAIC по конечному набору значений и оценки Монте-Карло с отдельным допуском. Для Arora проверяются Matrix-Project и условная Theorem 2.1.

• src/dl_complexity/ — общее ядро, criteria, bayesian, coding, compression, bounds, diagnostics и PyTorch-интеграции;
• tests/ — численные эталоны и проверки общего публичного контракта; tests/README.md — структура тестов и краткие расчёты;
• examples/quickstart.py — небольшой пример модели, данных и совместной оценки;
• examples/prequential_demo.py — MLP, blockwise/online/replay, калибровка и JSON-журналы;
• docs/ — Sphinx-сайт, руководства и API из исходных docstrings;
• .github/workflows/docs.yml — сборка документации и проверки prequential-ветки;
• pyproject.toml — упаковка src-layout и конфигурация тестов;
• literature/ — первоисточники и навигация по ним;
• presentation/ — презентация архитектуры и BIC PoC; предыдущая версия сохранена в архиве;
• NEXT_STEPS.md — актуальный план реализации.

Python-пакет — dl_complexity. Общий вызов: method.estimate(context, data=data) либо method.estimate(inputs=prepared). ComplexitySuite объединяет методы и явно сообщает о нехватке их входов. Результат сохраняет kind, units и components: native IC, кодовая длина и граница риска не становятся одной шкалой. Обучение и подготовка posterior/curvature/prefix artifacts выполняются явно.

Поддерживаемые варианты: WAIC2 (ddof=1); WBIC по переданным tempered likelihood; negative ELBO для заданных q/prior; KFAC с явными факторами и точной подготовкой для одного Gaussian Linear; blockwise CI/FS, online и uniform-prefix replay; weight-only сжатие с бинарным codec. Для Arora реализованы Matrix-Project (Algorithm 1) и условная Theorem 2.1 с полным sample certificate. Полная noise-stability Theorem 4.1 в этот API не входит. WAIC и WBIC принимают выборки весов; для модели PyTorch их готовят prepare_posterior_log_likelihood и prepare_tempered_likelihood (MALA/ULA/SGLD). KFAC для произвольной сети требует готовых факторов.

Основная презентация — архитектура библиотеки и BIC proof of concept, 6 слайдов на английском: PDF, LaTeX-исходник, сборка и пример запуска. Предыдущая презентация Tech Meeting 1 сохранена в архиве.