name: AlgorithmData

synopsis:

g++ [flags ...] file ... -l /isip/tools/lib/$ISIP_BINARY/lib_algo.a

#include <AlgorithmData.h>

AlgorithmData();
const VectorFloat& getVectorFloat() const;
const MatrixFloat& getMatrixFloat() const;
VectorFloat& makeVectorFloat();
MatrixFloat& makeMatrixFloat();

quick start:

AlgorithmData algd_1;
AlgorithmData algd_2;
algd_1.setDataType(AlgorithmData::VECTOR_FLOAT);
algd_1.setCoefType(AlgorithmData::GENERIC);
algd_1.assign(algd_2);

description:

The AlgorithmData class is simply a container class for data passed by the algorithm classes in this library. This is the lowest-level class in the algorithm library and is used to encapsulate the different data formats one can pass to algorithms. Programmers typically do not interact with AlgorithmData directly.

There are two important abstractions handled by this class: data type and coefficient type. These are represented by DATA_TYPE and COEF_TYPE respectively. Data_type controls the precision of the data structure used in computations. For example, a data type of VECTOR_FLOAT implies a result of a calculation will be generated as a vector of floats (typically, 32-bit floating point numbers). Most robust algorithms can operate safely within a 32-bit float, though some, such as matrix inversion, can occasionally require more precision.

The second abstraction, coefficient type, is a little more subtle. Many algorithms, such as a Fourier Transform, operate on any type of vector data in the same way. However, more complex operations, such as computing the spectrum from a linear predictive model, requires a series of more complicated operations. Further, the specific algorithm to perform these computations depends on the type of the representation (e.g., autocorrelation vs. reflection coefficients vs. predictor coefficients). COEF_TYPE is an enumeration that encapsulates all classes in the Algorithm library that require special consideration when performing such operations. For example, PREDICTION and REFLECTION are used to identify the corresponding type of linear prediction coefficients.

There are several special types: GENERIC, PROPAGATE, SIGNAL, and SPECTRUM. GENERIC are used to tell an algorithm that it can ignore the type of the input. PROPAGATE is used to allow the output type to be automatically set to the input type, no matter what the input is. This is an important functionality needed by isip_transform_builder and isip_transform. SIGNAL is used to denote a sampled data signal - it encapsulates things such as vectors and cepstra. SPECTRUM, similarly, is used to represent a frequency domain representation of a SIGNAL or comparable quantity.

These abstractions exist mainly because they are needed to implement our graph-oriented signal processing tool - isip_transform_builder. This is a data-driven tool in which users implement signal processing systems by drawing block diagrams. In such a system, one needs to have some notion of the type of data that is being generated at each step. We use DATA_TYPE and COEF_TYPE for this purpose.

dependencies:

public constants:

define the class name:

static const String CLASS_NAME = L"AlgorithmData";

define the enumeration for data type:

enum DATA_TYPE { NONE = 0, VECTOR_FLOAT, VECTOR_COMPLEX_FLOAT, MATRIX_FLOAT, MATRIX_COMPLEX_FLOAT, VECTOR_DOUBLE, VECTOR_COMPLEX_DOUBLE, MATRIX_DOUBLE, MATRIX_COMPLEX_DOUBLE, COMBINATION, DEF_DTYPE = NONE };

define the enumeration for coefficient type:

enum COEF_TYPE { GENERIC = 0, PROPAGATE, SIGNAL, SPECTRUM, CORRELATION, COVARIANCE, ENERGY, FILTER, LOG_AREA_RATIO, PREDICTION, REFLECTION, CORRELATION_INTEGRAL, MUTUAL_INFORMATION, CORRELATION_ENTROPY, CORRELATION_DIMENSION, DEF_CTYPE = GENERIC };

define static NameMap objects:

static const NameMap DTYPE_MAP = L"NONE, VECTOR_FLOAT, VECTOR_COMPLEX_FLOAT, MATRIX_FLOAT, MATRIX_COMPLEX_FLOAT, VECTOR_DOUBLE, VECTOR_COMPLEX_DOUBLE, MATRIX_DOUBLE, MATRIX_COMPLEX_DOUBLE, COMBINATION";

static const NameMap CTYPE_MAP = L"GENERIC, PROPAGATE, SIGNAL, SPECTRUM, CORRELATION, COVARIANCE, FILTER, LOG_AREA_RATIO, PREDICTION, REFLECTION, CORRELATION_INTEGRAL, MUTUAL_INFORMATION, CORRELATION_ENTROPY, CORRELATION_DIMENSION";

