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 /*@C 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()` 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 /*@C 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 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 105 PETSC_INTERN PetscErrorCode ISSetUp_General(IS); 106 107 /*@ 108 AOPetscToApplicationIS - Maps an index set in the PETSc ordering to 109 the application-defined ordering. 110 111 Collective 112 113 Input Parameters: 114 + ao - the application ordering context 115 - is - the index set; this is replaced with its mapped values 116 117 Output Parameter: 118 . is - the mapped index set 119 120 Level: intermediate 121 122 Notes: 123 The index set cannot be of type stride or block 124 125 Any integers in is that are negative are left unchanged. This 126 allows one to convert, for example, neighbor lists that use negative 127 entries to indicate nonexistent neighbors due to boundary conditions etc. 128 129 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, 130 `AOApplicationToPetscIS()`, `AOPetscToApplication()` 131 @*/ 132 PetscErrorCode AOPetscToApplicationIS(AO ao, IS is) 133 { 134 PetscInt n; 135 PetscInt *ia; 136 137 PetscFunctionBegin; 138 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 139 PetscValidHeaderSpecific(is, IS_CLASSID, 2); 140 PetscCall(ISToGeneral(is)); 141 /* we cheat because we know the IS is general and that we can change the indices */ 142 PetscCall(ISGetIndices(is, (const PetscInt **)&ia)); 143 PetscCall(ISGetLocalSize(is, &n)); 144 PetscUseTypeMethod(ao, petsctoapplication, n, ia); 145 PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia)); 146 /* updated cached values (sorted, min, max, etc.)*/ 147 PetscCall(ISSetUp_General(is)); 148 PetscFunctionReturn(PETSC_SUCCESS); 149 } 150 151 /*@ 152 AOApplicationToPetscIS - Maps an index set in the application-defined 153 ordering to the PETSc ordering. 154 155 Collective 156 157 Input Parameters: 158 + ao - the application ordering context 159 - is - the index set; this is replaced with its mapped values 160 161 Output Parameter: 162 . is - the mapped index set 163 164 Level: beginner 165 166 Notes: 167 The index set cannot be of type stride or block 168 169 Any integers in is that are negative are left unchanged. This 170 allows one to convert, for example, neighbor lists that use negative 171 entries to indicate nonexistent neighbors due to boundary conditions, etc. 172 173 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`, 174 `AOPetscToApplicationIS()`, `AOApplicationToPetsc()` 175 @*/ 176 PetscErrorCode AOApplicationToPetscIS(AO ao, IS is) 177 { 178 PetscInt n, *ia; 179 180 PetscFunctionBegin; 181 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 182 PetscValidHeaderSpecific(is, IS_CLASSID, 2); 183 PetscCall(ISToGeneral(is)); 184 /* we cheat because we know the IS is general and that we can change the indices */ 185 PetscCall(ISGetIndices(is, (const PetscInt **)&ia)); 186 PetscCall(ISGetLocalSize(is, &n)); 187 PetscUseTypeMethod(ao, applicationtopetsc, n, ia); 188 PetscCall(ISRestoreIndices(is, (const PetscInt **)&ia)); 189 /* updated cached values (sorted, min, max, etc.)*/ 190 PetscCall(ISSetUp_General(is)); 191 PetscFunctionReturn(PETSC_SUCCESS); 192 } 193 194 /*@ 195 AOPetscToApplication - Maps a set of integers in the PETSc ordering to 196 the application-defined ordering. 197 198 Collective 199 200 Input Parameters: 201 + ao - the application ordering context 202 . n - the number of integers 203 - ia - the integers; these are replaced with their mapped value 204 205 Output Parameter: 206 . ia - the mapped integers 207 208 Level: beginner 209 210 Note: 211 Any integers in ia[] that are negative are left unchanged. This 212 allows one to convert, for example, neighbor lists that use negative 213 entries to indicate nonexistent neighbors due to boundary conditions, etc. 214 215 Integers that are out of range are mapped to -1 216 217 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, 218 `AOPetscToApplicationIS()` 219 @*/ 220 PetscErrorCode AOPetscToApplication(AO ao, PetscInt n, PetscInt ia[]) 221 { 222 PetscFunctionBegin; 223 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 224 if (n) PetscAssertPointer(ia, 3); 225 PetscUseTypeMethod(ao, petsctoapplication, n, ia); 226 PetscFunctionReturn(PETSC_SUCCESS); 227 } 228 229 /*@ 230 AOApplicationToPetsc - Maps a set of integers in the application-defined 231 ordering to the PETSc ordering. 232 233 Collective 234 235 Input Parameters: 236 + ao - the application ordering context 237 . n - the number of integers 238 - ia - the integers; these are replaced with their mapped value 239 240 Output Parameter: 241 . ia - the mapped integers 242 243 Level: beginner 244 245 Notes: 246 Any integers in ia[] that are negative are left unchanged. This 247 allows one to convert, for example, neighbor lists that use negative 248 entries to indicate nonexistent neighbors due to boundary conditions, etc. 249 250 Integers that are out of range are mapped to -1 251 252 .seealso: [](sec_ao), `AOCreateBasic()`, `AOView()`, `AOPetscToApplication()`, 253 `AOPetscToApplicationIS()` 254 @*/ 255 PetscErrorCode AOApplicationToPetsc(AO ao, PetscInt n, PetscInt ia[]) 256 { 257 PetscFunctionBegin; 258 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 259 if (n) PetscAssertPointer(ia, 3); 260 PetscUseTypeMethod(ao, applicationtopetsc, n, ia); 261 PetscFunctionReturn(PETSC_SUCCESS); 262 } 263 264 /*@ 265 AOPetscToApplicationPermuteInt - Permutes an array of blocks of integers 266 in the PETSc ordering to the application-defined ordering. 267 268 Collective 269 270 Input Parameters: 271 + ao - The application ordering context 272 . block - The block size 273 - array - The integer array 274 275 Output Parameter: 276 . array - The permuted array 277 278 Level: beginner 279 280 Notes: 281 The length of the array should be block*N, where N is length 282 provided to the AOCreate*() method that created the AO. 283 284 The permutation takes array[i_pet] --> array[i_app], where i_app is 285 the index of 'i' in the application ordering and i_pet is the index 286 of 'i' in the petsc ordering. 287 288 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()` 289 @*/ 290 PetscErrorCode AOPetscToApplicationPermuteInt(AO ao, PetscInt block, PetscInt array[]) 291 { 292 PetscFunctionBegin; 293 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 294 PetscAssertPointer(array, 3); 295 PetscUseTypeMethod(ao, petsctoapplicationpermuteint, block, array); 296 PetscFunctionReturn(PETSC_SUCCESS); 297 } 298 299 /*@ 300 AOApplicationToPetscPermuteInt - Permutes an array of blocks of integers 301 in the application-defined ordering to the PETSc ordering. 302 303 Collective 304 305 Input Parameters: 306 + ao - The application ordering context 307 . block - The block size 308 - array - The integer array 309 310 Output Parameter: 311 . array - The permuted array 312 313 Level: beginner 314 315 Notes: 316 The length of the array should be block*N, where N is length 317 provided to the AOCreate*() method that created the AO. 318 319 The permutation takes array[i_app] --> array[i_pet], where i_app is 320 the index of 'i' in the application ordering and i_pet is the index 321 of 'i' in the petsc ordering. 322 323 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOPetscToApplicationIS()`, `AOApplicationToPetsc()` 324 @*/ 325 PetscErrorCode AOApplicationToPetscPermuteInt(AO ao, PetscInt block, PetscInt array[]) 326 { 327 PetscFunctionBegin; 328 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 329 PetscAssertPointer(array, 3); 330 PetscUseTypeMethod(ao, applicationtopetscpermuteint, block, array); 331 PetscFunctionReturn(PETSC_SUCCESS); 332 } 333 334 /*@ 335 AOPetscToApplicationPermuteReal - Permutes an array of blocks of reals 336 in the PETSc ordering to the application-defined ordering. 337 338 Collective 339 340 Input Parameters: 341 + ao - The application ordering context 342 . block - The block size 343 - array - The integer array 344 345 Output Parameter: 346 . array - The permuted array 347 348 Level: beginner 349 350 Notes: 351 The length of the array should be block*N, where N is length 352 provided to the AOCreate*() method that created the AO. 353 354 The permutation takes array[i_pet] --> array[i_app], where i_app is 355 the index of 'i' in the application ordering and i_pet is the index 356 of 'i' in the petsc ordering. 357 358 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()` 359 @*/ 360 PetscErrorCode AOPetscToApplicationPermuteReal(AO ao, PetscInt block, PetscReal array[]) 361 { 362 PetscFunctionBegin; 363 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 364 PetscAssertPointer(array, 3); 365 PetscUseTypeMethod(ao, petsctoapplicationpermutereal, block, array); 366 PetscFunctionReturn(PETSC_SUCCESS); 367 } 368 369 /*@ 370 AOApplicationToPetscPermuteReal - Permutes an array of blocks of reals 371 in the application-defined ordering to the PETSc ordering. 372 373 Collective 374 375 Input Parameters: 376 + ao - The application ordering context 377 . block - The block size 378 - array - The integer array 379 380 Output Parameter: 381 . array - The permuted array 382 383 Level: beginner 384 385 Notes: 386 The length of the array should be block*N, where N is length 387 provided to the AOCreate*() method that created the AO. 388 389 The permutation takes array[i_app] --> array[i_pet], where i_app is 390 the index of 'i' in the application ordering and i_pet is the index 391 of 'i' in the petsc ordering. 392 393 .seealso: [](sec_ao), `AO`, `AOCreateBasic()`, `AOView()`, `AOApplicationToPetsc()`, `AOPetscToApplicationIS()` 394 @*/ 395 PetscErrorCode AOApplicationToPetscPermuteReal(AO ao, PetscInt block, PetscReal array[]) 396 { 397 PetscFunctionBegin; 398 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 399 PetscAssertPointer(array, 3); 400 PetscUseTypeMethod(ao, applicationtopetscpermutereal, block, array); 401 PetscFunctionReturn(PETSC_SUCCESS); 402 } 403 404 /*@ 405 AOSetFromOptions - Sets `AO` options from the options database. 406 407 Collective 408 409 Input Parameter: 410 . ao - the application ordering 411 412 Level: beginner 413 414 .seealso: [](sec_ao), `AO`, `AOCreate()`, `AOSetType()`, `AODestroy()`, `AOPetscToApplication()`, `AOApplicationToPetsc()` 415 @*/ 416 PetscErrorCode AOSetFromOptions(AO ao) 417 { 418 char type[256]; 419 const char *def = AOBASIC; 420 PetscBool flg; 421 422 PetscFunctionBegin; 423 PetscValidHeaderSpecific(ao, AO_CLASSID, 1); 424 425 PetscObjectOptionsBegin((PetscObject)ao); 426 PetscCall(PetscOptionsFList("-ao_type", "AO type", "AOSetType", AOList, def, type, 256, &flg)); 427 if (flg) { 428 PetscCall(AOSetType(ao, type)); 429 } else if (!((PetscObject)ao)->type_name) { 430 PetscCall(AOSetType(ao, def)); 431 } 432 PetscOptionsEnd(); 433 PetscFunctionReturn(PETSC_SUCCESS); 434 } 435 436 /*@ 437 AOSetIS - Sets the `IS` associated with the application ordering. 438 439 Collective 440 441 Input Parameters: 442 + ao - the application ordering 443 . isapp - index set that defines an ordering 444 - ispetsc - index set that defines another ordering (may be `NULL` to use the 445 natural ordering) 446 447 Level: beginner 448 449 Notes: 450 The index sets isapp and ispetsc are used only for creation of ao. 451 452 This routine increases the reference count of isapp and ispetsc so you may/should destroy these arguments after this call 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`, `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 *ao = NULL; 500 PetscCall(AOInitializePackage()); 501 502 PetscCall(PetscHeaderCreate(aonew, AO_CLASSID, "AO", "Application Ordering", "AO", comm, AODestroy, AOView)); 503 *ao = aonew; 504 PetscFunctionReturn(PETSC_SUCCESS); 505 } 506