valska.external_tools.bayeseor

BayesEoR integration helpers.

Primary entry points: - prepare_bayeseor_run: render a BayesEoR config + SLURM submit script into a ValSKA results dir. - submit_bayeseor_run: submit a prepared BayesEoR run directory to SLURM. - get_template_path: access shipped validation templates.

class valska.external_tools.bayeseor.BayesEoRInstall(repo_path: Path, run_script: Path = PosixPath('scripts/run-analysis.py'))

Where BayesEoR lives and which script to invoke.

Notes: - For now we assume a BayesEoR clone exists (HPC-friendly). - Later, if BayesEoR provides a stable module/entrypoint, we can support that too.

repo_path: Path

run_script: Path = PosixPath('scripts/run-analysis.py')

class valska.external_tools.bayeseor.CondaRunner(conda_activate: str, env_name: str)

Run BayesEoR via a named conda environment.

conda_activate should point to conda.sh (or equivalent) so that conda activate works inside non-interactive batch shells (SLURM).

bash_prefix() → str: Return shell lines to activate the conda environment.

conda_activate: str

env_name: str

class valska.external_tools.bayeseor.ContainerRunner(apptainer_exe: str, image_path: Path, bind_paths: tuple[Path, ...] = ())

Future: Run BayesEoR inside a container (Apptainer/Singularity).

This is included now so we don’t need to redesign the API later. The only thing that should change is how we construct the command line; config rendering and output directory conventions stay identical.

Example future command:: apptainer exec –bind <binds> <image.sif> python <run-analysis.py> <config.yaml>

apptainer_exe: str

bind_paths: tuple[Path, ...] = ()

image_path: Path

exception valska.external_tools.bayeseor.SubmissionError: Raised when submission cannot proceed safely or sbatch fails.

valska.external_tools.bayeseor.generate_sweep_report(*, sweep_dir: Path, out_dir: Path | None = None, evidence_source: Literal['ns', 'ins'] = 'ins', make_plots: bool = True, include_plot_analysis_results: bool = False, include_complete_analysis_table: bool = False) → SweepReportResult: Generate summary table(s) and plots for an existing sweep directory.

valska.external_tools.bayeseor.get_template_path(name: str) → Path

Return a filesystem Path to a shipped template.

Uses importlib.resources so this works both from a source checkout and from an installed wheel.

valska.external_tools.bayeseor.inspect_sweep_health(sweep_dir: Path) → SweepHealth: Inspect a sweep directory and summarize point/sweep health.

valska.external_tools.bayeseor.list_templates() → list[str]: List shipped BayesEoR validation templates bundled with the package.

valska.external_tools.bayeseor.prepare_bayeseor_run(*, template_yaml: Path, install: BayesEoRInstall, runner: CondaRunner | ContainerRunner, results_root: Path, beam_model: str, sky_model: str, run_label: str, data_path: Path, overrides: Mapping[str, Any] | None = None, slurm: Mapping[str, object] | None = None, slurm_cpu: Mapping[str, object] | None = None, slurm_gpu: Mapping[str, object] | None = None, run_dir: Path | None = None, run_id: str = 'default', variant: str | None = None, unique: bool = False, fwhm_perturb_frac: float | None = None, antenna_diameter_perturb_frac: float | None = None, hypothesis: str = 'both') → dict[str, Path]

Prepare a BayesEoR run directory containing hypothesis-specific artefacts.

Canonical non-sweep layout (when run_dir is None):
<results_root>/bayeseor/<beam_model>/<sky_model>/<variant>/<run_label>/<run_id>[/<UTCSTAMP>]
The variant defaults to a value derived from the template filename stem (first occurrence of _template removed). If unique=True, a UTC timestamp is appended beneath run_id.

At most one perturbation mode can be active. fwhm_perturb_frac applies a multiplicative perturbation to fwhm_deg. antenna_diameter_perturb_frac applies a multiplicative perturbation to antenna_diameter.

A single shared CPU precompute script is generated and pointed at an available hypothesis config (signal_fit preferred when both are present).

Returns

dict: Paths to created artefacts (configs, submit scripts, manifest), plus run_dir.

valska.external_tools.bayeseor.submit_bayeseor_run(run_dir: Path, *, stage: Literal['cpu', 'gpu', 'all'] = 'all', hypothesis: Literal['signal_fit', 'no_signal', 'both'] = 'both', depend_afterok: str | None = None, sbatch_exe: str = 'sbatch', dry_run: bool = False, force: bool = False, record: Literal['jobs.json', 'manifest'] = 'jobs.json') → dict[str, Any]

Submit BayesEoR prepared scripts for a run_dir.

Parameters

run_dir: Prepared run directory.
stage: Which stage(s) to submit: “cpu”, “gpu”, or “all”.
hypothesis: Which GPU hypothesis to run: “signal_fit”, “no_signal”, or “both”.
depend_afterok: Optional sbatch job id to depend on for GPU submissions.
sbatch_exe: sbatch executable to invoke.
dry_run: If True, do not submit jobs; return the commands that would run.
force: If True, allow resubmission even if jobs.json indicates prior submissions.
record: Where to record submission metadata. Currently only “jobs.json” is supported.

Returns

dict: A jobs.json-style record of the submission (merged if not dry_run).

Notes on jobs.json recording

jobs.json is treated as a durable record that may be updated across invocations:

stage=cpu creates/updates jobs.cpu_precompute
stage=gpu appends/updates jobs.gpu
stage=all updates both

We also keep a submission ‘history’ list so previous job ids are not lost.

Modules

`cli_cleanup`	Cleanup utility for BayesEoR sweep artefacts.
`cli_compare_sweeps`	Compare two BayesEoR sweep report summaries.
`cli_help`	Command index/help for BayesEoR ValSKA CLIs.
`cli_list_sweeps`	List available ValSKA BayesEoR sweep directories.
`cli_prepare`	Prepare a BayesEoR validation run "kit" under the ValSKA results directory.
`cli_report`	Generate summary plots/tables for a completed BayesEoR sweep.
`cli_report_all`	Generate BayesEoR reports for all discovered sweeps.
`cli_resume`	Suggest re-run commands for incomplete BayesEoR sweep points.
`cli_submit`	CLI entrypoint for submitting prepared BayesEoR runs.
`cli_sweep`	CLI entrypoint for preparing and optionally submitting BayesEoR sweeps.
`cli_sweep_audit`	Discover sweeps and run status/validation checks in one command.
`cli_sweep_status`	Show health/status summary for a BayesEoR sweep directory.
`cli_validate_sweep`	Validate BayesEoR sweep integrity and return policy-based exit code.
`constants`	Constants for the BayesEoR integration.
`report`	Sweep-level post-processing reports for BayesEoR runs.
`runner`	Runner abstractions for executing BayesEoR via conda or containers.
`setup`	Prepare BayesEoR run directories, configs, and submit scripts.
`slurm`	SLURM submit-script rendering for BayesEoR runs.
`submit`	Submission helpers for BayesEoR prepared run directories.
`sweep`	Sweep orchestration for BayesEoR perturbation studies.
`sweep_health`	Shared sweep health inspection for BayesEoR sweep directories.
`templates`	Access to bundled BayesEoR validation templates.