User Guide

This guide explains the main configuration language for a skasim run.

The Configuration Model

Every simulation is defined by a single SimConfig object. It groups the telescope, observation, imaging, sky-model, noise, UV-coverage, and output settings in one validated document.

{
  "telescope": "SKA1MID",
  "telescope_version": "AA4",
  "observation": {
    "frequency_mhz": 1300,
    "bandwidth_mhz": 770,
    "n_channels": 64,
    "observation_time_s": 600,
    "phase_center_ra_deg": 0.0,
    "phase_center_dec_deg": -30.0
  },
  "imaging": [
    {"tag": "dirty", "imager": "oskar-dirty", "pixels": 1024},
    {
      "tag": "wsclean",
      "imager": "wsclean",
      "pixels": 1024,
      "clean_iterations": 10000,
      "robust": 0.0,
      "multiscale": true
    }
  ],
  "models": [
    {"type": "component_sky_model", "catalog": "MIGHTEE"}
  ],
  "output_dir": "my_run",
  "overwrite": true,
  "uv_coverage": true
}

The next sections describe each block.

SimConfig (top-level)

Top-level run settings:

  • telescope (str): Telescope name, e.g. SKA1MID, MeerKAT, SKA1LOW.

  • telescope_version (Optional[str]): Array-assembly version for telescopes that require one (e.g. AA0.5, AA1, AA4, AA* for SKA1-MID). Use skasim --show-telescopes to list accepted versions.

  • observation (ObsConfig): Observing setup.

  • imaging (list of ImgConfig): One or more imaging passes, each with a unique tag.

  • models (list of ModelEntry): Typed sky-model entries.

  • sky_file / catalog / fits_image (legacy): Single sky-model source used when models is empty.

  • source_flux_jy / stokes_q_jy / stokes_u_jy / stokes_v_jy: Generated point-source mode (used when no explicit sky model is supplied).

  • center (Optional[str]): Field centre as a sexagesimal string (e.g. "10h01m35.1s 2d41m41s"). Overrides the sky-model-derived centre.

  • rms / rms_value / rms_sigma (legacy noise toggle): Simple noise flag and level in Jy.

  • noise_rms_start / noise_rms_end (Optional[float]): OSKAR station-noise override in Jy. When set, the simulation uses a noise Range with these values instead of the telescope model noise.

  • uv_coverage (bool): Whether to run shadeMS and produce a UV-coverage plot.

  • shadems_command (str): Command used for shadeMS (default: shadems).

  • uv_coverage_canvas_size (int): Square canvas size for the UV-coverage plot.

  • output_dir (Optional[str]): Exact output directory. Defaults to YYYYMMDD_HHMMSS_<telescope>.

  • overwrite (bool): Remove an existing output directory before running.

  • title / description (Optional[str]): Human metadata shown in the weblog and manifest (config-file only, not CLI flags).

  • sky_format / column_mapping / flux_scale: Options shared with the legacy component-sky-model path.

ObsConfig

Observation parameters passed to Karabo:

  • frequency_mhz (float, default 700.0): Central observing frequency.

  • bandwidth_mhz / n_channels / channel_width_mhz (Optional): Spectral grid. If all three are omitted, defaults of 100 MHz, 8 channels, and 12.5 MHz are applied. If two are provided, the third is derived. If all three are provided, they must be consistent.

  • observation_time_s (int, default 600): Total observing duration in seconds.

  • phase_center_ra_deg / phase_center_dec_deg (Optional[float]): Phase centre in degrees. When omitted, the sky model centre is used.

  • start_time (Optional[datetime]): Observation start time. Defaults to the source culmination time computed by the pipeline.

ImgConfig

Imaging parameters for one pass:

  • tag (str, default "default"): Unique label for the pass. Used as the output subdirectory name and in the weblog.

  • imager (Literal): oskar-dirty or wsclean.

  • pixels (int, default 512): Image dimensions pixels × pixels (must be ≥ 64).

  • fov_deg (Optional[float]): Field of view in degrees. If omitted, the pipeline uses the diffraction-limited FoV for the telescope and frequency.

  • robust (float, default 0.0): Briggs robustness parameter for WSClean.

  • wsclean_command (str, default "wsclean"): Command prefix for WSClean. This can include extra native flags such as "wsclean -pol V".

  • clean_iterations (int, default 5000): CLEAN iteration limit for WSClean.

WSClean-only flags (ignored for oskar-dirty):

  • mgain (Optional[float]): Major-cycle gain. Default effective value 0.8.

  • multiscale (Optional[bool]): Enable multiscale CLEAN. None and True both enable it; False disables it.

  • multiscale_scales (Optional[List[int]]): Pixel scales for multiscale CLEAN.

  • auto_threshold (Optional[float]): Auto threshold sigma. Default 0.3.

  • auto_mask (Optional[float]): Auto mask sigma. Default 3.0.

  • local_rms (Optional[bool]): Enable -local-rms. Default off.

  • join_channels (Optional[bool]): Enable -join-channels. Default on.

  • channels_out (Optional[int]): Number of WSClean output channels. Defaults to the observation channel count (capped at 8 when derived internally).

  • padding (Optional[float]): WSClean padding factor.

  • threads (Optional[int]): WSClean parallel thread count (-j).

