casa::vi::VisibilityIterator2 Class Reference

VisibilityIterator2 iterates through one or more readonly MeasurementSets. More...

#include <VisibilityIterator2.h>

List of all members.

Classes

class  Factory

Public Types

enum  DataColumn {
  Observed,
  Model,
  Corrected
}
typedef enum MSIter::PolFrame PolFrame
typedef enum
casa::vi::VisibilityIterator2::DataColumn 
DataColumn

Public Member Functions

 VisibilityIterator2 (const VisibilityIterator2 &)
VisibilityIterator2operator= (const VisibilityIterator2 &)
 VisibilityIterator2 (const MeasurementSet &ms, const SortColumns &sortColumns=SortColumns(), Bool isWritable=False, const VisBufferComponents2 *prefetchColumns=0, Double timeInterval=0)
 Construct from an MS and a Block of MS column enums specifying the iteration order.
 VisibilityIterator2 (const Block< const MeasurementSet * > &mss, const SortColumns &sortColumns=SortColumns(), Bool isWritable=False, const VisBufferComponents2 *prefetchColumns=0, Double timeInterval=0)
 VisibilityIterator2 (const ViFactory &factory)
 VisibilityIterator2 (const Vector< ViiLayerFactory * > &factories)
virtual ~VisibilityIterator2 ()
 Destructor.
String ViiType () const
 Report the the ViImplementation type.
void origin ()
 END Experimental Section.
void next ()
Bool more () const
void originChunks ()
void nextChunk ()
Bool moreChunks () const
Subchunk getSubchunkId () const
 Returns the pair (chunk,subchunk) for the current position of the VI.
Iterator operation methods
These methods alter the way
that the VI operates After
applying any of 
these (except slurp which should be called after originChunks) originChunks must be called before the VI is advanced again
otherwise an exception will be thrown (changing these values in the middle of a sweep can lead to unexpected behavior).Selecting ranges of frequencies involves initializing a FrequencySelection(s) object and providing it to the VI.Once properly applied the VI will only return data for the selected frequencies.No interpolation is performed
the data returned is simply
the channels that currently
map to the selected
frequencies for the specified
frame of reference *void 
setFrequencySelection (const FrequencySelection &)
void setFrequencySelection (const FrequencySelections &)
Int getRowBlocking () const
 RowBlocking is a suggestion to the iterator that it try to use subchunks having the suggested number of rows.
void setRowBlocking (Int nRows=0)
Double getInterval () const
 In this context the interval determines what rows will be contained in a chunk.
void setInterval (Double timeInterval)
void slurp () const
 Call to use the slurp i/o method for all scalar columns.
Other methods Returns True if
this is an asynchronous VI
*Bool 
isAsynchronous () const
Bool isWritable () const
 Returns True if this VI is writable (always False for ROVI and True for VI; see VisibilityIterator class).
const SortColumnsgetSortColumns () const
 Returns the columns that the VisibilityIterator2 is sorting by.
bool existsColumn (VisBufferComponent2 id) const
 Returns true if the specified column exists.
VisBuffer2getVisBuffer ()
 Returns the VisBuffer permanently attached to this VisibilityIterator.
virtual void setWeightScaling (CountedPtr< WeightScaling > weightscaling)
 Manages the weight function that can be used to process the weights produced by the "scaled" variants of the weight accessors.
virtual Bool hasWeightScaling () const
Int nSpectralWindows () const
 Return number of spws, polids, ddids for the current MS.
Int nPolarizationIds () const
Int nDataDescriptionIds () const
 (i.e., length of polarization subtable)
Bool weightSpectrumExists () const
 Determine whether WEIGHT_SPECTRUM exists.
Bool sigmaSpectrumExists () const
 Determine whether WEIGHT_SPECTRUM exists.
const MeasurementSet & ms () const
 reference to actual ms in interator
const vi::SubtableColumnssubtableColumns () const
Int getReportingFrameOfReference () const
 The reporting frame of reference is the default frame of reference to be used when the user requests the frequencies of the current data selection in a VisBuffer.
void setReportingFrameOfReference (Int)
Int nRowsInChunk () const
 Return the numbers of rows in the current chunk.
