name: Lyapunov : public AlgorithmBase
synopsis:

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

>     #include <Lyapunov.h>

>     Lyapunov(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long num_neighbors = DEF_NUM_NEIGHBORS, long evolve_step = DEF_EVOLVE_STEP, long loc_dim = DEF_LOCAL_DIM, long num_steps = DEF_NUM_STEPS, float inner_radius = DEF_INNER_RADIUS, float outer_radius = DEF_OUTER_RADIUS, long num_neighbor_subgroups = DEF_NUM_NEIGHBOR_SUBGROUPS, long reinit_step = DEF_REINIT_STEP, long start_pos = DEF_START_POS);
>     boolean eq(const Lyapunov& arg);
>     boolean setAlgorithm(ALGORITHM algorithm);
>     boolean setNumNeighbors(long num_neighbors);

quick start:

>     Lyapunov lyapp;
>     MatrixFloat input(3, 3, L"1.0, 2.0, 4.0, 2.0, 4.0, 8.0, 4.0, 8.0, 16.0");
>     VectorFloat output;
>     lyap.set(Lyapunov::LINEAR_TANGENT_MAP, Lyapunov::TREPPEN_ITERATION, 1, 1, 3, 3);
>     lyap.compute(output, input);

description:
Lyapunov exponents are a set of invariants for a dynamical system and signifies how chaotic an attractor is. The method of estimating the Lyapunov spectra used here is treppen-iteration (iterative QR) of tangent maps and is explained in :

Michael Banbrook, Nonlinear analysis of speech from a synthesis perspective, PhD thesis, The University of Edinburgh, 1996.

dependencies:

- AlgorithmBase
- Rps

public constants:

- define the class name:

      static const String CLASS_NAME = L"Lyapunov";

- define algorithm types:

      enum ALGORITHM { LINEAR_TANGENT_MAP = 0, DEF_ALGORITHM = LINEAR_TANGENT_MAP };

- define implementation types:

      enum IMPLEMENTATION { TREPPEN_ITERATION = 0, DEF_IMPLEMENTATION = TREPPEN_ITERATION };

- define static NameMap objects:

      static const NameMap ALGO_MAP = L"LINEAR_TANGENT_MAP";

      static const NameMap IMPL_MAP = L"TREPPEN_ITERATION";

- 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_NUM_NEIGHBORS = L"num_neighbors";

      static const String PARAM_EVOLVE_STEP = L"evolve_step";

      static const String PARAM_LOCAL_DIM = L"local_dim";

      static const String PARAM_NUM_STEPS = L"num_steps";

      static const String PARAM_INNER_RADIUS = L"inner_radius";

      static const String PARAM_OUTER_RADIUS = L"outer_radius";

      static const String PARAM_NUM_NEIGHBOR_SUBGROUPS = L"num_neighbor_subgroups";

      static const String PARAM_REINIT_STEP = L"reinit_step";

      static const String PARAM_START_POS = L"start_pos";

- define default value(s) of the class data:

      static const long DEF_NUM_NEIGHBORS = -1;

      static const long DEF_EVOLVE_STEP = -1;

      static const long DEF_LOCAL_DIM = -1;

      static const long DEF_NUM_STEPS = 1000;

      static const float DEF_INNER_RADIUS = 0.0;

      static const float DEF_OUTER_RADIUS = -1.0;

      static const long DEF_NUM_NEIGHBOR_SUBGROUPS = -1;

      static const long DEF_REINIT_STEP = -1;

      static const long DEF_START_POS = 1;

- define default argument(s):

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

error codes:

- error code indicating Lyapunov class general error:

      static const long ERR = 73500;

      static const long ERR_SUBGRPS = 73501;

      static const long ERR_NGH = 73502;

      static const long ERR_DIM = 73503;

