Sierra Toolkit  Version of the Day
Classes | Modules | Typedefs | Enumerations | Enumerator | Functions | Variables
Sierra Toolkit Mesh
Collaboration diagram for Sierra Toolkit Mesh:

Classes

class  stk_classic::mesh::GatherField< F, R >
 Field with defined data type and multi-dimensions (if any) More...
class  stk_classic::mesh::Bucket
 A container for the field data of a homogeneous collection of entities. More...
class  stk_classic::mesh::BulkData
 Manager for an integrated collection of entities, entity relations, and buckets of field data. More...
class  stk_classic::mesh::Entity
 A fundamental unit within the discretization of a problem domain, including but not limited to nodes, edges, sides, and elements. More...
class  stk_classic::mesh::EntityLess
 Comparison operator for entities compares the entities' keys. More...
union  stk_classic::mesh::EntityKey
 Integer type for the entity keys, which is an encoding of the entity type and entity identifier. More...
class  stk_classic::mesh::Field< Scalar, Tag1, Tag2, Tag3, Tag4, Tag5, Tag6, Tag7 >
 Field with defined data type and multi-dimensions (if any) More...
class  stk_classic::mesh::MetaData
 The manager of an integrated collection of parts and fields. More...
class  stk_classic::mesh::Part
 An application-defined subset of a problem domain. More...
struct  stk_classic::mesh::PartLess
 Ordering operator for parts. More...
struct  stk_classic::mesh::PartRelation
 A defined entity-relationship between parts. An internal class that should never need to be directly used within application code. More...
class  stk_classic::mesh::Property< void >
 Property base class with an anonymous data type and anonymous multi-dimension. More...
class  stk_classic::mesh::Property< DataType >
 Property with defined data type and multi-dimensions (if any) More...
class  stk_classic::mesh::Relation
 A relation between two mesh entities with a relation identifier and kind . More...
class  stk_classic::mesh::Selector
 This is a class for selecting buckets based on a set of meshparts and set logic. More...

Modules

 Mesh Entity Relationships
 

An seemingly simple relationship between two mesh entities has consequences for entity membership in parts and derived field relationships.


 Meta Data Field Dimension Tags
 

Mesh specific Array dimension tags for defining multi-dimensional array field data.


 Mesh Field Bulk Data
 

Computational data associated with the entities within a mesh.


 Bulk Data Parallel Distribution
 

Parallel distribution of mesh bulk data.


 Bulk Data Finite Element Entities
 

Create entities with common used finite element topologies.


Typedefs

typedef uint64_t stk_classic::mesh::EntityKey::raw_key_type
typedef std::vector< Part * > stk_classic::mesh::PartVector
 Collections of parts are frequently maintained as a vector of Part pointers.
typedef std::vector< unsigned > stk_classic::mesh::OrdinalVector
typedef Property< void > stk_classic::mesh::PropertyBase
typedef std::vector< Bucket * > stk_classic::mesh::BucketVector
typedef std::vector< Entity * > stk_classic::mesh::EntityVector
typedef unsigned stk_classic::mesh::Ordinal
typedef Ordinal stk_classic::mesh::EntityRank
typedef Ordinal stk_classic::mesh::PartOrdinal
typedef Ordinal stk_classic::mesh::FieldOrdinal
typedef Ordinal stk_classic::mesh::RelationIdentifier
typedef Ordinal stk_classic::mesh::FieldArrayRank
typedef uint64_t stk_classic::mesh::EntityId
typedef std::vector< Relation > stk_classic::mesh::RelationVector
 Span of a sorted relations for a given domain entity.
typedef PairIter
< RelationVector::const_iterator > 		stk_classic::mesh::PairIterRelation

Enumerations

enum  { rank_digits = 8 }
enum  stk_classic::mesh::FieldState {
  stk_classic::mesh::StateNone = 0,
  stk_classic::mesh::StateNew = 0,
  stk_classic::mesh::StateNP1 = 0,
  stk_classic::mesh::StateOld = 1,
  stk_classic::mesh::StateN = 1,
  stk_classic::mesh::StateNM1 = 2,
  stk_classic::mesh::StateNM2 = 3,
  stk_classic::mesh::StateNM3 = 4,
  stk_classic::mesh::StateNM4 = 5
}
 Enumeration of states for multi-state fields. More...
enum  { MaximumFieldStates = 6 }
 Maximum number of states that a field can have.
enum  { MaximumFieldDimension = 7 }
 Maximum multi-dimenaional array dimension of a field.
