Proto
Proto::Box Class Reference

An interval in DIM dimensional space. More...

#include <Proto_Box.H>

Public Member Functions

Constructors
 Box ()
 Default Constructor. More...
 
Point boundary (const Side::LoHiSide a_side) const
 
Box faceBox (int a_idir, const Side::LoHiSide a_side) const
 
 Box (const Point &a_low, const Point &a_high)
 2 Point Constructor More...
 
 Box (const int *a_lo, const int *a_hi)
 Primitive Constructor. More...
 
void define (const int *a_lo, const int *a_hi)
 Define. More...
 
 Box (const Point &a_pt)
 1 Point (Origin) Constructor More...
 
 Box (const Box &a_box)
 Copy Constructor.
 
Accessors And Queries
Point low () const
 Access Low Corner. More...
 
Point high () const
 Access High Corner. More...
 
CUDA_DECORATION std::size_t size (unsigned char a_dim) const
 Edge Size. More...
 
CUDA_DECORATION std::size_t size () const
 Volumetric Size. More...
 
CUDA_DECORATION bool contains (const Point &a_pt) const
 Contains Point Query. More...
 
CUDA_DECORATION bool contains (const Box &a_rhs) const
 Contains Box Query. More...
 
bool onBoundary (const Point &a_p) const
 Point on Boundry Query. More...
 
CUDA_DECORATION bool empty () const
 Empty Query. More...
 
CUDA_DECORATION unsigned int index (const Point &a_pt) const
 Point to Linear Index. More...
 
CUDA_DECORATION Point operator[] (unsigned int a_index) const
 Access Point by Index. More...
 
CUDA_DECORATION Point operator() (unsigned int a_idx, unsigned int a_idy, unsigned a_idz) const
 
Operators
Box operator & (const Box &a_rightBox) const
 Intersection Operator. More...
 
void operator &= (const Box &a_rhs)
 In Place Intersection. More...
 
Box operator & (const Point &a_pt) const
 Add Point Operator. More...
 
void operator &= (const Point &a_pt)
 In Place Add Point Operator. More...
 
bool operator== (const Box &a_rhsBox) const
 Equality Operator. More...
 
bool operator!= (const Box &a_rhsBox) const
 Inequality Operator.
 
bool operator< (const Box &a_rhsBox) const
 < Operator. Based on same operator for Point applied to low corner. Used in Copier.
 
Point operator% (const Point &a_pt) const
 Modulus Operator. More...
 
Point mod (const Point &a_pt) const
 Modulus Function. More...
 
Transformations
Box shift (int a_direction, int a_offset) const
 Shift Transformation. More...
 
Box shift (const Point &a_pt) const
 Point Shift Transformation. More...
 
Box grow (int a_numpoints) const
 Isotropic Grow Operation. More...
 
Box grow (const Point &a_pt) const
 Anisotropic Grow Operation. More...
 
Box grow (int a_dir, int a_offset) const
 Anisotropic Grow (Int Version) More...
 
Box extrude (const Point &a_dir, int a_dist=1) const
 Extrude. More...
 
Box extrude (int a_dir, int a_dist=1, bool a_upper=true) const
 Extrude (Int Version) More...
 
Box growHi (int idir, int igrow) const
 Grow High Side. More...
 
Box growLo (int idir, int igrow) const
 Grow Low Side. More...
 
Box coarsen (unsigned int a_ratio) const
 Isotropic Coarsen Operation. More...
 
Box coarsen (const Point &a_pt) const
 Anisotropic Coarsen Operation. More...
 
bool coarsenable (const int &a_ratio) const
 (Isotropic) Coarsenable Query More...
 
bool coarsenable (const Point &a_ratio) const
 (Anisotropic) Coarsenable Query More...
 
Box taperCoarsen (const Point &a_ref) const
 Tapered Coarsen. More...
 
Box refine (const Point &a_pt) const
 Anisotropic Refine Operation. More...
 
Box refine (unsigned int a_ratio) const
 Isotropic Refine Operation. More...
 
Box edge (const Point &a_dir, int a_dist=1) const
 Edge. More...
 
Box flatten (const int a_dir, bool a_upper=false) const
 Flatten. More...
 
Box adjacent (const Point &a_dir, int a_dist=-1) const
 Adjacent Cells. More...
 
