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