edu.nrao.sss.model.resource
Interface CorrelatorBaseband

All Superinterfaces:

Cloneable, HasBandwidth, Identifiable

All Known Implementing Classes:

CorrelatorBasebandAbs, VlaBasebandPair, WidarBaseband, WidarBasebandPair, WidarBasebandSinglet

public interface CorrelatorBaseband
extends Cloneable, HasBandwidth, Identifiable

A baseband of a correlator.

A correlator baseband is a digitized frequency range that may contain signals of interest. Basebands are often broken up into smaller pieces, called subbands, for processing.

The frequency range of a baseband normally starts at zero (hence the term baseband), but represents, or proxies, another portion of frequency space.

This baseband interface was made more generic after its inception so that it could represent both baseband "singlets" and baseband pairs. The main consequence is that this baseband now returns a collection, instead of a single instance, of polarizations.

Version Info:

$Revision: 2200 $

$Date: 2009-04-15 16:00:47 -0600 (Wed, 15 Apr 2009) $

$Author: dharland $ (last person to modify)

Since:

2008-01-23

Author:

David M. Harland

Field Summary

Fields inherited from interface edu.nrao.sss.util.Identifiable

UNIDENTIFIED

Method Summary

void	addSubband(CorrelatorSubband newSubband) Adds newSubband to this baseband if this baseband is not already full.
void	clearId() Resets this instance's ID, and the IDs of all its components, to a value that represents the unidentified state.
CorrelatorBaseband	clone() Returns a copy of this baseband.
int	getInitialQuantization() Returns the number of bits per sample in this baseband.
int	getMaxSubbandCount() Returns the maximum number of subbands this baseband may hold.
String	getName() Returns the name of this baseband.
PolarizationType	getPolarization() Deprecated. Use getPolarizations().
List<PolarizationType>	getPolarizations() Returns the polarizations of the signals represented by this baseband.
FrequencyRange	getProxiedRange() Returns the portion of frequency space for which this baseband is a proxy.
int	getSubbandCount() Returns the number of subbands currently held by this baseband.
SortedSet<Frequency>	getSubbandGrid() Returns a set of frequencies that individual subbands should not cover.
List<CorrelatorSubband>	getSubbands() Returns a list of this baseband's subbands.
boolean	isPair() Returns true if this is a paired baseband.
boolean	isSinglet() Returns true if this is an unpaired, or singlet, baseband.
CorrelatorSubband	makeNewSubband() Creates and returns a new subband that may later be added to this subband.
boolean	proxiedRangeIsReversed() Returns true if the high and low frequencies in the proxied range are mapped to the low and high frequencies, respectively, of this baseband.
int	removeAllSubbands() Removes all subbands from this baseband.
boolean	removeSubband(CorrelatorSubband unwantedSubband) Removes the unwantedSubband from this baseband, if present.
CorrelatorSubband	removeSubbandAt(int index) Removes from this baseband the subband at the given index.
void	setBandwidth(Frequency newWidth) Sets the bandwidth of this baseband.

Methods inherited from interface edu.nrao.sss.model.resource.HasBandwidth

getAllowableBandwidthClosestTo, getAllowableBandwidthFor, getAllowableBandwidths, getBandwidth, getMaximumBandwidth, getMinimumBandwidth, hasDiscreteBandwidths

Methods inherited from interface edu.nrao.sss.util.Identifiable

getId

Method Detail

getName

String getName()

Returns the name of this baseband.

Returns:

the name of this baseband.

clearId

void clearId()

Resets this instance's ID, and the IDs of all its components, to a value that represents the unidentified state.

This method is useful for preparing an instance for storage in a database. The ID property (as of now, though this may change in the future) is used by our persistence mechanism to identify objects. If you are persisting this instance for the first time, you may need to call this method before performing a save. This is especially true if you have created this instance from XML, as the XML unmarshalling brings along the ID property.

isSinglet

boolean isSinglet()

Returns true if this is an unpaired, or singlet, baseband. If true, then the number of polarizations represented by this baseband should be one.

Either this method or isPair(), but not both, should be true. Only single and paired basebands are anticipated.

Returns:

true if this is an unpaired, or singlet, baseband.

isPair

boolean isPair()

Returns true if this is a paired baseband. If true, then the number of polarizations represented by this baseband should be two.

Either this method or isSinglet(), but not both, should be true. Only single and paired basebands are anticipated.

Returns:

true if this is a paired baseband.

setBandwidth

