//
//                        INTEL CORPORATION PROPRIETARY INFORMATION
//        This software is supplied under the terms of the license agreement
//        or nondisclosure agreement with Intel Corporation and may not be copied
//        or disclosed except in accordance with the terms of that agreement.
//            Copyright (c) 1999-2006 Intel Corporation. All Rights Reserved.
//
//


        Simple program to illustrate vector Gaussian mixture
        calculation and feature vectors processing
        Float means, variances, features and probabilities


        gauss_main.cpp file

The main program contains several calls of Fake_Decoder_Test function with different
arguments. Probabilities and features calculated while running the test could be
logged (last two arguments).


        Fake_Decoder class

Imitates time-synchronous tree decoder requests for state likelihoods (log
probabilities). Each state corresponds to a Gaussian mixtue. Active states and the
length of state activity interval are chosen randomly. Required active states number
is defined for each frame. State activity interval length is uniformly distributed in
[1,max_live]. Probability of the active state is requested for the current frame once
per frame only. The real decoder could request the same probability several times per
frame and could request probabilities for some following frames if acoustic look-ahead
is used.

Fake_Decoder(int state_number, int max_live)
                                     - constructor
~Fake_Decoder(void)                  - destructor
int Init_Decoder(void)               - internal structures initialization
                                       >= 0 if OK, otherwise failed
bool Attach_Cache(Prob_Cache *cache) - attach ready-to-use probability cache
                                       cache state number should not be less
                                       than decoder state number
                                       true if OK, otherwise failed
int Init_LogFile(char *prob_log)     - opens log file for probabilities
                                       each probability used by decoder
                                       is written to this file as float value
                                       file is closed in
                                       this feature is useful to compare
                                       different modes of probability calculation
                                       >= 0 if OK, otherwise failed

After successful constructor, Init_Decoder and Attach_Cache calls decoder is ready

bool Ready(void)                     - true if decoder is ready, false otherwise
bool Decode_Frame(int act_num)       - process frame with act_num active states
                                       real number of active states could differ
                                       from requested (eg if it was more for
                                       previous frame and no activity intervals
                                       is finished)
                                       true if the frame is not last one
void Close_Decoder(void)             - stop decoder and fix statistics
void Get_Statistics(Len_Stat *stat)  - extract statistics data: all requests,
                                       repeated requests (0 now), number of
                                       state activity intervals of length [1,256]

int Get_Probability(int state, float *prob) -
                                       request for state probability for current
                                       frame passed to cache and statistics collected
                                       if probability is accessible 0 is returned and
                                       it is written to prob[0]
                                       if probability is not accessible 1 is returned

int Use_Probability(int state, float *prob) -
                                       use of calculated probability (imitation of
                                       calculated probability use in decoder)
                                       0 is returned

int Activity_Interval(int max_len)   - random length of state activity interval




        Prob_Cache class

Simplified SDT probability cache class. Supplies probabilities for the current frame.
If the value is not in cache up to vec_length values are requested from probability
calculator. Cache has size state_number*vec_length and crawls forward one element per
frame. After frame_num frames it is moved to the beginning.

Prob_Cache(int state_number, int vec_length, int frame_num)
                                     - constructor
~Prob_Cache(void)                    - destructor
int Init_Cache(void)                 - internal structures initialization
                                       >= 0 if OK, otherwise failed
bool Attach_Calc(Prob_Calc *calc)    - attach ready-to-use probability calculator
                                       cache state number should not be less
                                       than calculator state number
                                       true if OK, otherwise failed

After successful constructor, Init_Cache and Attach_Calc calls cache is ready

bool Ready(void)                     - true if cache is ready, false otherwise
bool Step_Forward(void)              - step to the next frame, values for the
                                       previous frame are lost
                                       true if the next frame exists
void Detach_Calc(void)               - detach probability calculator
                                       after successful Attach_Calc cache could
                                       work with other calculator
void Get_Statistics(Len_Stat *stat)  - extract statistics data: unused values,
                                       calculated vectors of length [1,vec_length]

float Get_Probability(int state)     - request for state probability for current frame
int State_Number(void)               - get state number in cache (state_number)




        Prob_Calc class

Calculates the vector of Gaussian mixture probabilities. The model consists of
state_number states. Each state corresponds to Gaussian mixture with max_gauss or
less components. Weight, determinant, mean and var values are situated in separate
vectors in the same order. Mean and var vectors are aligned to 16 byte boundary.
Mixture parameters are read from the parameter file or fake calculator is created
(max_gauss components in all mixtures, zero means, identity vars, equal weights,
space_dim dets).

Prob_Calc (Calc_Hint hint)           - constructor
                                       hint - method of calculations
                                       calcVect - vector (LogGauss+LogAdd)
                                       calcVecM - vector (LogGauss+Max)
                                       calcMix  - mixture (LogGaussMixture)
                                       calcNone - access to data only
