// file: $isip/class/numeric/Sigmoid/Sigmoid.h
// version: $Id: Sigmoid.h 8338 2002-07-11 03:35:34Z picone $
//

// make sure definitions are only made once
//
#ifndef ISIP_SIGMOID
#define ISIP_SIGMOID

// isip include files
//
#ifndef ISIP_VECTOR_FLOAT
#include <VectorFloat.h>
#endif

#ifndef ISIP_VECTOR_DOUBLE
#include <VectorDouble.h>
#endif

#ifndef ISIP_MEMORY_MANAGER
#include <MemoryManager.h>
#endif

// Sigmoid: a class used to analyze and evaluate sigmoid functions of the form:
//
//                      gain
//      y(x)  =   -------------------------------  + y_offset
//                1 + e^(-slope * (x - x_offset))
//
// Nominally, the gain is 1, the offset is 0 and the slope is 1 which
// produces a function that varies smoothly between 0 and 1. The gain,
// x_offset and y_offset, can be adjusted to control the effective domain
// and range of the output. The slope is not truly the slope of the
// transition region but can be varied to control that slope.
//
class Sigmoid {

  //---------------------------------------------------------------------------
  //
  // public constants
  //
  //---------------------------------------------------------------------------
public:
  
  // define the class name
  //
  static const String CLASS_NAME;
  
  //----------------------------------------
  //
  // other important constants
  //
  //----------------------------------------

  //----------------------------------------
  //
  // i/o related constants
  //
  //----------------------------------------  
  
  static const String DEF_PARAM;
  static const String PARAM_GAIN;
  static const String PARAM_SLOPE;  
  static const String PARAM_XOFFSET; 
  static const String PARAM_YOFFSET;
  
  //----------------------------------------
  //
  // default values and arguments
  //
  //----------------------------------------  

  static const float DEF_GAIN = 1.0;
  static const float DEF_SLOPE = 1.0;
  static const float DEF_XOFFSET = 0.0;
  static const float DEF_YOFFSET = 0.0;
  
  //----------------------------------------
  //
  // error codes
  //
  //----------------------------------------  
  
  static const long ERR = 35000;
  
  //---------------------------------------------------------------------------
  //
  // protected data
  //
  //---------------------------------------------------------------------------
protected:
  
  // parameters of the functional sigmoid form
  //
  Float gain_d;
  Float slope_d;
  Float xoffset_d;
  Float yoffset_d;  

  // a static debug level
  //
  static Integral::DEBUG debug_level_d;
  
  // a static memory manager
  //
  static MemoryManager mgr_d;
  
  //---------------------------------------------------------------------------
  //
  // required public methods
  //
  //---------------------------------------------------------------------------
public:
    
  // method: name
  //
  static const String& name() {
    return CLASS_NAME;
  }

  // other static methods
  //
  static boolean diagnose(Integral::DEBUG debug_level);
  
  // method: setDebug
  //
  static boolean setDebug(Integral::DEBUG debug_level) {
    debug_level_d = debug_level;
    return true;
  }
  
  // other debug methods
  //
  boolean debug(const unichar* msg) const;

  // method: destructor
  //
  ~Sigmoid() {}
  
  // method: default constructor
  //
  Sigmoid(float gain = DEF_GAIN, float slope = DEF_SLOPE,
	  float xoffset = DEF_XOFFSET, float yoffset = DEF_YOFFSET) {
    gain_d = gain;
    slope_d = slope;
    xoffset_d = xoffset;
    yoffset_d = yoffset;
  }

  // method: copy constructor
  //
  Sigmoid(const Sigmoid& arg) {
    assign(arg);
  }
  
  // method: assign
  //
  boolean assign(const Sigmoid& arg) {
    gain_d = arg.gain_d;
    slope_d = arg.slope_d;
    xoffset_d = arg.xoffset_d;
    yoffset_d = arg.yoffset_d;
    return true;
  }

  // method: operator=
  //
  Sigmoid& operator= (const Sigmoid& arg) {
    assign(arg);
    return *this;
  }

  // method: sofSize
  //
  long sofSize() const {
    return (gain_d.sofSize() + slope_d.sofSize() + xoffset_d.sofSize() +
	    yoffset_d.sofSize());
  }
  
  // other i/o methods
  //
  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;

  // method: eq
  //
  boolean eq(const Sigmoid& arg) const {
    return(gain_d.eq(arg.gain_d) && slope_d.eq(arg.slope_d) &&
	   xoffset_d.eq(arg.xoffset_d) && yoffset_d.eq(arg.yoffset_d));
  }

  // method: new
  //
  static void* operator new(size_t size) {
    return mgr_d.get();
  }

  // method: new[]
  //
  static void* operator new[](size_t size) {
    return mgr_d.getBlock(size);
  }

  // method: delete
  //
  static void operator delete(void* ptr) {
    mgr_d.release(ptr);
  }

  // method: delete[]
  //
  static void operator delete[](void* ptr) {
    mgr_d.releaseBlock(ptr);
  }
  