enum  stk_classic::mesh::EntityModificationLog {
  EntityLogNoChange = 0,
  EntityLogCreated = 1,
  EntityLogModified = 2,
  EntityLogDeleted = 3
}

Functions

std::ostream & stk_classic::mesh::operator<< (std::ostream &, const Bucket &)
 Print the part names for which this bucket is a subset.
std::ostream & stk_classic::mesh::print (std::ostream &, const std::string &indent, const Bucket &)
 Print the parts and entities of this bucket.
bool stk_classic::mesh::bucket_part_equal (const unsigned *lhs, const unsigned *rhs)
bool stk_classic::mesh::has_superset (const Bucket &, const Part &p)
 Is this bucket a subset of the given part.
bool stk_classic::mesh::has_superset (const Bucket &, const unsigned &ordinal)
 Is this bucket a subset of the given part by partID.
bool stk_classic::mesh::has_superset (const Bucket &, const PartVector &)
 Is this bucket a subset of all of the given parts.
std::vector< Bucket * >::iterator stk_classic::mesh::lower_bound (std::vector< Bucket * > &v, const unsigned *key)
std::string stk_classic::mesh::print_entity_key (const Entity &entity)
std::string stk_classic::mesh::print_entity_key (const Entity *entity)
 stk_classic::mesh::EntityKey::~EntityKey ()
 Destructor.
 stk_classic::mesh::EntityKey::EntityKey ()
 stk_classic::mesh::EntityKey::EntityKey (const EntityKey &rhs)
EntityKey & stk_classic::mesh::EntityKey::operator= (const EntityKey &rhs)
 stk_classic::mesh::EntityKey::EntityKey (EntityRank entity_rank, raw_key_type entity_id)
raw_key_type stk_classic::mesh::EntityKey::id () const
EntityRank stk_classic::mesh::EntityKey::rank () const
EntityRank stk_classic::mesh::EntityKey::type () const
bool stk_classic::mesh::EntityKey::operator== (const EntityKey &rhs) const
bool stk_classic::mesh::EntityKey::operator!= (const EntityKey &rhs) const
bool stk_classic::mesh::EntityKey::operator< (const EntityKey &rhs) const
bool stk_classic::mesh::EntityKey::operator> (const EntityKey &rhs) const
bool stk_classic::mesh::EntityKey::operator<= (const EntityKey &rhs) const
bool stk_classic::mesh::EntityKey::operator>= (const EntityKey &rhs) const
 stk_classic::mesh::EntityKey::EntityKey (const raw_key_type *const value)
raw_key_type stk_classic::mesh::EntityKey::raw_key () const
EntityRank stk_classic::mesh::entity_rank (const EntityKey &key)
 Given an entity key, return an entity type (rank).
EntityId stk_classic::mesh::entity_id (const EntityKey &key)
 Given an entity key, return the identifier for the entity.
bool stk_classic::mesh::entity_key_valid (const EntityKey &key)
 Query if an entity key is valid.
bool stk_classic::mesh::entity_id_valid (EntityKey::raw_key_type id)
size_t stk_classic::mesh::hash_value (EntityKey key)
template<class SELECTOR >
void stk_classic::mesh::get_buckets (const SELECTOR &selector, const std::vector< Bucket * > &input, std::vector< Bucket * > &output)
AllSelectedBucketsRange stk_classic::mesh::get_buckets (const Selector &selector, const BulkData &mesh)
AllBucketsRange stk_classic::mesh::get_buckets (const BulkData &mesh)
AllBucketsRange stk_classic::mesh::get_buckets (EntityRank entity_rank, const BulkData &mesh)
AllSelectedBucketsRange stk_classic::mesh::get_buckets (const Selector &selector, const AllBucketsRange &range)
void stk_classic::mesh::get_involved_parts (const PartVector &union_parts, const Bucket &candidate, PartVector &involved_parts)
void stk_classic::mesh::count_entities (const Selector &selector, const BulkData &mesh, std::vector< EntityRank > &count)
 Local count selected entities of each type.
void stk_classic::mesh::get_entities (const BulkData &mesh, EntityRank entity_rank, std::vector< Entity * > &entities)
 Get all entities of the specified type, sorted by ID.
BucketVectorEntityIteratorRange stk_classic::mesh::get_entities (EntityRank entity_rank, const BulkData &mesh)
unsigned stk_classic::mesh::count_selected_entities (const Selector &selector, const std::vector< Bucket * > &input_buckets)
 Count entities in selected buckets (selected by the given selector instance), and sorted by ID.
