csimulator¶

The csimulator program is used to generate a measurement set from a model sky.

Running the program¶

It can be run with the following command, where “config.in” is a file containing the configuration parameters described in the next section.

$ csimulator -c config.in

Configuration Parameters¶

Available parameters for simulator are given in the following table (all parameters must have Csimulator prefix, i.e. Csimulator.dataset). For a number of parameters certain keywords are substituted, i.e. %w is replaced by the rank and %n by the number of nodes in the parallel case. In the serial case, these special strings are substituted by 0 and 1, respectively.

This substitution allows to reuse the same parameter file on all nodes of the cluster if the difference between jobs assigned to individual nodes can be coded in using these keywords (i.e. using specially crafted file names). If a parameter allows substitution, it is clearly stated in the description.

Parameter	Type	Default	Description
imagetype	string	“casa”	Type of the image handler (determines the format of the images read from the disk). The default is to read casa images and this is the only option implemented so far.
dataset	string	None	Data set file name to produce. Usual substitution rules apply.
sources.definition	string	None	Optional parameter. If defined, sky model (i.e. source info given as sources.something) is read from a separate parset file (name is given by this parameter). If this parameter is not defined, source description should be given in the main parset file. Usual substitution rules apply. The parameters used to define sky model are described below.
antennas.definition	string	None	Optional parameter. If defined, antenna layout (antennas.something) is read from a separate parset file (name is given by this parameter). Usual substitution rules apply. If this parameter is not defined, antenna layout must be given in the main parset file. A description of these parameters is given in a separate section.
feeds.definition	string	None	Optional parameter. If defined, feed information (feeds.something) is read from a separate parset file (name is given by this parameter). If this parameter is not defined, the appropriate parameters must be given in the main parset file (see a separate section below for description). Usual substitution rules apply.
spws.definition	string	None	Optional parameter. If defined, configuration of spectral windows (i.e. which frequencies are observed) is read from a separate parset file, which name is given by this parameter. If not, the appropriate parameters (spws.something) must be given in the main parset file (see a separate section below for description). Usual substitution rules apply.
simulation.definition	string	None	Optional parameter. If defined, additional parameters of simulations are read from a separate parset file (name is given by this parameter). If this parameter is not defined, these additional parameters (listed in a separate section below) must be given in the main parset file. Usual substitution rules apply.
observe.definition	string	None	Optional parameter. If defined, description of simulated observations is read from a separate parset file (name is given by this parameter). If this parameter is not defined, these details must be given in the main parset file (see the description in a separate section below).
visweights	string	“”	If this parameter is set to “MFS” gridders are setup to degrid with the weight required for the models given as Taylor series (i.e. multi-frequency synthesis models). At the moment, this parameter is decoupled from the setup of the model parameters. The user has to set it separately and in a consistent way with the model setup (nterms should be set to something greater than 1 and there should be an appropriate number of models defined).
visweights.MFS.reffreq	double	1.405e9	Reference frequency in Hz for MFS-model simulation (see above)
stman.bucketsize	int32	32768	Set the bucket size (in bytes) of the casa table storage manager. This usually translates to the I/O size.
stman.tilencorr	int32	4	Set the number of correlations per tile. This affects the way the table is stored on disk.
stman.tilenchan	int32	32	Set the number of channels per tile. This affects the way the table is stored on disk.
gridder	string	None	Name of the gridder, further parameters are given by gridder.something. See Gridders
corrupt	bool	False	if True, simulated data are corrupted by simulating calibration effects. See Access to calibrator solutions
corrupt.gainsfile	string	None	This is a deprecated parameter, which will be removed in the future. It used to define the name of the file with gains/leakages to apply if corrupt is true. The external file had a parset format, with keywords given in the form gain.g11.0 = [0.918308,0.000000], where g11 is for the first parallel-hand polarisation and g22 is for the second. The last number is the 0-based antenna number, and the value is a complex value with real and imaginary parts given in a vector. Leakage parameters were given in the form leakage.g12.x.y and leakage.g21.x.y and were used only if corrupt.leakage is true. Now the same functionality can be done using calibaccess.parset, see Access to calibrator solutions
corrupt.leakage	bool	false	If true, polarisation leakage is simulated. Values will be taken from file referred to by gainsfile.
noise	bool	false	if True, noise is added to the simulated visibilities. There are two ways to obtain noise level. It can either be given manually using noise.variance or noise.rms parameters or can be calculated automatically if Tsys and efficiency are given. There should be enough data for this calculation, otherwise an exception is thrown.
noise.variance	double	None	variance in Jy^2 of the Gaussian noise added to visibilities (to every element of the cube, so the noise level should be appropriate for single polarisation, single spectral channel). This parameter is only used if noise is true and is incompatible with any other noise-defining parameters like rms, Tsys or efficiency
noise.rms	double	None	rms in Jy of the Gaussian noise added to visibilities (to every element of the cube, so the noise level should be appropriate for single polarisation, single spectral channel). This parameter is only used if noise is true and is incompatible with any other noise-defining parameters like variance, Tsys or efficiency
noise.Tsys	double	None	Tsys in Kelvins. This parameter should only come in pair with efficiency. If given, neither rms, nor variance should be defined. If set, the noise level is estimated automatically using observation parameters.
noise.efficiency	double	None	Beam efficiency. This parameter should only come in pair with Tsys. If given, neither rms, nor variance should be defined. If set, the noise level is estimated automatically using observation parameters.
noise.seed1	string or int32	“time”	First seed of the random generator. Usual substitution rules apply (i.e. it is possible to have rank-dependent seed by specifying “%w”). If the word “time” is given, the seed will be taken from the timer.
noise.seed2	string or int32	“%w”	Second seed of the random generator. Usual substitution rules apply (i.e. it is possible to have rank-dependent seed by specifying “%w”). If the word “time” is given, the seed will be taken from the timer.
modelReadByMaster	bool	true	This parameter has effect in the parallel case only (can be set to anything in the serial case without affecting the result). If true, the sky model is read by the master and is then distributed to all workers. If false, each worker reads the model, which should be accessible from the worker nodes. This approach cuts down communication when the model is too big. Workers can also use individual models with the help of the substitution mechanism.
msWrittenByMaster	bool	false	If true, the workers send data to the master which writes a single measurement set, otherwise each worker writes its own measurement set which name is either given explicitly or via the substitution rule. This option is used to distribute simulation load implicitly, splitting in frequency channels. This is unlike the (default) explicit distribution of work which relies on %w wildcard and the substitution rules used appropriately in the parset: if this parameter is false and csimulator is executed in parallel, each non-zero rank becomes an independent worker which substitutes %w in the parset by the worker number, where supported, and, therefore, can simulate different data (e.g. different frequency or different time range). If this option is set to true, master distributes the prediction work to all available workers as evenly as possible (the total number of spectral channels divided by the number of available workers, or that plus one if the number of channels doesn’t divide evenly, is assigned to each available worker). In this case, care must be taken wi%w in the parset. The substitution is honored, but the appropriate code may be executed on master instead of worker, which would result in %w being replaced by -1. In this mode, %w should really only be used with the random seed initialisation, where it is the default (see above), but this is rarely changed by the end user anyway. If the total number of channel doesn’t divide evenly between workers, the last worker will process less channels as appropriate. Note, the case where the number of available workers exceeds the number of simulated spectral channels is not supported and will cause an exception. With the current ADE system with the number of channels being an integral multiple of 216, it makes sense to run the csimulator with 55, 109 or 217 ranks. The option is allowed to be set to true in the parallel case only.