void useImagingWeight (const VisImagingWeight &imWgt)
 Assign a VisImagingWeight object to this iterator.
const VisImagingWeightgetImagingWeightGenerator () const
virtual void writeFlag (const Cube< Bool > &flag)
 Write/modify the flags in the data.
virtual void writeFlagRow (const Vector< Bool > &rowflags)
 Write/modify the flag row column; dimension Vector(nrow).
void writeFlagCategory (const Array< Bool > &fc)
void writeVisCorrected (const Cube< Complex > &vis)
 Write/modify the visibilities.
void writeVisModel (const Cube< Complex > &vis)
void writeVisObserved (const Cube< Complex > &vis)
void writeWeight (const Matrix< Float > &wt)
 Write/modify the weights.
virtual void writeWeightSpectrum (const Cube< Float > &wtsp)
 Write/modify the weightMat.
virtual void initWeightSpectrum (const Cube< Float > &wtsp)
 Initialize the weightSpectrum.
void writeSigma (const Matrix< Float > &sig)
 Write/modify the Sigma.
void writeModel (const RecordInterface &rec, Bool iscomponentlist=True, Bool incremental=False)
 Write/modify the ncorr x nrow SigmaMat.
void writeBackChanges (VisBuffer2 *)
 Requests that the modified VisBuffer2 be written back to the visibility at the same spot that it came from.
ViImplementation2getImpl () const

Static Public Member Functions

BEGIN Experimental Section
*static VisibilityIterator2
copyingViFactory (const MeasurementSet &srcMs, MeasurementSet &dstMs)
template<typename KlugeIn , typename KlugeOut >
static KlugeOut KlugeForTesting (KlugeIn)
static Bool isAsynchronousIoEnabled ()
 Returns True if async I/O is globally enabled.
static String getAipsRcBase ()

Protected Member Functions

 VisibilityIterator2 ()
void construct (const VisBufferComponents2 *prefetchColumns, const Block< const MeasurementSet * > &mss, const SortColumns &sortColumns, Double timeInterval, Bool writable)
void originChunks (Bool forceRewind)
 advance the iteration

Private Attributes

ViImplementation2impl_p

Friends

class VisBuffer2Adapter
 These classes are members of the VI/VB framework and need extra access to the non-public methods of this class.
class asyncio::VLAT
 friend class VisBufferImpl2; friend class VisBufferState;
class casa::MSTransformIteratorFactory
 functions VLAT should not access private parts, especially variables

Detailed Description

VisibilityIterator2 iterates through one or more readonly MeasurementSets.

Intended use:

Public interface

Review Status

Date Reviewed:
yyyy/mm/dd

Prerequisite

Etymology

The VisibilityIterator2 is a readonly iterator returning visibilities

Synopsis

VisibilityIterator2 provides iteration with various sort orders for one or more MSs. It has member functions to retrieve the fields commonly needed in synthesis calibration and imaging.

One should use VisBuffer to access chunks of data.

VisibilityIterator2s can be either synchronous or asynchronous, depending on the constructor used to create them as well as the current value of a CASARC file setting. A synchronous instance is works the same as this class ever worked; an asynchronous instance uses a second thread (the Visibility Lookahead Thread or VLAT) to fill the VisBuffers in advance of their use by the original thread.

To create an asynchronous instance of ROVI you must use one of the two constructors which have a pointer to a PrefetchColumns object as the first argument. This object specifies which VisBuffer components should be prefetched by the VLAT; accessing components not specified in the PrefetchColumns object will result in an exception containing an error message indicating that the VisBuffer does not contain the requested column. In addition to using the appropriate constructor, the CASARC file setting VisibilityIterator2.async.enabled can be used to turn asynchronous I/O off globally; if it's globally enabled then it is still possible for the user to choose to enable/disable it on a VI by VI basis.

+-------------------+ | | | *** Nota Bene *** | | | +-------------------+

Because of the multithreaded nature of asynchronous I/O, the user needs to be a bit more careful in the use of the VI and it's attached VisBuffer. Data access operations need to be directed to the VisBuffer. Additionally the user must not attempt to access the data using a separate VI since the underlying casacore objects are not threadsafe and bizarre errors will likely occur.