void stk_classic::mesh::get_selected_entities (const Selector &selector, const std::vector< Bucket * > &input_buckets, std::vector< Entity * > &entities)
 Get entities in selected buckets (selected by the given selector instance), and sorted by ID.
SelectedBucketRangeEntityIteratorRange stk_classic::mesh::get_selected_entities (const Selector &selector, const AllBucketsRange &bucket_range)
void stk_classic::mesh::compute_memory_usage (const BulkData &bulk, MemoryUsage &mem_usage)
void stk_classic::mesh::print_memory_usage (const MemoryUsage &mem_usage, std::ostream &os)
std::ostream & stk_classic::mesh::print_entity_key (std::ostream &os, const MetaData &meta_data, const EntityKey &key)
 Print an entity key for this meta data.
std::string stk_classic::mesh::print_entity_key (const MetaData &meta_data, const EntityKey &key)
void stk_classic::mesh::verify_parallel_consistency (const MetaData &, ParallelMachine)
 Verify that the meta data is identical on all processors.
bool stk_classic::mesh::is_internal (const std::string &part_name)
bool stk_classic::mesh::is_internal (const Part &part)
std::string stk_classic::mesh::convert_to_internal_name (const std::string &part_name)
void stk_classic::mesh::order (PartVector &)
 Order a collection of parts: invoke sort and then unique.
void stk_classic::mesh::order (OrdinalVector &v)
bool stk_classic::mesh::insert (PartVector &, Part &)
 Insert a part into a properly ordered collection of parts. Returns true if this is a new insertion.
bool stk_classic::mesh::insert_ordinal (OrdinalVector &v, unsigned part_ordinal)
void stk_classic::mesh::remove (PartVector &, Part &)
 Remove a part from a properly ordered collection of parts.
Part * stk_classic::mesh::find (const PartVector &, const std::string &)
 Find a part by name in a collection of parts.
bool stk_classic::mesh::contain (const PartVector &, const Part &)
 Query containment within properly ordered PartVector.
template<class Iterator >
bool stk_classic::mesh::contains_ordinal (Iterator beg, Iterator end, unsigned part_ordinal)
bool stk_classic::mesh::contain (const PartVector &, const PartVector &)
 Query containment for two properly ordered PartVector.
size_t stk_classic::mesh::intersect (const PartVector &, const PartVector &)
 Query cardinality of intersection of two PartVectors.
size_t stk_classic::mesh::intersect (const PartVector &, const PartVector &, PartVector &)
 Generate the intersection of two PartVectors.
bool stk_classic::mesh::intersect (const Part &, const Part &)
 Query if two parts intersect; i.e., if one is a subset of the other or they share a common subset.
std::ostream & stk_classic::mesh::print (std::ostream &, const char *const , const Part &)
 Print a part's information including supersets, subsets, and intersection. Each line starts with the given leader string.
std::ostream & stk_classic::mesh::operator<< (std::ostream &, const PropertyBase &)
 Print the text name for a field.
std::ostream & stk_classic::mesh::print (std::ostream &, const char *const , const PropertyBase &)
 Print field and field restrictions on new lines.
template<typename property_type >
const property_type::data_type * stk_classic::mesh::property_data (const property_type &prop, const Part &part)
 Query pointer to property data for a given part.
template<typename property_type >
property_type::data_type * stk_classic::mesh::property_data (property_type &prop, const Part &part)
 Query pointer to property data for a given part.
void stk_classic::mesh::get_entities_through_relations (const std::vector< Entity * > &entities, std::vector< Entity * > &entities_related)
 Query which mesh entities have a relation to all of the input mesh entities.
void stk_classic::mesh::get_entities_through_relations (const std::vector< Entity * > &entities, EntityRank entities_related_rank, std::vector< Entity * > &entities_related)
 Query which mesh entities have a relation to all of the input mesh entities of the given mesh rank.
bool stk_classic::mesh::membership_is_induced (const Part &part, unsigned entity_rank)
 Query if a member entity of the given entity type has an induced membership.
void stk_classic::mesh::induced_part_membership (Part &part, unsigned entity_rank_from, unsigned entity_rank_to, RelationIdentifier relation_identifier, OrdinalVector &induced_parts, bool include_supersets=true)
 Induce entities' part membership based upon relationships between entities. Insert the result into 'induced_parts'.
