name: Generator : public AlgorithmBase
synopsis:

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

>     #include <Generator.h>

>     Generator(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);
>     Generator(const Generator& arg);
>     boolean assign(const Generator& arg);
>     boolean setAlgorithm(ALGORITHM type);

quick start:

>     Generator gen;
>     VectorFloat input;
>     VectorFloat output;
>     gen.compute(output, input);

description:
The Generator class is used to produce various types of signal. The following signals are currently supported: Sine, Pulse Train, Triangle, Gaussian Noise, Square and time series from Lorentz and Rossler systems.
Many DSP textbooks contain extensive discussion of the theory of signals. A good on-line reference on the theory of signals in speech recognition is:

Rodger E. Ziemer, William H. Tranter and D. Ronald Fannin, "Signals & Systems: Continuous and Discrete", Prentice Hall, 1998.

The mathematical descriptions of the signals supported in this class are described below for reference purposes. For each signal type, the design parameters have a different meaning. The correspondence between design parameters and the signal type is included in the description below.
dependencies:

- AlgorithmBase
- Float
- Long
- Vector
- String
- NameMap

public constants:

- define the class name:

      static const String CLASS_NAME = L"Generator";

- define algorithm choices:

      enum ALGORITHM { SINE = 0, PULSE, TRIANGLE, GAUSSIAN, SQUARE, LORENTZ, ROSSLER,  DEF_ALGORITHM = SINE };

- define the implementation choices:

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

- define phase mode choices:

      enum PHMODE { DETERMINISTIC = 0, RANDOM, DEF_PHMODE = DETERMINISTIC };

- define the static NameMap objects

      static const NameMap ALGO_MAP(L"SINE, PULSE, TRIANGLE, GAUSSIAN, SQUARE, LORENTZ, ROSSLER");

      static const NameMap IMPL_MAP(L"FUNCTION");

      static const NameMap PHMODE_MAP(L"DETERMINISTIC, RANDOM");

- define i/o related variables:

      static const String DEF_PARAM = L"";

      static const String PARAM_ALGORITHM = L"algorithm";

      static const String PARAM_IMPLEMENTATION = L"implementation";

      static const String PARAM_PHMODE = L"phase_mode";

      static const String PARAM_SAMPLE_FREQUENCY = L"sample_frequency";

      static const String PARAM_FRAME_DURATION = L"frame_duration";

      static const String PARAM_TIME = L"time";

      static const String PARAM_ACCUM_FRAME = L"accum_frame";

      static const String PARAM_CHANNELS = L"channels";

      static const String PARAM_FREQUENCY = L"frequency";

      static const String PARAM_AMPLITUDE = L"amplitude";

      static const String PARAM_MEAN = L"mean";

      static const String PARAM_VARIANCE = L"variance";

      static const String PARAM_DUTY_CYCLE = L"duty_cycle";

      static const String PARAM_PHASE = L"phase";

      static const String PARAM_MODE = L"mode";

      static const String PARAM_BIAS = L"DC";

      static const String PARAM_BIAS = L"seed";

      static const String PARAM_GEN_SAMPLE_FREQUENCY = L"gen_sample_frequency";

      static const String PARAM_CHAOS_A = L"gen_chaos_a";

      static const String PARAM_CHAOS_B = L"gen_chaos_b";

      static const String PARAM_CHAOS_C = L"gen_chaos_c";

      static const String PARAM_CHAOS_X0 = L"gen_chaos_x0";

      static const String PARAM_CHAOS_Y0 = L"gen_chaos_y0";

      static const String PARAM_CHAOS_Z0 = L"gen_chaos_z0";

      static const String PARAM_CHAOS_integrate_upsample = L"gen_chaos_integrate_upsample";

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

      static const double DEF_SAMPLE_FREQUENCY = 8000;

      static const double DEF_FRAME_DURATION = 0.01;

      static const llong  DEF_TIME = (llong)0;

      static const llong  DEF_ACCUM_FRAME = (llong)0;

      static const long   DEF_CHANNELS = (long)1;

      static const float  DEF_AMPLITUDE = 1.0;

      static const float  DEF_FREQUENCY = 100;

      static const float  DEF_MEAN = 0.0;

      static const float  DEF_VARIANCE = 1.0;

      static const float  DEF_DUTY_CYCLE = 50.0;

      static const float  DEF_PHASE = 0.0;

      static const llong  DEF_BIAS = 0.0;

      static const llong  DEF_SEED = 27;

      static const float DEF_CHAOS_A = 16;

      static const float DEF_CHAOS_B = 40;

      static const float DEF_CHAOS_C = 6;

      static const float DEF_CHAOS_X0 = 0.5;

      static const float DEF_CHAOS_Y0 = 0.5;

      static const float DEF_CHAOS_Z0 = 0.5;

      static const long DEF_CHAOS_INTEGRATE_UPSAMPLE = 1;

