nmrPolynomialBase.h

Go to the documentation of this file.

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-    */
/* ex: set filetype=cpp softtabstop=4 shiftwidth=4 tabstop=4 cindent expandtab: */

/*

  Author(s):    Ofri Sadowsky
  Created on:   2001-10-16

  (C) Copyright 2001-2007 Johns Hopkins University (JHU), All Rights
  Reserved.

--- begin cisst license - do not edit ---

This software is provided "as is" under an open source license, with
no warranty.  The complete license can be found in license.txt and
http://www.cisst.org/cisst/license.txt.

--- end cisst license ---
*/


#ifndef _nmrPolynomialBase_h
#define _nmrPolynomialBase_h


#include <vector>
#include <cisstCommon/cmnPortability.h>
#include <cisstNumerical/nmrPolynomialTermPowerIndex.h>

#include <cisstNumerical/nmrMultiVariablePowerBasis.h>

#include <cisstNumerical/nmrExport.h>

// This control macro defines, when set to one, the inclusion of deprecated
// code in the polynomial classes.  We everything that depends on a 'true'
// value of this macro to be erased from future releases of the cisst library.
#define INCLUDE_DEPRECATED_POLYNOMIAL_CODE 0

// class nmrPolynomialBase is an abstract base class for various polynomial classes.
// Since different polynomial classes store different information for the terms (for
// example, a standard polynomial stores a coefficient, a Bernstein polynomial stores a 
// coefficient and a multinomial factor), the base class defined the common subset of
// operations for a polynomial, but does not implement the storage for the terms, or 
// the rules that relate the variables (e.g., the sum of variables is always one for
// a Bernstein polynomial).
//
// A term in the polynomial is identified by an index, which is the set of powers for
// all the variables of the polynomial in the term. See class nmrPolynomialTermPowerIndex.
//
// An implementation of a multi-variable polynomial is in class nmrPolynomialContainer.
class CISST_EXPORT nmrPolynomialBase
{
public:
    typedef double ValueType;
    typedef double VariableType;
    typedef double CoefficientType;
    typedef nmrPolynomialTermPowerIndex::VariableIndexType VariableIndexType;
    typedef nmrPolynomialTermPowerIndex::PowerType PowerType;
    typedef nmrPolynomialTermPowerIndex::MultinomialCoefficientType TermCounterType;

    enum InsertStatus { INSERT_FAIL = -1, INSERT_NEW = 0, INSERT_REPLACE = 1 };

    // Ctor determines the number of variables and the degree of the polynomial
    nmrPolynomialBase(VariableIndexType numVariables, PowerType minDegree, PowerType maxDegree);

    virtual ~nmrPolynomialBase()
    {}

    VariableIndexType GetNumVariables() const
    {
        return NumVariables;
    }

    PowerType GetMinDegree() const
    {
        return MinDegree;
    }

    PowerType GetMaxDegree() const
    {
        return MaxDegree;
    }

    // implemented in nmrPolynomialContainer
    virtual TermCounterType GetNumberOfTerms() const = 0;

    // return the maximum possible number of terms for this polynomial, based on
    // the degrees.
    TermCounterType GetMaxNumberOfTerms() const
    {
        return (nmrPolynomialTermPowerIndex(*this)).CountPowerCombinations();
    }
    
#if INCLUDE_DEPRECATED_POLYNOMIAL_CODE
    // Set the values of the polynomial variables to a specific n-dimensional
    // point. This enables to pre-calculate the power basis for future 
    // evaluations.
    // Implemented for each concrete polynomial class
    virtual void CISST_DEPRECATED SetVariables(const VariableType vars[]) = 0;

    // Set the value of one variable
    // Implemented for each concrete polynomial class.
    virtual void CISST_DEPRECATED SetVariable(VariableIndexType varIndex, VariableType value) = 0;

    // Returns true if the value of variable indicated by the index can be set
    // using SetVariable().
    virtual bool CISST_DEPRECATED CanSetVariable(VariableIndexType varIndex) const = 0;

#ifdef CISST_COMPILER_IS_MSVC
#pragma warning(push)
#pragma warning(disable:4996)
#endif  // ifdef CISST_COMPILER_IS_MSVC
    // Retrieve the values of the variables at the current point
    void CISST_DEPRECATED GetVariables(VariableType vars[]) const 
    {
        VariableIndexType v;
        for (v = 0; v < GetNumVariables(); ++v)
            vars[v] = GetVariable(v);
    }

    // Retrieve the value of one variable
    VariableType CISST_DEPRECATED GetVariable(VariableIndexType var) const
    { 
        return VariablePowers->GetVariable(var);
    }