void stk_classic::mesh::induced_part_membership (const Entity &entity_from, const OrdinalVector &omit, unsigned entity_rank_to, RelationIdentifier relation_identifier, OrdinalVector &induced_parts, bool include_supersets=true)
 Induce entities' part membership based upon relationships between entities. Do not include and parts in the 'omit' list.
void stk_classic::mesh::induced_part_membership (const Entity &entity, const OrdinalVector &omit, OrdinalVector &induced_parts, bool include_supersets=true)
 Induce an entity's part membership based upon relationships from other entities. Do not include and parts in the 'omit' list.
std::ostream & stk_classic::mesh::operator<< (std::ostream &, const Relation &)
 Print the relation raw_relation_ids and referenced entity's key.
std::ostream & stk_classic::mesh::operator<< (std::ostream &out, const Selector &selector)
static BulkData & stk_classic::mesh::BulkData::get (const Bucket &bucket)
static BulkData & stk_classic::mesh::BulkData::get (const Entity &entity)
static BulkData & stk_classic::mesh::BulkData::get (const Ghosting &ghost)
static raw_relation_id_type stk_classic::mesh::Relation::raw_relation_id (unsigned rank, unsigned id)
 The encoded relation raw_relation_id.
unsigned stk_classic::mesh::Relation::entity_rank () const
 The rank of the referenced entity.
RelationIdentifier stk_classic::mesh::Relation::identifier () const
 The local relation identifier.
Selector operator& (const Part &A, const Part &B)
 
Selector operator& (const Part &A, const Selector &B)
 
Selector operator& (const Selector &A, const Part &B)
 
Selector operator& (const Selector &A, const Selector &B)
 
Selector operator| (const Part &A, const Part &B)
 
Selector operator| (const Part &A, const Selector &B)
 
Selector operator| (const Selector &A, const Part &B)
 
Selector operator| (const Selector &A, const Selector &B)
 
Selector operator! (const Part &A)
 
Selector selectUnion (const PartVector &union_part_vector)
 
Selector selectIntersection (const PartVector &intersection_part_vector)
 
Selector selectField (const FieldBase &field)
 Return a selector for the union of the parts where field exists.
 stk_classic::mesh::impl::EntityImpl::EntityImpl (const EntityKey &arg_key)

Variables

raw_key_type   stk_classic::mesh::EntityKey::@10::id: id_digits
raw_key_type   stk_classic::mesh::EntityKey::@10::rank: rank_digits
raw_key_type   stk_classic::mesh::EntityKey::@11::rank: rank_digits
raw_key_type   stk_classic::mesh::EntityKey::@11::id: id_digits
unsigned stk_classic::mesh::MemoryUsage::num_fields
unsigned stk_classic::mesh::MemoryUsage::field_bytes
unsigned stk_classic::mesh::MemoryUsage::num_parts
unsigned stk_classic::mesh::MemoryUsage::part_bytes
std::vector< std::string > stk_classic::mesh::MemoryUsage::entity_rank_names
std::vector< unsigned > stk_classic::mesh::MemoryUsage::entity_counts
unsigned stk_classic::mesh::MemoryUsage::bytes_per_entity
std::vector< unsigned > stk_classic::mesh::MemoryUsage::downward_relation_counts
std::vector< unsigned > stk_classic::mesh::MemoryUsage::upward_relation_counts
unsigned stk_classic::mesh::MemoryUsage::bytes_per_relation
std::vector< unsigned > stk_classic::mesh::MemoryUsage::bucket_counts
std::vector< unsigned > stk_classic::mesh::MemoryUsage::bucket_bytes
size_t stk_classic::mesh::MemoryUsage::total_bytes
static const char stk_classic::mesh::INTERNAL_PART_PREFIX = '{'
static const char stk_classic::mesh::INTERNAL_PART_POSTFIX = '}'
static const Ordinal stk_classic::mesh::InvalidOrdinal = static_cast<Ordinal>(-1)
static const EntityRank stk_classic::mesh::BaseEntityRank = 0
static const EntityRank stk_classic::mesh::InvalidEntityRank = InvalidOrdinal
static const PartOrdinal stk_classic::mesh::InvalidPartOrdinal = InvalidOrdinal
static const RelationIdentifier stk_classic::mesh::InvalidRelationIdentifier = InvalidOrdinal

Declare field data allocation rules

