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