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