template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Part &part, const void *init_value=NULL)
 Declare a field to exist for a given entity type and Part.
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Selector &selector, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Part &part, unsigned n1, const void *init_value=NULL)
 Declare a field to exist for a given entity type and Part. The extra unsigned arguments specify the size of a dimension. So, put_field( field, rank, part, 3, 3 ) would create a 3x3 2D field. Fields of up to seven dimensions are supported.
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Selector &selector, unsigned n1, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Part &part, unsigned n1, unsigned n2, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Selector &selector, unsigned n1, unsigned n2, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Part &part, unsigned n1, unsigned n2, unsigned n3, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Selector &selector, unsigned n1, unsigned n2, unsigned n3, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Part &part, unsigned n1, unsigned n2, unsigned n3, unsigned n4, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Part &part, unsigned n1, unsigned n2, unsigned n3, unsigned n4, unsigned n5, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Part &part, unsigned n1, unsigned n2, unsigned n3, unsigned n4, unsigned n5, unsigned n6, const void *init_value=NULL)
template<class field_type >
field_type & stk_classic::mesh::put_field (field_type &field, EntityRank entity_rank, const Part &part, unsigned n1, unsigned n2, unsigned n3, unsigned n4, unsigned n5, unsigned n6, unsigned n7, const void *init_value=NULL)

Detailed Description

Introduction

The Sierra Toolkit Mesh supports parallel distributed, heterogeneous, and dynamically modifiable unstructured meshes with computational field data. Mesh data is partitioned into (1) meta data which describes an application's problem domain and (2) bulk data which implements a discretization of an application's problem domain.

A bulk data manager owns and manages an integrated collection of entities (e.g. nodes and elements), relations between entities (i.e. connectivity), and computational field data associated with entities of the mesh. Field data for homogeneous subsets of entities is aggregated into buckets, i.e. contiguous blocks of memory. A meta data manager owns and manages an integrated collection of parts and fields. A part defines an expected subset of entities in the problem domain. A field defines the expected computational field data for a discretization of the problem domain.

Simple Example

An application must first create a meta data manager. An application owns the meta data manager that it creates; however, a meta data manager owns its parts and fields. 

  using namespace stk_classic ;

  mesh::MetaData meta_mgr ; // Owned by the application

  // Declare my element and face parts:

  mesh::Part & my_part_a = meta_mgr.declare_part("A",mesh::Element);
  mesh::Part & my_part_b = meta_mgr.declare_part("B",mesh::Element);
  mesh::Part & my_side = meta_mgr.declare_part("S",mesh::Face);

An application defines types for the fields that it will use. The first template parameter of a field type is the numerical type of the field. The remaining template parameters (if any) define the ranks of the multidimensional array. In this example the TensorAtIntegrationField defines a rank-two (FORTRAN ordering) array where the first array index selects a tensor component and the second array index selects an integration point. 

  typedef mesh::Field<double>                        ScalarField ;
  typedef mesh::Field<double,Cartesian>              VectorField ;
  typedef mesh::Field<double,FullTensor>             TensorField ;
  typedef mesh::Field<double,FullTensor,Integration> TensorAtIntegrationField ;
  // Declare fields of a specified type

  ScalarField & my_field_u = meta_mgr.declare_field< ScalarField >("u");
  VectorField & my_field_v = meta_mgr.declare_field< VectorField >("v");
  TensorField & my_field_w = meta_mgr.declare_field< TensorField >("w");
  TensorAtIntegrationField & my_field_x = meta_mgr.declare_field< TensorAtIntegrationField >("x");

  meta_mgr.put_field( my_field_u , mesh::Node , my_part_a );
  meta_mgr.put_field( my_field_u , mesh::Node , my_part_b );
  meta_mgr.put_field( my_field_u , mesh::Face , my_part_s );

  meta_mgr.put_field( my_field_w , mesh::Element , my_part_a );
  meta_mgr.put_field( my_field_x , mesh::Element , my_part_b , 8 );

Fields of a given type are declared with a text name. This text name is intended to be used exclusively by input and output functions, and should be immediately forgotten by the application. The put_field method is used to associate fields with entities on specified parts. In this example the nodes of my_part_a and my_part_b , and faces of my_side will have a scalar field data for my_field_u ; the elements of my_part_a will have tensor field data for my_field_w ; and each element of my_part_b will have the eight tensor values associated with my_field_x .

After populating it parts and fields a meta data manager is committed, locking it against further changes. A bulk data object is created to manage entities, relations, and field data that are (1) conformal to a given meta data objects and (2) distributed among the processors of a parallel communicator (e.g., MPI_Comm). 

  meta_mgr.commit(); // Finished constructing meta data

  mesh::BulkData bulk_mgr( meta_mgr , communicator );

