Спецификация: Калькулятор миксов

Назначение и биологический контекст

Пользователь задаёт рецепт на одну реакцию, целевой объём одной реакции и запас в процентах. Инструмент показывает объём каждого компонента на весь микс и итоговый объём смеси для каждого введённого количества реакций.

Инструмент не подбирает рецепт и не проверяет его научную правильность, не знает концентраций и разведений (объёмы вводятся готовыми числами), не привязан к конкретной реакции — ПЦР, рестрикция или лигирование задаются только названиями компонентов.

Границы: смесь не делится на мастер-микс и матрицу, посуда, лунки и пипетки не моделируются, расчётные данные не передаются на сервер — расчёт идёт в браузере, сохранения остаются на устройстве пользователя.

Математическая модель и формулы

Единица измерения — мкл. Внутри объёмы хранятся целыми тысячными долями микролитра, шаг ввода и показа — 0,001 мкл: значение с лишними знаками округляется до ближайшего шага, и об округлении сообщается.

Обозначения: V — целевой объём одной реакции, N — количество реакций, p — запас в процентах, v — объём компонента на одну реакцию, M — рабочее число реакций (с запасом), R — запас в реакциях.

• R = 0, если p = 0; иначе R = max(1, round(N × p / 100))R — сколько дополнительных реакций добавится, N — сколько реакций нужно, p — запас в процентах, round — округление до целого, max(1, …) — не меньше одной реакции. Запас считается по количеству реакций, а не по объёму. Пример: нужно 8 реакций при запасе 10 % — 8 × 10 / 100 = 0,8, округляем до 1, готовим на 9 реакций. При p = 0 ничего не добавляется.
• M = N + RРабочее число реакций, на которое закупается смесь.
• Объём компонента = v × MОбъём на одну реакцию умножается на рабочее число реакций.
• v доводки = V − сумма объёмов остальных компонентовДоводка в рецепте одна и числом не вводится: в поле объёма пишут служебное значение «до V». Отрицательная доводка блокирует результат.
• Итог = сумма объёмов всех компонентовИтог считается суммой, а не умножением V на M. Без доводки сумма может не совпасть с V — тогда показывается предупреждение, но результат считается.

Входные параметры

Выходные параметры и состав отчёта

Результат — таблица: столбцы «Компонент», «×1» и по столбцу на каждое заполненное количество реакций («×8», «×24»). В колонке «×1» стоит объём на одну реакцию, в колонках «×N» — объём на весь микс. В подвале таблицы строка «V итог»: сумма объёмов компонентов для этой колонки.

Над таблицей стоит подпись результата: протокол, целевой объём и запас; при нулевом запасе оговорка о запасе не показывается.

Служебные N, R и M на экране и в выгрузке не показываются: посетителю нужны объёмы, а не внутренние числа расчёта.

• Выгрузка: PNG (картинка протокола), Word, Excel. Состав один и тот же: протокол, дата, V и запас, таблица компонентов и строка итогового объёма.
• Копирование PNG и «Поделиться»: системное меню устройства с файлом картинки — там, где устройство умеет делиться файлами.
• Режим «У стола»: крупный список компонентов, которые отмечают нажатием, со счётчиком отмеченного.
• Сохранённые расчёты: последние 10, хранятся в браузере пользователя и опознаются по названию эксперимента или по подписи входа.
• Ошибки и предупреждения показываются отдельными блоками: ошибка останавливает результат, предупреждение — нет.

Правила валидации

• Неполный ввод не считается ошибкой: пустой объём реакции, все пустые окошки количества, компонент без названия или объёма, отсутствие компонентов — расчёт не запускается, показывается подсказка, введённое сохраняется.
• Целевой объём: должен быть больше нуля; вне обычного диапазона 0,1–1000 мкл — предупреждение, но расчёт идёт.
• Запас: число в процентах, не меньше нуля; пустое поле читается как 10 %.
• Количество реакций: целое число не меньше единицы; одновременно не больше пяти окошек.
• Компонент: название обязательно и не повторяется; недостающее название — ошибка «Укажите название компонента».
• Доводка: ровно одна; объём у неё не вводится — иначе ошибка «У доводки объём не вводится»; при двух доводках расчёт останавливается.
• Отрицательный объём компонента — ошибка; нулевой объём, объём меньше 0,1 мкл и больше 1000 мкл — предупреждения.
• Отрицательная доводка (сумма компонентов больше целевого объёма) — ошибка: расчёт не показывается, пока рецепт не исправлен.
• Округление: значение с лишними знаками округляется до шага 0,001 мкл, и об этом сообщается отдельной строкой.

Источники

• Метод, контрольные примеры и история версий — docs/MIX_CALCULATOR_V2.md в репозитории проекта