Actual source code: isreg.c


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

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

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

 10:    Collective

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

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

 18:    Level: beginner

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

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

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

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

 42:   Collective

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

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

 51:   Level: intermediate

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

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

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

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

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

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

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

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

 86:   Not Collective

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

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

 94:   Level: intermediate

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

108: /*--------------------------------------------------------------------------------------------------------------------*/

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

113:   Not Collective

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

119:   Sample usage:
120: .vb
121:     ISRegister("my_is_name",  MyISCreate);
122: .ve

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

134:   Level: developer

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

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

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