Line data Source code
1 : //# SkyJones.h: Definitions of interface for SkyJones
2 : //# Copyright (C) 1996,1997,1998,2000,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_TRANSFORM2_SKYJONES_H
30 : #define SYNTHESIS_TRANSFORM2_SKYJONES_H
31 :
32 : #include <casacore/casa/aips.h>
33 : #include <casacore/casa/BasicSL/Complex.h>
34 : #include <casacore/images/Images/ImageInterface.h>
35 : #include <components/ComponentModels/ComponentList.h>
36 : #include <components/ComponentModels/SkyComponent.h>
37 : #include <casacore/casa/Utilities/CompositeNumber.h>
38 : #include <msvis/MSVis/VisBuffer2.h>
39 : #include <synthesis/TransformMachines/SkyJones.h>
40 :
41 : namespace casacore{
42 :
43 : class ImageRegion;
44 : class CoordinateSystem;
45 : }
46 :
47 : namespace casa{
48 : //class SkyEquation;
49 : namespace refim{ //#namespace for refactored imaging
50 : //#forward
51 :
52 :
53 : //# Need forward declaration for Solve in the Jones Matrices
54 :
55 : // <summary>
56 : // Sky Jones: Model sky-plane instrumental effects for the SkyEquation
57 : // </summary>
58 :
59 : // <use visibility=export>
60 :
61 : // <reviewed reviewer="" date="" tests="" demos="">
62 :
63 : // <prerequisite>
64 : // <li> <linkto class="SkyEquation">SkyEquation</linkto> class
65 : // </prerequisite>
66 : //
67 : // <etymology>
68 : // SkyJones describes an interface for Components to be used in
69 : // the <linkto class="SkyEquation">SkyEquation</linkto>.
70 : // It is an Abstract Base Class: most methods
71 : // must be defined in derived classes.
72 : // </etymology>
73 : //
74 : // <synopsis>
75 : //
76 : // A SkyJones implements the instrumental effect of some sky-plane based
77 : // calibration effect. It conceptually applies an image of Jones matrices
78 : // to an image. For example, it takes an image of the sky brightness and
79 : // applies the complex primary beam for a given interferometer. Only the
80 : // interface is defined here in the Abstract Base Class. Actual concrete
81 : // classes must be derived from SkyJones. Some (most) SkyJones are
82 : // solvable: the SkyEquation can be used by the SkyJones to return
83 : // gradients with respect to itself (via the image interface). Thus for a
84 : // SkyJones to solve for itself, it calls the SkyEquation methods to get
85 : // gradients of chi-squared with respect to the image pixel values. The
86 : // SkyJones then uses these gradients as appropriate to update itself.
87 : //
88 : //
89 : // The following examples illustrate how a SkyJones can be
90 : // used:
91 : // <ul>
92 : // <li> Mosaicing: one SkyJones for the primary beam. For efficiency
93 : // the image must be cached and the VisSet iteration order set to
94 : // minimize the number of recalculations.
95 : // </ul>
96 : // </synopsis>
97 : //
98 : // <example>
99 : // <srcblock>
100 : //
101 : // // Low level code example:
102 : //
103 : // casacore::MeasurementSet ms("imagertest/3C273XC1.ms", casacore::Table::Update);
104 : // VPSkyJones unsquintedVPSJ(ms);
105 : // VPSkyJones squintedVPSJ(ms, true, casacore::Quantity(5.0, "deg"), BeamSquint::GOFIGURE);
106 : // unsquintedVPSJ.reset();
107 : // squintedVPSJ.reset();
108 : //
109 : // casacore::PagedImage<casacore::Complex> imageIn;
110 : // casacore::PagedImage<casacore::Complex> imageOut; // in reality, this ouwld need more construction with coords and shapes
111 : //
112 : // VisSet vs(ms,bi,chanSelection,interval);
113 : //
114 : // casacore::Int row = 0;
115 : // VisIter &vi = vs.iter();
116 : // VisBuffer vb(vi);
117 : // for (vi.originChunks();vi.moreChunks();vi.nextChunk()) {
118 : // cout << "This is integration: " << nChunks++ << endl;
119 : // for (vi.origin();vi.more();vi++) {
120 : // if (myVPSJ.change(vb)) {
121 : // cout << "State has changed: " << endl;
122 : // squintedVPSJ.showState(os);
123 : // squintedVPSJ.apply(imageIn, imageOut, vb, row);
124 : // }
125 : // }
126 : // }
127 : //
128 : //
129 : // // High Level Code Example:
130 : //
131 : //
132 : // // Create an ImageSkyJones from an image on disk
133 : // ImageSkyModel ism(casacore::PagedImage<casacore::Float>("3C273XC1.modelImage"));
134 : //
135 : // // Make an FTMachine: here we use a simple Grid and FT.
136 : // GridFT ft;
137 : //
138 : // SkyEquation se(ism, vs, ft);
139 : //
140 : // // Make a Primary Beam Sky Model
141 : // VPSkyJones pbsj(ms);
142 : //
143 : // // Add it to the SkyEquation
144 : // se.setSkyJones(pbsj);
145 : //
146 : // // Predict the visibility set
147 : // se.predict();
148 : //
149 : // // Read some other data
150 : // VisSet othervs("3c84.MS.Otherdata");
151 : //
152 : // // Make a Clean Image and write it out
153 : // HogbomCleanImageSkyJones csm(ism);
154 : // if (csm.solve(othervs)) {
155 : // casacore::PagedImage<casacore::Float> cleanImage=csm.image(0);
156 : // cleanImage.setName("3c84.cleanImage");
157 : // }
158 : //
159 : // </srcblock>
160 : // </example>
161 : //
162 : // <motivation>
163 : // The properties of sky-plane based calibration effects must be described
164 : // for the <linkto class="SkyEquation">SkyEquation</linkto>
165 : // </motivation>
166 : //
167 : // <todo asof="97/10/01">
168 : // <li> There are no Concrete Classes derived from SkyJones!
169 : // <li> Solvable part needs implementation: we need to derive an
170 : // image of gradients of the elements of the Jones matrix. See VisJones
171 : // for how to do this.
172 : // </todo>
173 :
174 : class SkyJones {
175 : public:
176 :
177 : // Allowed types of VisJones matrices
178 : //enum Type{E,T,F,D};
179 :
180 : //enum SizeType{COMPOSITE, POWEROF2, ANY};
181 :
182 : SkyJones();
183 : // Destructor.
184 : virtual ~SkyJones();
185 :
186 : // Apply Jones matrix to an image (and adjoint)
187 : // <group>
188 : virtual casacore::ImageInterface<casacore::Complex>& apply(const casacore::ImageInterface<casacore::Complex>& in,
189 : casacore::ImageInterface<casacore::Complex>& out,
190 : const vi::VisBuffer2& vb, casacore::Int row,
191 : casacore::Bool forward=true) = 0;
192 :
193 : virtual casacore::ImageInterface<casacore::Float>& apply(const casacore::ImageInterface<casacore::Float>& in,
194 : casacore::ImageInterface<casacore::Float>& out,
195 : const vi::VisBuffer2& vb, casacore::Int row) = 0;
196 :
197 : virtual casacore::ImageInterface<casacore::Float>& applySquare(const casacore::ImageInterface<casacore::Float>& in,
198 : casacore::ImageInterface<casacore::Float>& out,
199 : const vi::VisBuffer2& vb, casacore::Int row) = 0;
200 : // </group>
201 :
202 : // Apply Jones matrix to a sky component (and adjoint)
203 : // <group>
204 : virtual SkyComponent& apply(SkyComponent& in,
205 : SkyComponent& out,
206 : const vi::VisBuffer2& vb, casacore::Int row, casacore::Bool forward=true) = 0;
207 : virtual SkyComponent& applySquare(SkyComponent& in,
208 : SkyComponent& out,
209 : const vi::VisBuffer2& vb, casacore::Int row) = 0;
210 : // </group>
211 :
212 : // Has this operator changed since the last application?
213 : virtual casacore::Bool changed(const vi::VisBuffer2& vb, casacore::Int row) = 0;
214 :
215 : // Does this operator changed in this VisBuffer,
216 : // starting with row1?
217 : // If yes, we return in row2, the last row that has the
218 : // same SkyJones as row1.
219 : virtual casacore::Bool changedBuffer(const vi::VisBuffer2& vb, casacore::Int row1, casacore::Int& row2) = 0;
220 :
221 : // Reset
222 : virtual void reset() = 0;
223 :
224 : // Assure
225 : virtual void assure(const vi::VisBuffer2& vb, casacore::Int row) = 0;
226 :
227 : // Does the operator change in this visbuffer or since the last
228 : // call?
229 : // I'm not sure this is useful -- come back to it
230 : // m.a.h. Dec 30 1999
231 : virtual casacore::Bool change(const vi::VisBuffer2& vb) = 0;
232 :
233 : // Return the type of this Jones matrix (actual type of derived class).
234 : virtual ::casa::SkyJones::Type type() = 0;
235 :
236 : // Apply gradient
237 : virtual casacore::ImageInterface<casacore::Complex>&
238 : applyGradient(casacore::ImageInterface<casacore::Complex>& result, const vi::VisBuffer2& vb, casacore::Int row)
239 : = 0;
240 : virtual SkyComponent&
241 : applyGradient(SkyComponent& result, const vi::VisBuffer2& vb, casacore::Int row)
242 : = 0;
243 :
244 : // Is this solveable?
245 : virtual casacore::Bool isSolveable()=0;
246 :
247 : // Initialize for gradient search
248 : virtual void initializeGradients()=0;
249 :
250 : // Finalize for gradient search
251 : virtual void finalizeGradients()=0;
252 :
253 : // Add to Gradient Chisq
254 : virtual void addGradients(const vi::VisBuffer2& vb, casacore::Int row, const casacore::Float sumwt,
255 : const casacore::Float chisq, const casacore::Matrix<casacore::Complex>& c,
256 : const casacore::Matrix<casacore::Float>& f)=0;
257 :
258 : // Solve
259 : //virtual casacore::Bool solve (SkyEquation& se) = 0;
260 :
261 : // Get the casacore::ImageRegion of the primary beam on an Image for a given pointing
262 : // Note: casacore::ImageRegion is not necesarily constrained to lie within the
263 : // image region (for example, if the pointing center is near the edge of the
264 : // image). fPad: extra fractional padding beyond the primary beam support
265 : // (note: we do not properly treat squint yet, this will cover it for now)
266 : // iChan: frequency channel to take: lowest frequency channel is safe for all
267 : // SizeType: COMPOSITE = next larger composite number,
268 : // POWEROF2 = next larger power of 2,
269 : // ANY = just take what we get!
270 : //
271 : // Potential problem: this casacore::ImageRegion includes all casacore::Stokes and Frequency Channels
272 : // present in the input image.
273 : //COMMENTING out for now as this depend on PBMathInterface and which depends
274 : //back on SkyJones::sizeType
275 :
276 : virtual casacore::ImageRegion* extent (const casacore::ImageInterface<casacore::Complex>& im,
277 : const vi::VisBuffer2& vb,
278 : const casacore::Int irow=-1,
279 : const casacore::Float fPad=1.2,
280 : const casacore::Int iChan=0,
281 : const casa::SkyJones::SizeType sizeType=casa::SkyJones::COMPOSITE)=0;
282 : virtual casacore::ImageRegion* extent (const casacore::ImageInterface<casacore::Float>& im,
283 : const vi::VisBuffer2& vb,
284 : const casacore::Int irow=-1,
285 : const casacore::Float fPad=1.2,
286 : const casacore::Int iChan=0,
287 : const casa::SkyJones::SizeType sizeType=casa::SkyJones::COMPOSITE)=0;
288 :
289 : virtual casacore::String telescope()=0;
290 :
291 : virtual casacore::Int support(const vi::VisBuffer2& vb, const casacore::CoordinateSystem& cs)=0;
292 :
293 0 : virtual void setThreshold(const casacore::Float t){threshold_p=t;};
294 0 : virtual casacore::Float threshold(){return threshold_p;};
295 :
296 :
297 : protected:
298 :
299 : // Could be over-ridden if necessary
300 0 : virtual casacore::String typeName() {
301 0 : switch(type()) {
302 0 : case ::casa::SkyJones::E: // voltage pattern (ie, on-axis terms)
303 0 : return "E Jones";
304 0 : case ::casa::SkyJones::T: // Tropospheric effects
305 0 : return "T Jones";
306 0 : case ::casa::SkyJones::F: // Faraday
307 0 : return "F Jones";
308 0 : case ::casa::SkyJones::D: // D Beam (ie, polarization leakage beam; off axis terms)
309 0 : return "D Jones";
310 : }
311 0 : return "Not known";
312 : };
313 :
314 : casacore::Float threshold_p;
315 :
316 :
317 : private:
318 : };
319 :
320 : }//# end of namespace refim
321 :
322 : } // end namespace casa
323 :
324 : #endif
325 :
326 :
327 :
328 :
329 :
330 :
331 :
332 :
333 :
334 :
|
