Assemblies

NOTE: The logical name of this concept would be group, but there is already an experimental group use in Exodus which use the NetCDF group implementation.

The existing experimental grouping concept is basically a hierarchy of Exodus (NetCDF) files inside an Exodus file. This group has never been officially released and I am probably the only one to use it, so an option would be to rename the existing Exodus experimental group to be file_group or db_group and then use group instead of assembly.

For now, the exodus grouping concept will be called assembly ** NOTE: In the description below, object type refers to a node, edge, face, side, or element set; or an edge face, or element block.

Motivation

Currently, the primary "grouping" entity in an exodus model is an element block which describes a collection of one or more elements of homogenous topology (i.e., all hexes or all tets or all quads). The model also contains a global "block" of nodes, and various sets and blocks consisting of nodes (sets only), edges, faces, and elements; however, the element block is the primary grouping mechanism.

As model complexity increases, a mesh (or exodus model) can contain tens to hundreds to thousands of element blocks. As geometric model complexity increases, it may be necessary to split geometric volumes or "parts" into multiple "meshable volumes" each of which becomes an individual element block (for example a complicated volume may be mostly meshable using hexes, but may in addition have a few areas that require tets and then some transition wedges from the tets to hexes. Since element blocks are homogenous topology, that part would consist of at least three element blocks). It can become very difficult for an analyst to remember the mapping from element blocks back to the geometric part in the solid model.

Another issue is that the assembly hierarchy in the original solid model or geometry is lost in the exodus file where there is simply a flat list of element blocks.

The assembly concept described herein is an attempt to solve these issues in the exodus model. An assembly will be a homogenous collection of one or more element blocks OR one or more assemblies. Note that a mixed collection of element blocks AND assemblies is not allowed. An assembly cannot contain itself, either directly or indirectly.

An assembly will have:

Member list. Either:
- non-empty list of element blocks belonging to assembly
- non-empty list of assemblies belonging to the assembly.
- non-empty homogeneous list of node, edge, face, side, or element sets is also allowed.
- non-empty homogeneous list of edge or face blocks is also allowed.
unique id (required, positive, unique among assemblies)
unique name (required, unique among all blocks/sets/assemblies)
zero or more named attributes (optional)
- See https://github.com/SandiaLabs/seacas/wiki/Entity-Attributes
- attribute is per assembly, not a value for each entity in the assembly.
- attribute can be of type--integer, char*, double.
- if type is integer or double, then there can be multiple values per attribute.
- NOTE: Named entity attributes can also be applied to other blocks and sets and GLOBAL.
transient data, zero or more named real variables which are output on each timestep. (optional)
- The variables are termed "reduction variables" since they are a single value per assembly.
- [UNDECIDED] The reduction variables can be unique to a specific assembly
- [UNDECIDED] Not all reduction variables must be on all assemblies.
- Names should be unique across all transient reduction variable names in the model.
- Value is per assembly, not per entity in the assembly.
- NOTE: transient reduction variables are also supported on all block and set objects.

Note that although the assembly feature will represent a directed acyclic graph of assemblies, blocks, and sets, the exodus file does not know how to manipulate this graph, do any queries based on the graph, or validate the graph. Exodus does not know about parent-child relations or roots or leaves of the tree/graph. The structure of this graph; however, will be able to be constructed based on the data stored in the exodus file.

Note that, conceptually, there is a "global assembly" which contains all element blocks in the model. The current "global variables" are in essence the reduction variables for this global assembly. Not sure yet if this provides any benefit in the implementation...

An assembly or object type can be in multiple assemblies. The structure is a directed acyclic graph
Assemblies will be homogenous -- all members of a specific assembly will be all element blocks or all assemblies or all same object type.
[UNDECIDED] An assembly or object type can appear multiple times in a single assembly. Potentially useful for a part containing multiple copies of a part -- perhaps offset for each instance. Example is a bolt circle of multiple instances of the same bolt each offset by a specified angle from a specified center point.

Parallel

The assembly data will be replicated on all processors--Each processor will have the same data.

Undecided

As implemented, any object type can be in an assembly. Must be homogenous type within an assembly.
- There are benefits to allowing assemblies of side sets, especially if move to using the Block Dominant models.
- What is homogenous in this case. Can an assembly contain an "assembly of element blocks" and an "assembly of sidesets" or is that a non-homogenous collection...? As implemented, can have an assembly containing an assembly of element blocks and an assembly of sidesets.

C API

[NOT YET IMPLEMENTED] Will also have to provide wrapper functions for the fortran API.

Determine number of assemblies on an exodus file:

 int num_assembly = ex_inquire_int(exoid, EX_INQ_ASSEMBLY);

Define number of assemblies which will be defined in an exodus file:

The number of assemblies does not need to be specified prior to defining an assembly.

Get / Put names of all assemblies or an individual assembly:

Assembly names are set and queried via the ex_put_assemblies and ex_get_assemblies functions. They are somewhat different from other object types in that the names are not defined via the ex_put_name calls. However, the names can be queried using ex_get_name() although it is recommended to use the ex_get_assembly() function.

 ex_get_name(exoid, EX_ASSEMBLY, assembly_id, name);
 ex_get_names(exoid, EX_ASSEMBLY,  names[]);

Define and output assembly

typedef struct ex_assembly
{
  int64_t        id;
  char           *name;
  ex_entity_type type; /* EX_ELEM_BLOCK or EX_ASSEMBLY or other valid object type */
  int64_t        entity_count;
  void_int       *entity_list;
} ex_assembly;

ex_put_assembly(exoid, ex_assembly assembly);
ex_put_assemblies(exoid, num_assembly, ex_assembly *assemblies);

Defines and outputs an assembly with id id and name name consisting of entity_count entities of type entity_type (EX_ASSEMBLY or EX_ELEM_BLOCK). The list of entity_count entities is given by the ids in entity_list. If entity_list is NULL, then only the "metadata" of the assembly is defined. A subsequent call to ex_put_assembly or ex_put_assemblies with a non-NULL entity_list is required to fully define the assembly.

NOTE: Efficiency -- it is more efficient to define multiple assemblies via a call to ex_put_assemblies() then to call ex_put_assembly() multiple times.

   /* conceptual; not real C code */
   ex_assembly assembly[3];
   assembly.id = {11, 22, 3};
   assembly.name = {"Fred", "Wilma", "BamBam"};
   assembly.type = {EX_ELEM_BLOCK, EX_ELEM_BLOCK, EX_ASSEMBLY};
   assembly.entity_count = {2, 2, 2};
   assembly[0].entity_list = {10, 20};
   assembly[1].entity_list = {30, 40};
   assembly[2].entity_list = {11, 22};
   ex_put_assemblies(exoid, 3, assembly);

Read all assemblies

   int num_assembly = ex_inquire_int(exoid, EX_INQ_ASSEMBLY);
   int64_t ids[num_assembly];
   ex_get_ids(exoid, EX_ASSEMBLY, ids);

   int name_len = ex_inquire_int(exoid, EX_INQ_DB_MAX_USED_NAME_LENGTH);
   struct ex_assembly assemblies[num_assembly];
   for (int i=0; i < num_assembly; i++) {
      assemblies[i].entity_list = NULL;
      assemblies[i].name = malloc(name_len + 1);
   } 
   /* Get parameters for all assemblies, but not entity_list */
   ex_get_assemblies(exoid, assemblies);

   for (i = 0; i < num_assembly; i++) {
      int entity_count = assemblies[i].entity_count;
      assemblies[i].entity_list = malloc(entity_count * sizeof(INT));
   }

   /* Now get the entity_lists */
   ex_get_assemblies(exoid, assemblies);

Define/Query assembly attributes and attribute names

See https://github.com/SandiaLabs/seacas/wiki/Entity-Attributes An assembly attribute is similar to an IOSS property consisting of a name, a type, and a value or values. It is not a value per entity in the assembly, but a value for the assembly. For now, they types will be limited to text, integer, and double to provide capability without the complexity of supporting the many types available in NetCDF-4 including user-defined types. Note that an attribute can have multiple values, for example if the attribute is a range, a single attributed could have two double values -- {1.0, 100.0}

Define/Query number of variables on an assembly

 ex_put_reduction_variable_param(exoid, EX_ASSEMBLY, num_variables);
 ex_get_reduction_variable_param(exoid, EX_ASSEMBLY, &num_variables);

Note that there will be a value written to and read from the database for all variables on all assemblies, but only the values corresponding to a defined variable will be valid values.

Define / Query names of variables on an assembly

 ex_put_reduction_variable_names(exoid, EX_ASSEMBLY, num_variables, names);
 ex_get_reduction_variable_names(exoid, EX_ASSEMBLY, num_variables, names);
 ex_put_reduction_variable_name(exoid, EX_ASSEMBLY, index, name);
 ex_get_reduction_variable_name(exoid, EX_ASSEMBLY, index, name);

Write / Read data for assembly variable(s) at a time step

All variables for a single assembly (with id id):

  ex_get_reduction_vars(exoid, step, EX_ASSEMBLY, id, num_assem_vars, values);
  ex_put_reduction_vars(exoid, step, EX_ASSEMBLY, id, num_assem_vars, values);

Representation options

In the examples that follow, assume for illustration that there are 3 assemblies and 4 element blocks. Assembly 11 is blocks 10 and 30; Assembly 22 is blocks 20 and 40; Assembly 33 is assemblies 11 and 22.

The assembly is represented with an explicit listing of the entity type (EX_ELEM_BLOCK or EX_ASSEMBLY), count, and a list of the ids of the entities.

	type	count	members
A1	element	2	10, 30
A2	element	2	20, 40
A3	assembly	2	11, 22

CDF Representation options

Assembly definition

variables:
# How are assemblies represented in the file:
# Note that assemblies are homogenous, so members are either all element blocks or all assemblies
# Each assembly is defined individually.  Either a set of element blocks or a set of assemblies
# Currently the assembly id is used in the names of the `dim` and `var` representing assemblies.
# This makes it easier to add new assemblies to an existing file.
# NOTE: Currently redundancy in `id` and in `_type` and `_typename`
	int assembly_entity100(num_entity_assembly100) ;
		assembly_entity100:_id = 100 ;
		assembly_entity100:_type = 16 ;
		assembly_entity100:_name = "Root" ;
		assembly_entity100:_typename = "assembly" ;

Assembly Attributes

variables:
	int assembly_entity100(num_entity_assembly100) ;
		assembly_entity100:_id = 100 ;
		assembly_entity100:_type = 16 ;
		assembly_entity100:_name = "Root" ;
		assembly_entity100:_typename = "assembly" ;
		assembly_entity100:Scale = 1.5 ;
		assembly_entity100:Units = 1, 0, 0, -1 ;

In the above, there are two user-defined attributes Scale which is a single double value and Units which is a set of 4 integers.

Assembly Reduction Variables

dimensions:
	num_assembly_red_var = 4 ;
variables:
	char name_assembly_red_var(num_assembly_red_var, len_name) ;
		name_assembly_red_var:_FillValue = "" ;
	double vals_red_var_assembly100(time_step, num_assembly_red_var) ;
data:
 vals_red_var_assembly100 =
  0.02, 0.03, 0.04, 0.05,
  0.04, 0.06, 0.08, 0.1,
  0.06, 0.09, 0.12, 0.15,
  0.08, 0.12, 0.16, 0.2,
  0.1, 0.15, 0.2, 0.25,
  0.12, 0.18, 0.24, 0.3,
  0.14, 0.21, 0.28, 0.35,
  0.16, 0.24, 0.32, 0.4,
  0.18, 0.27, 0.36, 0.45,
  0.2, 0.3, 0.4, 0.5 ;

Example Assembly Output/Input Code

See the files testwt-assembly.c, testrd-assembly.c and test-add-assembly.c in the packages/seacas/libraries/exodus/test directory.

Additional Changes

Distribution

Developed on branch exodus-blob
Branch merged into SEACAS/github master branch
Snapshot to Trilinos
Snapshot to Sierra
Inform Paraview Developers to they can support
Inform STK Developers
Inform CUBIT Developers

IOSS

Add an Assembly Ioss::GroupingEntity class
Read assembly information from Exodus file and create the assembly graph in an Ioss Region.
IOSS will know parent/child information so could support graph-structure queries.
Client can modify assembly structure which will be persisted to the output database.
- Modifying assembly structure of an input database will not modify structure in existing exodus file.

SEACAS Applications

Applications will need to be modified to support assemblies. Unless noted below, a SEACAS application will not know about assemblies or replicate them to an output file the application creates (i.e., assembly information will be lost).

Creation / Modification of Assemblies

Created io_modify which can add/modify the assembly information in an existing exodus file. For certain modification, the file is modified in place; other modifications require creating a new file.

Visualization:

Paraview Support
- Contacted and provided with a basic file containing assemblies of element blocks and assemblies of assemblies
Ensight Support

Provide feedback

Saved searches

Use saved searches to filter your results more quickly