edu.nrao.sss.model.resource
Interface CorrelatorSubband

All Superinterfaces:

Cloneable, HasBandwidth, Identifiable

All Known Implementing Classes:

CorrelatorSubbandAbs, VlaSubband, WidarSubband

public interface CorrelatorSubband
extends Cloneable, HasBandwidth, Identifiable

A portion of a correlator baseband.

The main properties of a subband are its location in frequency space, its (re)quantization, and its correlation products. Rather than hold its correlation products directly, this subband holds them indirectly through groups of correlation products. A group is formed by a collection of products that have identical properties, such as integration times or allocated correlator resources. For applications that do not make use of groups, merely populate a group with a single product.

Version Info:

$Revision: 1986 $

$Date: 2009-02-19 16:47:31 -0700 (Thu, 19 Feb 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

CorrelationProductGroup	addNewCorrelationProductGroup() Creates a new correlation product group, adds it to this subband, and returns it.
void	clearId() Resets this instance's ID, and the IDs of all its components, to a value that represents the unidentified state.
SortedSet<Integer>	getAllowableRequantizations() Returns the set of allowable requantization values for this subband.
CorrelatorBaseband	getBaseband() Returns the baseband to which this subband belongs.
Frequency	getCentralFrequency() Returns the central frequency of this subband.
List<CorrelationProductGroup>	getCorrelationProductGroups() Returns this subband's collection of correlation product groups.
FrequencyRange	getFrequencyRange() Returns the frequency range covered by this subband.
Frequency	getMaximumCentralFrequency() Returns the largest allowable central frequency for this subband.
Frequency	getMinimumCentralFrequency() Returns the smallest allowable central frequency for this subband.
String	getName() Returns the name of this subband.
FrequencyRange	getProxiedRange() Returns the portion of frequency space for which this subband is a proxy.
int	getRequantization() Returns the number of bits to which the data in this subband will be requantized.
void	removeCorrelationProductGroup(CorrelationProductGroup unwantedGroup) Removes a correlation product group from this subband.
void	setBandwidth(Frequency newWidth) Sets the bandwidth of this subband.
void	setCentralFrequency(Frequency newCenter) Sets the central frequency of this subband.
void	setCentralProxiedFrequency(Frequency newSkyCenter) Modifies this subband so that its new center is a proxy for newSkyCenter.
void	setName(String newName) Sets the (optional) name of this subband.
void	setRequantization(int bits) Sets the number of bits to which data should be requantized.

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

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.

setName

void setName(String newName)

Sets the (optional) name of this subband. The default state is to have no name.

Parameters:

newName - the new name for this subband. A value of null may be used to make this an unnamed subband, which is its default state.

getName

String getName()

Returns the name of this subband. If this subband has no name, the empty string ("") is returned.

Returns:

the name of this subband or the empty string if it has no name.

setBandwidth

void setBandwidth(Frequency newWidth)

Sets the bandwidth of this subband.

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

If this subband has a discrete set of allowable bandwidths, then this method will set the bandwidth to that which is closest to newWidth. If the newWidth is not an allowable bandwidth and is equally distant from two allowable values, this subband's bandwidth will be set to the smaller of those values.

When changing the bandwidth, this method will attempt to leave this subband's center where it is. However, if doing so would result in a frequency range whose low value is less than zero, the center will be reset to be half of the bandwidth.

Parameters:

newWidth - the new bandwidth of this subband.

setCentralFrequency

void setCentralFrequency(Frequency newCenter)

Sets the central frequency of this subband.

When moving the center, this method will always leave the bandwidth unchanged. If an attempt is made to move the center in such a way that the low end of this subband's range would be negative, the center will be moved to the lowest value that would not force this subband to contain negative frequencies. This value is equal to one half the bandwidth. Likewise, if this subband belongs to a baseband, this method will not move the center frequency such that any part of this subband extends beyond the high end of its baseband.

Parameters:

newCenter - the central frequency of this subband.

getCentralFrequency

Frequency getCentralFrequency()

Returns the central frequency of this subband.

Returns:

the central frequency of this subband.

getMinimumCentralFrequency

Frequency getMinimumCentralFrequency()

Returns the smallest allowable central frequency for this subband. The returned value will be equal to half of this subband's bandwidth.

Returns:

the smallest allowable central frequency for this subband.

getMaximumCentralFrequency

Frequency getMaximumCentralFrequency()

Returns the largest allowable central frequency for this subband. If this subband belongs to no baseband, the returned value is infinite. Otherwise it is equal to the bandwidth of the baseband less one half the bandwidth of this subband.

Returns:

the largest allowable central frequency for this subband.

getFrequencyRange

FrequencyRange getFrequencyRange()

Returns the frequency range covered by this subband.

Returns:

the frequency range covered by this subband.

getProxiedRange

FrequencyRange getProxiedRange()

Returns the portion of frequency space for which this subband is a proxy. If this subband belongs to no baseband, then the range returned is the same as the range returned by getFrequencyRange(). If, on the other hand, this subband belongs to a baseband, the range returned will follow this example:

   Let the baseband go from 0.0GHz to 2.0GHz.
   Let the above range represent sky frequencies from 41.5GHz to 43.5GHz.
   If this subband has a range from 0.4GHz to 1.1GHz, the range returned
   by this method will be 41.9GHz to 42.6GHz.
 

Returns:

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

setCentralProxiedFrequency

void setCentralProxiedFrequency(Frequency newSkyCenter)

Modifies this subband so that its new center is a proxy for newSkyCenter. This subband may need to move its center in such a way that it no longer proxies newSkyCenter. This would be true if the calculated center frequency is outside of the bounds of this subband's baseband, or if there are certain restrictions for the placement of a subband within it baseband. Concrete implementations are expected to get the actual center as close as possible to the value that represents newSkyCenter.

Parameters:

newSkyCenter - the new center sky, or proxied, frequency for this subband.

getAllowableRequantizations

SortedSet<Integer> getAllowableRequantizations()

Returns the set of allowable requantization values for this subband.

Returns:

the set of allowable requantization values for this subband.

setRequantization

void setRequantization(int bits)

Sets the number of bits to which data should be requantized.

This subband allows only certain values for the number of bits. These values are given by getAllowableRequantizations(). If a disallowed value is sent to this method, it will be replaced by the nearest acceptable value. If it is equally near two acceptable values, the smaller one will be used.

Parameters:

bits - the number of bits to which data should be requantized.

getRequantization

int getRequantization()

Returns the number of bits to which the data in this subband will be requantized.

Returns:

the number of bits to which the data in this subband will be requantized.

See Also:

CorrelatorBaseband.getInitialQuantization()

getCorrelationProductGroups

List<CorrelationProductGroup> getCorrelationProductGroups()

Returns this subband's collection of correlation product groups.

Returns:

this subband's collection of correlation product groups.

addNewCorrelationProductGroup

CorrelationProductGroup addNewCorrelationProductGroup()

Creates a new correlation product group, adds it to this subband, and returns it.

Returns:

a new correlation product group of this subband.

removeCorrelationProductGroup

void removeCorrelationProductGroup(CorrelationProductGroup unwantedGroup)

Removes a correlation product group from this subband.

Parameters:

unwantedGroup - a correlation product group to be removed from this subband.

getBaseband

CorrelatorBaseband getBaseband()

Returns the baseband to which this subband belongs.

Some implementations may allow for the creation of subbands apart from any baseband, with the idea that this subband would eventually be added to a baseband. Prior to being added to a baseband the return value from this method would be null.

Returns:

the baseband to which this subband belongs, or null if it belongs to no baseband.