void setBandwidth(Frequency newWidth)

Sets the bandwidth of this baseband.

An attempt to set the bandwidth to a value lower than this baseband's minimum will result in a bandwidth equal to the lowest allowable, and likewise for exceeding this bandwidth's maximum.

If this baseband has a discrete set of allowable bandwidths, then this method will set the bandwidth to the smallest allowable value that is greater than newWidth.

Parameters:

newWidth - the new bandwidth of this baseband.

Throws:

IllegalArgumentException - if newWidth is null.

getProxiedRange

FrequencyRange getProxiedRange()

Returns the portion of frequency space for which this baseband is a proxy.

Returns:

the portion of frequency space for which this baseband is a proxy.

proxiedRangeIsReversed

boolean proxiedRangeIsReversed()

Returns true if the high and low frequencies in the proxied range are mapped to the low and high frequencies, respectively, of this baseband.

An example where the return value of this method would be true is if this baseband had a width of 2 GHz and proxied an original range of 45 GHz - 43 GHz, respectively. That is, the 2 GHz signal in the baseband would represent 45 GHz, 1 GHz would represent 44 GHz, and 0 GHz would represent 43 GHz.

Returns:

true if the high and low frequencies of the proxied rage are reversed with respect to this baseband.

getInitialQuantization

int getInitialQuantization()

Returns the number of bits per sample in this baseband. This quantity is called the initial quantization because some correlators allow clients to requantize the data during processing. The initial quantization, or IQ, is typically a property of the signal before it ever reaches the correlator.

Returns:

the number of bits per sample in this baseband.

getPolarization

@Deprecated
PolarizationType getPolarization()

Deprecated. Use getPolarizations().

getPolarizations

List<PolarizationType> getPolarizations()

Returns the polarizations of the signals represented by this baseband.

Returns:

the polarizations of the signals represented by this baseband.

getMaxSubbandCount

int getMaxSubbandCount()

Returns the maximum number of subbands this baseband may hold.

Returns:

the maximum number of subbands this baseband may hold.

getSubbandCount

int getSubbandCount()

Returns the number of subbands currently held by this baseband.

Returns:

the number of subbands currently held by this baseband.

getSubbands

List<CorrelatorSubband> getSubbands()

Returns a list of this baseband's subbands.

Returns:

a list of this baseband's subbands.

makeNewSubband

CorrelatorSubband makeNewSubband()

Creates and returns a new subband that may later be added to this subband. Each implementation of this CorrelatorBaseband interface will decide which implementation of CorrelatorSubband it constructs.

The returned subband will belong to no baseband.

Returns:

a new subband of a type that is compatible with this baseband.

addSubband

void addSubband(CorrelatorSubband newSubband)

Adds newSubband to this baseband if this baseband is not already full.

Parameters:

newSubband - a subband to be added to this baseband.

Throws:

IllegalArgumentException - if this baseband already holds its maximum number of subbands.

removeSubband

boolean removeSubband(CorrelatorSubband unwantedSubband)

Removes the unwantedSubband from this baseband, if present. The unwanted subband will belong to no baseband after its removal.

Parameters:

unwantedSubband - the subband to be removed from this baseband.

Returns:

true if this baseband contained newSubband.

removeSubbandAt

CorrelatorSubband removeSubbandAt(int index)

Removes from this baseband the subband at the given index. The subband currently at this index is returned. If there is no subband at that index, null is returned.

Parameters:

index - the index of the unwanted subband in this baseband's list of subbands.

Returns:

the unwanted subband, or null if there was no subband at index.

removeAllSubbands

int removeAllSubbands()

Removes all subbands from this baseband.

Returns:

the number of subbands removed.

getSubbandGrid

SortedSet<Frequency> getSubbandGrid()

Returns a set of frequencies that individual subbands should not cover. Not all implementations of basebands will have such frequencies. For those that do not, an empty set will be returned.

The frequencies in the returned set represent a preset subband grid. Subbands may start or end exactly on these frequencies, but should not otherwise contain them. The low and high frequencies of this baseband are included in the returned range. The high frequency is included even if it is not a natural grid point. For example, if this baseband covers the frequency range from 0 to 45 units, with a grid line every 10 units, the returned set will contain 0, 10, 20, 30, 40, and 45 units.

Returns:

a set of frequencies that individual subbands should not cover.

clone

CorrelatorBaseband clone()

Returns a copy of this baseband.

Returns:

a copy of this baseband.