Mesh I/O Operations

Functions for reading and writing mesh files. More...

Collaboration diagram for Mesh I/O Operations:

Functions
ErrCode	iMOAB_ReadHeaderInfo (const iMOAB_String filename, int *num_global_vertices, int *num_global_elements, int *num_dimension, int *num_parts)
	Read mesh file header information without loading full mesh. More...
ErrCode	iMOAB_LoadMesh (iMOAB_AppID pid, const iMOAB_String filename, const iMOAB_String read_options, int *num_ghost_layers)
	Load mesh file into application's mesh set. More...
ErrCode	iMOAB_WriteMesh (iMOAB_AppID pid, const iMOAB_String filename, const iMOAB_String write_options)
	Write application's mesh to file. More...
ErrCode	iMOAB_WriteLocalMesh (iMOAB_AppID pid, iMOAB_String prefix)
	Write each process's local mesh to separate file for debugging. More...

Detailed Description

Functions for reading and writing mesh files.

Function Documentation

iMOAB_LoadMesh()

ErrCode iMOAB_LoadMesh	(	iMOAB_AppID	pid,
		const iMOAB_String	filename,
		const iMOAB_String	read_options,
		int *	num_ghost_layers
	)

Load mesh file into application's mesh set.

Load a MOAB mesh file in parallel and exchange ghost layers as requested.

Loads mesh from file (HDF5, Exodus, VTK, etc.) into application's mesh set with optional ghost layer exchange for parallel simulations. Automatically configures parallel reading options.

Loading Process:

1. Construct read options string from user options + automatic parallel settings
2. Add PARALLEL_COMM option for parallel HDF5/NetCDF files
3. Add ghost layer options (PARALLEL_GHOSTS, PARTITION_DISTRIBUTE) if requested
4. Load mesh into application's file set using MOAB::load_file()
5. Update mesh information (vertex/element counts, ranges, etc.)
6. Exchange ghost layers if num_ghost_layers > 0

Parameters

[in]	pid	Application ID
[in]	filename	Path to mesh file to load
[in]	read_options	Optional reader options (semicolon-separated, can be NULL)
[in]	num_ghost_layers	Number of ghost element layers to exchange (0 for none)

Precondition

Application must be registered via iMOAB_RegisterApplication

File must exist and be readable

For parallel: MPI must be initialized

Postcondition

Mesh loaded into application's file set

Mesh info updated (vertices, elements, ranges)

Ghost layers exchanged if requested

Note

Supported formats: HDF5 (.h5m), Exodus (.exo), VTK (.vtk), NetCDF (.nc), etc.

PARALLEL_COMM option automatically added for parallel HDF5/NetCDF

Ghost exchange requires PARALLEL_GHOSTS and PARTITION_DISTRIBUTE options

Warning

Do not manually specify PARALLEL_COMM in read_options (will cause error)

Returns

moab::MB_SUCCESS on success, error code otherwise

See also

iMOAB_WriteMesh(), iMOAB_UpdateMeshInfo()

Definition at line 895 of file iMOAB.cpp.

