Application Management

Functions for registering and managing application instances. More...

Collaboration diagram for Application Management:

Functions
ErrCode	iMOAB_RegisterApplication (const iMOAB_String app_name, MPI_Comm *comm, int *compid, iMOAB_AppID pid)
	Register a new application instance with iMOAB. More...
ErrCode	iMOAB_RegisterApplicationFortran (const iMOAB_String app_name, int *comm, int *compid, iMOAB_AppID pid)
	Fortran-compatible wrapper for iMOAB_RegisterApplication. More...
ErrCode	iMOAB_DeregisterApplication (iMOAB_AppID pid)
	Deregister an application instance and cleanup associated resources. More...
ErrCode	iMOAB_DeregisterApplicationFortran (iMOAB_AppID pid)
	Fortran-compatible wrapper for iMOAB_DeregisterApplication. More...

Detailed Description

Functions for registering and managing application instances.

Function Documentation

iMOAB_DeregisterApplication()

ErrCode iMOAB_DeregisterApplication

(

iMOAB_AppID

pid

)

Deregister an application instance and cleanup associated resources.

De-Register application: delete mesh (set) associated with the application ID.

Removes application from iMOAB, deletes mesh entities, frees parallel communicator, and cleans up all associated data structures. Must be called before iMOAB_Finalize().

Cleanup Process:

1. Validate application ID exists
2. Delete all mesh entities in application's file set
3. Delete communication graphs (ParCommGraph instances)
4. Delete parallel communicator if MPI enabled
5. Delete TempestRemap objects if present
6. Delete application's mesh set
7. Remove application from global context maps

Parameters

[in]

pid

Application ID to deregister

Precondition

Application must have been registered via iMOAB_RegisterApplication

Postcondition

All mesh data deleted

Parallel communicator deleted

Application ID invalid and cannot be reused

Warning

Do not access application ID after deregistration

Note

Safe to deregister in any order relative to other applications

Returns

moab::MB_SUCCESS on success, moab::MB_FAILURE if application not found

See also

iMOAB_RegisterApplication()

Definition at line 559 of file iMOAB.cpp.

{
    // Look up application in global context
    auto appIterator = context.appDatas.find( *pid );
 
    // Validate application exists before attempting deletion
    if( appIterator == context.appDatas.end() ) return MB_FAILURE;
 
    // we found the application
    appData& data = appIterator->second;
    int rankHere  = 0;
#ifdef MOAB_HAVE_MPI
    rankHere = data.pcomm->rank();
#endif
    if( !rankHere )
        std::cout << " application with ID: " << *pid << " global id: " << data.global_id << " name: " << data.name
                  << " is de-registered now \n";
 
    EntityHandle fileSet = data.file_set;
    // get all entities part of the file set
    Range fileents;
    MB_CHK_SET_ERR( context.MBI->get_entities_by_handle( fileSet, fileents, /*recursive */ true ),
                    "can't get file entities" );
    fileents.insert( fileSet );
    MB_CHK_SET_ERR( context.MBI->get_entities_by_type( fileSet, MBENTITYSET, fileents ),
                    "can't get file entities" );  // append all mesh sets
 
#ifdef MOAB_HAVE_TEMPESTREMAP
    if( data.tempestData.remapper ) delete data.tempestData.remapper;
    if( data.tempestData.weightMaps.size() ) data.tempestData.weightMaps.clear();
#endif
 
#ifdef MOAB_HAVE_MPI
    // NOTE: we could get the pco also with the following workflow.
    // ParallelComm * pcomm = ParallelComm::get_pcomm(context.MBI, *pid);
 
    auto& pargs = data.pgraph;
    // free the parallel comm graphs associated with this app
    for( auto mt = pargs.begin(); mt != pargs.end(); ++mt )
    {
        ParCommGraph* pgr = mt->second;
        if( pgr != nullptr )
        {
            delete pgr;
            pgr = nullptr;
        }
    }
    // now free the ParallelComm resources
    if( data.pcomm )
    {
        delete data.pcomm;
        data.pcomm = nullptr;
    }
#endif
 
    // delete first all except vertices
    Range vertices = fileents.subset_by_type( MBVERTEX );
    Range noverts  = subtract( fileents, vertices );
 
    MB_CHK_SET_ERR( context.MBI->delete_entities( noverts ), "can't delete entities" );
    // now retrieve connected elements that still exist (maybe in other sets, pids?)
    Range adj_ents_left;
    MB_CHK_SET_ERR( context.MBI->get_adjacencies( vertices, 1, false, adj_ents_left, Interface::UNION ),
                    "can't get 1D adjacencies" );
    MB_CHK_SET_ERR( context.MBI->get_adjacencies( vertices, 2, false, adj_ents_left, Interface::UNION ),
                    "can't get 2D adjacencies" );
    MB_CHK_SET_ERR( context.MBI->get_adjacencies( vertices, 3, false, adj_ents_left, Interface::UNION ),
                    "can't get 3D adjacencies" );
 
    if( !adj_ents_left.empty() )
    {
        Range conn_verts;
        MB_CHK_SET_ERR( context.MBI->get_connectivity( adj_ents_left, conn_verts ), "can't get connectivity" );
        vertices = subtract( vertices, conn_verts );
    }
 
    MB_CHK_SET_ERR( context.MBI->delete_entities( vertices ), "can't delete vertices" );
 
    for( auto mit = context.appIdMap.begin(); mit != context.appIdMap.end(); ++mit )
    {
        if( *pid == mit->second )
        {
#ifdef MOAB_HAVE_MPI
            if( data.pcomm )
            {
                delete data.pcomm;
                data.pcomm = nullptr;
            }
#endif
            context.appIdMap.erase( mit );
            break;
        }
    }
 
    // now we can finally delete the application data itself
    context.appDatas.erase( appIterator );
 
    return moab::MB_SUCCESS;
}