- default arguments to methods:

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

error codes:

- error code indicating Generator class general error:

      static const long ERR = 70900;

      static const long ERR_ALGO = 70901;

      static const long ERR_DTYPE = 70902;

      static const long ERR_ZFREQ = 70903;

      static const long ERR_FREQ = 70904;

      static const long ERR_INTEGRATE = 70905;

protected data:

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

        ALGORITHM algorithm_d;

  - implementation name:

        IMPLEMENTATION implementation_d;

  - phase mode name:

        PHMODE phase_mode_d;

  - frequency:

        Float frequency_d;

  - amplitude:

        Float amplitude_d;

  - phase:

        Float phase_d;

  - mean:

        Float mean_d;

  - variance:

        Float variance_d;

  - duty cycle:

        Float duty_cycle_d;

  - number of input channels:

        Long channels_d;

  - number of frame generated:

        Vector<Llong> accum_frame_d;

  - DC of the signal:

        Float bias_d;

  - random number seed:

        Long seed_d;

  - chaotic system parameter:

         float chaos_a_d;

  - chaotic system parameter:

         float chaos_b_d;

  - chaotic system parameter:

         float chaos_c_d;

  - chaotic system parameter:

         float chaos_x0_d;

  - chaotic system parameter:

         float chaos_y0_d;

  - chaotic system parameter:

         float chaos_z0_d;

  - chaotic system parameter:

         long chaos_integrate_upsample_d;

  - define parameters that are specific for this class

         Float gen_sample_freq_d;

  - static memory manager:

        static MemoryManager mgr_d;

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

      ~Generator();

      Generator(ALGORITHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);

      Generator(const Generator& arg);

- assign methods:

      boolean assign(const Generator& arg);

