Sky Simulations (skysim)

simms.skymodel.fits_skies.compute_lm_coords(phase_centre: ndarray, n_ra: float, n_dec: float, ra_coords: ndarray = None, dec_coords: ndarray = None, tol_mask: ndarray = None)

Compute direction-cosine coordinates (l, m) for an image grid.

Parameters:

  • phase_centre (numpy.ndarray) – Array-like of shape (2,) with [ra0, dec0] of the phase-tracking centre in radians.

  • n_ra (int) – Number of pixels along right ascension (l-axis).

  • n_dec (int) – Number of pixels along declination (m-axis).

  • ra_coords (numpy.ndarray, optional) – 1D array of right ascension pixel coordinates in radians.

  • dec_coords (numpy.ndarray, optional) – 1D array of declination pixel coordinates in radians.

  • tol_mask (numpy.ndarray, optional) – Boolean mask of shape (n_ra * n_dec,) selecting pixels to keep. When provided, only the corresponding (l, m) rows are returned.

Returns:

Array of direction cosines: - If tol_mask is None, an array with the grid of (l, m) values with

shape (…, 2), where the last dimension stores (l, m).

  • If tol_mask is provided, a 2D array with shape (N, 2) containing only the selected (l, m) pairs.

Return type:

numpy.ndarray

Notes

The conversion from (ra, dec) to (l, m) is performed by simms.utilities.pix_radec2lm relative to the given phase centre. All angular quantities are in radians.

simms.skymodel.fits_skies.skymodel_from_fits(input_fitsimages: File | List[File], ra0: float, dec0: float, chan_freqs: ndarray, ms_delta_nu: float, ncorr: int, linear_basis: bool = True, tol: float = 1e-07, use_dft: bool | None = None, stack_axis='STOKES', interpolation='nearest') → tuple

Convert one or more FITS images into a brightness array usable for visibility prediction, optionally computing sparse (l, m) coordinates for DFT. Handles unit conversion, frequency interpolation, Stokes stacking, and sparsity-based selection between DFT and FFT workflows.

Parameters:

  • input_fitsimages (scabha.basetypes.File or list of File) – A single FITS image or an ordered list of FITS images (e.g., per Stokes).

  • ra0 (float) – Right ascension of the phase-tracking centre in radians.

  • dec0 (float) – Declination of the phase-tracking centre in radians.

  • chan_freqs (numpy.ndarray) – 1D array of MS channel centre frequencies in Hz.

  • ms_delta_nu (float) – MS channel width in Hz.

  • ncorr (int) – Number of output correlations (e.g., 1, 2, or 4).

  • linear_basis (bool, default True) – If True, output correlations are in the linear basis (XX, XY, YX, YY). If False, use the circular basis (RR, RL, LR, LL).

  • tol (float, default 1e-7) – Pixel brightness threshold used to select non-zero pixels for DFT. Units follow the FITS BUNIT after conversion (typically Jy).

  • use_dft (bool or None, optional) – Whether to force DFT (True) or FFT (False). If None, the choice is made based on the sparsity of the thresholded image (DFT if >= 80% zeros).

  • stack_axis (str or dict, default "STOKES") – Axis name to stack along when multiple input FITS images are provided. If a dict, it is passed to fitstoolz.reader.FitsData.add_axis().

  • interpolation ({"nearest", "linear", ...}, default "nearest") – Interpolation method used when regridding the FITS spectral axis to the MS frequencies.

Returns:

Container with the following fields: - image : numpy.ndarray

If DFT is selected or forced: shape (N_nonzero, N_freq, ncorr), containing only thresholded non-zero pixels. If FFT is selected: shape (n_pix_l, n_pix_m, N_freq, ncorr), the full image cube.

  • lmnumpy.ndarray or None

    If DFT is selected or forced: array of shape (N_nonzero, 2) with direction cosines (l, m) for the retained pixels. Otherwise None.

  • is_polarisedbool

    True if any of Q, U, V are present in the input.

  • expand_freq_dimbool

    True if the FITS image had a single frequency and should be expanded along the MS frequency axis downstream.

  • use_dftbool

    The final choice used for visibility prediction.

  • ra_pixel_sizefloat or None

    Pixel size along RA in radians for FFT workflows; None for DFT.

  • dec_pixel_sizefloat or None

    Pixel size along Dec in radians for FFT workflows; None for DFT.

Return type:

ObjDict

Raises:

  • TypeError – If stack_axis is neither a string nor a dict.

  • RuntimeError – If the requested stack_axis does not exist and cannot be added.

  • FITSSkymodelError – If the MS frequency range lies outside the FITS frequency coverage and interpolation is not possible.

