Command-line interface

Run project commands through uv run from the repository root so the tracked environment and git-sourced dependencies are selected.

lan-sbatch

The installed entry point for sbatch_scripts.gen_sbatch has three commands:

uv run lan-sbatch generate --help
uv run lan-sbatch jaxtrain --help
uv run lan-sbatch torchtrain --help

generate

Option	Required/default	Meaning
--config-path PATH	required	ssm-simulators generation YAML
--output-path PATH	required	Data output root; generated scripts/logs use its runs/ child
--n-jobs-in-array INTEGER	1	Slurm array size before optional lane splitting
--n-files INTEGER	unset	Files generated by each worker
--cluster-config PATH	unset	Shared cluster YAML; adjacent .local.yaml is merged automatically
--use-all-lanes	false	Split an array across configured CPU lanes and emit one result per lane
--account, --partition	config/fallback	Explicit scheduling overrides
--num-gpus, --cores, --mem, --time	config/fallback	Explicit resource overrides
--script-only	false	Render without submitting or creating MLflow state
--log-level TEXT	WARNING	DEBUG, INFO, WARNING, ERROR, or CRITICAL

The rendered generate command also receives --n-cpus equal to the resolved core request.

jaxtrain and torchtrain

The trainer commands have the same interface and differ only in the LANfactory console command embedded in the script.

Option	Required/default	Meaning
--config-path PATH	required	LANfactory training YAML
--output-path PATH	required	Network output root
--training-data-folder PATH	required	Generated data consumed by the trainer
--network-id INTEGER	0	Network configuration index
--data-generation-experiment-id TEXT	unset	MLflow generation experiment linked as input lineage
--cluster-config PATH	unset	Shared cluster YAML plus automatic personal overlay
--account, --partition	config/fallback	Explicit scheduling overrides
--num-gpus, --cores, --mem, --time	config/fallback	Explicit resource overrides
--dl-workers INTEGER	1	LANfactory dataloader worker count
--script-only	false	Render without submitting or creating MLflow state
--log-level TEXT	WARNING	Logging threshold

lan-publish

uv run lan-publish --help

Option	Required/default	Meaning
--hf-repo TEXT	required	Non-production Hugging Face target; there is deliberately no default
--run-id TEXT	selection A	Exact MLflow training run
--model TEXT	selection B	Model for newest-completed-run selection
--network-type TEXT	selection B	lan, cpn, opn, or gonogo
--artifact-dir PATH	run output path	Local folder holding the training artifacts
--staging-dir PATH	temporary directory	Persistent isolated upload assembly directory
--skip-density	false	Skip G4 for a shorter rehearsal; the result cannot publish
--dry-run	false	Validate and print the plan without HF/MLflow publication writes
--overwrite-root	false	Intentionally replace an existing canonical root artifact
--log-level TEXT	INFO	Logging threshold

Pass --run-id, or pass both --model and --network-type. The source run's recorded parameters remain authoritative after selection.

Network validation

uv run python validation/validate_network.py --help

Option	Required/default	Meaning
--onnx-path PATH	required	Trusted ONNX artifact; sibling config may be unpickled
--model-name TEXT	required	ssm-simulators model name
--network-type TEXT	lan	lan, cpn, opn, or gonogo
--report-path PATH	next to ONNX	Detailed JSON report destination
--skip-density	false	Mark density skipped
--skip-hssm	false	Mark HSSM integration skipped
--hellinger-ratio-max FLOAT	3.0	Maximum density error relative to sampling floor
--log-level TEXT	WARNING	Logging threshold

Parameter-recovery worker

recover_parameters.py fits one synthetic dataset and writes one shard. This one-fit-per-process interface is the unit to fan out across a Slurm array.

uv run --group validate python validation/recover_parameters.py --help

Option	Required/default	Meaning
--model TEXT	ddm_sdv	Model known to both HSSM and ssm-simulators
--design TEXT	required	Recovery-ladder design declared in validation/recovery_designs.py
--dataset-index INTEGER	required	Dataset identity; the worker uses seed 10000 + dataset_index for paired arms
--likelihood TEXT	approx_differentiable	Likelihood arm, such as the candidate network or an analytical reference
--bounds-from TEXT	approx_differentiable	Likelihood whose bounds define the shared priors
--condition-param TEXT	inferred	Parameter varied across conditions
--onnx-path PATH	unset	Local candidate artifact; required for approx_differentiable
--p-outlier FLOAT	unset	Lapse probability; unset matches the lapse-free simulator
--arm TEXT	derived	Pooling key; defaults to likelihood plus the ONNX stem for a network
--out-dir PATH	.	Destination for the schema-version-2 shard
--draws, --tune	1000 each	Posterior draws and tuning draws
--chains INTEGER	2	Sampling chains
--target-accept FLOAT	0.9	NumPyro target acceptance probability
--log-level TEXT	WARNING	Logging threshold

Parameter-recovery aggregator

aggregate_recovery.py reads every recovery_*.json shard below one directory, applies the eligibility and calibration gates, and writes one report.

uv run --group validate python validation/aggregate_recovery.py --help

Option	Required/default	Meaning
--shard-dir PATH	required	Existing directory containing recovery shards
--out PATH	<shard-dir>/recovery_report.json	Schema-version-2 report destination
--log-level TEXT	WARNING	Logging threshold

Cluster discovery

uv run python scripts/discover_cluster.py --help

Option	Default	Meaning
--ssh-host TEXT	local shell	Run read-only Slurm queries through an SSH config host
--output PATH	configs/cluster/oscar.local.yaml	Personal overlay destination
--print	false	Print generated YAML instead of writing it

Visual inspection

export INSPECT_ONNX="/path/to/candidate.onnx"
export INSPECT_MODEL="ddm"
uv run --group inspect marimo edit validation/inspect_network.py

The inspector is a marimo application configured through environment variables, not a stable machine interface.

Documentation

./scripts/docs.sh build
./scripts/docs.sh serve

build always adds MkDocs strict mode. Both commands sync only the locked docs group with Python 3.12 and do not install the project.