Box adjCellLo (int a_idir, int a_length) const
 Lower Adjacent Cells. More...
 
Box adjCellHi (int a_idir, int a_length) const
 Upper Adjacent Cells. More...
 
Box adjCellSide (int a_idir, int a_length, Side::LoHiSide a_sd) const
 
Utility
BoxIterator begin () const
 Iterator Begin. More...
 
BoxIterator end () const
 Iterator End. More...
 
BoxIterator rbegin () const
 Iterator Reverse Begin. More...
 
BoxIterator rend () const
 Iterator Reverse End. More...
 
void print () const
 Print. More...
 

Static Functions

static Box Cube (int a_size)
 
static Box Kernel (int a_radius)
 Kernel Function. More...
 

Detailed Description

An interval in DIM dimensional space.

A Box is a region in $ \bf{Z}^{DIM} $ specified by two corner Point objects, high and low INCLUSIVELY.
Equivalently, a Box is a collection of $DIM$ linear intervals in $\bf{Z}^{DIM}$ $[high[i] ,low[i]] : i \in [0,DIM)$.
Boxes are written using the notation [low, high] .

Constructor & Destructor Documentation

◆ Box() [1/4]

Proto::Box::Box ( )
inline

Default Constructor.

Builds the empty Box [(-1,-1,...,-1), (0,0,...,0)]

◆ Box() [2/4]

Proto::Box::Box ( const Point a_low,
const Point a_high 
)
inline

2 Point Constructor

Builds the non-trivial Box [low, high]

Parameters
a_lowlow corner
a_highhigh corner

◆ Box() [3/4]

Proto::Box::Box ( const int *  a_lo,
const int *  a_hi 
)
inline

Primitive Constructor.

Used for building a Box on platforms where plain-old-data is more convenient

Parameters
a_loC-Array representing this.low()
a_hiC-Array representing this.high()

◆ Box() [4/4]

Proto::Box::Box ( const Point a_pt)
inline

1 Point (Origin) Constructor

Builds the non-trivial Box [(0,...,0), a_pt]

Parameters
a_pthigh corner

Member Function Documentation

◆ adjacent()

Box Proto::Box::adjacent ( const Point a_dir,
int  a_dist = -1 
) const
inline

Adjacent Cells.

Returns a box adjacent to *this in a given direction with a thickness a_dist in the normal direction. If there are multiple non-zero entries in a_dir, a_dist will be applied to the thickness in all of those directions

Parameters
a_dir"Normal" direction of the desired adjacent cell
a_dist"thickness" of the desired adjacent cell

Examples:

//DIM = 2;
Box B0 = Box::Cube(8); // [(0,0) , (7,7)]
B0.adjacent((1,0) , 2); // [(8,0) , (9,7)]
B0.adjacent((0,-1), 2); // [(0,-2), (7,-1)]
B0.adjacent((-1,1), 2); // [(-2,8), (-1,9)]

◆ adjCellHi()

Box Proto::Box::adjCellHi ( int  a_idir,
int  a_length 
) const
inline

Upper Adjacent Cells.

Alias for adjacent(Point::Basis(a_idir), +1)

◆ adjCellLo()

Box Proto::Box::adjCellLo ( int  a_idir,
int  a_length 
) const
inline

Lower Adjacent Cells.

Alias for adjacent(Point::Basis(a_idir), -1)

◆ begin()

BoxIterator Proto::Box::begin ( ) const
inline

Iterator Begin.

See documentation for Proto::BoxIterator for a basic usage example.

◆ coarsen() [1/2]

Box Proto::Box::coarsen ( unsigned int  a_ratio) const
inline

Isotropic Coarsen Operation.

Returns a new Box coarsened by a factor of a_numpoints. Fails if user tries to coarsen using a non-positive ratio. If the limits of *this are not multiples of the coarsening ratio (e.g. if this-> coarsenable() != true) the resulting Box is not guaranteed to be a subset of *this. In this situation, use Box::taperCoarsen

Parameters
a_ratioCoarsening ratio

Example:

//DIM=2
using namespace Proto;
Box B0 = Box::Cube(4);
Box B1 = B0.coarsen(2);
B0.print(); //prints [(0, 0), (3, 3)]
B1.print(); //prints [(0, 0), (1, 1)]
Box B3 = B2.coarsen(2);
B2.print(); //prints [(2, 2), (4, 4)]
B3.print(); //prints [(1, 1), (2, 2)]