  // method: setGrowSize
  // 
  static boolean setGrowSize(long grow_size) {
    return mgr_d.setGrow(grow_size);
  }

  // method: clear
  //
  boolean clear(Integral::CMODE cmode = Integral::DEF_CMODE) {
    if (cmode != Integral::RETAIN) {
      gain_d = DEF_GAIN;
      slope_d = DEF_SLOPE;
      xoffset_d = DEF_XOFFSET;
      yoffset_d = DEF_YOFFSET;
    }
    return true;
  }

  //---------------------------------------------------------------------------
  //
  // class-specific public methods:
  //  set methods
  //
  //---------------------------------------------------------------------------
 
  // method: setGain
  //
  boolean setGain(float gain) {
    gain_d = gain;
    return true;  
  }
  
  // method: setSlope
  //
  boolean setSlope(float slope) {
    slope_d = slope;
    return true;  
  }
  
  // method: setXOffset
  //
  boolean setXOffset(float xoffset) {
    xoffset_d = xoffset;
    return true;  
  }
  
  // method: setYOffset
  //
  boolean setYOffset(float yoffset) {
    yoffset_d = yoffset;
    return true;  
  }
  
  // method: set
  //
  boolean set(float gain, float slope, float xoffset, float yoffset) {
    gain_d = gain;
    slope_d = slope;
    xoffset_d = xoffset;
    yoffset_d = yoffset;
    return true;  
  }
  
  //---------------------------------------------------------------------------
  //
  // class-specific public methods:
  //  get methods
  //
  //---------------------------------------------------------------------------
 
  // method: getGain
  //
  float getGain() {
    return gain_d;
  }
  
  // method: getSlope
  //
  float getSlope() {
    return slope_d;
  }
  
  // method: getXOffset
  //
  float getXOffset() {
    return xoffset_d;
  }
  
  // method: getYOffset
  //
  float getYOffset() {
    return yoffset_d;
  }
  
  // method: get
  //
  boolean get(float& gain, float& slope, float& xoffset, float& yoffset) {
    gain = gain_d;
    slope = slope_d;
    xoffset = xoffset_d;
    yoffset = yoffset_d;
    return true;  
  }
  
  //---------------------------------------------------------------------------
  //
  // class-specific public methods:
  //  computational methods
  //  all of these methods are defined for double and float types
  //
  //---------------------------------------------------------------------------

  // method: compute
  //  the vector method gives y[i] = sigmoid(x[i])
  //
  boolean compute(float& y, float x) const {
    return computeScalar<float>(y, x);
  }

  // method: compute
  //
  boolean compute(double& y, const double x) const {
    return computeScalar<double>(y, x);
  }

  // method: compute
  //
  boolean compute(VectorFloat& y, const VectorFloat& x) const {
    return computeVector<VectorFloat, float>(y, x);
  }

  // method: compute
  //
  boolean compute(VectorDouble& y, const VectorDouble& x) const {
    return computeVector<VectorDouble, double>(y, x);
  }

  // method: derivative
  //  derivative = the derivative with respect to (w.r.t.) x, evaluated at x
  //
  boolean derivative(float& dydx, float x) const {
    return derivativeScalar<float>(dydx, x);
  }

  // method: derivative
  //  derivative = the derivative with respect to (w.r.t.) x, evaluated at x
  //
  boolean derivative(double& dydx, const double x) const {
    return derivativeScalar<double>(dydx, x);
  }

  // method: derivative
  //  derivative = the derivative with respect to (w.r.t.) x, evaluated at x
  //
  boolean derivative(VectorFloat& dydx, const VectorFloat& x) const {
    return derivativeVector<VectorFloat, float>(dydx, x);
  }

  // method: derivative
  //  derivative = the derivative with respect to (w.r.t.) x, evaluated at x
  //
  boolean derivative(VectorDouble& dydx, const VectorDouble& x) const {
    return derivativeVector<VectorDouble, double>(dydx, x);
  }

  // method: derivativeGain
  //  derivativeGain = the derivative w.r.t. the gain, evaluated at x
  //
  boolean derivativeGain(float& dydgain, float x) const {
    return derivativeGainScalar<float>(dydgain, x);
  }

  // method: derivativeGain
  //  derivativeGain = the derivative w.r.t. the gain, evaluated at x
  //
  boolean derivativeGain(double& dydgain, const double x) const {
    return derivativeGainScalar<double>(dydgain, x);
  }

  // method: derivativeGain
  //  derivativeGain = the derivative w.r.t. the gain, evaluated at x
  //
  boolean derivativeGain(VectorFloat& dydgain,
			 const VectorFloat& x) const {
    return derivativeGainVector<VectorFloat, float>(dydgain, x);
  }

  // method: derivativeGain
  //  derivativeGain = the derivative w.r.t. the gain, evaluated at x
  //
  boolean derivativeGain(VectorDouble& dydgain,
			 const VectorDouble& x) const {
    return derivativeGainVector<VectorDouble, double>(dydgain, x);
  }

  // method: derivativeSlope
  //  derivativeSlope = the derivative w.r.t. the slope, evaluated at x
  //
  boolean derivativeSlope(float& dydslope, float x) const {
    return derivativeSlopeScalar<float>(dydslope, x);
  }

  // method: derivativeSlope
  //  derivativeSlope = the derivative w.r.t. the slope, evaluated at x
  //
  boolean derivativeSlope(double& dydslope, const double x) const {
    return derivativeSlopeScalar<double>(dydslope, x);
  }

  // method: derivativeSlope
  //  derivativeSlope = the derivative w.r.t. the slope, evaluated at x
  //
  boolean derivativeSlope(VectorFloat& dydslope,
			  const VectorFloat& x) const {
    return derivativeSlopeVector<VectorFloat, float>(dydslope, x);
  }

  // method: derivativeSlope
  //  derivativeSlope = the derivative w.r.t. the slope, evaluated at x
  //
  boolean derivativeSlope(VectorDouble& dydslope,
			  const VectorDouble& x) const {
    return derivativeSlopeVector<VectorDouble, double>(dydslope, x);
  }

  // method: derivativeXOffset
  //  derivativeXOffset = the derivative w.r.t. the xoffset, evaluated at x
  //
  boolean derivativeXOffset(float& dydxoffset, float x) const {
    return derivativeXOffsetScalar<float>(dydxoffset, x);
  }

  // method: derivativeXOffset
  //  derivativeXOffset = the derivative w.r.t. the xoffset, evaluated at x
  //
  boolean derivativeXOffset(double& dydxoffset, const double x) const {
    return derivativeXOffsetScalar<double>(dydxoffset, x);
  }

  // method: derivativeXOffset
  //  derivativeXOffset = the derivative w.r.t. the xoffset, evaluated at x
  //
  boolean derivativeXOffset(VectorFloat& dydxoffset,
			    const VectorFloat& x) const {
    return derivativeXOffsetVector<VectorFloat, float>(dydxoffset, x);
  }
  
  // method: derivativeXOffset
  //  derivativeXOffset = the derivative w.r.t. the xoffset, evaluated at x
  //
  boolean derivativeXOffset(VectorDouble& dydxoffset,
			    const VectorDouble& x) const {
    return derivativeXOffsetVector<VectorDouble, double>(dydxoffset, x);
  }
  
  // method: derivativeYOffset
  //  derivativeYOffset = the derivative w.r.t. the yoffset, evaluated at x
  //
  boolean derivativeYOffset(float& dydyoffset, float x) const {
    return derivativeYOffsetScalar<float>(dydyoffset, x);
  }

  // method: derivativeYOffset
  //  derivativeYOffset = the derivative w.r.t. the yoffset, evaluated at x
  //
  boolean derivativeYOffset(double& dydyoffset, const double x) const {
    return derivativeYOffsetScalar<double>(dydyoffset, x);
  }

  // method: derivativeYOffset
  //  derivativeYOffset = the derivative w.r.t. the yoffset, evaluated at x
  //
  boolean derivativeYOffset(VectorFloat& dydyoffset,
			    const VectorFloat& x) const {
    return derivativeYOffsetVector<VectorFloat, float>(dydyoffset, x);
  }
  
  // method: derivativeYOffset
  //  derivativeYOffset = the derivative w.r.t. the yoffset, evaluated at x
  //
  boolean derivativeYOffset(VectorDouble& dydyoffset,
			    const VectorDouble& x) const {
    return derivativeYOffsetVector<VectorDouble, double>(dydyoffset, x);
  }
  
  //---------------------------------------------------------------------------
  //
  // private methods
  //
  //---------------------------------------------------------------------------
private:

  // templatized computation methods
  //
  template <class TIntegral>
  boolean computeScalar(TIntegral& y, const TIntegral x) const;

  template <class TVector, class TIntegral>
  boolean computeVector(TVector& y, const TVector& x) const;  

  template <class TIntegral>
  boolean derivativeScalar(TIntegral& dydx, const TIntegral x) const;

  template <class TVector, class TIntegral>
  boolean derivativeVector(TVector& dydx, const TVector& x) const;

  template <class TIntegral>
  boolean derivativeGainScalar(TIntegral& dydgain, const TIntegral x) const;

  template <class TVector, class TIntegral>
  boolean derivativeGainVector(TVector& dydgain, const TVector& x) const;

  template <class TIntegral>
  boolean derivativeSlopeScalar(TIntegral& dydslope, const TIntegral x) const;

  template <class TVector, class TIntegral>
  boolean derivativeSlopeVector(TVector& dydslope, const TVector& x) const;

  template <class TIntegral>
  boolean derivativeXOffsetScalar(TIntegral& dydxoffset,
				  const TIntegral x) const;

  template <class TVector, class TIntegral>
  boolean derivativeXOffsetVector(TVector& dydxoffset, const TVector& x) const;
  
  template <class TIntegral>
  boolean derivativeYOffsetScalar(TIntegral& dydyoffset,
				  const TIntegral x) const;

  template <class TVector, class TIntegral>
  boolean derivativeYOffsetVector(TVector& dydyoffset, const TVector& x) const;
  
};

// end of include file
// 
#endif