{
    IMOAB_CHECKPOINTER( filename, 2 );
    IMOAB_ASSERT( strlen( filename ), "Invalid filename length." );
    IMOAB_CHECKPOINTER( num_ghost_layers, 4 );
 
    // make sure we use the file set and pcomm associated with the *pid
    std::ostringstream newopts;
    if( read_options ) newopts << read_options;
 
#ifdef MOAB_HAVE_MPI
 
    if( context.MPI_initialized )
    {
        if( context.worldprocs > 1 )
        {
            std::string opts( ( read_options ? read_options : "" ) );
            std::string pcid( "PARALLEL_COMM=" );
            std::size_t found = opts.find( pcid );
 
            if( found != std::string::npos )
            {
                std::cerr << " cannot specify PARALLEL_COMM option, it is implicit \n";
                return moab::MB_FAILURE;
            }
 
            // in serial, apply PARALLEL_COMM option only for h5m files; it does not work for .g
            // files (used in test_remapping)
            std::string filen( filename );
            std::string::size_type idx = filen.rfind( '.' );
 
            if( idx != std::string::npos )
            {
                ParallelComm* pco     = context.appDatas[*pid].pcomm;
                std::string extension = filen.substr( idx + 1 );
                if( ( extension == std::string( "h5m" ) ) || ( extension == std::string( "nc" ) ) )
                    newopts << ";;PARALLEL_COMM=" << pco->get_id();
            }
 
            if( *num_ghost_layers >= 1 )
            {
                // if we want ghosts, we will want additional entities, the last .1
                // because the addl ents can be edges, faces that are part of the neumann sets
                std::string pcid2( "PARALLEL_GHOSTS=" );
                std::size_t found2 = opts.find( pcid2 );
 
                if( found2 != std::string::npos )
                {
                    std::cout << " PARALLEL_GHOSTS option is already specified, ignore passed "
                                 "number of layers \n";
                }
                else
                {
                    // dimension of primary entities is 3 here, but it could be 2 for climate
                    // meshes; we would need to pass PARALLEL_GHOSTS explicitly for 2d meshes, for
                    // example:  ";PARALLEL_GHOSTS=2.0.1"
                    newopts << ";PARALLEL_GHOSTS=3.0." << *num_ghost_layers << ".3";
                }
            }
        }
    }
#else
    IMOAB_ASSERT( *num_ghost_layers == 0, "Cannot provide ghost layers in serial." );
#endif
 
    // Now let us actually load the MOAB file with the appropriate read options
    MB_CHK_SET_ERR( context.MBI->load_file( filename, &context.appDatas[*pid].file_set, newopts.str().c_str() ),
                    "can't load file" );
 
#ifdef VERBOSE
    // some debugging stuff
    std::ostringstream outfile;
#ifdef MOAB_HAVE_MPI
    ParallelComm* pco = context.appDatas[*pid].pcomm;
    int rank          = pco->rank();
    int nprocs        = pco->size();
    outfile << "TaskMesh_n" << nprocs << "." << rank << ".h5m";
#else
    outfile << "TaskMesh_n1.0.h5m";
#endif
    // the mesh contains ghosts too, but they are not part of mat/neumann set
    // write in serial the file, to see what tags are missing
    MB_CHK_SET_ERR( context.MBI->write_file( outfile.str().c_str() ),
                    "can't write file" );  // everything on current task, written in serial
#endif
 
    // Update ghost layer information
    context.appDatas[*pid].num_ghost_layers = *num_ghost_layers;
 
    // Update mesh information
    return iMOAB_UpdateMeshInfo( pid );
}

References GlobalContext::appDatas, context, moab::ParallelComm::get_id(), IMOAB_ASSERT, IMOAB_CHECKPOINTER, iMOAB_UpdateMeshInfo(), moab::Interface::load_file(), MB_CHK_SET_ERR, GlobalContext::MBI, GlobalContext::MPI_initialized, moab::ParallelComm::rank(), moab::ParallelComm::size(), GlobalContext::worldprocs, and moab::Interface::write_file().

iMOAB_ReadHeaderInfo()

ErrCode iMOAB_ReadHeaderInfo	(	const iMOAB_String	filename,
		int *	num_global_vertices,
		int *	num_global_elements,
		int *	num_dimension,
		int *	num_parts
	)

Read mesh file header information without loading full mesh.

It should be called on master task only, and information obtained could be broadcasted by the user. It is a fast lookup in the header of the file.

Quickly extracts metadata from HDF5 mesh file including vertex count, element count, spatial dimension, and partition count. Useful for memory planning before full load.

Implementation:

• Opens HDF5 file in read-only mode using mhdf library
• Reads file summary without loading actual mesh data
• Counts elements by type (edges, faces, regions)
• Extracts partition information from parallel decomposition tags

Parameters

[in]	filename	Path to HDF5 mesh file
[out]	num_global_vertices	Total number of vertices in mesh
[out]	num_global_elements	Total number of elements in mesh (all types)
[out]	num_dimension	Spatial dimension (2D or 3D)
[out]	num_parts	Number of parallel partitions

Precondition

HDF5 support must be enabled (MOAB_HAVE_HDF5)

File must be valid HDF5 mesh file

Postcondition

Output parameters populated with file metadata

File remains closed (no mesh data loaded)

Note

Lightweight operation - does not load mesh into memory

All output parameters are optional (can be NULL)

Warning

Returns failure if HDF5 support not enabled

Returns

moab::MB_SUCCESS on success, moab::MB_FAILURE on error

See also

iMOAB_LoadMesh()

Definition at line 714 of file iMOAB.cpp.