Mesh bulk data is created and managed with respect to a committed mesh meta data. This separates, and thus simplifies, concerns of meta data changes from bulk data changes.

At this point in an application mesh bulk data is typically read from a mesh file into the mesh bulk data, bulk_mgr . The typical access pattern for bulk data is to (1) iterate mesh entities of a given type (e.g., node or element) that belong to a given part and (2) operate on computational field data associated with the selected entities.

  std::vector< mesh::Bucket *> buckets ;
  // Get buckets for elements in <c> my_part_a </c>
  mesh::get_buckets( BucketSelector( my_part_a ) ,
                     bulk_mgr.buckets( mesh::Element ), buckets );

  for ( unsigned i = 0 ; i < buckets.size() ; ++i ) {
    mesh::Bucket & k = * buckets[i] ;

    // number of elements in this bucket:
    const unsigned n = k.size();

    // Pointer to field data for 'n' elements:
    double * const tensor = mesh::field_data( my_field_w , k );

    // Iterate the elements in the bucketa and the field data
    for ( unsigned j = 0 ; j < n ; ++j ) {
      mesh::Entity & element = * k[j] ;
      double * element_tensor = tensor + size_of_tensor * j ;
      // computations...
    }
  }

Mesh How To ...

Sierra Mesh

STK Mesh Documentation...

STK Mesh Documentation

Getting Started

API Reference

Working with STK (include development issues here?)

Community and Resources

Contributing

Licenses

  • BSD
  • Licenses Used in STK

First Steps

Demonstrations

  • Internal Force Calculation (Use Case 14)
  • Gears Demonstration & video

Installation

  • Use the Trilinos cmake installation instructions to install stk_mesh.

Class and Function Documentation

This page includes information on the classes and functions in STK. This page also includes a description of the namespace conventions in STK. This page also includes a description of the global objects in STK.

Modules and Extensions to STK

This page explains the various STK modules and extension points in STK.

Tutorials and Examples

How-To's and Best Practices

  • How-To's
    • How to create a fast-gather for nodal fields from an element?
    • How do I read from an exodus file?
    • How do I create a mesh by hand?
    • How do I create full topological adjacency entities in stk_mesh?
  • Design Decisions:
    • Why are parts used to determine bucket decomposition?
    • Why are attributes const?
    • Why is modified status propagated upward through relations?
    • Why can't we add parts after meta data is committed?
    • Why are attributes settable on meta data for parts, but you can only get them off of the parts?
    • etc.
  • Free Function Philosophy:
    • We endorse the use of free functions that provide the following benefits while outweighing the following disadvantages.
    • Benefits:
      • Provide extension without modification to the API in cooperation with the Open Closed Principle
      • Help encourage the Single Responsibility Principle and cohesion through a minimally defined API
    • Disadvantages:
      • Too many ways to do things
      • Too hard to find where the free functions are defined
      • Often belong in the user-space

Vocabulary

This page explains the vocabulary used in stk_mesh.

Building STK mesh

  • Sierra (bake or bjam)
  • Trilinos (cmake)

Running STK mesh

Unit Testing and Debugging

To run unit tests

  • Build the stk_mesh product and look for the unit test (name/loc will depend on if you build Sierra-style or Trilinos-style).
  • You can run the exectuble in serial or in parallel with MPI
  • You can select specific unit-tests to run using the --gtest_filter flag
    • Example, to run all Entity unit tests: <utest-exe> -- --gtest_filter=UnitTestEntity.*
    • Example, to run a specific unit test: <utest-exe> -- --gtest_filter=UnitTestEntity.testEntityKey

To debug unit tests

  • A unit-test can fail for a number of reasons
    • One of the macro assertions has failed; gtest will print the name of the failing unit test, line file and line number of the failing check, and some details about the failing check.
    • An uncaught exception was raised; the exception will be printed along with a stacktrace. Since Gtest prints test names as it starts them, it should be obvious which test caused the problem.
    • The program crashed, probably due to a segfault. Since Gtest prints test names as it starts them, it should be obvious which test caused the problem.
  • When debugging, it is usually best to only run the failing test (use gtest_filter to select the failing test)
  • Serial debugging can be done in gdb or totalview
    • GDB
      • gdb <utest-exe>
        • % run -- --gtest_filter=<failing-test>
    • Totalview
      • mpirun -np 1 -tv <utest-exe> -- --gtest_filter=<failing-test>
  • Parallel debugging should be done with totalview, but it is possible to do it with GDB as well
    • GDB
    • Totalview
      • mpirun -np <N> -tv <utest-exe> -- --gtest_filter=<failing-test>
      • To find where an exception is being generated, a common technique is to set a breakpoint at __cxa_throw
  • Debugging memory problems can be done with valgrind
    • In serial: valgrind <utest-exe> -- --gtest_filter=<failing-test>
    • In parallel it is more difficult
      • If you have access to the sntools, you can use mpigrind:
        • mpigrind mpirun -np <N> <utest-exe> -- --gtest_filter=<failing_test>
      • Otherwise, you'll have to create a script that runs the test under valgrind and then run mpirun on that script.

