001 package edu.nrao.sss.model.resource;
002
003 import java.util.List;
004 import java.util.SortedSet;
005
006 import edu.nrao.sss.astronomy.PolarizationType;
007 import edu.nrao.sss.measure.Frequency;
008 import edu.nrao.sss.measure.FrequencyRange;
009 import edu.nrao.sss.util.Identifiable;
010
011 /**
012 * A baseband of a correlator.
013 * <p>
014 * A correlator baseband is a digitized frequency range that may contain
015 * signals of interest. Basebands are often broken up into smaller
016 * pieces, called subbands, for processing.</p>
017 * <p>
018 * The frequency range of a baseband normally starts at zero (hence the
019 * term <i>base</i>band), but represents, or proxies, another portion
020 * of frequency space.</p>
021 * <p>
022 * This baseband interface was made more generic after its inception so
023 * that it could represent both baseband "singlets" and baseband pairs.
024 * The main consequence is that this baseband now returns a collection,
025 * instead of a single instance, of polarizations.</p>
026 * <p>
027 * <b>Version Info:</b>
028 * <table style="margin-left:2em">
029 * <tr><td>$Revision: 2200 $</td></tr>
030 * <tr><td>$Date: 2009-04-15 16:00:47 -0600 (Wed, 15 Apr 2009) $</td></tr>
031 * <tr><td>$Author: dharland $ (last person to modify)</td></tr>
032 * </table></p>
033 *
034 * @author David M. Harland
035 * @since 2008-01-23
036 */
037 public interface CorrelatorBaseband
038 extends Cloneable, HasBandwidth, Identifiable
039 {
040 /**
041 * Returns the name of this baseband.
042 * @return the name of this baseband.
043 */
044 public String getName();
045
046 /**
047 * Resets this instance's ID, and the IDs of all its components,
048 * to a value that represents the unidentified state.
049 * <p>
050 * This method is useful for preparing an instance for storage in a database.
051 * The ID property (as of now, though this may change in the future) is
052 * used by our persistence mechanism to identify objects. If you are
053 * persisting this instance for the first time, you may need to call
054 * this method before performing a save. This is especially true if
055 * you have created this instance from XML, as the XML unmarshalling
056 * brings along the ID property.</p>
057 */
058 public void clearId();
059
060 /**
061 * Returns <i>true</i> if this is an unpaired, or singlet, baseband.
062 * If <i>true</i>, then the number of
063 * {@link #getPolarizations() polarizations} represented by this baseband
064 * should be one.
065 * <p>
066 * Either this method or {@link #isPair()}, but not both, should
067 * be <i>true</i>. Only single and paired basebands are anticipated.</p>
068 *
069 * @return <i>true</i> if this is an unpaired, or singlet, baseband.
070 */
071 public boolean isSinglet();
072
073 /**
074 * Returns <i>true</i> if this is a paired baseband.
075 * If <i>true</i>, then the number of
076 * {@link #getPolarizations() polarizations} represented by this baseband
077 * should be two.
078 * <p>
079 * Either this method or {@link #isSinglet()}, but not both, should
080 * be <i>true</i>. Only single and paired basebands are anticipated.</p>
081 *
082 * @return <i>true</i> if this is a paired baseband.
083 */
084 public boolean isPair();
085
086 //============================================================================
087 // FREQUENCY
088 //============================================================================
089
090 /**
091 * Sets the bandwidth of this baseband.
092 * <p>
093 * An attempt to set the bandwidth to a value lower than this baseband's
094 * minimum will result in a bandwidth equal to the lowest allowable,
095 * and likewise for exceeding this bandwidth's maximum.</p>
096 * <p>
097 * If this baseband has a discrete set of allowable bandwidths, then this
098 * method will set the bandwidth to the smallest allowable value that is
099 * greater than {@code newWidth}.</p>
100 *
101 * @param newWidth
102 * the new bandwidth of this baseband.
103 *
104 * @throws IllegalArgumentException
105 * if {@code newWidth} is <i>null</i>.
106 */
107 public void setBandwidth(Frequency newWidth);
108
109 /**
110 * Returns the portion of frequency space for which this baseband is a proxy.
111 * @return the portion of frequency space for which this baseband is a proxy.
112 */
113 public FrequencyRange getProxiedRange();
114
115 /**
116 * Returns <i>true</i> if the high and low frequencies in the
117 * proxied range are mapped to the low and high frequencies,
118 * respectively, of this baseband.
119 * <p>
120 * An example where the return value of this method would be <i>true</i>
121 * is if this baseband had a width of 2 GHz and proxied an original
122 * range of 45 GHz - 43 GHz, respectively. That is, the 2 GHz signal
123 * in the baseband would represent 45 GHz, 1 GHz would represent 44 GHz,
124 * and 0 GHz would represent 43 GHz.</p>
125 *
126 * @return
127 * <i>true</i> if the high and low frequencies of the proxied rage
128 * are reversed with respect to this baseband.
129 */
130 public boolean proxiedRangeIsReversed();
131
132 //============================================================================
133 // QUANTIZATION & POLARIZATION
134 //============================================================================
135
136 /**
137 * Returns the number of bits per sample in this baseband.
138 * This quantity is called the <i>initial</i> quantization because some
139 * correlators allow clients to <i>re</i>quantize the data during
140 * processing. The initial quantization, or IQ, is typically a property
141 * of the signal before it ever reaches the correlator.
142 *
143 * @return the number of bits per sample in this baseband.
144 */
145 public int getInitialQuantization();
146
147 /** @deprecated Use {@link #getPolarizations()}. */
148 @Deprecated
149 public PolarizationType getPolarization();
150
151 /**
152 * Returns the polarizations of the signals represented by this baseband.
153 * @return the polarizations of the signals represented by this baseband.
154 */
155 public List<PolarizationType> getPolarizations();
156
157 //============================================================================
158 // SUBBAND
159 //============================================================================
160
161 /**
162 * Returns the maximum number of subbands this baseband may hold.
163 * @return the maximum number of subbands this baseband may hold.
164 */
165 public int getMaxSubbandCount();
166
167 /**
168 * Returns the number of subbands currently held by this baseband.
169 * @return the number of subbands currently held by this baseband.
170 */
171 public int getSubbandCount();
172
173 /**
174 * Returns a list of this baseband's subbands.
175 * @return a list of this baseband's subbands.
176 */
177 public List<CorrelatorSubband> getSubbands();
178
179 /**
180 * Creates and returns a new subband that may later be added
181 * to this subband. Each implementation of this <tt>CorrelatorBaseband</tt>
182 * interface will decide which implementation of <tt>CorrelatorSubband</tt>
183 * it constructs.
184 * <p>
185 * The returned subband will belong to no baseband.</p>
186 *
187 * @return
188 * a new subband of a type that is compatible with this baseband.
189 */
190 public CorrelatorSubband makeNewSubband();
191
192 /**
193 * Adds {@code newSubband} to this baseband if this baseband is not
194 * already full.
195 *
196 * @param newSubband
197 * a subband to be added to this baseband.
198 *
199 * @throws IllegalArgumentException
200 * if this baseband already holds its maximum number of subbands.
201 */
202 public void addSubband(CorrelatorSubband newSubband);
203
204 /**
205 * Removes the {@code unwantedSubband} from this baseband, if present.
206 * The unwanted subband will belong to no baseband after its removal.
207 *
208 * @param unwantedSubband
209 * the subband to be removed from this baseband.
210 *
211 * @return
212 * <i>true</i> if this baseband contained {@code newSubband}.
213 */
214 public boolean removeSubband(CorrelatorSubband unwantedSubband);
215
216 /**
217 * Removes from this baseband the subband at the given index.
218 * The subband currently at this index is returned. If there
219 * is no subband at that index, <i>null</i> is returned.
220 *
221 * @param index
222 * the index of the unwanted subband in this baseband's list of subbands.
223 *
224 * @return
225 * the unwanted subband, or <i>null</i> if there was no subband
226 * at {@code index}.
227 */
228 public CorrelatorSubband removeSubbandAt(int index);
229
230 /**
231 * Removes all subbands from this baseband.
232 *
233 * @return the number of subbands removed.
234 */
235 public int removeAllSubbands();
236
237 /**
238 * Returns a set of frequencies that individual subbands should not cover.
239 * Not all implementations of basebands will have such frequencies. For those
240 * that do not, an empty set will be returned.
241 * <p>
242 * The frequencies in the returned set represent a preset subband grid.
243 * Subbands may start or end exactly on these frequencies, but should not
244 * otherwise contain them. The low and high frequencies of this baseband
245 * are included in the returned range. The high frequency is included even
246 * if it is not a natural grid point. For example, if this baseband covers
247 * the frequency range from 0 to 45 units, with a grid line every 10 units,
248 * the returned set will contain 0, 10, 20, 30, 40, and 45 units.</p>
249 *
250 * @return a set of frequencies that individual subbands should not cover.
251 */
252 public SortedSet<Frequency> getSubbandGrid();
253
254 //============================================================================
255 // VALIDATION
256 //============================================================================
257
258 //TODO see TODO items in VALIDATION section of CorrelatorSubband
259
260 //============================================================================
261 //
262 //============================================================================
263
264 /**
265 * Returns a copy of this baseband.
266 * @return a copy of this baseband.
267 */
268 public CorrelatorBaseband clone();
269 }