casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
SkyJones.h
Go to the documentation of this file.
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: 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_SKYJONES_H
30 #define SYNTHESIS_SKYJONES_H
31 
32 #include <casa/aips.h>
33 #include <casa/BasicSL/Complex.h>
34 #include <msvis/MSVis/VisSet.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 
179 
180  SkyJones();
181  // Destructor.
182  virtual ~SkyJones();
183 
184  // Apply Jones matrix to an image (and adjoint)
185  // <group>
188  const VisBuffer& vb, casacore::Int row,
189  casacore::Bool forward=true) = 0;
190 
193  const VisBuffer& vb, casacore::Int row) = 0;
194 
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;
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
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,
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 
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;
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  virtual void setThreshold(const casacore::Float t){threshold_p=t;};
291 
292 
293 protected:
294 
295  // Could be over-ridden if necessary
297  switch(type()) {
298  case SkyJones::E: // voltage pattern (ie, on-axis terms)
299  return "E Jones";
300  case SkyJones::T: // Tropospheric effects
301  return "T Jones";
302  case SkyJones::F: // Faraday
303  return "F Jones";
304  case SkyJones::D: // D Beam (ie, polarization leakage beam; off axis terms)
305  return "D Jones";
306  }
307  return "Not known";
308  };
309 
311 
312 
313 private:
314 };
315 
316 
317 } //# NAMESPACE CASA - END
318 
319 #endif
320 
321 
322 
323 
324 
325 
326 
327 
328 
329 
virtual void finalizeGradients()=0
Finalize for gradient search.
int Int
Definition: aipstype.h:50
virtual casacore::Bool changedBuffer(const VisBuffer &vb, casacore::Int row1, casacore::Int &row2)=0
Does this operator changed in this VisBuffer, starting with row1? If yes, we return in row2...
virtual void initializeGradients()=0
Initialize for gradient search.
virtual void assure(const VisBuffer &vb, casacore::Int row)=0
Assure.
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)=0
Add to Gradient Chisq.
virtual casacore::Float threshold()
Definition: SkyJones.h:290
virtual 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)=0
Apply Jones matrix to an image (and adjoint)
virtual casacore::String telescope()=0
virtual casacore::ImageInterface< casacore::Float > & applySquare(const casacore::ImageInterface< casacore::Float > &in, casacore::ImageInterface< casacore::Float > &out, const VisBuffer &vb, casacore::Int row)=0
casacore::Float threshold_p
Definition: SkyJones.h:308
virtual void reset()=0
Reset.
virtual 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=COMPOSITE)=0
Get the casacore::ImageRegion of the primary beam on an Image for a given pointing Note: casacore::Im...
virtual ~SkyJones()
Destructor.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual void setThreshold(const casacore::Float t)
Definition: SkyJones.h:289
virtual casacore::Int support(const VisBuffer &vb, const casacore::CoordinateSystem &cs)=0
float Float
Definition: aipstype.h:54
Class to hold a region of interest in an image.
Definition: ImageRegion.h:86
virtual casacore::String typeName()
Could be over-ridden if necessary.
Definition: SkyJones.h:296
Sky Jones: Model sky-plane instrumental effects for the SkyEquation.
Definition: SkyJones.h:172
virtual casacore::Bool change(const VisBuffer &vb)=0
Does the operator change in this visbuffer or since the last call? I&#39;m not sure this is useful – come...
const Double c
Fundamental physical constants (SI units):
A component of a model of the sky.
Definition: SkyComponent.h:130
virtual casacore::ImageInterface< casacore::Complex > &virtual SkyComponent &virtual casacore::Bool isSolveable()=0
Apply gradient.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
VisBuffers encapsulate one chunk of visibility data for processing.
Definition: VisBuffer.h:153
virtual casacore::Bool solve(SkyEquation &se)=0
Solve.
Interconvert pixel and world coordinates.
Type
Allowed types of VisJones matrices.
Definition: SkyJones.h:176
virtual Type type()=0
Return the type of this Jones matrix (actual type of derived class).
virtual casacore::Bool changed(const VisBuffer &vb, casacore::Int row)=0
Has this operator changed since the last application?
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42