Notes

  • FITS cubes with spectral coordinates in velocity (VRAD/VOPT) are converted to frequency using astropy.units and the Doppler convention.

  • If BUNIT is “Jy/beam”, beam areas are used to convert to Jy/pixel.

  • When spectral grids differ, the FITS image is interpolated onto the MS frequency grid, which can be memory intensive for large cubes.

class simms.skymodel.source_factory.SourceType(name: str, required: List[str] = <factory>, inherit: Any = None, surplus: List[str] = <factory>)

Bases: object

inherit: Any = None
is_valid(fields: List[str], raise_exception: bool = False, none_or_all: bool = False)
name: str
required: List[str]
surplus: List[str]
class simms.skymodel.source_factory.StokesData(data: List[int] | ndarray, linear_basis: bool | None = True)

Bases: object

Container for source/image Stokes intensity data.

Parameters:

  • data (list of int or numpy.ndarray) – Stokes parameter data ordered as I, Q, U, V (or IVQU when not linear).

  • linear_basis (bool, optional) – If True, the Stokes parameters are interpreted in a linear basis (I, Q, U, V). If False, they are interpreted in a circular basis (I, V, Q, U). Default is True.

property I
property Q
property U
property V
data: List[int] | ndarray
get_brightness_matrix(ncorr: int) → ndarray

Build the brightness (coherency) matrix.

Parameters:

ncorr (int) – Number of output correlations (2 or 4).

Returns:

Brightness matrix with the same shape as self.data except that the Stokes axis is replaced by a correlation axis of length ncorr. For ncorr == 2 the dtype is float; for ncorr == 4 the dtype is complex.

Return type:

numpy.ndarray

property is_polarised
linear_basis: bool | None = True
set_lightcurve(lightcurve_func: Callable, **kwargs)

Add a time axis using a lightcurve.

Parameters:

  • lightcurve_func (Callable) – Callable returning a 1D time-series array (shape (ntimes,)).

  • **kwargs – Additional keyword arguments forwarded to lightcurve_func.

Return type:

None

set_spectrum(freqs: ndarray, specfunc: Callable, full_pol: bool = True, **kwargs)

Add a spectral axis to the Stokes data.

Parameters:

  • freqs (numpy.ndarray) – Frequency array.

  • specfunc (Callable) – Callable with signature f(freqs, flux, **kwargs) returning the spectral profile.

  • full_pol (bool, optional) – If True, compute spectra for all four Stokes parameters. If False, only Stokes I is used. Default is True.

  • **kwargs – Additional keyword arguments forwarded to specfunc.

Return type:

None

class simms.skymodel.source_factory.StokesDataFits(coord: DataArray, dim_idx: int, data: ndarray, linear_basis: bool = True)

Bases: StokesData

property is_polarised
simms.skymodel.source_factory.contspec(freqs: ndarray, flux: float, coeff: float | ndarray | List, nu_ref: float)

Continuum (power-law) spectral profile.

Parameters:

  • freqs (numpy.ndarray) – Frequency array.

  • flux (float) – Reference flux density at nu_ref.

  • coeff (float or array-like) – Power-law coefficient(s). If array-like with length > 1, treated as polynomial coefficients of log-log curvature (via numpy.polynomial). If length == 1 or float, treated as spectral index.

  • nu_ref (float) – Reference frequency.

Returns:

Spectral profile evaluated at freqs.

Return type:

numpy.ndarray

simms.skymodel.source_factory.exoplanet_transient_logistic(start_time: int, end_time: int, ntimes: int, transient_start: int, transient_absorb: float, transient_ingress: int, transient_period: int)

Logistic transit lightcurve for an exoplanet-like transient.

Parameters:

  • start_time (int) – Start time of the observation (seconds).

  • end_time (int) – End time of the observation (seconds).

  • ntimes (int) – Number of time samples between start and end.

  • transient_start (int) – Time at which the transit begins (seconds).

  • transient_absorb (float) – Maximum fractional flux decrease during transit (e.g., 0.01 = 1% dip).

  • transient_ingress (int) – Duration of ingress/egress (seconds).

  • transient_period (int) – Total duration of the transit event, including ingress and egress (seconds).

Returns:

Normalized intensity time series of shape (ntimes,).

Return type:

numpy.ndarray

simms.skymodel.source_factory.gauss_1d(xaxis: ndarray, peak: float, width: float, x0: float)

Single Gaussian spectral line profile.

Parameters:

  • xaxis (numpy.ndarray) – Grid along the spectral axis.

  • peak (float) – Gaussian peak amplitude.

  • width (float) – Full width at half maximum (FWHM) in the same units as xaxis.

  • x0 (float) – Centre position of the Gaussian.

Returns:

Profile evaluated at xaxis.

Return type:

numpy.ndarray