    // Return a specific power of a specific variable
    VariableType CISST_DEPRECATED GetVariablePower(VariableIndexType var, PowerType power) const
    {
        return VariablePowers->GetVariablePower(var, power);
    }

#ifdef CISST_COMPILER_IS_MSVC
#pragma warning(pop)
#endif  // ifdef CISST_COMPILER_IS_MSVC
#endif  // INCLUDE_DEPRECATED_POLYNOMIAL_CODE

    //: Tell if there are any nonzero terms in the polynomial.
    // Implemented in nmrPolynomialContainer.
    virtual bool IsEmpty() const = 0;

    //: Update the minimum allowable degree of this polynomial to the given
    // input degree.  The method verifies that the polynomial currently contains
    // only terms of degree greater than or equal to the input, by looking at the
    // degree of the first term, which is presumably the lowest.  Note that terms
    // already contained in this polynomial aren't modified.
    virtual void SetMinDegree(PowerType newMin) throw(std::runtime_error) = 0;


    //: Update the maximum allowable degree of this polynomial to the given
    // input degree.  The method verifies that the polynomial currently contains
    // only terms of degree lower than or equal to the input by looking at the
    // degree of the last term, which is presumably the highest.  Note that terms
    // already contained in this polynomial aren't modified.
    virtual void SetMaxDegree(PowerType newMax) throw(std::runtime_error) = 0;

    //: Generate all possible terms for this polynomial, and store them for later
    // use.
    // Implemented in nmrPolynomialContainer.
    virtual void FillAllTerms() = 0;
    
    // Tells if this polynomial can have the given term as one of its terms.
    // In other words, if it's a valid term of this polynomial.
    bool CanIncludeIndex(const nmrPolynomialTermPowerIndex& term) const;

    // Find a term by its coefficients. Return true is the term is found.
    // return 'false' otherwise.
    // Implemented in nmrPolynomialContainer.
    virtual bool IncludesIndex(const nmrPolynomialTermPowerIndex& target) const = 0;

    // Find a term by its coefficients.  If the term is found, return the sequential
    // position (zero-based) of the term in the sequence of terms for this polynomial.
    // If the term is not found, return a number greater than or equal to the current number 
    // of terms in the sequence.
    virtual TermCounterType GetIndexPosition(const nmrPolynomialTermPowerIndex & term) const = 0;

    // Remove a term from the polynomial.
    // Implemented in nmrPolynomialContainer.
    virtual void RemoveTerm(const nmrPolynomialTermPowerIndex & where) = 0;

    // Remove all the terms to make an empty (zero) polynomial
    // Implemented in nmrPolynomialContainer.
    virtual void Clear() = 0;

    // Set a coefficient for the given term.
    // Implemented for each concrete polynomial class.
    virtual InsertStatus SetCoefficient(const nmrPolynomialTermPowerIndex & where, CoefficientType coefficient) = 0;

    // Retrieve the value of the user defined coefficient for a given term.
    // Implemented for each concrete polynomial class.
    virtual CoefficientType GetCoefficient(const nmrPolynomialTermPowerIndex & CMN_UNUSED(where)) const
    { 
        return 0; 
    }

    // Store all the coefficients into the target array, ordered the same
    // way as the terms in this polynomial.  The user has to make sure that
    // the target array has enough space to contain all the coefficients,
    // and note that if this polynomial is modified then the target array is
    // no longer valid.
    virtual void CollectCoefficients(CoefficientType source[]) const = 0;

    // Restore all the coefficients from the source array, ordered the same
    // way as the terms in this polynomial.  The user has to make sure that
    // the target array is ordered properly -- typically it's generated using
    // CollectCoefficients(). 
    virtual void RestoreCoefficients(const CoefficientType source[]) = 0;

#if INCLUDE_DEPRECATED_POLYNOMIAL_CODE
#ifdef CISST_COMPILER_IS_MSVC
#pragma warning(push)
#pragma warning(disable:4996)
#endif  // ifdef CISST_COMPILER_IS_MSVC
    // Evaluate the product of powers for a given term index and the variables
    // set in this object.
    ValueType CISST_DEPRECATED EvaluatePowerProduct(const nmrPolynomialTermPowerIndex & where) const
    {
        CMN_ASSERT(this->CanIncludeIndex(where));
        return VariablePowers->EvaluatePowerProduct(where.GetPowers());
    }

    /* The function has been factored out to nmrMultiVariablePowerBasis */
    ValueType CISST_DEPRECATED EvaluatePowerProduct(const PowerType powers[]) const
    {
        return VariablePowers->EvaluatePowerProduct(powers);
    }

    ValueType CISST_DEPRECATED EvaluateBasis(const nmrPolynomialTermPowerIndex & where) const
    {
        return EvaluateBasis(where, *VariablePowers);
    }
    
