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

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

  6: /*@
  7:   ISCreate - Creates an index set object. `IS` are 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: /*@C
 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: /*@C
 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

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: }