Proto_Point.H

Go to the documentation of this file.

#pragma once
#ifndef _PROTO_POINT_
#define _PROTO_POINT_

#include <iostream>
#include <sstream>
#include <array>
#include <set>

#include "Proto_Accel.H"
#include "Proto_Face.H"
#include "Proto_PAssert.H"

namespace Proto
{

#ifdef PR_HDF5
    class HDF5Handler;
#endif
    /// Integer Valued Vector
    /**
      An element \f$\mathbf{p}\in\mathbb{Z}^{DIM}\f$
    */
    class Point
    {
#ifdef PR_HDF5
        friend class Proto::HDF5Handler;
#endif
        public:
        //////////////////////////////////////////////////////////////////////////////////////////
        /** @name Constructors */
        ///@{
        /// Default Constructor
        /**
            Creates the zero Point <code>(0,0,...,0)</code>
        */
        ACCEL_DECORATION inline Point();

        /// C-Array Constructor
        /**

            Allows "literal" construction of points using a C-Array

            Example:
            @code
            using namespace Proto;
            //DIM=2
            Point p = Point({-5,13}); //creates the point (-5,13)
            //NB: This will not compile when DIM != 2
            @endcode

            \param a_tuple  integer array representing a Point
        */
        ACCEL_DECORATION inline Point(const int (&a_tuple)[DIM]);

        /// Variadic Constructor
        /**
            Builds a Point from the first DIM arguments given to this. Any trailing arguments are ignored.
            This constructor is very useful for building dimensionally independent test code.

            Example:
            @code
            Point p(1,2,3,4,5,6);
            if (DIM == 1)
            {
            std::cout << p << std::endl;    //prints (1)
            } else if (DIM == 2) {
            std::cout << p << std::endl;    //prints (1, 2)
            } else if (DIM == 3) {
            std::cout << p << std::endl;    //prints (1, 2, 3)
            } //etc.
            @endcode

            \param args     At least DIM integer arguments representing a Point
        */
        template<typename... vals>
        ACCEL_DECORATION inline explicit Point(vals... args) { unpack(0, args...); }

        /// Copy Constructor
        /**
            Creates a new point by copying an existing one.

            \param a_pt     A Point.
        */
        ACCEL_DECORATION inline Point(const Point& a_pt);

        ///@}
        //////////////////////////////////////////////////////////////////////////////////////////
        /** @name Static Methods */
        ///@{

        /// Get Ones
        /**
            Returns the unit Point <code>scale*(1,1,...,1)</code>

            \param a_scale  (Optional) value to scale the vector by (default: 1)
        */
        ACCEL_DECORATION inline static Point Ones(int a_scale=1);

        /// Get Unit Point
        /**
            Returns the Point <code>(1,1,...,1)</code>
        */
        ACCEL_DECORATION inline static Point Unit() { return Ones(1); }

        /// Get Zeros
        /**
            Returns the zero Point <code>(0,0,...,0)</code>
        */
        ACCEL_DECORATION inline static Point Zeros();

        /// Get Zeros (Pedantic Spelling)
        /**
            Identical to Zeros() but with alternative spelling.
        */
        ACCEL_DECORATION inline static Point Zeroes() { return Zeros(); }
  
        /// Get Zeros (Alternate Spelling)
        /**
            Identical to Zeros() but with alternative spelling.
        */
        ACCEL_DECORATION inline static Point Zero() { return Zeros(); }
    
        /// Get Basis 
        /**
            Returns an axis-aligned Point \f$\bf{p}: \bf{p}[k] = scale*\delta_{dir}^k\f$.

            \param a_dir    A coordinate axis.
            \param a_scale  (Optional) value to scale the unit vector by (default: 1)
        */
        ACCEL_DECORATION inline static Point Basis(int a_dir, int a_scale=1);

        /// Get Basis (Side Argument)
        /**
            Returns an axis-aligned Point \f$\bf{p}: \bf{p}[k] = s*\delta_{dir}^k\f$.
            Where \f$ s = 1 \f$ if <code> a_side = Side::Hi </code> and 
            where \f$ s = -1 \f$ if <code> a_side = Side::Lo </code>. 

            \param a_dir    A spatial axis (0 for x, 1 for y, etc.)
            \param a_side   Low or high side. Low amounts to scaling by -1.
        */
        ACCEL_DECORATION inline static Point Basis(int a_dir, const Side::LoHiSide a_side);
        