◆ coarsen() [2/2]

Box Proto::Box::coarsen ( const Point a_pt) const
inline

Anisotropic Coarsen Operation.

Returns a new Box coarsened in each direction according to a_pt. Fails if user tries to coarsen using a non-positive ratio. (*this).coarsen(a_pt).refine(a_pt) will always contain *this.

Parameters
a_ptCoarsening ratios

Example:

//DIM=2
using namespace Proto;
Box B0 = Box::Cube(4);
//coarsen in only the 1 direction
Box B1 = B0.coarsen(Point({1,2}));
B1.print(); //prints [(0,0),(3,1)]

◆ coarsenable() [1/2]

bool Proto::Box::coarsenable ( const int &  a_ratio) const
inline

(Isotropic) Coarsenable Query

Returns true if *this will coarsen normally by a given ratio.

Parameters
a_ratioCoarsening ratio

◆ coarsenable() [2/2]

bool Proto::Box::coarsenable ( const Point a_ratio) const
inline

(Anisotropic) Coarsenable Query

Returns true if *this will coarsen normally by a given ratio.

Parameters
a_ratioCoarsening ratio

◆ contains() [1/2]

CUDA_DECORATION bool Proto::Box::contains ( const Point a_pt) const
inline

Contains Point Query.

Checks if a_pt is inside of *this. Note that this->low() and this->high() are both considered inside *this

Example:

//DIM=2
using namespace Proto;
Box B(Point::Zeros(), Point({1,3}));
std::cout << B.contains(Point({0,0})) << std::endl; //prints true
std::cout << B.contains(Point({1,1})) << std::endl; //prints true
std::cout << B.contains(Point({1,3})) << std::endl; //prints true
std::cout << B.contains(Point({1,4})) << std::endl; //prints false

◆ contains() [2/2]

CUDA_DECORATION bool Proto::Box::contains ( const Box a_rhs) const
inline

Contains Box Query.

Check if Box a_rhs is a subset of *this. Returns true even if a_rhs is not a proper subset. Equivalent to this->contains(a_rhs.low()) && this->contains(a_rhs.high()

Example:

//DIM=2
using namespace Proto;
Box B0(Point({0,0}),Point({3,3}));
Box B1(Point({1,1}),Point({2,2}));
Box B2(Point({1,1}),Point({4,4}));
Box B2(Point({-1,-1}),Point({2,2}));
std::cout << B0.contains(B0) << std::endl; //prints true
std::cout << B0.contains(B1) << std::endl; //prints true
std::cout << B0.contains(B2) << std::endl; //prints false
std::cout << B0.contains(B3) << std::endl; //prints false

◆ Cube()

Box Proto::Box::Cube ( int  a_size)
inlinestatic

Cube Function Creates the Box [Point::Zeros(), Point::Ones()*(a_size-1)], a cube in $\bf{Z}^{DIM}$ of side length a_size

Parameters
a_sizeside length

◆ define()

void Proto::Box::define ( const int *  a_lo,
const int *  a_hi 
)
inline

Define.

Weak construct this Box if necessary

Parameters
a_loC-Array representing this.low()
a_hiC-Array representing this.high()

◆ edge()

Box Proto::Box::edge ( const Point a_dir,
int  a_dist = 1 
) const
inline

Edge.

Returns the subset on the boundary of *this in a given direction with specified thickness. Very handy for adjacency and boundary based computations. The returned Box is always a subset of *this

Parameters
a_dirDirection of desired edge with respect to the cell center of *this
a_distThickness of the output

Examples:

//DIM = 2
using namespace Proto;
auto B0 = Box::Cube(4).shift(Point::Ones()); //[(1,1), (4,4)]
auto B1 = B0.edge(Point::Basis(0)); //[(4,1), (4,4)]
auto B2 = B0.edge(Point::Ones(), 2); //[(3,3), (4,4)]
auto B3 = B0.edge(Point::Basis(1,-1), 2); //[(1,1), (4,2)]

◆ empty()

CUDA_DECORATION bool Proto::Box::empty ( ) const
inline

Empty Query.

Check if *this contains no Points

◆ end()

BoxIterator Proto::Box::end ( ) const
inline

Iterator End.

See documentation for Proto::BoxIterator for a basic usage example.

◆ extrude() [1/2]

Box Proto::Box::extrude ( const Point a_dir,
int  a_dist = 1 
) const
inline

Extrude.

AKA single sided grow. Returns a new Box with the a_dir direction extruded a distance a_dist </code). By default, the extrusion is upwards. If a_upper is false, extrudes downwards.

