Installation

skasim supports two installation paths:

a pip-only path for lightweight use, including imports, configuration validation, CLI help, documentation builds, and lightweight tests;
a conda full-runtime path for executing simulations with Karabo, OSKAR, and the supported runtime stack.

Pip-only lightweight install

Use this path when you want to inspect the CLI, validate configuration, build the documentation, or run tests that do not execute Karabo simulations:

git clone git@github.com:espsrc/espsrc_ska_simulator.git
cd espsrc_ska_simulator
python -m pip install -e .

This install intentionally does not provide the full Karabo simulation runtime. Commands such as skasim --help should work, but running a simulation requires the conda environment below.

Conda full-runtime install

Use this procedure for simulation runs on the current development system. The environment is named skasim and uses Python 3.10, Karabo, OSKAR, and WSClean from conda packages. The editable pip install also installs Python dependencies from pyproject.toml, including shadems for UV-coverage plots:

conda create -y -n skasim python=3.10
conda install -y -n skasim --no-channel-priority \
  -c nvidia/label/cuda-11.7.0 \
  -c i4ds \
  -c conda-forge \
  karabo-pipeline "cuda-version=11.7"
conda run -n skasim pip install -e .

The --no-channel-priority option is needed because strict channel priority can block MPI/FFTW dependencies required by the Karabo runtime stack. The cuda-version=11.7 pin is also needed: the OSKAR build installed with Karabo expects CUDA 11 runtime libraries such as libcudart.so.11.0 and libcufft.so.10.

The checked-in environment.yml remains useful as a declaration of the intended runtime dependencies, but the command sequence above is the verified installation path on this machine.

WSClean

The conda full-runtime install above installs WSClean through the karabo-pipeline dependency set. On the verified skasim environment, karabo-pipeline depends on wsclean and Conda installs wsclean 3.5.0 from the i4ds channel.

WSClean checks whether OpenBLAS multi-threading is enabled and aborts if OPENBLAS_NUM_THREADS is not set to 1. The skasim pipeline sets this environment variable automatically before launching WSClean, so pipeline runs can succeed even when a direct shell command such as wsclean --version fails. To inspect WSClean directly, use:

conda run -n skasim env OPENBLAS_NUM_THREADS=1 wsclean --version

The WSClean command defaults to wsclean. If WSClean is available through a wrapper or container instead, pass it explicitly with --wsclean-command.

On this machine, the Singularity container can be used as an example:

skasim --imager wsclean \
  --wsclean-command "singularity exec /mnt/software/containers/wsclean-3.10-dysco.sif wsclean"

This command is an environment-specific example, not the default.

shadeMS

skasim uses shadems to generate the UV-coverage plot displayed beside the telescope layout in the weblog. shadems is installed from pip through the package dependencies. To inspect it directly, use:

conda run -n skasim shadems --help

The pipeline runs shadeMS with U and V axes, a square canvas, and writable Matplotlib/Numba cache directories inside the run output directory.

Verifying the installation

For the pip-only path, confirm that the CLI can be inspected:

skasim --help

For the conda full-runtime path, verify the installed runtime before running simulations:

conda run -n skasim python -c "import karabo, oskar; print('karabo', karabo.__version__); print('oskar ok')"
conda run -n skasim which oskar_sim_interferometer
conda run -n skasim which wsclean
conda run -n skasim which shadems
conda run -n skasim skasim --help

oskarpy is not required for the supported execution path; the successful import oskar check and a completed visibility simulation verify the OSKAR backend used by Karabo.

A small WSClean smoke run with the named MIGHTEE catalog is:

conda run -n skasim skasim \
  --output-dir smoke_mightee_wsclean_quick \
  --telescope MeerKAT \
  --observation-time 30 \
  --frequency-mhz 1300 \
  --bandwidth-mhz 25 \
  --n-channels 2 \
  --pixels 256 \
  --catalog MIGHTEE \
  --imager wsclean \
  --clean-iterations 20 \
  --overwrite

The verified smoke run completed with exit code 0 and wrote visibilities.MS, a shadeMS UV-coverage plot, WSClean FITS products, PNG previews, run_manifest.json, and weblog.html under smoke_mightee_wsclean_quick/.