        ACCEL_DECORATION inline static Point X() { return Basis(0); }
        ACCEL_DECORATION inline static Point Y() { return Basis(1); }
        ACCEL_DECORATION inline static Point Z() { return Basis(2); }

        inline static std::set<Point> Directions();
        inline static std::set<Point> DirectionsOfCodim(int a_codim);
        

        ///@}
        //////////////////////////////////////////////////////////////////////////////////////////
        /** @name Accessors */
        ///@{

        /// Get Component (Const)
        /**
            Returns a const reference to the a_index component of *this

            \param a_index  Index in [0,DIM)
        */
        ACCEL_DECORATION inline const int&  operator[](unsigned int a_index) const;

        /// Get Component (Non-Const)
        /**
            Returns a mutable reference to the a_index component of *this

            \param a_index  Index in [0,DIM)
        */
        ACCEL_DECORATION inline int&  operator[](unsigned int a_index);
            
        ///@}
        //////////////////////////////////////////////////////////////////////////////////////////
        /** @name Operators */
        ///@{

        /// Asignment Operator
        /**
            Performs copy assignment.

            \param a_rhs    Another Point
        */
        ACCEL_DECORATION inline Point& operator=(const Point& a_rhs);

        /// Less-Than Operator
        /** 
            Used to define an ordering for placing Points in maps etc.
            Uses Lexical comparison. Note that Chombo lexLT is also lexical
            but uses the dimensions in the opposite way.

            \param a_rhs    Another Point
        */
        ACCEL_DECORATION inline bool operator<(const Point& a_rhs) const;

        /// Equality Operator
        /**
            Equality is checked componentwise.   
         
            \param a_pt     Another Point
        */
        ACCEL_DECORATION inline bool operator==(const Point& a_pt) const;

        /// Inequality Operator
        /**
            Equality is checked componentwise.   

            \param a_pt     Another Point
        */
        ACCEL_DECORATION inline bool operator!=(const Point& a_pt) const;

        /// Componentwise Point Addition Operator
        /**
            Creates the new Point by adding <code>*this</code> and <code>a_rhs</code> componentwise.

            \param a_rhs     Another Point
        */
        ACCEL_DECORATION inline Point operator+(const Point& a_rhs) const;

        /// Componentwise Point Subtraction Operator 
        /**
            Creates the new Point by subtracting <code>*this</code> 
            and <code>a_rhs</code> componentwise.

            \param a_rhs     Another Point
        */
        ACCEL_DECORATION inline Point operator-(const Point& a_rhs) const;

        /// Componentwise Point Multiplication Operator
        /**
            Creates the new Point by multiplying <code>*this</code> 
            and <code>a_rhs</code> componentwise.

            \param a_pt     Another Point
        */
        ACCEL_DECORATION inline Point operator*(const Point& a_pt) const;

        /// Componentwise Point Division Operator
        /**
            Creates the new Point by dividing <code>*this</code> 
            by <code>a_rhs</code> componentwise. Quotients are rounded down.
            Division of any component by 0 yields an error. 

            \param a_pt     Another Point
        */
        ACCEL_DECORATION inline Point operator/(const Point& a_pt) const;

        /// Componentwise Point Modulus Operator
        /**
            Creates the new Point by taking the modulus of  <code>*this</code> 
            by <code>a_rhs</code> componentwise. Quotients are rounded down.
            Modulo by 0 yields an error. 

            \param a_pt     Another Point
        */
        ACCEL_DECORATION inline Point operator%(const Point& a_pt) const;

        ///Scalar Addition Operator
        /**
            Creates a new Point by adding nref to each component of <code>*this</code>.

            \param a_value   An Integer scalar
        */
        inline Point operator+(int a_value) const;