Parameters
a_dirAxis to extrude along
a_dist(Optional) Distance to extrude (default: 1)

Example:

//DIM=3
using namespace Proto;
Box B1 = B0.extrude(Point::Ones(), 2);
Box B2 = B0.extrude(Point::Basis(0,-1),3);
B0.print(); //prints [(1, 1, 1), (4, 4, 4)]
B1.print(); //prints [(1, 1, 1), (6, 6, 6)]
B2.print(); //prints [(-2, 1, 1), (4, 4, 4)]

◆ extrude() [2/2]

Box Proto::Box::extrude ( int  a_dir,
int  a_dist = 1,
bool  a_upper = true 
) const
inline

Extrude (Int Version)

AKA single sided grow. Returns a new Box with the a_dir direction extruded a distance a_dist </code). By default, the extrusion is upwards. If a_upper is false, extrudes downwards.

Parameters
a_dirAxis to extrude along
a_dist(Optional) Distance to extrude (default: 1)
a_upper(Optional) Extrude upwards? (default: true)

Example:

//DIM=2
using namespace Proto;
Box B1 = B0.extrude(2,3,false);
Box B2 = B0.extrude(2,3,true);
B0.print(); //prints [(1, 1, 1), (4, 4, 4)]
B1.print(); //prints [(1, 1, -2), (4, 4, 4)]
B2.print(); //prints [(1, 1, 1), (4, 4, 7)]

◆ flatten()

Box Proto::Box::flatten ( const int  a_dir,
bool  a_upper = false 
) const
inline

Flatten.

Returns a copy of *this with dimension a_dir flattened to a thickness of 1. Useful for creating Boxes of dimensionality less than DIM (e.g. a plane in 3D)

Parameters
a_dirDirection to flatten
a_upperFlatten upwards? Example:
//DIM=3
using namespace Proto;
Box B1 = B0.flatten(2);
Box B2 = B0.flatten(2,true);
B0.print(); //prints [(1, 1, 1), (4, 4, 4)]
B1.print(); //prints [(1, 1, 1), (4, 4, 1)]
B2.print(); //prints [(1, 1, 4), (4, 4, 4)]

◆ grow() [1/3]

Box Proto::Box::grow ( int  a_numpoints) const
inline

Isotropic Grow Operation.

Returns a new Box which is larger in every direction by a_numpoints units. If a_numpoints is negative, the box will shrink.

Parameters
a_numpointsnumber of points to grow by in each direction

Example:

//DIM=2
using namespace Proto;
Box B1 = B0.grow(3);
Box B2 = B1.grow(-2);
B0.print(); //prints [(0, 0), (1, 1)]
B1.print(); //prints [(-3,-3), (4, 4)]
B2.print(); //prints [(-1,-1), (2, 2)]

◆ grow() [2/3]

Box Proto::Box::grow ( const Point a_pt) const
inline

Anisotropic Grow Operation.

Returns the reshaped Box: [low() - a_pt, high() + a_pt] To grow a grow a box only upwards / downwards, see Box::extrude.

Parameters
a_ptgrowth offset

Example:

//DIM=2
using namespace Proto;
Box B1 = B0.grow(Point({-1,1})); //shrink in dimension 0, grow in dimension 1
B0.print(); //prints [(0, 0), (3, 3)]
B1.print(); //prints [(1, -1), (2, 4)]

◆ grow() [3/3]

Box Proto::Box::grow ( int  a_dir,
int  a_offset 
) const
inline

Anisotropic Grow (Int Version)

Returns grow(Point::Basis(dir, offset)) Useful in places where plain-old-data inputs are preferable. To grow a grow a box only upwards / downwards, see Box::extrude.

Parameters
a_dirA direction in [0,DIM)
a_offsetDistance to grow

◆ growHi()

Box Proto::Box::growHi ( int  idir,
int  igrow 
) const
inline

Grow High Side.

