1 #include <petsc/private/isimpl.h> /*I "petscis.h" I*/
2
3 PetscFunctionList ISList = NULL;
4 PetscBool ISRegisterAllCalled = PETSC_FALSE;
5
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`
8
9 Collective
10
11 Input Parameter:
12 . comm - the MPI communicator
13
14 Output Parameter:
15 . is - the new index set
16
17 Level: beginner
18
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.
24
25 .seealso: [](sec_scatter), `IS`, `ISType()`, `ISSetType()`, `ISCreateGeneral()`, `ISCreateStride()`, `ISCreateBlock()`, `ISAllGather()`
26 @*/
ISCreate(MPI_Comm comm,IS * is)27 PetscErrorCode ISCreate(MPI_Comm comm, IS *is)
28 {
29 PetscFunctionBegin;
30 PetscAssertPointer(is, 2);
31 PetscCall(ISInitializePackage());
32
33 PetscCall(PetscHeaderCreate(*is, IS_CLASSID, "IS", "Index Set", "IS", comm, ISDestroy, ISView));
34 PetscCall(PetscLayoutCreate(comm, &(*is)->map));
35 (*is)->compressOutput = PETSC_TRUE;
36 PetscFunctionReturn(PETSC_SUCCESS);
37 }
38
39 /*@
40 ISSetType - Builds a index set, for a particular `ISType`
41
42 Collective
43
44 Input Parameters:
45 + is - The index set object
46 - method - The name of the index set type
47
48 Options Database Key:
49 . -is_type <type> - Sets the index set type; use `-help` for a list of available types
50
51 Level: intermediate
52
53 Notes:
54 See `ISType` for available types (for instance, `ISGENERAL`, `ISSTRIDE`, or `ISBLOCK`).
55
56 Often convenience constructors such as `ISCreateGeneral()`, `ISCreateStride()` or `ISCreateBlock()` can be used to construct the desired `IS` in one step
57
58 Use `ISDuplicate()` to make a duplicate
59
60 .seealso: [](sec_scatter), `IS`, `ISGENERAL`, `ISBLOCK`, `ISGetType()`, `ISCreate()`, `ISCreateGeneral()`, `ISCreateStride()`, `ISCreateBlock()`
61 @*/
ISSetType(IS is,ISType method)62 PetscErrorCode ISSetType(IS is, ISType method)
63 {
64 PetscErrorCode (*r)(IS);
65 PetscBool match;
66
67 PetscFunctionBegin;
68 PetscValidHeaderSpecific(is, IS_CLASSID, 1);
69 PetscCall(PetscObjectTypeCompare((PetscObject)is, method, &match));
70 if (match) PetscFunctionReturn(PETSC_SUCCESS);
71
72 PetscCall(ISRegisterAll());
73 PetscCall(PetscFunctionListFind(ISList, method, &r));
74 PetscCheck(r, PetscObjectComm((PetscObject)is), PETSC_ERR_ARG_UNKNOWN_TYPE, "Unknown IS type: %s", method);
75 PetscTryTypeMethod(is, destroy);
76 is->ops->destroy = NULL;
77
78 PetscCall((*r)(is));
79 PetscCall(PetscObjectChangeTypeName((PetscObject)is, method));
80 PetscFunctionReturn(PETSC_SUCCESS);
81 }
82
83 /*@
84 ISGetType - Gets the index set type name, `ISType`, (as a string) from the `IS`.
85
86 Not Collective
87
88 Input Parameter:
89 . is - The index set
90
91 Output Parameter:
92 . type - The index set type name
93
94 Level: intermediate
95
96 .seealso: [](sec_scatter), `IS`, `ISType`, `ISSetType()`, `ISCreate()`
97 @*/
ISGetType(IS is,ISType * type)98 PetscErrorCode ISGetType(IS is, ISType *type)
99 {
100 PetscFunctionBegin;
101 PetscValidHeaderSpecific(is, IS_CLASSID, 1);
102 PetscAssertPointer(type, 2);
103 if (!ISRegisterAllCalled) PetscCall(ISRegisterAll());
104 *type = ((PetscObject)is)->type_name;
105 PetscFunctionReturn(PETSC_SUCCESS);
106 }
107
108 /*@C
109 ISRegister - Adds a new index set implementation
110
111 Not Collective, No Fortran Support
112
113 Input Parameters:
114 + sname - The name of a new user-defined creation routine
115 - function - The creation routine itself
116
117 Example Usage:
118 .vb
119 ISRegister("my_is_name", MyISCreate);
120 .ve
121
122 Then, your vector type can be chosen with the procedural interface via
123 .vb
124 ISCreate(MPI_Comm, IS *);
125 ISSetType(IS,"my_is_name");
126 .ve
127 or at runtime via the option
128 .vb
129 -is_type my_is_name
130 .ve
131
132 Level: developer
133
134 Notes:
135 `ISRegister()` may be called multiple times to add several user-defined vectors
136
137 This is no `ISSetFromOptions()` and the current implementations do not have a way to dynamically determine type, so
138 dynamic registration of custom `IS` types will be of limited use to users.
139
140 .seealso: [](sec_scatter), `IS`, `ISType`, `ISSetType()`, `ISRegisterAll()`, `ISRegisterDestroy()`
141 @*/
ISRegister(const char sname[],PetscErrorCode (* function)(IS))142 PetscErrorCode ISRegister(const char sname[], PetscErrorCode (*function)(IS))
143 {
144 PetscFunctionBegin;
145 PetscCall(ISInitializePackage());
146 PetscCall(PetscFunctionListAdd(&ISList, sname, function));
147 PetscFunctionReturn(PETSC_SUCCESS);
148 }
149