/********************************************************************** * PatchX.h * * Defines the abstract public interface to a user defined container class to * be used in a KeLP application. * Conformance to this interface is enforced by the internal use, by KeLP, of * of concrete member functions defined here or in an implementation of * a concrete Patch class. * Note that this file illustrates the minimum requirements for a KeLP 1.4 * compliant Patch class. For example, an application Patch may be templated * on the datatype it holds, but this is not required. A more practical example * is provided in a separate file, UserPatchX.h. * A Patch is not required to support random access, though it must support * copying over a regular section (including fields, if present). * A concrete patch class might include random access capability, but such * capability isn't required for the correct operation of the other KeLP * classes: FloorPlan, XArray, MotionPlan, and Mover * * A PatchX is a generalization of an X-dimensional array. * It has an associated rectangular bounding box, called the Region, but the * data do not necessarily form a uniform rectangular array. In particular, * it need not be defined over all the points of its Region. * A Patch may have one or more indexable solution fields, with a separate * index domain which is a KeLP Region1 * * * Programmer interface and implementation * * The simplest kind of Patch might be an ordinary rectangular array. * The KeLP distribution includes such a definition, Grid, which previously * had been supplied as part of KeLP. This definition may be used as a * starting point for implementing new Patch classes. We note, however, * that a Patch might be explicitly represented on only a subset of the Region. * * The implementer of a concrete Patch should use this file as a template. * Patch class implementations which conform to this specification are said * to comply with KeLP v. 1.4. * * PatchX.h specifies various member functions to implement * * o construction * o copying and serialization * * The PatchX specification requires that the following specific member * functions be defined. KeLP requires these functions in order to operate. * * PatchX() The PatchX Constructor * SerializeIn () Linearization (pack) * SerializeOut () Linearization (unpack) * LinearSize() Size of array needed by SerializeIn() * isPreallocatable() Whether the result of LinearSize() * can be determined from local information only * * Some of these members are abstract while others specify * certain actions that must take place. * * Since some users may choose not to use indexable Patch fields, * alternative forms of the above functionality is provided, that elides * fields specifiers * * A KeLP patch provides the user with considerable flexibility in defining * storage layout. In some cases, the region and field parameters to a * Patch constructor may not be sufficient to completely specify how much * storage needs to be allocated. For example, in embedded boundary methods, * the allocation of memory for the array depends on geometry information. A * natural way to communicate this information would be by passing the geometry * object to the Patch constructor, but then KeLP would have to know about that * detail of the application, which is undesirable. Should the user need to * work around this restrction, KeLP supports the notion of a DataFactory class. * The DataFactory is a generic wrapper which is defined by the user. The * constructor for a user-defined DataFactory class takes a user-determined list * of fields, and thus may have internal access to the additional state * required to perform the construction of the Patch. * * This file implements various member functions that query Patch attributes * that are common to all concrete instances. * It is strongly advised that an application Patch class not override these * concrete members, since the correct operation of KeLP depends on them. * Scott B. Baden, 9/14/99 * Modified Daniel Shalit 03/24/01 **********************************************************************/ #ifndef _included_PatchX_h #define _included_PatchX_h typedef int SIZE_T; class PatchX { private: dTYPE* _data //dTYPE may be intrinsic or user defined. RegionX _region; // The region Region1 _fields; // The range of the fields. // Note the internal use of the // Region1 specifier for fields. public: // // Constructors // PatchX( ) {} PatchX(const RegionX& region, Region1 fields = Region1(1,1), DataFactoryX& factory = DataFactoryX () ) : _region(region), _fields(fields){} //Note that the use of default arguments makes // myPatch(Region1 region) //perfectly legal // // Destructors // virtual ~PatchX(){} // // Functions for querying various patch attributes. These must be implemented // as shown since KeLP class methods depend them. // const Region1& fields() const { return _fields; } const int cs() const { return _fields.lower(0) ; } const int ce() const { return _fields.upper(0) ; } const int nFields() const { return fields().size(); } // // Bounds // const RegionX& region() const { return _region; } const PointX& lower() const { return _region.lower(); } const PointX& upper() const { return _region.upper(); } PointX extents() const { return _region.extents(); } const int lower(const int k) const { return _region.lower(k); } const int upper(const int k) const { return _region.upper(k); } const int extents(const int k) const { return _region.extents(k); } // This tells the user if the size of a serialized region of data // can be computed with local information only virtual const int isPreallocatable() const ; // // Functions to move data from/to PatchX /**************************************************************** virtual void Copy(const RegionX& Rd, const PatchX& Ps, const RegionX& Rs, const int csd=1, const int ced=1, const int css=1, const int ces = 1 ) Copy from (Ps on Rs over fields css through ces) into (*this on Rd over fields csd through ced) Various quantities in the source and destination must conform: Rs must lie wholly within Ps's Region Rd must lie wholly within *this's Region (css:ces) must be valid field indices for Ps (csd:ced) must be valid field indices for Pd ced - csd == ces - css Note that Rs and Rd need not necessarily have the same number of points Such a constraint might be required of an ordinary array class, and properly belongs in a concrete class definition rather than in Patch ***************************************************************/ virtual void Copy(const RegionX& Rd, const PatchX& Ps, const RegionX& Rs, const int csd=1, const int ced=1, const int css=1, const int ces = 1 ) ; // Returns the number of bytes required to store this Patch restricted // to the Region Rs over fields Rc.lower(0) through Rc.upper(0) virtual const SIZE_T LinearSize(const RegionX& Rs, const Region1& myFields) const ; // Pack the subset of Patch restricted to Region Rd and fields (cs:ce) // into previously allocated contiguous storage virtual void SerializeIn(void *Lptr, const RegionX& Rd, const int cs, const int ce) const ; // Unpack data previously Serialized in contiguous storage into an // existing patch virtual void SerializeOut(void *Lptr, const RegionX& Rs, const int cs, const int ce) ; }; #endif