Parameters of the sources (or fields)¶

This section describes how the sky model is specified. The parameters can be given either in the main parset file or in a separate one pointed by sources.definition (see above). All parameters below have Csimulator prefix, if given in the main parset file. The sky model is specified by either a model image (using sources.nameOfSource.model) or components (using sources.nameOfSource.components), but not both. If both options are provided in the parset, the task will abort.

Parameter	Type	Default	Description
sources.names	vector<string>	None	List of sources (or fields) to simulate. Each field is definded by an image and/or a number of components. The name is used to reference the details on the corresponding sky model given in separate parameters (see below) and can be arbitrary.
sources.nameOfSource.xxx			Additional parameters for the source nameOfSource, specifying either image-based model or component-based model (or both). These are described below.

All following parameters have Csimulator.sources.nameOfSource prefix.

Parameter	Type	Default	Description
direction	direction	None	Direction to the source or field (given as direction string, e.g. [12h30m00.000, -15.00.00.000, J2000]). If the model is defined by an image, this parameter should match the coordinate system in the image. For components, this value is supposed to be a reference position, but is not used at the moment (this is the current limitation of the component code that all components are defined with respect to the phase centre and therefore are always replicated for all synthetic beams).
model	vector<string>	None	If this parameter is defined, an image-based model is used for the source. The value of this parameter is the file name of the image. Usual substituting rules apply (see the description at the top of the page). However, the substitution only makes sense if workers read the model (see modelReadByMaster parameter). If more than one model is given, it is assumed that the model is given as Taylor series (nterms parameter described below should match the number of models in this case) and each image corresponds to the appropriate Taylor term starting from 0. If only one model image is given and nterms is not 1, the name is treated as base name and .taylor.x suffix is appended to each name
nterms	int	1	Number of taylor terms in the given image-based model. See the model keyword for the supported ways to define individual Taylor terms.
components	vector<string>	None	list of components (names) to simulate for this source (or field). Each component defined by parameters componentName.xxx as below (with just Csimulator.sources.nameOfSource prefix)
componentName.flux.i	double	None	Flux density of the component in Jy at ref_freq
componentName.flux.spectral_index	double	0	Spectral index of the component
componentName.flux.ref_freq	double	None	Reference frequency of spectrum
componentName.direction.ra	double	None	RA offset from the field centre for the given component (in radians)
componentName.direction.dec	double	None	Dec offset from the field centre for the given component (in radians)
componentName.shape.bmaj	double	None	Required only for a gaussian component. Major axis of the gaussian (in radians) for this component.
componentName.shape.bmin	double	None	Required only for a gaussian component. Minor axis of the gaussian (in radians) for this component.
componentName.shape.bpa	double	None	Required only for a gaussian component. Position angle of the gaussian (in radians) for this component.

