Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/simalma.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 18:48 +0000
1##################### generated by xml-casa (v2) from simalma.xml ###################
2##################### 4a3ac82c1288b5699e222ce63d959cad ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_simalma import simalma as _simalma_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _simalma:
15 """
16 simalma ---- Simulation task for ALMA
19 This task simulates ALMA observation including 12-m, ACA 7-m and total
20 power arrays, and images and analyzes simulated data.
22 This task makes multiple calls to simobserve (to calculate
23 visibilities and total power spectra), followed by gridding of total
24 power spectra (if total power is requested), concatenation of the
25 simulated visibilities, calls to the simanalyze task for visibility
26 inversion and deconvolution and calculation of difference and fidelity
27 images, and feathering of single dish and interferometric data.
29 These steps may not all be familiar to new users, so the simalma task
30 runs by default in a "dryrun" mode, in which it assesses the user's
31 input parameters and sky model, and prints an informational report
32 including the required calls to other CASA tasks, both to the screen
33 and to a text file in the project directory (defined below).
35 The user can modify their parameters based on the information, then
36 either run with dryrun=False to actually call the other tasks to
37 create the simulated data, or run the other tasks individually one at
38 a time to better understand and control the process.
40 NOTE The ALMA project is refining the optimal method of combining the
41 three types of data. If that best practice is changed after this
42 release of CASA, the user can control the process by modifying the
43 calls to the other CASA tasks.
45 --------- parameter descriptions ---------------------------------------------
47 project root prefix for output file names
48 dryrun dryrun=True will only produce the informative report, not run simobserve/analyze
49 skymodel model image to observe
50 inbright scale surface brightness of brightest pixel e.g. "1.2Jy/pixel"
51 indirection set new direction e.g. "J2000 19h00m00 -40d00m00"
52 incell set new cell/pixel size e.g. "0.1arcsec"
53 incenter set new frequency of center channel e.g. "89GHz" (required even for 2D model)
54 inwidth set new channel width e.g. "10MHz" (required even for 2D model)
55 complist componentlist to observe
56 compwidth bandwidth of components
57 setpointings If True, calculate a map of pointings and write *ptgfile*.
58 ptgfile list of pointing positions
59 integration integration (sampling) time
60 direction "J2000 19h00m00 -40d00m00" or "" to center on model
61 mapsize angular size of map or "" to cover model
62 antennalist antenna position files of ALMA 12m and 7m arrays
63 hourangle hour angle of observation center e.g. -3:00:00, or "transit"
64 totaltime total time of observation; vector corresponding to antennalist
65 tpnant Number of total power antennas to use (0-4)
66 tptime total observation time for total power
67 pwv Precipitable Water Vapor in mm. 0 for noise-free simulation
68 image image simulated data
69 imsize output image size in pixels (x,y) or 0 to match model
70 imdirection set output image direction, (otherwise center on the model)
71 cell cell size with units or "" to equal model
72 niter maximum number of iterations (0 for dirty image)
73 threshold flux level (+units) to stop cleaning
74 graphics display graphics at each stage to [screen|file|both|none]
75 verbose Print extra information to the logger and terminal.
76 overwrite overwrite files starting with $project
77 [1;42mRETURNS[1;m bool
79 --------- examples -----------------------------------------------------------
82 -------------------------------
83 Parameters:
85 project -- root filename for all output files. A subdirectory will be
86 created, and all created files will be placed in that subdirectory
87 including the informational report.
89 -------------------------------
90 skymodel -- input image (used as a model of the sky)
91 * simalma requires a CASA or fits image. If you merely have a grid of
92 numbers, you will need to write them out as fits or write a
93 CASA script to read them in and use the ia tool to create an image
94 and insert the data.
96 * simalma does NOT require a coordinate system in the header. If the
97 coordinate information is incomplete, missing, or you would like to
98 override it, set the appropriate "in" parameters. NOTE that setting
99 those parameters simply changes the header values, ignoring
100 any values already in the image. No regridding is performed.
102 * If you have a proper Coordinate System, simalma will do its best to
103 generate visibilities from that, and then create a synthesis image
104 according to the specified user parameters.
106 * You can manipulate an image header manually with the "imhead" task.
108 inbright -- peak brightness to scale the image to in Jy/pixel,
109 or "" for unchanged
110 * NOTE: "unchanged" will take the numerical values in your image
111 and assume they are in Jy/pixel, even if it says some other unit
112 in the header.
114 indirection -- central direction to place the sky model image,
115 or "" to use whatever is in the image already
117 incell -- spatial pixel size to scale the skymodel image,
118 or "" to use whatever is in the image already.
120 incenter -- frequency to use for the center channel (or only channel,
121 if the skymodel is 2D) e.g. "89GHz",
122 or "" to use what is in the header.
124 inwidth -- width of channels to use, or "" to use what is in the image
125 should be a string representing a quantity with units e.g. "10MHz"
126 * NOTE: only works reliably with frequencies, not velocities
127 * NOTE: it is not possible to change the number of spectral planes
128 of the sky model, only to relabel them with different frequencies
129 That kind of regridding can be accomplished with the CASA toolkit.
131 -------------------------------
132 complist -- component list model of the sky, added to or instead of skymodel
133 see http://casaguides.nrao.edu/index.php?title=Simulation_Guide_Component_Lists_%28CASA_4.1%29
135 compwidth -- bandwidth of components; if simulating from components only,
136 this defines the bandwidth of the MS and output images
138 -------------------------------
139 setpointings -- if true, calculate a map of pointings and write ptgfile.
140 * if graphics are on, display the pointings shown on the model image
141 * observations with the ALMA 12m and ACA 7m arrays will observe a
142 region of size "mapsize" using the same hexagonal algorithm as
143 the ALMA OT, with Nyquist sampling.
144 * The total power array maps a slightly (+1 primary beam) larger area
145 than the 12m array does, to improve later image combination.
146 It samples the region with lattice grids of spacing 0.33 lambda/D.
147 * if setpointings=false, read pointings from ptgfile.
149 ptgfile -- a text file specifying directions in the same
150 format as the example, and optional integration times, e.g.
151 #Epoch RA DEC TIME(optional)
152 J2000 23h59m28.10 -019d52m12.35 10.0
153 * if the time column is not present in the file, it will use
154 "integration" for all pointings.
155 * NOTE: at this time the file should contain only science pointings:
156 simalma will observe these until totaltime is used up.
158 integration --- Time interval for each integration e.g '10s'
159 * NOTE: to simulate a "scan" longer than one integration, use
160 setpointings to generate a pointing file, and then edit the
161 file to increase the time at each point to be larger than
162 the parameter integration time.
164 direction -- mosaic center direction e.g 'J2000 19h00m00 -40d00m00'
165 if unset, will use the center of the skymodel image.
166 * can optionally be a list of pointings, otherwise
167 * simobserve will cover a region of size mapsize according to maptype
169 mapsize -- angular size of mosaic map to simulate.
170 * set to "" to cover the model image
172 -------------------------------
173 antennalist -- vector of ascii files containing antenna positions,
174 one for each configuration of 7m or 12m dishes.
175 * NOTE: In this task, it should be an ALMA configuration.
176 * standard arrays are found in your CASA data repository,
177 os.getenv("CASAPATH").split()[0]+"/data/alma/simmos/"
178 * a string of the form "alma;0.5arcsec" will be parsed into a
179 12m ALMA configuration - see casaguides.nrao.edu
180 * examples: ['alma.cycle2.5.cfg','aca.cycle2.i.cfg']
181 ['alma.cycle1;0.3arcsec','alma.cycle1.1.cfg','aca.i.cfg']
183 hourangle -- hour angle of observation e.g. '-3h'
185 totaltime --- total time of observations. This should either be a scalar
186 time quantity expressed as a string e.g. '1h', '3600sec', '10min',
187 or a vector of such quantities, corresponding to the elements of
188 the antennalist vector, e.g. ['5min','20min','3h']. If you
189 specify a scalar, that will be used for the highest resolution
190 12m configuration in antennalist, and any lower resolution 12m
191 configurations, any 7m configurations, and any TP configurations
192 will have observing times relative to totaltime of 0.5, 2,and 4,
193 respectively.
194 -------------------------------
196 tpnant -- the number of total power antennas to use in simulation.
198 tptime -- if tpnant>0, the user must specify the observing time for
199 total power as a CASA quantity e.g. '4h'.
200 * NOTE: this is not broken up among multiple days -
201 a 20h track will include observations below the horizon,
202 which is probably not what is desired.
204 -------------------------------
205 pwv -- precipitable water vapor if constructing an atmospheric model.
206 Set 0 for noise-free simulation. When pwv>0, thermal noise is
207 applied to the simulated data.
208 * J. Pardo's ATM library will be used to construct anatmospheric
209 profile for the ALMA site:
210 altitude 5000m, ground pressure 650mbar, relhum=20%,
211 a water layer of pwv at altitude of 2km,
212 the sky brightness temperature returned by ATM, and internally
213 tabulated receiver temperatures.
214 See the documentation of simobserve for more details.
216 -------------------------------
217 image -- option to invert and deconvolve the simulated measurement set(s)
218 * NOTE: interactive clean or more parameters than the subset visible
219 here are available by simply running the clean task directly.
220 * if graphics turned on, display the clean image and residual image
221 * uses Cotton-Schwab clean for single fields and Mosaic gridding
222 for multiple fields (with Clark PSF calculation in minor cycles).
224 imsize -- image size in spatial pixels (x,y)
225 0 or -1 will use the model image size; example: imsize=[500,500]
227 imdirection -- phase center for synthesized image. default is to
228 center on the sky model.
230 cell -- cell size e.g '10arcsec'. "" defaults to the skymodel cell
232 niter -- number of clean/deconvolution iterations, 0 for no cleaning
234 threshold -- flux level to stop cleaning
235 -------------------------------
236 graphics -- view plots on the screen, saved to file, both, or neither
237 verbose -- print extra information to the logger and terminal
238 overwrite -- overwrite existing files in the project subdirectory
239 -------------------------------
241 Please see the documents of simobserve and simanalyze for
242 the list of outputs produced.
246 """
248 _info_group_ = """simulation"""
249 _info_desc_ = """Simulation task for ALMA """
251 def __call__( self, project='sim', dryrun=True, skymodel='', inbright='', indirection='', incell='', incenter='', inwidth='', complist='', compwidth='"8GHz"', setpointings=True, ptgfile='$project.ptg.txt', integration='10s', direction=[ ], mapsize=[ '','' ], antennalist=[ 'alma.cycle1.1.cfg','aca.cycle1.cfg' ], hourangle='transit', totaltime=[ '20min','1h' ], tpnant=int(0), tptime='0s', pwv=float(0.5), image=True, imsize=[ int(128),int(128) ], imdirection='', cell='', niter=int(0), threshold='0.1mJy', graphics='both', verbose=False, overwrite=False ):
252 schema = {'project': {'type': 'cStr', 'coerce': _coerce.to_str}, 'dryrun': {'type': 'cBool'}, 'skymodel': {'type': 'cStr', 'coerce': _coerce.to_str}, 'inbright': {'type': 'cStr', 'coerce': _coerce.to_str}, 'indirection': {'type': 'cStr', 'coerce': _coerce.to_str}, 'incell': {'type': 'cStr', 'coerce': _coerce.to_str}, 'incenter': {'type': 'cStr', 'coerce': _coerce.to_str}, 'inwidth': {'type': 'cStr', 'coerce': _coerce.to_str}, 'complist': {'type': 'cStr', 'coerce': _coerce.to_str}, 'compwidth': {'type': 'cStr', 'coerce': _coerce.to_str}, 'setpointings': {'type': 'cBool'}, 'ptgfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'integration': {'type': 'cStr', 'coerce': _coerce.to_str}, 'direction': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'mapsize': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'antennalist': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'hourangle': {'type': 'cStr', 'coerce': _coerce.to_str}, 'totaltime': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'tpnant': {'type': 'cInt', 'min': 0, 'max': 4}, 'tptime': {'type': 'cStr', 'coerce': _coerce.to_str}, 'pwv': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': 0}, 'image': {'type': 'cBool'}, 'imsize': {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, 'imdirection': {'type': 'cStr', 'coerce': _coerce.to_str}, 'cell': {'type': 'cStr', 'coerce': _coerce.to_str}, 'niter': {'type': 'cInt'}, 'threshold': {'type': 'cStr', 'coerce': _coerce.to_str}, 'graphics': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'none', 'file', 'both', 'screen', '' ]}, 'verbose': {'type': 'cBool'}, 'overwrite': {'type': 'cBool'}}
253 doc = {'project': project, 'dryrun': dryrun, 'skymodel': skymodel, 'inbright': inbright, 'indirection': indirection, 'incell': incell, 'incenter': incenter, 'inwidth': inwidth, 'complist': complist, 'compwidth': compwidth, 'setpointings': setpointings, 'ptgfile': ptgfile, 'integration': integration, 'direction': direction, 'mapsize': mapsize, 'antennalist': antennalist, 'hourangle': hourangle, 'totaltime': totaltime, 'tpnant': tpnant, 'tptime': tptime, 'pwv': pwv, 'image': image, 'imsize': imsize, 'imdirection': imdirection, 'cell': cell, 'niter': niter, 'threshold': threshold, 'graphics': graphics, 'verbose': verbose, 'overwrite': overwrite}
254 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
255 _logging_state_ = _start_log( 'simalma', [ 'project=' + repr(_pc.document['project']), 'dryrun=' + repr(_pc.document['dryrun']), 'skymodel=' + repr(_pc.document['skymodel']), 'inbright=' + repr(_pc.document['inbright']), 'indirection=' + repr(_pc.document['indirection']), 'incell=' + repr(_pc.document['incell']), 'incenter=' + repr(_pc.document['incenter']), 'inwidth=' + repr(_pc.document['inwidth']), 'complist=' + repr(_pc.document['complist']), 'compwidth=' + repr(_pc.document['compwidth']), 'setpointings=' + repr(_pc.document['setpointings']), 'ptgfile=' + repr(_pc.document['ptgfile']), 'integration=' + repr(_pc.document['integration']), 'direction=' + repr(_pc.document['direction']), 'mapsize=' + repr(_pc.document['mapsize']), 'antennalist=' + repr(_pc.document['antennalist']), 'hourangle=' + repr(_pc.document['hourangle']), 'totaltime=' + repr(_pc.document['totaltime']), 'tpnant=' + repr(_pc.document['tpnant']), 'tptime=' + repr(_pc.document['tptime']), 'pwv=' + repr(_pc.document['pwv']), 'image=' + repr(_pc.document['image']), 'imsize=' + repr(_pc.document['imsize']), 'imdirection=' + repr(_pc.document['imdirection']), 'cell=' + repr(_pc.document['cell']), 'niter=' + repr(_pc.document['niter']), 'threshold=' + repr(_pc.document['threshold']), 'graphics=' + repr(_pc.document['graphics']), 'verbose=' + repr(_pc.document['verbose']), 'overwrite=' + repr(_pc.document['overwrite']) ] )
256 task_result = None
257 try:
258 task_result = _simalma_t( _pc.document['project'], _pc.document['dryrun'], _pc.document['skymodel'], _pc.document['inbright'], _pc.document['indirection'], _pc.document['incell'], _pc.document['incenter'], _pc.document['inwidth'], _pc.document['complist'], _pc.document['compwidth'], _pc.document['setpointings'], _pc.document['ptgfile'], _pc.document['integration'], _pc.document['direction'], _pc.document['mapsize'], _pc.document['antennalist'], _pc.document['hourangle'], _pc.document['totaltime'], _pc.document['tpnant'], _pc.document['tptime'], _pc.document['pwv'], _pc.document['image'], _pc.document['imsize'], _pc.document['imdirection'], _pc.document['cell'], _pc.document['niter'], _pc.document['threshold'], _pc.document['graphics'], _pc.document['verbose'], _pc.document['overwrite'] )
259 except Exception as exc:
260 _except_log('simalma', exc)
261 raise
262 finally:
263 task_result = _end_log( _logging_state_, 'simalma', task_result )
264 return task_result
266simalma = _simalma( )