Sky Ingestion Models

Version 0.2 introduced a typed models API. A run can include one component_sky_model plus any number of image-model entries.

Component Models

Type: component_sky_model

Point-source / Gaussian component catalogs. Exactly one of path or catalog must be provided.

  • path: Path to a FITS table, JSON array/JSONL, pickle, or Karabo model file.

  • catalog: Named built-in catalog (MIGHTEE, GLEAM, SKAMid).

  • sky_format (Literal): auto, fits, json, pickle, random.

  • column_mapping (str): Comma-separated FITS column indices for id,ra,dec,I,Q,U,V,spec_index,ref_freq,rm,major,minor,pa. Default: "0,1,2,3,4,5,6,7,8,9,10,11,12".

  • flux_scale (float): Global multiplier applied to Stokes I fluxes.

Example (JSON config):

"models": [
  {
    "type": "component_sky_model",
    "catalog": "MIGHTEE"
  }
]

Image Models

Image-based models are injected via CASA ft into the MODEL_DATA column and then merged into DATA.

1. Continuum I + Alpha (continuum_i_alpha)

Injects a spatially extended source with a varying spectral index.

  • stokes_i: FITS image in Jy/pixel.

  • alpha: FITS spectral-index map on the same grid.

  • reference_frequency_hz: Frequency at which stokes_i is defined.

Semantics: \(I(\nu) = I_0 \cdot (\nu/\nu_0)^\alpha\).

2. CASA Taylor Terms (casa_taylor_terms)

Direct usage of existing CASA Taylor-term images (e.g. from a previous WSClean run).

  • tt0: Path to the CASA image table for Taylor term 0.

  • tt1: (Optional) Path to Taylor term 1.

  • reference_frequency_hz: Taylor expansion reference frequency.

3. Static Stokes Maps (static_stokes_maps)

Injects a spectrally flat, spatially extended Stokes-I model through wsclean -predict. skasim creates one FITS model plane per observation channel, using the observation spectral grid, then WSClean writes the predicted visibilities to MODEL_DATA.

  • stokes_i: Required 2D spatial FITS image in Jy/pixel. It is copied without flux scaling into every observation channel.

  • The FITS header must provide valid CDELT1 and CDELT2 pixel scales.

  • The image should be square. Non-square inputs are accepted with a warning, but WSClean predict uses the x dimension for both image dimensions and can distort the model.

  • The model frequency reference is the observation channel grid; there is no model-level reference-frequency parameter for this spectrally flat type.

Example (JSON config):

"models": [
  {
    "type": "static_stokes_maps",
    "stokes_i": "/path/to/model_i.fits"
  }
]

Warning

The schema also accepts stokes_q, stokes_u and stokes_v paths, but this implementation injects Stokes I only. Q/U/V planes are not yet validated or predicted; do not rely on them for polarized simulations.

Spectral Reference Policy

When using image models, skasim automatically adjusts the model’s spectral reference to the centre of the observed band.

  • Idempotency: The original model files are never modified. The pipeline works on local copies in the work_dir.

  • Correction: If a spectral index is provided (via alpha map or tt1), pixel values are scaled using the power-law convention: \(tt0' = tt0 \cdot (\nu_{new} / \nu_{old})^\alpha\).

  • Metadata: The single-channel spectral coordinate (CRVAL4) of the local CASA images is updated to the observation’s centre frequency.

Generated Source Fluxes (Legacy Mode)

If no typed models are provided, skasim can generate point sources using legacy CLI flags:

skasim --flux-density 1.0 0.5 --observation-time 120

Warning

Generated source flags are ignored if the models list is used.

Multi-Imaging Runs

imaging is a list, so several passes can be produced from a single visibility set:

"imaging": [
  {"tag": "dirty", "imager": "oskar-dirty"},
  {"tag": "clean", "imager": "wsclean", "clean_iterations": 1000}
]

The CLI --imager flag overrides only the first entry; for full control over multiple passes, use a JSON config file.

WSClean Command

The WSClean command defaults to wsclean. For containerized environments, pass the command explicitly:

skasim --imager wsclean \
  --wsclean-command "singularity exec wsclean-3.10.sif wsclean"

The wsclean_command field also accepts native WSClean flags that do not have a first-class ImgConfig field, for example polarization selection:

{"wsclean_command": "wsclean -pol V"}

Run Records

Each run writes a Manifest and an Always-on Weblog.

Note

See the Run Outputs and Records section for detailed information on run records.