Definition of the array layout¶

This section describes how the array layout is defined. The parameters can be given either in the main parset file or in a separate one pointed by antennas.definition (see above). All parameters below have Csimulator prefix, if given in the main parset file.

Parameter	Type	Default	Description
antennas.telescope	string	None	name of the array, e.g. ASKAP. This name is used to compose other parameter names (see below)
antennas.nameOfArray.names	vector<string>	None	List of antenna names included into array, e.g. ANT1, ANT2, etc. These names are used to form the parameter name to define the position of each antenna (in the form antennas.nameOfArray.antennaName, see below). For useful operation should contain at least 2 antennas.
antennas.nameOfArray.mount	string	equatorial	Antenna mount (must be the same for the whole array). Only _equatorial_ (default) or _alt-az_ mounts are allowed. Use _equatorial_ to simulate ASKAP’s 3-axis mount (assumes perfect compensation for the parallactic angle rotation)
antennas.nameOfArray.diameter	quantity string	“12m”	Diameter of the antennas (assumed the same for the whole array)
antennas.nameOfArray.coordinates	string	local	Type of the coordinate system used to define antenna position. Allowed values are global and local. This string is passed directly to the casacore’s NewMSSimulator, which is doing the actual job to generate metadata. If local (default) the antenna coordinates are treated as offsets from the reference location. If global they are offsets w.r.t. the Earth Centre and the coordinate axes are aligned with ITRF. Note, this is not the how we normally use the simulator
antennas.nameOfArray.scale	float	1.0	Optional scaling factor for the antenna layout. Default is no scaling.
antennas.nameOfArray.antennaName	vector<float>	None	Coordinates (in the form [x,y,z], the values are in metres) for antenna with name antennaName. There should be one such parameter for each antenna listed in antennas.nameOfArray.names (parameters for antennas not listed in there are simply ignored). Coordinates are multiplied by the scale before being passed to casacore’s NewMSSimulator, which is responsible for simulation of metadata.
antennas.nameOfArray.location	vector<string>	None	Centre location for the array layout given as a 4-element vector with longitude, latitude, altitude (all given as quantities) and reference frame, i.e. [+115deg, -26deg, 192km, WGS84]. For local coordinates (see above), this is the origin of the coordinate system where antenna positions are defined (axes point to the East, North and to the local zenith). For global coordinates this position is used to determine whether the source is visible (casacore’s NewMSSimulator doesn’t properly support VLBI-scale baselines), although geocentric X,Y,Z define the antenna positions on the ground