protected data:

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

        ALGORITHM algorithm_d;

  - define an implementation name:

        IMPLEMENTATION implementation_d;

  - define number of neighbors

        Long num_neighbors_d;

  - define evolve step

        Long evolve_step_d;

  - define the local embedding dimension

        Long local_dim_d;

  - define number of points to evolve

        Long num_points_d;

  - define the minimum radius for nearest neighbors

        Float inner_radius_d;

  - define the maximum radius for nearest neighbors (not used now)

        Float outer_radius_d;

  - define the number of subgroups of neighbors

        Float num_neighbor_subgroups_d;

  - define reinitialization step for LE recalculation

        Long reinit_step_d;

  - define starting point in trajectory

        Long start_pos_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):

      ~Lyapunov();

      Lyapunov(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long num_neighbors = DEF_NUM_NEIGHBORS, long evolve_step = DEF_EVOLVE_STEP, long local_dim = DEF_LOCAL_DIM, long num_steps = DEF_NUM_STEPS, float inner_radius = DEF_INNER_RADIUS, float outer_radius = DEF_OUTER_RADIUS, long num_neighbor_subgroups = DEF_NUM_NEIGHBOR_SUBGROUPS, long reinit_step = DEF_REINIT_STEP, long start_pos = DEF_START_POS);

      Lyapunov(const Lyapunov& arg);

- assign methods:

      boolean assign(const Lyapunov& arg);

- operator= methods:

      Lyapunov& operator= (const Lyapunov& 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 Lyapunov& 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 setNumNeighbors(long num_neighbors);

      boolean setEvolveStep(long evolve_step);

      boolean setLocalDim(long local_dim);

      boolean setNumSteps(long num_steps);

      boolean setInnerRadius(float inner_radius);

      boolean setOuterRadius(float outer_radius);

      boolean setNumNeighborSubgroups(long num_neighbor_subgroups);

      boolean setReinitStep(long reinit_step);

      boolean setStartPos(long start_pos);

      boolean set(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION, long num_neighbors = DEF_NUM_NEIGHBORS, long evolve_step = DEF_EVOLVE_STEP, long local_dim = DEF_LOCAL_DIM, long num_steps = DEF_NUM_STEPS, float inner_radius = DEF_INNER_RADIUS, float outer_radius = DEF_OUTER_RADIUS, long num_neighbor_subgroups = DEF_NUM_NEIGHBOR_SUBGROUPS, long reinit_step = DEF_REINIT_STEP, long start_pos = DEF_START_POS);

- get methods:

      boolean getAlgorithm(ALGORITHM algorithm);

      boolean getImplementation(IMPLEMENTATION implementation);

      long getNumNeighbors();

      long getEvolveStep();

      long getLocalDim();

      boolean getNumSteps(Long num_steps);

      float getInnerRadius();

      float getOuterRadius();

      long getNumNeighborSubgroups();

      long getReinitStep();

      long getStartPos();

      boolean get(ALGORITHM& algorithm, IMPLEMENTATION& implementation, long& num_neighbors, long& evolve_step, long& local_dim, long& num_steps, float& inner_radius, float& outer_radius, long& num_neighbor_subgroups, long& reinit_step, long& start_pos);

- computational methods:

      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);

- AlgorithmBase interface contract methods:

      boolean assign(const AlgorithmBase& arg);

      boolean eq(const AlgorithmBase& arg) const;

      const String& className() const;

      boolean init();

      boolean apply(Vector<AlgorithmData>& output, const Vector< CircularBuffer<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 and implementation specific computational methods:

      boolean computeLyapunovLinearTangentMapMethod(VectorFloat& output, const MatrixFloat& rps_input);

examples:

- This example shows how to compute the Lyapunov spectra:

      Lyapunov lyap_block(Lyapunov::DEF_ALGORITHM, Lyapunov::DEF_IMPLEMENTATION, (1, 1, 3, 3);
      lyap_block.setSampleFrequency(100.00);

      MatrixFloat rps_matrix(3 , 3, L"1.0, 2.0, 4.0, 2.0, 4.0, 8.0, 4.0, 8.0, 16.0");

      VectorFloat lyap_coef;
      lyap_block.compute(lyap_coef, rps_matrix);

notes:

- The sample frequency should be set before compute or apply since the Lyapunov spectra estimates are normalized using it.