FOLDIFF — WHAM / MBAR И КОНТРОЛЬ КАЧЕСТВА
Этап F7.3 · веб-калькулятор и локальный пакет · 15 октября 2026

Что реализовано
Одномерные гармонические umbrella-потенциалы при одной температуре и одном
физическом гамильтониане. Вход: CSV time,cv для каждого непрерывного запуска
и JSON с единицами, температурой, центрами, константами и независимыми повторами.
Периодические углы поддерживаются с корректным переходом через −180/180°.
Собственные CSV и config.json рассчитываются в веб-приложении после явного
нажатия кнопки расчёта. Файлы передаются серверу в России и удаляются после
задачи. Результат хранится в оперативной памяти до часа с доступом по приватному
ключу. Сохраните JSON и CSV. Просмотр готового JSON выполняется в браузере.
Для больших наборов доступен локальный пакет umbrella_core.py.

Это НЕ генератор MD, не универсальная 2D-модель и пока НЕ PMF тропонина.
Структурные конечные кадры WT/R145W не используются как равновесная выборка.

Математика и единицы
U_bias(x)=0.5*k*delta(x,center)^2. Для угла delta выбирает кратчайшее расстояние
по окружности. Константа k должна быть указана в energy_unit/coordinate_unit^2.
Поддерживаются kcal/mol, kJ/mol; angstrom, nm, degree, radian. Выход — kcal/mol.
Внутренний R = 0.00198720425864083 kcal/(mol K).
Colvars forceConstant может зависеть от width и conventions. Сырые параметры
NAMD нельзя переносить, не приведя их к этой явной формуле.
Восстанавливается профиль после удаления ТОЛЬКО указанной umbrella-добавки.
Другие общие ограничения остаются частью физического ансамбля.
WT и R145W нельзя объединять в один расчёт. Различные температуры и гамильтонианы
требуют полных физических энергий; в этом этапе отклоняются.

MBAR: PyMBAR 4.0.3 решает уравнения по beta*U_bias. Общая физическая энергия
сокращается только при подтверждённых одинаковых гамильтониане и температуре.
Веса целевого состояния w_n ∝ 1 / sum_k N_k exp(f_k-beta*U_bias,k(x_n)).
Из взвешенной гистограммы получаем F_i = −RT ln(P_i/bin_width) + C.
Аналитическая стандартная ошибка — через histogram FES PyMBAR относительно
минимума; это НЕ 95% интервал и НЕ полная ошибка физической модели.
WHAM: собственная дискретная самосогласованная реализация в логарифмах;
удерживающая энергия считается в центрах равных интервалов. Это приближение
зависит от ширины интервалов, поэтому сравниваем WHAM/MBAR и более мелкую сетку.
Нулевое заполнение хранится как отсутствие данных, а не как бесконечная энергия.
Нули независимых PMF условные: их вычитание не является ΔΔG стабильности мутации.

Контроль качества
• Проверка конечных чисел, единиц, температуры, положительных k и всех входов.
• Строго возрастающее равномерное время. Сброс времени или дубли не склеиваются.
• Дубликаты файлов отклоняются по SHA-256; повтор центра внутри одного replica
  требует явного объединения проверенных продолжений.
• Отброс начала: явно заданная доля; опционально дополнительная автоматическая
  оценка эквилибрации PyMBAR. Для углов — sin/cos, а не разрыв в ±180°.
• g оценивается по CV (max для sin/cos); берутся декоррелированные кадры.
  Это не устраняет риск медленных скрытых координат и коротких траекторий.
• Разорванное перекрытие гистограмм блокирует единый профиль; дополнительно
  строится граф MBAR при пороге 1e−5. Порог — диагностическая настройка.
• ESS интервала = (sum w)^2 / sum(w^2); по умолчанию линия скрыта при ESS<20.
  Нельзя интерполировать через провал выборки и выдавать такой барьер за результат.
• Дрейф первой/второй половины относительно SD; предупреждение при >0.5.
• Чувствительность: отброс ещё 10%, вторая половина, вдвое более мелкая сетка.
  Сравнение после одного постоянного сдвига по общим поддержанным интервалам.
• Независимые повторы сравниваются отдельно при одинаковых сетках окон.
  Номера продолжений нельзя объявлять независимыми повторениями.
• Сходимость численного решателя не означает равновесие физической системы.

