A Proposed Set of Simulation Parameters for CASA

S. Myers, C. Brogan, R. Reid

Draft 1.0 2007-02-08
Draft 1.1 2007-02-10

------------------------------------------------------------------------

This document contains a description of what we think a reasonable
set of simulation parameters for the CASA simulator task should be.

As described in our "", we propose that there be two sets of
parameters.  These are:

1) Meta-parameters ("meta-pars") - a restricted set of high-level
   controlling parameters that users first set.  These are then
   used to determine the values of the sim-pars.

2) Simulation parameters ("sim-pars") - the full set of parameters
   that control the simulation and imaging engines.  Most sim-pars
   will depend upon one or more meta-pars, though there may be
   "hidden" sim-pars that do not depend on the meta-pars but can
   be manually changed from default values in running the simulater.

Note that we are deprecating the use of very long lists or arrays as
parameters and instead using intermediary files.

The scope of this study is the development of a useable ALMA simulator,
but we are mindful of the desire to allow additional arrays (evla,carma,
atca) to be simulated here also.  We will occasionally indicate how
this might be done within the paradigm of this design.

------------------------------------------------------------------------

Key:

Meta-Parameters

   MP: meta-par

   MP=SP: both a meta-par and sim-par

   HMP: hidden meta-par (does not appear on meta-par only list
        as input to meta-task, but does appear as meta-par at
        the lower level

   DP: Each meta-par has a list of sim-pars that depend upon it.

Sim Parameters

   SP: sim-par

   HSP: hidden sim-par (not dependent upon any meta-par but
        available for control of low-level simulater and 
        simager)

   AP: Each sim-par has a list of meta-pars that affect it.

Options for each enumerated parameter (parameters where you choose
from a list of a fixed set of choices) are given.  Some enumerated
parameters allow 'Custom' which will put in some basic default
but disable checking - useful for where the user knows they want
to manually set the sim-pars (to possibly disallowed values).

--------------------------------------------------------
1. Project Setup
--------------------------------------------------------

MP: project - name to be used for file generation, etc.
        (e.g. project = 'sim_cepha') [USER CHOICE]

    DP: various file names

--------------------------------------------------------
2. Array Setup
--------------------------------------------------------

MP: alma_config - configuration for the main ALMA (12m) array
        ['O-1','O-2',...,'Y+','Custom','']

MP: aca_config -  configuration for the ACA (7m)
        ['A','B','Custom','']

    DP: antlist

Choose which configuration of antennas that will be in the ms.  Can
pick one main array and one ACA configuration.  Note that if both main
and ACA configs are chosen, it will assume that these are being
cross-correlated together with the same observing and band parameters.

OPTION: It would be ideal if instead of configuration names the user
could specify a desired resolution, e.g. alma_config='1arcsec' which
would then lookup and choose the particular configuration whose
resolution most closely matches the desired synthesized beam size.

SP: antfile - file containing list of antennas (Num,X,Y,Z,D,type)
    AP: alma_config, aca_config

We expect that the action of the generator will be to produce lists of
antennas, pad locations, diameters (and eventually antenna types) that
are the inputs to the simulater.  We suggest that this actually be
done through a file (e.g. <project>.antlist ) that contains this
information in ascii format, so users can edit this.  This file could
also just include the python for these lists (e.g. padlist=[1,19,...];
padxlist=[62439.6,...]; etc.).

NOTE: This design is ALMA-specific.  If you want to expand the scope,
then one might designate an uber-parameter array:

MP: array - ['alma','evla','atca','carma','Custom']

which then changes the allowed choices for other MP and SP (not
allowed in our simple design).  Then you might have a config
variable

MP: config - ['O-1',...,'Y+','ACA-A','ACA-B'] if array='alma'
    config - ['A','B','C','D','BnA',...] if array='evla'

where you can choose for array='alma' one main config and one ACA.
Seems too complicated to me.  I would make separate tasks (STM).

--------------------------------------------------------
3. Band Setup
--------------------------------------------------------

MP: bandname - name of ALMA band ['1cm','3mm','2mm','1mm',...,'Custom']
    (default='3mm')

    DP: nband, bandwidth, nchan, centerfreq

The names suggested should actually be decided by someone like
the Science IPT or NAASC!  This is an enumerated list.

SP: nband - number of sidebands or sub-bands
    AP: bandname

SP: bandwidth(nband) - total bandwidth for each sideband or sub-band
    AP: bandname

SP: nchan(nband) - number of channels for each sideband or sub-band
    AP: bandname

SP: centerfreq(nband) - center freq of sub-bands (e.g. '115.67GHz')
    (if only one, then this is the uppermost band, with the lower
     bands contiguous below)
    AP: bandname

The assumption here is that there are two sidebands for ALMA (USB,LSB)
each with the given bandwidth for most bands, though some will have
only one sideband.  Or these could be the correlator sub-bands.
We are not sure you can assume that each sub-band has the same bandwidth
and nchan so these can be lists also (if a single value use for all).

Defaults - for a given band, set the bandwidth to the largest value,
pick a reasonable number of channels, and center the bands to some
sensible values.

--------------------------------------------------------
4. Mosaic Setup
--------------------------------------------------------

These parameters need to change to map angular size to facilitate 
different raster patterns and to incorporate both single dish and 
ACA for which these parameters will not be constant but map size 
will be.

MP: map_center - the center of the pointing or mosaic raster

    Check that map_center can be seen from array.

MP: mos_shape - the shape of the rectangular mosaic area (xsize,ysize,pa)
       (e.g. mos_size=['10arcmin','10arcmin'] or '5arcmin' for a square
       raster, or ['10arcmin','2arcmin','45deg'] for a strip oriented
       with long axis at 45deg).
    DP: mos_fields, nmos

HMP: mos_factor - how much to stretch the pointing separation, as a
		  ratio of the desired spacing to optimum spacing at
		  the highest frequency
    DP: mos_fields, nmos

NOTE: This should be a hex-packed pattern, with spacing
from the Miriad Users Guide
   http://www.atnf.csiro.au/computing/software/miriad/userguide/node168.html
of sqrt(2/3)*lambda/D rather than the (1/2)*lambda/D for a rectangular
pattern.

It is unclear whether we should optimize this for the uppermost
frequency requested (the highest channel of the highest sub-band) or
some compromise (e.g. the center of the highest sub-band). TBD.

SP: mos_fields - name of field file containing the pointing centers of
       the mosaic, or if a single field, the center of that field (e.g. 
       mos_fields='<project>.fields' or mos_fields='16h00m00.0s +87d52m00.0s') 
    AP: map_center, mos_shape, mos_factor

SP: nmos - total number of mosaic fields (nominally redundant as you
       could figure out from the file or value, but useful)
    AP: mos_shape, mos_factor
 
NOTE: The reporter should report how long the source is above the
horizon (or elevation limit), which is very useful for observers.

IMPORTANT: We should eventually be able to handle the output of the
observing tool, which I hear has cool features for drawing regions
and getting pointing centers.  I think we could even get a trial
version.

--------------------------------------------------------
5. Observation Setup
--------------------------------------------------------

MP: refday - (first) day of observation (default to current day?)

MP: ha_range - desired maximum HA range (lower,upper) for observations
        in a given day (e.g. ha_range=['-2h','2h'])
        default = full uptime on a given day

        Note: if the requested observations take less time than this,
        they will be centered on the center of the requested HA range.

MP: integration - integration time per visibility.
        default: something like '10s'?

MP: dwell - number of integrations per pointing per cycle
	default: 10?

MP: ncycles - number of times each field is repeated.  Each repeat
        consists of dwell integrations per field.
        default: 1

MP: overhead - overhead (in time) per pointing after each dwell,
        (e.g. overhead='30s').
        default: 0?

HMP: min_el: Minimum elevation. Note that the actual HA range that
        you will get is the MINIMUM of what ha_range specifies and
        the uptime of the source above min_el
        default: '10deg'

In a "cycle", each mosaic pointing is observed in turn.  Note that in
this simulator, no slew is modeled (this can be approxmated using
the overhead).

The total integration time of the visibilities simulated in the ms
will be equal to 

  integtime-per-field = integration*dwell*ncycles


with the total duration spanned by the observations

  totaltime = ( integration*dwell + overhead )*nmos*ncycles - overhead

(the last cycle doesnt get its overhead!).

If this totaltime cannot be accomodated in the ha_range or min_el
uptime allowed in a single day, it will spill onto consecutive days
in the ms.

NOTE: it is often best to simulate a small ms (say 2 hours) and then
make its noise equivalent to a much longer observation using noisefac
(see below).

--------------------------------------------------------
6. Model Setup
--------------------------------------------------------

MP: modelimage - name of image(s) to use 
    DP: nimages

MP: componentlist - name of componentlist(s) to use
    DP: ncompl

    Componentlists are assumed to contain the info needed to
    get the right fluxes (like their spectrum).  If not will
    need to apply emission model like for images (see below).

HMP: docenter - put images centered on map_center (rather
        than use their real centers, makes sims from theoretical
        models easier).  Boolean?  Can be a list then one for
        each image.  default : N (or should this be Y?)

SP: nimages - number of images to use (default: length of modelimage
        list).

SP: ncompl - number of complists to use (default: length of componentlist list)

HSP: modim_fac(nimages) - scale factor for images
        default: 1.0

HSP: modim_temp(nimages) - blackbody temperature for images.  Can also
        be a list of temperature images.  If T < 0, then set B=0.
        default : -1.0

HSP: modim_tau(nimages) - blackbody optical depth (<0=infinity) for
        images. Can also  be a list of tau images.  default : -1.0 

HSP: modim_alpha(nimages) - power-law spectral index for images. Can
        also be a list of alpha images.  default : 0.0

Provided for EACH image (not componentlist).

These are "hidden" sim-pars because no meta-par sets them from their defaults.

The simulater will simulate visibilities obtained from union of
specified images and comps.

Emission Model:
---------------

We use the simplified emission model:

   S_f(S_0,T,tau,alpha) = S_0*[ (1-A)*B_f(T) + A ]*(f/f_0)^alpha

where f is the channel freq and f_0 the reference freq.  The
B_f(T) is the Planck blackbody function

         B_f(T) = (2hf^3/c^2)/[ exp(hf/kT) - 1]

The attenuation factor 0.LE.A.LE.1 represents A = exp(-tau).  If
tau<0 set A=0 (tau=infinity).

Thus, for special cases

   synchrotron : tau=0, set alpha

   thermal: tau=-1, alpha=0, set T

   thermal dust: tau=-1, set alpha and T

Each image or component should be able to have a set of 
(S_0,T,tau,alpha).

The reference frequency f_0 for the dataset should be set somewhere
(maybe the centerfreq of highest band)?

--------------------------------------------------------
7. Noise and Error setup
--------------------------------------------------------

MP: noisefac - Factor to multiply the expected thermal noise by.
        default : 1.0

        Setting noisefac=0.0 disables thermal noise.

        Setting noisefac>0 approximates a longer observation, e.g.
        N=noisefac^2 times of repeating the simulated observations.
        For example, if you set up a 2 hour observation, but set 
        noisefac=10, you get an ms with size of a 2 hour observation 
        but with the noise of a 200 hour observation.

The default behavior is to set thermal noise based upon the ALMA
lookup information on band sensitivities.

SP: aeff - Aperture efficiency
    DP: band

SP: ceff - Correlator quantization efficiency
    DP: band

SP: seff - Spillover efficiency
    DP: band

SP: tau0 - Atmospheric optical depth
    DP: band

SP: trxc - Receiver temperature (K)
    DP: band

SP: tatm - Atmosphere temperature (K)
    DP: band

### ALMA specs from http://www.cv.nrao.edu/naasc/ALMAsensitivity.ps
### e.g. following values are for 110 GHz
### aeff:=0.74; ceff:=0.95; seff:= 0.95; tau0:=0.049; trxc:=36; tatm:=264;
### e.g. following values are for 230 GHz
### aeff:=0.72; ceff:=0.95; seff:= 0.95; tau0:=0.065; trxc:=70; tatm:=264;
### Results in 6.4mJy noise added to 10s 2GHz vis
### Estimated 30 GHz values
### aeff:=0.75; ceff:=0.95; seff:= 0.95; tau0:=0.017; trxc:=12; tatm:=264;

HSP: phasenoise - rms phase error (deg) to corrupt data to represent
        residual gain and atmospheric delay errors
        default : '0.0deg'

HSP: phasetime - coherence time for phase errors, either in units of
        the integration time (if a number is given) or in time.
        default : 1.0 (integrations - each independent)

HSP: random_seed - Seed for random number generator to ensure
        repeatibility.  default : internal seed different every time

HSP: point_rms, point_ct - pointing errors
        rms pointing error, coherence time 
        default : use ALMA spec? (0.6"?)

            Independent of antenna if scalar, but the user can provide lists of
            values for each antenna.

HMP: phase_screen - image of atmospheric phase screen over array for the wind
		    to blow around.
		    Default: 0.

HMP: wind_rms, wind_ct - rms wind speed and coherence time
		         ONLY used to push phase_screen around.  Any effects of
		         the wind on pointing (except for the standard 0.6")
			 should be guessed at by the user and put in point_rms
			 and point_ct.

SP: leakage_rms - rms polarization (on-axis) leakage of each antenna.
        Alternatively, a file for the leakages to be used for each antenna.
	Default: '0.0deg' or default for each band
	AP: band (if we implement band defaults)

SP: leakage_map - an image of the polarization response of the telescope
	for off-axis polarization leakage patterns
	Default: '' or default map for each band?
	AP: band (if standard band maps are supplied)

--------------------------------------------------------
8. Imaging Setup
--------------------------------------------------------

MP: deconv_alg - a deconvolution algorithm supported by imager.
        Basic choices are 'clean' and 'mem'.
	Default: 'clean'

MP: sd_diam - Diameter of single dish used to fill in short baselines.
        The default action will be to convolve the model image (or
        other user supplied image) with a beam corresponding to a 
        telescope of this diameter and use this in feathering.
        If sd_diam < 0, use model but with no convolution.
        If sd_diam = 0, turn off feathering.
	Default: '0.0m' (no TP feathering)

SP: tpimage - an image to be used to simulate adding total power
        data.  If sd_diam>0 this will be convolved to that telescope
        PSF diameter.
        Default: <image-model> (the final total model)

SP: autocor_wt - weight with which to include main array or ACA 
        autocorrelations.
     	Default: 0.0 (no autocor)

SP: simager_ms - list of ms to include in imaging.  By default this
        contains the ms just generated.  Users can add additional
        ms to this list to simulate adding mult-config data (including
        separate ACA observations to main array).  Eventually can add
        true SD ms to really simulate joint deconvolution (not just
        feathering).

    	Default: <project>.ms from current sim run.

SP: imsize - image size in spatial pixels (x,y)
	Default: covers area selected in current mos_shape
        AP: band, mos_shape

SP: cell - image cell size e.g '10arcsec'
        Default: 1/3 of band synth. beamsize
        AP: band

SP: stokes - Stokes parameters to image, e.g. stokes='IQUV'
        <Options: 'I','IV','IQU','IQUV'>
	Default='I'

SP: weighting - weighting to apply to visibilities, e.g. weighting='uniform'
        <Options: 'natural','uniform','briggs','radial', 'superuniform'>
	Default='natural'

SP: rmode - Brigg's robustness mode (DO WE NEED	THIS?)
        <Options: 'norm','abs','none'>
        Default='none'

SP: robust - Brigg's robustness parameter 
	<Options: -2.0 to 2.0; -2 (uniform)/+2 (natural)>
        Default=0.0

Some possible others:

HSP: uvtaper - Gaussian uvtaper

HSP: uvrange - min, max uvrange


8.1 CLEAN deconvolution params

    These options depend upon choice of deconv_alg='clean'.

SP: clean_niter - max number of clean iterations

SP: clean_gain - clean gain factor

SP: clean_rms - residual threshold to stop clean


8.2 MEM deconvolution params

    These options depend upon choice of deconv_alg='mem'.

SP: mem_niter - max number of mem iterations

SP: mem_flux - total flux in image for mem

SP: mem_rms - estimate of the noise for mem


--------------------------------------------------------
9. Display Setup
--------------------------------------------------------

MP: display - plot array config, uv coverage, beam, and images
         <Options: True/False>
         Default=True

         If True will also write file <project>.ps containing
         the plot.