    // Evaluate a single term at the currently specified point, including
    // the basis function and the term's.  This function uses the internally
    // stored coefficient.
    ValueType CISST_DEPRECATED EvaluateTerm(const nmrPolynomialTermPowerIndex & where) const
    {
        CoefficientType coefficient = GetCoefficient(where);
        return EvaluateTerm(where, coefficient);
    }

    // Evaluate a single term at the currently specified point, including
    // the basis function and the term's coefficient.  This function takes
    // the coefficient as a parameter, and does not use internally stored 
    // coefficients.
    ValueType CISST_DEPRECATED EvaluateTerm(const nmrPolynomialTermPowerIndex & where, CoefficientType coefficient) const
    {
        return EvaluateTerm(where, *VariablePowers, coefficient);
    }

    void CISST_DEPRECATED EvaluateBasisVector(ValueType termBaseValues[]) const
    {
        EvaluateBasisVector(*VariablePowers, termBaseValues);
    }
    
    // Evaluate the polynomial at the currently specified point.
    // Implemented in nmrPolynomialContainer.
    ValueType CISST_DEPRECATED Evaluate()
    {
        return Evaluate(*VariablePowers);
    }

    // Evaluate the polynomial at the currently specified point, using
    // externally defined coefficients.  This lets the user create many
    // polynomials over the same set of basis functions without having to
    // duplicate the terms.
    // The input coefficients must be ordered the same way as the terms in this
    // object.  It is best to order them using CollectCoefficients()
    ValueType CISST_DEPRECATED EvaluateForCoefficients(const CoefficientType coefficients[]) const
    {
        return EvaluateForCoefficients(*VariablePowers, coefficients);
    }
#ifdef CISST_COMPILER_IS_MSVC
#pragma warning(pop)
#endif  // ifdef CISST_COMPILER_IS_MSVC
#endif  // INCLUDE_DEPRECATED_POLYNOMIAL_CODE

    virtual ValueType EvaluateBasis(const nmrPolynomialTermPowerIndex & where,
        const nmrMultiVariablePowerBasis & variables) const = 0;

    ValueType EvaluateTerm(const nmrPolynomialTermPowerIndex & where,
        const nmrMultiVariablePowerBasis & variables) const
    {
        CoefficientType coefficient = GetCoefficient(where);
        return EvaluateTerm(where, variables, coefficient);
    }

    ValueType EvaluateTerm(const nmrPolynomialTermPowerIndex & where,
        const nmrMultiVariablePowerBasis & variables, CoefficientType coefficient) const
    {
        if (coefficient == 0)
            return 0;
        return coefficient * EvaluateBasis(where, variables);
    }

    virtual void EvaluateBasisVector(const nmrMultiVariablePowerBasis & variables,
        ValueType termBaseValues[]) const = 0;

    virtual ValueType EvaluateForCoefficients(const nmrMultiVariablePowerBasis & variables,
        const CoefficientType coefficients[]) const = 0;

    virtual ValueType Evaluate(const nmrMultiVariablePowerBasis & variables)
        const = 0;


    virtual void Scale(CoefficientType scaleFactor) = 0;

    void CISST_DEPRECATED ScaleCoefficients(CoefficientType coefficients[], CoefficientType scaleFactor) const;

    virtual void AddConstant(CoefficientType shiftAmount) = 0;

    virtual void AddConstantToCoefficients(CoefficientType coefficients[],
        CoefficientType shiftAmount) const = 0;

#if DEFINE_FORMATTED_OUTPUT
    // Format the terms of the polynomial as a string.
    // Return: a pointer to the character immediately following the formatted output
    virtual char * Format(char * buffer) const = 0;
#endif

#if DEFINE_FORMATTED_OUTPUT
    int CalculateFormatLength() const
    {
        int termPowerLength = nmrPolynomialTermPowerIndex(*this).CalculateFormatPowerLength();
        int coefficientLength = 15;
        // <coefficient>< ><{><powers>}\n
        int termLength = coefficientLength + 1 + 2 + termPowerLength + 3;
        int numTerms = GetNumberOfTerms();
        return numTerms * termLength;
    }
#endif

    virtual void SerializeRaw(std::ostream & output) const;

    virtual void DeserializeRaw(std::istream & input);

protected:
    VariableIndexType NumVariables;
    PowerType MinDegree;
    PowerType MaxDegree;

#if INCLUDE_DEPRECATED_POLYNOMIAL_CODE
    CISST_DEPRECATED nmrMultiVariablePowerBasis * VariablePowers;
#endif  // INCLUDE_DEPRECATED_POLYNOMIAL_CODE

};



#endif // _nmrPolynomialBase_h