        ///Scalar Subtraction Operator
        /**
            Creates a new Point by subtracting nref to each component of <code>*this</code>.

            \param a_value   An Integer scalar
        */
        inline Point operator-(int a_value) const;

        /// Scalar Multiplication Operator
        /**
            Creates a new Point by multiplying each component of <code>*this</code> by <code>a_value</code>.

            \param a_value   An Integer scalar
        */
        inline Point operator*(int a_value) const;

        /// Scalar Division Operator
        /**
            Creates a new Point by dividing each component of <code>*this</code> by <code>a_value</code>.
            Quotients are rounded down. Division of any component by 0 yields an error. 

            \param a_value   An Integer scalar
        */
        inline Point operator/(int a_value) const;

        /// Scalar Modulus Operator
        /**
            Creates a new Point by taking the modulus of each component of <code>*this</code> by <code>a_value</code>.
            Quotients are rounded down. Modulo of any component by 0 yields an error. 

            \param a_value   An Integer scalar
        */
        inline Point operator%(int a_value) const;

        /// In Place Componentwise Addition Operator
        /**
            Adds another Point componentwise to <code>*this</code>.

            \param a_pt     Another Point
        */
        ACCEL_DECORATION inline void operator+=(const Point& a_pt);

        /// In Place Componentwise Subtraction Operator
        /**
            Subtracts another Point componentwise from <code>*this</code>.

            \param a_pt     Another Point
        */
        ACCEL_DECORATION inline void operator-=(const Point& a_pt);

        /// In Place Componentwise Multiplication Operator
        /**
            Multiplies <code>*this</code> by another Point componentwise.

            \param a_pt     Another Point
        */
        ACCEL_DECORATION  inline void operator*=(const Point& a_pt);

        /// In Place Componentwise Division Operator
        /**
            Divides <code>*this</code> by another Point componentwise.
            Quotients are rounded down. Division of any component by 0 yields an error. 

            \param a_pt       Another Point
        */
        ACCEL_DECORATION inline void operator/=(const Point& a_pt);

        /// In Place Componentwise Modulus Operator
        /**
            Computes the modulus of <code>*this</code> by another Point componentwise.
            Quotients are rounded down. Module of any component by 0 yields an error.

            \param a_pt     Another Point
        */
        ACCEL_DECORATION inline void operator%=(const Point& a_pt);

        /// In Place Scalar Addition Operator
        /**
            Adds an integer to every component of <code>*this</code>.

            \param a_n  An integer.
        */
        inline void operator+=(int a_n);

        /// In Place Scalar Subtraction Operator
        /**
            Subtracts an integer from every component of <code>*this</code>.

            \param a_n  An integer.
        */
        inline void operator-=(int a_n);

        /// In Place Scalar Multiplication Operator
        /**
            Multiplies every component of <code>*this</code> by an integer.

            \param a_n  An integer.
        */
        inline void operator*=(int a_n);

        /// In Place Scalar Division Operator
        /**
            Divides every component of <code>*this</code> by an integer.
            Quotients are rounded down. Division by 0 yields an error.

            \param a_n  An integer.
        */
        inline void operator/=(int a_n);

        /// In Place Scalar Modulus Operator
        /**
            Computes the modulus of every component of *this by an integer.
            Modulo of 0 results in an error.

            \param a_n  An integer.
        */
        inline void operator%=(int a_n); 
      
        /// Compute Dot Product
        inline int dot(const Point& a_rhs) const;

        /// Coarsen Operator
        /**
            Returns a new Point coarsened by a_refRatio.
            This function is identical to any of the division operators.

            \param a_refRatio   A non-zero refinement ratio.
        */
        inline Point coarsen(unsigned int a_refRatio) const;
        
        /// Sum Operator
        /**
            Computes the sum of the entries in *this
        */
        ACCEL_DECORATION
        inline int sum() const;

        /// Absolute Value Sum Operator
        /**
            Computes the sum of the absolute values of the entries in *this
        */
        inline int sumAbs() const;

        inline int min() const;

        inline int max() const;

        inline Point abs() const;
        /// Isotropic Query
        /**
            Checks if all elements of *this are equal.
        */
        inline bool isotropic() const;
       
