/**
\author Yanting Wang and V.Chandrasekar
\brief This generic module estimates KDP from PHIDP (for all radar).

This module implements an adaptive approach to estimate KDP from 
radar measured PHIDP, which can be folded due to limited unambiguous
phase interval.

This header file specifies the interface to execute KDP estimation by 
calling this module.
*/

#ifndef __DP_PHI_PROC_H_
#define __DP_PHI_PROC_H_

#ifdef __cplusplus
extern "C" {
#endif
#if 0
}
#endif

/* Forward declarations */
struct conf_par_entry;
struct dp_phi_proc_dat;

/** Default Standard(not adaptive) Smoothing Factor */
#define STD_CSS_FACTOR (0.1)

/** Default Adaptive Smoothing Factor */
#define ADA_CSS_FACTOR (1.1)

/** Default  LSQ FIR weights width [km] */
#define DEF_FIR_WIDTH   (3.0)

/** Default bin/gate size [km] */
#define DEF_BIN_SPACING (0.15)

/** Default quality criteria for the Kdp data mask */
#define BEG_RANGE_PHIDP 3.0
//#define END_BINS_REMOVAL 0
#define MIN_DISPERSION 0.91
#define MIN_RHOHV 0.75
#define MIN_SNR   15.0
#define MIN_GOOD_BINS 8 
#define MIN_BAD_BINS 10

enum phidp_cond {
    PHIDP_LSQ,    /**< Linear least square fit */
    PHIDP_SPLINES /**< Qubic splines */
};

struct dp_phi_proc_params {
    enum phidp_cond phidp_alg;
    float std_sf;      /**< Standard Smoothing Factor */
    float adp_sf;      /**< Adaptive Smoothing Factor */
    float fir_width;   /**< default LSQ FIR weights width [km] */
    float bin_space;   /**< Ray data bin/gate size [km] */

    float start_range_phidp; /**< Quality criterium for the shortest distance (km) at which PhiDP propagation may start */
    float snr_phidp;   /**< Quality criterium for minimal SNR to enter "rain", or stay in "rain" */
    float disp_phidp;  /**< Quality criterium for minimal PhiDP dispersion to enter "rain" (perfect tune=1) */
    float rhohv_phidp; /**< Quality criterium for minimal RhoHV to stay in "rain" */
    int   mgood_phidp; /**< Quality criterium for the shortest "rain" segement, in gates */
    int   mbad_phidp;  /**< Quality criterium for the longest "bad" bins allowed in "rain", in gates */
    int debug2stderr;  /**< Internal flag for debugging */
};

/** set parameters to default values */
void dp_phi_proc_init_config(struct dp_phi_proc_params * params);

/** try to apply  conf. item. If failed return 1 */
int dp_phi_proc_set_config(struct dp_phi_proc_params * params,
                           const struct conf_par_entry * conf_item);

/** try to modify conf. item. If failed return 1 */
int dp_phi_proc_get_config(const struct dp_phi_proc_params * params,
                           struct conf_par_entry * conf_item);

/** Initialize memory for the qubic spline processing of PhiDP */
struct dp_phi_proc_dat *  dp_phi_proc_init(const struct dp_phi_proc_params * params,
                                           size_t max_bin_count);

/** Release all privatly allocated objects */
void  dp_phi_proc_uninit(struct dp_phi_proc_dat * hdl);

/** Process one ray */
void  dp_phi_proc_run(const struct dp_phi_proc_params * params,
                      struct dp_phi_proc_dat * hdl,
                      float phase_amb,
                      float phidp_r0,
                      size_t bin_count,
                      const float *r,     /**< the range mask - array of per-bin ranges */
                      const int *premask, /**< the processing mask  good=1, bad=0  */
                      const float *snr,   //*< the singal-top-noise ratio */
                      const float *rhohv, /**< the co-polar correlation coefficient */
                      const float *phidp, /**< the measured differential propagation phase */
                      float *phidp_flt,   /**< the filtered and unfolded differential propagation phase */
                      float *phidp_unf,   /**< the unfolded (not filtered) differential propagation phase */
                      float *kdp,         /**< the estimated specific differential propagation phase */
                      int *kdpmask);      /**< the kdp mask  good=1, bad=0  */
 
#if 0
{
#endif
#ifdef __cplusplus
}
#endif
#endif /* __DP_PHI_PROC_H_ */