define i/o related constants:
```
static const String DEF_PARAM = L"";
```

error codes:

error codes indicating a general error:

static const long ERR = 50300;

static const long ERR_TYPE = 50301;

protected data:

define the type of the data (vector, matrix, etc.):

DATA_TYPE data_type_d;

define the type of coefficient:

COEF_TYPE coef_type_d;

a pointer to the data itself:

void* data_d;

define a debug level:
```
static DebugLevel debug_level_d;
```
define the memory manager:
```
static MemoryManager mgr_d;
```

required public methods:

static methods:

static const String& name();

static boolean diagnose(Integral::DEBUG debug_level);

debug methods

boolean debug(const unichar* message) const;

destructor/constructor(s):

~AlgorithmData();

AlgorithmData();

AlgorithmData(const AlgorithmData& arg);

assign methods:

boolean assign(const AlgorithmData& arg);

operator= methods:

AlgorithmData& operator= (const AlgorithmData& arg);

i/o methods:

long sofSize() const;

boolean read(Sof& sof, long tag, const String& name = CLASS_NAME);

boolean write(Sof& sof, long tag, const String& name = CLASS_NAME) const;

boolean readData(Sof& sof, const String& pname = DEF_PARAM, long size = SofParser::FULL_OBJECT, boolean param = true, boolean nested = false);

boolean writeData(Sof& sof, const String& pname = DEF_PARAM) const;

equality methods:

boolean eq(const AlgorithmData& arg) const;

memory management methods:

static void* operator new(size_t size);

static void* operator new[](size_t size);

static void operator delete(void* ptr);

static void operator delete[](void* ptr);

static boolean setGrowSize(long grow_size);

boolean clear(Integral::CMODE ctype = Integral::DEF_CMODE);

class-specific public methods:

set methods:

boolean setDataType(DATA_TYPE dtype);

boolean setCoefType(COEF_TYPE ctype);

get methods:

DATA_TYPE getDataType() const;

COEF_TYPE getCoefType() const;

const VectorFloat& getVectorFloat() const;

VectorFloat& getVectorFloat();

const VectorComplexFloat& getVectorComplexFloat() const;

VectorComplexFloat& getVectorComplexFloat();

const MatrixFloat& getMatrixFloat() const;

MatrixFloat& getMatrixFloat();

const MatrixComplexFloat& getMatrixComplexFloat() const;

MatrixComplexFloat& getMatrixComplexFloat();

const VectorDouble& getVectorDouble() const;

VectorDouble& getVectorDouble();

const VectorComplexDouble& getVectorComplexDouble() const;

VectorComplexDouble& getVectorComplexDouble();

const MatrixDouble& getMatrixDouble() const;

MatrixDouble& getMatrixDouble();

const MatrixComplexDouble& getMatrixComplexDouble() const;

MatrixComplexDouble& getMatrixComplexDouble();

const Vector<AlgorithmData>& getCombination() const;

Vector<AlgorithmData>& getCombination();

make methods:

boolean make(const AlgorithmData& arg);

VectorFloat& makeVectorFloat();

VectorComplexFloat& makeVectorComplexFloat();

MatrixFloat& makeMatrixFloat();

MatrixComplexFloat& makeMatrixComplexFloat();

VectorDouble& makeVectorDouble();

VectorComplexDouble& makeVectorComplexDouble();

MatrixDouble& makeMatrixDouble();

MatrixComplexDouble& makeMatrixComplexDouble();

Vector<AlgorithmData>& makeCombination();

swap methods:
```
boolean swap(AlgorithmData& arg);
```

AlgorithmData interface contract methods:

This class does not need to support the interface contract.

private methods:

none.

examples:

This example shows how to use makeVectorFloat and getVectorFloat methods

// isip include files
//
#include <AlgorithmData.h>

// main program starts here
//
int main() {

  // define an AlgorithmData object
  //
  AlgorithmData foo;

  // test setDataType
  //
  foo.setDataType(AlgorithmData::VECTOR_FLOAT);

  // test makeVectorFloat and getVectorFloat
  //
  foo.makeVectorFloat().assign(L"1,2,3");
  foo.getVectorFloat().debug(L"VectorFloat");

  foo.debug(L"foo");

  // exit gracefully
  //
  Integral::exit();
}

notes:

This class is mainly used to move data from files, streams, etc., to/from the Algorithm classes. It is not used independently as a general class.