casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
BeamSkyJones.h
Go to the documentation of this file.
1 //# BeamSkyJones.h: Definitions of interface for BeamSkyJones
2 //# Copyright (C) 1996,1997,1998,1999,2000,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 adressed 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 //#
27 //# $Id$
28 
29 #ifndef SYNTHESIS_BEAMSKYJONES_H
30 #define SYNTHESIS_BEAMSKYJONES_H
31 
32 #include <casa/aips.h>
33 #include <casa/Containers/Block.h>
34 #include <casa/Exceptions/Error.h>
36 #include <measures/Measures.h>
41 
42 namespace casacore{
43 
44 class ImageRegion;
45 }
46 
47 namespace casa { //# NAMESPACE CASA - BEGIN
48 
49 //#forward
50 class SkyModel;
51 
52 //# Need forward declaration for Solve in the Jones Matrices
53 class SkyEquation;
54 
55 // <summary> beam-like sky-plane effects for the SkyEquation </summary>
56 
57 // <use visibility=export>
58 
59 // <reviewed reviewer="" date="" tests="" demos="">
60 
61 // <prerequisite>
62 // <li> <linkto class="SkyEquation">SkyEquation</linkto> class
63 // <li> <linkto class="SkyJones">SkyJones</linkto> class
64 // <li> <linkto class="PBMathInterface">PBMathInterface</linkto> class
65 // </prerequisite>
66 //
67 // <etymology>
68 // BeamSkyJones, derived from SkyJones, describes an interface to
69 // beam-based SkyJones objects. Like SkyJones, it too is an Abstract
70 // Base Class, but implements the beam-related methods.
71 // </etymology>
72 //
73 // <synopsis>
74 //
75 // <motivation>
76 // The properties of sky-plane based calibration effects must be described
77 // for the <linkto class="SkyEquation">SkyEquation</linkto>; this class
78 // encapsulates the antenna beam-based aspects which are present in at least
79 // a few other specific SkyJones (VPSkyJones and DBeamSkyJones).
80 // </motivation>
81 //
82 // <todo asof="98/11/01">
83 // <li> Solvable part needs implementation: we need to derive an
84 // image of gradients of the elements of the Jones matrix. See VisJones
85 // for how to do this.
86 // <li> The casacore::MS, version II, will have a beam subtable, which will have PBMaths
87 // for each antenna. Until this becomes available, we need to do some
88 // fudging; for example, we
89 // </todo>
90 
91 class BeamSkyJones : virtual public SkyJones {
92 
93 public:
94 
95  // Eventually, the casacore::MS will have all the beam information in its Beam Subtable.
96  // Till then, we either guess the PB to use or explicitly define it upon construction.
97  // Construct from a Measurement Set, figure out the most appropriate PBMath object
98  // from casacore::MS information
99  BeamSkyJones(const casacore::Quantity &parallacticAngleIncrement = casacore::Quantity(720.0, "deg"), // def= 1 PA interval
100  BeamSquint::SquintType doSquint = BeamSquint::NONE, // def= no beam squint offsets
101  const casacore::Quantity &skyPositionThreshold = casacore::Quantity(180,"deg")); // def= assume there is no change of
102  // this operator due to position offset
103 
104 
105  // Virtual destructor (this is a virtual base class)
106  virtual ~BeamSkyJones() = 0;
107 
108  // Print out information concerning the state of this object
109  virtual void showState(casacore::LogIO& os);
110 
111  // Apply Jones matrix to an image (and adjoint)
112  // No "applyInverse" is available from the SkyJones classes,
113  // you can get them directly from PBMath or you can get
114  // the equivalent effect by dividing by grad grad Chi^2
115  // in ImageSkyModel.
116  // <group>
119  const VisBuffer& vb, casacore::Int row,
120  casacore::Bool forward=true);
123  const VisBuffer& vb, casacore::Int row);
124 
127  const VisBuffer& vb, casacore::Int row);
128  // </group>
129 
130  // Apply Jones matrix to a sky component (and adjoint)
131  //if fullspectral==True then the output skycomponent will have a TabularSpectrum
132  //Spectral Model which will be at all the channel frequencies available in the vb;
133  //when False the out SkyComponent is modified using the first channel frequency only.
134  //Thus dealing with the frequency dependence of the SkyJones.
135  // <group>
137  SkyComponent& out,
138  const VisBuffer& vb, casacore::Int row,
139  casacore::Bool forward = true, casacore::Bool fullspectral=false);
141  SkyComponent& out,
142  const VisBuffer& vb, casacore::Int row, casacore::Bool fullspectral=false);
143  // </group>
144 
145  // Understand if things have changed since last PB application
146  // <group>
147 
148  // Reset to pristine state
149  virtual void reset();
150 
151  // Has this operator changed since the last Application?
152  // (or more properly, since the last update() )
153  virtual casacore::Bool changed(const VisBuffer& vb, casacore::Int row);
154 
155  // Does the operator change in this visbuffer or since the last call?
156  // May not be useful -- check it out: m.a.h. Dec 30 1999
157  virtual casacore::Bool change(const VisBuffer& vb);
158 
159  // Does this operator changed in this VisBuffer,
160  // starting with row1?
161  // If yes, we return in row2, the last row that has the
162  // same SkyJones as row1.
163  // NOTE: need to first call changed(const VisBuffer& vb, casacore::Int row) and
164  // shield the user from the case where the fieldID has changed
165  // (which only changes in blocks)
166  virtual casacore::Bool changedBuffer(const VisBuffer& vb, casacore::Int row1, casacore::Int& row2);
167 
168  // Update the FieldID, Telescope, pointingDirection, Parallactic angle info
169  void update(const VisBuffer& vb, casacore::Int row);
170 
171  // if (changed) {update()}
172  virtual void assure (const VisBuffer& vb, casacore::Int row);
173  // </group>
174 
175  // Return the type of this Jones matrix (actual type of derived class).
176  virtual Type type() {return SkyJones::E;};
177 
178  // Apply gradient
181  casacore::Int row);
182 
183  virtual SkyComponent&
184  applyGradient(SkyComponent& result, const VisBuffer& vb,
185  casacore::Int row);
186 
187  // Is this solveable?
188  virtual casacore::Bool isSolveable() {return false;};
189 
190  // Initialize for gradient search
191  virtual void initializeGradients();
192 
193  // Finalize for gradient search
194  virtual void finalizeGradients();
195 
196  // Add to Gradient Chisq
197  virtual void addGradients(const VisBuffer& vb, casacore::Int row, const casacore::Float sumwt,
200 
201  // Solve
202  virtual casacore::Bool solve (SkyEquation& se);
203 
204  // Manage the PBMath objects
205  // <group>
206  // set the PB based on telescope name, antennaID and feedID
207  // If antennaID or feedID is -1, the PBMath object is set for
208  // all antennae or feeds, respectively. These are the default
209  // values to retain the previous interface.
210  //
211  // Note. It would be nice to change the interface and make antennaID
212  // and feedID the second and the third parameter, respectively.
213  void setPBMath(const casacore::String &telescope, PBMath &myPBmath,
214  const casacore::Int &antennaID = -1, const casacore::Int &feedID = -1);
215 
216  // get the PBMath object; returns false if that one doesn't exist,
217  // true if it does exist and is OK
218  // whichAnt is an index into an array of PBMaths, which is different
219  // for all telescope/antenna/feed combinations
220  // Not sure why we need such a low-level method declared as public,
221  // retained to preserve old interface
222  casacore::Bool getPBMath(casacore::uInt whichAnt, PBMath &myPBMath) const;
223 
224  // get the PBMath object; returns false if that one doesn't exist,
225  // true if it does exist and is OK
226  // antennaID and feedID default to -1 to preserve the old interface
227  // TODO: change the interface and make antennaID and feedID the
228  // second and third parameter respectively to have a better looking code
230  const casacore::Int &antennaID = -1, const casacore::Int &feedID = -1) const;
231 
233 
235 
236  // Return true if all antennas share a common VP
238  //</group>
239 
240  // Get the casacore::ImageRegion of the primary beam on an Image for a given pointing
241  // Note: casacore::ImageRegion is not necesarily constrained to lie within the
242  // image region (for example, if the pointing center is near the edge of the
243  // image). fPad: extra padding over the primary beam supporrt,
244  // fractional (ie, 1.2 for 20% padding), in all directions.
245  // (note: we do not properly treat squint yet, this will cover it for now)
246  // iChan: frequency channel to take: lowest frequency channel is safe for all
247  //
248  // Potential problem: this casacore::ImageRegion includes all casacore::Stokes and Frequency Channels
249  // present in the input image.
251  const VisBuffer& vb,
252  const casacore::Int irow=-1,
253  const casacore::Float fPad=1.2,
254  const casacore::Int iChan=0,
255  const SkyJones::SizeType sizeType=SkyJones::COMPOSITE);
256 
258  const VisBuffer& vb, const casacore::Int irow=-1,
259  const casacore::Float fPad=1.2, const casacore::Int iChan=0,
260  const SkyJones::SizeType sizeType=SkyJones::COMPOSITE);
261 
262  // summarize the PBMaths contained here.
263  // n = -1 => terse table
264  // n = 0 => table plus constructor values
265  // n = m => plot m samples of the PB profile
266  virtual void summary(casacore::Int n=0);
267 
268  //return the telescope it is on at this state
270 
271  //Get an idea of the support of the PB in number of pixels
272  virtual casacore::Int support(const VisBuffer& vb, const casacore::CoordinateSystem& cs);
273 
274 private:
275 
276 
277 
278 
280 
282 
284 
287 
288  casacore::Double parallacticAngleIncrement_p; // a parallactic angle threshold
289  // beyond which the operator is considered to be
290  // changed (in radians)
291  casacore::Double skyPositionThreshold_p; // a sky position threshold beyond
292  // which the operator is considered to be changed
293  // (in radians)
295  // used when the operator was applied last time.
296  // One value in radians for each beam model in PBMaths.
297  // A zero-length block means that the operator
298  // has never been applied
300  // used when the operator was applied last time.
301  // One element for each beam model in PBMaths.
302  // A zero-length block means that the operator
303  // has never been applied
304 
305  // One or more PBMaths (a common one for the
306  // entire array, or one for each antenna)
307  // This requires some sorting out for heterogeneous arrays!
309  // Names of telescopes (parralel with PBMaths
311 
312  // Antenna IDs (parallel with PBMaths)
314  // Feed IDs (parallel with PBMaths)
316 
317  // cache of the indices to the PBMaths container for antenna/feed 1 and 2
318  mutable const VisBuffer *lastUpdateVisBuffer_p; // to ensure that the cache
319  // is filled for the correct
320  // VisBuffer. The value is used
321  // for comparison only
322  mutable casacore::Int lastUpdateRow_p; // to ensure that the cache is filled for
323  // correct row in the VisBuffer
324  mutable casacore::Int lastUpdateIndex1_p; // index of the first antenna/feed
325  mutable casacore::Int lastUpdateIndex2_p; // index of the second antenna/feed
326  //
327 
328  mutable casacore::Bool hasBeenApplied; // true if the operator has been applied at least once
329 
330  // update the indices cache. This method could be made protected in the
331  // future (need access functions for lastUpdateIndex?_p to benefit from it)
332  // Cache will be valid for a given VisBuffer and row
333  void updatePBMathIndices(const VisBuffer &vb, casacore::Int row) const;
334 
335 protected:
336  // return true if two directions are close enough to consider the
337  // operator unchanged, false otherwise
339  const casacore::MDirection &dir2) const;
340 
341  // return index of compareTelescope, compareAntenna and compareFeed in
342  // myTelescopes_p, myAntennaIDs and myFeedIDs; -1 if not found
343  // if compareAntenna or compareTelescope is -1, this means that the
344  // PBMath class is the same for all antennae/feeds. An exception will
345  // be raised, if separate PBMath objects have been assigned by setPBMath
346  // for different feeds/antennae but -1 is used for query.
347  //
348  // It would be good to rename this function to indexBeams as this name
349  // is more appropriate.
350  //
351  casacore::Int indexTelescope(const casacore::String & compareTelescope,
352  const casacore::Int &compareAntenna=-1,
353  const casacore::Int &compareFeed=-1) const;
357 
358 };
359 
360 
361 } //# NAMESPACE CASA - END
362 
363 #endif
364 
A Measure: astronomical direction.
Definition: MDirection.h:174
int Int
Definition: aipstype.h:50
casacore::Int lastMSId_p
Definition: BeamSkyJones.h:283
casacore::Int lastUpdateRow_p
is filled for the correct VisBuffer.
Definition: BeamSkyJones.h:322
virtual void showState(casacore::LogIO &os)
Print out information concerning the state of this object.
virtual casacore::Bool changed(const VisBuffer &vb, casacore::Int row)
Has this operator changed since the last Application? (or more properly, since the last update()) ...
BeamSkyJones(const casacore::Quantity &parallacticAngleIncrement=casacore::Quantity(720.0,"deg"), BeamSquint::SquintType doSquint=BeamSquint::NONE, const casacore::Quantity &skyPositionThreshold=casacore::Quantity(180,"deg"))
Eventually, the casacore::MS will have all the beam information in its Beam Subtable.
casacore::Block< casacore::Double > lastParallacticAngles_p
which the operator is considered to be changed (in radians)
Definition: BeamSkyJones.h:294
Quantum< Double > Quantity
Definition: Quantum.h:38
void updatePBMathIndices(const VisBuffer &vb, casacore::Int row) const
update the indices cache.
virtual void summary(casacore::Int n=0)
summarize the PBMaths contained here.
Primary beam envelope class, derived from PBMathInterface.
Definition: PBMath.h:126
SquintType
Allowed Squints: NONE = no squint: PB is centered on the pointing center RR = PB is shifted from poin...
Definition: BeamSquint.h:109
ostream-like interface to creating log messages.
Definition: LogIO.h:167
virtual casacore::Bool solve(SkyEquation &se)
Solve.
void update(const VisBuffer &vb, casacore::Int row)
Update the FieldID, Telescope, pointingDirection, Parallactic angle info.
casacore::Quantity getPAIncrement()
Definition: BeamSkyJones.h:232
casacore::Bool isHomogeneous() const
Return true if all antennas share a common VP.
Types
Types of known MDirections Warning: The order defines the order in the translation matrix FromTo in ...
Definition: MDirection.h:188
casacore::Block< casacore::MDirection > lastDirections_p
used when the operator was applied last time.
Definition: BeamSkyJones.h:299
casacore::Block< casacore::Int > myFeedIDs_p
Feed IDs (parallel with PBMaths)
Definition: BeamSkyJones.h:315
virtual Type type()
Return the type of this Jones matrix (actual type of derived class).
Definition: BeamSkyJones.h:176
casacore::String telescope_p
Definition: BeamSkyJones.h:355
casacore::Int lastArrayId_p
Definition: BeamSkyJones.h:281
void setPBMath(const casacore::String &telescope, PBMath &myPBmath, const casacore::Int &antennaID=-1, const casacore::Int &feedID=-1)
Manage the PBMath objects.
Referenced counted pointer for constant data.
Definition: VisModelData.h:42
casacore::Int lastUpdateIndex1_p
correct row in the VisBuffer
Definition: BeamSkyJones.h:324
casacore::Bool getPBMath(casacore::uInt whichAnt, PBMath &myPBMath) const
get the PBMath object; returns false if that one doesn&#39;t exist, true if it does exist and is OK which...
BeamSquint::SquintType doSquint_p
Definition: BeamSkyJones.h:286
double Double
Definition: aipstype.h:55
virtual casacore::Bool changedBuffer(const VisBuffer &vb, casacore::Int row1, casacore::Int &row2)
Does this operator changed in this VisBuffer, starting with row1? If yes, we return in row2...
casacore::Bool hasBeenApplied
Definition: BeamSkyJones.h:328
casacore::ImageRegion * extent(const casacore::ImageInterface< casacore::Complex > &im, const VisBuffer &vb, const casacore::Int irow=-1, const casacore::Float fPad=1.2, const casacore::Int iChan=0, const SkyJones::SizeType sizeType=SkyJones::COMPOSITE)
Get the casacore::ImageRegion of the primary beam on an Image for a given pointing Note: casacore::Im...
beam-like sky-plane effects for the SkyEquation
Definition: BeamSkyJones.h:91
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::Double skyPositionThreshold_p
beyond which the operator is considered to be changed (in radians)
Definition: BeamSkyJones.h:291
float Float
Definition: aipstype.h:54
virtual ~BeamSkyJones()=0
this operator due to position offset
virtual casacore::Bool isSolveable()
Is this solveable?
Definition: BeamSkyJones.h:188
virtual casacore::Bool change(const VisBuffer &vb)
Does the operator change in this visbuffer or since the last call? May not be useful – check it out: ...
casacore::MDirection convertDir(const VisBuffer &vb, const casacore::MDirection &inDir, const casacore::MDirection::Types outType)
Class to hold a region of interest in an image.
Definition: ImageRegion.h:86
casacore::Int indexTelescope(const casacore::String &compareTelescope, const casacore::Int &compareAntenna=-1, const casacore::Int &compareFeed=-1) const
return index of compareTelescope, compareAntenna and compareFeed in myTelescopes_p, myAntennaIDs and myFeedIDs; -1 if not found if compareAntenna or compareTelescope is -1, this means that the PBMath class is the same for all antennae/feeds.
casacore::String telescope()
return the telescope it is on at this state
Sky Jones: Model sky-plane instrumental effects for the SkyEquation.
Definition: SkyJones.h:172
casacore::Int lastUpdateIndex2_p
Definition: BeamSkyJones.h:325
const VisBuffer * lastUpdateVisBuffer_p
cache of the indices to the PBMaths container for antenna/feed 1 and 2
Definition: BeamSkyJones.h:318
const Double c
Fundamental physical constants (SI units):
A component of a model of the sky.
Definition: SkyComponent.h:130
casacore::ImageInterface< casacore::Float > & applySquare(const casacore::ImageInterface< casacore::Float > &in, casacore::ImageInterface< casacore::Float > &out, const VisBuffer &vb, casacore::Int row)
casacore::Double lastTime_p
Definition: BeamSkyJones.h:285
virtual void assure(const VisBuffer &vb, casacore::Int row)
if (changed) {update()}
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::Block< casacore::Int > myAntennaIDs_p
Antenna IDs (parallel with PBMaths)
Definition: BeamSkyJones.h:313
casacore::ImageInterface< casacore::Complex > & apply(const casacore::ImageInterface< casacore::Complex > &in, casacore::ImageInterface< casacore::Complex > &out, const VisBuffer &vb, casacore::Int row, casacore::Bool forward=true)
Apply Jones matrix to an image (and adjoint) No &quot;applyInverse&quot; is available from the SkyJones classes...
VisBuffers encapsulate one chunk of visibility data for processing.
Definition: VisBuffer.h:153
casacore::CountedPtr< VisBufferUtil > vbutil_p
Definition: BeamSkyJones.h:356
virtual void finalizeGradients()
Finalize for gradient search.
virtual casacore::Int support(const VisBuffer &vb, const casacore::CoordinateSystem &cs)
Get an idea of the support of the PB in number of pixels.
virtual void addGradients(const VisBuffer &vb, casacore::Int row, const casacore::Float sumwt, const casacore::Float chisq, const casacore::Matrix< casacore::Complex > &c, const casacore::Matrix< casacore::Float > &f)
Add to Gradient Chisq.
virtual void initializeGradients()
Initialize for gradient search.
casacore::Block< PBMath > myPBMaths_p
used when the operator was applied last time.
Definition: BeamSkyJones.h:308
virtual void reset()
Understand if things have changed since last PB application.
casacore::Int lastFieldId_p
Definition: BeamSkyJones.h:279
casacore::Block< casacore::String > myTelescopes_p
Names of telescopes (parralel with PBMaths.
Definition: BeamSkyJones.h:310
casacore::Quantity getSkyPositionThreshold()
Definition: BeamSkyJones.h:234
virtual casacore::ImageInterface< casacore::Complex > & applyGradient(casacore::ImageInterface< casacore::Complex > &result, const VisBuffer &vb, casacore::Int row)
Apply gradient.
casacore::Double parallacticAngleIncrement_p
Definition: BeamSkyJones.h:288
Interconvert pixel and world coordinates.
Type
Allowed types of VisJones matrices.
Definition: SkyJones.h:176
unsigned int uInt
Definition: aipstype.h:51
casacore::Bool directionsCloseEnough(const casacore::MDirection &dir1, const casacore::MDirection &dir2) const
return true if two directions are close enough to consider the operator unchanged, false otherwise
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42