        /// Query Codimension
        /**
            Returns the codimensionality of *this (e.g. the number of num-zero entries)
        */
        inline int codim() const;
        
        /// Parallel Unit Vectors
        /**
            Returns an array of Point representing the basis vectors
            of the smallest vector space containing *this. If the ith element
            of *this is non-zero, the ith element of the output will be Basis(i).
            Otherwise, the ith element of the output will be Zeros().
        */
        inline std::array<Point, DIM> parallelUnit() const;

        /// Perpendicular Unit Vectors
        /**
            Returns an array of Point representing the basis vectors
            of the largest vector space not containing *this. If the ith element
            of *this is zero, the ith element of the output will be Basis(i).
            Otherwise, the ith element of the output will be Zeros().
        */
        inline std::array<Point, DIM> perpUnit() const;

        inline int firstNonZeroIndex() const;

        inline int lastNonZeroIndex() const;

        /// Coordinates of non-zero entries
        inline std::vector<int> coords() const;

        /// Coordinates of zero entries
        inline std::vector<int> perpCoords() const;

        /// Scaled Unit Vectors
        inline std::vector<Point> split() const;
        
        /// Returns a vector of Points each of which are this dotted into a subset of unit vectors
        /// The zero vector is omitted
        inline std::vector<Point> subset() const;

        /// Convert Point to Direction
        /** A "direction" is defined as a Point with values limited to 1, 0, and -1.
         */
        inline Point dir() const;
        /// Linear Size
        /**
             Returns the size of *this in bytes
        */
        inline size_t linearSize() const;

        /// Linear Out
        /**
            Writes from *this into a linear buffer of size <code>this->linearSize()</code>.
            
            \param a_buf    A buffer
        */
        inline void linearOut(char* a_buf) const;

        /// Linear In
        /**
            Reads to *this from a linear buffer of size <code>this->linearSize()</code>.
            
            \param a_buf    A buffer
        */
        inline void linearIn(const char* a_buf);

        ///@}
        //////////////////////////////////////////////////////////////////////////////////////////
        /** @name Utility */
        ///@{

        /// Print Function
        /**
             Output is formatted: <code>(p1,p2,...)</code>
        */
        inline void print() const;
        inline std::string str() const;
        ///@}


      
        int m_tuple[DIM]; ///<Integer coordinates of the Point
        
        template<typename... vars>
        ACCEL_DECORATION inline void unpack(int D, int i, vars... args)
        {
            if (D < DIM)
            {
                m_tuple[D] = i;
                unpack(D+1, args...);
            }
        }
        
    }; //end class Point
        
    template<>
    ACCEL_DECORATION inline void Point::unpack(int D, int i)
    {
        if (D < DIM)
        {
            m_tuple[D] = i;
        }
    }

    //////////////////////////////////////////////////////////////////////////////////////////
    /** @name External Operators */
    ///@{

    /// Stream Operator
    inline std::ostream& operator <<(std::ostream& a_os, const Point& a_pt);
    /// Stream Operator
  inline std::istream& operator >>(std::istream& a_os,  Point& a_pt);

    /// Premultiplication by scalar
    inline Point operator*(int a_scale, Point a_pt) { return (a_pt*a_scale); }

    /// Unary Negation
    inline Point operator-(Point a_pt) { return a_pt*(-1); }

    inline Point minPoint(Point a_p1, Point a_p2)
    {
        Point p;
        for (int ii = 0; ii < DIM; ii++)
        {
            p[ii] = std::min(a_p1[ii], a_p2[ii]);
        }
        return p;
    }

    inline Point maxPoint(Point a_p1, Point a_p2)
    {
        Point p;
        for (int ii = 0; ii < DIM; ii++)
        {
            p[ii] = std::max(a_p1[ii], a_p2[ii]);
        }
        return p;
    }

    inline Point absMaxPoint(Point a_p1, Point a_p2)
    {
        Point p;
        for (int ii = 0; ii < DIM; ii++)
        {
            p[ii] = std::max(abs(a_p1[ii]), abs(a_p2[ii]));
        }
        return p;
    }

    ///@}
} //end namespace Proto
#endif //end include guard