Alias for Box::extrude(idir, igrow, true).

◆ growLo()

Box Proto::Box::growLo ( int  idir,
int  igrow 
) const
inline

Grow Low Side.

Alias for Box::extrude(idir, igrow, false).

◆ high()

Point Proto::Box::high ( ) const
inline

Access High Corner.

This function returns by value; a Box cannot be altered through the output of high().

◆ index()

CUDA_DECORATION unsigned int Proto::Box::index ( const Point a_pt) const
inline

Point to Linear Index.

Returns a linear index in [0,this->size()) associated with a_pt. Fails by assertion if a_pt is not inside *this. Indices start at this->low() which has an index of 0. Indices increase fastest in dimension 0 and slowest in dimension DIM-1. this->high() has an index of this->size()-1

Parameters
a_pta Point inside *this

◆ Kernel()

Box Proto::Box::Kernel ( int  a_radius)
inlinestatic

Kernel Function.

Creates a Box of size 2*a_radius + 1 on all sides with (0,...,0) at the center. Useful for iterating through boundary cells.

Parameters
a_radiusthe number of "rings" of cells around the center cell.

Example:

//DIM=2
using namespace Proto;
auto K0 = Box::Kernel(1);
K0.print(); // [(-1,-1), (1, 1)]
auto K1 = Box::Kernel(2);
K1.print(); // [(-2, -2), (2, 2)]

◆ low()

Point Proto::Box::low ( ) const
inline

Access Low Corner.

This function returns by value; a Box cannot be altered through the output of low().

◆ mod()

Point Proto::Box::mod ( const Point a_pt) const
inline

Modulus Function.

Returns the periodic image of a_pt that is inside *this.

Parameters
a_ptPoint divisor

Example:

//DIM = 2;
using namespace Proto;
Box B = Box::Cube(3);
std::cout << B.mod(Point({3,3})) << std::endl; //prints (1,1)
std::cout << B.mod(Point({-1,-1})) << std::endl; //prints (2,2)

◆ onBoundary()

bool Proto::Box::onBoundary ( const Point a_p) const
inline

Point on Boundry Query.

Check of a_p is part of the boundry of this Box.

Parameters
a_pA Point

◆ operator &() [1/2]

Box Proto::Box::operator& ( const Box a_rightBox) const
inline

Intersection Operator.

Returns a new Box which is the intersection of *this and *a_rightBox.

Parameters
a_rightBoxAnother Box

Example:

//DIM=2
using namespace Proto;
Box B0 = Box::Cube(3);
Box B2 = B0 & B1;
B0.print(); //prints [(0,0),(2,2)]
B1.print(); //prints [(1,1),(3,3)]
B2.print(); //prints [(1,1),(2,2)]

◆ operator &() [2/2]

Box Proto::Box::operator& ( const Point a_pt) const
inline

Add Point Operator.