Unit test development

  • Individual Unit Tests:
    • Test one part of functionality at a time and put each test in its own STKUNIT_UNIT_TEST macro.
    • Name each test with a descriptive name.
    • Aim for short and concise unit tests that each fit on a single page
    • Use descriptive names for variables
    • Name/label all magic-numbers including 0 and 1.
    • Aim for positive logic in testing, try to be obvious
    • If using a complex fixture, use ascii art to document the fixture
    • If the unit_test is complex, have a comment at the top of the unit test describing what you're testing and why
  • General Notes:
    • Remember that these tests will be read 10x more than they're written (especially during refactoring)
    • Place code in namespace stk_classic::unit_test
    • Use namespaces judiciously to improve readability ( Prefer: using stk_classic::mesh::MetaData; over using namespace stk_classic; and namespace stk_classic { )
    • Avoid “unsigned” and use pre-defined typedefs instead (EntityRank, size_t, PartOrdinal, FieldOrdinal, etc…)
  • STKUNIT macros for verifying results inside STKUNIT_UNIT_TEST macro:
    • STKUNIT_EXPECT_* vs. STKUNIT_ASSERT_*, the ASSERT will stop the unit test at this line on failure.
    • Boolean values: STKUNIT_ASSERT_[EQ, NE, LE, LT, GE, GT, TRUE, FALSE]
    • String values: STKUNIT_ASSERT_[STREQ, STRNE, STRCASEEQ, STRCASENE] (CASE means ignore case)
    • Exceptions: STKUNIT_ASSERT_[THROW, NO_THROW]
    • Floating point values: STKUNIT_ASSERT_[DOUBLE_EQ, NEAR]

Software Architecture

  • The site Resources for Software Architects has excellent free documentation.
  • Domain Modeling expresses the requirements for software within a conceptual model of the problem domain. Such a model spans the software’s requirements, architectural design (the decomposition of software into architectural components and relationships among those components), and key concepts of the software design.

Should I continue to copy verbatim out of the wiki?

Online Resources

FAQ

  • How is Stk_mesh different from Moab?
  • How is Stk_mesh different from libMesh?

Developers

Support, Training and Services

  • For support, contact the Sierra Tool-Kit user email list: <stk-users@software.sandia.gov>
  • Our Tutorial and Training materials are currently under development
  • For Services, please contact our product owner: Mike Glass <mwglass@sandia.gov>

Report Bugs and Make Suggestions

Repository

  • The Sierra Tool-Kit repository is located at software.sandia.gov

Credits

BSD

  • The Sierra Tool-Kit is currently distributed with Trilinos under the BSD license.

Use Case 1

This is a hello world example for how to construct a stk mesh. First, these two headers need to be included: 

#include <stk_mesh/base/MetaData.hpp>
#include <stk_mesh/base/BulkData.hpp>
/// end code snippet
Then a simple class is created which contains MetaData and BulkData: 
class UseCase_1_Mesh
{
public:
  ~UseCase_1_Mesh();

  UseCase_1_Mesh( stk_classic::ParallelMachine comm );

  enum { SpatialDim = 1};
Second, we have the definition file with the bare minimum of includes: 
#include <use_cases/UseCase_1.hpp>

#include <stk_util/parallel/Parallel.hpp>

#include <stk_mesh/fem/FEMMetaData.hpp>
/// end code snippet
And here we have a small function which creates the vector of rank names for MetaData. 
 And finally we have the constructor which sets up MetaData and BulkData in a very trivial way: 
 


Typedef Documentation






      

        

          typedef std::vector<Relation> stk_classic::mesh::RelationVector
        

      







Span of a sorted relations for a given domain entity. 


The span is sorted by


    

  1. range entity rank,
    2. 

  2. relation identifier, and
    3. 

  3. range entity global identifier. 
    4. 




Definition at line 161 of file Types.hpp.







Enumeration Type Documentation






      

        

          enum stk_classic::mesh::FieldState
        

      







Enumeration of states for multi-state fields. 


A field may be declared to have field data for multiple states.


    

  • Field states StateNone, StateNew, or StateNP1 refer to the current or newest of a field.
    • 

  • Field states StateOld or StateN refer to the previous state of a field with two or more states.
      

    • The remaining field states StateNM1, StateNM2, StateNM3, StateNM4 refer to prior states N-1, N-2, N-3, and N-4 accordingly.
      • 

    

    • 



See Field.hpp for more. 


Enumerator: 


StateNone 

State of a field with one state. 




StateNew 

Newest state of a field with two states. 




StateNP1 

Newest state of a field with three+ states. 




StateOld 

Previous state of a field with two states. 




StateN 

Previous state of a field with three+ states. 




StateNM1 

Previous-1 state of a field with three+ states. 




StateNM2 

Previous-2 state of a field with four+ states. 




StateNM3 

Previous-3 state of a field with five+ states. 




StateNM4 

Previous-4 state of a field with six states. 











Definition at line 34 of file FieldState.hpp.











      

        

          enum stk_classic::mesh::EntityModificationLog
        

      






Change log to reflect change from before 'modification_begin' to the current status. 



Definition at line 77 of file Types.hpp.







Function Documentation






      

        

          stk_classic::mesh::EntityKey::EntityKey 
          (
          )
           [inline]
        

      






Default constructor. Note that entity_key_valid(key) == false if key is default-constructed. 



Definition at line 97 of file base/EntityKey.hpp.











      

        

          stk_classic::mesh::EntityKey::EntityKey 
          (
          EntityRank 
          entity_rank, 
        

        

          
          
          EntityKey::raw_key_type 
          entity_id 
        

        

          
          )
          
        

      






Constructor


Parameters:

  

    
entity_rankis required to lie in the range 0 to 255 (which is the limit of what can be stored in 8 bits). This limit may be raised if we decide to use more than 8 bits for encoding an entity-type.

    
entity_idis required to lie in the range 1 to 2^id_digits.

  

  




If entity_rank or entity_id lie outside these ranges an exception will be thrown. 



Definition at line 22 of file EntityKey.cpp.











      

        

          AllSelectedBucketsRange stk_classic::mesh::get_buckets 
          (
          const Selector & 
          selector, 
        

        

          
          
          const BulkData & 
          mesh 
        

        

          
          )
          
        

      






For all the buckets in the mesh, return a range of selected buckets. 



Definition at line 26 of file GetBuckets.cpp.











      

        

          AllBucketsRange stk_classic::mesh::get_buckets 
          (
          const BulkData & 
          mesh)
          
        

      






Return a range of all buckets in the mesh 



Definition at line 32 of file GetBuckets.cpp.











      

        

          AllBucketsRange stk_classic::mesh::get_buckets 
          (
          EntityRank 
          entity_rank, 
        

        

          
          
          const BulkData & 
          mesh 
        

        

          
          )
          
        

      






Return a range of buckets for a certain rank. 



Definition at line 37 of file GetBuckets.cpp.











      

        

          AllSelectedBucketsRange stk_classic::mesh::get_buckets 
          (
          const Selector & 
          selector, 
        

        

          
          
          const AllBucketsRange & 
          range 
        

        

          
          )
          
        

      






Return a range of selected buckets within a bucket range 



Definition at line 42 of file GetBuckets.cpp.











      

        

          void stk_classic::mesh::count_entities 
          (
          const Selector & 
          selector, 
        

        

          
          
          const BulkData & 
          mesh, 
        

        

          
          
          std::vector< EntityRank > & 
          count 
        

        

          
          )
          
        

      







Local count selected entities of each type. 


Parameters:

  

    
selector

    
mesh

    
count

  

  





Definition at line 113 of file GetEntities.cpp.













template<class field_type > 

      

        

          field_type& stk_classic::mesh::put_field 
          (
          field_type & 
          field, 
        

        

          
          
          EntityRank 
          entity_rank, 
        

        

          
          
          const Part & 
          part, 
        

        

          
          
          const void * 
          init_value = NULL 
        

        

          
          )
          
        

      







Declare a field to exist for a given entity type and Part. 


See Field.hpp for a full discussion of field restrictions. 











 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines