name: Sigmoid
synopsis:

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

>     #include <Sigmoid.h>

>     boolean set(float gain, float slope, float xoffset, float yoffset);
>     boolean compute(float& y, float x);

quick start:

>     Sigmoid sigm(1, 0.5);
>     float y;
>     float x = 0.5;

>     // evaluate y = sigmoid(x)
>     //
>     sigm.compute(y, x);

>     // evaluate y = derivative with respect to 'x' of the sigmoid function
>     // evaluated at x
>     //
>     sigm.derivative(y, x);

description:
The Sigmoid class is 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 variable named slope is not truly the slope of the transition region but can be varied to control that slope.
dependencies:

- VectorDouble
- VectorFloat
- MemoryManager

public constants:

- define the class name:

      static const String CLASS_NAME = L"Sigmoid";

- i/o related constants:

      static const String DEF_PARAM = L"";

      static const String PARAM_GAIN = L"gain";

      static const String PARAM_SLOPE = L"slope";

      static const String PARAM_XOFFSET = L"xoffset";

      static const String PARAM_YOFFSET = L"yoffset";

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

      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:

- error code indicating Sigmoid class general error:

      static const long ERR = (long)35000;

protected data:

- parameters of the functional sigmoid form

      Float gain_d;

      Float slope_d;

      Float xoffset_d;

      Float yoffset_d;

- debug level:

      static Integral::DEBUG debug_level_d;

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

      boolean setDebug(Integral::DEBUG debug_level);

      boolean debug(const unichar* message) const;

- destructor/constructor(s):

      ~Sigmoid();

      Sigmoid();

      Sigmoid(const Sigmoid& arg);

- assign methods:

      boolean assign(const Sigmoid& arg)

- operator= methods:

      Sigmoid& operator= (const Sigmoid& 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 Sigmoid& 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 setGain(float gain);

      boolean setSlope(float slope);

      boolean setXOffset(float xoffset);

      boolean setYOffset(float yoffset);

      boolean set(float gain, float slope, float xoffset, float yoffset);

- get methods:

      float getGain();

      float getSlope();

      float getXOffset();

      float getYOffset();

      boolean get(float& gain, float& slope, float& xoffset, float& yoffset);

- computational methods:

      boolean compute(float& y, float x) const;

      boolean compute(double& y, const double x) const;

      boolean compute(VectorFloat& y, const VectorFloat& x) const;

      boolean compute(VectorDouble& y, const VectorDouble& x) const;

      boolean derivative(float& dydx, float x) const;

      boolean derivative(double& dydx, const double x) const;

      boolean derivative(VectorFloat& dydx, const VectorFloat& x) const;

      boolean derivative(VectorDouble& dydx, const VectorDouble& x) const;

      boolean derivativeGain(float& dydgain, float x) const;

      boolean derivativeGain(double& dydgain, const double x) const;

      boolean derivativeGain(VectorFloat& dydgain, const VectorFloat& x) const;

      boolean derivativeGain(VectorDouble& dydgain, const VectorDouble& x) const;

      boolean derivativeSlope(float& dydslope, float x) const;

      boolean derivativeSlope(double& dydslope, const double x) const;

      boolean derivativeSlope(VectorFloat& dydslope, const VectorFloat& x) const;

      boolean derivativeSlope(VectorDouble& dydslope, const VectorDouble& x) const;

      boolean derivativeXOffset(float& dydxoffset, float x) const;

      boolean derivativeXOffset(double& dydxoffset, const double x) const;

      boolean derivativeXOffset(VectorFloat& dydxoffset, const VectorFloat& x) const;

      boolean derivativeXOffset(VectorDouble& dydxoffset, const VectorDouble& x) const;

      boolean derivativeYOffset(float& dydyoffset, float x) const;

      boolean derivativeYOffset(double& dydyoffset, const double x) const;

      boolean derivativeYOffset(VectorFloat& dydyoffset, const VectorFloat& x) const;

      boolean derivativeYOffset(VectorDouble& dydyoffset, const VectorDouble& x) const;

private methods:

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

examples:

- This example shows how to create and evaluate a sigmoid function:

      #include <Sigmoid.h>
      #include <VectorDouble.h>

      int main() {

        // declare a Sigmoid object
        //
        Sigmoid sigm;

        // set the parameters of the sigmoid:
        // gain = 0.5, slope = 0.2, xoffset = 1, yoffset = 0
        //
        sigm.set(0.5, 0.2, 1, 0);

        // declare the input and output vectors
        //
        VectorDouble input(L"0, 1, -1, 2, -2");
        VectorDouble output;

        // compute the sigmoid function at the prescribed input points
        //
        sigm.compute(output, input);

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

notes:

- This class has internal data (parameter settings for the Sigmoid) and must be instantiated before being used.