Definition of the feed configuration¶

This section describes how the feed (strictly speaking should call it a synthetic beam) layout is defined. The parameters can be given either in the main parset file or in a separate parset file pointed by feeds.definition (see above). All parameters below have Csimulator prefix, if given in the main parset file.

Parameter	Type	Default	Description
feeds.names	vector<string>	None	List of beams to define (e.g. [Beam1,Beam2]), at least one should be defined. The names are used to compose the parameter name (in the form feeds.beamName) defining angular offsets from the boresight
feeds.mode	string	“perfect X Y”	Polarisation properties of each beam (assumed the same for all). Any string understood by casacore is supported. Default is perfect (i.e. not sensitive to circular or orthogonal linear polarisation) linears. Note, that although “perfect L R” is supported here, in some other places the linear receptors are implicitly assumed.
feeds.beamName	vector<double>	None	Dimensionless offset of the given beam from the boresight direction (given as [x,y]). Values are multiplied by feeds.spacing before being passed to casacore’s NewMSSimulator, which does the actual job of simulating the metadata.This also defines the units (assumed the same for all beams) to get a correct angular quantity.If feeds.spacing is not defined, the values in this parameter are treated as angular offsets in radians. The offsets should be defined for every beam listed in feeds.names. Parameters corresponding to beams which are not listed in there are ignored
feeds.spacing	quantity string	None	Optional parameter. If present, it determines the dimension and scaling of the beam layout (see above). If not defined, all beam offsets are assumed to be in radians.

Definition of the spectral windows¶

This section describes how the spectral windows (i.e. frequency mapping) is defined. The parameters can be given either in the main parset file or in a separate parset file pointed by spws.definition (see above). All parameters below have Csimulator prefix, if given in the main parset file.

Parameter	Type	Default	Description
spws.names	vector<string>	None	List of names for all spectral windows. Names are used to define parameters for each spectral window (in the form spws.nameOfWindow). Spectral windows defined, but not listed here are ignored.
spws.nameOfWindow	vector<string>	None	A 4-element vector describing the actual spectral window (or correlator setup) configuration containing the number of channels, frequency of the first channel (quantity), frequency increment (quantity) and polarisation products required (given as [1, 1.420GHz, -16MHz, “XX XY YX YY”]). The current code provides enough flexibility to simulate various polarisation products including mixed ones, i.e “XX RR I”, as long as the inputs are sufficient to make the transformation.

Additional parameters of simulation¶

This section describes how simulations can be fine tuned. The parameters listed below can be given either in the main parset file or in a separate parset file pointed by simulation.definition (see above). All parameters below have Csimulator prefix, if they are defined in the main parset file.