{
    IMOAB_CHECKPOINTER( filename, 1 );
    IMOAB_ASSERT( strlen( filename ), "Invalid filename length." );
 
#ifdef MOAB_HAVE_HDF5
    std::string filen( filename );
 
    int edges   = 0;
    int faces   = 0;
    int regions = 0;
    if( num_global_vertices ) *num_global_vertices = 0;
    if( num_global_elements ) *num_global_elements = 0;
    if( num_dimension ) *num_dimension = 0;
    if( num_parts ) *num_parts = 0;
 
    mhdf_FileHandle file;
    mhdf_Status status;
    unsigned long max_id;
    struct mhdf_FileDesc* data;
 
    file = mhdf_openFile( filen.c_str(), 0, &max_id, -1, &status );
 
    if( mhdf_isError( &status ) )
    {
        fprintf( stderr, "%s: %s\n", filename, mhdf_message( &status ) );
        return moab::MB_FAILURE;
    }
 
    data = mhdf_getFileSummary( file, H5T_NATIVE_ULONG, &status,
                                1 );  // will use extra set info; will get parallel partition tag info too!
 
    if( mhdf_isError( &status ) )
    {
        fprintf( stderr, "%s: %s\n", filename, mhdf_message( &status ) );
        return moab::MB_FAILURE;
    }
 
    if( num_dimension ) *num_dimension = data->nodes.vals_per_ent;
    if( num_global_vertices ) *num_global_vertices = (int)data->nodes.count;
 
    for( int i = 0; i < data->num_elem_desc; i++ )
    {
        struct mhdf_ElemDesc* el_desc = &( data->elems[i] );
        struct mhdf_EntDesc* ent_d    = &( el_desc->desc );
 
        if( 0 == strcmp( el_desc->type, mhdf_EDGE_TYPE_NAME ) )
        {
            edges += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mhdf_TRI_TYPE_NAME ) )
        {
            faces += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mhdf_QUAD_TYPE_NAME ) )
        {
            faces += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mhdf_POLYGON_TYPE_NAME ) )
        {
            faces += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mhdf_TET_TYPE_NAME ) )
        {
            regions += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mhdf_PYRAMID_TYPE_NAME ) )
        {
            regions += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mhdf_PRISM_TYPE_NAME ) )
        {
            regions += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mdhf_KNIFE_TYPE_NAME ) )
        {
            regions += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mdhf_HEX_TYPE_NAME ) )
        {
            regions += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mhdf_POLYHEDRON_TYPE_NAME ) )
        {
            regions += ent_d->count;
        }
 
        if( 0 == strcmp( el_desc->type, mhdf_SEPTAHEDRON_TYPE_NAME ) )
        {
            regions += ent_d->count;
        }
    }
 
    if( num_parts ) *num_parts = data->numEntSets[0];
 
    // is this required?
    if( edges > 0 )
    {
        if( num_dimension ) *num_dimension = 1;  // I don't think it will ever return 1
        if( num_global_elements ) *num_global_elements = edges;
    }
 
    if( faces > 0 )
    {
        if( num_dimension ) *num_dimension = 2;
        if( num_global_elements ) *num_global_elements = faces;
    }
 
    if( regions > 0 )
    {
        if( num_dimension ) *num_dimension = 3;
        if( num_global_elements ) *num_global_elements = regions;
    }
 
    mhdf_closeFile( file, &status );
 
    free( data );
 
#else
    std::cout << filename
              << ": Please reconfigure with HDF5. Cannot retrieve header information for file "
                 "formats other than a h5m file.\n";
    if( num_global_vertices ) *num_global_vertices = 0;
    if( num_global_elements ) *num_global_elements = 0;
    if( num_dimension ) *num_dimension = 0;
    if( num_parts ) *num_parts = 0;
#endif
 
    return moab::MB_SUCCESS;
}

