feelpp_mesh_partitioner(1)

1. NAME

feelpp_mesh_partitioner - a mesh partitioner for Feel++

2. SYNOPSIS

feelpp_mesh_partitioner [--json file.json] --part num [num2…] --ifile file [--dim d] [--shape s] [--order num] [--splitting array] [--ofile file] [--odir dir]

3. DESCRIPTION

feelpp_mesh_partitioner is a simple application which can generate a partitioned mesh and save it in a Feel++ specific json+hdf5 file format.

The generated mesh can then be loaded very efficiently in parallel.

3.1. Options

feelpp_mesh_partitioner requires some options.

Table 1. Table of command-line feelpp_mesh_partitioner options
Name	Description	Default value
dim	dimension of the mesh	3
shape	shape of the mesh elements	Simplex
order	mesh geometric order	1
splitting	partitioning each subdomain specified with the markers
part	number of desired partitions
ifile	name or path to the mesh
ofile	output filename prefix (without extension)
odir	output directory
json	json file that describes the partitioning
export-visualization	boolean allow to enable/disable export of mesh with partitioning(s)

4. EXAMPLES

4.1. Generating a single mesh partitioning

We generate a mesh partitioned on 4 cores with the following command

feelpp_mesh_partitioner --part 4  --ifile /usr/share/feelpp/data/geo/torus.geo --odir torus_partitioning

You should have in the current directory 4 files

ls torus_partitioning/
torus_p4.h5  torus_p4.json

Now the file torus_p4.json can be loaded in a Feel++ application distributed on 4 cores.

Others file generated by the application (msh file from geo, log, …) are located into the app directory (which is controled by directory option)

4.2. Generating multiple mesh partitioning

Often we are interested in a set of partitioned meshes in order to do a speed-up study. feelpp_mesh_partitioner is the right tool for that. Let’s consider a set of partitions \(\mathcal{P}=\{2, 4, 8, 16, 32 \}\).

feelpp_mesh_partitioner --part 2 4 8 16 32  --ifile  /usr/share/feelpp/data/geo/torus.geo --odir torus_partitioning

You should have in the directory torus_partitioning (thanks to the odir option) 5 partitioned meshes

ls torus_partitioning
torus_p16.h5  torus_p16.json  torus_p2.h5  torus_p2.json  torus_p32.h5  torus_p32.json  torus_p4.h5  torus_p4.json  torus_p8.h5  torus_p8.json

The mesh filenames contain the partition information.

If you want a different prefix than torus, like torus-coarse, you can use the --ofile torus-coarse option and you will have a set of files named torus-coarse_p*.* in the torus_partitioning directory.

4.3. Export partitioning for visualization

Mesh partitioning visualization can be usefull feature for checking the generated partitioned mesh and its potential properties. Enable the export of partitiong can be done by setting option export-visualization or JSON entry visualization-exporter.enabled to the boolean true. By default, export is disabled.

If more than one partitioning is required, then the export visualuation see each partitioning as a time step (time will be the number of partition).

| export-visualization | boolean allow to enable/disable export of mesh with partitioning(s) |

4.4. Using json setup

A JSON can be given to feelpp_mesh_parititoner in order to configure the partitioner. This JSON data is defined by the json option, which represents the JSON file path. An exemple of JSON file is shown below.

{
    "input":{
        "filename":"$cfgdir/domain2d.geo" (1)
    },
    "output":{
        "directory":"examples/case2d" (2)
    },
    "visualization-exporter":{
        "enabled":true (3)
    },
    "partitioner":
    {
        "number-of-partition":[5,8,13,21,58,265], (4)
        "splitting":[ "OmegaTE","OmegaHT", ["OmegaHT2","OmegaHT3","OmegaTE2"] ] (5)
    }
}

1	input mesh filename : geo, msh, json+hdf5, … all format supported by Feel++
2	output directory of partitioned mesh file. Relative path represents path in application directory (i.e. customisable by `directory` option )
3	enable the visualization exporter
4	number of partition to generated (integer or array of integer)
5	splitting definitions from mesh marker names

4.5. Generating a mesh partitioning by subdomains

In some cases, it can be necessary to apply a partitioning on several subdomains (a splitting of the global domain). The partitioner/splitting entry of JSON setup or 'splitting' option allow to define this feature. The value described an array of subdomain, with each subdomain defined by an marker name or an array of marker name (union).

If the splitting definition does not represent the whole mesh, i.e. union of each subdomain is not equal to mesh domain, regions not include will have a partion id equal to 0.

With the command line, we need to put special quotes between the splitting definition, as in the following code snippet

--splitting='["OmegaTE","OmegaHT",["OmegaHT2","OmegaHT3","OmegaTE2"]]'

4.6. Aggregating elements of a mesh

For some numerical methods, it is necessary to aggregate elements that share faces marked with a specific marker. This is done to

avoid these faces are also interprocess faces
avoid having degrees of freedom split over different processes

To do so we use the --json option to specify the partitioning.

The following code will aggregate the elements of the spheres marked with CenterSphere, LeftSphere and RightSphere in the mesh on the same processor. The aggregation is done by adding weights to the elements sharing the same face marked with the same marker which then force the graph partitioner to put them on the same processor.

{
    "partitioner":
    {
        "aggregates":
        {
            "spheres":{
                "type": "faces",
                "markers": ["CenterSphere","LeftSphere","RightSphere"]
            }
        }
    }
}

5. SEE ALSO

Feel++ Documentation: docs.feelpp.org
Latest feelpp_mesh_partitioner manual: docs.feelpp.org/user/latest/using/tools/mesh_partitioner.html