~Prob_Calc(void)                     - destructor
int Init_Calc(int state_number, int max_gauss, int space_dim, int max_len, int min_len)
int Init_Calc(char* file, int max_len, int min_len)
                                     - internal structures initialization for fake
                                       and file based probability calculator
                                       Mixture parameter file structure is
                                       described in feat_calc.cpp file
                                       Buffer for max_len features is reserved
                                       Vectors of lengt [min_len,max_len] are
                                       calculated (shorter at the utterance end)
                                       >= 0 if OK, otherwise failed
bool Attach_Feat(Feat_Calc *feat)    - attach ready-to-use feature producer
                                       feature vector length should be the same as
                                       for calculator
                                       true if OK, otherwise failed
int Init_LogFile(char *feat_log)     - opens log file for features
                                       feature vectors really used by probability
                                       calculator are written as HTK feature file
                                       file is closed in desctuctor or while
                                       feature producer detachment
                                       >= 0 if OK, otherwise failed

After successful constructor, Init_Calc and Attach_Feat calls cache is ready

bool Ready(void)                     - true if calculator is ready, false otherwise
bool Step_Forward(void)              - step to the next frame
                                       true if the next frame exists
void Detach_Feat(void)               - detach feature producer
                                       after successful Attach_Feat calculator could
                                       work with other producer

int Obv_Prob_Vec(int state, float *result, int len)
                                     - calculate len probabilities from current
                                       frame that are placed to result
                                       less than len values could be calculated if
                                       there are less than len features in the buffer
                                       ot at the end of utterance
                                       features are requested from feature producer
                                       if less than min_len features are in buffer
                                       calculator requests and takes into account
                                       number of partially calculated features due
                                       to delta calculation
                                       number of calculated probabilities is returned
                                       or -1 for wrong arguments
int State_Number(void)               - get state number in calculator (state_number)
int Max_Gauss(void)                  - get maximal Gaussians in mixture (max_gauss)
int Feature_Length(void)             - get feature vector length in calculator
float *Mean(int state)               - get pointer to first element of first mean of state
float *Var(int state)                - get pointer to first element of first var of state
float *Det(int state)                - get pointer to first det of state
float *Weight(int state)             - get pointer to first weight of state




        Feat_Calc class

Calculates feature vectors for probability calculator. Fake producer provides zero
feature vectors. File producer takes data from HTK feature file with float data.
Two modes of feature processing are supported: raw features without energy (as for
the first decoder pass) and CMS&VN'ed features with energy (as for the second pass).
Delta or double delta are calculated if necessary.

Feat_Calc (int space_dim, int max_delay) - constructor
                                       Each feature vector of length space_dim is
                                       appended to the length (space_dim+3)&(~3)
                                       for 16 byte alignment
                                       max_delay is used to imitate low delay
                                       feature producer - features are calculated by
                                       portions of length no more than max_delay.
                                       If deltas are calculated delta_delay =
                                       delta_window*(delta_number+1) is added.
                                       delta_delay is 0 for fake feature producer
                                       If max_delay<=0 features for all utterance
                                       could be calculated at once
                                       Feature producer has no internal buffer and
                                       calculates features in consumer's buffer
~Init_Feat(void)                     - destructor
int Init_Feat(int frame_number)      - internal structures initialization for fake
int Init_Feat(char *file)              and SDT based feature producers
                                       Fake feature producer provides an utterance
                                       of frame_number frames, each frame is zero
                                       vector of length space_dim
                                       HTK file based feature producer reads raw feature
                                       vectors of length raw_dim from HTK feature file
                                       Feature vector elements assumed to be floats.
                                       space_dim should be equal to raw_dim, raw_dim*2,
                                       raw_dim*3, (raw_dim-1), (raw_dim-1)*2 or
                                       (raw_dim-1)*3. If necessary last element of
                                       raw feature is deleted and deltas or double
                                       deltas with delta_window=2 are calculated.
                                       >= 0 if OK, otherwise failed

After successful constructor and Init_Feat calls producer is ready

bool Ready(void)                     - true if producer is ready, false otherwise
int  Get_Feature(float *dst, int len, bool* end)
                                     - puts calculated featurs to consumers buffer dst
                                       len features is requested, the number of
                                       fully calculated features is returned
                                       if utterance is not ended  they are followed by
                                       delta_delay partially calculated feature vectors
                                       The first partially calculated feature vector is
                                       passed as dst for the next feature portion
                                       if the calculated portion ends the utterance
                                       end[0] is true otherwise false
int Feature_Length(void)             - get output feature vector length
int Delta_Delay(void)                - get delta_delay of feature producer
                                       Probability calculator requests this number to
                                       provide correct interaction with probability
int Write_LogHeader(FILE *flog)      - writes HTK feature file header to log file
                                       feature vector length includes deltas or
                                       double deltas if any
                                       calculator