# Руководство пользователя BDF
Самостоятельный BDF-солвер является плотным неявным решателем,
ориентированным на поведение SciPy, для небольших и средних полностью
связанных систем. Это намеренно не второй структурированный солвер. Для
разреженного или ленточного хранения используйте LSODE2 и явно выбирайте его
маршрут `Sparse` или `Banded`.
## Выбор бэкенда
Публичные настройки BDF поддерживают три основных режима:
- native callbacks, если правая часть и якобиан уже написаны на Rust;
- символьные callback-функции `Lambdify` для подготовленной задачи;
- AOT callback-функции для размещаемого скомпилированного артефакта.
Для символьной сборки доступны `IvpSymbolicAssemblyBackend::ExprLegacy` и
`IvpSymbolicAssemblyBackend::AtomView`. Оба маршрута имеют одинаковый численный
контракт. Их стоимость подготовки и callback-стоимость зависят от workload,
поэтому выбор следует делать по измерениям, а не по универсальному рейтингу.
## Плотный native-решатель
Минимальный пример находится в `examples/rus/bdf_native_dense_guide.rs`:
```text
cargo run --no-default-features --example rus_bdf_native_dense_guide
```
Он устанавливает native residual и постоянный аналитический плотный якобиан,
включает счетчики телеметрии, использует типизированный `try_solve` и
сравнивает результат с точным решением.
## Символьное продолжение по параметру
`examples/rus/bdf_symbolic_continuation_guide.rs` показывает AtomView вместе с
Lambdify. Подготовленные residual и Jacobian переиспользуются, меняются только
значение параметра и численная история BDF:
```text
cargo run --no-default-features --example rus_bdf_symbolic_continuation_guide
```
Продолжение безопасно, пока символьная структура не меняется. Изменение формы
уравнений, размерности состояния, layout якобиана или политики бэкенда требует
новой подготовленной сборки.
## AOT и toolchain
`examples/rus/bdf_aot_guide.rs` использует AtomView и генерируемые
C/tcc callback-функции:
```text
cargo run --no-default-features --example rus_bdf_aot_guide
```
Если `tcc` отсутствует в `PATH`, пример завершается штатно с поясняющим
сообщением. Подготовка AOT включает materialize, build, link и publication;
при warm continuation опубликованный артефакт должен переиспользоваться без
повторной компиляции.
## Телеметрия и ошибки
Телеметрия по умолчанию выключена. `BdfTelemetryMode::Counters` дает
низкозатратные счетчики работы, а `BdfTelemetryMode::Timings` добавляет
диагностические таймеры стадий. Вложенные timing scopes являются inclusive и
их нельзя складывать.
В прикладном коде предпочтителен типизированный API `try_*`, включая
`try_solve`, continuation и методы конфигурации. Он сообщает типизированными
ошибками о неверной размерности, отсутствующих callback-функциях,
неподдерживаемых комбинациях бэкендов и сбоях подготовки.
## Граница области применения
Самостоятельный BDF хранит плотные якобианы и использует плотную линейную
алгебру. Указание плотного `jac_sparsity` не превращает его в разреженный
решатель. Для больших diffusion- или banded-задач используйте LSODE2: там есть
структурированные matrix backends, телеметрия и соответствующие story-тесты.
## Сверка численного ядра со SciPy
Численный контроллер сверялся с закрепленной официальной реализацией SciPy
1.18.1 BDF в `src/numerical/ivp_scipy_reference`. В Python-копию добавлена
только наблюдательная телеметрия: формулы и ветви контроллера SciPy не менялись.
Сопоставленный Rust/Python story-тест охватывает десять задач: постоянный и
конечно-разностный якобианы, намеренно устаревший постоянный якобиан с повтором
Ньютона, Robertson, интегрирование назад, автоматический первый шаг, HIRES,
combustion-like кинетику, неавтономную задачу с разными масштабами и полностью
связанную плотную систему.
Сравниваются конечные состояния, три общие внутренние точки траектории,
метаданные состояния решателя и сопоставимые счетчики работы. Максимальное
масштабированное расхождение конечного состояния составило `1.109e-7`, а
внутренних точек — `0.405` при явном пороге `2`. Числа принятых/отклоненных
шагов, изменения порядка, работа Ньютона и линейные решения совпали на
проверенных задачах. Отдельный release-бенчмарк сравнивает создание SciPy
решателя, интегрирование и сбор состояний с численной инициализацией,
интегрированием и сбором результата Rust. Символьная подготовка Rust исключена;
это не сравнение полных API и не универсальное обещание скорости.
Оставшиеся расхождения счетчиков объяснены и не означают неизвестного
изменения алгоритма. SciPy не включает пробы конечно-разностного якобиана в
`nfev`; Rust считает фактические вызовы невязки и повторно использует начальное
значение невязки как базу FD. В FD-задаче получено `nfev=506` у SciPy и `509` у
Rust (510 фактических вызовов RHS у SciPy). В задаче с намеренно устаревшим
якобианом Rust выполнил на одну LU-факторизацию больше (`245` против `244`):
из-за округления кандидат Rust оказался чуть за конечной границей, был обрезан,
и LU инвалидировалась; SciPy достиг границы без этого перехода и переиспользовал
LU. Предшествующие пошаговые числа LU совпадают, а траектория остается в
допустимом диапазоне parity.
Это свидетельство численной parity для проверенного набора задач, а не
побитового совпадения или полной совместимости API со SciPy. Настраиваемый
`max_steps`, типизированные ошибки callback-функций и поведение no-progress /
underflow являются возможностями Rust и проверяются отдельно. В Rust BDF пока
нет публичного вычислителя dense output: внутренние значения сравнивались с
отдельными Rust-решениями до тех же моментов времени, а не с реализацией
интерполяции Rust. Это явно обозначенные границы проверки, а не необъясненные
расхождения контроллера. Перед объявлением всей release-матрицы BDF полностью
зеленой нужно повторно запустить ее после исправления двух тестовых ожиданий.