valska.external_tools.pyuvsim.cli_prepare

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

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

valska-pyuvsim-prepare

What this does

This generates reproducible run artefacts for a pyuvsim simulation, without actually running pyuvsim itself.

Specifically, it:

  • resolves runtime paths (results_root, optional beamdata expansion, default template)

  • instantiates the pyuvsim runner (currently conda)

  • prepares a run directory containing: - a simulation config YAML / obsparam YAML - a submit script for the simulation stage - a manifest.json recording provenance & resolved paths

Design principles

  • setup.prepare_pyuvsim_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. 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>/pyuvsim/<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 is rejected to prevent silent misrouting.

Beamdata path resolution

If you pass –beamdata 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:

--beamdata foo/bar  ->  /path/to/datasets/foo/bar

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 may 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-pyuvsim-prepare.

main([argv])

CLI entrypoint for valska-pyuvsim-prepare.
valska.external_tools.pyuvsim.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_pyuvsim_run(). For real prepares we pass run_dir=None so setup.py computes the canonical location itself (single source of truth).

valska.external_tools.pyuvsim.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

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

Format a run label from a fractional FWHM perturbation.

valska.external_tools.pyuvsim.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.pyuvsim.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).

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

Extract SLURM defaults from runtime_paths.yaml for pyuvsim.

Passes through ALL keys from the config to support any SBATCH directive.

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

Return a UTC timestamp suitable for directory naming.

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

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

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

CLI entrypoint for valska-pyuvsim-prepare.