Sierra Toolkit Version of the Day
Sierra Toolkit Mesh
Collaboration diagram for Sierra Toolkit Mesh:

Classes

class  stk::mesh::GatherField< F, R >
 Field with defined data type and multi-dimensions (if any) More...
class  stk::mesh::BucketIterator
 A random access iterator for a bucket that dereferences to a entity reference. More...
class  stk::mesh::Bucket
 A container for the field data of a homogeneous collection of entities. More...
class  stk::mesh::BulkData
 Manager for an integrated collection of entities, entity relations, and buckets of field data. More...
class  stk::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::mesh::EntityLess
 Comparison operator for entities compares the entities' keys. More...
union  stk::mesh::EntityKey
 Integer type for the entity keys, which is an encoding of the entity type and entity identifier. More...
class  stk::mesh::Field< Scalar, Tag1, Tag2, Tag3, Tag4, Tag5, Tag6, Tag7 >
 Field with defined data type and multi-dimensions (if any) More...
class  stk::mesh::MetaData
 The manager of an integrated collection of parts and fields. More...
class  stk::mesh::Part
 An application-defined subset of a problem domain. More...
struct  stk::mesh::PartLess
 Ordering operator for parts. More...
struct  stk::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::mesh::Property< void >
 Property base class with an anonymous data type and anonymous multi-dimension. More...
class  stk::mesh::Property< DataType >
 Property with defined data type and multi-dimensions (if any) More...
class  stk::mesh::Relation
 A relation between two mesh entities with a relation identifier and kind . More...
class  stk::mesh::Selector
 This is a class for selecting buckets based on a set of meshparts and set logic. More...
class  stk::mesh::Transaction
 Transaction journal of modifications to the bulk data during a transaction. Since the modification transaction guarantees a path independent result of mesh entities when modification_end() is called, the transaction just notes the state of altered mesh entities when the transaction was started. 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
boost::transform_iterator
< To_Ptr, BucketIterator > 
stk::mesh::BucketPtrIterator
typedef std::vector< BucketList > stk::mesh::Transaction::BucketListByType
 Bucket containers used to sort mesh entities by state so that they can be accessed after modification_end()
typedef std::set< Part * > stk::mesh::Transaction::PartSet
 Part list for tracking bulk transactions.
typedef std::vector< Part * > stk::mesh::PartVector
 Collections of parts are frequently maintained as a vector of Part pointers.
typedef Property< void > stk::mesh::PropertyBase
typedef std::vector< Bucket * > stk::mesh::BucketVector
typedef std::vector< Entity * > stk::mesh::EntityVector
typedef unsigned stk::mesh::Ordinal
typedef Ordinal stk::mesh::EntityRank
typedef Ordinal stk::mesh::PartOrdinal
typedef Ordinal stk::mesh::FieldOrdinal
typedef Ordinal stk::mesh::RelationIdentifier
typedef Ordinal stk::mesh::FieldArrayRank
typedef uint64_t stk::mesh::EntityId
typedef PairIter< std::vector
< Relation >::const_iterator > 
stk::mesh::PairIterRelation
 Span of a sorted relations for a given domain entity.
typedef std::vector< Relation > stk::mesh::RelationVector

Enumerations

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

Functions

std::ostream & stk::mesh::operator<< (std::ostream &, const Bucket &)
 Print the part names for which this bucket is a subset.
std::ostream & stk::mesh::print (std::ostream &, const std::string &indent, const Bucket &)
 Print the parts and entities of this bucket.
bool stk::mesh::bucket_part_equal (const unsigned *lhs, const unsigned *rhs)
bool stk::mesh::has_superset (const Bucket &, const Part &p)
 Is this bucket a subset of the given part.
bool stk::mesh::has_superset (const Bucket &, const unsigned &ordinal)
 Is this bucket a subset of the given part by partID.
bool stk::mesh::has_superset (const Bucket &, const PartVector &)
 Is this bucket a subset of all of the given parts.
std::vector< Bucket * >::iterator stk::mesh::lower_bound (std::vector< Bucket * > &v, const unsigned *key)
std::string stk::mesh::print_entity_key (const Entity &entity)
std::string stk::mesh::print_entity_key (const Entity *entity)
 stk::mesh::EntityKey::~EntityKey ()
 Destructor.
 stk::mesh::EntityKey::EntityKey ()
 stk::mesh::EntityKey::EntityKey (const EntityKey &rhs)
EntityKey & stk::mesh::EntityKey::operator= (const EntityKey &rhs)
 stk::mesh::EntityKey::EntityKey (EntityRank entity_rank, raw_key_type entity_id)