CASARC Settings ===============

Normal settings ---------------

VisibilityIterator2.async.enabled - Boolean value that enables or disables async I/O. The default value is currently False (i.e., disabled). VisibilityIterator2.async.nBuffers - The number of lookahead buffers. This defaults to 2.

Debug settings --------------

VisibilityIterator2.async.doStats: true VisibilityIterator2.async.debug.logFile: stderr VisibilityIterator2.async.debug.logLevel: 1

Example

Motivation

For imaging and calibration you need to access an MS in some consistent order (by field, spectralwindow, time interval etc.). This class provides that access.

Thrown Exceptions

To Do

Definition at line 364 of file VisibilityIterator2.h.


Member Typedef Documentation

typedef enum MSIter::PolFrame casa::vi::VisibilityIterator2::PolFrame

Definition at line 406 of file VisibilityIterator2.h.


Member Enumeration Documentation

Enumerator:
Observed 
Model 
Corrected 

Definition at line 408 of file VisibilityIterator2.h.


Constructor & Destructor Documentation

casa::vi::VisibilityIterator2::VisibilityIterator2 ( const VisibilityIterator2  ) 
casa::vi::VisibilityIterator2::VisibilityIterator2 ( const MeasurementSet &  ms,
const SortColumns sortColumns = SortColumns(),
Bool  isWritable = False,
const VisBufferComponents2 prefetchColumns = 0,
Double  timeInterval = 0 
)

Construct from an MS and a Block of MS column enums specifying the iteration order.

These can be specified as MS::ANTENNA1, MS::ARRAY_ID, etc.; they are defined in MSMainEnums.h. If no order is specified, it uses the default sort order of MSIter, which is not necessarily the raw order of ms! The default ordering is ARRAY_ID, FIELD_ID, DATA_DESC_ID, and TIME, but check MSIter.h to be sure. These columns will be added first if they are not specified.

An optional timeInterval (in seconds) can be given to iterate through chunks of time. The default interval of 0 groups all times together. Every 'chunk' of data contains all data within a certain time interval and with identical values of the other iteration columns (e.g. DATA_DESC_ID and FIELD_ID).

A set of prefetch columns can be specified for asynchronous I/O use. These roughly correspond to the fields accessible from the VisBuffer. Specifying prefetch columns will cause an asynchronous VI to be created if asynchronous I/O is globally enabled. If the user wishes to have application-specific enable/disable of asynchronous I/O then they must implement logic that either either provides prefetch columns (enables) or a null pointer (disables).

casa::vi::VisibilityIterator2::VisibilityIterator2 ( const Block< const MeasurementSet * > &  mss,
const SortColumns sortColumns = SortColumns(),
Bool  isWritable = False,
const VisBufferComponents2 prefetchColumns = 0,
Double  timeInterval = 0 
)
casa::vi::VisibilityIterator2::VisibilityIterator2 ( const ViFactory factory  ) 
casa::vi::VisibilityIterator2::VisibilityIterator2 ( const Vector< ViiLayerFactory * > &  factories  ) 
virtual casa::vi::VisibilityIterator2::~VisibilityIterator2 (  )  [virtual]

Destructor.

casa::vi::VisibilityIterator2::VisibilityIterator2 (  )  [protected]

Member Function Documentation

void casa::vi::VisibilityIterator2::construct ( const VisBufferComponents2 prefetchColumns,
const Block< const MeasurementSet * > &  mss,
const SortColumns sortColumns,
Double  timeInterval,
Bool  writable 
) [protected]
BEGIN Experimental Section* static VisibilityIterator2* casa::vi::VisibilityIterator2::copyingViFactory ( const MeasurementSet &  srcMs,
MeasurementSet &  dstMs 
) [static]
bool casa::vi::VisibilityIterator2::existsColumn ( VisBufferComponent2  id  )  const
static String casa::vi::VisibilityIterator2::getAipsRcBase (  )  [inline, static]

Definition at line 655 of file VisibilityIterator2.h.

