1 /* 2 Defines the abstract operations on AO (application orderings) 3 */ 4 #include <../src/vec/is/ao/aoimpl.h> /*I "petscao.h" I*/ 5 6 /* Logging support */ 7 PetscClassId AO_CLASSID; 8 PetscLogEvent AO_PetscToApplication, AO_ApplicationToPetsc; 9 10 /*@ 11 AOView - Displays an application ordering. 12 13 Collective 14 15 Input Parameters: 16 + ao - the application ordering context 17 - viewer - viewer used for display 18 19 Level: intermediate 20 21 Options Database Key: 22 . -ao_view - calls `AOView()` at end of `AOCreate()` 23 24 Notes: 25 The available visualization contexts include 26 + `PETSC_VIEWER_STDOUT_SELF` - standard output (default) 27 - `PETSC_VIEWER_STDOUT_WORLD` - synchronized standard 28 output where only the first processor opens 29 the file. All other processors send their 30 data to the first processor to print. 31 32 The user can open an alternative visualization context with 33 `PetscViewerASCIIOpen()` - output to a specified file. 34 35 .seealso: [](sec_ao), `AO`, `PetscViewerASCIIOpen()`, `AOViewFromOptions()` 36 @*/ 37 PetscErrorCode AOView(AO ao, PetscViewer viewer) 38 { 39 PetscFunctionBegin; 40 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 41 if (!viewer) PetscCall(PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)ao), &viewer)); 42 PetscValidHeaderSpecific(viewer, PETSC_VIEWER_CLASSID, 2); 43 44 PetscCall(PetscObjectPrintClassNamePrefixType((PetscObject)ao, viewer)); 45 PetscUseTypeMethod(ao, view, viewer); 46 PetscFunctionReturn(PETSC_SUCCESS); 47 } 48 49 /*@ 50 AOViewFromOptions - View an `AO` based on values in the options database 51 52 Collective 53 54 Input Parameters: 55 + ao - the application ordering context 56 . obj - optional object that provides the prefix used to search the options database 57 - name - command line option 58 59 Level: intermediate 60 61 .seealso: [](sec_ao), `AO`, `AOView()`, `PetscObjectViewFromOptions()`, `AOCreate()` 62 @*/ 63 PetscErrorCode AOViewFromOptions(AO ao, PetscObject obj, const char name[]) 64 { 65 PetscFunctionBegin; 66 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 67 PetscCall(PetscObjectViewFromOptions((PetscObject)ao, obj, name)); 68 PetscFunctionReturn(PETSC_SUCCESS); 69 } 70 71 /*@ 72 AODestroy - Destroys an application ordering. 73 74 Collective 75 76 Input Parameter: 77 . ao - the application ordering context 78 79 Level: beginner 80 81 .seealso: [](sec_ao), `AO`, `AOCreate()` 82 @*/ 83 PetscErrorCode AODestroy(AO *ao) 84 { 85 PetscFunctionBegin; 86 if (!*ao) PetscFunctionReturn(PETSC_SUCCESS); 87 PetscValidHeaderSpecific(*ao, AO_CLASSID, 1); 88 if (--((PetscObject)*ao)->refct > 0) { 89 *ao = NULL; 90 PetscFunctionReturn(PETSC_SUCCESS); 91 } 92 /* if memory was published with SAWs then destroy it */ 93 PetscCall(PetscObjectSAWsViewOff((PetscObject)*ao)); 94 PetscCall(ISDestroy(&(*ao)->isapp)); 95 PetscCall(ISDestroy(&(*ao)->ispetsc)); 96 /* destroy the internal part */ 97 PetscTryTypeMethod(*ao, destroy); 98 PetscCall(PetscHeaderDestroy(ao)); 99 PetscFunctionReturn(PETSC_SUCCESS); 100 } 101 102 #include <../src/vec/is/is/impls/general/general.h> 103 104 PETSC_INTERN PetscErrorCode ISSetUp_General(IS); 105 106 /*@ 107 AOPetscToApplicationIS - Maps an index set in the PETSc ordering to 108 the application-defined ordering. 109 110 Collective 111 112 Input Parameters: 113 + ao - the application ordering context 114 - is - the index set; this is replaced with its mapped values 115 116 Output Parameter: 117 . is - the mapped index set 118 119 Level: intermediate 120 121 Notes: 122 The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK`. 123 124 Any integers in is that are negative are left unchanged. This 125 allows one to convert, for example, neighbor lists that use negative 126 entries to indicate nonexistent neighbors due to boundary conditions etc. 127 128 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, 129 `AOApplicationToPetscIS()`, `AOPetscToApplication()`, `ISSTRIDE`, `ISBLOCK` 130 @*/ 131 PetscErrorCode AOPetscToApplicationIS(AO ao, IS is) 132 { 133 PetscInt n; 134 PetscInt *ia; 135 136 PetscFunctionBegin; 137 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 138 PetscValidHeaderSpecific(is, IS_CLASSID, 2); 139 PetscCall(ISToGeneral(is)); 140 /* we cheat because we know the IS is general and that we can change the indices */ 141 PetscCall(ISGetIndices(is, (const PetscInt **)&ia)); 142 PetscCall(ISGetLocalSize(is, &n)); 143 PetscUseTypeMethod(ao, petsctoapplication, n, ia); 144 PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia)); 145 /* updated cached values (sorted, min, max, etc.)*/ 146 PetscCall(ISSetUp_General(is)); 147 PetscFunctionReturn(PETSC_SUCCESS); 148 } 149 150 /*@ 151 AOApplicationToPetscIS - Maps an index set in the application-defined 152 ordering to the PETSc ordering. 153 154 Collective 155 156 Input Parameters: 157 + ao - the application ordering context 158 - is - the index set; this is replaced with its mapped values 159 160 Output Parameter: 161 . is - the mapped index set 162 163 Level: beginner 164 165 Notes: 166 The index set cannot be of `ISType` `ISSTRIDE` or `ISBLOCK` 167 168 Any integers in is that are negative are left unchanged. This 169 allows one to convert, for example, neighbor lists that use negative 170 entries to indicate nonexistent neighbors due to boundary conditions, etc. 171 172 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`, 173 `AOPetscToApplicationIS()`, `AOApplicationToPetsc()`, `ISSTRIDE`, `ISBLOCK` 174 @*/ 175 PetscErrorCode AOApplicationToPetscIS(AO ao, IS is) 176 { 177 PetscInt n, *ia; 178 179 PetscFunctionBegin; 180 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 181 PetscValidHeaderSpecific(is, IS_CLASSID, 2); 182 PetscCall(ISToGeneral(is)); 183 /* we cheat because we know the IS is general and that we can change the indices */ 184 PetscCall(ISGetIndices(is, (const PetscInt **)&ia)); 185 PetscCall(ISGetLocalSize(is, &n)); 186 PetscUseTypeMethod(ao, applicationtopetsc, n, ia); 187 PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia)); 188 /* updated cached values (sorted, min, max, etc.)*/ 189 PetscCall(ISSetUp_General(is)); 190 PetscFunctionReturn(PETSC_SUCCESS); 191 } 192 193 /*@ 194 AOPetscToApplication - Maps a set of integers in the PETSc ordering to 195 the application-defined ordering. 196 197 Collective 198 199 Input Parameters: 200 + ao - the application ordering context 201 . n - the number of integers 202 - ia - the integers; these are replaced with their mapped value 203 204 Output Parameter: 205 . ia - the mapped integers 206 207 Level: beginner 208 209 Note: 210 Any integers in `ia` that are negative are left unchanged. This 211 allows one to convert, for example, neighbor lists that use negative 212 entries to indicate nonexistent neighbors due to boundary conditions, etc. 213 214 Integers that are out of range are mapped to -1 215 216 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, 217 `AOPetscToApplicationIS()` 218 @*/ 219 PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[]) 220 { 221 PetscFunctionBegin; 222 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 223 if (n) PetscAssertPointer(ia, 3); 224 PetscUseTypeMethod(ao, petsctoapplication, n, ia); 225 PetscFunctionReturn(PETSC_SUCCESS); 226 } 227 228 /*@ 229 AOApplicationToPetsc - Maps a set of integers in the application-defined 230 ordering to the PETSc ordering. 231 232 Collective 233 234 Input Parameters: 235 + ao - the application ordering context 236 . n - the number of integers 237 - ia - the integers; these are replaced with their mapped value 238 239 Output Parameter: 240 . ia - the mapped integers 241 242 Level: beginner 243 244 Notes: 245 Any integers in `ia` that are negative are left unchanged. This 246 allows one to convert, for example, neighbor lists that use negative 247 entries to indicate nonexistent neighbors due to boundary conditions, etc. 248 249 Integers that are out of range are mapped to -1 250 251 .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`, 252 `AOPetscToApplicationIS()` 253 @*/ 254 PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[]) 255 { 256 PetscFunctionBegin; 257 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 258 if (n) PetscAssertPointer(ia, 3); 259 PetscUseTypeMethod(ao, applicationtopetsc, n, ia); 260 PetscFunctionReturn(PETSC_SUCCESS); 261 } 262 263 /*@ 264 AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers 265 in the PETSc ordering to the application-defined ordering. 266 267 Collective 268 269 Input Parameters: 270 + ao - The application ordering context 271 . block - The block size 272 - array - The integer array 273 274 Output Parameter: 275 . array - The permuted array 276 277 Level: beginner 278 279 Notes: 280 The length of the array should be $block*N$, where `N` is length 281 provided to the AOCreate*() method that created the `AO`. 282 283 The permutation takes `array[i_pet] --> array[i_app]`, where `i_app` is 284 the index of `i` in the application ordering and `i_pet` is the index 285 of `i` in the PETSc ordering. 286 287 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()` 288 @*/ 289 PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[]) 290 { 291 PetscFunctionBegin; 292 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 293 PetscAssertPointer(array, 3); 294 PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array); 295 PetscFunctionReturn(PETSC_SUCCESS); 296 } 297 298 /*@ 299 AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers 300 in the application-defined ordering to the PETSc ordering. 301 302 Collective 303 304 Input Parameters: 305 + ao - The application ordering context 306 . block - The block size 307 - array - The integer array 308 309 Output Parameter: 310 . array - The permuted array 311 312 Level: beginner 313 314 Notes: 315 The length of the array should be $ block*N $, where `N` is length 316 provided to the AOCreate*() method that created the `AO`. 317 318 The permutation takes `array[i_app] --> array[i_pet]`, where `i_app` is 319 the index of `i` in the application ordering and `i_pet` is the index 320 of `i` in the PETSc ordering. 321 322 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()` 323 @*/ 324 PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[]) 325 { 326 PetscFunctionBegin; 327 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 328 PetscAssertPointer(array, 3); 329 PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array); 330 PetscFunctionReturn(PETSC_SUCCESS); 331 } 332 333 /*@ 334 AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals 335 in the PETSc ordering to the application-defined ordering. 336 337 Collective 338 339 Input Parameters: 340 + ao - The application ordering context 341 . block - The block size 342 - array - The integer array 343 344 Output Parameter: 345 . array - The permuted array 346 347 Level: beginner 348 349 Notes: 350 The length of the array should be $block*N$, where `N` is length 351 provided to the AOCreate*() method that created the `AO`. 352 353 The permutation takes `array[i_pet] --> array[i_app]`, where `i_app` is 354 the index of `i` in the application ordering and `i_pet` is the index 355 of `i` in the PETSc ordering. 356 357 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()` 358 @*/ 359 PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[]) 360 { 361 PetscFunctionBegin; 362 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 363 PetscAssertPointer(array, 3); 364 PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array); 365 PetscFunctionReturn(PETSC_SUCCESS); 366 } 367 368 /*@ 369 AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals 370 in the application-defined ordering to the PETSc ordering. 371 372 Collective 373 374 Input Parameters: 375 + ao - The application ordering context 376 . block - The block size 377 - array - The integer array 378 379 Output Parameter: 380 . array - The permuted array 381 382 Level: beginner 383 384 Notes: 385 The length of the array should be $block*N$, where `N` is length 386 provided to the AOCreate*() method that created the `AO`. 387 388 The permutation takes `array[i_app] --> array[i_pet]`, where `i_app` is 389 the index of `i` in the application ordering and `i_pet` is the index 390 of `i` in the PETSc ordering. 391 392 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()` 393 @*/ 394 PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[]) 395 { 396 PetscFunctionBegin; 397 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 398 PetscAssertPointer(array, 3); 399 PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array); 400 PetscFunctionReturn(PETSC_SUCCESS); 401 } 402 403 /*@ 404 AOSetFromOptions - Sets `AO` options from the options database. 405 406 Collective 407 408 Input Parameter: 409 . ao - the application ordering 410 411 Options Database Key: 412 . -ao_type <basic, memoryscalable> - sets the type of the `AO` 413 414 Level: beginner 415 416 .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()` 417 @*/ 418 PetscErrorCode AOSetFromOptions(AO ao) 419 { 420 char type[256]; 421 const char *def = AOBASIC; 422 PetscBool flg; 423 424 PetscFunctionBegin; 425 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 426 427 PetscObjectOptionsBegin((PetscObject)ao); 428 PetscCall(PetscOptionsFList("-ao_type", "AO type", "AOSetType", AOList, def, type, 256, &flg)); 429 if (flg) { 430 PetscCall(AOSetType(ao, type)); 431 } else if (!((PetscObject)ao)->type_name) { 432 PetscCall(AOSetType(ao, def)); 433 } 434 PetscOptionsEnd(); 435 PetscFunctionReturn(PETSC_SUCCESS); 436 } 437 438 /*@ 439 AOSetIS - Sets the `IS` associated with the application ordering. 440 441 Collective 442 443 Input Parameters: 444 + ao - the application ordering 445 . isapp - index set that defines an ordering 446 - ispetsc - index set that defines another ordering (may be `NULL` to use the natural ordering) 447 448 Level: beginner 449 450 Note: 451 This routine increases the reference count of `isapp` and `ispetsc` so you may/should destroy these arguments after this call 452 if you no longer need them 453 454 .seealso: [](sec_ao), [](sec_scatter), `AO`, `AOCreate()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()` 455 @*/ 456 PetscErrorCode AOSetIS(AO ao, IS isapp, IS ispetsc) 457 { 458 PetscFunctionBegin; 459 if (ispetsc) { 460 PetscInt napp, npetsc; 461 PetscCall(ISGetLocalSize(isapp, &napp)); 462 PetscCall(ISGetLocalSize(ispetsc, &npetsc)); 463 PetscCheck(napp == npetsc, PETSC_COMM_SELF, PETSC_ERR_ARG_SIZ, "napp %" PetscInt_FMT " != npetsc %" PetscInt_FMT ". Local IS lengths must match", napp, npetsc); 464 } 465 if (isapp) PetscCall(PetscObjectReference((PetscObject)isapp)); 466 if (ispetsc) PetscCall(PetscObjectReference((PetscObject)ispetsc)); 467 PetscCall(ISDestroy(&ao->isapp)); 468 PetscCall(ISDestroy(&ao->ispetsc)); 469 ao->isapp = isapp; 470 ao->ispetsc = ispetsc; 471 PetscFunctionReturn(PETSC_SUCCESS); 472 } 473 474 /*@ 475 AOCreate - Creates an application ordering. That is an object that maps from an application ordering to a PETSc ordering and vice versa 476 477 Collective 478 479 Input Parameter: 480 . comm - MPI communicator that is to share the `AO` 481 482 Output Parameter: 483 . ao - the new application ordering 484 485 Options Database Key: 486 + -ao_type <aotype> - create `AO` with particular format 487 - -ao_view - call `AOView()` at the conclusion of `AOCreate()` 488 489 Level: beginner 490 491 .seealso: [](sec_ao), `AO`, `AOView()`, `AOSetIS()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()` 492 @*/ 493 PetscErrorCode AOCreate(MPI_Comm comm, AO *ao) 494 { 495 AO aonew; 496 497 PetscFunctionBegin; 498 PetscAssertPointer(ao, 2); 499 PetscCall(AOInitializePackage()); 500 501 PetscCall(PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView)); 502 *ao = aonew; 503 PetscFunctionReturn(PETSC_SUCCESS); 504 } 505