Date: 2025-03-29T05:58:52+00:00

Actual source code: isreg.c

      1: #include <petsc/private/isimpl.h>

      3: PetscFunctionList ISList              = NULL;
      4: PetscBool         ISRegisterAllCalled = PETSC_FALSE;

      6: /*@
      7:   ISCreate - Create an index set object. `IS`, index sets, are PETSc objects used to do efficient indexing into other data structures such as `Vec` and `Mat`

      9:   Collective

     11:   Input Parameter:
     12: . comm - the MPI communicator

     14:   Output Parameter:
     15: . is - the new index set

     17:   Level: beginner

     19:   Notes:
     20:   When the communicator is not `MPI_COMM_SELF`, the operations on `is` are NOT
     21:   conceptually the same as `MPI_Group` operations. The `IS` are then
     22:   distributed sets of indices and thus certain operations on them are
     23:   collective.

     25: .seealso: [](sec_scatter), `IS`, `ISType()`, `ISSetType()`, `ISCreateGeneral()`, `ISCreateStride()`, `ISCreateBlock()`, `ISAllGather()`
     26: @*/
     27: PetscErrorCode ISCreate(MPI_Comm comm, IS *is)
     28: {
     29:   PetscFunctionBegin;
     30:   PetscAssertPointer(is, 2);
     31:   PetscCall(ISInitializePackage());

     33:   PetscCall(PetscHeaderCreate(*is, IS_CLASSID, "IS", "Index Set", "IS", comm, ISDestroy, ISView));
     34:   PetscCall(PetscLayoutCreate(comm, &(*is)->map));
     35:   PetscFunctionReturn(PETSC_SUCCESS);
     36: }

     38: /*@
     39:   ISSetType - Builds a index set, for a particular `ISType`

     41:   Collective

     43:   Input Parameters:
     44: + is     - The index set object
     45: - method - The name of the index set type

     47:   Options Database Key:
     48: . -is_type <type> - Sets the index set type; use `-help` for a list of available types

     50:   Level: intermediate

     52:   Notes:
     53:   See `ISType` for available types (for instance, `ISGENERAL`, `ISSTRIDE`, or `ISBLOCK`).

     55:   Often convenience constructors such as `ISCreateGeneral()`, `ISCreateStride()` or  `ISCreateBlock()` can be used to construct the desired `IS` in one step

     57:   Use `ISDuplicate()` to make a duplicate

     59: .seealso: [](sec_scatter), `IS`, `ISGENERAL`, `ISBLOCK`, `ISGetType()`, `ISCreate()`, `ISCreateGeneral()`, `ISCreateStride()`, `ISCreateBlock()`
     60: @*/
     61: PetscErrorCode ISSetType(IS is, ISType method)
     62: {
     63:   PetscErrorCode (*r)(IS);
     64:   PetscBool match;

     66:   PetscFunctionBegin;
     68:   PetscCall(PetscObjectTypeCompare((PetscObject)is, method, &match));
     69:   if (match) PetscFunctionReturn(PETSC_SUCCESS);

     71:   PetscCall(ISRegisterAll());
     72:   PetscCall(PetscFunctionListFind(ISList, method, &r));
     73:   PetscCheck(r, PetscObjectComm((PetscObject)is), PETSC_ERR_ARG_UNKNOWN_TYPE, "Unknown IS type: %s", method);
     74:   PetscTryTypeMethod(is, destroy);
     75:   is->ops->destroy = NULL;

     77:   PetscCall((*r)(is));
     78:   PetscCall(PetscObjectChangeTypeName((PetscObject)is, method));
     79:   PetscFunctionReturn(PETSC_SUCCESS);
     80: }

     82: /*@
     83:   ISGetType - Gets the index set type name, `ISType`, (as a string) from the `IS`.

     85:   Not Collective

     87:   Input Parameter:
     88: . is - The index set

     90:   Output Parameter:
     91: . type - The index set type name

     93:   Level: intermediate

     95: .seealso: [](sec_scatter), `IS`, `ISType`, `ISSetType()`, `ISCreate()`
     96: @*/
     97: PetscErrorCode ISGetType(IS is, ISType *type)
     98: {
     99:   PetscFunctionBegin;
    101:   PetscAssertPointer(type, 2);
    102:   if (!ISRegisterAllCalled) PetscCall(ISRegisterAll());
    103:   *type = ((PetscObject)is)->type_name;
    104:   PetscFunctionReturn(PETSC_SUCCESS);
    105: }

    107: /*--------------------------------------------------------------------------------------------------------------------*/

    109: /*@C
    110:   ISRegister - Adds a new index set implementation

    112:   Not Collective, No Fortran Support

    114:   Input Parameters:
    115: + sname    - The name of a new user-defined creation routine
    116: - function - The creation routine itself

    118:   Example Usage:
    119: .vb
    120:     ISRegister("my_is_name",  MyISCreate);
    121: .ve

    123:   Then, your vector type can be chosen with the procedural interface via
    124: .vb
    125:     ISCreate(MPI_Comm, IS *);
    126:     ISSetType(IS,"my_is_name");
    127: .ve
    128:   or at runtime via the option
    129: .vb
    130:     -is_type my_is_name
    131: .ve

    133:   Level: developer

    135:   Notes:
    136:   `ISRegister()` may be called multiple times to add several user-defined vectors

    138:   This is no `ISSetFromOptions()` and the current implementations do not have a way to dynamically determine type, so
    139:   dynamic registration of custom `IS` types will be of limited use to users.

    141: .seealso: [](sec_scatter), `IS`, `ISType`, `ISSetType()`, `ISRegisterAll()`, `ISRegisterDestroy()`
    142: @*/
    143: PetscErrorCode ISRegister(const char sname[], PetscErrorCode (*function)(IS))
    144: {
    145:   PetscFunctionBegin;
    146:   PetscCall(ISInitializePackage());
    147:   PetscCall(PetscFunctionListAdd(&ISList, sname, function));
    148:   PetscFunctionReturn(PETSC_SUCCESS);
    149: }