raw_key_type stk::mesh::EntityKey::id () const
EntityRank stk::mesh::EntityKey::rank () const
EntityRank stk::mesh::EntityKey::type () const
bool stk::mesh::EntityKey::operator== (const EntityKey &rhs) const
bool stk::mesh::EntityKey::operator!= (const EntityKey &rhs) const
bool stk::mesh::EntityKey::operator< (const EntityKey &rhs) const
bool stk::mesh::EntityKey::operator> (const EntityKey &rhs) const
bool stk::mesh::EntityKey::operator<= (const EntityKey &rhs) const
bool stk::mesh::EntityKey::operator>= (const EntityKey &rhs) const
 stk::mesh::EntityKey::EntityKey (const raw_key_type *const value)
raw_key_type stk::mesh::EntityKey::raw_key () const
EntityRank stk::mesh::entity_rank (const EntityKey &key)
 Given an entity key, return an entity type (rank).
EntityId stk::mesh::entity_id (const EntityKey &key)
 Given an entity key, return the identifier for the entity.
bool stk::mesh::entity_key_valid (const EntityKey &key)
 Query if an entity key is valid.
bool stk::mesh::entity_id_valid (EntityKey::raw_key_type id)
void stk::mesh::get_buckets (const Selector &selector, const std::vector< Bucket * > &input, std::vector< Bucket * > &output)
AllSelectedBucketsRange stk::mesh::get_buckets (const Selector &selector, const BulkData &mesh)
AllBucketsRange stk::mesh::get_buckets (const BulkData &mesh)
AllBucketsRange stk::mesh::get_buckets (EntityRank entity_rank, const BulkData &mesh)
AllSelectedBucketsRange stk::mesh::get_buckets (const Selector &selector, const AllBucketsRange &range)
void stk::mesh::get_involved_parts (const PartVector &union_parts, const Bucket &candidate, PartVector &involved_parts)
void stk::mesh::count_entities (const Selector &selector, const BulkData &mesh, std::vector< EntityRank > &count)
 Local count selected entities of each type.
void stk::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::mesh::get_entities (EntityRank entity_rank, const BulkData &mesh)
unsigned stk::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::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::mesh::get_selected_entities (const Selector &selector, const AllBucketsRange &bucket_range)
void stk::mesh::compute_memory_usage (const BulkData &bulk, MemoryUsage &mem_usage)
void stk::mesh::print_memory_usage (const MemoryUsage &mem_usage, std::ostream &os)
std::ostream & stk::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::mesh::print_entity_key (const MetaData &meta_data, const EntityKey &key)
void stk::mesh::verify_parallel_consistency (const MetaData &, ParallelMachine)
 Verify that the meta data is identical on all processors.
void stk::mesh::order (PartVector &)
 Order a collection of parts: invoke sort and then unique.
bool stk::mesh::insert (PartVector &, Part &)
 Insert a part into a properly ordered collection of parts. Returns true if this is a new insertion.
void stk::mesh::remove (PartVector &, Part &)
 Remove a part from a properly ordered collection of parts.
Part * stk::mesh::find (const PartVector &, const std::string &)
 Find a part by name in a collection of parts.
bool stk::mesh::contain (const PartVector &, const Part &)
 Query containment within properly ordered PartVector.
bool stk::mesh::contain (const PartVector &, const PartVector &)
 Query containment for two properly ordered PartVector.
size_t stk::mesh::intersect (const PartVector &, const PartVector &)
 Query cardinality of intersection of two PartVectors.
size_t stk::mesh::intersect (const PartVector &, const PartVector &, PartVector &)
 Generate the intersection of two PartVectors.
bool stk::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::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::mesh::operator<< (std::ostream &, const PropertyBase &)
 Print the text name for a field.
std::ostream & stk::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::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::mesh::property_data (property_type &prop, const Part &part)
 Query pointer to property data for a given part.
void stk::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::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::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::mesh::induced_part_membership (Part &part, unsigned entity_rank_from, unsigned entity_rank_to, RelationIdentifier relation_identifier, PartVector &induced_parts)
 Induce entities' part membership based upon relationships between entities. Insert the result into 'induced_parts'.
void stk::mesh::induced_part_membership (const Entity &entity_from, const PartVector &omit, unsigned entity_rank_to, RelationIdentifier relation_identifier, PartVector &induced_parts)
 Induce entities' part membership based upon relationships between entities. Do not include and parts in the 'omit' list.
void stk::mesh::induced_part_membership (const Entity &entity, const PartVector &omit, PartVector &induced_parts)
 Induce an entity's part membership based upon relationships from other entities. Do not include and parts in the 'omit' list.
std::ostream & stk::mesh::operator<< (std::ostream &, const Relation &)
 Print the relation raw_relation_ids and referenced entity's key.
std::ostream & stk::mesh::Transaction::print_stream (std::ostream &os) const
 Pretty print the transaction.
const BucketList & stk::mesh::Transaction::get_modified_buckets (unsigned type) const
 Retrieve buckets of a particular type that contain modified entities.
const BucketList & stk::mesh::Transaction::get_deleted_buckets (unsigned type) const
 Retrieve buckets of a particular type that contain deleted entities.
const BucketList & stk::mesh::Transaction::get_inserted_buckets (unsigned type) const
 Retrieve buckets of a particular type that contain inserted entities.
void stk::mesh::Transaction::get_parts_with_modified_entities (PartVector &pv) const
 Retrieve a part vector of parts whose entities were modified.
void stk::mesh::Transaction::get_parts_with_deleted_entities (PartVector &pv) const
 Retrieve a part vector of parts from which entities were deleted.
void stk::mesh::Transaction::get_parts_with_inserted_entities (PartVector &pv) const
 Retrieve a part vector of parts into which entities were inserted.
std::ostream & stk::mesh::operator<< (std::ostream &os, const Transaction &rhs)
void stk::mesh::print_bucket_list (const BucketList &, std::ostream &)
 Pretty print helper.
static BulkData & stk::mesh::BulkData::get (const Bucket &bucket)
static BulkData & stk::mesh::BulkData::get (const Entity &entity)
static BulkData & stk::mesh::BulkData::get (const Ghosting &ghost)
static raw_relation_id_type stk::mesh::Relation::raw_relation_id (unsigned rank, unsigned id)
 The encoded relation raw_relation_id.
unsigned stk::mesh::Relation::entity_rank () const
 The rank of the referenced entity.
RelationIdentifier stk::mesh::Relation::identifier () const
 The local relation identifier.
Selector stk::mesh::Selector::operator& (const Part &A, const Part &B)
 
Selector stk::mesh::Selector::operator& (const Part &A, const Selector &B)
 
Selector stk::mesh::Selector::operator& (const Selector &A, const Part &B)
 
Selector stk::mesh::Selector::operator& (const Selector &A, const Selector &B)
 
Selector stk::mesh::Selector::operator| (const Part &A, const Part &B)
 
Selector stk::mesh::Selector::operator| (const Part &A, const Selector &B)
 
Selector stk::mesh::Selector::operator| (const Selector &A, const Part &B)
 
Selector stk::mesh::Selector::operator| (const Selector &A, const Selector &B)
 
Selector stk::mesh::Selector::operator! (const Part &A)
 
Selector stk::mesh::Selector::selectUnion (const PartVector &union_part_vector)
 
Selector stk::mesh::Selector::selectIntersection (const PartVector &intersection_part_vector)
 
Selector stk::mesh::Selector::selectField (const FieldBase &field)
 Return a selector for the union of the parts where field exists.

Variables

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

Friends

class stk::mesh::Transaction::BulkData
std::ostream & stk::mesh::Transaction::operator<< (std::ostream &os, const Transaction &rhs)

Declare field data allocation rules

template<class field_type >
field_type & stk::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::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::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::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::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::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::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::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 ;

  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...

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::unit_test
    • Use namespaces judiciously to improve readability ( Prefer: using stk::mesh::MetaData; over using namespace stk; and namespace stk { )
    • 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::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 PairIter< std::vector<Relation>::const_iterator > stk::mesh::PairIterRelation

Span of a sorted relations for a given domain entity.

The span is sorted by

  1. range entity rank,
  2. relation identifier, and
  3. range entity global identifier.

Definition at line 159 of file Types.hpp.


Enumeration Type Documentation

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.

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

Definition at line 76 of file Types.hpp.


Function Documentation

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

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

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

stk::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::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 38 of file GetBuckets.cpp.

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

Return a range of all buckets in the mesh

Definition at line 44 of file GetBuckets.cpp.

AllBucketsRange stk::mesh::get_buckets ( EntityRank  entity_rank,
const BulkData &  mesh 
)

Return a range of buckets for a certain rank.

Definition at line 49 of file GetBuckets.cpp.

AllSelectedBucketsRange stk::mesh::get_buckets ( const Selector &  selector,
const AllBucketsRange &  range 
)

Return a range of selected buckets within a bucket range

Definition at line 54 of file GetBuckets.cpp.

void stk::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 109 of file GetEntities.cpp.

template<class field_type >
field_type& stk::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