const VisImagingWeight& casa::vi::VisibilityIterator2::getImagingWeightGenerator (  )  const
ViImplementation2* casa::vi::VisibilityIterator2::getImpl (  )  const
Double casa::vi::VisibilityIterator2::getInterval (  )  const

In this context the interval determines what rows will be contained in a chunk.

A chunk is all the rows in an MS that have the same values in the sort columns, except for time; all rows that otherwise have the same values for the sort columns will be in the chunk if they are no later than "interval" seconds after the first row in the chunk.

This value is unrelated to the interval field of the MS main table.

Int casa::vi::VisibilityIterator2::getReportingFrameOfReference (  )  const

The reporting frame of reference is the default frame of reference to be used when the user requests the frequencies of the current data selection in a VisBuffer.

This is useful when the user wishes to select the data using one frame of reference but use the frequencies from another frame of reference. If not specified then the default will be to use the frame of reference used to select the data.

These *do not* change the selection in any way.

Int casa::vi::VisibilityIterator2::getRowBlocking (  )  const

RowBlocking is a suggestion to the iterator that it try to use subchunks having the suggested number of rows.

The VI will attempt to honor the suggestion except when there are not enough rows remaining in the chunk or when putting the suggested number of rows in the subchunk cannot be contained in a cube (e.g., there are sets of row with different numbers of frequencies, etc.). The latter case will mainly occur when the row visibility shape changes from one row to the next.

const SortColumns& casa::vi::VisibilityIterator2::getSortColumns (  )  const

Returns the columns that the VisibilityIterator2 is sorting by.

These are defined in MSMainEnums.h. These can be specified as MS::ANTENNA1, MS::ARRAY_ID, etc.

Subchunk casa::vi::VisibilityIterator2::getSubchunkId (  )  const

Returns the pair (chunk,subchunk) for the current position of the VI.

Only valid after origin has been called.

VisBuffer2* casa::vi::VisibilityIterator2::getVisBuffer (  ) 

Returns the VisBuffer permanently attached to this VisibilityIterator.

Referenced by casa::MSTransformManager::getVisBuffer().

virtual Bool casa::vi::VisibilityIterator2::hasWeightScaling (  )  const [virtual]
virtual void casa::vi::VisibilityIterator2::initWeightSpectrum ( const Cube< Float > &  wtsp  )  [virtual]

Initialize the weightSpectrum.

Other methods Returns True if this is an asynchronous VI* Bool casa::vi::VisibilityIterator2::isAsynchronous (  )  const
static Bool casa::vi::VisibilityIterator2::isAsynchronousIoEnabled (  )  [static]

Returns True if async I/O is globally enabled.

Bool casa::vi::VisibilityIterator2::isWritable (  )  const

Returns True if this VI is writable (always False for ROVI and True for VI; see VisibilityIterator class).

template<typename KlugeIn , typename KlugeOut >
static KlugeOut casa::vi::VisibilityIterator2::KlugeForTesting ( KlugeIn   )  [inline, static]
Bool casa::vi::VisibilityIterator2::more (  )  const
Bool casa::vi::VisibilityIterator2::moreChunks (  )  const
const MeasurementSet& casa::vi::VisibilityIterator2::ms (  )  const

reference to actual ms in interator

Int casa::vi::VisibilityIterator2::nDataDescriptionIds (  )  const

(i.e., length of polarization subtable)

void casa::vi::VisibilityIterator2::next (  ) 
void casa::vi::VisibilityIterator2::nextChunk (  ) 
Int casa::vi::VisibilityIterator2::nPolarizationIds (  )  const
Int casa::vi::VisibilityIterator2::nRowsInChunk (  )  const

Return the numbers of rows in the current chunk.

Int casa::vi::VisibilityIterator2::nSpectralWindows (  )  const

Return number of spws, polids, ddids for the current MS.

VisibilityIterator2& casa::vi::VisibilityIterator2::operator= ( const VisibilityIterator2  ) 
void casa::vi::VisibilityIterator2::origin (  ) 

END Experimental Section.

///////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////

Iteration movement methods

The typical use case for VisibilityIteration looks like

for (vi.originChunks(); vi.moreChunks(); nextChunk()){ for (vi.origin (); vi.more(); vi++){ } }

