Справка CLI

CLI nextstatпредоставляет основные операции в виде подкоманд. Реализация находится в крейте ns-cli.

Команды

nextstat fit

Запуск оценки максимального правдоподобия (MLE) на workspace.

nextstat fit --input workspace.json

nextstat hypotest

Асимптотическая CLs-проверка гипотезы при заданной силе сигнала μ.

nextstat hypotest --input workspace.json --mu 1.0
nextstat hypotest --input workspace.json --mu 1.0 --expected-set

nextstat hypotest-toys

Toy-based CLs-проверка гипотезы с параллельным выполнением.

# CPU (все ядра)
nextstat hypotest-toys --input workspace.json \
  --mu 1.0 --n-toys 10000 --seed 42 --threads 0

# NVIDIA GPU (CUDA)
nextstat hypotest-toys --input workspace.json \
  --mu 1.0 --n-toys 10000 --gpu cuda

# Apple Silicon GPU (Metal)
nextstat hypotest-toys --input workspace.json \
  --mu 1.0 --n-toys 10000 --gpu metal

nextstat upper-limit

Вычисление CLs верхнего предела сканированием силы сигнала.

nextstat upper-limit --input workspace.json \
  --expected \
  --scan-start 0 --scan-stop 5 --scan-points 201

nextstat scan

GPU-ускоренный скан профильного правдоподобия. Использует одну GpuSession для всех точек скана с warm-start.

nextstat scan --input workspace.json \
  --start 0 --stop 5 --points 21 --gpu cuda

nextstat audit

Инспекция pyhf/HS3 workspace: количество каналов, образцов и модификаторов, а также неподдерживаемые функции.

nextstat audit --input workspace.json
nextstat audit --input workspace.json --format json --output audit.json

nextstat export histfactory

Конвертация pyhf workspace обратно в HistFactory XML + ROOT-файлы гистограмм. Опциональный --python генерирует управляющий скрипт.

nextstat export histfactory --input workspace.json --out-dir export/
nextstat export histfactory --input workspace.json \
  --out-dir export/ --prefix meas --overwrite --python

nextstat import histfactory

Разбор combination.xml и XML-файлов каналов, чтение ROOT-гистограмм и генерация pyhf-совместимого workspace.json.

nextstat import histfactory --input config/combination.xml \
  --output workspace.json

nextstat import trex-config

Миграция конфигов TRExFitter (по возможности) из .config. Поддерживаются режимы ReadFrom: NTUP и ReadFrom: HIST.

nextstat import trex-config --input myfit.config \
  --output workspace.json
nextstat import trex-config --input myfit.config \
  --output workspace.json --analysis-yaml --coverage-json

ReadFrom: HIST (режим только фильтрации)

›Оборачивает существующий экспорт HistFactory через HistoPath: или CombinationXml:.
›Region: блоки работают как include-list по каналам, поэтому Variable/Binning не требуются.
›Sample: блоки работают как include-list по сэмплам, поэтому File не требуется. Фильтры Regions: на уровне сэмпла учитываются.
›Пустые каналы автоматически отбрасываются, если они явно не выбраны через блоки Region: (иначе будет ошибка).

nextstat timeseries kalman-viz

Создание plot-friendly JSON-артефакта со сглаженными состояниями, наблюдениями, маргинальными полосами и опциональным прогнозом.

nextstat timeseries kalman-viz --input kalman_1d.json
nextstat timeseries kalman-viz --input kalman_1d.json \
  --level 0.99 --forecast-steps 20

nextstat ranking

Вычисление влияния мешающих параметров (данные для ranking plot).

nextstat ranking --input workspace.json
nextstat ranking --input workspace.json --gpu cuda

nextstat report

Генерация распределений, pulls, корреляций, yields и ранкинга неопределённостей из workspace.

nextstat report --input workspace.json --output report/
nextstat report --input workspace.json --output report/ \
  --blind --deterministic --render

nextstat validation-report