Лимиты веб-калькулятора
До 2 МБ JSON вместе с CSV; 3–40 запусков, 20–20000 строк на файл,
до 80000 исходных и 15000 декоррелированных записей, 5–100 интервалов.
Дополнительно: K×N ≤800000 и N×(K+B+1) ≤1800000, где K — запуски,
N — выбранные записи, B — интервалы. Одна задача одновременно, до 180 секунд;
6 запросов в час с одного IP. Исходные файлы не сохраняются в кабинете.

Лимиты локального пакета
3–100 окон-запусков, 20–100000 строк на CSV, до 5 млн исходных записей;
матрица после декорреляции — до 12 млн элементов. 5–300 равных интервалов.
Если лимит превышен, расчёт останавливается. Нужна проверенная подготовка данных,
а не автоматическое произвольное прореживание. Автоматический перевод NAMD
colvars.traj и истории рестартов появится после получения реальных файлов.

Проверочные наборы
1. Гармонический потенциал, два независимых искусственных повтора, корреляция
   AR(1) rho=0.7. Истинный профиль вычисляется интегрированием вероятности по bins.
2. Двухъямный потенциал 2.5*(x²−1)²−0.4*x, два искусственных повтора. Никакого
   отношения к результатам тропонина эти тестовые числа не имеют.
3. Лизоцим L99A с бензолом: 26 окон угла боковой цепи, 501 запись/окно.
   Открытый пример PyMBAR, связанный с Mobley et al., JMB 2007,
   DOI 10.1016/j.jmb.2007.06.002. Это опубликованные данные моделирования,
   не лабораторные измерения и не доказательство биологической точности.
   Исходный коммит, URL и SHA-256 сохранены в research/. Чужие параметры
   не перенесены в тропонин. Исходные XVG преобразованы в CSV без прореживания.

Численная сверка
10 групп автоматических проверок; методы сравниваются между собой и с
интегральным известным ответом. Точный результат: tests/validation.json.
RMSE MBAR к известному ответу: harmonic 0.05089, doublewell 0.02710 kcal/mol
по интервалам ESS≥20 (для зафиксированных выборок и seed).
Для лизоцима повторно запущена гистограммная часть официального скрипта:
RMSE 0.000527 kcal/mol относительно нашего результата. После согласования
константы R: 0.000181 kcal/mol; остаток сопоставим с округлением печати 0.001 kT.
Исторический сохранённый sample_output отличается и не выдается за точный эталон.
WHAM/MBAR на сетке 10°: RMSE 0.18970; при 5°: 0.04149 kcal/mol.
Все три набора имеют статус «требует интерпретации»: на искусственных тестах
пустые/бедные хвосты, в опубликованном примере только один независимый запуск/окно.
Это ожидаемые ограничения, а не основание скрывать предупреждения.

Запуск из корня проекта
Python с numpy/scipy/pymbar: Foldiff-GPT/states/.validation-venv/bin/python
1. Подготовить свой config.json по examples/lysozyme/config.json.
2. Запустить:
   <python> Foldiff-GPT/landscapes/umbrella/umbrella_core.py /path/config.json --output /path/result.json
Рядом с JSON сохраняется CSV профиля с ошибкой, ESS и флагом поддержки интервала.
3. Открыть https://oligoplan.ru/app/landscapes/umbrella/
   и выбрать result.json в разделе сохранённых результатов.
   Для прямого расчёта выберите «Свои данные», загрузите config.json и CSV,
   проверьте параметры, подтвердите единицы и нажмите «Рассчитать».
Для повторения тестов: prepare_examples.py → umbrella_core.py для трёх примеров
→ validate.py → write_validation_report.py → build_report.py.
Для импортированного пользовательского результата численная валидация тестовых
наборов не считается автоматической валидацией нового эксперимента.

Дальше по тропонину
Получить отдельные CV-ряды HP и SP, WT и R145W, 24 окна × 3 повтора; реальные
времена и рестарты, температуру, ограничения, Colvars width и версии. Затем
адаптер и отдельные четыре постановки, проверка перекрытия/дрейфа/повторов,
воспроизведение определений ΔG из статьи. Пока недостающие ряды не синтезируем.

Источники
https://pymbar.readthedocs.io/en/stable/fes_with_pymbar.html
https://pymbar.readthedocs.io/en/stable/timeseries.html
https://github.com/choderalab/pymbar/tree/main/examples/umbrella-sampling-fes
https://doi.org/10.1016/j.jmb.2007.06.002
https://doi.org/10.1063/1.2978177 (MBAR, Shirts & Chodera 2008)