References mhdf_EntDesc::count, mhdf_ElemDesc::desc, mhdf_FileDesc::elems, IMOAB_ASSERT, IMOAB_CHECKPOINTER, MB_SUCCESS, mdhf_HEX_TYPE_NAME, mdhf_KNIFE_TYPE_NAME, mhdf_closeFile(), mhdf_EDGE_TYPE_NAME, mhdf_getFileSummary(), mhdf_isError(), mhdf_message(), mhdf_openFile(), mhdf_POLYGON_TYPE_NAME, mhdf_POLYHEDRON_TYPE_NAME, mhdf_PRISM_TYPE_NAME, mhdf_PYRAMID_TYPE_NAME, mhdf_QUAD_TYPE_NAME, mhdf_SEPTAHEDRON_TYPE_NAME, mhdf_TET_TYPE_NAME, mhdf_TRI_TYPE_NAME, mhdf_FileDesc::nodes, mhdf_FileDesc::num_elem_desc, mhdf_FileDesc::numEntSets, mhdf_ElemDesc::type, and mhdf_EntDesc::vals_per_ent.

iMOAB_WriteLocalMesh()

ErrCode iMOAB_WriteLocalMesh	(	iMOAB_AppID	pid,
		iMOAB_String	prefix
	)

Write each process's local mesh to separate file for debugging.

Write a local MOAB mesh copy.

Creates per-process HDF5 file with naming convention: prefix_nprocs_rank.h5m. Useful for debugging parallel mesh distribution and ghost layer issues.

Parameters

[in]	pid	Application ID
[in]	prefix	Output file prefix (rank and process count appended automatically)

Precondition

Application must be registered and mesh loaded

Postcondition

Each process writes its local mesh to: prefix_<nprocs>_<rank>.h5m

Note

Output files show per-process mesh partition (useful for parallel debugging)

Files include both owned and ghost entities

Returns

moab::MB_SUCCESS on success, error code otherwise

See also

iMOAB_WriteMesh()

Definition at line 1131 of file iMOAB.cpp.

{
    IMOAB_CHECKPOINTER( prefix, 2 );
    IMOAB_ASSERT( strlen( prefix ), "Invalid prefix string length." );
 
    // Construct filename with parallel decomposition info: prefix_nprocs_rank.h5m
    std::ostringstream file_name;
    int rank = 0, size = 1;
#ifdef MOAB_HAVE_MPI
    ParallelComm* pcomm = context.appDatas[*pid].pcomm;
    rank                = pcomm->rank();
    size                = pcomm->size();
#endif
    file_name << prefix << "_" << size << "_" << rank << ".h5m";
 
    // Write this process's local mesh partition to its own file
    MB_CHK_ERR( context.MBI->write_file( file_name.str().c_str(), 0, 0, &context.appDatas[*pid].file_set, 1 ) );
 
    return moab::MB_SUCCESS;
}

References GlobalContext::appDatas, context, IMOAB_ASSERT, IMOAB_CHECKPOINTER, MB_CHK_ERR, MB_SUCCESS, GlobalContext::MBI, moab::ParallelComm::rank(), moab::ParallelComm::size(), and moab::Interface::write_file().

iMOAB_WriteMesh()

ErrCode iMOAB_WriteMesh	(	iMOAB_AppID	pid,
		const iMOAB_String	filename,
		const iMOAB_String	write_options
	)

Write application's mesh to file.

Write a MOAB mesh along with the solution tags to a file.

Writes mesh data from application's mesh set to file in various formats (HDF5, Exodus, VTK, etc.). Automatically includes GLOBAL_ID and PARALLEL_PARTITION tags for parallel simulations.

Writing Process:

1. Construct write options from user options + automatic parallel settings
2. Add PARALLEL=WRITE_PART for parallel HDF5 output if needed
3. Append GLOBAL_ID tag if not already in tag list
4. Append PARALLEL_PARTITION tag if available and not in tag list
5. Write mesh using MOAB::write_file() with appropriate options

Parameters

[in]	pid	Application ID
[in]	filename	Output file path
[in]	write_options	Optional writer options (semicolon-separated, can be NULL)

Precondition

Application must be registered and mesh loaded

For parallel: output directory must be writable by all processes

Postcondition

Mesh written to file with requested format

GLOBAL_ID and PARALLEL_PARTITION tags included if available

Note

Supported formats: HDF5 (.h5m), Exodus (.exo), VTK (.vtk), etc.

For parallel writes, use PARALLEL=WRITE_PART option

Tags in application's tagList are automatically written

Returns

moab::MB_SUCCESS on success, error code otherwise

See also

iMOAB_LoadMesh(), iMOAB_WriteLocalMesh()

Definition at line 1105 of file iMOAB.cpp.

{
    return internal_WriteMesh( pid, filename, write_options );
}

References internal_WriteMesh().