Command-line interface

The simms command is a click group chaining three subcommands: telsim, skysim, and primary-beam. Global options (--ms, --log-level, --chain) precede the subcommand:

$ simms [--log-level LEVEL] [--ms FILE --chain] COMMAND ...

Pass --chain on the group to run telsim and skysim back to back against one MS given once at the top level (--ms is then dropped from the subcommands):

$ simms --ms obs.ms --chain telsim --telescope kat-7 skysim --ascii-sky sky.txt

simms

Tools for simulating radio interferometry observations. ‘telsim’ creates a simulated observation (Measurement Set; MS), and ‘skysim’ populates an MS with visibilities generated from a given skymodel (FITS or ASCII format). For more info on the tools run:

simms telsim –help

simms skysim –help

Usage

simms [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Options

--version

Show the version and exit.

-ms, --ms <ms>

-ll, --log-level <log_level>

Log level

Options:

INFO | WARNING | CRITICAL | ERROR

--chain

Chain telsim and skysim for an End-to-End simulation. When this option is set, the -ms/–ms has to be given in the main command and excluded from both sub-commands

primary-beam

Usage

simms primary-beam [OPTIONS] str

Options

-bp, --beam-pattern <str>

Beam model: a cosine-taper CSV path, a built-in name (e.g. MKAT-EA-L-JIM-2026), a band shorthand (L/UHF), or a FITS beam cube (.fits). Used by to-fits/apply/correct.

--beam-band <str>

Default band for a built-in beam when beam-pattern omits one.

Options:

UHF | L

--beam-pa-step <float>

Parallactic-angle sampling step (degrees) for the time-averaged beam.

--ms <MS>

Measurement set (time/parallactic-angle range, array position and frequencies). Required for tag-ms/apply/correct.

-fits, --fits-sky <File>

Input FITS image sky model (apply/correct).

-ascii, --ascii-sky <File>

Input ASCII component sky model (apply/correct).

-ad, --ascii-delimiter <str>

Delimiter used in the ascii-sky file. Defaults to whitespace.

--source-schema <File>

Custom source schema (YAML) mapping the ascii-sky columns to the fields simms expects, as for skysim. Defaults to the built-in simms source schema.

-o, --output <str>

Output path - FITS beam (to-fits) or beamed/corrected sky model (apply/correct).

-tnc, --telescope-name-column <str>

ANTENNA-table column holding the per-antenna telescope/type label (tag-ms).

--label <str>

Single telescope-name label applied to all antennas (tag-ms).

--label-map <File>

YAML mapping antenna NAME -> telescope-name label (tag-ms).

--from-layout <str>

simms layout whose per-antenna telescope_name is matched to the MS antenna names (tag-ms).

--pb-cutoff <float>

In correct mode, blank (NaN) where the beam is below this level.

-fi, --field-id <int>

FIELD_ID whose phase centre and time span define the beam (apply/correct).

--spw-id <int>

Spectral-window (DATA_DESC_ID) whose frequencies define the beam (apply/correct).

--pixel-size <str>

Angular pixel size for the to-fits grid, e.g. “1arcmin” or “0.02deg”.

--npix <int>

Number of pixels per side for the to-fits grid.

-sf, --start-freq <str>

Start frequency of the to-fits cube, e.g. “856MHz”. Defaults to the beam’s first tabulated frequency.

-cw, --chan-width <str>

Channel width of the to-fits cube, e.g. “10MHz”. Defaults to spanning the beam’s frequency range across –nchan.

-nc, --nchan <int>

Number of output channels in the to-fits cube. Defaults to the beam’s tabulated channel count.

--nworkers <int>

Number of worker threads.

Arguments

str

Required argument

skysim

Usage

simms skysim [OPTIONS] MS

Options

-as, --ascii-sky <File>

Catalogue of sources. A full description of accepted units can be found in the documentation.

-fs, --fits-sky <Union[File, List[File>

FITS file(s) containing the sky model

-ws, --wsclean-sky <File>

WSClean component list (point and Gaussian components, Stokes I).

-fsi, --fits-sky-interp <str>

Interpolation method when the MS and FITS frequency grids do not match and the cube is kept. ‘nearest’ costs about 1e-3 in flux; prefer an analytic spectrum (–fits-spectrum poly) where the spectrum allows it.

Options:

nearest | linear | cubic

-pol, --polarisation, --no-polarisation

Simulate all available stokes parameters (correlations). If false, only consider stokes I

--pol-basis <str>

Polarization basis for the simulation. The default is circular polarization.

Options:

linear | circular

-pt, --pixel-tol <float>

minimum brightness for a pixel to be considered in direct Fourier transform

-fsp, --fits-spectrum <str>

How the FITS sky model varies with frequency. ‘flat’ is one frequency-independent plane; ‘poly’ is a flux at a reference frequency times a per-pixel log-polynomial; ‘cube’ keeps the explicit planes. ‘auto’ fits a log-polynomial to a cube and falls back to the cube when the fit is poor.

Options:

auto | flat | poly | cube

--fits-spi <str,str,...>

Spectral-index (and higher-order) coefficient maps, ordered c1, c2, … Given these, the spectrum is analytic and nothing is fitted. Requires –fits-ref-freq.

-frf, --fits-ref-freq <float>

Reference frequency (Hz) of an analytic FITS spectrum. Defaults to the MS band centre.

--fits-spectrum-order <int>

Order of the fitted log-polynomial spectrum. 1 is a plain spectral index.

-pb, --predict-backend <str>

Backend for FITS sky model prediction. ‘dft’ is exact for any projection; ‘fft’ grids the image, reprojecting to SIN when necessary; ‘perchan’ predicts a cube one channel at a time, skipping empty channels and choosing dft or fft per channel. ‘auto’ uses ‘perchan’ for a cube and the cheaper of dft/fft for a single-plane model.

Options:

auto | dft | fft | perchan

--fft-precision <str>

Precision of the FFT calculation. The default is double precision.

Options:

single | double

--do-wstacking, --no-do-wstacking

Whether to use w-stacking for FFT-based visibility prediction.

-ad, --ascii-delimiter <str>

Delimiter that is used in the ascii-sky

-col, --column <str>

Data column for simulation

--nworkers <int>

Number of workers (one per CPU)

-rcs, --row-chunks <int>

Number of rows per chunk. Controls the row-wise task/memory granularity.

-ccs, --chan-chunks <int>

Number of channels per chunk. Defaults to all channels in one chunk.

-pb, --primary-beam <File>

Path to a beam-config YAML mapping each ANTENNA TELESCOPE_NAME to a beam model (e.g. “MK: {jimbeam: L}”). Applies a per-antenna, parallactic-rotating primary beam to component skies (ASCII/WSClean). Requires a linear pol basis.

--beam-band <str>

Default band for JimBeam entries that omit an explicit model/CSV.

Options:

UHF | L

--beam-pa-step <float>

Spacing (degrees) of the parallactic-angle grid the beam is sampled on and interpolated from. Smaller is more accurate but uses more memory/compute.

--beam-grid-max-gib <float>

Hard ceiling (GiB) on the sampled beam grid, which scales with parallactic-angle samples x sky components x channels and is held in memory for the whole run. skysim errors (rather than risking an out-of-memory kill) if the grid would exceed this; lower it with a coarser –beam-pa-step or fewer components.

--beam-jones <str>

Primary-beam application for component skies. “diagonal” applies a per-feed voltage (fast, linear correlations only). “full” applies the complete 2x2 E-Jones (models cross-hand leakage from FITS beam cubes and supports circular correlations); requires 4 correlations. Ignored on the FITS-image path.

Options:

diagonal | full

-tnc, --telescope-name-column <str>

Name of the ANTENNA-table column holding the per-antenna telescope/type label that maps to a beam model. Must match the column telsim wrote (default TELESCOPE_NAME). The primary beam requires this column; it is never inferred.

-fi, --field-id <int>

Field ID

--spw-id <int>

Spectral Window ID

--sefd <float>

Add noise using the this SEFD value

--seed <int>

Random seed for the thermal noise, reproducible across runs at a fixed chunking. Omit for a non-reproducible run.

-asp, --ascii-species <str>

Non-simms sky model type.

Options:

bdsf_gaul | aegean | wsclean

-ic, --input-column <str>

Input column (see option –mode)

--mode <str>

Simulation mode. To create a new column use “sim”; to add to column use “add”; to subtract from column use “subtract”.

Options:

sim | add | subtract

--source-schema <File>

Specify a custom source schema via a YAML file that specifies how to map columns in custom sky model to the columns expected by simms. See the bdsf_gaul schema file at ‘https://github.com/wits-cfa/simms/tree/main/simms/schemas’

Arguments

MS

Required argument

telsim

Usage

simms telsim [OPTIONS] MS

Options

-ls, --list

Dispalys a list of available telescope array layouts

-tel, --telescope <str>

Required Name of telescope you are simulating

-sublist, --subarray-list <str,str,...>

Custom list of antennas to use, e.g., M000,M005,SKA009. If specified, this must be a subarray of the given telescope.

-subrange, --subarray-range <int,int,...>

Custom range of antennas indices to use, e.g. start,end,step where step is optional. If specified, this must be a subarray of the given telescope.

-subfile, --subarray-file <File>

File with list of custom antennas to use, e.g., /path/to/subarray.yaml. File should contain antnames key, e.g., [M000,M005,SKA009]. This must be a subarray of the given telescope.

-tnc, --telescope-name-column <str>

Name of the ANTENNA-table column that holds the per-antenna telescope/type label (used by skysim to select a primary beam). Provisional spec; configurable so skysim can be pointed at the same name.

-dir, --direction <EPOCH,]RA,Dec>

Direction of field centre for MS. Example, J2000,0h24m20s,-30d12m33s or J2000,0:24:20,-30:12:33. Default is J2000,1h0m0s,-31d0m0s.

-st, --starttime <YYYY-MM-DDTHH:MM:SS>

Observation start time in UTC. For example, ‘2024-03-14T06:15:10’. Default is the current machine time.

-sha, --startha <float>

Hour angle at start of observation. Can be used instead of date.

-dt, --dtime <float>

Integration/exposure time in seconds. Default is 8 seconds.

-nt, --ntime <int>

Number of times slots for MS. Default is 10.

-sf, --startfreq <Union[str, float>

Centre of first frequency channel/bin, e.g 0.55GHz. If given without units, Hertz are assumed. Default is 1420MHz.

-df, --dfreq <Union[str, float>

Channel width and units, e.g 2.4MHz. If given without units, Hertz are assumed. Default is 1MHz.

-nc, --nchan <int>

Number of frequency channels. Default is 9.

-corr, --correlations <str>

Feed correlations for MS, e.g., ‘XX,YY’. Default is ‘XX,YY’.

--nworkers <int>

Number of workers (one per CPU). Default is 4.

-rc, --rowchunks <int>

Number of chunks to divide the data into, larger number of chunks improves the computation speed. Default is 50000.

-col, --column <str>

The column in which to corrupt the visibilities with noise. Default is MODEL_DATA column.

--sefd <float>

Antenna SEFD (one value for all frequencies)

-tos, --tsys-over-eta <float>

Antenna system temperature over aperture efficiency (one value for all frequencies)

-sfile, --sensitivity-file <File>

File with antenna spectral sensitivity information. Allowed keys (column names) are ‘freq, tsys, sefd, tsys_over_eta’

-lsl, --low-source-limit <float>

Minimum source elevation in degrees that is considered reliable data. The data recorded when the source is below this value is flagged.

-hsl, --high-source-limit <float>

Maximum source elevation in degrees that is considered reliable data. The data recorded when the source is above this value is flagged.

-fr, --freq-range <str>

A list containing the start frequency, end frequency, and number of channels, e.g., startfreq,endfreq,nchan.

--smooth <str>

If you have provided a sensitivity file with frequencies and their corresponding sefd or tsys_over_eta, then we will fit to get the approximate sefd matching the MS frequencies. There are two fitting options, polyn and spline.

-fo, --fit-order <int>

The fitting order to use when approximating the MS frequencies SEFDs.

Arguments

MS

Required argument