TL;DR

• You can simply use a global mesh where its subdomains specified with domain attributes.
• With unit component meshes, you need to specify global configuration in a HDF5 format, which can be complex.
• We provide some useful python classes in utils/python to auto-generate hdf5-format global configuration.

scaleupROM exploits "attribute" feature of MFEM mesh format.

SubMesh topology handler

If the global mesh file is provided, MFEM's SubMesh supports splitting the global mesh into smaller child meshes, based on its domain attributes. As long as the mesh file specifies the attributes for all elements, no more information is needed for the global configuration.

Component topology handler

For component topology handler, only reference components are provided with MFEM meshes. Domain attributes in mesh files are not used. Global configuration and connection of the reference components are specified using the boundary attributes of the reference meshes.

Global configuration hdf5 data structure

The global configuration data is stored in HDF5 format. The hierarchy of the data structure is:

GROUP "/"
|- GROUP "components"
|  |- ATTRIBUTE "number_of_components": integer, number of components
|  |- ATTRIBUTE "0": string, name of 0-th component
|  |- ATTRIBUTE "1": string, name of 1st component
|  |- ...
|  |- DATASET "meshes": Array of integers, component index of each subdomain mesh
|  |- DATASET "configurations": 2d-array of doubles, global location of each subdomain mesh
|- DATASET "boundary": 2d-array of doubles, global boundary attributes of each subdomain mesh
|- GROUP "ports"
   |- ATTRIBUTE "number_of_references": integer, number of reference interfaces
   |- ATTRIBUTE "0": string, name of 0-th reference interface
   |- ATTRIBUTE "1": string, name of 1st reference interface
   |- ...
   |- GROUP "port0 name": data for 0-th reference interface
   |- GROUP "port1 name": data for 1st reference interface
   |- ...
   |- DATASET "interface": 2d array of integers, interface information of all global interfaces

Datasets in global config file

• /components/meshes: specifies the component index of each subdomain mesh used in the global configuration. The component index is listed as ATTRIBUTE of /components. For example,

      DATASET "meshes" {
         DATATYPE  H5T_STD_I64LE
         DATASPACE  SIMPLE { ( 3 ) / ( 3 ) }
         DATA {
         (0): 0, 1, 1
         }
      }

indicates the 3-mesh system where two reference components are used.

• /components/configurations: specify the global location/direction of each subdomain mesh. Each row is composed of 6 real numbers. The first 3 numbers correspond to translation of the mesh, while the last 3 numbers correspond to rotation of the mesh. Currently only the translation is supported. The following example shows the configuration of 3 meshes where the last 2 meshes are next to the first mesh:

      DATASET "configuration" {
         DATATYPE  H5T_IEEE_F64LE
         DATASPACE  SIMPLE { ( 3, 6 ) / ( 3, 6 ) }
         DATA {
         (0,0): 0, 0, 0, 0, 0, 0,
         (1,0): 1, 0, 0, 0, 0, 0,
         (2,0): 0, 1, 0, 0, 0, 0
         }
      }

• /boundary: specifies global boundaries using the boundary attributes of each subdomain meshes. Each row is composed of 3 integers:

[ component-battr, mesh-index, global-battr ]

An example boundary setup is:

   DATASET "boundary" {
      DATATYPE  H5T_STD_I64LE
      DATASPACE  SIMPLE { ( 10, 3 ) / ( 10, 3 ) }
      DATA {
      (0,0): 1, 0, 1,
      (1,0): 1, 1, 1,
      (2,0): 3, 1, 3,
      (3,0): 3, 2, 3,
      (4,0): 2, 1, 2,
      (5,0): 2, 2, 2,
      (6,0): 4, 0, 4,
      (7,0): 4, 2, 4,
      (8,0): 5, 1, 5,
      (9,0): 5, 2, 5
      }
   }

• /ports/interface: similar to /boundary, specify the pair of meshes and boundary attributes. each row is composed of 5 integers:

[ mesh1-index, mesh2-index, mesh1-battr, mesh2-battr, port-index ]

where available port-index are listed as ATTRIBUTE of /ports. An example interface setup is:

      DATASET "interface" {
         DATATYPE  H5T_IEEE_F64LE
         DATASPACE  SIMPLE { ( 2, 5 ) / ( 2, 5 ) }
         DATA {
         (0,0): 0, 1, 2, 4, 0,
         (1,0): 0, 2, 3, 1, 1
         }
      }

• /ports/port0 name, /ports/port1 name, ...: these groups contain the data for each reference interface. The name of each reference interface is specified in ATTRIBUTE of /ports with the corresponding port index. Each group has the following structure:

GROUP "k-th port name"
|- ATTRIBUTE "comp1": string, the name of component 1
|- ATTRIBUTE "comp2": string, the name of component 2
|- ATTRIBUTE "attr1": boundary attribute of component 1
|- ATTRIBUTE "attr2": boundary attribute of component 2
|- DATASET "comp2_configuration": array of 6 doubles, the relative configuration of component 2
                                                      with respect to component 1

The dataset comp2_configuration follows the same format of the rows in /components/configuration.

Using python scripts to generate global configuration files

Manually generating this global configuration file with complex structure is a tedious work. We provide some useful base python classes in utils/python/config.py. An application to box-shaped global configurations with random objects is also implemented in utils/python/box_channel_config.py. For example, the following python script with files from utils/python

# Copy the python files into the same working directory
import numpy as np
from copy import deepcopy
from config import Configuration, Empty, ObjectInSpace
from channel_config import ManhattanDistance
from box_channel_config import BoxChannelConfig

if __name__ == "__main__":
    comp_list = {'empty': Empty(),
                 'circle': ObjectInSpace('square-circle'),
                 'square': ObjectInSpace('square-square'),
                 'triangle': ObjectInSpace('square-triangle'),
                 'star': ObjectInSpace('square-star'),}

    example = BoxChannelConfig(2,2)
    for name, comp in comp_list.items():
        example.addComponent(comp)

    example.addMesh(1, 0) # add circle at first available location
    example.addMesh(0, 0) # add empty at first available location
    example.addMesh(2, 0) # add square at first available location
    example.addMesh(4, 0) # add star at first available location


    example.close()
    example.save('2x2_config.h5')

generates a global configuration file that is used in the tutorial for single run.