References GlobalContext::appDatas, GlobalContext::appIdMap, context, moab::Interface::delete_entities(), moab::Range::empty(), appData::file_set, moab::Interface::get_adjacencies(), moab::Interface::get_connectivity(), moab::Interface::get_entities_by_handle(), moab::Interface::get_entities_by_type(), appData::global_id, moab::Range::insert(), MB_CHK_SET_ERR, MB_SUCCESS, MBENTITYSET, GlobalContext::MBI, MBVERTEX, appData::name, appData::pcomm, appData::pgraph, moab::ParallelComm::rank(), moab::Range::subset_by_type(), moab::subtract(), and moab::Interface::UNION.

Referenced by iMOAB_DeregisterApplicationFortran().

iMOAB_DeregisterApplicationFortran()

ErrCode iMOAB_DeregisterApplicationFortran

(

iMOAB_AppID

pid

)

Fortran-compatible wrapper for iMOAB_DeregisterApplication.

De-Register the Fortran based application: delete mesh (set) associated with the application ID.

Deregisters application from Fortran code by clearing Fortran flag and calling C-style deregistration.

Parameters

[in]

pid

Application ID to deregister

Returns

moab::MB_SUCCESS on success, moab::MB_FAILURE if application not found

See also

iMOAB_DeregisterApplication()

Definition at line 672 of file iMOAB.cpp.

{
    // Clear Fortran-specific flag before passing to C-style deregistration
    context.appDatas[*pid].is_fortran = false;
 
    // Release all data structure allocations via C-style function
    return iMOAB_DeregisterApplication( pid );
}

References GlobalContext::appDatas, context, and iMOAB_DeregisterApplication().

iMOAB_RegisterApplication()

ErrCode iMOAB_RegisterApplication	(	const iMOAB_String	app_name,
		MPI_Comm *	comm,
		int *	compid,
		iMOAB_AppID	pid
	)

Register a new application instance with iMOAB.

Creates a new application context with unique ID, allocates a mesh set for data storage, and sets up parallel communicator if MPI is enabled. Each application represents a distinct component in a coupled simulation (e.g., atmosphere, ocean, land).

Registration Process:

1. Validate application name is unique (not already registered)
2. Generate unique application ID using FNV hash of name + component ID
3. Create MOAB mesh set for storing application's mesh data
4. Initialize application data structure (appData) with default values
5. Create ParallelComm instance for parallel operations if MPI enabled
6. Store application context in global map indexed by application ID

Parameters

[in]	app_name	Unique name for this application instance
[in]	comm	MPI communicator for this application (MPI builds only)
[in]	compid	External component ID (must be positive)
[out]	pid	Generated application ID (output parameter)

Precondition

iMOAB_Initialize must have been called

app_name must be unique (not already registered)

compid must be positive

Postcondition

Application registered and ready for mesh loading

Application ID stored in pid

Mesh set created and stored in context.appDatas[pid]

ParallelComm created if MPI enabled

Note

Application ID is computed as hash(app_name, compid) for uniqueness

Fortran interface should use iMOAB_RegisterApplicationFortran()

Returns

moab::MB_SUCCESS on success, moab::MB_FAILURE if already registered or compid invalid

See also

iMOAB_DeregisterApplication()

Definition at line 394 of file iMOAB.cpp.