The outer loop is the "chunk" loop and the inner loop is the "subchunk" loop. A chunk contains all the rows having identical values for the sort columns values except time; time can have an optional interval value specified either in the constructor or via the setInterval method. If an interval is specified the set of rows will all have timestamps that are within that interval of the first row in the chunk; if no interval is specified then the chunk will contain only rows having the identical timestamp. If multiple MSs are specified in the constructor then changing from one MS to the next will occur on a chunk boundary (i.e., a chunk will never contain data from more than one MS).

A subchunk typically contains all the rows in the chunk having identical timestamps. The only exception is when the user calls setRowBlocking(N) with a positive value. In this case, the subchunk *may* contain up to N rows; however, this is only a suggestion to the VI. If there are less than N rows remaining in the chunk then fewer than N rows will be contained in the chunk. The number of rows in a subchunk will also be less than N if a larger set of rows would create an inconsistently shaped visibility cube; this could happen if the number of channels changes from one timestamp to another or the framed frequency selection selects a different number of channels from one timestamp to the next.

origin () - positions VI to the start of the current chunk operator++ - advance VI to next subchunk if it exists more - returns True if the VI is pointing to a valid subchunk

originChunks - Move to the first chunk of data. operator++ - advance VI to the next chunk if it exists moreChunks - returns True if the VI is pointing to a valid chunk.

void casa::vi::VisibilityIterator2::originChunks ( Bool  forceRewind  )  [protected]

advance the iteration

void casa::vi::VisibilityIterator2::originChunks (  ) 
void casa::vi::VisibilityIterator2::setFrequencySelection ( const FrequencySelections  ) 
the data returned is simply the channels that currently map to the selected frequencies for the specified frame of reference* void casa::vi::VisibilityIterator2::setFrequencySelection ( const FrequencySelection  ) 
void casa::vi::VisibilityIterator2::setInterval ( Double  timeInterval  ) 
void casa::vi::VisibilityIterator2::setReportingFrameOfReference ( Int   ) 
void casa::vi::VisibilityIterator2::setRowBlocking ( Int  nRows = 0  ) 
virtual void casa::vi::VisibilityIterator2::setWeightScaling ( CountedPtr< WeightScaling weightscaling  )  [virtual]

Manages the weight function that can be used to process the weights produced by the "scaled" variants of the weight accessors.

Use generateWeightscaling to create a WeightScaling object. This allow you to use either a function (FLoat (Float)) or a functor (object having method Float operator () (Float)).

To revert to having no scaling function, call setWeightScaling with 0 as the argument. Any call to setWeightScaling needs to be followed by an originChunks call before any further data access is performed using the VI.

The method hasWeightScaling will return false if either no weightScaling object has installed or setWeightScaling (0) was called. There is not way for VI to know if the user has passed in the identity function; doing so will still cause hasWeightScaling to return true.

Bool casa::vi::VisibilityIterator2::sigmaSpectrumExists (  )  const

Determine whether WEIGHT_SPECTRUM exists.

void casa::vi::VisibilityIterator2::slurp (  )  const

Call to use the slurp i/o method for all scalar columns.

This will set the BucketCache cache size to the full column length and cause the full column to be cached in memory, if any value of the column is used. In case of out-of-memory, it will automatically fall-back on the smaller cache size. Slurping the column is to be considered as a work-around for the Table i/o code, which uses BucketCache and performs extremely bad for random access. Slurping is useful when iterating non-sequentially an MS or parts of an MS, it is not tested with multiple MSs.

const vi::SubtableColumns& casa::vi::VisibilityIterator2::subtableColumns (  )  const
Iterator operation methods These methods alter the way that the VI operates After applying any of casa::vi::VisibilityIterator2::these ( except slurp which should be called after  originChunks  ) 
otherwise an exception will be casa::vi::VisibilityIterator2::thrown ( changing these values in the middle of a sweep can lead to unexpected  behavior  )  [final]
void casa::vi::VisibilityIterator2::useImagingWeight ( const VisImagingWeight imWgt  ) 

Assign a VisImagingWeight object to this iterator.

This object is used to generate imaging weights.

String casa::vi::VisibilityIterator2::ViiType (  )  const