Parameter	Type	Default	Description
simulation.blockage	double	0.0	Fractional blocakge limit to determine whether antenna is shadowed. It is passed directly to casacore’s NewMSSimulator which generates the actual metadata. If the antenna aperture area larger than this fraction from the total area is shadowed, all visibilities including this antenna are flagged. (MV:) It is probably safer to use a very small (like 1e-6 which is a default in casacore, btw) value, rather than 0 to achieve flagging for shadowing of any extent. Because the fractional area is always non-zero. The flagging condition in casacore could be satisfied due to round-off error causing spurious flagging. However, it is worth noting that we haven’t seen such effect in the current simulations.
simulation.elevationlimit	quantity string	“8deg”	Elevation limit of all antennas. If source elevation is below this value, corresponding visibilities are flagged. Note, casacore’s NewSimulator calculates the source elevation for the reference location only. Therefore, even if the array is sparse enough all baselines will be flagged at the same time.
simulation.autocorrwt	double	0.0	Relative weight given to autocorrelations (default value of 0.0 means the weight will be 0). Csimulator assumes the same diameter for all antennas. In this case, an equal weight of 1 will be generated for all visibilities. Auto-correlations will be assigned a weight equal to this factor. (MV:) I see no use in this factor given the equal diameter assumption. It should probably be set to 1.0 rather than 0.0 if, in the future, we want to do something with autocorrelations.
simulation.integrationtime	quantity string	“10s”	Simulated integration time of the correlator.
simulation.usehourangles	bool	True	if True, the start and stop time are interpreted as hour angles, rather than actual UT times
simulation.referencetime	epoch string	None	Reference epoch used to specify start and stop time, e.g. [2007Mar07, UTC]

Parameters of simulated observations¶

This section describes how to setup parameters of the observation to be simulated. The parameters listed below can be given either in the main parset file or in a separate parset file pointed by observe.definition (see above). All parameters below have Csimulator prefix, if they are defined in the main parset file.

Parameter	Type	Default	Description
observe.number	int	0	Number of scans to simulate (should be non-zero, default value would cause an exception). Parameters describing each scan are given by observe.scanN, where scanN is zero-based number of the scan. An exception is thrown if such a parameter is missing for any of the simulated scans.
observe.scanN	vector<string>	None	Parameters for the scan N (0..number-1) specified as a 4-element vector (e.g. [10uJy, Wide0, -0.0416667h, 0.0416667h]). Usual substitute rules apply for the first two elements of the vector. The first element is the source name (see definition of sources or fields), the second is the spectral window name (see definition of spectral windows). The last two elements are treated as quantities and represent start and stop time (or hour angle if simulation.usehourangles is True)

Examples¶

Csimulator.dataset                              =       10uJy_stdtest.ms

#
# The name of the model source is 10uJy. Specify direction and model file
#
Csimulator.sources.names                        =       [10uJy]
Csimulator.sources.10uJy.direction              =       [12h30m00.000, -45.00.00.000, J2000]
Csimulator.sources.10uJy.model                  =       10uJy.model.small

#
# Define the antenna locations, feed locations, and spectral window definitions
#
Csimulator.antennas.definition                  =       definitions/ASKAP45.in
Csimulator.feeds.definition                     =       definitions/ASKAP1feeds.in
Csimulator.spws.definition                      =       definitions/ASKAPspws.in

#
# Standard settings for the simulaton step
#
Csimulator.simulation.blockage                  =       0.01
Csimulator.simulation.elevationlimit            =       8deg
Csimulator.simulation.autocorrwt                =       0.0
Csimulator.simulation.usehourangles             =       True
Csimulator.simulation.referencetime             =       [2007Mar07, UTC]

#
# Undersample in time by ~ 10 to make the processing run quickly
#
Csimulator.simulation.integrationtime           =       150s

#
# Observe source 10uJy for 12 hours with a single channel spectral window
#

Csimulator.observe.number                       =       1
Csimulator.observe.scan0                        =       [10uJy, Continuum0, -6h, 6h]

#
# Use a gridder to apply primary beam during the W projection step.
#
Csimulator.gridder                              = AWProject
Csimulator.gridder.AWProject.wmax               = 15000
Csimulator.gridder.AWProject.nwplanes           = 129
Csimulator.gridder.AWProject.oversample         = 8
Csimulator.gridder.AWProject.diameter           = 12m
Csimulator.gridder.AWProject.blockage           = 2m
Csimulator.gridder.AWProject.maxfeeds           = 1
Csimulator.gridder.AWProject.maxsupport         = 1024
Csimulator.gridder.AWProject.frequencydependent = false
Csimulator.gridder.AWProject.tablename          = AWProject.tab