namespace stk_classic {
namespace mesh {
}
}

/** \addtogroup stk_mesh_relations
 *
 * \section entity_relation Entity Relation
 *
 *  An \ref stk_classic::mesh::Relation "entity relation"
 *  defines a directed relationship between two
 *  \ref stk_classic::mesh::Entity "entities" <em>eA</em> and <em>eB</em>.
 *  This relationship is directed from the higher ranking
 *  entity to the lower ranking entity.
 *  \code
 *  if ( eA.entity_type() > eB.entity_type() ) {
 *    // relationship is from eA to eB
 *  }
 *  \endcode
 *
 *  Each \ref stk_classic::mesh::Relation "relationship" has two attributes:
 *  - a <em>local identifier</em> for the relation.
 *  - the <em>kind</em> of relation and
 *
 *  The identifier is <em>local</em> to the <em>from</em>
 *  entity of the relationship.  For example, a relationship
 *  from an element entity to a node entity is given local identifier
 *  according to the element topology's local numbering system
 *  for nodes.
 *  
 *  The kind attribute support and application-defined taxonomy
 *  of relationships.  For example,
 *  - kind == 0 : simple topological connectivity relationships,
 *  - kind == 1 : constraint relationships, or
 *  - kind == 2 : proximity relationships for contact tracking,
 *
 *
 * \section  Querying Relations
 *
 *  Each \ref stk_classic::mesh::Entity "entity" has a set of
 *  \ref stk_classic::mesh::Relation "relations" for which that
 *  entity is a member.
 *  Relations for which the entity is a <em>from</em> members
 *  or a <em>to</em> member are included.
 *
 *
 * \section entity_relation_stencil  Relation Stencil
 *
 *  An \ref stk_classic::mesh::relation_stencil_ptr "entity relation stencil"
 *  is a mapping of a relation <em>type</em> to an integer value.
 *  \code
 *    i = stencil( from_entity_type , to_entity_type , identifer , kind );
 *  \endcode
 *  If the returned integer value is non-negative then a relation
 *  of this type is in the domain of the map.  Otherwise it is not.
 *
 *  An \ref stk_classic::mesh::relation_stencil_ptr "entity relation stencil"
 *  is used to induce
 *  \ref stk_classic::mesh::Entity "entity" membership in
 *  \ref stk_classic::mesh::Part "parts" and to induce
 *  \ref stk_mesh_field_data "field data" pointer values from
 *  \ref stk_classic::mesh::Relation "entity relations". 
 *
 *
 * \section  Induced Part Membership
 *
 *  An \ref stk_classic::mesh::Entity "entity" is becomes a member of a
 *  \ref stk_classic::mesh::Part "mesh part" explicility via the
 *  \ref stk_classic::mesh::BulkData "mesh bulk data"
 *  \ref stk_classic::mesh::BulkData::change_entity_part "change entity parts"
 *  method, and when it membership is <em>induced</em>
 *  by its relationships.
 *
 *  Induced membership occurs as per the following simple type-based rule.
 *  - If <em>entity_from</em> is a explicitly a member of <em>part</em>, and
 *  - if <em>entity_from.entity_type() == part.primary_entity_type()</em>, and
 *  - if a relation exists from <em>entity_from</em> to <em>entity_to</em>
 *  - then <em>entity_to</em> is induced to be a member of <em>part</em>.
 *
 *  Induced membership may also occur as per the following stencil-based rule.
 *  - Let <em>( part_from , stencil , part_to )</em> be a
 *    \ref stk_classic::mesh::PartRelation "part relation".
 *  - Let <em>( entity_from , relation , entity_to )</em> be an
 *    \ref stk_classic::mesh::Relation "entity relation".
 *  - If <em>entity_from</em> is a explicitly a member of <em>part_from</em>,
 *    and
 *  - if <em>0 <= stencil( entity_from.entity_type() , entity_to.entity_type() ,
 *                         relation.identifier() , relation.kind() )
 *  - then <em>entity_to</em> is a member of <em>part_to</em>.
 *
 *  The negation holds for both of these induced membership rules:
 *  - In the type-based rule the <em>entity_to</em> cannot be a member
 *    of <em>part</em> unless the conditions of the type-based rule
 *    are satisfied.
 *  - In the stencil-based rule the <em>entity_to</em> cannot be a member
 *    of <em>part_to</em> unless the conditions of the stencil-based rule
 *    are satisfied.
 * 
 *
 * \section  Induced Field Relations
 *
 *  A \ref stk_classic::mesh::FieldRelation "field relation" is used to induce
 *  \ref stk_mesh_field_data "field data" relationships between related
 *  mesh entities.
 *
 *  If the following field relation conditions are satisfied
 *  - Let <em>field_from</em> be a pointer-valued field to the
 *    scalar data type of the <em>field_to</em> non-pointer valued field.
 *  - Let <em>( field_from , stencil , field_to )</em> be a
 *    \ref stk_classic::mesh::FieldRelation "field relation".
 *  - Let <em>( entity_from , relation , entity_to )</em> be an
 *    \ref stk_classic::mesh::Relation "entity relation".
 *  - If <em>entity_from</em> has field data for <em>field_from</em>, and
 *    if <em>entity_to</em> has field data for <em>field_to<em>, and
 *  - index = stencil( entity_from.entity_type() , entity_to.entity_type() ,
 *                     relation.identifier() , relation.kind() ), and
 *  - if <em>0 <= index < n</em> where <em>n</em> is the length
 *    of the field data on <em>entity_from</em>
 *  - then following field data relationship is maintained.
 *  \code
 *    field_data( field_from , entity_from )[ index ] =
 *      field_data( field_to , entity_to )
 *  \endcode
 *
 *  Note that the non-negative values of the <em>stencil</em> map must
 *  be unique over the domain of the stencil.
 */