- operator= methods:

      Generator& operator= (const Generator& 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 Generator& 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();

class-specific public methods:

- set methods:

      boolean setAlgorithm(ALGORITHM algorithm);

      boolean setImplementation(IMPLEMENTATION implementation);

      boolean set(ALGoRIHM algorithm = DEF_ALGORITHM, IMPLEMENTATION implementation = DEF_IMPLEMENTATION);

      boolean setPhaseMode(PHMODE phase_mode);

      boolean setAccumFrame(Vector<Llong> &accum_frame);

      boolean setChannel(long channels);

      boolean setFrequency(Float frequency);

      boolean setGenSampleFrequency(Float sf);

      boolean setAmplitude(Float amplitude);

      boolean setMean(Float mean);

      boolean setVariance(Float mean);

      boolean setDutyCycle(Float duty_cycle);

      boolean setPhase(Float phase);

      boolean setBias(Float bias);

      boolean setSeed(Float bias);

      boolean setSine(Float frequency, Float amplitude, Float phase, Float bias);

      boolean setGaussian(Float mean, Float variance);

      boolean setPulse(Float frequency, Float amplitude, Float phase, Float duty_cycle, Float bias);

      boolean setSquare(Float frequency, Float amplitude, Float phase, Float duty_cycle, Float bias);

      boolean setTriangle(Float frequency, Float amplitude, Float phase, Float duty_cycle, Float bias);

      boolean setChaosParams(float chaos_a, float chaos_b, float chaos_c);

      boolean setChaosInitialValues(float chaos_x0, float chaos_y0, float chaos_z0);

      boolean setIntegrateUpsample(long chaos_integrate_upsample);

      boolean setLorentz(float chaos_a, float chaos_b, float chaos_c,float chaos_x0, float chaos_y0, float chaos_z0, long chaos_integrate_upsample);

      boolean setRossler(float chaos_a, float chaos_b, float chaos_c,float chaos_x0, float chaos_y0, float chaos_z0, long chaos_integrate_upsample);

- get methods:

      ALGORITHM getAlgorithm() const;

      IMPLEMENTATION getImplementation() const;

      boolean get(Algorithm& algorithm, IMPLEMENTATION& implementation) const;

      PHMODE getPhaseMode() const;

      llong getAccumFrame() const;

      long getChannel() const;

      double getSampleFrequency() const;

      double getFrameDuration() const;

      Float getFrequency() const;

      Float getAmplitude() const;

      Float getMean() const;

      Float getVariance() const;

      Float getDutyCycle() const;

      Float getPhase() const;

      Float getBias() const;

      Float getSeed() const;

      Float getChaosA() const;

      Float getChaosB() const;

      Float getChaosC() const;

      Float getChaosX0() const;

      Float getChaosX0() const;

      Float getChaosY0() const;

      Float getChaosZ0() const;

      Long getChaosIntegrationUpsample() const;

      Float getGenSampleFrequency(Float& freq) const;

- computation methods:

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

- AlgorithmBase interface contract methods:

      boolean assign(const AlgorithmBase& arg);

      boolean eq(const AlgorithmBase& arg) const;

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

      const String& className() const;

      boolean init();

      boolean setSampleFrequency(double sf);

      boolean setFrameDuration(double fd);

      boolean setParser(SofParser* parser);

private methods:

- specific computational methods:

      boolean computeSine(VectorFloat& sine_wave, long channel_index);

      boolean computeGaussianNoise(VectorFloat& gaussian_noise, long channel_index);

      boolean computeSquare(VectorFloat& square_wave, long channel_index);

      boolean computePulse(VectorFloat& pulse_wave, long channel_index);

      boolean computeTriangle(VectorFloat& triangle_wave, long channel_index);

      boolean computeLorentz(VectorFloat& lorentz, long channel_index);

      boolean computeRossler(VectorFloat& rossler, long channel_index);

examples:

- This example shows how to generate sine signal:

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

      // main program starts here
      //
      int main(int argc, const char **argv) {

        // declare a generator
        //
        Generator gen;

        // set signal type to be sine
        //
        gen.setAlgorithm(Generator::SINE);

        // set sample frequency
        //
        gen.setSampleFrequency(40);

        // set frame duration
        //
        gen.setFrameDuration(1);

        // set amplitude
        //
        gen.setAmplitude(1);

        // set frequency
        //
        gen.setFrequency(4);

        // create a pseudo input vector
        //
        VectorFloat input;

        // compute the signal output
        //
        VectorFloat output;
        gen.compute(output, input);

        // print the input, the output and the generator object to the console
        //
        input.debug(L"input:");
        gen.debug(L"generator:");
        output.debug(L"output:");

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

- This example shows how to generate gaussian noise:

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

      // main program starts here
      //
      int main(int argc, const char **argv) {

        // declare a generator
        //
        Generator gen;

        // set signal type to be gaussian
        //
        gen.setAlgorithm(Generator::GAUSSIAN);

        // set the mean and the variance of the gaussian noise
        //
        gen.setMean(1.5);
        gen.setVariance(-0.5);

        // seed the random number generator
        //
        gen.setSeed(80);

        // set other parameters
        //
        gen.setSampleFrequency(40);
        gen.setFrameDuration(1);
        gen.setSignalDuration(1);

        // create a pseudo input vector
        //
        VectorFloat input;

        // compute the signal output
        //
        VectorFloat output;
        gen.compute(output, input);

        // print the input, the output and the generator object to the console
        //
        input.debug(L"input:");
        gen.debug(L"generator:");
        output.debug(L"output:");

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

- This example shows how to generate a Lorentz time series:

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

      int main() {

        VectorFloat test_generation, dummy;

        // declare a generator
        //
        Generator gen1;

        // Set the type and parameters for the Lorentz system
        //
        gen1.set(Generator::LORENTZ);
        gen1.setSampleFrequency((float)100);
        gen1.setGenSampleFrequency((float)100);
        gen1.setSignalDuration(1);
        gen1.setFrameDuration(1);
        gen1.setLorentz((float)0.15, (float)0.2, (float)10, (float)0.5,
                        (float)0.5 , (float)0.5, (float)0.5);
        gen1.compute(test_generation, dummy);

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

      }

notes:

- None.