001 package edu.nrao.sss.astronomy;
002
003 import java.util.SortedSet;
004 import java.util.TreeSet;
005
006 import edu.nrao.sss.util.EnumerationUtility;
007
008 /**
009 * A set of values that describe the polarization state of electromagnetic
010 * radiation<sup>1</sup>.
011 * <p>
012 * This enumeration has the same name, and elements that have the same
013 * names and are in the same order, as the corresponding
014 * <a href="http://almasw.hq.eso.org/almasw/bin/view/HLA/GeneratedEnums#StokesParameter">
015 * ALMA enumeration</a>, which in turn is based on a CASA enumeration.</p>
016 * <p>
017 * <b><u>References</u></b>
018 * <ul>
019 * <li><a href="http://scienceworld.wolfram.com/physics/StokesParameters.html">
020 * World of Physics</a></li>
021 * <li><a href="http://www.atnf.csiro.au/computing/software/atca_aips/node11.html">
022 * ATNF</a></li>
023 * <li><a href="http://en.wikipedia.org/wiki/Stokes_parameters">
024 * Wikipedia</a></li>
025 * <li><a href="http://www.optics.arizona.edu/jcwyant/JoseDiaz/Polarization-Circular.htm">
026 * University of Arizona</a> (there's a great 3D motion display here)</li>
027 * </ul></p>
028 * <p style="font-size:small; font-style:italic">
029 * <sup>1</sup>Stokes parameters. (2007, September 2). In Wikipedia, The Free
030 * Encyclopedia. Retrieved 15:13, September 24, 2007, from
031 * <a href="http://en.wikipedia.org/w/index.php?title=Stokes_parameters&oldid=155199986">
032 * http://en.wikipedia.org/w/index.php?title=Stokes_parameters&oldid=155199986</a>.</p>
033 * <p>
034 * <b>Version Info:</b>
035 * <table style="margin-left:2em">
036 * <tr><td>$Revision: 1763 $</td></tr>
037 * <tr><td>$Date: 2008-11-24 16:22:07 -0700 (Mon, 24 Nov 2008) $</td></tr>
038 * <tr><td>$Author: dharland $ (last person to modify)</td></tr>
039 * </table></p>
040 *
041 * @author David M. Harland
042 * @since 2007-09-24
043 */
044 public enum StokesParameter
045 {
046 /**
047 * Total intensity. For the Stokes Parameters,
048 * <tt>I<sup>2</sup> = Q<sup>2</sup> + U<sup>2</sup> + V<sup>2</sup></tt>.
049 */
050 I,
051
052 /**
053 * The Q, or S<sub>1</sub>, Stokes parameter.
054 * Q, along with U, represents linear polarization.
055 */
056 Q,
057
058 /**
059 * The U, or S<sub>2</sub>, Stokes parameter.
060 * U, along with Q, represents linear polarization.
061 */
062 U,
063
064 /**
065 * The V, or S<sub>3</sub>, Stokes parameter.
066 * V represents circular polarization.
067 */
068 V,
069
070 /**
071 * Circular polarization measurement equal to
072 * <tt>I + V</tt>.
073 */
074 RR,
075
076 /**
077 * Circular polarization measurement equal to
078 * <tt>Q + iU</tt>, where <tt>i = (-1)<sup>1/2</sup></tt>.
079 */
080 RL,
081
082 /**
083 * Circular polarization measurement equal to
084 * <tt>Q - iU</tt>, where <tt>i = (-1)<sup>1/2</sup></tt>.
085 */
086 LR,
087
088 /**
089 * Circular polarization measurement equal to
090 * <tt>I - V</tt>.
091 */
092 LL,
093
094 /**
095 * Linear polarization measurement equal to
096 * <tt>I + Q</tt>.
097 */
098 XX,
099
100 /**
101 * Linear polarization measurement equal to
102 * <tt>U + iV</tt>, where <tt>i = (-1)<sup>1/2</sup></tt>.
103 */
104 XY,
105
106 /**
107 * Linear polarization measurement equal to
108 * <tt>U - iV</tt>, where <tt>i = (-1)<sup>1/2</sup></tt>.
109 */
110 YX,
111
112 /**
113 * Linear polarization measurement equal to
114 * <tt>I - Q</tt>.
115 */
116 YY,
117
118 RX,
119 RY,
120 LX,
121 LY,
122 XR,
123 XL,
124 YR,
125 YL,
126
127 PP,
128 PQ,
129 QP,
130 QQ,
131
132 RCIRCULAR,
133 LCIRCULAR,
134
135 /**
136 * Single dish polarization type
137 * <span style="font-size:x-small;font-style:italic">(ALMA definition)</span>.
138 */
139 LINEAR,
140
141 /**
142 * Polarized intensity, equal to
143 * <tt>(Q<sup>2</sup>+U<sup>2</sup>+V<sup>2</sup>)<sup>1/2</sup></tt>
144 * <span style="font-size:x-small;font-style:italic">(ALMA definition)</span>.
145 */
146 PTOTAL,
147
148 /**
149 * Linearly polarized intensity, equal to
150 * <tt>(Q<sup>2</sup>+U<sup>2</sup>)<sup>1/2</sup></tt>
151 * <span style="font-size:x-small;font-style:italic">(ALMA definition)</span>.
152 */
153 PLINEAR,
154
155 /**
156 * Polarization fraction, equal to <tt>PTOTAL</tt> / <tt>I</tt>
157 * <span style="font-size:x-small;font-style:italic">(ALMA definition)</span>.
158 */
159 PFTOTAL,
160
161 /**
162 * Linear polarization fraction, equal to <tt>PLINEAR</tt> / <tt>I</tt>
163 * <span style="font-size:x-small;font-style:italic">(ALMA definition)</span>.
164 */
165 PFLINEAR,
166
167 /**
168 * Linear polarization angle, equal to
169 * <tt>0.5 * arctan(U/Q)</tt>, in radians
170 * <span style="font-size:x-small;font-style:italic">(ALMA definition)</span>.
171 */
172 PANGLE;
173
174 /**
175 * Returns a default stokes parameter.
176 * @return a default stokes parameter.
177 */
178 public static StokesParameter getDefault()
179 {
180 return I;
181 }
182
183 /**
184 * Returns the stokes parameter represented by {@code text}.
185 * <p>
186 * For details about the transformation, see
187 * {@link EnumerationUtility#enumFromString(Class, String)}.</p>
188 *
189 * @param text a text representation of a stokes parameter.
190 *
191 * @return the stokes parameter represented by {@code text}.
192 */
193 public static StokesParameter fromString(String text)
194 {
195 return EnumerationUtility.getSharedInstance()
196 .enumFromString(StokesParameter.class, text);
197 }
198
199 /**
200 * Returns a set of stokes parameters than can be created from the given
201 * polarizations. The returned set will never be <i>null</i>, but will
202 * be empty if no Stokes Parameters can be created from the polarizations.
203 * <p>
204 * It is permissible to have one or both of the parameters be <i>null</i>.
205 * If both are <i>null</i> the returned set will be empty. If one is
206 * <i>null</i> and the other is not the returned set will have one
207 * element. For example if <tt>p1</tt> is <i>null</i> and <tt>p2</tt>
208 * is <tt>PolarizationType.R</tt>, the returned set will contain
209 * only {@link #RR}.</p>
210 *
211 * @param p1
212 * a polarization to be combined with <tt>p2</tt> to form
213 * Stokes parameters.
214 *
215 * @param p2
216 * a polarization to be combined with <tt>p1</tt> to form
217 * Stokes parameters.
218 *
219 * @return
220 * a set of stokes parameters than can be created from the given
221 * polarizations.
222 */
223 public static SortedSet<StokesParameter>
224 getStokesFor(PolarizationType p1, PolarizationType p2)
225 {
226 SortedSet<StokesParameter> result = new TreeSet<StokesParameter>();
227
228 String name1 = (p1 == null) ? null : p1.name();
229 String name2 = (p2 == null) ? null : p2.name();
230
231 if (name1 != null && name2 == null)
232 {
233 name2 = name1;
234 }
235 else if (name1 == null && name2 != null)
236 {
237 name1 = name2;
238 }
239
240 //At this point both names are non-null or both are null.
241 //We add to the set only if both are non-null
242 if (name1 != null)
243 addParamToSet(result, name1, name2);
244
245 return result;
246 }
247
248 private static void addParamToSet(SortedSet<StokesParameter> s,
249 String name1, String name2)
250 {
251 StokesParameter sp = StokesParameter.fromString(name1 + name1);
252 if (sp != null)
253 s.add(sp);
254
255 sp = StokesParameter.fromString(name1 + name2);
256 if (sp != null)
257 s.add(sp);
258
259 sp = StokesParameter.fromString(name2 + name1);
260 if (sp != null)
261 s.add(sp);
262
263 sp = StokesParameter.fromString(name2 + name2);
264 if (sp != null)
265 s.add(sp);
266 }
267
268 /*
269 public static void main(String... args) throws Exception
270 {
271 Set<StokesParameter> sp = StokesParameter.getStokesFor(PolarizationType.L,
272 PolarizationType.R);
273 System.out.println(sp);
274 }
275 */
276 }