API Reference
Public Python API for skasim configuration.
- class skasim.ImgConfig(**data)[source]
Bases:
BaseModelimaging parameters passed to OSKAR / WSClean.
WSClean-specific flags (mgain, multiscale, auto-threshold, etc.) are ignored when
imagerisoskar-dirty; they only affect argv building forwsclean.Geometry triplet:
fov_deg,pixels,cell_size_arcsecare linked. Any two determine the third. A fully specified triplet must satisfyfov_deg == pixels * cell_size_arcsec / 3600within a relative tolerance of1e-6. Omitting all three selects the legacy defaults and emits a deprecation warning.- auto_mask: Optional[float]
- auto_threshold: Optional[float]
- cell_size_arcsec: Optional[float]
- channels_out: Optional[int]
- clean_iterations: int
- fov_deg: Optional[float]
- imager: Literal['oskar-dirty', 'wsclean']
- join_channels: Optional[bool]
- local_rms: Optional[bool]
- mgain: Optional[float]
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- multiscale: Optional[bool]
- multiscale_scales: Optional[list[int]]
- padding: Optional[float]
- pixels: int
- resolve_geometry(diffraction_fov_deg, theoretical_beam_arcsec, reference_frequency_hz)[source]
Resolve this block’s geometry against the observation-level beam.
- Return type:
ImageGeometry
- robust: float
- spectral_mode: Literal['auto', 'cube', 'continuum']
- tag: str
- threads: Optional[int]
- wsclean_command: str
- wsclean_predict_command: Optional[str]
- class skasim.ObsConfig(**data)[source]
Bases:
BaseModelobservation parameters for Karabo.
- bandwidth_mhz: Optional[float]
- channel_width_mhz: Optional[float]
- frequency_mhz: float
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- n_channels: Optional[int]
- observation_time_s: int
- phase_center_dec_deg: Optional[float]
- phase_center_ra_deg: Optional[float]
- start_time: Optional[datetime]
- class skasim.SimConfig(**data)[source]
Bases:
BaseModelsimulation settings.
- catalog: Optional[CatalogName]
- center: Optional[str]
- column_mapping: Optional[str]
- description: Optional[str]
- fits_image: Optional[str]
- flux_scale: float
- imaging: list[ImgConfig]
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- models: list[ModelEntry]
- noise_injection: NoiseInjectionConfig
- noise_rms_end: Optional[float]
- noise_rms_start: Optional[float]
- observation: ObsConfig
- output_dir: Optional[str]
- overwrite: bool
- rms: bool
- rms_sigma: float
- rms_value: float
- shadems_command: str
- sky_file: Optional[str]
- sky_format: Literal['auto', 'fits', 'json', 'pickle', 'random']
- source_flux_jy: Optional[list[float]]
- stokes_q_jy: Optional[list[float]]
- stokes_u_jy: Optional[list[float]]
- stokes_v_jy: Optional[list[float]]
- telescope: str
- telescope_version: Optional[str]
- title: Optional[str]
- uv_coverage: bool
- uv_coverage_canvas_size: int
skasim.config
- class skasim.config.CasaTaylorTermsModelEntry(**data)[source]
Bases:
BaseModelExisting CASA Taylor-term image model set.
This entry type currently only supports the legacy CASA
ftbackend. Awsclean_predictbackend is planned but not yet implemented; theinjection_backendfield is reserved for future use and defaults tocasa_ft.- injection_backend: Literal['casa_ft']
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- reference_frequency_hz: float
- tt0: str
- tt1: Optional[str]
- type: Literal['casa_taylor_terms']
- class skasim.config.ComponentSkyModelEntry(**data)[source]
Bases:
BaseModelExisting catalog/component sky-model entry.
- catalog: Optional[CatalogName]
- column_mapping: Optional[str]
- flux_scale: float
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- path: Optional[str]
- sky_format: Literal['auto', 'fits', 'json', 'pickle', 'random']
- type: Literal['component_sky_model']
- class skasim.config.ContinuumIAlphaModelEntry(**data)[source]
Bases:
BaseModelContinuum image model with a spatially varying spectral index.
- alpha: str
- injection_backend: Literal['wsclean_predict', 'casa_ft']
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- reference_frequency_hz: float
- stokes_i: str
- type: Literal['continuum_i_alpha']
- class skasim.config.ImgConfig(**data)[source]
Bases:
BaseModelimaging parameters passed to OSKAR / WSClean.
WSClean-specific flags (mgain, multiscale, auto-threshold, etc.) are ignored when
imagerisoskar-dirty; they only affect argv building forwsclean.Geometry triplet:
fov_deg,pixels,cell_size_arcsecare linked. Any two determine the third. A fully specified triplet must satisfyfov_deg == pixels * cell_size_arcsec / 3600within a relative tolerance of1e-6. Omitting all three selects the legacy defaults and emits a deprecation warning.- auto_mask: Optional[float]
- auto_threshold: Optional[float]
- cell_size_arcsec: Optional[float]
- channels_out: Optional[int]
- clean_iterations: int
- fov_deg: Optional[float]
- imager: Literal['oskar-dirty', 'wsclean']
- join_channels: Optional[bool]
- local_rms: Optional[bool]
- mgain: Optional[float]
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- multiscale: Optional[bool]
- multiscale_scales: Optional[list[int]]
- padding: Optional[float]
- pixels: int
- resolve_geometry(diffraction_fov_deg, theoretical_beam_arcsec, reference_frequency_hz)[source]
Resolve this block’s geometry against the observation-level beam.
- Return type:
ImageGeometry
- robust: float
- spectral_mode: Literal['auto', 'cube', 'continuum']
- tag: str
- threads: Optional[int]
- wsclean_command: str
- wsclean_predict_command: Optional[str]
- class skasim.config.NoiseInjectionConfig(**data)[source]
Bases:
BaseModelRealistic thermal-noise injection parameters.
When enabled, OSKAR simulates without noise and this module injects per-baseline Gaussian noise computed from per-antenna SEFDs using the radiometer equation (Radcliffe et al. 2024, eq. 1).
- enabled: bool
- eta_c: float
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- sefd_file: Optional[str]
- class skasim.config.ObsConfig(**data)[source]
Bases:
BaseModelobservation parameters for Karabo.
- bandwidth_mhz: Optional[float]
- channel_width_mhz: Optional[float]
- frequency_mhz: float
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- n_channels: Optional[int]
- observation_time_s: int
- phase_center_dec_deg: Optional[float]
- phase_center_ra_deg: Optional[float]
- start_time: Optional[datetime]
- class skasim.config.SimConfig(**data)[source]
Bases:
BaseModelsimulation settings.
- catalog: Optional[CatalogName]
- center: Optional[str]
- column_mapping: Optional[str]
- description: Optional[str]
- fits_image: Optional[str]
- flux_scale: float
- imaging: list[ImgConfig]
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- models: list[ModelEntry]
- noise_injection: NoiseInjectionConfig
- noise_rms_end: Optional[float]
- noise_rms_start: Optional[float]
- observation: ObsConfig
- output_dir: Optional[str]
- overwrite: bool
- rms: bool
- rms_sigma: float
- rms_value: float
- shadems_command: str
- sky_file: Optional[str]
- sky_format: Literal['auto', 'fits', 'json', 'pickle', 'random']
- source_flux_jy: Optional[list[float]]
- stokes_q_jy: Optional[list[float]]
- stokes_u_jy: Optional[list[float]]
- stokes_v_jy: Optional[list[float]]
- telescope: str
- telescope_version: Optional[str]
- title: Optional[str]
- uv_coverage: bool
- uv_coverage_canvas_size: int
- class skasim.config.SpectralCubeModelEntry(**data)[source]
Bases:
BaseModel3D spectral-line cube (RA, Dec, FREQ) in Stokes I.
The cube describes the sky and may have a much finer spectral grid than the observation. Validation only checks that the observed channel centres lie inside the cube’s frequency extent and that the spatial dimensions match the imaging configuration. The optional
reference_frequency_hz,channel_width_hzandn_channelsfields are accepted for backward compatibility but are ignored; the FITS header is authoritative.- channel_width_hz: Optional[float]
- cube: str
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- n_channels: Optional[int]
- reference_frequency_hz: Optional[float]
- type: Literal['spectral_cube']
- class skasim.config.StaticStokesMapsModelEntry(**data)[source]
Bases:
BaseModelStatic Stokes map set. Currently Stokes I only via wsclean_predict.
- model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- stokes_i: str
- stokes_q: Optional[str]
- stokes_u: Optional[str]
- stokes_v: Optional[str]
- type: Literal['static_stokes_maps']
- skasim.config.has_spectral_cube_model(config)[source]
Return True if the simulation contains a spectral_cube model entry.
- Return type:
bool
skasim.cli
cli.py — command-line entry point (adapted from synthsim.py)
skasim.pipeline
pipeline.py — end-to-end interferometric simulation orchestrator.
- skasim.pipeline.build_observation(ctx, center, telescope, sky_center=None)[source]
Return (observation, frequency, bandwidth, n_channels, delta_freq, start_freq).
sky_centeris the sky model’s own centre, before anySimConfig.centeroverride is applied tocenter. When omitted it defaults tocenter, so a caller that doesn’t track the pre-override centre simply reports no drift.- Return type:
tuple
- skasim.pipeline.build_sky_model(ctx, fov)[source]
Return (sky_model, center).
- Return type:
tuple[SkyModel,SkyCoord]
- skasim.pipeline.build_zero_flux_sky_model(center)[source]
Build a one-source zero-flux sky model for base-MS fallback creation.
- Return type:
- skasim.pipeline.catalogue_beam_flux(table, center, beam)[source]
Total catalogue Stokes I at the beam reference frequency, with and without beam.
Sources with a positive reference frequency are scaled with their spectral index,
I (nu0 / nu_ref)^alpha; others are taken as flat.- Return type:
dict
- skasim.pipeline.catalogue_source_table(sky_model)[source]
Return
(ra_deg, dec_deg, stokes_i_jy, ref_freq_hz, spectral_index).Columns follow the Karabo/OSKAR source array (
ra, dec, I, Q, U, V, ref_freq, spectral_index, ...); missing spectral columns are zero. ReturnsNonewhen the model has no readable source array.- Return type:
Optional[Tuple[ndarray,...]]
- skasim.pipeline.compute_fov(telescope, fov_deg, frequency)[source]
return FoV in radians. If fov_deg is set, use it; else diffraction limit.
- Return type:
Quantity
- skasim.pipeline.maximum_baseline_m(telescope)[source]
Return Karabo’s maximum antenna separation in metres.
- Return type:
float
- skasim.pipeline.phase_centre_rule(config)[source]
Name the rule that decides the phase centre for this run.
Precedence: explicit
center→ catalogue (typed component entry or a legacy sky file / catalog / FITS catalogue) → first image model with a usable WCS → default field (image models without WCS centre) → generated sources.- Return type:
str
- skasim.pipeline.resolve_telescope_version(telescope_module, telescope, version)[source]
Resolve a CLI/config telescope version string to Karabo’s enum member.
- skasim.pipeline.run(config)[source]
Execute the full simulation pipeline from a SimConfig.
- Return type:
None
- skasim.pipeline.run_beam(fov_sim, freq)[source]
Return the Gaussian beam OSKAR applies to the catalogue for this run.
The same beam is applied to every image model before WSClean prediction so all sky components share one attenuation (see
skasim.primary_beam).- Return type:
GaussianStationBeam
skasim.imaging
imaging.py — dirty (OSKAR) and cleaned (WSClean) imaging wrappers.
- skasim.imaging.build_wsclean_argv(img_config, visibility_path, fov, output_prefix, n_channels=1)[source]
Build a shell-free WSClean argv list from the resolved imaging config.
- Return type:
list[str]
- skasim.imaging.collect_wsclean_outputs(work_dir, output_prefix)[source]
Collect WSClean FITS outputs for one configured output prefix.
- Return type:
list[Path]
- skasim.imaging.effective_wsclean_channels_out(img_config, n_channels)[source]
Return the
-channels-outvaluebuild_wsclean_argvwill use.- Return type:
int
- skasim.imaging.resolve_wsclean_img_config(img_config, spectral_mode, n_channels)[source]
Return the WSClean settings actually used for one imaging block.
cube: per-channel imaging (see_resolve_spectral_cube_wsclean_config).explicit
continuum: a single image of all channels combined (channels_out=1, no channel joining) unlesschannels_outis set.autoresolving to continuum: the settings are used unchanged.
- Return type:
- skasim.imaging.run_dirty_imaging(ctx, visibility_path, fov, center, img_config, sub_dir)[source]
produce dirty image via OSKAR.
- Return type:
None
- skasim.imaging.run_wsclean_command(argv, work_dir)[source]
Run WSClean with argv and an explicit working directory.
Streams stdout/stderr line-by-line through loguru so that WSClean progress appears in the skasim logs in real time.
- skasim.imaging.run_wsclean_imaging(ctx, visibility_path, fov, img_config, sub_dir, n_channels=1)[source]
produce cleaned image via external WSClean binary.
- Return type:
None
- skasim.imaging.stack_channels(channel_paths, output_path)[source]
Stack WSClean per-channel FITS images into a single 3D spectral cube.
Uses the same logic as
scripts/wsclean_channels_to_cube.pybut inlined here so it works without puttingscripts/onPYTHONPATH.- Return type:
None
- skasim.imaging.write_fits_preview(img_path, png_path, title, recenter=None, scale_factor=1000.0, bunit='mJy/beam', colorbar_label='mJy/beam')[source]
Write a publication-style PNG preview for a WSClean FITS image, optionally recentered.
- Return type:
None
- skasim.imaging.write_psf_profile_preview(psf_path, png_path, title='Point spread function')[source]
Write a PSF preview with 1D x/y cuts through the peak, to judge gaussianity.
The 2D panel shows the PSF core; the two line panels are slices through the peak along x and y so an asymmetric or non-Gaussian main lobe (a common sign of poor UV coverage or excessive weighting) is visible by eye.
- Return type:
None
- skasim.imaging.write_sky_model_previews(sky_model, center, fov, work_dir, run_id)[source]
Write full and FoV sky-model source previews.
- Return type:
list[tuple[str,str]]
- skasim.imaging.wsclean_output_prefix(ctx)[source]
Return the stable WSClean output prefix for this run.
- Return type:
str
- skasim.imaging.wsclean_product_name(filename, output_prefix)[source]
Split a WSClean output name into
(product, per_channel).WSClean names outputs
<prefix>-<product>with-channels-out 1, and<prefix>-NNNN-<product>per channel plus<prefix>-MFS-<product>otherwise.productis e.g.imageorpsf(extension removed); it isNonewhen the name does not start with<prefix>-, in which caseper_channelfalls back to spotting a-NNNN-index.- Return type:
tuple[str|None,bool]
skasim.sky
- class skasim.sky.SkyModel(*args: Any, **kwargs: Any)[source]
Bases:
SkyModel- static from_fits(fits_file, total_intensity=<Quantity 1. Jy>, fov=<Quantity 1. deg>, frequency=<Quantity 1. GHz>, log_file='sky_model.log', prefix='sky_model', t0=0)[source]
Load a SkyModel from a FITS file. Parameters: - fits_file: Path to the FITS file. Returns: - SkyModel object.
- static from_fits_table(fits_file, log_file='sky_model.log', prefix='sky_model')[source]
Load a SkyModel from a FITS table file. Parameters: - fits_file: Path to the FITS file. Returns: - SkyModel object.
- phase_center = None
- class skasim.sky.Source(ra, dec, I, Q=<Quantity 0. Jy>, U=<Quantity 0. Jy>, V=<Quantity 0. Jy>, ref_freq=<Quantity 0. Hz>, spec_index=0, rot_meas=<Quantity 0. rad / m2>, major_axis=<Quantity 0. arcsec>, minor_axis=<Quantity 0. arcsec>, pa=<Quantity 0. deg>, true_redshift=0, obs_redshift=0, obj_id=None, resolved=False, isl_rms=<Quantity 0. Jy>)[source]
Bases:
object- property flux
- static from_array(array, colnames=['ra', 'dec', 'I', 'Q', 'U', 'V', 'ref_freq', 'spec_index', 'rot_meas', 'major_axis', 'minor_axis', 'pa', 'true_redshift', 'obs_redshift', 'resolved', 'isl_rms'])[source]
- static from_sky_model(data)[source]
Reconstruct Source from 14-element tuple (inverse of to_sky_model).
- get_best_observation_time(telescope, date=None)[source]
Return the UTC time of maximum source elevation on the requested date.
Parameters: - ra_hours: Right Ascension in hours (float) - dec_degrees: Declination in degrees (float) - lat_deg: Observer’s latitude in degrees (float) - lon_deg: Observer’s longitude in degrees (float, positive to the East) - elevation_m: Altitude above sea level (optional) - date: Date as a string ‘YYYY-MM-DD’ (optional, defaults to today if not provided) - timezone_offset: Time difference relative to UTC (e.g., -6 for CDMX)
Returns: - Best time.
skasim.noise
Realistic thermal-noise injection into measurement-set visibilities.
- Implements the radiometer equation from Radcliffe et al. (2024), MNRAS 527, 942:
sigma_pq = (1/eta_c) * sqrt(SEFD_p * SEFD_q / (2 * t_int * delta_nu))
sigma_pq is the noise in the real or imaginary part of one visibility (Wrobel & Walker convention). The injected noise is circularly complex Gaussian with zero mean: the real and imaginary parts are independent and each has standard deviation sigma_pq, so the complex visibility has total variance 2 * sigma_pq^2.
- skasim.noise.compute_baseline_sigma(sefd, eta_c, t_int_s, delta_nu_hz)[source]
Compute per-baseline noise standard deviation.
- Return type:
dict[tuple[int,int],float]
Parameters
- sefdnp.ndarray
SEFD values in Jy, one per antenna, indexed by ANTENNA index.
- eta_cfloat
System efficiency factor.
- t_int_sfloat
Integration time in seconds.
- delta_nu_hzfloat
Channel bandwidth in Hz.
Returns
dict mapping (ant1, ant2) -> sigma_pq (Jy).
- skasim.noise.inject_noise(ms_path, sefd_antennas, delta_nu_hz, eta_c=0.88, chunk_rows=5000, random_seed=None)[source]
Inject realistic thermal noise into the DATA column of a measurement set.
- Return type:
dict
Parameters
- ms_pathstr | Path
Path to the MS to modify (read-write).
- sefd_antennaslist[dict]
Loaded SEFD antenna metadata from load_sefd_file().
- eta_cfloat, optional
System efficiency factor. Default 0.88.
- delta_nu_hzfloat
Channel bandwidth in Hz.
- chunk_rowsint, optional
Number of rows to process per I/O chunk. Default 5000.
- random_seedint, optional
If provided, seed the RNG for reproducible noise.
Returns
dict with summary statistics (min_sigma, max_sigma, mean_sigma, n_rows).
skasim.manifest
manifest.py — Pydantic models for run manifest, milestone tracking, and pipeline context.
- class skasim.manifest.Milestone(**data)[source]
Bases:
BaseModelsingle checkpoint in a simulation run.
- details: dict
- elapsed_s: Optional[float]
- model_config: ClassVar[ConfigDict] = {}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- name: str
- status: Literal['started', 'completed', 'failed']
- timestamp_utc: datetime
- class skasim.manifest.OutputRecord(**data)[source]
Bases:
BaseModelOne output produced by a run.
- image_product_id: Optional[str]
- imager: Optional[str]
- kind: OutputKind
- metadata: dict
- model_config: ClassVar[ConfigDict] = {}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- path: str
- role: Optional[str]
- class skasim.manifest.RunContext(**data)[source]
Bases:
BaseModelpassed through all pipeline functions; bundles config, paths, and manifest.
- add_milestone(*args, **kwargs)[source]
convenience: add milestone to manifest and persist to disk.
- Return type:
- config: SimConfig
- log_path: Path
- manifest: RunManifest
- manifest_path: Path
- model_config: ClassVar[ConfigDict] = {}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- sky_file_resolved: Optional[Path]
- visibility_path: Path
- weblog_path: Path
- work_dir: Path
- class skasim.manifest.RunManifest(**data)[source]
Bases:
BaseModelcanonical machine-readable record of one simulation run.
- add_milestone(name, status, elapsed_s=None, details=None)[source]
append a milestone and return it.
- Return type:
- add_output(kind, path, image_product_id=None, imager=None, role=None, metadata=None)[source]
append a structured output record and return it.
- Return type:
- completed_at: Optional[datetime]
- config: SimConfig
- errors: list[str]
- invocation: Optional[list[str]]
- milestones: list[Milestone]
- model_config: ClassVar[ConfigDict] = {}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- outputs: list[OutputRecord]
- run_id: str
- started_at: datetime
- status: Literal['running', 'completed', 'failed']
skasim.runtime
Runtime dependency helpers.
- exception skasim.runtime.CasacoreRuntimeError[source]
Bases:
RuntimeErrorRaised when CASA image-table manipulation needs python-casacore but it is unavailable.
- exception skasim.runtime.KaraboRuntimeError[source]
Bases:
RuntimeErrorRaised when full simulation execution needs Karabo but it is unavailable.
- exception skasim.runtime.OskarRuntimeError[source]
Bases:
RuntimeErrorRaised when FITS image ingestion needs OSKAR but it is unavailable.
- skasim.runtime.require_casacore()[source]
Import casacore.tables and provide a clear runtime error if unavailable.
skasim.utils
helpers extracted from legacy scripts/utils.py.
- class skasim.utils.NpEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]
Bases:
JSONEncoder- default(obj)[source]
Implement this method in a subclass such that it returns a serializable object for
o, or calls the base implementation (to raise aTypeError).For example, to support arbitrary iterators, you could implement default like this:
def default(self, o): try: iterable = iter(o) except TypeError: pass else: return list(iterable) # Let the base class default method raise the TypeError return super().default(o)
- skasim.utils.build_shadems_uv_coverage_argv(shadems_command, visibility_path, output_dir, png_name, title, canvas_size=600)[source]
Build a shell-free shadeMS argv list for a U/V coverage plot.
- Return type:
list[str]
- skasim.utils.init_logger(log_file=None)[source]
Cconfigure loguru: stderr + optional log file.
- Return type:
None
skasim.loaders
skasim.loaders — Loaders that produce SkyModel from external sources.
- class skasim.loaders.CasaModelProduct(model_paths, nterms, reffreq, intermediates, cube_data=None, header=None, freq_axis=None, model_dir=None)[source]
Bases:
objectCASA-ready model product generated from one model entry.
-
cube_data:
ndarray|None= None
-
freq_axis:
int|None= None
-
header:
Header|None= None
-
intermediates:
list[Path]
-
model_dir:
Path|None= None
-
model_paths:
list[Path]
-
nterms:
int
-
reffreq:
str
-
cube_data:
- class skasim.loaders.FitsCatalogLoader(fpath, column_mapping, scale_I=1.0, ref_freq_hz=None, frequency=None)[source]
Bases:
objectLoad a SkyModel from a FITS table using a column_mapping string.
Automatically falls back to a custom loader (no Karabo) when mapped columns lack TUNIT in the FITS header. When all mapped columnsprovide TUNIT, the path via SkyPrefixMapping + SkySourcesUnits is used.
- class skasim.loaders.FitsCubeInfo(path, shape, spatial_shape, unit, n_channels, channel_width_hz, start_frequency_hz, reference_frequency_hz)[source]
Bases:
objectSmall summary of an accepted 3D spectral-cube model.
-
channel_width_hz:
float
-
n_channels:
int
-
path:
Path
-
reference_frequency_hz:
float
-
shape:
tuple[int,int,int]
-
spatial_shape:
tuple[int,int]
-
start_frequency_hz:
float
-
unit:
str
-
channel_width_hz:
- class skasim.loaders.FitsImageInfo(path, spatial_shape, unit, celestial_header, center)[source]
Bases:
objectSmall summary of one accepted FITS image model plane.
-
celestial_header:
dict[str,object]
-
center:
SkyCoord|None
-
path:
Path
-
spatial_shape:
tuple[int,int]
-
unit:
str|None
-
celestial_header:
- class skasim.loaders.FitsImageLoader(fpath, fallback_freq_mhz=None)[source]
Bases:
objectLoad a SkyModel from a FITS image using oskar.Sky.
- The protocol is:
oskar.Sky.from_fits_file(path) → to_array() → np.ndarray → SkyModel
This loader encapsulates the entire OSKAR dependency, allowing lazy import via require_oskar_module so that the module can be imported even when OSKAR is not installed.
- skasim.loaders.adjust_spectral_reference(image_path, old_ref_hz, new_ref_hz, alpha_map=None)[source]
Adjust the spectral reference of a CASA image to the observation band centre.
For nterms=1 (alpha_map is None), set the spectral CRVAL to new_ref_hz only — the model is spectrally flat and no pixel-data correction is needed.
For nterms≥2 (alpha_map provided), correct the pixel data element-wise following CASA’s Taylor-series convention:
tt0'(x,y) = tt0(x,y) · (ν_new / ν_old) ^ α(x,y)
where α(x,y) = tt1(x,y) / tt0(x,y) for each pixel. The spectral CRVAL is also set.
Returns the adjusted reference frequency in Hz (always new_ref_hz).
- Return type:
float
- skasim.loaders.component_model_entries(config)[source]
- Return type:
list[ComponentSkyModelEntry]
- skasim.loaders.has_spectral_cube_model(config)[source]
Return True if the simulation contains a spectral_cube model entry.
- Return type:
bool
- skasim.loaders.image_model_center(entries)[source]
Return the centre of the first image model with usable celestial WCS.
- Return type:
SkyCoord|None
- skasim.loaders.image_model_center_entry(entries)[source]
Return
(index, entry, centre)of the first entry with a usable WCS.Spectral cubes count like any other image entry, in
modelsorder.- Return type:
tuple[int,Union[ComponentSkyModelEntry,ContinuumIAlphaModelEntry,CasaTaylorTermsModelEntry,StaticStokesMapsModelEntry,SpectralCubeModelEntry],SkyCoord] |None
- skasim.loaders.image_model_entries(config)[source]
- Return type:
list[Union[ComponentSkyModelEntry,ContinuumIAlphaModelEntry,CasaTaylorTermsModelEntry,StaticStokesMapsModelEntry,SpectralCubeModelEntry]]
- skasim.loaders.image_model_footprints(entries, center, beam, field_fov_deg)[source]
Return each FITS image model’s footprint relative to the phase centre.
The footprint radius is the largest angular distance of any pixel-edge corner from the phase centre. It is compared with the shared beam’s half-power radius at its reference frequency and with the simulation field radius, so heavily attenuated components can be flagged.
- Return type:
list[dict]
- skasim.loaders.inject_image_models(ctx, visibility_path, imaging_configs=None, phase_center=None, beam=None)[source]
Inject configured image models into an existing Measurement Set.
beamandphase_centerdescribe the shared Gaussian primary beam the pipeline also applies to catalogue sources; WSClean-predicted entries are attenuated by it. Each entry is merged intoDATAstraight after its prediction because both backends overwriteMODEL_DATA.- Return type:
None
- skasim.loaders.inject_spectral_cube_with_wsclean_predict(ctx, entry, index, visibility_path, img_config, cube_data, header, freq_axis, phase_center=None, beam=None)[source]
Place a spectral cube, apply the beam, and run
wsclean -predict.cube_datais(freq, y, x)on the MS channel grid (seeprepare_spectral_cube_for_casa). Withphase_centerthe cube lands at its FITS WCS position and, withbeam, every channel is attenuated by the shared power beam at its frequency (seeplace_spectral_cube()).- Return type:
dict
- skasim.loaders.merge_model_data_into_data(visibility_path, chunk_bytes=536870912)[source]
Add image-model MODEL_DATA into the delivered DATA column.
Rows are processed in chunks of roughly
chunk_bytesper column so peak memory stays bounded for long observations and wide cubes.- Return type:
None
- skasim.loaders.prepare_continuum_i_alpha_for_casa(ctx, entry, index)[source]
Create CASA image products for a continuum I+alpha model.
Adjusts the spectral reference to the observation band centre using the explicit spectral index from the model entry.
- Return type:
- skasim.loaders.prepare_spectral_cube_for_casa(ctx, entry, index, report)[source]
Resample a 3D FITS spectral cube to the MS spectral grid.
Returns the resampled cube array in numpy order (freq, dec, ra) together with a 3D FITS header that describes the per-channel model images. The caller is responsible for splitting this into WSClean per-channel model images and running
wsclean -predict.- Return type:
- skasim.loaders.primary_model_fits_path(entry)[source]
Return the representative FITS image for previews and phase-centre inference.
- Return type:
Path|None
- skasim.loaders.read_fits_cube_info(path)[source]
Read metadata from a 3D FITS spectral cube.
- Return type:
- skasim.loaders.read_fits_image_info(path)[source]
Read FITS image metadata used by validation and reporting.
- Return type:
- skasim.loaders.run_casa_exportfits(work_dir, imagename, fitsimage)[source]
Run CASA exportfits in batch mode for a CASA image table.
- Return type:
None
- skasim.loaders.run_casa_ft(visibility_path, model_paths, nterms, reffreq, incremental)[source]
Run CASA ft into MODEL_DATA for one prepared model entry.
- Return type:
None
- skasim.loaders.run_casa_set_spectral_coordinate(work_dir, image_paths, frequency_hz)[source]
Set the single-channel spectral coordinate of CASA images to the run reference.
- Return type:
None
- skasim.loaders.run_wsclean_predict(wsclean_command, visibility_path, img_config, prefix, n_channels, work_dir, pixel_size_arcsec=None, n_pixels=None, shift=None)[source]
Run WSClean in predict mode to fill MODEL_DATA of the MS.
- Return type:
None
- skasim.loaders.spectral_cube_model_entries(config)[source]
Return all spectral_cube model entries in the config.
- Return type:
list
- skasim.loaders.validate_continuum_i_alpha(entry)[source]
Validate the continuum image contract and return report metadata.
- Return type:
dict
- skasim.loaders.validate_spectral_cube(entry, obs, img)[source]
Validate the spectral-cube contract against the observation config.
Checks the Jy/pixel unit, a minimum spatial size, and that the cube’s frequency range lies inside the observation band. The cube is placed on sky from its own WCS, so its spatial grid is independent of the imaging blocks;
imgis kept for API compatibility and is not used.- Return type:
dict
- skasim.loaders.validate_static_stokes_maps(entry, obs, img_config)[source]
Validate a static Stokes I map and return report metadata.
Currently only
stokes_iis supported. The image must be a 2D spatial FITS file with Jy/pixel-compatible BUNIT.- Return type:
dict
- skasim.loaders.write_image_model_previews(ctx, fov, center=None)[source]
Write two-panel FITS model previews for the weblog sky-model section.
Each continuum/Stokes-map/CASA-Taylor-term entry produces a side-by-side PNG: LEFT shows the FITS at its natural image extent so small models are legible; RIGHT shows the simulation FoV contextual view with the primary beam as a circle and the image-model footprint as a rectangle. Spectral cubes keep the existing single-panel moment-8 preview.
- Return type:
None
Parameters
- ctx
Run context with the model configuration and manifest.
- fov
Simulation field of view used for the right-hand contextual panel.
- center
Simulation phase centre. When
None, the contextual panel falls back to the FITS model’s own centre if it has a usable WCS.
- skasim.loaders.write_sky_composition_preview(ctx, center, beam, field_fov_deg, catalogue=None, phase_centre_rule=None)[source]
Draw one panel with every sky component around the phase centre.
Catalogue sources (symbol area scaling with flux density), each FITS image model’s on-sky footprint, the shared beam’s half-power circle at the reference frequency, and the simulation field are drawn in offsets from the phase centre (east to the left).
catalogueis an optional(ra_deg, dec_deg, flux_jy)tuple of arrays.- Return type:
Optional[Path]
- skasim.loaders.write_spectral_cube_input_preview(ctx, fov)[source]
Render a peak-intensity (moment-8) PNG preview of the input spectral cube.
The preview is added to the manifest as a sky-model plot so it appears in the weblog’s Sky Model section.
- Return type:
None
skasim.loaders.fits_catalogue
loaders/fits_catalogue.py — FITS catalogue loading helpers.
Loads FITS table sky models using an explicit column mapping.
- class skasim.loaders.fits_catalogue.FitsCatalogLoader(fpath, column_mapping, scale_I=1.0, ref_freq_hz=None, frequency=None)[source]
Bases:
objectLoad a SkyModel from a FITS table using a column_mapping string.
Automatically falls back to a custom loader (no Karabo) when mapped columns lack TUNIT in the FITS header. When all mapped columnsprovide TUNIT, the path via SkyPrefixMapping + SkySourcesUnits is used.
skasim.loaders.fits_image
loaders/fits_image.py — Load a SkyModel from a FITS image via OSKAR.
- class skasim.loaders.fits_image.FitsImageLoader(fpath, fallback_freq_mhz=None)[source]
Bases:
objectLoad a SkyModel from a FITS image using oskar.Sky.
- The protocol is:
oskar.Sky.from_fits_file(path) → to_array() → np.ndarray → SkyModel
This loader encapsulates the entire OSKAR dependency, allowing lazy import via require_oskar_module so that the module can be imported even when OSKAR is not installed.
skasim.loaders.image_models
Public façade for image-model loading, validation and injection.
- class skasim.loaders.image_models.CasaModelProduct(model_paths, nterms, reffreq, intermediates, cube_data=None, header=None, freq_axis=None, model_dir=None)[source]
Bases:
objectCASA-ready model product generated from one model entry.
-
cube_data:
ndarray|None= None
-
freq_axis:
int|None= None
-
header:
Header|None= None
-
intermediates:
list[Path]
-
model_dir:
Path|None= None
-
model_paths:
list[Path]
-
nterms:
int
-
reffreq:
str
-
cube_data:
- class skasim.loaders.image_models.FitsCubeInfo(path, shape, spatial_shape, unit, n_channels, channel_width_hz, start_frequency_hz, reference_frequency_hz)[source]
Bases:
objectSmall summary of an accepted 3D spectral-cube model.
-
channel_width_hz:
float
-
n_channels:
int
-
path:
Path
-
reference_frequency_hz:
float
-
shape:
tuple[int,int,int]
-
spatial_shape:
tuple[int,int]
-
start_frequency_hz:
float
-
unit:
str
-
channel_width_hz:
- class skasim.loaders.image_models.FitsImageInfo(path, spatial_shape, unit, celestial_header, center)[source]
Bases:
objectSmall summary of one accepted FITS image model plane.
-
celestial_header:
dict[str,object]
-
center:
SkyCoord|None
-
path:
Path
-
spatial_shape:
tuple[int,int]
-
unit:
str|None
-
celestial_header:
- skasim.loaders.image_models.adjust_spectral_reference(image_path, old_ref_hz, new_ref_hz, alpha_map=None)[source]
Adjust the spectral reference of a CASA image to the observation band centre.
For nterms=1 (alpha_map is None), set the spectral CRVAL to new_ref_hz only — the model is spectrally flat and no pixel-data correction is needed.
For nterms≥2 (alpha_map provided), correct the pixel data element-wise following CASA’s Taylor-series convention:
tt0'(x,y) = tt0(x,y) · (ν_new / ν_old) ^ α(x,y)
where α(x,y) = tt1(x,y) / tt0(x,y) for each pixel. The spectral CRVAL is also set.
Returns the adjusted reference frequency in Hz (always new_ref_hz).
- Return type:
float
- skasim.loaders.image_models.component_model_entries(config)[source]
- Return type:
list[ComponentSkyModelEntry]
- skasim.loaders.image_models.has_spectral_cube_model(config)[source]
Return True if the simulation contains a spectral_cube model entry.
- Return type:
bool
- skasim.loaders.image_models.image_model_center(entries)[source]
Return the centre of the first image model with usable celestial WCS.
- Return type:
SkyCoord|None
- skasim.loaders.image_models.image_model_center_entry(entries)[source]
Return
(index, entry, centre)of the first entry with a usable WCS.Spectral cubes count like any other image entry, in
modelsorder.- Return type:
tuple[int,Union[ComponentSkyModelEntry,ContinuumIAlphaModelEntry,CasaTaylorTermsModelEntry,StaticStokesMapsModelEntry,SpectralCubeModelEntry],SkyCoord] |None
- skasim.loaders.image_models.image_model_entries(config)[source]
- Return type:
list[Union[ComponentSkyModelEntry,ContinuumIAlphaModelEntry,CasaTaylorTermsModelEntry,StaticStokesMapsModelEntry,SpectralCubeModelEntry]]
- skasim.loaders.image_models.image_model_footprints(entries, center, beam, field_fov_deg)[source]
Return each FITS image model’s footprint relative to the phase centre.
The footprint radius is the largest angular distance of any pixel-edge corner from the phase centre. It is compared with the shared beam’s half-power radius at its reference frequency and with the simulation field radius, so heavily attenuated components can be flagged.
- Return type:
list[dict]
- skasim.loaders.image_models.inject_image_models(ctx, visibility_path, imaging_configs=None, phase_center=None, beam=None)[source]
Inject configured image models into an existing Measurement Set.
beamandphase_centerdescribe the shared Gaussian primary beam the pipeline also applies to catalogue sources; WSClean-predicted entries are attenuated by it. Each entry is merged intoDATAstraight after its prediction because both backends overwriteMODEL_DATA.- Return type:
None
- skasim.loaders.image_models.merge_model_data_into_data(visibility_path, chunk_bytes=536870912)[source]
Add image-model MODEL_DATA into the delivered DATA column.
Rows are processed in chunks of roughly
chunk_bytesper column so peak memory stays bounded for long observations and wide cubes.- Return type:
None
- skasim.loaders.image_models.prepare_casa_taylor_terms(ctx, entry, index)[source]
Copy CASA Taylor-term images into the run and align their spectral reference.
The reference frequency is adjusted to the observation band centre. For nterms≥2, tt0 pixel data is scaled: tt0’ = tt0 · (ν_obs / ν_old)^α where α = mean(tt1) / mean(tt0). tt1 pixel data is unchanged. For nterms=1, only the spectral CRVAL is updated.
- Return type:
- skasim.loaders.image_models.prepare_continuum_i_alpha_for_casa(ctx, entry, index)[source]
Create CASA image products for a continuum I+alpha model.
Adjusts the spectral reference to the observation band centre using the explicit spectral index from the model entry.
- Return type:
- skasim.loaders.image_models.prepare_spectral_cube_for_casa(ctx, entry, index, report)[source]
Resample a 3D FITS spectral cube to the MS spectral grid.
Returns the resampled cube array in numpy order (freq, dec, ra) together with a 3D FITS header that describes the per-channel model images. The caller is responsible for splitting this into WSClean per-channel model images and running
wsclean -predict.- Return type:
- skasim.loaders.image_models.primary_model_fits_path(entry)[source]
Return the representative FITS image for previews and phase-centre inference.
- Return type:
Path|None
- skasim.loaders.image_models.read_fits_cube_info(path)[source]
Read metadata from a 3D FITS spectral cube.
- Return type:
- skasim.loaders.image_models.read_fits_image_info(path)[source]
Read FITS image metadata used by validation and reporting.
- Return type:
- skasim.loaders.image_models.require_casa_executable()[source]
Return a CASA executable for batch-mode fallback.
- Return type:
Path
- skasim.loaders.image_models.run_casa_exportfits(work_dir, imagename, fitsimage)[source]
Run CASA exportfits in batch mode for a CASA image table.
- Return type:
None
- skasim.loaders.image_models.run_casa_ft(visibility_path, model_paths, nterms, reffreq, incremental)[source]
Run CASA ft into MODEL_DATA for one prepared model entry.
- Return type:
None
- skasim.loaders.image_models.run_casa_importfits(work_dir, images)[source]
Run CASA importfits in batch mode for prepared FITS images.
- Return type:
None
- skasim.loaders.image_models.run_casa_set_spectral_coordinate(work_dir, image_paths, frequency_hz)[source]
Set the single-channel spectral coordinate of CASA images to the run reference.
- Return type:
None
- skasim.loaders.image_models.run_moment8_for_spectral_cube(ctx, work_dir, output_prefix, tag)[source]
Generate a moment-8 (peak intensity) map and an average spectrum plot from the stacked WSClean clean cube.
Uses pure NumPy over the FITS cube; no CASA required.
- Return type:
None
- skasim.loaders.image_models.spectral_cube_model_entries(config)[source]
Return all spectral_cube model entries in the config.
- Return type:
list
- skasim.loaders.image_models.validate_casa_taylor_terms(entry)[source]
Validate an existing CASA Taylor-term image model entry.
- Return type:
dict
- skasim.loaders.image_models.validate_continuum_i_alpha(entry)[source]
Validate the continuum image contract and return report metadata.
- Return type:
dict
- skasim.loaders.image_models.validate_spectral_cube(entry, obs, img)[source]
Validate the spectral-cube contract against the observation config.
Checks the Jy/pixel unit, a minimum spatial size, and that the cube’s frequency range lies inside the observation band. The cube is placed on sky from its own WCS, so its spatial grid is independent of the imaging blocks;
imgis kept for API compatibility and is not used.- Return type:
dict
- skasim.loaders.image_models.validate_static_stokes_maps(entry, obs, img_config)[source]
Validate a static Stokes I map and return report metadata.
Currently only
stokes_iis supported. The image must be a 2D spatial FITS file with Jy/pixel-compatible BUNIT.- Return type:
dict
- skasim.loaders.image_models.write_image_model_previews(ctx, fov, center=None)[source]
Write two-panel FITS model previews for the weblog sky-model section.
Each continuum/Stokes-map/CASA-Taylor-term entry produces a side-by-side PNG: LEFT shows the FITS at its natural image extent so small models are legible; RIGHT shows the simulation FoV contextual view with the primary beam as a circle and the image-model footprint as a rectangle. Spectral cubes keep the existing single-panel moment-8 preview.
- Return type:
None
Parameters
- ctx
Run context with the model configuration and manifest.
- fov
Simulation field of view used for the right-hand contextual panel.
- center
Simulation phase centre. When
None, the contextual panel falls back to the FITS model’s own centre if it has a usable WCS.
- skasim.loaders.image_models.write_sky_composition_preview(ctx, center, beam, field_fov_deg, catalogue=None, phase_centre_rule=None)[source]
Draw one panel with every sky component around the phase centre.
Catalogue sources (symbol area scaling with flux density), each FITS image model’s on-sky footprint, the shared beam’s half-power circle at the reference frequency, and the simulation field are drawn in offsets from the phase centre (east to the left).
catalogueis an optional(ra_deg, dec_deg, flux_jy)tuple of arrays.- Return type:
Optional[Path]