Генерация единого артефакта валидации (JSON + опц. PDF), объединяющего результаты Apex2 с отпечатками workspace.

nextstat validation-report \
  --apex2 tmp/apex2_master_report.json \
  --workspace workspace.json \
  --out validation_report.json \
  --pdf validation_report.pdf \
  --deterministic

nextstat preprocess

Запуск препроцессинга систематик: сглаживание (353QH), прунинг (shape/norm/overall), с декларативной YAML-конфигурацией и кешированием по хешу.

nextstat preprocess --config preprocess.yaml \
  --input workspace.json --output workspace_smooth.json

nextstat survival

Фит параметрических (Weibull, log-normal AFT) и полупараметрических (Cox PH) моделей выживаемости.

nextstat survival fit --model cox --input data.json
nextstat survival predict --model weibull --input data.json

nextstat build-hists

Запуск конвейера ntuple-to-workspace: заполнение гистограмм из ROOT TTree и создание pyhf JSON workspace.

nextstat build-hists --config analysis.yaml \
  --output workspace.json

nextstat run

Выполнение полного конвейера анализа из файла Analysis Spec v0 YAML (import → fit → scan → report).

nextstat run analysis_spec.yaml

nextstat unbinned-fit

MLE-фит для unbinned (event-level) модели. Конфигурация задаётся JSON-файлом по схеме unbinned_spec_v0.

nextstat unbinned-fit --config unbinned.json
nextstat unbinned-fit --config unbinned.json --threads 0

PDF (v0): gaussian, crystal_ball, double_crystal_ball, exponential, chebyshev, argus, voigtian, spline, histogram, histogram_from_tree, kde, kde_from_tree, product, flow, conditional_flow, dcr_surrogate. Модификаторы yields: normsys (Code1), weightsys (Code0/Code4p).

nextstat unbinned-scan

Профильный скан правдоподобия для unbinned-модели. Требует model.poi в спецификации.

nextstat unbinned-scan --config unbinned.json \
  --start 0 --stop 5 --points 21 --threads 0

nextstat unbinned-fit-toys

Генерация toy-экспериментов и фит каждого для unbinned-модели.

nextstat unbinned-fit-toys --config unbinned.json \
  --n-toys 100 --seed 42 --threads 0
# Генерация от MLE-точки вместо init
nextstat unbinned-fit-toys --config unbinned.json \
  --n-toys 100 --seed 42 --gen mle

nextstat unbinned-hypotest

Вычисление асимптотического qₘ (и q₀ если μ=0 в пределах) для unbinned-модели.

nextstat unbinned-hypotest --config unbinned.json --mu 1.0
nextstat unbinned-hypotest --config unbinned.json --mu 1.0 --gpu cuda

nextstat unbinned-hypotest-toys

Toy-based CLs (q̃) для unbinned-моделей. GPU-ускоренный батч-фит с опциональным device-resident сэмплированием.

nextstat unbinned-hypotest-toys --config unbinned.json \
  --mu 1.0 --n-toys 1000 --seed 42 --threads 0

# CUDA с device-resident сэмплированием + шардинг
nextstat unbinned-hypotest-toys --config unbinned.json \
  --mu 1.0 --n-toys 10000 --gpu cuda --gpu-sample-toys --gpu-shards 4

# Metal
nextstat unbinned-hypotest-toys --config unbinned.json \
  --mu 1.0 --n-toys 10000 --gpu metal

nextstat unbinned-merge-toys

Объединение результатов шардов из unbinned-fit-toys --shard в единый результат.

# CPU farm: разделение 10k toys на 4 узла
nextstat unbinned-fit-toys --config spec.json --n-toys 10000 --shard 0/4 -o shard0.json
nextstat unbinned-fit-toys --config spec.json --n-toys 10000 --shard 1/4 -o shard1.json
nextstat unbinned-fit-toys --config spec.json --n-toys 10000 --shard 2/4 -o shard2.json
nextstat unbinned-fit-toys --config spec.json --n-toys 10000 --shard 3/4 -o shard3.json

