Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/simulator.py: 58%
79 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 17:39 +0000
1##################### generated by xml-casa (v2) from simulator.xml #################
2##################### fa27e622696d3e2e500786ae4519c6b1 ##############################
3from __future__ import absolute_import
4from .__casac__.simulator import simulator as _simulator
6from .errors import create_error_string
7from .typecheck import CasaValidator as _validator
8_pc = _validator( )
9from .coercetype import coerce as _coerce
12class simulator:
13 _info_group_ = """simulator"""
14 _info_desc_ = """Tool for simulation"""
15 ### self
16 def __init__(self, *args, **kwargs):
17 """Create a simulator tool.
19 """
20 self._swigobj = kwargs.get('swig_object',None)
21 if self._swigobj is None:
22 self._swigobj = _simulator()
24 def open(self, ms=''):
25 """A simulator tool can either operate on an existing MeasurementSet,
26 predicting and/or corrupting data on the existing uvw coordinates
28 -- to do that open the MS with sm.openfromms(msname).
30 or it can be used to create a new MeasurementSet from descriptions of
31 the array configuration and the observational parameters
33 -- to create a new MS, use this method sm.open(msname).
35 You will also need to run setconfig, setfield, setspw, setspwindow,
36 setfeed, and settimes.
38 Creating the actual (empty) MS is accomplished with sm.observe.
39 Data can be subsequently sm.predict-ed and sm.corrupt-ed.
41 NOTE: sm.predict assumes the model image units are Jy/pixel, and
42 in fact will overwrite the brightness units of the image itself!
44 """
45 return self._swigobj.open(ms)
47 def openfromms(self, ms=''):
48 """A simulator tool can either operate on an existing MeasurementSet,
49 predicting and/or corrupting data on the existing uvw coordinates
50 - to do that open the MS with sm.openfromms(msname)
51 or it can be used to create a new MeasurementSet from descriptions of
52 the array configuration and the observational parameters.
53 - to create a new MS, use sm.open(msname).
55 NOTE: sm.predict assumes the model image units are Jy/pixel, and in
56 fact will overwrite the brightness units of the image itself!
58 """
59 return self._swigobj.openfromms(ms)
61 def close(self):
62 """Close tools and write data to disk. This is a synonym for done.
64 """
65 return self._swigobj.close()
67 def done(self):
68 """Close tools and write data to disk. This is a synonym for done.
70 """
71 return self._swigobj.done()
73 def name(self):
74 """Returns the name of the attached MeasurementSet.
76 """
77 return self._swigobj.name()
79 def summary(self):
80 """Writes a summary of the currently set properties to the default logger.
82 """
83 return self._swigobj.summary()
85 def type(self):
86 """This function returns the string `Simulator'. It is used so that in a
87 script, you can make sure this variable is a simulator tool.
89 """
90 return self._swigobj.type()
92 def settimes(self, integrationtime=[ ], usehourangle=True, referencetime=[ ]):
93 """This method sets values to be used in sm.observe.
95 If usehourangle=False, the start and stop times in sm.observe are
96 referenced to referencetime.
98 If usehourangle=True, then in sm.observe, starttime/stoptime will be
99 interpreted as startha/stopha.
100 In that case, the start and stop times are calculated such that the
101 start time is later than the reference time, but less than one day
102 later. The hour angles refer to the first source observed.
104 """
105 return self._swigobj.settimes(integrationtime, usehourangle, referencetime)
107 def observe(self, sourcename='', spwname='', starttime=[ ], stoptime=[ ], add_observation=False, state_sig=True, state_ref=False, state_cal=float(0.0), state_load=float(0.0), state_sub_scan=int(0), state_obs_mode='OBSERVE_TARGET.ON_SOURCE', observer='CASA simulator', project='CASA simulation'):
108 """Observe a given source with a given spectral window for the specified
109 times, including start, stop, integration, and gap times.
111 If usehourangle=False (set with settimes), the start and stop times
112 are referenced to referencetime.
114 If userhourangle=True, starttime/stoptime are interpreted as
115 startha/stopha, the start and stop times are calculated such that the
116 start time is later than the reference time, but less than one day
117 later, and the hour angles refer to the first source observed.
119 setconfig, setspwindow, setfeed, and setfield must
120 be run before observe can be run.
122 See also sm.observemany
124 """
125 return self._swigobj.observe(sourcename, spwname, starttime, stoptime, add_observation, state_sig, state_ref, state_cal, state_load, state_sub_scan, state_obs_mode, observer, project)
127 def observemany(self, sourcenames=[ ], spwname='', starttimes=[ '0s' ], stoptimes=[ '3600s' ], directions=[ '' ], add_observation=False, state_sig=True, state_ref=False, state_cal=float(0.0), state_load=float(0.0), state_sub_scan=int(0), state_obs_mode='OBSERVE_TARGET#ON_SOURCE', observer='CASA simulator', project='CASA simulation'):
128 """Observe given sources with a given spectral window for the specified
129 times, including start, stop, integration, and gap times.
131 If usehourangle=False (set with settimes), the start and stop times
132 are referenced to referencetime.
134 If userhourangle=True, starttime/stoptime are interpreted as
135 startha/stopha, the start and stop times are calculated such that the
136 start time is later than the reference time, but less than one day
137 later, and the hour angles refer to the first source observed.
139 See also sm.observe
141 """
142 return self._swigobj.observemany(sourcenames, spwname, starttimes, stoptimes, directions, add_observation, state_sig, state_ref, state_cal, state_load, state_sub_scan, state_obs_mode, observer, project)
144 def setlimits(self, shadowlimit=float(1e-6), elevationlimit=[ ]):
145 """Data are flagged for two conditions:
147 - Below elevation limit: If either of the antennas point below the
148 specified elevation limit then the data are flagged. The elevation is
149 calculated correctly for antennas at different locations (such as
150 occurs in VLBI).
152 - Shadowing: If one antenna shadows another such that the fractional
153 (geometric) blockage is greater than the specified limit then the data
154 are flagged. No correction for blockage is made for shadowed but
155 non-flagged points.
157 """
158 return self._swigobj.setlimits(shadowlimit, elevationlimit)
160 def setauto(self, autocorrwt=float(0.0)):
161 """
162 """
163 return self._swigobj.setauto(autocorrwt)
165 def setconfig(self, telescopename='VLA', x=[ float(0) ], y=[ float(0) ], z=[ float(0) ], dishdiameter=[ float(0) ], offset=[ float(0) ], mount=[ 'ALT-AZ' ], antname=[ 'A' ], padname=[ 'P' ], coordsystem='global', referencelocation=[ ]):
166 """Set the positions of the antennas.
167 - The name of the telescope will control which voltage pattern
168 is applied to the data (see sm.setvp for details).
169 - The diameter(s) will be written to the antenna subtable but
170 ONLY affect the calculated visibilities in sm.predict if
171 telescope=ALMA,ACA,OVRO, *and* ftmachine=mosaic
172 (see sm.setvp for details).
173 - simutil::readantenna can be used to read an antenna config. file
174 which includes many existing observatories.
175 see help for the simobserve task, or the example below
177 """
178 return self._swigobj.setconfig(telescopename, x, y, z, dishdiameter, offset, mount, antname, padname, coordsystem, referencelocation)
180 def setfeed(self, mode='', x=[ float(0) ], y=[ float(0) ], pol=[ 'R' ]):
181 """Specify feed parameters. At this moment, you only have the choice
182 between 'perfect R L' and 'perfect X Y' (i.e., you cannot invent
183 your own corrupted feeds yet). Doesn't need to be run if you want
184 perfect R and L feeds.
186 """
187 return self._swigobj.setfeed(mode, x, y, pol)
189 def setfield(self, sourcename='SOURCE', sourcedirection=[ ], calcode='', distance=[ ]):
190 """Set one or more observed fields, including name and coordinates.
191 Can be invoked multiple times for a complex observation.
192 Must be invoked at least once before sm.observe.
194 If the distance to the object is set then the phase term includes a
195 curvature for the near-field effect at the center of the image.
197 """
198 return self._swigobj.setfield(sourcename, sourcedirection, calcode, distance)
200 def setmosaicfield(self, sourcename='SOURCE', calcode='', fieldcenter=[ ], xmosp=int(1), ymosp=int(1), mosspacing=[ ], distance=[ ]):
201 """Set mosaic fields by internally invoking setfield multiple times.
202 Currently only handle a rectangular mosaicing pattern. Either
203 setfield or setmosaicfield must be invoked at least once before
204 observe.
206 If the distance to the object is set then the phase term includes a
207 curvature for the near-field effect at the center of the image.
209 """
210 return self._swigobj.setmosaicfield(sourcename, calcode, fieldcenter, xmosp, ymosp, mosspacing, distance)
212 def setspwindow(self, spwname='XBAND', freq=[ ], deltafreq=[ ], freqresolution=[ ], refcode='TOPO', nchannels=int(1), stokes='RR LL'):
213 """Set one or more spectral windows for the observations, including
214 starting frequency, number of channels, channel increment and
215 resolution, and stokes parameters observed. Can be invoked
216 multiple times for a complex observation. Must be invoked at
217 least once before observe.
219 """
220 return self._swigobj.setspwindow(spwname, freq, deltafreq, freqresolution, refcode, nchannels, stokes)
222 def setdata(self, spwid=[ int(0) ], fieldid=[ int(0) ], msselect=''):
223 """This setup tool function selects which data are to be used
224 subsequently. After invocation of setdata, only the selected data are
225 operated on.
227 """
228 return self._swigobj.setdata(spwid, fieldid, msselect)
230 def predict(self, imagename=[ ], complist='', incremental=False):
231 """Predict astronomical data from an image. The (u,v) coordinates
232 already exist, either from a MeasurementSet we have read in or by
233 generating the MeasurementSet coordinates and empty data through
234 smobserve. This method calculates visibilities for those
235 coordinates.
237 - predict(incremental=False) calculates new visibilities and
238 replaces the DATA column,
239 - predict(incremental=True) calculates new visibilities, adds
240 them to the DATA column
241 - predict for any value of incremental then sets CORRECTED_DATA
242 equal to DATA, and MODEL_DATA to 1
243 - predict assumes model image units are Jy/pixel, and in fact
244 will overwrite the brightness units of the image itself!
245 - treatment of primary beam depends critically on parameters set in
246 sm.setvp() and sm.setoptions(ftmachine) - see help sm.setvp for
247 details. For componentlists, if sm.setvp() is run prior to predict, then the spectral variation of each component in the componentlist will include the multiplicative term of the beam value for each channel frequency. So a flat spectrum component will show the frequency variation of the beam in the predicted visibilities.
250 """
251 return self._swigobj.predict(imagename, complist, incremental)
253 def setoptions(self, ftmachine='ft', cache=int(0), tile=int(16), gridfunction='SF', location=[ ], padding=float(1.3), facets=int(1), maxdata=float(2000.0), wprojplanes=int(1)):
254 """Set options for predict. See also imager help.
256 To simulate single dish data, use gridft=SD and gridfunction=PB.
258 To invoke primary beam convolution in the uv domain, use
259 ftmachine="mosaic". This is the only option that allows
260 heterogeneous array simulation - see the example below and
261 help sm.setvp for more details.
263 """
264 return self._swigobj.setoptions(ftmachine, cache, tile, gridfunction, location, padding, facets, maxdata, wprojplanes)
266 def setvp(self, dovp=True, usedefaultvp=True, vptable='', dosquint=True, parangleinc=[ ], skyposthreshold=[ ], pblimit=float(1.0e-2)):
267 """Set the voltage pattern model (and hence, the primary beam) used
268 for a Telecope. There are currently two ways to set the voltage
269 pattern: by using the extensive list of defaults which the system
270 knows about, or by creating a voltage pattern description with
271 the vpmanager. If you are
272 simulating a telescope which doesn't yet exist, you will need to
273 supply a model voltage pattern using
274 the vpmanager.
276 sm.predict behavior depends critically on the parameters here, and
277 the ftmachine parameter set in sm.setoptions
279 sm.predict will always query the vpmanager for a primary beam/VP pattern.
280 if usedefaultvp==True, it will reset the vpmanager first, so that
281 the PB obtained will be the default for the given telescope name
282 if usedefaultvp==False, it will check whether vptable is set, and if so,
283 load that table into the vpmanager and use the beams therein.
284 if usedefaultvp==False and vptable is not set, it will use whatever is
285 already set in the vpmanager (see example below for overriding a
286 default telescope beam).
288 What sm.predict does with the obtained PB depends on the ftmachine and
289 dovp parameters:
291 if ftmachine=="mosaic":
292 - a message "Performing Mosaic Gridding" indicates that one is using
293 uv domain convolution for simulating from images.
294 - if the primary beam returned by the vpmanager is ALMA, ACA, or OVRO,
295 heterogeneous gridding will be invoked, and the dish diameter set
296 in sm.setconfig, or already in the antenna subtable, will be used
297 to convolve sky model images.
298 for ALMA or ACA, dish diameter =12m will use a 10.7m Airy pattern,
299 and dish diameter =7m will use a 6.25m Airy pattern.
300 see help sm.setoptions for an example.
301 - otherwise the PB returned by the vpmanager will be used.
302 - heterogeneous simulation only works at present from a sky model
303 image, NOT from sky model components. If you want to simulate a
304 heterogeneous array, please add components to an image using
305 ia.modify, and don't specify a component list in sm.predict.
306 Homogeneous array simulation from component lists works fine.
307 - IF dovp=True, the primary beam returned by the vpmanager will
308 be used to convolve sky model components. This is not automatically
309 invoked by ftmachine="mosaic", but needs to be set explicitly with
310 sm.setvp() if you are simulating from components in addition to or
311 instead of sky model images.
313 if ftmachine=="ft" (the default):
314 - a message "Synthesis Gridding" indicates that if requested with
315 dovp==True, image domain PB convolution will be used.
316 - if dovp==True, the primary beam returned by the vpmanager will be
317 used to convolve sky model components and images.
320 """
321 return self._swigobj.setvp(dovp, usedefaultvp, vptable, dosquint, parangleinc, skyposthreshold, pblimit)
323 def corrupt(self):
324 """Add errors specified by the set* functions (such as noise, gains,
325 polarization leakage, bandpass, etc) to the visibility data. The
326 errors are applied to the DATA and CORRECTED_DATA columns.
328 Note that corrupt handles only
329 visibility-plane effects, not image-plane effects such as pointing
330 errors and voltage patterns, which get applied in predict. Note, the
331 function applies errors to both cross- and auto-correlation data; The
332 auto-correlation data are corrupted properly only for the thermalnoise
333 set by setnoise.
335 """
336 return self._swigobj.corrupt()
338 def reset(self):
339 """Reset the visibility corruption terms: this means that corrupt
340 introduces no errors.
342 """
343 return self._swigobj.reset()
345 def setbandpass(self, mode='calculate', table='', interval=[ ], amplitude=[ float(0.0) ]):
346 """Set the level of bandpass errors. The error distributions are normal, mean
347 zero, with the variances as specified. (Not yet implemented).
349 """
350 return self._swigobj.setbandpass(mode, table, interval, amplitude)
352 def setapply(self, table='', type='', t=float(0.0), field=[ ], interp='linear', calwt=False, spwmap=[ int(-1) ], opacity=float(0.0)):
353 """Arrange for corruption by existing cal tables, in a manner
354 exactly analogous to calibrater.setapply.
356 """
357 return self._swigobj.setapply(table, type, t, field, interp, calwt, spwmap, opacity)
359 def setgain(self, mode='fbm', table='', interval=[ ], amplitude=[ float(0.01) ]):
360 """Set the level of gain errors. Gain drift is implemented as
361 fractional brownian motion with rms amplitude as specified.
362 Interval is not currently used.
365 """
366 return self._swigobj.setgain(mode, table, interval, amplitude)
368 def settrop(self, mode='screen', table='', pwv=float(3.0), deltapwv=float(0.15), beta=float(1.1), windspeed=float(7.), simint=float(-1.)):
369 """Set up for corruption by the atmosphere - attenuation and increase in
370 noise.
372 """
373 return self._swigobj.settrop(mode, table, pwv, deltapwv, beta, windspeed, simint)
375 def setpointingerror(self, epjtablename='', applypointingoffsets=False, dopbcorrection=False):
376 """Set the pointing error from a calpointing table
378 """
379 return self._swigobj.setpointingerror(epjtablename, applypointingoffsets, dopbcorrection)
381 def setleakage(self, mode='constant', table='', amplitude=[ float(0.01) ], offset=[ float(0.) ]):
382 """Set the level of polarization leakage between feeds.
383 Currently, no time dependence is available.
385 """
386 return self._swigobj.setleakage(mode, table, amplitude, offset)
388 def oldsetnoise(self, mode='calculate', table='', simplenoise=[ ], antefficiency=float(0.8), correfficiency=float(0.85), spillefficiency=float(0.85), tau=float(0.1), trx=float(50), tatmos=float(230.0), tcmb=float(2.7)):
389 """Set various system parameters from which the thermal (ie, random
390 additive) noise level will be calculated.
392 For mode=simplenoise, one specifies the standard deviation for the
393 noise to be added to real and imaginary parts of the visibility.
395 For mode=calculate, the noise will vary with dish diameter,
396 antenna efficiency, system temperature, opacity, sky temperature,
397 etc. The noise will increase with the airmass if tau is greater
398 than zero. The noise is calculated according to the Brown
399 Equation (ie, R.L. Brown's calculation of MMA sensitivity,
400 3Oct95):
402 ``dS = 4*sqrt(2) *( T_rx*exp(-tau_atm) +
403 T_atm*( exp(tau_atm) - epsilon_l + T_cmb) )
404 *epsilon_q *epsilon_a *pi *D^2 *sqrt(dnu*dt)``
406 """
407 return self._swigobj.oldsetnoise(mode, table, simplenoise, antefficiency, correfficiency, spillefficiency, tau, trx, tatmos, tcmb)
409 def setnoise(self, mode='simplenoise', table='', simplenoise=[ ], pground=[ ], relhum=float(20.0), altitude=[ ], waterheight=[ ], pwv=[ ], tatmos=float(250.0), tau=float(0.1), antefficiency=float(0.8), spillefficiency=float(0.85), correfficiency=float(0.88), trx=float(50), tground=float(270.0), tcmb=float(2.73), OTF=True, senscoeff=float(0.), rxtype=int(0)):
410 """Set various system parameters from which the thermal (ie, random
411 additive) noise level will be calculated.
413 For mode=simplenoise, one specifies the standard deviation "sigma"
414 for the noise to be added to real and imaginary parts of the visibility.
415 The noise in amplitude per visibility is approximately "sigma" although
416 it is not Gaussian (see Thompson, Moran, and Swenson fig. 6.9)
417 and the point source noise in a Stokes I image will approximately be
418 sigma/sqrt(n_pol * n_baselines * n_integrations * n_chan),
419 where n_pol are the number of polarizations in the MS (typically 2),
420 and n_integrations are the number of correlator integration times
421 in the MS (~ track time / int. time)
423 For mode=tsys-atm or tsys-manual, the noise will vary with dish
424 diameter, antenna efficiency, system temperature, opacity, sky
425 temperature, etc. The noise will increase with the airmass if tau
426 is greater than zero. The noise is calculated according to the
427 Brown Equation (ie, R.L. Brown's calculation of MMA sensitivity,
428 3Oct95):
430 ``dS = 4*sqrt(2) *( T_rx*exp(-tau_atm) +
431 T_atm*( exp(tau_atm) - epsilon_l + T_cmb) )
432 *epsilon_q *epsilon_a *pi *D^2 *sqrt(dnu*dt)``
434 For mode=tsys-atm, the sky brightness temperature is calculated
435 using an atmospheric model created for the user-input PWV. For
436 mode=tsys-manual, the user specifies the sky brightness temperature
437 manually.
439 """
440 return self._swigobj.setnoise(mode, table, simplenoise, pground, relhum, altitude, waterheight, pwv, tatmos, tau, antefficiency, spillefficiency, correfficiency, trx, tground, tcmb, OTF, senscoeff, rxtype)
442 def setpa(self, mode='calculate', table='', interval=[ ]):
443 """Corrupt phase by the parallactic angle
445 """
446 return self._swigobj.setpa(mode, table, interval)
448 def setseed(self, seed=int(185349251)):
449 """
450 """
451 return self._swigobj.setseed(seed)