{
    IMOAB_CHECKPOINTER( app_name, 1 );
#ifdef MOAB_HAVE_MPI
    IMOAB_CHECKPOINTER( comm, 2 );
    IMOAB_CHECKPOINTER( compid, 3 );
#else
    IMOAB_CHECKPOINTER( compid, 2 );
#endif
 
    // will create a parallel comm for this application too, so there will be a
    // mapping from *pid to file set and to parallel comm instances
    std::string name( app_name );
 
    if( context.appIdMap.find( name ) != context.appIdMap.end() )
    {
        std::cout << " application " << name << " already registered \n";
        return moab::MB_FAILURE;
    }
 
    // trivial hash: just use the id that the user provided and assume it is unique
    // *pid = *compid;
    // hash: compute a unique hash as a combination of the appname and the component id
    *pid = apphash( app_name, *compid );
    // store map of application name and the ID we just generated
    context.appIdMap[name] = *pid;
    int rankHere           = 0;
#ifdef MOAB_HAVE_MPI
    MPI_Comm_rank( *comm, &rankHere );
#endif
    if( !rankHere )
        std::cout << " application " << name << " with ID = " << *pid << " and external id: " << *compid
                  << "  is registered now \n";
    if( *compid <= 0 )
    {
        std::cout << " convention for external application is to have its id positive \n";
        return moab::MB_FAILURE;
    }
 
    // create now the file set that will be used for loading the model in
    EntityHandle file_set;
    MB_CHK_SET_ERR( context.MBI->create_meshset( MESHSET_SET, file_set ), "can't create file set" );
 
    appData app_data;
    app_data.file_set  = file_set;
    app_data.global_id = *compid;  // will be used mostly for par comm graph
    app_data.name      = name;     // save the name of application
 
#ifdef MOAB_HAVE_TEMPESTREMAP
    app_data.tempestData.remapper             = nullptr;  // Only allocate as needed
    app_data.tempestData.num_src_ghost_layers = 0;
    app_data.tempestData.num_tgt_ghost_layers = 0;
#endif
 
    // set some default values
    app_data.num_ghost_layers = 0;
    app_data.point_cloud      = false;
    app_data.is_fortran       = false;
#ifdef MOAB_HAVE_TEMPESTREMAP
    app_data.secondary_file_set = app_data.file_set;
#endif
 
#ifdef MOAB_HAVE_MPI
    if( *comm ) app_data.pcomm = new ParallelComm( context.MBI, *comm );
#endif
    context.appDatas[*pid] = app_data;  // Store application data indexed by generated ID
    return moab::MB_SUCCESS;
}

References GlobalContext::appDatas, apphash(), GlobalContext::appIdMap, context, moab::Interface::create_meshset(), appData::file_set, appData::global_id, IMOAB_CHECKPOINTER, appData::is_fortran, MB_CHK_SET_ERR, MB_SUCCESS, GlobalContext::MBI, MESHSET_SET, appData::name, appData::num_ghost_layers, appData::pcomm, and appData::point_cloud.

Referenced by iMOAB_RegisterApplicationFortran().

iMOAB_RegisterApplicationFortran()

ErrCode iMOAB_RegisterApplicationFortran	(	const iMOAB_String	app_name,
		int *	comm,
		int *	compid,
		iMOAB_AppID	pid
	)

Fortran-compatible wrapper for iMOAB_RegisterApplication.

Registers application from Fortran code by converting Fortran MPI communicator to C and calling C-style registration. Sets is_fortran flag to enable proper MPI handle conversions.

Parameters

[in]	app_name	Unique name for this application instance
[in]	comm	Fortran MPI communicator (integer handle, MPI builds only)
[in]	compid	External component ID (must be positive)
[out]	pid	Generated application ID (output parameter)

Note

Automatically converts Fortran MPI_Comm to C MPI_Comm using MPI_Comm_f2c

Sets is_fortran flag in application data for future MPI handle conversions

Returns

moab::MB_SUCCESS on success, moab::MB_FAILURE otherwise

See also

iMOAB_RegisterApplication(), MPI_Comm_f2c()

Definition at line 487 of file iMOAB.cpp.

{
    IMOAB_CHECKPOINTER( app_name, 1 );
#ifdef MOAB_HAVE_MPI
    IMOAB_CHECKPOINTER( comm, 2 );
    IMOAB_CHECKPOINTER( compid, 3 );
#else
    IMOAB_CHECKPOINTER( compid, 2 );
#endif
 
    ErrCode err;
    assert( app_name != nullptr );
    std::string name( app_name );
 
#ifdef MOAB_HAVE_MPI
    MPI_Comm ccomm;
    if( comm )
    {
        // Convert from Fortran communicator (integer) to C communicator
        // See MPI standard: http://www.mpi-forum.org/docs/mpi-2.2/mpi22-report/node361.htm
        ccomm = MPI_Comm_f2c( (MPI_Fint)*comm );
    }
#endif
 
    // Call C-style registration function with converted communicator
    err = iMOAB_RegisterApplication( app_name,
#ifdef MOAB_HAVE_MPI
                                     &ccomm,
#endif
                                     compid, pid );
 
    // Mark application as Fortran-based for proper MPI handle conversions in future calls
    context.appDatas[*pid].is_fortran = true;
 
    return err;
}

References GlobalContext::appDatas, context, ErrCode, IMOAB_CHECKPOINTER, iMOAB_RegisterApplication(), and MOAB_HAVE_MPI.