Installation

skasim supports three installation paths:

  • a container image with the complete runtime (Karabo, OSKAR, WSClean, CASA, shadeMS) — the quickest way to run simulations;

  • 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.

Container image (Docker / Apptainer)

Released versions of skasim are published as a container image on the GitHub Container Registry:

docker pull ghcr.io/espsrc/skasim:0.5.0      # or :latest

The image contains skasim with the validated runtime stack (Python 3.12, Karabo 0.36, OSKAR 2.12, WSClean 3.6 with EveryBeam and Dysco, CASA 6.7 casatools/casatasks with its runtime data, and shadeMS). It contains no configurations, sky models or data: mount your working directory and reference files relative to it. The image’s command is skasim, and its working directory is /work:

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" \
  ghcr.io/espsrc/skasim:0.5.0 --config myconfig.json

--user makes the outputs belong to you rather than to root. Any command that does not start with - is run inside the activated environment instead of skasim, for example wsclean --version, python or bash:

docker run --rm -it -v "$PWD:/work" ghcr.io/espsrc/skasim:0.5.0 bash

Platforms and GPUs. The image is built for linux/amd64 only; on Apple Silicon it runs under emulation at best. It ships the CUDA 12 runtime used by Karabo and OSKAR, and falls back to the CPU when no GPU is visible. It has been validated on CPU only; GPU execution (docker run --gpus all ..., which needs the NVIDIA Container Toolkit and a driver supporting CUDA 12) is not yet tested.

HPC clusters. Where Docker is not available, Apptainer (Singularity) can run the same image:

apptainer pull skasim_0.5.0.sif docker://ghcr.io/espsrc/skasim:0.5.0
apptainer run --bind "$PWD:/work" --pwd /work skasim_0.5.0.sif --config myconfig.json

Apptainer already runs as your own user, so --user is not needed.

Licences. skasim is MIT-licensed, but the image also redistributes GPL-licensed software (WSClean, EveryBeam) and CASA under their own licences, so the image as a whole is subject to those terms. The full list is in /usr/share/doc/skasim/THIRD_PARTY_LICENSES.md inside the image and in docker/THIRD_PARTY_LICENSES.md in the repository.

Maintainers. The image recipe lives in docker/. Pushing a release tag vX.Y.Z builds, smoke-tests and publishes :X.Y.Z and :latest; the Docker image workflow can also be run manually for an existing tag. After changing environment.yml or the dependencies in pyproject.toml, regenerate the lockfiles with docker/update-lock.sh (requires Docker only).

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 outside the container. The checked-in environment.yml declares the validated cluster runtime: Python 3.12, karabo-pipeline 0.36.0 (which no longer depends on RASCIL), OSKAR 2.12.2 from the i4ds/label/dev channel, and the CUDA 12 runtime. The editable pip install also installs Python dependencies from pyproject.toml, including shadems for UV-coverage plots:

conda env create -f environment.yml
conda activate skasim

Use flexible channel priority (conda config --set channel_priority flexible) if the solve fails: Karabo comes from i4ds while OSKAR comes from i4ds/label/dev, and strict channel priority can also block MPI/FFTW dependencies required by the Karabo runtime stack.

The exact package versions used by the container image are pinned in docker/conda-linux-64.lock and docker/requirements-pip.lock.

WSClean

The conda full-runtime install above installs WSClean through the karabo-pipeline dependency set: Karabo 0.36 depends on wsclean and Conda installs WSClean 3.6, with EveryBeam and Dysco support, 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/.