Returns a new Box which has been grown such that it contains a_pt. if this->contains(a_pt> this function returns *this.

Parameters
a_ptPoint to be added

Example:

//DIM=2
using namespace Proto;
auto B0 = Box::Cube(3);
B0.print(); //[(0,0), (2,2)]
Point p(-1,3);
auto B1 = B0 & p;
B1.print(); //[(-1,0), (2,3)]

◆ operator &=() [1/2]

void Proto::Box::operator&= ( const Box a_rhs)
inline

In Place Intersection.

Performs intersection on *this with a_rhs

Parameters
a_rhsAnother Box

◆ operator &=() [2/2]

void Proto::Box::operator&= ( const Point a_pt)
inline

In Place Add Point Operator.

Alters *this so that it now includes a_pt. If this->contains(a_pt), this function does nothing.

Parameters
a_ptA Point

◆ operator%()

Point Proto::Box::operator% ( const Point a_pt) const
inline

Modulus Operator.

Convenience operator for Box::mod(...). Returns the periodic image of a_pt contained in *this

Parameters
a_ptA Point to mod by

◆ operator==()

bool Proto::Box::operator== ( const Box a_rhsBox) const
inline

Equality Operator.

Two Boxes are considered equal if they have identical (==) low() and high()

Parameters
a_rhsBoxA Box to test equality with

◆ operator[]()

CUDA_DECORATION Point Proto::Box::operator[] ( unsigned int  a_index) const
inline

Access Point by Index.

Return a Point associated with a_index . This is the inverse of the index(Point) function.

Parameters
a_indexan index in [0,this->size())

◆ print()

void Proto::Box::print ( ) const
inline

Print.

Prints *this using the format [low, high]

◆ rbegin()

BoxIterator Proto::Box::rbegin ( ) const
inline

Iterator Reverse Begin.

See documentation for Proto::BoxIterator for a basic usage example.

◆ refine() [1/2]

Box Proto::Box::refine ( const Point a_pt) const
inline

Anisotropic Refine Operation.

Returns a new Box refined in each direction according to a_pt.

Parameters
a_ptRefinement ratios

Example:

//DIM=2
using namespace Proto;
Box B0 = Box::Cube(2);
Box B1 = B0.refine(Point({1,2}));
B0.print(); //prints [(0, 0), (1, 1)]
B1.print(); //prints [(0, 0), (1, 3)]

◆ refine() [2/2]

Box Proto::Box::refine ( unsigned int  a_ratio) const
inline

Isotropic Refine Operation.

Returns a new Box refined in all directions by a_numpoints.

Parameters
a_ratioRefinement ratio

Example:

//DIM=2
using namespace Proto;
Box B0 = Box::Cube(2);
Box B1 = B0.refine(2);
B0.print(); //prints [(0, 0), (1, 1)]
B1.print(); //prints [(0, 0), (3, 3)]
Box B3 = B2.coarsen(2);
B2.print(); //prints [(1, 1), (2, 2)]
B3.print(); //prints [(2, 2), (5, 5)]

◆ rend()

BoxIterator Proto::Box::rend ( ) const
inline

Iterator Reverse End.

See documentation for Proto::BoxIterator for a basic usage example.

◆ shift() [1/2]

Box Proto::Box::shift ( int  a_direction,
int  a_offset 
) const
inline

Shift Transformation.

Creates a new Box shifted in a_direction by a_offset units relative to *this.

Parameters
a_directionan int in /f$[0,DIM)/f$ specifying a direction
a_offsetnumber of points to offset. Use a negative value for a negative offset.

Example:

//DIM=2
using namespace Proto;
Box B1 = Box::Cube(2);
Box B2 = B1.shift(0,1);
Box B3 = B1.shift(1,-1);
B1.print(); //prints [(0,0), (1,1)]
B2.print(); //prints [(1,0), (2,1)]
B3.print(); //prints [(0,-1), (1,0)]

◆ shift() [2/2]

Box Proto::Box::shift ( const Point a_pt) const
inline

Point Shift Transformation.

Creates a new Box shifted by a_pt relative to *this. New Box is: [low() + a_pt, high() + a_pt]

Parameters
a_ptshift offset

Example:

//DIM=2
using namespace Proto;
Box B2 = B1.shift(Point({2,-3}));
B1.print(); //prints [(0,0), (1,1)]
B2.print(); //prints [(2,-3), (3,-2)]

◆ size() [1/2]

CUDA_DECORATION std::size_t Proto::Box::size ( unsigned char  a_dim) const
inline

Edge Size.

Returns the "edge length" of this Box on a given axis

/param a_dim direction axis in [0,DIM)

Example:

//DIM=2
using namespace Proto;
Box B(Point::Zeros(), Point({1,3}));
B.print(); //prints [(0,0),(1,3)]
std::cout << B.size(0) << std::endl; //prints 2
std::cout << B.size(1) << std::endl; //prints 4

◆ size() [2/2]

CUDA_DECORATION std::size_t Proto::Box::size ( ) const
inline

Volumetric Size.

Returns the "volume" (in number of points) of this box.

Example:

//DIM=2
using namespace Proto;
Box B(Point::Zeros(), Point({1,3}));
B.print(); //prints [(0,0),(1,3)]
std::cout << B.size() << std::endl; //prints 8 (=2*4)

◆ taperCoarsen()

Box Proto::Box::taperCoarsen ( const Point a_ref) const
inline

Tapered Coarsen.

This function is identical to Box::coarsen when Box::coarsenable() is true. For non-coarsenable Boxes, the new Box's limits are rounded such that the result Is always a subset of *this. Specifically, the lower limits are always rounded UP.

Parameters
a_refCoarsening ratio

The documentation for this class was generated from the following file: