# Utility hecmw_part1

## hecmw_part1

hecmw_part1 is a utility software which divides a single domain mesh data into sub-domains and generates distributed mesh data for the parallel finite element method.

The software uses the HEC-MW library's data input function to divide single-domain mesh data into an arbitrary number of sub-domains The data is divided into two regions. In addition, HEC-MW library's data output function is used to generate "distributed mesh data", and the software developed with HEC-MW can analyze the data generated by hecmw_part1.

The hecmw_part1 has two types of domain decomposition methods: "node-based decomposition" and "element-based decomposition".

We have also implemented an interface to the METIS library, which applies graph theory to domain decomposition, so that the domain decomposition method using kMETIS and pMETIS in the library can be implemented. The system also enables segmentation. In addition, it is possible to set the overlapping depth between partial regions in the node-based segmentation.

### Domain segmentation technique

The following division methods are available for hecmw_part1.

#### RCB

It stands for Recursive Coordinate Bisection and is a method of dividing a region based on the size of the coordinate values. It is a fast and stable method, but its subregion is limited to $2^n$ . It is an effective method for simple shapes.

#### METIS

This open-sourced free software is widely used in the world because it is a fast and stable method and provides good region separation even for complex shapes. This software has an interface to the METIS library and allows you to perform region segmentation directly using pMETIS and kMETIS. You can download METIS from the following URL.

METIS - Serial Graph Partitioning and Fill-reducing Matrix Ordering

### Domain division type

hecmw_part1 supports the following two types of division of a single region mesh into subregions.

#### Nodal segmentation (Node-based segmentation)

As shown in Figure 1.3-1, this is a node-based region partitioning method, in which the only belonging subregion is determined for all nodes, and overlapping elements between adjacent subregions are created. Therefore, in node-based decomposition, each subregion possesses the following information about nodes and elements (Figure 1.3-2).

Fig. 1.3-1 Region segmentation per node

Figure 1.3-2 Nodes and elements held by each subregion (node-based segmentation)

• Nodes that belong to that subregion (internal nodes)
• Elements containing internal nodes
• Nodes that make up the elements, including internal nodes

It also possesses the following information on communication between adjacent sub-regions (communication table).

• Import nodes: Nodes within a subregion that belong to another subregion
• Export node: Internal node that is an import node of another sub-region
• Shared elements: elements that are shared with other subdomains

The import nodes, export nodes, and shared elements in the second subregion of Figure 1.3-1 are shown in Figures 1.3-3, 1.3-4, and 1.3-5.

Figure 1.3-3 Import nodes in the second sub-region.

Export nodes in the second sub-region.

Figure 1.3-5 Shared elements in the second subdomain.

#### Region division by elements (element-based division)

As shown in Fig. 1.3-6, region decomposition is performed on an element-by-element basis, and in this case, only one subregion is determined for every element, and overlapping nodes are generated between adjacent subregions. Hence, in element-based decomposition, each subregion has the following nodal points and element information (Figure 1.3-7).

Fig. 1.3-6 Region segmentation by element

Figure 1.3-7 Nodes and elements held by each subregion (element-based partitioning)

• Elements that belong to this subdomain (internal elements)
• Nodes that make up the internal elements
• Elements containing the nodes that make up the internal elements

It also possesses the following information on communication between adjacent sub-regions (communication table).

• Imported elements: elements in a subregion that belong to another subregion
• Export elements: internal elements that are import elements of other sub-regions
• Shared nodes: nodes that are shared with other subregions

The import element, export element, and shared nodes in the second subregion of Figure 1.3-7 are shown in Figure 1.3-8, Figure 1.3-9, and Figure 1.3-10.

Figure 1.3-8 Import elements in the second sub-region.

Figure 1.3-9 Export elements in the second sub-region.

Fig. 1.3-10 Shared nodes in the second sub-region.

In both types of domain division, the user does not need to consider the communication because the domain division utility automatically creates and writes its communication table to the distributed mesh data.

#### Variable overlap depth

The hecmw_part1 allows you to set the overlapping depth between subregions as you like (except when the region decomposition type is nodal decomposition). Normally, the overlap depth is set to 1. However, when SAI (Sparse Approximate Inverse) is used for preprocessing to solve contact and MPC constraint problems, the overlap depth needs to be increased.

#### Creating a UCD file for generating a domain division image

hecmw_part1 can generate a UCD file to display a region image in MicroAVS and so on.

#### Handling of contact points

hecmw_part1 can specify

CONTACT=[DEFAULT|AGGREGATE|DISTRIBUTE|SIMPLE]


for the contact point when dealing with a contact problem.

### Files required for execution

In order to execute hecmw_part1, the following files are required.

• Single-region mesh data for domain segmentation
• global control file
• Domain division utility control file

These files are described below.

#### Single-region mesh data file for domain segmentation

The data input function of the HEC-MW library is used for the data input function of this software, and the mesh data of a single region that can be input by this function can be divided into regions as input data.

#### global control file

This software uses the global control file of HEC-MW to specify the mesh data to be displayed. In order to run this software, you need to specify the following in the global control file.

• File name of the mesh data of the single area to be divided
• The file name header for the distributed mesh data to be created

The following is an example of the description of a global control file.

If the single region mesh data named mesh.dat is divided into the following three files, the global control file (hecmw_ctrl.dat) is written as follows: mesh.dist.0, mesh.dist.1... The description of the global control file (hecmw_ctrl.dat) is as follows.

# Definition of single region mesh data to be domain segmented
!MESH, NAME=part_in, TYPE=HECMW-ENTIRE
mesh.dat
# Define the Distributed Mesh Data to Create
!MESH, NAME=part_out, TYPE=HECMW-DIST
mesh.dist


Here, in the definition of the single region mesh data (the first !MESH in the first example), the string specified for the NAME option is fixed at part_in. In addition, in the definition of the distributed mesh data (the second !MESH in example 2), the string for the NAME option is fixed to part_out and the file format specifier for the TYPE option is fixed to HECMW-DIST. If these options do not contain the specified string, an error occurs.

#### Domain division utility control file

hecmw_part1 sets up the conditions of region separation such as the region separation method, the number of region divisions, and so on, in the region separation utility control file (hecmw_part_ctrl.dat). The following is how to write the control manual.

The default file name of this control file is hecmw_part_ctrl.dat.

In the Application Examples chapter, the contents of the utility control file for each example are shown. Please refer to them when you are writing.

##### line 1
!PARTITION, TYPE=<type>, METHOD=<method>, DOMAIN=<domain> [, optional parameter]

Parameter
TYPE Domain division type (required)
METHOD Domain decomposition method (required)
DOMAIN Number of division (required)
DEPTH Overlap depth (optional)
UCD Output UCD file for the segmented image (optional)
CONTACT
Parameter Parameter value Contents
TYPE NODE-BASED node-based division
ELEMENT-BASED element-based division
METHOD RCB RCB method, the division reference axis must be specified on line 2
KMETIS kMETIS
PMETIS pMETIS
DOMAIN number of divisions
DEPTH The overlap depth of the partial region (DEPTH=1 if omitted)
Cannot be specified when TYPE=ELEMENT-BASED
UCD UCD file name (can be abbreviated)
CONTACT DEFAULT
AGGREGATE
DISTRIBUTE
SIMPLE
##### Line 2 (required only if METHOD=RCB)
(Line 2) DIR1, DIR2, DIR3, ... (Specify the number of installments)

variable name attribute contents
DIRX C Division reference axis (specified by lowercase x, y, or z)
##### Example of a control file

Example 1

!PARTITION, TYPE=NODE-BASED, METHOD=RCB, DOMAIN=8, DEPTH=1, UCD=mesh.inp
x, y, z


Example 2

!PARTITION, TYPE=ELEMENT-BASED, METHOD=PMETIS, DOMAIN=32


### execution method

The start-up commands for this software are as follows.

\$ hecmw_part1 [-f <part_ctrl_filename>]


With the -f option, you can specify the file name of the utility control file for region partitioning. If this option is omitted, the utility control information is read from a file with the default file name (hecmw_part_ctrl.dat) in the execution directory.

Moreover, when hecmw_part1 is executed, the global control file is placed in the execution directory and the single region mesh data file is placed in the directory specified in the global control file.

### Application examples

#### Simple cube model (48 nodes x 48 nodes x 48 nodes)

• Element type: Hexahedron linear elements
• Number of nodes : 110,592
• Number of elements: 103,823
##### An example of a control file description for the domain division utility
!PARTITION, TYPE=NODE-BASED, METHOD=RCB, DOMAIN=64, UCD=cube.rcb.inp
x, y, z, x, y, z


Fig. 4.1-1 Domain decomposition utility application example 1: Simple cube model (Node-based decomposition, RCB method, number of edgecuts: 20,736/324,864)

##### An example of a control file description for the domain division utility
!PARTITION, TYPE=NODE-BASED, METHOD=KMETIS, DOMAIN=64, UCD=cube.kmetis.inp


Fig. 4.1-2 Domain decomposition utility application example 1: Simple cube model (node-based decomposition, kMETIS, edgecut number: 26,160/324,864)

#### Akamon (Hongo campus of the University of Tokyo) model

• Element type : Tetrahedral primary elements
• Number of nodes : 3,550
• Number of elements: 10,156
##### An example of a control file description for the domain division utility
!PARTITION, TYPE=NODE-BASED, METHOD=RCB, DOMAIN=32, UCD=akamon.rcb.inp
x, y, z, x, y


Fig. 4.2-1 Domain decomposition utility application example 2: Red gate model (nodal-based decomposition, RCB method, edgecut:4,396/17,180)

##### An example of a control file description for the domain division utility
!PARTITION, TYPE=NODE-BASED, METHOD=PMETIS, DOMAIN=32, UCD=akamon.kmetis.inp


Fig.4.2-2 Domain decomposition utility application example 2: Red gate model (nodal-based decomposition,pMETIS,edgetcut:2,119/17,180)

#### Honshu model

• Element type: triangular primary element
• Number of nodes : 21,285
• Number of elements: 40,548
##### Example of a control file description for the domain division utility
!PARTITION, TYPE=ELEMENT-BASED, METHOD=RCB, DOMAIN=64, UCD=honshu.rcb.inp
x, y, x, y, x, y


Fig.4.3-1 Utility application example 3: Honshu model (element-based decomposition, RCB method, edgecut:17,241/237,627)

##### Example of a control file description for the domain division utility
!PARTITION, TYPE=ELEMENT-BASED, METHOD=KMETIS, DOMAIN=64, UCD=honshu.kmetis.inp


Fig.4.3-2 Domain decomposition utility application example 3: Honshu model (element-based decomposition,kMETIS,edgecut:11,657/237,627)

#### Graphite Block Model

• Element type: primary hexahedron elements
• Number of nodes : 1,308
• Number of elements: 795
##### An example of a control file description for the domain division utility
!PARTITION, TYPE=NODE-BASED, METHOD=RCB, DOMAIN=4, DEPTH=1, UCD=carbon.1.inp
x, y


Fig.4.4-1 Application example of domain decomposition utility 4: Graphite block model (overlap depth change example, DEPTH=1)

##### An example of a control file description for the domain division utility
!PARTITION, TYPE=NODE-BASED, METHOD=RCB, DOMAIN=4, DEPTH=2, UCD=carbon.2.inp
x, y


Fig.4.4-2 Application example of domain decomposition utility 4: Graphite block model (overlap depth change example,DEPETH=2)

### error message

#### HECMW-PART-E0001: No such file or directory

The specified file does not exist.

#### HECMW-PART-E0002: File close error

An unexpected error occurred while closing the file.

#### HECMW-PART-E0003: Too long file name

The file name is too long.

#### HECMW-PART-E0004: NULL pointer was found

Illegal null pointer detected.

#### HECMW-PART-E0005: Invalid EOF is found

Unexpected EOF detected.

#### HECMW-PART-E0006: Invalid argument is found

Illegal arguments are detected.

#### HECMW-PART-E0101: Invalid token found

Invalid token detected.

#### HECMW-PART-E0111: 'TYPE' must not be omitted

Can't find 'TYPE', a mandatory option for '!PARTITION'

#### HECMW-PART-E0121: 'METHOD' must not be omitted

Can't find the required option 'METHOD' for '!PARTITION'

#### HECMW-PART-E0131: 'DOMAIN' must not be omitted

Missing 'DOMAIN', a mandatory option for '!PARTITION'

#### HECMW-PART-E0134: 'METHOD' is 'RCB', but 'DOMAIN' is not n-th power of 2

'RCB' is specified for 'METHOD', but the value of 'DOMAIN' is not a power of 2.

#### HECMW-PART-E0161: Partitioning directions are not enough

The direction of divisional axis is not specified enough.

#### HECMW-PART-E0201: Invalid partitioning type is found

We have detected an illegal domain split type.

#### HECMW-PART-E0202: Invalid partitioning method is found

We have detected an illegal domain division method.

#### HECMW-PART-E0203: Invalid element type is found

Illegal element type detected.

#### HECMW-PART-E0204: Invalid partitioning direction is found

Illegal split axis direction detected.

#### HECMW-PART-E0205: Invalid number of sub-domains is found

We have detected an illegal subspace count.

#### HECMW-PART-E0206: Invalid overlapping depth is found

Illegal inter-regional overlap depth detected

#### HECMW-PART-E0211: Stack overflow

The stack array overflowed.

#### HECMW-PART-E0301: Domain number is outside of the range

The number of partial regions exceeds the number of partial regions.

#### HECMW-PART-E0311: Number of nodes is outside of the range

Illegal node count detected.

#### HECMW-PART-E0312: Number of internal nodes is outside of the range

Illegal internal node count detected.

#### HECMW-PART-E0321: Number of elements is outside of the range

Illegal element count detected.

#### HECMW-PART-E0322: Number of internal elements is outside of the range

We have detected an illegal internal element count.

#### HECMW-PART-E0331: Number of neighboring sub-domains must be grater than or equal 0

The number of adjacent subregions is less than 0.

#### HECMW-PART-E0501: Log file has not initialized yet

Log files have not been initialized.

#### HECMW-PART-E9999: Fatal error

There was a serious error.

#### HECMW-PART-W0162: Too many partitioning directions are specified

More than the required number of axis directions are specified.

#### HECMW-PART-W0401: EQUATION_BLOCK is not found

Can't find the EQUATION_BLOCK.

#### HECMW-PART-W0502: Log file for practitioner has already initialized

The log file initialization process was called multiple times.