Report the the ViImplementation type.

Bool casa::vi::VisibilityIterator2::weightSpectrumExists (  )  const

Determine whether WEIGHT_SPECTRUM exists.

void casa::vi::VisibilityIterator2::writeBackChanges ( VisBuffer2  ) 

Requests that the modified VisBuffer2 be written back to the visibility at the same spot that it came from.

The dirtyComponents feature of VisBuffer is used to mark which portions of the VisBuffer actually need to be written back out.

virtual void casa::vi::VisibilityIterator2::writeFlag ( const Cube< Bool > &  flag  )  [virtual]

Write/modify the flags in the data.

This will flag all channels in the original data that contributed to the output channel in the case of channel averaging. All polarizations have the same flag value.

Write/modify the flags in the data. This writes the flags as found in the MS, Cube(npol,nchan,nrow), where nrow is the number of rows in the current iteration (given by nRow()).

void casa::vi::VisibilityIterator2::writeFlagCategory ( const Array< Bool > &  fc  ) 
virtual void casa::vi::VisibilityIterator2::writeFlagRow ( const Vector< Bool > &  rowflags  )  [virtual]

Write/modify the flag row column; dimension Vector(nrow).

void casa::vi::VisibilityIterator2::writeModel ( const RecordInterface &  rec,
Bool  iscomponentlist = True,
Bool  incremental = False 
)

Write/modify the ncorr x nrow SigmaMat.

void writeSigmaMat(const Matrix<Float>& sigmat);

This puts a model into the descriptor of the current ms in the iterator Set iscomponentlist to True if the record represent a componentlist if False then it is a FTMachine Record that holds the model image note the spw and fields selected are going to be associated with this model incremetal =True implies add the model to previous any existant model in the ms for the spw and fields false means any existant model will be replaces.

void casa::vi::VisibilityIterator2::writeSigma ( const Matrix< Float > &  sig  ) 

Write/modify the Sigma.

void casa::vi::VisibilityIterator2::writeVisCorrected ( const Cube< Complex > &  vis  ) 

Write/modify the visibilities.

This is possibly only for a 'reference' MS which has a new DATA column. The first axis of the matrix should equal the selected number of channels in the original MS. If the MS does not contain all polarizations, only the parallel hand polarizations are used.

void writeVisCorrected (const Matrix<CStokesVector>& vis); void writeVisModel (const Matrix<CStokesVector>& vis); void writeVisObserved (const Matrix<CStokesVector>& vis);

Write/modify the visibilities This writes the data as found in the MS, Cube(npol,nchan,nrow).

void casa::vi::VisibilityIterator2::writeVisModel ( const Cube< Complex > &  vis  ) 
void casa::vi::VisibilityIterator2::writeVisObserved ( const Cube< Complex > &  vis  ) 
void casa::vi::VisibilityIterator2::writeWeight ( const Matrix< Float > &  wt  ) 

Write/modify the weights.

virtual void casa::vi::VisibilityIterator2::writeWeightSpectrum ( const Cube< Float > &  wtsp  )  [virtual]

Write/modify the weightMat.

virtual void writeWeightMat(const Matrix<Float>& wtmat);

Write/modify the weightSpectrum


Friends And Related Function Documentation

friend class asyncio::VLAT [friend]

friend class VisBufferImpl2; friend class VisBufferState;

Definition at line 380 of file VisibilityIterator2.h.

friend class casa::MSTransformIteratorFactory [friend]

functions VLAT should not access private parts, especially variables

Definition at line 383 of file VisibilityIterator2.h.

friend class VisBuffer2Adapter [friend]

These classes are members of the VI/VB framework and need extra access to the non-public methods of this class.

Any additions of classes not in this framework is strongly discouraged.

Friends of the class should limit themselves to accessing the protected area of this class so that items in the private area can remeain de facto private.

friend class VisibilityIteratorImpl2; friend VisBuffer2 * VisBuffer2::factory (VisibilityIterator2 * vi, VisBufferType t, VisBufferOptions options);

Definition at line 377 of file VisibilityIterator2.h.


Member Data Documentation

Definition at line 781 of file VisibilityIterator2.h.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1