# Объединение
nextstat unbinned-merge-toys shard0.json shard1.json shard2.json shard3.json -o merged.json

nextstat viz render

Рендеринг одного JSON viz артефакта в изображение без генерации полного отчёта. Поддерживает pulls, corr и ranking.

nextstat viz render --kind pulls --input pulls.json --output pulls.png
nextstat viz render --kind corr --input corr.json --output corr.png \
  --corr-top-n 40 --dpi 220

nextstat version

Вывод строки версии и выход.

nextstat version

nextstat-server (отдельный бинарник)

Самостоятельный REST API для общего GPU-вывода. Собран как отдельный бинарник в crates/ns-server.

# Сборка
cargo build -p ns-server --release
cargo build -p ns-server --features cuda --release

# Запустить
nextstat-server --port 3742 --gpu cuda
nextstat-server --host 0.0.0.0 --port 3742 --threads 8

Метод	Путь	Описание
POST	/v1/fit	MLE-фит (workspace → FitResult)
POST	/v1/ranking	Ранкинг мешающих параметров
POST	/v1/batch/fit	Батч-фит (до 100 workspace'ов)
POST	/v1/batch/toys	GPU-ускоренный батч-фиттинг тоев
POST	/v1/models	Загрузка workspace в кеш моделей
GET	/v1/models	Список кешированных моделей
DELETE	/v1/models/:id	Удаление модели из кеша
GET	/v1/health	Здоровье сервера + число кешированных моделей

Модели кешируются по SHA-256 хешу. Передайте model_id вместо workspace, чтобы пропустить повторный парсинг. LRU-вытеснение с лимитом 64 модели. Полная справка: сервер вывода.

Автоопределение формата ввода

Все команды, принимающие --input автоматически определяют формат JSON. Оба формата pyhf и HS3 (HEP Statistics Serialization Standard v0.2) поддерживаются нативно.

# pyhf workspace (определяется автоматически)
nextstat fit --input workspace.json

# HS3 workspace из ROOT 6.37+ (определяется автоматически)
nextstat fit --input workspace-postFit_PTV.json

Определение мгновенное (сканирование префикса первых ~2 КБ). HS3-файлы идентифицируются по наличию ключей "distributions" и "hs3_version" ключей. Все типы модификаторов поддерживаются: normfactor, normsys, histosys, staterror, shapesys, shapefactor, lumi. Неизвестные типы молча пропускаются (прямая совместимость).

Значения интерполяции по умолчанию

›--interp-defaults root (по умолчанию) — Code4/Code4p сглаженная интерполяция для NormSys/HistoSys.
›--interp-defaults pyhf — Code1/Code0 строгие значения pyhf по умолчанию (экспоненциальная/кусочно-линейная).
›HS3-входы всегда используют значения ROOT HistFactory по умолчанию (Code1 для NormSys, Code0 для HistoSys), вне зависимости от этого флага.

Общие флаги

Флаг	Описание
--input <path>	Путь к JSON-файлу workspace
--mu <float>	Сила сигнала для проверки гипотезы
--n-toys <int>	Количество toy-экспериментов
--seed <int>	Случайное семя для воспроизводимости
--threads <int>	Количество потоков (0 = все ядра, 1 = детерминированный)
--gpu <cuda\|metal>	GPU-бэкенд для генерации тоев
--expected-set	Вернуть ожидаемую полосу (±1σ, ±2σ)
--parity	Детерминированный режим (суммирование Кэхена, однопоточный, побитово точный)
--interp-defaults <root\|pyhf>	Коды интерполяции по умолчанию (root=Code4/Code4p, pyhf=Code1/Code0)
--deterministic	Стабильный порядок ключей JSON в выходах отчётов
--log-level <level>	Уровень логирования (error, warn, info, debug, trace)
--bundle <path>	Сохранение воспроизводимого пакета запуска (входы + выходы + окружение)