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