valska.external_tools.bayeseor.cli_prepare

Prepare a BayesEoR validation run “kit” under the ValSKA results directory.

This module is the importable CLI entrypoint used by the console script:

valska-bayeseor-prepare

It preserves the behaviour of the development driver script:

scripts/prepare_bayeseor_run.py

What this does

This generates reproducible run artefacts for a BayesEoR analysis, without actually running BayesEoR itself.

Specifically, it:

  • resolves runtime paths (results_root, data root expansion, default template)

  • instantiates the BayesEoR runner (currently conda)

  • prepares a run directory containing: - hypothesis-specific config YAMLs (signal_fit / no_signal) - submit scripts for CPU precompute and GPU run stages - a manifest.json recording provenance & resolved paths

Design principles

  • setup.prepare_bayeseor_run() is the single source of truth for canonical run_dir construction. This CLI only duplicates run_dir logic for –dry-run display.

Variant concept

We include a <variant> directory level to separate template-level differences that should never collide (e.g. validation_v1d0 vs validation_v1d0_achromatic). By default it is derived from the template filename stem by removing the first occurrence of “_template”.

Beam/sky taxonomy

The results tree is organised by (beam_model, sky_model), replacing the earlier overloaded “scenario” label.

Canonical non-sweep run directory:

<results_root>/bayeseor/<beam_model>/<sky_model>/<variant>/<run_label>/<run_id>[/<UTCSTAMP>]

Backwards compatibility

  • –scenario is deprecated. If used, it must be unambiguous: - –scenario <beam>/<sky> - –scenario <beam>__<sky>

  • Any other form (e.g. “GLEAM_beam”) is rejected to prevent silent misrouting.

Data path resolution

If you pass –data as a relative path, it is resolved using runtime_paths.yaml:data.root if set.

Example runtime_paths.yaml:

results_root: /share/nas-0-3/psims/validation_results/UKSRC
data:
  root: /path/to/datasets

Then ValSKA will resolve:

--data foo/bar.uvh5  ->  /path/to/datasets/foo/bar.uvh5

Absolute paths are used as-is. The resolved absolute path is recorded in the manifest.

Future container support

Today this assumes a conda-based runner. In the future we will support Apptainer/Singularity containers by swapping the “runner” configuration; the produced run directory, config YAML, and scripts are designed to remain stable.

Functions

build_parser()

Build the CLI argument parser for valska-bayeseor-prepare.

main([argv])

CLI entrypoint for valska-bayeseor-prepare.
valska.external_tools.bayeseor.cli_prepare._compute_run_dir(*, results_root: Path, beam_model: str, sky_model: str, variant: str, run_label: str, run_id: str, unique: bool) → Path

Compute the canonical run directory for –dry-run display only.

NOTE: This duplicates the layout logic used in setup.prepare_bayeseor_run(). For real prepares we pass run_dir=None so setup.py computes the canonical location itself (single source of truth).

valska.external_tools.bayeseor.cli_prepare._derive_variant_from_template_path(template_yaml: Path) → str

Derive a stable variant key from a template filename.

Rules:

  • take filename stem

  • remove first occurrence of “_template” if present

Examples:

validation_v1d0_template.yaml -> validation_v1d0 validation_v1d0_template_achromatic.yaml -> validation_v1d0_achromatic beam_achromatic.yaml -> beam_achromatic

valska.external_tools.bayeseor.cli_prepare._format_run_label_from_antenna_diameter_frac(frac: float) → str

Format a run label from a fractional antenna_diameter perturbation.

valska.external_tools.bayeseor.cli_prepare._format_run_label_from_fwhm_frac(frac: float) → str

Format a run label from a fractional FWHM perturbation.

valska.external_tools.bayeseor.cli_prepare._get_nested(d: dict[str, Any], *keys: str) → Any

Safely access nested dict keys; returns None if any level is missing.

valska.external_tools.bayeseor.cli_prepare._parse_beam_sky(*, beam: str | None, sky: str | None, scenario: str | None) → tuple[str, str, str]

Preferred: –beam and –sky.

Deprecated: –scenario in the form ‘<beam>/<sky>’ or ‘<beam>__<sky>’.

Returns (beam_model, sky_model, source_tag) where source_tag is one of:

  • “CLI(–beam/–sky)”

  • “DEPRECATED(–scenario)”

valska.external_tools.bayeseor.cli_prepare._parse_overrides(kvs: list[str]) → dict[str, str]
valska.external_tools.bayeseor.cli_prepare._slurm_defaults(runtime: dict[str, Any], profile: str) → dict[str, Any]

Extract SLURM defaults from runtime_paths.yaml.

Passes through ALL keys from the config to support any SBATCH directive. Only truly universal defaults are set here; cluster-specific options should be configured in runtime_paths.yaml.

valska.external_tools.bayeseor.cli_prepare._utc_stamp() → str

Return a UTC timestamp suitable for directory naming.

valska.external_tools.bayeseor.cli_prepare.build_parser() → ArgumentParser

Build the CLI argument parser for valska-bayeseor-prepare.

valska.external_tools.bayeseor.cli_prepare.main(argv: list[str] | None = None) → int

CLI entrypoint for valska-bayeseor-prepare.