Line data Source code
1 : //# VisibilityIterator.h: Step through the MeasurementEquation by visibility
2 : //# Copyright (C) 1996,1997,1998,1999,2000,2001,2002,2003
3 : //# Associated Universities, Inc. Washington DC, USA.
4 : //#
5 : //# This library is free software; you can redistribute it and/or modify it
6 : //# under the terms of the GNU Library General Public License as published by
7 : //# the Free Software Foundation; either version 2 of the License, or (at your
8 : //# option) any later version.
9 : //#
10 : //# This library is distributed in the hope that it will be useful, but WITHOUT
11 : //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 : //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 : //# License for more details.
14 : //#
15 : //# You should have received a copy of the GNU Library General Public License
16 : //# along with this library; if not, write to the Free Software Foundation,
17 : //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 : //#
19 : //# Correspondence concerning AIPS++ should be addressed as follows:
20 : //# Internet email: aips2-request@nrao.edu.
21 : //# Postal address: AIPS++ Project Office
22 : //# National Radio Astronomy Observatory
23 : //# 520 Edgemont Road
24 : //# Charlottesville, VA 22903-2475 USA
25 : //#
26 : //# $Id: VisibilityIterator.h,v 19.14 2006/02/28 04:48:58 mvoronko Exp $
27 :
28 : #ifndef MSVIS_VISIBILITYITERATOR2_H
29 : #define MSVIS_VISIBILITYITERATOR2_H
30 :
31 : #include <memory>
32 :
33 : #include <casacore/casa/aips.h>
34 :
35 : #include <casacore/ms/MeasurementSets/MSIter.h>
36 : #include <casacore/ms/MeasurementSets/MeasurementSet.h>
37 : #include <msvis/MSVis/VisBuffer2.h>
38 : #include <msvis/MSVis/VisBufferComponents2.h>
39 : #include <msvis/MSVis/ViiLayerFactory.h>
40 :
41 : #include <map>
42 : #include <set>
43 : #include <utility>
44 : #include <vector>
45 :
46 : namespace casacore{
47 :
48 : class MDirection;
49 : class MSDerivedValues;
50 : class MSIter;
51 : class RecordInterface;
52 : class MSAntennaColumns;
53 : class MSDataDescColumns;
54 : class MSFeedColumns;
55 : class MSFieldColumns;
56 : class MSFlagCmdColumns;
57 : class MSHistoryColumns;
58 : class MSObservationColumns;
59 : class MSPointingColumns;
60 : class MSPolarizationColumns;
61 : class MSProcessorColumns;
62 : class MSSpWindowColumns;
63 : class MSStateColumns;
64 : class MSDopplerColumns;
65 : class MSFreqOffsetColumns;
66 : class MSSourceColumns;
67 : class MSSysCalColumns;
68 : class MSWeatherColumns;
69 : template <typename T, Int N> class RigidVector;
70 : template <typename T, Int N> class SquareMatrix;
71 : }
72 :
73 : namespace casa { //# NAMESPACE CASA - BEGIN
74 :
75 : //# forward decl
76 :
77 : //class CStokesVector;
78 : class VisBufferType;
79 : class VisBufferOptions;
80 : class VisImagingWeight;
81 :
82 : namespace asyncio {
83 :
84 : class VLAT;
85 :
86 : } // end namespace asyncio
87 :
88 : // Forward declarations outside namespace vi
89 : class MSTransformIteratorFactory;
90 :
91 : namespace vi {
92 :
93 : class FrequencySelection;
94 : class FrequencySelections;
95 : class VisBuffer2;
96 : class VisBufferComponents2;
97 : class VisBufferImpl2;
98 : class ViImplementation2;
99 :
100 : class SubtableColumns {
101 :
102 : public:
103 :
104 : // Simple wrapper class to limit access to only the columns associated with the
105 : // current casacore::MS's subtables. This prevents misuse of the main table data columns
106 : // which are provided as part of the casacore::MSColumns object returned by
107 : // MSIter::msColumns.
108 :
109 : SubtableColumns (casacore::CountedPtr <casacore::MSIter> msIter);
110 :
111 : const casacore::MSAntennaColumns& antenna() const;
112 : const casacore::MSDataDescColumns& dataDescription() const;
113 : const casacore::MSFeedColumns& feed() const;
114 : const casacore::MSFieldColumns& field() const;
115 : const casacore::MSFlagCmdColumns& flagCmd() const;
116 : const casacore::MSHistoryColumns& history() const;
117 : const casacore::MSObservationColumns& observation() const;
118 : const casacore::MSPointingColumns& pointing() const;
119 : const casacore::MSPolarizationColumns& polarization() const;
120 : const casacore::MSProcessorColumns& processor() const;
121 : const casacore::MSSpWindowColumns& spectralWindow() const;
122 : const casacore::MSStateColumns& state() const;
123 : const casacore::MSDopplerColumns& doppler() const;
124 : const casacore::MSFreqOffsetColumns& freqOffset() const;
125 : const casacore::MSSourceColumns& source() const;
126 : const casacore::MSSysCalColumns& sysCal() const;
127 : const casacore::MSWeatherColumns& weather() const;
128 :
129 : private:
130 :
131 : casacore::CountedPtr <casacore::MSIter> msIter_p;
132 : };
133 :
134 : ///////////////////////////////////////////////////////////////////
135 : //
136 : // Subchunk class
137 : //
138 : // Provides the ordered pair identifying the current subchunk. The first
139 : // component is the chunk (goes from 0 to nChunks-1 during the outer loop
140 : // iteration). The second component is the subchunk number which is
141 : // zero after VisibilityIterator::origin is called and is increment
142 : // until ROVI::more returns false.
143 :
144 : class Subchunk : public std::pair<casacore::Int, casacore::Int>{
145 :
146 : public:
147 :
148 : // First component is Chunk and second is Subchunk
149 :
150 59638 : Subchunk () { resetToOrigin ();}
151 0 : Subchunk (casacore::Int a , casacore::Int b) : std::pair<casacore::Int,casacore::Int> (a,b) {}
152 :
153 : casacore::Bool operator== (const Subchunk & other){
154 : return first == other.first && second == other.second;
155 : }
156 :
157 : casacore::Bool operator< (const Subchunk & other){
158 : return first < other.first ||
159 : (first == other.first && second < other.second);
160 : }
161 :
162 : casacore::Bool atOrigin () const { return * this == Subchunk ();}
163 : casacore::Int chunk () const { return first;}
164 2869843 : void incrementSubChunk () { second ++;}
165 257350 : void incrementChunk () { first ++; second = 0; }
166 :
167 276384 : void resetSubChunk () { second = 0;} // position to start of chunk
168 :
169 77990 : void resetToOrigin () { first = 0; second = 0; }
170 : // Make a subchunk pair that is positioned to the first subchunk of the
171 : // first chunk (i.e., 0,0)
172 :
173 163920 : casacore::Int subchunk () const { return second;}
174 : casacore::String toString () const;
175 :
176 : static Subchunk noMoreData ();
177 :
178 : private:
179 :
180 : };
181 :
182 :
183 :
184 : ///////////////////////////////////////////////////////////
185 : //
186 : // Code to provide interface to weight function
187 : //
188 : // WeightScaling is essentially the interface to the function
189 : // used for weight scaling while WeightScalingImpl is the class
190 : // to actually use to create WeightScaling functors. The use of
191 : // a templated implementation allows the wrapping of both functors
192 : // and functions while the base class allows polymorphic storage.
193 :
194 : class WeightScaling {
195 : public:
196 :
197 202 : virtual ~WeightScaling () {}
198 0 : casacore::Float operator() (casacore::Float x) { return apply (x);}
199 :
200 : static casacore::CountedPtr<WeightScaling> generateUnityWeightScaling ();
201 : static casacore::CountedPtr<WeightScaling> generateIdentityWeightScaling ();
202 : static casacore::CountedPtr<WeightScaling> generateSquareWeightScaling ();
203 :
204 : protected:
205 :
206 : virtual casacore::Float apply (casacore::Float) = 0;
207 : static casacore::Float unity (casacore::Float);
208 : static casacore::Float identity (casacore::Float x);
209 : static casacore::Float square (casacore::Float x);
210 : };
211 :
212 : template<typename F>
213 : class WeightScalingImpl : public WeightScaling {
214 : public:
215 :
216 : // Provide either a unary function, casacore::Float (*) (casacore::Float), or
217 : // a functor class having a casacore::Float operator() (casacore::Float) method.
218 :
219 202 : WeightScalingImpl (F f) : function_p (f) {}
220 :
221 0 : casacore::Float apply (casacore::Float f) { return function_p (f);}
222 :
223 : private:
224 :
225 : F function_p;
226 : };
227 :
228 :
229 : template<typename F>
230 202 : casacore::CountedPtr <WeightScaling> generateWeightScaling (F f) { return new WeightScalingImpl<F> (f);}
231 :
232 : class SortColumns {
233 : public:
234 :
235 : explicit SortColumns (const casacore::Block<casacore::Int> & columnIds = casacore::Block<casacore::Int> (), casacore::Bool addDefaultColumns = true);
236 :
237 : explicit SortColumns (casacore::Bool usingDefaultSortingFunctions);
238 :
239 : // Constructor from a list of (column Ids, comparison function)
240 : // The column Ids are actually MSMainEnums enums.
241 : explicit SortColumns (const std::vector<std::pair<casacore::MS::PredefinedColumns, std::shared_ptr<casacore::BaseCompare>>> sortingDefinition);
242 :
243 : // Constructor from a list of (column names, comparison function)
244 : // The column names could in principle be any column name which must
245 : // of course exist in the MS.
246 : explicit SortColumns (const std::vector<std::pair<casacore::String, std::shared_ptr<casacore::BaseCompare>>> sortingDefinition);
247 :
248 : // Add a sorting column to the existing definitions.
249 : // It will be added at the end, i. e., it will be "running" faster
250 : // If sortingFunction = nullptr then a unique sorting function
251 : // for the type of the column will be used (ObjCompare<T>)
252 : void addSortingColumn(casacore::MS::PredefinedColumns colId,
253 : std::shared_ptr<casacore::BaseCompare> sortingFunction = nullptr);
254 :
255 : // Add a sorting column to the existing definitions.
256 : // It will be added at the end, i. e., it will be "running" faster
257 : // If sortingFunction = nullptr then a unique sorting function
258 : // for the type of the column will be used (ObjCompare<T>)
259 : void addSortingColumn(casacore::String colName,
260 : std::shared_ptr<casacore::BaseCompare> sortingFunction = nullptr);
261 :
262 : bool usingDefaultSortingFunctions () const;
263 :
264 : casacore::Bool shouldAddDefaultColumns () const;
265 :
266 : const casacore::Block<casacore::Int> & getColumnIds () const;
267 :
268 : // Get the sorting definitions, including the comparison functions
269 : const std::vector<std::pair<casacore::String, std::shared_ptr<casacore::BaseCompare>>> & sortingDefinition() const;
270 :
271 : private:
272 :
273 : casacore::Bool addDefaultColumns_p;
274 : casacore::Block<casacore::Int> columnIds_p;
275 : std::vector<std::pair<casacore::String, std::shared_ptr<casacore::BaseCompare>>> sortingDefinition_p;
276 : bool usingDefaultSortingFunctions_p;
277 : };
278 :
279 : class VisibilityIterator2;
280 :
281 : //////////////////////////////////////////////////////////////////////
282 : //
283 : // Class ViFactory
284 : //
285 : // The ViFactory is a class that can be used to initialize the implementation of
286 : // a VisibilityIterator2. It is passed into VI2's constructor where it creates
287 : // the needed ViImplementation object used by the VI2. The first example of this
288 : // factory is the AveragingVi2Factory which is used to create a VI2 which will
289 : // return time-averaged data.
290 :
291 : class ViFactory {
292 :
293 : public:
294 :
295 277 : virtual ~ViFactory () {}
296 :
297 : protected:
298 :
299 : friend class VisibilityIterator2;
300 :
301 : virtual ViImplementation2 * createVi () const = 0;
302 : };
303 :
304 : // <summary>
305 : // VisibilityIterator2 iterates through one or more readonly MeasurementSets
306 : // </summary>
307 : // <use visibility=export>
308 : // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
309 : // </reviewed>
310 : // <prerequisite>
311 : // <li> <linkto class="MSIter">MSIter</linkto>
312 : // <li> <linkto class="casacore::MeasurementSet">casacore::MeasurementSet</linkto>
313 : // <li> <linkto class="VisSet">VisSet</linkto>
314 : // <li> <linkto class="PrefetchColumns">PrefetchColumns</linkto>
315 : // </prerequisite>
316 : //
317 : // <etymology>
318 : // The VisibilityIterator2 is a readonly iterator returning visibilities
319 : // </etymology>
320 : //
321 : // <synopsis>
322 : // VisibilityIterator2 provides iteration with various sort orders
323 : // for one or more MSs. It has member functions to retrieve the fields
324 : // commonly needed in synthesis calibration and imaging.
325 : //
326 : // One should use <linkto class="VisBuffer">VisBuffer</linkto>
327 : // to access chunks of data.
328 : //
329 : // VisibilityIterator2s can be either synchronous or asynchronous, depending
330 : // on the constructor used to create them as well as the current value of
331 : // a CASARC file setting. A synchronous instance is works the same as
332 : // this class ever worked; an asynchronous instance uses a second thread
333 : // (the Visibility Lookahead Thread or VLAT) to fill the VisBuffers in
334 : // advance of their use by the original thread.
335 : //
336 : // To create an asynchronous instance of ROVI you must use one of the two
337 : // constructors which have a pointer to a PrefetchColumns object as the
338 : // first argument. This object specifies which VisBuffer components should be
339 : // prefetched by the VLAT; accessing components not specified in the PrefetchColumns
340 : // object will result in an exception containing an error message indicating
341 : // that the VisBuffer does not contain the requested column. In addition
342 : // to using the appropriate constructor, the CASARC file setting
343 : // VisibilityIterator2.async.enabled can be used to turn asynchronous I/O
344 : // off globally; if it's globally enabled then it is still possible for the
345 : // user to choose to enable/disable it on a VI by VI basis.
346 : //
347 : // +-------------------+
348 : // | |
349 : // | *** Nota Bene *** |
350 : // | |
351 : // +-------------------+
352 : //
353 : // Because of the multithreaded nature of asynchronous I/O, the user
354 : // needs to be a bit more careful in the use of the VI and it's attached VisBuffer.
355 : // casacore::Data access operations need to be directed to the VisBuffer. Additionally
356 : // the user must not attempt to access the data using a separate VI since
357 : // the underlying casacore objects are not threadsafe and bizarre errors
358 : // will likely occur.
359 : //
360 : // CASARC Settings
361 : // ===============
362 : //
363 : // casacore::Normal settings
364 : // ---------------
365 : //
366 : // VisibilityIterator2.async.enabled - Boolean value that enables or disables
367 : // async I/O. The default value is currently false (i.e., disabled).
368 : // VisibilityIterator2.async.nBuffers - The number of lookahead buffers. This
369 : // defaults to 2.
370 : //
371 : //
372 : // Debug settings
373 : // --------------
374 : //
375 : // VisibilityIterator2.async.doStats: true
376 : // VisibilityIterator2.async.debug.logFile: stderr
377 : // VisibilityIterator2.async.debug.logLevel: 1
378 : //
379 :
380 : // </synopsis>
381 : //
382 : // <example>
383 : // <code>
384 : // //
385 : // </code>
386 : // </example>
387 : //
388 : // <motivation>
389 : // For imaging and calibration you need to access an casacore::MS in some consistent
390 : // order (by field, spectralwindow, time interval etc.). This class provides
391 : // that access.
392 : // </motivation>
393 : //
394 : // <thrown>
395 : // <li>
396 : // <li>
397 : // </thrown>
398 : //
399 : // <todo asof="1997/05/30">
400 : // <li> cleanup the currently dual interface for visibilities and flags
401 : // <li> sort out what to do with weights when interpolating
402 : // </todo>
403 : class VisibilityIterator2
404 : {
405 : // These classes are members of the VI/VB framework and need extra
406 : // access to the non-public methods of this class. Any additions of
407 : // classes not in this framework is strongly discouraged.
408 : //
409 : // Friends of the class should limit themselves to accessing the protected
410 : // area of this class so that items in the private area can remeain de
411 : // facto private.
412 :
413 : //friend class VisibilityIteratorImpl2;
414 : // friend VisBuffer2 * VisBuffer2::factory (VisibilityIterator2 * vi, VisBufferType t,
415 : // VisBufferOptions options);
416 : friend class VisBuffer2Adapter;
417 : //friend class VisBufferImpl2;
418 : //friend class VisBufferState;
419 : friend class asyncio::VLAT; // allow VI lookahead thread class to access protected
420 : // functions VLAT should not access private parts,
421 : // especially variables
422 : friend class casa::MSTransformIteratorFactory;
423 :
424 : public:
425 :
426 : VisibilityIterator2( const VisibilityIterator2& ) = delete;
427 : VisibilityIterator2& operator=( const VisibilityIterator2& ) = delete;
428 : class Factory { // Interface for implementation creation factory
429 :
430 : public:
431 :
432 : virtual ~Factory () {}
433 :
434 : virtual ViImplementation2 *
435 : operator() (const VisBufferComponents2 * /*prefetchColumns*/,
436 : const casacore::Block<casacore::MeasurementSet>& /*mss*/,
437 : const casacore::Block<casacore::Int>& /*sortColumns*/,
438 : const casacore::Bool /*addDefaultSortCols*/,
439 : casacore::Double /*timeInterval*/) const
440 : {
441 : return NULL;
442 : }
443 : };
444 :
445 : typedef enum casacore::MSIter::PolFrame PolFrame;
446 :
447 : typedef enum DataColumn {
448 : Observed=0, // Observed data
449 : Model, // Model data
450 : Corrected // Corrected data
451 : } DataColumn;
452 :
453 : // Construct from an casacore::MS and a casacore::Block of casacore::MS column enums specifying the
454 : // iteration order. These can be specified as casacore::MS::ANTENNA1, casacore::MS::ARRAY_ID,
455 : // etc.; they are defined in MSMainEnums.h.
456 : // If no order is specified, it uses the default sort
457 : // order of MSIter, which is not necessarily the raw order of ms!
458 : // The default ordering is ARRAY_ID, FIELD_ID, DATA_DESC_ID,
459 : // and TIME, but check MSIter.h to be sure.
460 : // These columns will be added first if they are not specified.
461 : //
462 : // An optional timeInterval (in seconds) can be given to iterate through
463 : // chunks of time. The default interval of 0 groups all times together.
464 : // Every 'chunk' of data contains all data within a certain time interval and
465 : // with identical values of the other iteration columns (e.g. DATA_DESC_ID
466 : // and FIELD_ID).
467 : //
468 : // A set of prefetch columns can be specified for asynchronous I/O use. These
469 : // roughly correspond to the fields accessible from the VisBuffer. Specifying
470 : // prefetch columns will cause an asynchronous VI to be created if asynchronous
471 : // I/O is globally enabled. If the user wishes to have application-specific
472 : // enable/disable of asynchronous I/O then they must implement logic that
473 : // either either provides prefetch columns (enables) or a null pointer (disables).
474 :
475 : VisibilityIterator2 (const casacore::MeasurementSet& ms,
476 : const SortColumns & sortColumns = SortColumns (),
477 : casacore::Bool isWritable = false,
478 : const VisBufferComponents2 * prefetchColumns = 0,
479 : casacore::Double timeInterval = 0);
480 :
481 : VisibilityIterator2 (const casacore::Block<const casacore::MeasurementSet *>& mss,
482 : const SortColumns & sortColumns = SortColumns (),
483 : casacore::Bool isWritable = false,
484 : const VisBufferComponents2 * prefetchColumns = 0,
485 : casacore::Double timeInterval = 0);
486 :
487 : VisibilityIterator2 (const ViFactory & factory);
488 :
489 : // Creates an iterator from a stack of VI factories
490 : // <thrown>
491 : // <li> AipsError if the last factory is NULL
492 : // </thrown>
493 : VisibilityIterator2 (const casacore::Vector<ViiLayerFactory*> & factories);
494 :
495 : // Destructor
496 :
497 : virtual ~VisibilityIterator2();
498 :
499 : // Report the the ViImplementation type
500 : casacore::String ViiType() const;
501 :
502 : ///////////////////////////////////////////////////////////////////
503 : //
504 : // BEGIN Experimental Section
505 : //
506 :
507 : static VisibilityIterator2 * copyingViFactory (const casacore::MeasurementSet & srcMs,
508 : casacore::MeasurementSet & dstMs);
509 :
510 : //
511 : // END Experimental Section
512 : //
513 : ///////////////////////////////////////////////////////////////////
514 :
515 : ///////////////////////////////////////////////////////////////////
516 : //
517 : // Iteration movement methods
518 : //
519 : // The typical use case for VisibilityIteration looks like
520 : //
521 : // for (vi.originChunks(); vi.moreChunks(); nextChunk()){
522 : // for (vi.origin (); vi.more(); vi++){
523 : // }
524 : // }
525 : //
526 : // Record result;
527 : // vi.result(result);
528 : // // return or do something with the result record
529 : //
530 : // The outer loop is the "chunk" loop and the inner loop is the "subchunk"
531 : // loop. A chunk contains all the rows having identical values for the
532 : // sort columns values except time; time can have an optional interval
533 : // value specified either in the constructor or via the setInterval
534 : // method. If an interval is specified the set of rows will all have
535 : // timestamps that are within that interval of the first row in the
536 : // chunk; if no interval is specified then the chunk will contain only
537 : // rows having the identical timestamp. If multiple MSs are specified
538 : // in the constructor then changing from one casacore::MS to the next will occur
539 : // on a chunk boundary (i.e., a chunk will never contain data from more
540 : // than one casacore::MS).
541 : //
542 : // A subchunk typically contains all the rows in the chunk having identical
543 : // timestamps. The only exception is when the user calls setRowBlocking(N)
544 : // with a positive value. In this case, the subchunk *may* contain up to
545 : // N rows; however, this is only a suggestion to the VI. If there are
546 : // less than N rows remaining in the chunk then fewer than N rows will be
547 : // contained in the chunk. The number of rows in a subchunk will also be
548 : // less than N if a larger set of rows would create an inconsistently
549 : // shaped visibility cube; this could happen if the number of channels
550 : // changes from one timestamp to another or the framed frequency
551 : // selection selects a different number of channels from one timestamp to
552 : // the next.
553 : //
554 : // origin () - positions VI to the start of the current chunk
555 : // operator++ - advance VI to next subchunk if it exists
556 : // more - returns true if the VI is pointing to a valid subchunk
557 : //
558 : // originChunks - Move to the first chunk of data.
559 : // operator++ - advance VI to the next chunk if it exists
560 : // moreChunks - returns true if the VI is pointing to a valid chunk.
561 : //
562 : // result - populate result record after iterating through chunks
563 :
564 : void origin(); // Reset to start of the chunk
565 : void next ();
566 : casacore::Bool more() const;
567 :
568 : void originChunks();
569 : void nextChunk();
570 : casacore::Bool moreChunks() const;
571 :
572 : virtual void result(casacore::Record& res) const;
573 :
574 : // Report Name of slowest column that changes at end of current chunk iteration
575 : virtual casacore::String keyChange() const;
576 :
577 : // Returns the pair (chunk,subchunk) for the current position of the VI. Only
578 : // valid after origin has been called.
579 :
580 : Subchunk getSubchunkId () const;
581 :
582 : ///////////////////////////////////////////////////////////////////
583 : //
584 : // Iterator operation methods
585 : //
586 : // These methods alter the way that the VI operates. After applying any of these
587 : // (except slurp which should be called after originChunks) originChunks must be
588 : // called before the VI is advanced again; otherwise an exception will be thrown
589 : // (changing these values in the middle of a sweep can lead to unexpected behavior).
590 : //
591 : // Selecting ranges of frequencies involves initializing a
592 : // FrequencySelection(s) object and providing it to the VI. Once
593 : // properly applied the VI will only return data for the selected
594 : // frequencies. No interpolation is performed; the data returned is
595 : // simply the channels that currently map to the selected frequencies for
596 : // the specified frame of reference.
597 :
598 : void setFrequencySelection (const FrequencySelection &); // for single MS
599 : void setFrequencySelection (const FrequencySelections &); // when using multiple MSs
600 :
601 : // RowBlocking is a suggestion to the iterator that it try to use subchunks
602 : // having the suggested number of rows. The VI will attempt to honor the
603 : // suggestion except when there are not enough rows remaining in the chunk
604 : // or when putting the suggested number of rows in the subchunk cannot
605 : // be contained in a cube (e.g., there are sets of row with different
606 : // numbers of frequencies, etc.). The latter case will mainly occur
607 : // when the row visibility shape changes from one row to the next.
608 :
609 : casacore::Int getRowBlocking() const;
610 : void setRowBlocking(casacore::rownr_t nRows=0);
611 :
612 : // In this context the interval determines what rows will be contained
613 : // in a chunk. A chunk is all the rows in an casacore::MS that have the same values
614 : // in the sort columns, except for time; all rows that otherwise have the
615 : // same values for the sort columns will be in the chunk if they are no
616 : // later than "interval" seconds after the first row in the chunk.
617 : //
618 : // *** This value is unrelated to the interval field of the casacore::MS main table.
619 :
620 : casacore::Double getInterval() const;
621 : void setInterval(casacore::Double timeInterval);
622 :
623 : // Call to use the slurp i/o method for all scalar columns. This
624 : // will set the casacore::BucketCache cache size to the full column length
625 : // and cause the full column to be cached in memory, if
626 : // any value of the column is used. In case of out-of-memory,
627 : // it will automatically fall-back on the smaller cache size.
628 : // Slurping the column is to be considered as a work-around for the
629 : // casacore::Table i/o code, which uses casacore::BucketCache and performs extremely bad
630 : // for random access. Slurping is useful when iterating non-sequentially
631 : // an casacore::MS or parts of an casacore::MS, it is not tested with multiple MSs.
632 :
633 : void slurp() const;
634 :
635 : ///////////////////////////////////////////////////////////////////
636 : //
637 : // Other methods
638 : //
639 :
640 : // Returns true if this is an asynchronous VI
641 :
642 : casacore::Bool isAsynchronous () const;
643 :
644 : // Returns true if async I/O is globally enabled.
645 :
646 : static casacore::Bool isAsynchronousIoEnabled();
647 :
648 : // Returns true if this VI is writable (always false for ROVI and
649 : // true for VI; see VisibilityIterator class).
650 :
651 : casacore::Bool isWritable () const;
652 :
653 : // Returns the columns that the VisibilityIterator2 is sorting by. These are
654 : // defined in MSMainEnums.h. These can be specified as casacore::MS::ANTENNA1,
655 : // casacore::MS::ARRAY_ID, etc.
656 :
657 : const SortColumns & getSortColumns() const;
658 :
659 : // Returns true if the specified column exists.
660 :
661 : bool existsColumn (VisBufferComponent2 id) const;
662 :
663 : // Returns the VisBuffer permanently attached to this VisibilityIterator.
664 :
665 : VisBuffer2 * getVisBuffer ();
666 :
667 : // Manages the weight function that can be used to process the weights
668 : // produced by the "scaled" variants of the weight accessors. Use
669 : // generateWeightscaling to create a WeightScaling object. This allow you
670 : // to use either a function (FLoat (casacore::Float)) or a functor (object having
671 : // method casacore::Float operator () (casacore::Float)).
672 : //
673 : // To revert to having no scaling function, call setWeightScaling with
674 : // 0 as the argument. Any call to setWeightScaling needs to be followed
675 : // by an originChunks call before any further data access is performed
676 : // using the VI.
677 : //
678 : // The method hasWeightScaling will return false if either no weightScaling
679 : // object has installed or setWeightScaling (0) was called. There is not
680 : // way for VI to know if the user has passed in the identity function;
681 : // doing so will still cause hasWeightScaling to return true.
682 :
683 : virtual void setWeightScaling (casacore::CountedPtr<WeightScaling> weightscaling);
684 : virtual casacore::Bool hasWeightScaling () const;
685 :
686 : // Return number of spws, polids, ddids for the current MS
687 :
688 : casacore::Int nSpectralWindows () const;
689 : casacore::Int nPolarizationIds () const; // number of different polarization configurations
690 : // (i.e., length of polarization subtable)
691 : casacore::Int nDataDescriptionIds () const;
692 :
693 : // Determine whether WEIGHT_SPECTRUM exists.
694 :
695 : casacore::Bool weightSpectrumExists() const;
696 :
697 : // Determine whether WEIGHT_SPECTRUM exists.
698 :
699 : casacore::Bool sigmaSpectrumExists() const;
700 :
701 : //reference to actual ms in interator
702 :
703 : const casacore::MeasurementSet& ms() const /*__attribute__((deprecated))*/;
704 :
705 : const vi::SubtableColumns & subtableColumns () const /*__attribute__((deprecated))*/;
706 :
707 5629 : static casacore::String getAipsRcBase () { return "VisibilityIterator2";}
708 :
709 : // The reporting frame of reference is the default frame of reference to be
710 : // used when the user requests the frequencies of the current data selection
711 : // in a VisBuffer. This is useful when the user wishes to select the data
712 : // using one frame of reference but use the frequencies from another frame
713 : // of reference. If not specified then the default will be to use the
714 : // frame of reference used to select the data.
715 : //
716 : // These *do not* change the selection in any way.
717 :
718 : casacore::Int getReportingFrameOfReference () const;
719 : void setReportingFrameOfReference (casacore::Int);
720 :
721 : // Return the numbers of rows in the current chunk
722 :
723 : casacore::rownr_t nRowsInChunk() const;
724 :
725 : // Assign a VisImagingWeight object to this iterator. This object is used
726 : // to generate imaging weights.
727 :
728 : void useImagingWeight(const VisImagingWeight& imWgt);
729 : const VisImagingWeight & getImagingWeightGenerator () const;
730 :
731 : // Write/modify the flags in the data.
732 : // This will flag all channels in the original data that contributed to
733 : // the output channel in the case of channel averaging.
734 : // All polarizations have the same flag value.
735 :
736 : // Write/modify the flags in the data.
737 : // This writes the flags as found in the casacore::MS, casacore::Cube(npol,nchan,nrow),
738 : // where nrow is the number of rows in the current iteration (given by
739 : // nRow()).
740 :
741 : virtual void writeFlag(const casacore::Cube<casacore::Bool>& flag);
742 :
743 : // Write/modify the flag row column; dimension casacore::Vector(nrow)
744 :
745 : virtual void writeFlagRow(const casacore::Vector<casacore::Bool>& rowflags);
746 :
747 : void writeFlagCategory(const casacore::Array<casacore::Bool>& fc);
748 :
749 : // Write/modify the visibilities.
750 : // This is possibly only for a 'reference' casacore::MS which has a new DATA column.
751 : // The first axis of the matrix should equal the selected number of channels
752 : // in the original MS.
753 : // If the casacore::MS does not contain all polarizations, only the parallel
754 : // hand polarizations are used.
755 :
756 : // void writeVisCorrected (const casacore::Matrix<CStokesVector>& vis);
757 : // void writeVisModel (const casacore::Matrix<CStokesVector>& vis);
758 : // void writeVisObserved (const casacore::Matrix<CStokesVector>& vis);
759 :
760 : // Write/modify the visibilities
761 : // This writes the data as found in the casacore::MS, casacore::Cube(npol,nchan,nrow).
762 :
763 : void writeVisCorrected (const casacore::Cube <casacore::Complex> & vis);
764 : void writeVisModel (const casacore::Cube <casacore::Complex> & vis);
765 : void writeVisObserved (const casacore::Cube <casacore::Complex> & vis);
766 :
767 : // Write/modify the weights
768 :
769 : void writeWeight(const casacore::Matrix<casacore::Float>& wt);
770 :
771 : // Write/modify the weightMat
772 :
773 : //virtual void writeWeightMat(const casacore::Matrix<casacore::Float>& wtmat);
774 :
775 : // Write/modify the weightSpectrum
776 :
777 : virtual void writeWeightSpectrum(const casacore::Cube<casacore::Float>& wtsp);
778 :
779 :
780 : // Initialize the weightSpectrum
781 : virtual void initWeightSpectrum(const casacore::Cube<casacore::Float>& wtsp);
782 :
783 : // Write/modify the Sigma
784 :
785 : void writeSigma(const casacore::Matrix<casacore::Float>& sig);
786 :
787 : // Write/modify the ncorr x nrow SigmaMat.
788 :
789 : //void writeSigmaMat(const casacore::Matrix<casacore::Float>& sigmat);
790 :
791 : // This puts a model into the descriptor of the current ms in the iterator.
792 : // Set isComponentList to true if the record represents a componentList;
793 : // if false then it is a FTMachine Record that holds the model image.
794 : // Note that the spw and fields selected are going to be associated with this model.
795 : // Setting addToExistingModel to true adds the model to the previous existent model
796 : // in the ms for the spw and fields; setting it to false means any existing
797 : // model will be replaced.
798 :
799 : void writeModel(const casacore::RecordInterface & record,
800 : casacore::Bool isComponentList = true,
801 : casacore::Bool addToExistingModel = false);
802 :
803 : // Requests that the modified VisBuffer2 be written back to the visibility
804 : // at the same spot that it came from. The dirtyComponents feature of
805 : // VisBuffer is used to mark which portions of the VisBuffer actually need
806 : // to be written back out.
807 :
808 : void writeBackChanges (VisBuffer2 *);
809 :
810 : //**********************************************************************
811 : // Methods to access the subtables.
812 : //**********************************************************************
813 :
814 : // Access to antenna subtable
815 : const casacore::MSAntennaColumns& antennaSubtablecols() const;
816 :
817 : // Access to MS dataDescription subtable
818 : const casacore::MSDataDescColumns& dataDescriptionSubtablecols() const;
819 :
820 : // Access to MS feed subtable
821 : const casacore::MSFeedColumns& feedSubtablecols() const;
822 :
823 : // Access to MS field subtable
824 : const casacore::MSFieldColumns& fieldSubtablecols() const;
825 :
826 : // Access to MS flagCmd subtable
827 : const casacore::MSFlagCmdColumns& flagCmdSubtablecols() const;
828 :
829 : // Access to MS history subtable
830 : const casacore::MSHistoryColumns& historySubtablecols() const;
831 :
832 : // Access to MS observation subtable
833 : const casacore::MSObservationColumns& observationSubtablecols() const;
834 :
835 : // Access to MS pointing subtable
836 : const casacore::MSPointingColumns& pointingSubtablecols() const;
837 :
838 : // Access to MS polarization subtable
839 : const casacore::MSPolarizationColumns& polarizationSubtablecols() const;
840 :
841 : // Access to MS processor subtable
842 : const casacore::MSProcessorColumns& processorSubtablecols() const;
843 :
844 : // Access to MS spectralWindow subtable
845 : const casacore::MSSpWindowColumns& spectralWindowSubtablecols() const;
846 :
847 : // Access to MS state subtable
848 : const casacore::MSStateColumns& stateSubtablecols() const;
849 :
850 : // Access to MS doppler subtable
851 : const casacore::MSDopplerColumns& dopplerSubtablecols() const;
852 :
853 : // Access to MS freqOffset subtable
854 : const casacore::MSFreqOffsetColumns& freqOffsetSubtablecols() const;
855 :
856 : // Access to MS source subtable
857 : const casacore::MSSourceColumns& sourceSubtablecols() const;
858 :
859 : // Access to MS sysCal subtable
860 : const casacore::MSSysCalColumns& sysCalSubtablecols() const;
861 :
862 : // Access to MS weather subtable
863 : const casacore::MSWeatherColumns& weatherSubtablecols() const;
864 :
865 :
866 : //**********************************************************************
867 : // Internal methods below this line
868 : //**********************************************************************
869 :
870 : ViImplementation2 * getImpl() const;
871 :
872 : protected:
873 :
874 :
875 : VisibilityIterator2();
876 :
877 : void construct (const VisBufferComponents2 * prefetchColumns,
878 : const casacore::Block<const casacore::MeasurementSet *>& mss,
879 : const SortColumns & sortColumns,
880 : casacore::Double timeInterval,
881 : casacore::Bool writable);
882 :
883 : // advance the iteration
884 :
885 : void originChunks(casacore::Bool forceRewind);
886 :
887 :
888 : private:
889 :
890 : ViImplementation2 * impl_p;
891 : };
892 :
893 : } // end namespace vi
894 :
895 : } //# NAMESPACE CASA - END
896 :
897 : #endif
|
