Line data Source code
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: 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 : //#
27 : //# $Id$
28 :
29 : #ifndef SYNTHESIS_BEAMSKYJONES_H
30 : #define SYNTHESIS_BEAMSKYJONES_H
31 :
32 : #include <casacore/casa/aips.h>
33 : #include <casacore/casa/Containers/Block.h>
34 : #include <casacore/casa/Exceptions/Error.h>
35 : #include <casacore/measures/Measures/MDirection.h>
36 : #include <casacore/measures/Measures.h>
37 : #include <casacore/measures/Measures/Stokes.h>
38 : #include <synthesis/TransformMachines/SkyJones.h>
39 : #include <synthesis/TransformMachines/PBMath.h>
40 : #include <msvis/MSVis/VisBufferUtil.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 ¶llacticAngleIncrement = 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>
117 : casacore::ImageInterface<casacore::Complex>& apply(const casacore::ImageInterface<casacore::Complex>& in,
118 : casacore::ImageInterface<casacore::Complex>& out,
119 : const VisBuffer& vb, casacore::Int row,
120 : casacore::Bool forward=true);
121 : casacore::ImageInterface<casacore::Float>& apply(const casacore::ImageInterface<casacore::Float>& in,
122 : casacore::ImageInterface<casacore::Float>& out,
123 : const VisBuffer& vb, casacore::Int row);
124 :
125 : casacore::ImageInterface<casacore::Float>& applySquare(const casacore::ImageInterface<casacore::Float>& in,
126 : casacore::ImageInterface<casacore::Float>& out,
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>
136 : SkyComponent& apply(SkyComponent& in,
137 : SkyComponent& out,
138 : const VisBuffer& vb, casacore::Int row,
139 : casacore::Bool forward = true, casacore::Bool fullspectral=false);
140 : SkyComponent& applySquare(SkyComponent& in,
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 0 : virtual Type type() {return SkyJones::E;};
177 :
178 : // Apply gradient
179 : virtual casacore::ImageInterface<casacore::Complex>&
180 : applyGradient(casacore::ImageInterface<casacore::Complex>& result, const VisBuffer& vb,
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 0 : 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,
198 : const casacore::Float chisq, const casacore::Matrix<casacore::Complex>& c,
199 : const casacore::Matrix<casacore::Float>& f);
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 45 : 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
229 : casacore::Bool getPBMath(const casacore::String &telescope, PBMath &myPBMath,
230 : const casacore::Int &antennaID = -1, const casacore::Int &feedID = -1) const;
231 :
232 0 : casacore::Quantity getPAIncrement() {return casacore::Quantity(parallacticAngleIncrement_p,"rad");}
233 :
234 : casacore::Quantity getSkyPositionThreshold() {return casacore::Quantity(skyPositionThreshold_p,"rad");}
235 :
236 : // Return true if all antennas share a common VP
237 : casacore::Bool isHomogeneous() const;
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.
250 : casacore::ImageRegion* extent (const casacore::ImageInterface<casacore::Complex>& im,
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 :
257 : casacore::ImageRegion* extent (const casacore::ImageInterface<casacore::Float>& im,
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
269 : casacore::String telescope();
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 :
279 : casacore::Int lastFieldId_p;
280 :
281 : casacore::Int lastArrayId_p;
282 :
283 : casacore::Int lastMSId_p;
284 :
285 : casacore::Double lastTime_p;
286 : BeamSquint::SquintType doSquint_p;
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)
294 : casacore::Block<casacore::Double> lastParallacticAngles_p; // a cache of parallactic angles
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
299 : casacore::Block<casacore::MDirection> lastDirections_p; // a chache of directions
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!
308 : casacore::Block<PBMath> myPBMaths_p;
309 : // Names of telescopes (parralel with PBMaths
310 : casacore::Block<casacore::String> myTelescopes_p;
311 :
312 : // Antenna IDs (parallel with PBMaths)
313 : casacore::Block<casacore::Int> myAntennaIDs_p;
314 : // Feed IDs (parallel with PBMaths)
315 : casacore::Block<casacore::Int> myFeedIDs_p;
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
338 : casacore::Bool directionsCloseEnough(const casacore::MDirection &dir1,
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 0 : const casacore::Int &compareAntenna=-1,
353 45 : const casacore::Int &compareFeed=-1) const;
354 : casacore::MDirection convertDir(const VisBuffer& vb, const casacore::MDirection& inDir, const casacore::MDirection::Types outType);
355 : casacore::String telescope_p;
356 : casacore::CountedPtr<VisBufferUtil> vbutil_p;
357 :
358 : };
359 :
360 :
361 : } //# NAMESPACE CASA - END
362 :
363 : #endif
364 :
|
