name: Reflection : public AlgorithmBase
synopsis:

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

>     #include <Reflection.h>

>     Reflection(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long order = DEF_ORDER, float dyn_range = DEF_DYN_RANGE);
>     boolean eq(const Reflection& arg);
>     boolean setAlgorithm(ALGORITHM algorithm);
>     boolean set(ALGORITHM algo = DEF_ALGORITHM, IMPLEMENTATION impl = DEF_IMPLEMENTATION, long order = DEF_ORDER, float dyn_range = DEF_DYN_RANGE);

quick start:

>     Reflection refl;
>     VectorFloat in_vec(L"1.0, 2,0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0");
>     VectorFloat refl_coef;
>     refl.set(Reflection::AUTOCORRELATION, Reflection::DURBIN, 4, -40);
>     refl.compute(refl_coef, in_vec);

description:
The Reflection class is used to calculate or convert linear prediction coefficients. It is one of several classes that provide a complete inventory of linear prediction manipulations. See the prediction coefficient class Prediction.h for a more detailed explanation of linear prediction. The algorithm and implementation choices are shown below:
The step-up algorithm is defined in:

J.D. Markel and A.H. Gray, Linear Prediction of Speech, Springer-Verlag, New York, New York, USA, pp. 95, 1980.

Some of the algorithms used in reflection coefficient class compute coefficients directly (LATTICE) while others compute both reflection and prediction coefficients simultaneously (AUTOCORRELATION).
dependencies:

- AlgorithmBase
- Correlation
- Covariance
- Prediction

public constants:

- define the class name:

      static const String CLASS_NAME = L"Reflection";

- define algorithm choices:

      enum ALGORITHM { AUTOCORRELATION = 0, COVARIANCE, LATTICE, PREDICTION, LOG_AREA_RATIO, DEF_ALGORITHM = AUTOCORRELATION };

- define the implementation choices:

      enum IMPLEMENTATION { DURBIN = 0, LEROUX_GUEGUEN, CHOLESKY, BURG, STEP_UP, KELLY_LOCHBAUM, DEF_IMPLEMENTATION = DURBIN };

- define the static NameMap objects:

      static const NameMap ALGO_MAP(L"AUTOCORRELATION, COVARIANCE, LATTICE, PREDICTION, LOG_AREA_RATIO");

      static const NameMap IMPL_MAP(L"DURBIN, LEROUX_GUEGUEN, CHOLESKY, BURG, STEP_UP, KELLY_LOCHBAUM");

- define i/o related constants:

      static const String DEF_PARAM = L"";

      static const String PARAM_ALGORITHM = L"algorithm";

      static const String PARAM_IMPLEMENTATION = L"implementation";

      static const String PARAM_ORDER = L"order";

      static const String PARAM_DYN_RANGE = L"dynamic_range";

- define the default order of the fourier transform:

      static const long DEF_ORDER = (long)9;

      static const float DEF_DYN_RANGE = (float)-100;

- define default argument(s):

      static const AlgorithmData::COEF_TYPE DEF_COEF_TYPE = AlgorithmData::CORRELATION;

error codes:

- error code indicating Reflection class general error:

      static const long ERR = (long)71000;

      static const long ERR_DYNRANGE = (long)71001;

      static const long ERR_BETA = (long)71002;

      static const long ERR_ENERGY = (long)71003;

      static const long ERR_PREDERR = (long)71004;

protected data:

- data common to all algorithms and implementations:
  - define an algorithm name:

        ALGORITHM algorithm_d;

  - define an implementation name:

        IMPLEMENTATION implementation_d;

  - define a prediction order:

        Long order_d;

  - define a dynamic range threshold:

        Float dyn_range_d;

  - a static memory manager:

        static MemoryManager mgr_d;

- algorithm and implementation specific variables: none.

required public methods:

- static methods:

      static const String& name();

      static boolean diagnose(Integral::DEBUG debug_level);

- debug methods: setDebug method is inherited from base class

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~Reflection();

      Reflection(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long order = DEF_ORDER, float dyn_range = DEF_DYN_RANGE);

      Reflection(const Reflection& arg);

- assign methods:

      boolean assign(const Reflection& arg);

- operator= methods:

      Reflection& operator= (const Reflection& 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& name = DEF_PARAM) const;

- equality methods:

      boolean eq(const Reflection& 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 setAlgorithm(ALGORITHM algorithm);

      boolean setImplementation(IMPLEMENTATION implementation);

      boolean setOrder(long order);

      boolean setDynRange(float dyn_range);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long order = DEF_ORDER, float dyn_range = DEF_DYN_RANGE);

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      long getOrder() const;

      float getDynRange() const;

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, long& order, float& dyn_range) const;

- computational methods:

      boolean compute(VectorFloat& output, const VectorFloat& input, long index = DEF_CHANNEL_INDEX, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

      boolean compute(VectorFloat& output, const MatrixFloat& input, long index = DEF_CHANNEL_INDEX, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

      boolean compute(VectorFloat& output, Float& err_energy, const VectorFloat& input, long index = DEF_CHANNEL_INDEX, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

      boolean compute(VectorFloat& output, Float& err_energy, const MatrixFloat& input, long index = DEF_CHANNEL_INDEX, AlgorithmData::COEF_TYPE input_coef_type = DEF_COEF_TYPE, long index = DEF_CHANNEL_INDEX);

- AlgorithmBase interface contract methods:

      boolean assign(const AlgorithmBase& arg);

      boolean eq(const AlgorithmBase& arg) const;

      const String& className() const;

      boolean apply(Vector< CircularBuffer<AlgorithmData> >& output, const Vector<AlgorithmData>& input);

      boolean setParser(SofParser* parser);

private methods:

- algorithm-specific i/o methods:

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

      boolean writeDataCommon(Sof& sof, const String& pname);

- algorithm-specific compute methods:

      boolean computeAutoDurbin(VectorFloat& output, Float& err_energy, const VectorFloat& input);

      boolean computeAutoLeroux(VectorFloat& output, Float& err_energy, const VectorFloat& input);

      boolean computeCovarCholesky(VectorFloat& output, Float& err_energy, const MatrixFloat& input);

      boolean computeLatticeBurg(VectorFloat& output, Float& err_energy, const VectorFloat& input);

      boolean computePredictionStepUp(VectorFloat& output,, const VectorFloat& input);

      boolean computeLogAreaKellyLochbaum(VectorFloat& output, const VectorFloat& input);

examples:

- This example shows how to compute the reflection coefficients using the Burg analysis:

      Reflection refl;
      VectorFloat input;
      VectorFloat refl_coef;
      Float err_energy;

      // use the following data as input:
      //
      //  x(n) = 0 when n = 0, 1, 2, 3;
      //  x(n) = 1*pow(0.99, n-4) - pow(0.99, 2(n-4)),  when 4 <= n < 20;
      //  x(n) = 0 when n = 20, 21, 22, 23
      //
      input.setLength(24);

      float z = 1;
      for (long i = 4; i < 20; i++) {
        input(i) = 2 * z - z * z;
        z = 0.99 * z;
      }

      // set the order, algorithm, implementation and dynamic threshold
      //
      long order = 4;
      float dyn_range = -60;

      refl.set(Reflection::LATTICE, Reflection::BURG, order, dyn_range);

      // compute the reflection coefficents
      //
      refl.compute(refl_coef, err_energy, input, AlgorithmData::SIGNAL);

notes:

- none.