org.das2.qds

Interface QFunction

All Known Implementing Classes:

AbstractQFunction, DataSourceTcaSource, DemoFunction1, NearestNeighborTcaFunction, QFunctionLarry, UriTcaSource

public interface QFunction

QFunctions try to recycle as much of the QDataSet interface as possible to define functions. Functions take N parameters as input and result in M parameter output. The N parameters are passed into value as a rank 1 bundle QDataSet, or rank 0 dataset when there is just one input. The M parameter output is returned in a rank 1 bundle dataset. The method exampleInput returns an example input that allows for discovery of the function. Implementations will generally extend AbstractQFunction, which implements values() and exampleOutput(). Goals:

• support extra tick labels of axis, which are often the result of SPICE kernel evaluations.
• allow discovery of function, so the system can pick it up and use it.
• allow tabulation and plotting of a function.
• non-linear function optimization.

See Also:

Method Summary

Modifier and Type	Method and Description
QDataSet	exampleInput() Discover an example input.
QDataSet	exampleOutput() Discover an example of output.
QDataSet	value(QDataSet parm) Evaluate the function at the location.
QDataSet	values(QDataSet parm) Evaluate the function at the locations in parm.

Method Detail

value

QDataSet value(QDataSet parm)

Evaluate the function at the location. A rank 1 dataset of N parameters is passed in, and a rank 1 dataset of M parameters is returned. It's presumed that this is calculated in interactive time (1/30sec) for GUI applications like attaching ephemeris ticks to an axis (note no monitor parameter to indicate feedback).

Parameters:

parm - rank 1 bundle of N elements, or rank 2 array of such.

Returns:

rank 1 bundle of M elements, or rank 2 array of such.

values

QDataSet values(QDataSet parm)

Evaluate the function at the locations in parm. A rank 2 dataset of CxN parameters is passed in, and a rank 1 dataset of CxM parameters is returned, where C is the number of repeated value operations. This is useful for when it's expensive to look up the first value.

Parameters:

parm - rank 2 of C bundles of N elements. rank 1 parm is acceptable if the exampleInput result is rank 0.

Returns:

rank 2 of C bundles of M elements, or rank 2 array of such.

exampleInput

QDataSet exampleInput()

Discover an example input. Result is a rank 1 bundle QDataSet.

QFunction ff= TestFunction();
ff.exampleInput().length();  // how many parameters the function takes
QDataSet bds= ff.exampleInput().property( QDataSet.BUNDLE_0 );
bds.slice(0).property( QDataSet.UNITS )       // function should handle convertible units (e.g. TimeAxes Ephemeris).
bds.slice(0).property( QDataSet.VALID_MIN )   // absolute limits of domain of the function
bds.slice(0).property( QDataSet.VALID_MAX )
bds.slice(0).property( QDataSet.TYPICAL_MIN ) // domain of the function parameter
bds.slice(0).property( QDataSet.TYPICAL_MAX )
bds.slice(0).property( QDataSet.CADENCE ) // granularity of the function parameter
bds.slice(0).property( QDataSet.LABEL )   // label for the parameter

slice(0) is the first argument, slice(1) would be the second, etc. This would be a bundle. Note, for functions that have only one argument, like F(T)→[R,MLT,MLAT], this may return a rank 0 dataset. Clients should pass a dataset to the value method a dataset with the same geometry.

Returns:

rank 1 bundle of N elements, or rank 0 for functions when the function has just one parameter.

exampleOutput

QDataSet exampleOutput()

Discover an example of output. Result is a rank 1 bundle QDataSet. This was introduced to support QFunctions where it would be expensive to calculate an input that would result in a meaningful output. It's assumed that many implementations will simply be:

value( exampleInput() );

Returns:

rank 1 bundle of M elements.