Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/simobserve.py: 100%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-11-01 07:19 +0000
1##################### generated by xml-casa (v2) from simobserve.xml ################
2##################### 0e3aaa53282e4e44cb7a3dfe57d8f593 ##############################
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_simobserve import simobserve as _simobserve_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 _simobserve:
15 """
16 simobserve ---- visibility simulation task
19 This task simulates interferometric or total power measurment sets. It
20 is currently optimized for JVLA and ALMA, although many observatories
21 are included, and adding your own is simply a matter of providing an
22 antenna location file (see below).
24 simobserve is meant to work in conjunction with the simanalyze
25 task. Calling simobserve one more times will produce simulated
26 measurement set(s), which are then gridded, inverted and deconvolved
27 into output simulated images using simanalyze.
29 ALMA users are encouraged to use the simalma task, which provides
30 additional information on the multiple simobserve and simanalyze calls
31 required to simulate an ALMA observation which may consist of 12m
32 interferometric, 7m interferometric, and 12m total power data.
34 More information and examples are availible in the CASA Guides (http://casaguides.nrao.edu) under Simulations.
35 Please contact the CASA Team with any questions (see
36 https://casa.nrao.edu/index_contact.shtml)
38 --------- parameter descriptions ---------------------------------------------
40 project root prefix for output file names
41 skymodel Model image to observe
43 * simobserve uses a CASA or fits image. If you
44 merely have a grid of numbers, you will need to
45 write them out as fits or write a CASA script to
46 read them in and use the ia tool to create an
47 image and insert the data.
49 * simobserve does NOT require a coordinate system
50 in the header. If the coordinate information is
51 incomplete, missing, or you would like to
52 override it, set the appropriate "in"
53 parameters. NOTE that setting those parameters
54 simply changes the header values, ignoring any
55 values already in the image. No regridding is
56 performed.
58 * You can also manipulate an image header manually
59 with the "imhead" task.
61 * If you have a proper Coordinate System,
62 simobserve will do its best to generate
63 visibilities from that.
64 inbright Peak brightness to scale the image to, in Jy/pixel
65 Subparameter of skymodel
66 Default: '' (i.e., unchanged)
68 Example: inbright='1.2Jy/pixel'
70 Note: "unchanged" will take the numerical values
71 in your image and assume they are in Jy/pixel,
72 even if it says some other unit in the header.
73 indirection Central direction to place the sky model image
74 Subparameter of skymodel
75 Default: '' (use whatever is in the image
76 already)
78 Example: indirection='J2000 19h00m00
79 -40d00m00'
80 incell set new cell/pixel size
81 Subparameter of skymodel
82 Default: '' (use whatever is in the image
83 already)
85 Example: incell='0.1arcsec'
86 incenter Frequency to use for the center channel (or only channel,
87 if the skymodel is 2D).
88 Subparameter of skymodel
89 Default: '' (use whatever is in the image
90 already)
92 This will also become the default rest frequency, e.g. when imaging with tclean.
94 Example: incenter='89GHz'
95 inwidth Set new channel width
96 Subparameter of skymodel
97 Default: '' (use whatever is in the image
98 already)
100 Should be a string representing a quantity with
101 units e.g. inwidth='10MHz'
103 NOTES:
104 * Only works reliably with frequencies, not
105 velocities
106 * It is not possible to change the number of
107 spectral planes of the sky model, only to relabel
108 them with different frequencies That kind of
109 regridding can be accomplished with the CASA
110 toolkit.
111 complist Component list model of the sky, added to or instead of skymodel.
112 compwidth Bandwidth of components
113 Subparameter of complist
115 If simulating from components only, this defines
116 the bandwidth of the MS and output images
118 Example: compwidth='8GHz'
119 comp_nchan Channelization of components
120 Subparameter of complist
122 If simulating from components only, this defines
123 the number of channels of the MeasurementSet
125 Example: comp_nchan=256
126 setpointings If true, calculate a map of pointings and write ptgfile. If false, read pointings from ptgfile.
127 Default: True
129 If graphics are on, display the pointings shown
130 on the model image
131 ptgfile A text file specifying directions
132 Subparameter of setpointings=False
134 The text file should have the following format,
135 with optional integration times:
136 Epoch RA DEC TIME(optional)
137 J2000 23h59m28.10 -019d52m12.35 10.0
139 If the time column is not present in the file, it
140 will use "integration" for all pointings.
142 NOTE: at this time the file should contain only
143 science pointings: simobserve will observe these,
144 then optionally the calibrator, then the list of
145 science pointings again, etc, until totaltime is
146 used up.
147 integration Time interval for each integration
148 Subparameter of setpointings=False
150 Example: integration='10s'
152 NOTE: to simulate a "scan" longer than one
153 integration, use setpointings to generate a
154 pointing file, and then edit the file to increase
155 the time at each point to be larger than the
156 parameter integration time.
157 direction Mosaic center direction.
158 Subparameter of setpointings=True
160 Example: "J2000 19h00m00 -40d00m00" or "" to
161 center on model
163 If unset, will use the center of the skymodel
164 image.
165 * can optionally be a list of pointings, otherwise
166 * simobserve will cover a region of size mapsize
167 according to maptype
168 mapsize Angular size of of mosaic map to simulate.
169 Subparameter of setpointings=True
171 Set to "" to cover model
172 maptype How to calculate the pointings for the mosaic
173 observation?
174 Subparameter of setpointings=True
175 Options: hexagonal, square (raster), ALMA, etc
177 "ALMA" for the same hex algorithm as the ALMA
178 Cycle 1 OT or "ALMA2012" for the algorithm used
179 in the Cycle 0 OT
180 pointingspacing Spacing in between pointings.
181 Subparameter of setpointings=True
183 Examples:
184 pointingspacing="0.25PB"
185 pointingspacing="" for ALMA default
186 INT=lambda/D/sqrt(3), SD=lambda/D/3
187 caldirection pt source calibrator [experimental]
188 calflux pt source calibrator flux [experimental]
189 obsmode Observation mode to simulate
190 Options: int(interferometer)|sd(singledish)|""(none)
192 Observation mode to calculate visibilities from a
193 skymodel image (which may have been modified
194 above), an optional component list, and a
195 pointing file (which also may have been generated
196 above).
198 This parameter takes two possible values:
199 - interferometer (or int)
200 - singledish (or sd)
201 * If graphics are on, this observe step will
202 display the array (similar to plotants), the uv
203 coverage, the synthesized (dirty) beam, and
204 ephemeris information
205 * If simulating from a component list, you should
206 specify "compwidth", the desired bandwidth; and
207 specify "comp_nchan", the desired channelization
208 if more than one output channel is desired
209 refdate Date of simulated observation
210 Subparameter of obsmode='int|sd'
211 Not critical unless concatting simulations
213 Example: refdate="2014/05/21"
214 hourangle Hour angle of observation center.
215 Subparameter of obsmode='int|sd'
217 Examples:
218 hourangle="-3:00:00", "5h", or "transit"
219 totaltime Total time of observation or number of repetitions
220 Subparameter of obsmode='int|sd'
222 Example:
223 totaltime='7200s'
224 If a number without units, interpreted as the
225 number of times to repeat the mosaic.
226 antennalist Text file containing antenna positions.
227 Subparameter of obsmode='int|""'
229 Each row has x y z coordinates and antenna diameter
230 with optional station name and antenna name.
231 Header lines are required to specify:
232 # observatory=ALMA
233 # coordsys=UTM
235 If the Universal Transverse Mercator projection is
236 specified, then other keywords are required:
237 # datum=WGS84
238 # zone=19
239 # hemisphere=S
241 If the observatory keyword is not defined, then the
242 COFA keyword should be, using a coordinate pair:
243 #COFA=-67.75,-23.02
245 * Standard array configurations are found in your
246 CASA data repository,
247 * If "", simobserve will not not produce an
248 interferometric MS
249 * A string of the form "alma;0.5arcsec" will be
250 parsed into a full 12m ALMA configuration.
251 sdantlist single dish antenna position file
252 Subparameter of obsmode='sd|""'
253 sdant Index of the antenna in the list to use for total power.
254 Subparameter of obsmode='sd|""'
255 Default: first antenna on the list.
256 outframe spectral frame of MS to create
257 Subparameter of obsmode='sd|""'
258 thermalnoise add thermal noise.
259 Options: tsys-atm, tsys-manual, ""
261 This parameter accepts two settings:
262 - tsys-atm: J. Pardo's ATM library will be used
263 to construct an atmospheric profile for the ALMA
264 site: altitude 5000m, ground pressure 650mbar,
265 relhum=20%, a water layer of user_pwv at altitude
266 of 2km, the sky brightness temperature returned
267 by ATM, and internally tabulated receiver
268 temperatures.
269 - tsys-manual: instead of using the ATM model,
270 specify the zenith sky brightness and opacity
271 manually. Noise is added and then the visibility
272 flux scale is referenced above the atmosphere.
274 If left unset (empty string) no thermalnoise
275 corruption is performed.
277 In either mode, noise is calculated using an
278 antenna spillover efficiency of 0.96, taper of
279 0.86, surface accuracy of 25 and 300 microns for
280 ALMA and EVLA respectively (using the Ruze
281 formula for surface efficiency), correlator
282 efficiencies of 0.95 and 0.91 for ALMA and EVLA,
283 receiver temperatures
284 for ALMA of 17, 30, 37, 51, 65,
285 83,147,196,175,230 K interpolated between 35,
286 75,110,145,185,230,345,409,675,867 GHz,
287 for EVLA of 500, 70, 60, 55, 100, 130, 350 K
288 interpolated between
289 0.33,1.47,4.89,8.44,22.5,33.5,43.3 GHz,
290 for SMA of 67, 116, 134, 500 K interpolated
291 between 212.,310.,383.,660. GHz.
293 Note: These are only approximate numbers and do
294 not take into account performance at edges of
295 receiver bands, neither are they guaranteed to
296 reflect the most recent measurements. Caveat
297 emptor. Use the sm tool to add noise if you want
298 more precise control, and use the ALMA exposure
299 time calculator for sensitivity numbers in
300 proposals.
301 user_pwv Precipitable water vapor if constructing an atmospheric
302 model (in mm)
303 Subparameter of thermalnoise='tsys-atm'
304 t_ground Ground/spillover temperature in K
305 Subparameter of
306 thermalnoise='tsys-atm|tsys-manual'
307 t_sky Atmospheric temperature in K
308 Subparameter of thermalnoise='tsys-manual'
309 tau0 Zenith opacity at observing frequency
310 Subparameter of thermalnoise='tsys-manual'
312 See the Simulations CASA Guide (https://casaguides.nrao.edu) on 'Corrupting Simulated Data' for more information on noise, in particular how to add a phase screen using the toolkit
313 seed Random number seed
314 Subparameter of
315 thermalnoise='tsys-atm|tsys-manual'
316 leakage add cross polarization corruption of this fractional
317 magnitude (interferometer only)
318 graphics View plots on the screen, saved to file, both, or neither
319 Options: screen|file|both|none
320 verbose Print extra information to the logger and terminal
321 Default: False
322 Options: True|False
323 overwrite Overwrite files starting with $project
324 Default: False
325 Options: True|False
326 [1;42mRETURNS[1;m bool
328 --------- examples -----------------------------------------------------------
333 For more information, see the task pages of simobserve in CASA Docs:
335 https://casa.nrao.edu/casadocs/
338 """
340 _info_group_ = """simulation"""
341 _info_desc_ = """visibility simulation task"""
343 def __call__( self, project='sim', skymodel='', inbright='', indirection='', incell='', incenter='', inwidth='', complist='', compwidth='"8GHz"', comp_nchan=int(1), setpointings=True, ptgfile='$project.ptg.txt', integration='10s', direction=[ ], mapsize=[ '','' ], maptype='hexagonal', pointingspacing='', caldirection='', calflux='1Jy', obsmode='int', refdate='2014/01/01', hourangle='transit', totaltime='7200s', antennalist='', sdantlist='aca.tp.cfg', sdant=int(0), outframe='LSRK', thermalnoise='tsys-atm', user_pwv=float(0.5), t_ground=float(270.), t_sky=float(260.), tau0=float(0.1), seed=int(11111), leakage=float(0.0), graphics='both', verbose=False, overwrite=True ):
344 schema = {'project': {'type': 'cStr', 'coerce': _coerce.to_str}, '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}, 'comp_nchan': {'type': 'cInt'}, '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]}, 'maptype': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'alma', 'square', 'hexagonal', 'ALMA-OT', 'ALMA', 'ALMA2012', 'hex' ]}, 'pointingspacing': {'type': 'cStr', 'coerce': _coerce.to_str}, 'caldirection': {'type': 'cStr', 'coerce': _coerce.to_str}, 'calflux': {'type': 'cStr', 'coerce': _coerce.to_str}, 'obsmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ '', 'int', 'sd' ]}, 'refdate': {'type': 'cStr', 'coerce': _coerce.to_str}, 'hourangle': {'type': 'cStr', 'coerce': _coerce.to_str}, 'totaltime': {'type': 'cStr', 'coerce': _coerce.to_str}, 'antennalist': {'type': 'cStr', 'coerce': _coerce.to_str}, 'sdantlist': {'type': 'cStr', 'coerce': _coerce.to_str}, 'sdant': {'type': 'cInt'}, 'outframe': {'type': 'cStr', 'coerce': _coerce.to_str}, 'thermalnoise': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ '', 'tsys-atm', 'tsys-manual' ]}, 'user_pwv': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': 0}, 't_ground': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': 0}, 't_sky': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': 0}, 'tau0': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': 0}, 'seed': {'type': 'cInt'}, 'leakage': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': 0}, 'graphics': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'none', 'file', 'both', 'screen', '' ]}, 'verbose': {'type': 'cBool'}, 'overwrite': {'type': 'cBool'}}
345 doc = {'project': project, 'skymodel': skymodel, 'inbright': inbright, 'indirection': indirection, 'incell': incell, 'incenter': incenter, 'inwidth': inwidth, 'complist': complist, 'compwidth': compwidth, 'comp_nchan': comp_nchan, 'setpointings': setpointings, 'ptgfile': ptgfile, 'integration': integration, 'direction': direction, 'mapsize': mapsize, 'maptype': maptype, 'pointingspacing': pointingspacing, 'caldirection': caldirection, 'calflux': calflux, 'obsmode': obsmode, 'refdate': refdate, 'hourangle': hourangle, 'totaltime': totaltime, 'antennalist': antennalist, 'sdantlist': sdantlist, 'sdant': sdant, 'outframe': outframe, 'thermalnoise': thermalnoise, 'user_pwv': user_pwv, 't_ground': t_ground, 't_sky': t_sky, 'tau0': tau0, 'seed': seed, 'leakage': leakage, 'graphics': graphics, 'verbose': verbose, 'overwrite': overwrite}
346 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
347 _logging_state_ = _start_log( 'simobserve', [ 'project=' + repr(_pc.document['project']), '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']), 'comp_nchan=' + repr(_pc.document['comp_nchan']), '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']), 'maptype=' + repr(_pc.document['maptype']), 'pointingspacing=' + repr(_pc.document['pointingspacing']), 'caldirection=' + repr(_pc.document['caldirection']), 'calflux=' + repr(_pc.document['calflux']), 'obsmode=' + repr(_pc.document['obsmode']), 'refdate=' + repr(_pc.document['refdate']), 'hourangle=' + repr(_pc.document['hourangle']), 'totaltime=' + repr(_pc.document['totaltime']), 'antennalist=' + repr(_pc.document['antennalist']), 'sdantlist=' + repr(_pc.document['sdantlist']), 'sdant=' + repr(_pc.document['sdant']), 'outframe=' + repr(_pc.document['outframe']), 'thermalnoise=' + repr(_pc.document['thermalnoise']), 'user_pwv=' + repr(_pc.document['user_pwv']), 't_ground=' + repr(_pc.document['t_ground']), 't_sky=' + repr(_pc.document['t_sky']), 'tau0=' + repr(_pc.document['tau0']), 'seed=' + repr(_pc.document['seed']), 'leakage=' + repr(_pc.document['leakage']), 'graphics=' + repr(_pc.document['graphics']), 'verbose=' + repr(_pc.document['verbose']), 'overwrite=' + repr(_pc.document['overwrite']) ] )
348 task_result = None
349 try:
350 task_result = _simobserve_t( _pc.document['project'], _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['comp_nchan'], _pc.document['setpointings'], _pc.document['ptgfile'], _pc.document['integration'], _pc.document['direction'], _pc.document['mapsize'], _pc.document['maptype'], _pc.document['pointingspacing'], _pc.document['caldirection'], _pc.document['calflux'], _pc.document['obsmode'], _pc.document['refdate'], _pc.document['hourangle'], _pc.document['totaltime'], _pc.document['antennalist'], _pc.document['sdantlist'], _pc.document['sdant'], _pc.document['outframe'], _pc.document['thermalnoise'], _pc.document['user_pwv'], _pc.document['t_ground'], _pc.document['t_sky'], _pc.document['tau0'], _pc.document['seed'], _pc.document['leakage'], _pc.document['graphics'], _pc.document['verbose'], _pc.document['overwrite'] )
351 except Exception as exc:
352 _except_log('simobserve', exc)
353 raise
354 finally:
355 task_result = _end_log( _logging_state_, 'simobserve', task_result )
356 return task_result
358simobserve = _simobserve( )