1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058
|
<!DOCTYPE html>
<html lang="en" data-content_root="../" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Basic Object Design and Implementation — PETSc 3.23.1 documentation</title>
<script data-cfasync="false">
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
</script>
<!-- Loaded before other Sphinx assets -->
<link href="../_static/styles/theme.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/styles/bootstrap.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/styles/pydata-sphinx-theme.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link href="../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=bd9e20870c6007c4c509" rel="stylesheet" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" />
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=8f2a1f02" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="../_static/sphinx-design.min.css?v=87e54e7c" />
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/katex@0.16.10/dist/katex.min.css" />
<link rel="stylesheet" type="text/css" href="../_static/katex-math.css?v=91adb8b6" />
<link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=dbe1606d" />
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=bd9e20870c6007c4c509" />
<link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=bd9e20870c6007c4c509" />
<script src="../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=bd9e20870c6007c4c509"></script>
<script src="../_static/documentation_options.js?v=34da53a5"></script>
<script src="../_static/doctools.js?v=9a2dae69"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/clipboard.min.js?v=a7894cd8"></script>
<script src="../_static/copybutton.js?v=a56c686a"></script>
<script src="../_static/design-tabs.js?v=f930bc37"></script>
<script src="../_static/katex.min.js?v=be8ff15f"></script>
<script src="../_static/auto-render.min.js?v=ad136472"></script>
<script src="../_static/katex_autorenderer.js?v=bebc588a"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'developers/objects';</script>
<link rel="icon" href="../_static/petsc_favicon.png"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="How the Solvers Handle User Provided Callbacks" href="callbacks.html" />
<link rel="prev" title="The PETSc Kernel" href="kernel.html" />
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="docsearch:language" content="en"/>
<meta name="docbuild:last-update" content="2025-04-30T13:10:40-0500 (v3.23.1)"/>
</head>
<body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">
<a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a>
<div id="pst-scroll-pixel-helper"></div>
<button type="button" class="btn rounded-pill" id="pst-back-to-top">
<i class="fa-solid fa-arrow-up"></i>
Back to top
</button>
<input type="checkbox"
class="sidebar-toggle"
name="__primary"
id="__primary"/>
<label class="overlay overlay-primary" for="__primary"></label>
<input type="checkbox"
class="sidebar-toggle"
name="__secondary"
id="__secondary"/>
<label class="overlay overlay-secondary" for="__secondary"></label>
<div class="search-button__wrapper">
<div class="search-button__overlay"></div>
<div class="search-button__search-container">
<form class="bd-search d-flex align-items-center"
action="../search.html"
method="get">
<i class="fa-solid fa-magnifying-glass"></i>
<input type="search"
class="form-control"
name="q"
id="search-input"
placeholder="Search the docs ..."
aria-label="Search the docs ..."
autocomplete="off"
autocorrect="off"
autocapitalize="off"
spellcheck="false"/>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form></div>
</div>
<header>
<div class="bd-header navbar navbar-expand-lg bd-navbar">
<div class="bd-header__inner bd-page-width">
<label class="sidebar-toggle primary-toggle" for="__primary">
<span class="fa-solid fa-bars"></span>
</label>
<div class="col-lg-3 navbar-header-items__start">
<div class="navbar-item">
<a class="navbar-brand logo" href="../index.html">
<img src="../_static/PETSc-TAO_RGB.svg" class="logo__image only-light" alt="PETSc 3.23.1 documentation - Home"/>
<script>document.write(`<img src="../_static/PETSc-TAO_RGB_white.svg" class="logo__image only-dark" alt="PETSc 3.23.1 documentation - Home"/>`);</script>
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-item">
<nav class="navbar-nav">
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item">
<a class="nav-link nav-internal" href="../overview/index.html">
Overview
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../install/index.html">
Install
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../tutorials/index.html">
Tutorials
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../manual/index.html">
User-Guide
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../manualpages/index.html">
C/Fortran API
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../petsc4py/index.html">
petsc4py API
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../faq/index.html">
FAQ
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../community/index.html">
Community
</a>
</li>
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
Developers
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../miscellaneous/index.html">
Misc.
</a>
</li>
</ul>
</nav></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item navbar-persistent--container">
<script>
document.write(`
<button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
`);
</script>
</div>
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
</button>
`);
</script></div>
<div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://gitlab.com/petsc/petsc" title="GitLab" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fab fa-gitlab fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">GitLab</span></a>
</li>
</ul></div>
</div>
</div>
<div class="navbar-persistent--mobile">
<script>
document.write(`
<button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
`);
</script>
</div>
<label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0">
<span class="fa-solid fa-outdent"></span>
</label>
</div>
</div>
</header>
<div class="bd-container">
<div class="bd-container__inner bd-page-width">
<div class="bd-sidebar-primary bd-sidebar">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-item">
<nav class="navbar-nav">
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item">
<a class="nav-link nav-internal" href="../overview/index.html">
Overview
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../install/index.html">
Install
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../tutorials/index.html">
Tutorials
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../manual/index.html">
User-Guide
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../manualpages/index.html">
C/Fortran API
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../petsc4py/index.html">
petsc4py API
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../faq/index.html">
FAQ
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../community/index.html">
Community
</a>
</li>
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
Developers
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../miscellaneous/index.html">
Misc.
</a>
</li>
</ul>
</nav></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
</button>
`);
</script></div>
<div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://gitlab.com/petsc/petsc" title="GitLab" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fab fa-gitlab fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">GitLab</span></a>
</li>
</ul></div>
</div>
</div>
<div class="sidebar-primary-items__start sidebar-primary__section">
<div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
aria-label="Section Navigation">
<p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
<div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="communication.html">PETSc Developers Communication Channels</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="contributing/index.html">Contributing to PETSc</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="contributing/developingmr.html">Developing a Merge Request</a></li>
<li class="toctree-l2"><a class="reference internal" href="contributing/submittingmr.html">Submitting a Merge Request</a></li>
<li class="toctree-l2"><a class="reference internal" href="contributing/pipelines.html">GitLab CI Pipelines</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="mrmanagement.html">Merge request management</a></li>
<li class="toctree-l1"><a class="reference internal" href="development.html">PETSc Development Environment</a></li>
<li class="toctree-l1"><a class="reference internal" href="style.html">PETSc Style and Usage Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="buildsystem.html">BuildSystem</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">PETSc Testing System</a></li>
<li class="toctree-l1"><a class="reference internal" href="documentation.html">Developing PETSc Documentation</a></li>
<li class="toctree-l1 current active has-children"><a class="reference internal" href="design.html">The Design of PETSc</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-2"><i class="fa-solid fa-chevron-down"></i></label><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="kernel.html">The PETSc Kernel</a></li>
<li class="toctree-l2 current active"><a class="current reference internal" href="#">Basic Object Design and Implementation</a></li>
<li class="toctree-l2"><a class="reference internal" href="callbacks.html">How the Solvers Handle User Provided Callbacks</a></li>
<li class="toctree-l2"><a class="reference internal" href="matrices.html">The Various Matrix Classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="articles.html">Articles about PETSc Design</a></li>
</ul>
</li>
</ul>
</div>
</nav></div>
</div>
<div class="sidebar-primary-items__end sidebar-primary__section">
</div>
<div id="rtd-footer-container"></div>
</div>
<main id="main-content" class="bd-main">
<div class="bd-content">
<div class="bd-article-container">
<div class="bd-header-article">
<div class="header-article-items header-article__inner">
<div class="header-article-items__start">
<div class="header-article-item">
<nav aria-label="Breadcrumb">
<ul class="bd-breadcrumbs">
<li class="breadcrumb-item breadcrumb-home">
<a href="../index.html" class="nav-link" aria-label="Home">
<i class="fa-solid fa-home"></i>
</a>
</li>
<li class="breadcrumb-item"><a href="index.html" class="nav-link">Developers</a></li>
<li class="breadcrumb-item"><a href="design.html" class="nav-link">The Design of PETSc</a></li>
<li class="breadcrumb-item active" aria-current="page">Basic...</li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section class="tex2jax_ignore mathjax_ignore" id="basic-object-design-and-implementation">
<h1>Basic Object Design and Implementation<a class="headerlink" href="#basic-object-design-and-implementation" title="Link to this heading">#</a></h1>
<p>PETSc is designed by using strong data encapsulation. Hence, any
collection of data (for instance, a sparse matrix) is stored in a way
that is completely private from the application code. The application
code can manipulate the data only through a well-defined interface,
since it does <em>not</em> “know” how the data is stored internally.</p>
<section id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">#</a></h2>
<p>PETSc is designed around several classes including <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code> (vectors) and
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code> (matrices, both dense and sparse). Each class is implemented by
using a C <code class="docutils notranslate"><span class="pre">struct</span></code> that contains the data and function pointers for
operations on the data (much like virtual functions in C++ classes).
Each class consists of three parts:</p>
<p>A (small) common part shared by all PETSc classes (for example, both
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> have this same header).</p>
<p>Another common part shared by all PETSc implementations of the class
(for example, both <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPGMRES.html">KSPGMRES</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPCG.html">KSPCG</a></span></code> have this common
subheader).</p>
<p>A private part used by only one particular implementation written in
PETSc.</p>
<p>For example, all matrix (<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code>) classes share a function table of
operations that may be performed on the matrix; all PETSc matrix
implementations share some additional data fields, including matrix
parallel layout, while a particular matrix implementation in PETSc (say
compressed sparse row) has its own data fields for storing the actual
matrix values and sparsity pattern. This will be explained in more
detail in the following sections. New class implementations <em>must</em> use
the PETSc common part.</p>
<p>We will use <code class="docutils notranslate"><span class="pre"><class>_<implementation></span></code> to denote the actual source code
and data structures used for a particular implementation of an object
that has the <code class="docutils notranslate"><span class="pre"><class></span></code> interface.</p>
</section>
<section id="organization-of-the-source-code">
<h2>Organization of the Source Code<a class="headerlink" href="#organization-of-the-source-code" title="Link to this heading">#</a></h2>
<p>Each class has the following organization.</p>
<p>Its own, application-public, include file <code class="docutils notranslate"><span class="pre">include/petsc<class>.h</span></code>.</p>
<p>Its own directory, <code class="docutils notranslate"><span class="pre">src/<class></span></code> or <code class="docutils notranslate"><span class="pre">src/<package>/<class></span></code>.</p>
<p>A data structure defined in the file
<code class="docutils notranslate"><span class="pre">include/petsc/private/<class>impl.h</span></code>. This data structure is shared
by all the different PETSc implementations of the class. For example,
for matrices it is shared by dense, sparse, parallel, and sequential
formats.</p>
<p>An abstract interface that defines the application-callable functions
for the class. These are defined in the directory
<code class="docutils notranslate"><span class="pre">src/<class>/interface</span></code>. This is how polymorphism is supported with
code that implements the abstract interface to the operations on the
object. Essentially, these routines do some error checking of arguments
and logging of profiling information and then call the function
appropriate for the particular implementation of the object. The name of
the abstract function is <code class="docutils notranslate"><span class="pre"><class>Operation</span></code>, for instance,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/MatMult.html">MatMult</a>()</span></code> or <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PCCreate.html">PCCreate</a>(</span></code>), while the name of a particular
implementation is <code class="docutils notranslate"><span class="pre"><class>Operation_<implementation></span></code>, for instance,
<code class="docutils notranslate"><span class="pre">MatMult_SeqAIJ()</span></code> or <code class="docutils notranslate"><span class="pre">PCCreate_ILU()</span></code>. These naming conventions are
used to simplify code maintenance (also see Section [sec:stylenames]).</p>
<p>One or more actual implementations of the class (for example, sparse
uniprocessor and parallel matrices implemented with the AIJ storage
format). These are each in a subdirectory of <code class="docutils notranslate"><span class="pre">src/<class>/impls</span></code>.
Except in rare circumstances, data structures defined here should not be
referenced from outside this directory.</p>
<p>Each type of object (for instance, a vector) is defined in its own
public include file, by <code class="docutils notranslate"><span class="pre">typedef</span> <span class="pre">_p_<class>*</span> <span class="pre"><class></span></code>; (for example,
<code class="docutils notranslate"><span class="pre">typedef</span> <span class="pre">_p_Vec*</span> <span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a>;</span></code>). This organization allows the compiler to
perform type checking on all subroutine calls while at the same time
completely removing the details of the implementation of <code class="docutils notranslate"><span class="pre">_p_<class></span></code>
from the application code. This capability is extremely important
because it allows the library internals to be changed without altering
or recompiling the application code.</p>
</section>
<section id="common-object-header">
<h2>Common Object Header<a class="headerlink" href="#common-object-header" title="Link to this heading">#</a></h2>
<p>All PETSc objects (derived from the base class <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span></code>) have the following common header structures
defined in
<a href="../include/petsc/private/petscimpl.h.html">include/petsc/private/petscimpl.h</a></p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">getcomm</span><span class="p">)(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="o">*</span><span class="p">);</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">view</span><span class="p">)(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">,</span><span class="n">Viewer</span><span class="p">);</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">destroy</span><span class="p">)(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">);</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">query</span><span class="p">)(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="o">*</span><span class="p">);</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">compose</span><span class="p">)(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">);</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">composefunction</span><span class="p">)(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="p">,</span><span class="kt">void</span><span class="p">(</span><span class="o">*</span><span class="p">)(</span><span class="kt">void</span><span class="p">));</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">queryfunction</span><span class="p">)(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="o">*</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="p">(</span><span class="o">**</span><span class="p">)(</span><span class="kt">void</span><span class="p">));</span>
<span class="p">}</span><span class="w"> </span><span class="n">PetscOps</span><span class="p">;</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">_p_</span><span class="o"><</span><span class="n">class</span><span class="o">></span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscClassId.html">PetscClassId</a></span><span class="w"> </span><span class="n">classid</span><span class="p">;</span>
<span class="w"> </span><span class="n">PetscOps</span><span class="w"> </span><span class="o">*</span><span class="n">bops</span><span class="p">;</span>
<span class="w"> </span><span class="o"><</span><span class="n">class</span><span class="o">></span><span class="n">Ops</span><span class="w"> </span><span class="o">*</span><span class="n">ops</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscLogDouble.html">PetscLogDouble</a></span><span class="w"> </span><span class="n">flops</span><span class="p">,</span><span class="n">time</span><span class="p">,</span><span class="n">mem</span><span class="p">;</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">id</span><span class="p">;</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">refct</span><span class="p">;</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">tag</span><span class="p">;</span>
<span class="w"> </span><span class="n">DLList</span><span class="w"> </span><span class="n">qlist</span><span class="p">;</span>
<span class="w"> </span><span class="n">OList</span><span class="w"> </span><span class="n">olist</span><span class="p">;</span>
<span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">type_name</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">parent</span><span class="p">;</span>
<span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">;</span>
<span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">prefix</span><span class="p">;</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">cpp</span><span class="p">;</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">**</span><span class="n">fortran_func_pointers</span><span class="p">;</span>
<span class="w"> </span><span class="p">..........</span>
<span class="w"> </span><span class="n">CLASS</span><span class="o">-</span><span class="n">SPECIFIC</span><span class="w"> </span><span class="n">DATASTRUCTURES</span>
<span class="p">};</span>
</pre></div>
</div>
<p>Here <code class="docutils notranslate"><span class="pre"><class>ops</span></code> is a function table (like the <code class="docutils notranslate"><span class="pre">PetscOps</span></code> above)
that contains the function pointers for the operations specific to that
class. For example, the PETSc vector class object operations in
<a href="../include/petsc/private/vecimpl.h.html">include/petsc/private/vecimpl.h</a>
include the following.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">_VecOps</span><span class="o">*</span><span class="w"> </span><span class="n">VecOps</span><span class="p">;</span>
<span class="k">struct</span><span class="w"> </span><span class="nc">_VecOps</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">duplicate</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="o">*</span><span class="p">);</span><span class="w"> </span><span class="cm">/* get single vector */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">duplicatevecs</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="o">**</span><span class="p">);</span><span class="w"> </span><span class="cm">/* get array of vectors */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">destroyvecs</span><span class="p">)(</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">[]);</span><span class="w"> </span><span class="cm">/* free array of vectors */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">dot</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">*</span><span class="p">);</span><span class="w"> </span><span class="cm">/* z = x^H * y */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">mdot</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">[],</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">*</span><span class="p">);</span><span class="w"> </span><span class="cm">/* z[j] = x dot y[j] */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">norm</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/NormType.html">NormType</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscReal.html">PetscReal</a></span><span class="o">*</span><span class="p">);</span><span class="w"> </span><span class="cm">/* z = sqrt(x^H * x) */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">tdot</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">*</span><span class="p">);</span><span class="w"> </span><span class="cm">/* x'*y */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">mtdot</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">[],</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">*</span><span class="p">);</span><span class="cm">/* z[j] = x dot y[j] */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">scale</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="p">);</span><span class="w"> </span><span class="cm">/* x = alpha * x */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">copy</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">);</span><span class="w"> </span><span class="cm">/* y = x */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">set</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="p">);</span><span class="w"> </span><span class="cm">/* y = alpha */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">swap</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">);</span><span class="w"> </span><span class="cm">/* exchange x and y */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">axpy</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">);</span><span class="w"> </span><span class="cm">/* y = y + alpha * x */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">axpby</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">);</span><span class="w"> </span><span class="cm">/* y = alpha * x + beta * y*/</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">maxpy</span><span class="p">)(</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscScalar.html">PetscScalar</a></span><span class="o">*</span><span class="p">,</span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="o">*</span><span class="p">);</span><span class="w"> </span><span class="cm">/* y = y + alpha[j] x[j] */</span>
<span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">(</span><span class="n">AND</span><span class="w"> </span><span class="n">SO</span><span class="w"> </span><span class="n">ON</span><span class="p">)</span><span class="w"> </span><span class="p">...</span>
<span class="p">};</span>
</pre></div>
</div>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">_p_Vec</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscClassId.html">PetscClassId</a></span><span class="w"> </span><span class="n">classid</span><span class="p">;</span>
<span class="w"> </span><span class="n">PetscOps</span><span class="w"> </span><span class="o">*</span><span class="n">bops</span><span class="p">;</span>
<span class="w"> </span><span class="n">VecOps</span><span class="w"> </span><span class="o">*</span><span class="n">ops</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscLogDouble.html">PetscLogDouble</a></span><span class="w"> </span><span class="n">flops</span><span class="p">,</span><span class="n">time</span><span class="p">,</span><span class="n">mem</span><span class="p">;</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">id</span><span class="p">;</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">refct</span><span class="p">;</span>
<span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">tag</span><span class="p">;</span>
<span class="w"> </span><span class="n">DLList</span><span class="w"> </span><span class="n">qlist</span><span class="p">;</span>
<span class="w"> </span><span class="n">OList</span><span class="w"> </span><span class="n">olist</span><span class="p">;</span>
<span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">type_name</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">parent</span><span class="p">;</span>
<span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">;</span>
<span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">prefix</span><span class="p">;</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">**</span><span class="n">fortran_func_pointers</span><span class="p">;</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">data</span><span class="p">;</span><span class="w"> </span><span class="cm">/* implementation-specific data */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/IS/PetscLayout.html">PetscLayout</a></span><span class="w"> </span><span class="n">map</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/IS/ISLocalToGlobalMapping.html">ISLocalToGlobalMapping</a></span><span class="w"> </span><span class="n">mapping</span><span class="p">;</span><span class="w"> </span><span class="cm">/* mapping used in <a href="../manualpages/Vec/VecSetValuesLocal.html">VecSetValuesLocal</a>() */</span>
<span class="p">};</span>
</pre></div>
</div>
<p>Each PETSc object begins with a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscClassId.html">PetscClassId</a></span></code>, which is used for
error checking. Each different class of objects has its value for
<code class="docutils notranslate"><span class="pre">classid</span></code>; these are used to distinguish between classes. When a new
class is created you need to call</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Log/PetscClassIdRegister.html">PetscClassIdRegister</a></span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">classname</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscClassId.html">PetscClassId</a></span><span class="w"> </span><span class="o">*</span><span class="n">classid</span><span class="p">);</span>
</pre></div>
</div>
<p>For example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Log/PetscClassIdRegister.html">PetscClassIdRegister</a></span><span class="p">(</span><span class="s">"index set"</span><span class="p">,</span><span class="o">&</span><span class="n">IS_CLASSID</span><span class="p">);</span>
</pre></div>
</div>
<p>you can verify that an object is valid of a particular class with
<code class="docutils notranslate"><span class="pre">PetscValidHeaderSpecific</span></code>, for example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PetscValidHeaderSpecific</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">VEC_CLASSID</span><span class="p">,</span><span class="mi">1</span><span class="p">);</span>
</pre></div>
</div>
<p>The third argument to this macro indicates the position in the calling
sequence of the function the object was passed in. This is to generate
more complete error messages.</p>
<p>To check for an object of any type, use</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PetscValidHeader</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="mi">1</span><span class="p">);</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre">obj->ops</span></code> functions provide implementations of the standard methods of the object class. Each type
of the class may have different function pointers in the array. Subtypes sometimes replace some of the
function pointers of the parent, so they play the role of virtual methods in C++.</p>
<p>PETSc code that calls these function pointers should be done via</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscUseTypeMethod.html">PetscUseTypeMethod</a></span><span class="p">(</span><span class="n">obj</span><span class="p">,</span><span class="n">method</span><span class="p">,</span><span class="n">other</span><span class="w"> </span><span class="n">arguments</span><span class="p">);</span>
<span class="n"><a href="../manualpages/Sys/PetscTryTypeMethod.html">PetscTryTypeMethod</a></span><span class="p">(</span><span class="n">obj</span><span class="p">,</span><span class="n">method</span><span class="p">,</span><span class="n">other</span><span class="w"> </span><span class="n">arguments</span><span class="p">);</span>
</pre></div>
</div>
<p>For example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">XXXOp</span><span class="p">(</span><span class="n">XXX</span><span class="w"> </span><span class="n">x</span><span class="p">,</span><span class="n">YYY</span><span class="w"> </span><span class="n">y</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBegin.html">PetscFunctionBegin</a></span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscUseTypeMethod.html">PetscUseTypeMethod</a></span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="n">op</span><span class="p">,</span><span class="n">y</span><span class="p">);</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre">Try</span></code> variant skips the function call if the method has not been set while the <code class="docutils notranslate"><span class="pre">Use</span></code> version generates an error in that case.</p>
<p>See also, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscUseMethod.html">PetscUseMethod</a>()</span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscTryMethod.html">PetscTryMethod</a>()</span></code>.</p>
</section>
<section id="common-object-functions">
<h2>Common Object Functions<a class="headerlink" href="#common-object-functions" title="Link to this heading">#</a></h2>
<p>Several routines are provided for manipulating data within the header.
These include the specific functions in the PETSc common function table.
The function pointers are not called directly; rather you should call
<code class="docutils notranslate"><span class="pre">PetscObjectFunctionName()</span></code>, where <code class="docutils notranslate"><span class="pre">FunctionName</span></code> is one of the
functions listed below with the first letter of each word capitalized.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectGetComm.html">PetscObjectGetComm</a>()</span></code> calls the <code class="docutils notranslate"><span class="pre">getcomm(<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>,<a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a>*)</span></code> function point which obtains the MPI communicator
associated with this object.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectView.html">PetscObjectView</a>()</span></code> calls the <code class="docutils notranslate"><span class="pre">view(<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>,<a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a>)</span></code> function point which allows you to store or visualize the
data inside an object. If the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Viewer/PetscViewer.html">PetscViewer</a></span></code> is <code class="docutils notranslate"><span class="pre">NULL</span></code>, then it should cause the
object to print information on the object to <code class="docutils notranslate"><span class="pre">stdout</span></code>.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectDestroy.html">PetscObjectDestroy</a>()</span></code> calls the <code class="docutils notranslate"><span class="pre">destroy(<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>)</span></code> function pointer which causes the reference count of the object to be
decreased by one or the object to be destroyed and all memory used by
the object to be freed when the reference count drops to zero. If the
object has any other objects composed with it, the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectDestroy.html">PetscObjectDestroy</a>()</span></code> function is called on them.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectCompose.html">PetscObjectCompose</a>()</span></code> calls the <code class="docutils notranslate"><span class="pre">compose(<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>,const</span> <span class="pre">char</span> <span class="pre">*name,<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>)</span></code> function pointer which associates the
second object with the first object and increases the reference count of
the second object. If an object with the same name was previously
composed, that object is dereferenced and replaced with the new object.
If the second object is <code class="docutils notranslate"><span class="pre">NULL</span></code> and an object with the same name has
already been composed, that object is dereferenced (the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectDestroy.html">PetscObjectDestroy</a>()</span></code>
function is called on it, and that object is removed from the first
object). This is a way to remove, by name, an object that was previously
composed.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectQuery.html">PetscObjectQuery</a>()</span></code> calls the <code class="docutils notranslate"><span class="pre">query(<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>,const</span> <span class="pre">char</span> <span class="pre">*name,<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>*)</span></code> function pointer which retrieves an object
that was previously composed with the first object via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectCompose.html">PetscObjectCompose</a>()</span></code>. It retrieves a <code class="docutils notranslate"><span class="pre">NULL</span></code> if no object with that
name was previously composed.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectComposeFunction.html">PetscObjectComposeFunction</a>()</span></code> calls the <code class="docutils notranslate"><span class="pre">composefunction(<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>,const</span> <span class="pre">char</span> <span class="pre">*name,void</span> <span class="pre">*func)</span></code> function pointer which associates
a function pointer with an object. If the object already had a composed
function with the same name, the old one is replaced. If <code class="docutils notranslate"><span class="pre">func</span></code> is
<code class="docutils notranslate"><span class="pre">NULL</span></code>, the existing function is removed from the object. The string
<code class="docutils notranslate"><span class="pre">name</span></code> is the character string name of the function.</p>
<p>For example, <code class="docutils notranslate"><span class="pre">fname</span></code> may be <code class="docutils notranslate"><span class="pre">PCCreate_LU</span></code>.</p>
<p><code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectQueryFunction.html">PetscObjectQueryFunction</a>()</span></code> calls the <code class="docutils notranslate"><span class="pre">queryfunction(<a href="../manualpages/Sys/PetscObject.html">PetscObject</a>,const</span> <span class="pre">char</span> <span class="pre">*name,void</span> <span class="pre">**func)</span></code> function pointer which retrieves a
function pointer that was associated with the object via
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectComposeFunction.html">PetscObjectComposeFunction</a>()</span></code>. If dynamic libraries are used, the
function is loaded into memory at this time (if it has not been
previously loaded), not when the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectComposeFunction.html">PetscObjectComposeFunction</a>()</span></code> routine was
called.</p>
<p>Since the object composition allows one to compose PETSc objects
with PETSc objects, PETSc provides the
convenience object <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscContainer.html">PetscContainer</a></span></code>, created with the routine
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscContainerCreate.html">PetscContainerCreate</a>(<a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a>,<a href="../manualpages/Sys/PetscContainer.html">PetscContainer</a>*)</span></code>, to allow wrapping any
kind of data into a PETSc object that can then be composed with a PETSc
object. One can also use <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectContainerCompose.html">PetscObjectContainerCompose</a>()</span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectContainerQuery.html">PetscObjectContainerQuery</a>()</span></code> to compose
arbitrary pointers with a PETSc object.</p>
</section>
<section id="object-function-implementation">
<h2>Object Function Implementation<a class="headerlink" href="#object-function-implementation" title="Link to this heading">#</a></h2>
<p>This section discusses how PETSc implements the <code class="docutils notranslate"><span class="pre">compose()</span></code>,
<code class="docutils notranslate"><span class="pre">query()</span></code>, <code class="docutils notranslate"><span class="pre">composefunction()</span></code>, and <code class="docutils notranslate"><span class="pre">queryfunction()</span></code> functions
for its object implementations. Other PETSc-compatible class
implementations are free to manage these functions in any manner; but
unless there is a specific reason, they should use the PETSc defaults so
that the library writer does not have to “reinvent the wheel.”</p>
<section id="compose-and-query-objects">
<h3>Compose and Query Objects<a class="headerlink" href="#compose-and-query-objects" title="Link to this heading">#</a></h3>
<p>In
<a href="../src/sys/objects/olist.c.html">src/sys/objects/olist.c</a>
PETSc defines a C <code class="docutils notranslate"><span class="pre">struct</span></code></p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">_PetscObjectList</span><span class="o">*</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscObjectList.html">PetscObjectList</a></span><span class="p">;</span>
<span class="k">struct</span><span class="w"> </span><span class="nc">_PetscObjectList</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="n">name</span><span class="p">[</span><span class="mi">128</span><span class="p">];</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">obj</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscObjectList.html">PetscObjectList</a></span><span class="w"> </span><span class="n">next</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>from which linked lists of composed objects may be constructed. The
routines to manipulate these elementary objects are</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="nf"><a href="../manualpages/Sys/PetscObjectListAdd.html">PetscObjectListAdd</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectList.html">PetscObjectList</a></span><span class="w"> </span><span class="o">*</span><span class="n">fl</span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">obj</span><span class="p">);</span>
<span class="kt">int</span><span class="w"> </span><span class="nf"><a href="../manualpages/Sys/PetscObjectListDestroy.html">PetscObjectListDestroy</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectList.html">PetscObjectList</a></span><span class="w"> </span><span class="o">*</span><span class="n">fl</span><span class="p">);</span>
<span class="kt">int</span><span class="w"> </span><span class="nf"><a href="../manualpages/Sys/PetscObjectListFind.html">PetscObjectListFind</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectList.html">PetscObjectList</a></span><span class="w"> </span><span class="n">fl</span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="o">*</span><span class="n">obj</span><span class="p">)</span>
<span class="kt">int</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscObjectListDuplicate.html">PetscObjectListDuplicate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectList.html">PetscObjectList</a></span><span class="w"> </span><span class="n">fl</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscObjectList.html">PetscObjectList</a></span><span class="w"> </span><span class="o">*</span><span class="n">nl</span><span class="p">);</span>
</pre></div>
</div>
<p>The function <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscObjectListAdd.html">PetscObjectListAdd</a>()</span></code> will create the initial
PetscObjectList if the argument <code class="docutils notranslate"><span class="pre">fl</span></code> points to a NULL.</p>
<p>The PETSc object <code class="docutils notranslate"><span class="pre">compose()</span></code> and <code class="docutils notranslate"><span class="pre">query()</span></code> functions are as follows
(defined in
<a href="../src/sys/objects/inherit.c.html">src/sys/objects/inherit.c</a></p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PetscObjectCompose_Petsc</span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">obj</span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">ptr</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBegin.html">PetscFunctionBegin</a></span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectListAdd.html">PetscObjectListAdd</a></span><span class="p">(</span><span class="o">&</span><span class="n">obj</span><span class="o">-></span><span class="n">olist</span><span class="p">,</span><span class="n">name</span><span class="p">,</span><span class="n">ptr</span><span class="p">));</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PetscObjectQuery_Petsc</span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">obj</span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="o">*</span><span class="n">ptr</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBegin.html">PetscFunctionBegin</a></span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObjectListFind.html">PetscObjectListFind</a></span><span class="p">(</span><span class="n">obj</span><span class="o">-></span><span class="n">olist</span><span class="p">,</span><span class="n">name</span><span class="p">,</span><span class="n">ptr</span><span class="p">));</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="compose-and-query-functions">
<h3>Compose and Query Functions<a class="headerlink" href="#compose-and-query-functions" title="Link to this heading">#</a></h3>
<p>PETSc allows you to compose functions by specifying a name and function
pointer. In
<a href="../src/sys/dll/reg.c.html">src/sys/dll/reg.c</a>
PETSc defines the following linked list structure.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">_n_PetscFunctionList</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="p">(</span><span class="o">*</span><span class="n">routine</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span><span class="w"> </span><span class="cm">/* the routine */</span>
<span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">;</span><span class="w"> </span><span class="cm">/* string to identify routine */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionList.html">PetscFunctionList</a></span><span class="w"> </span><span class="n">next</span><span class="p">;</span><span class="w"> </span><span class="cm">/* next pointer */</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionList.html">PetscFunctionList</a></span><span class="w"> </span><span class="n">next_list</span><span class="p">;</span><span class="w"> </span><span class="cm">/* used to maintain list of all lists for freeing */</span>
<span class="p">};</span>
</pre></div>
</div>
<p>Each PETSc object contains a <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFunctionList.html">PetscFunctionList</a></span></code> object. The
<code class="docutils notranslate"><span class="pre">composefunction()</span></code> and <code class="docutils notranslate"><span class="pre">queryfunction()</span></code> are given by the
following.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PetscObjectComposeFunction_Petsc</span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">obj</span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ptr</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBegin.html">PetscFunctionBegin</a></span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscFunctionListAdd.html">PetscFunctionListAdd</a></span><span class="p">(</span><span class="o">&</span><span class="n">obj</span><span class="o">-></span><span class="n">qlist</span><span class="p">,</span><span class="n">name</span><span class="p">,</span><span class="n">fname</span><span class="p">,</span><span class="n">ptr</span><span class="p">));</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
<span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf">PetscObjectQueryFunction_Petsc</span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscObject.html">PetscObject</a></span><span class="w"> </span><span class="n">obj</span><span class="p">,</span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">name</span><span class="p">,</span><span class="kt">void</span><span class="w"> </span><span class="p">(</span><span class="o">**</span><span class="n">ptr</span><span class="p">)(</span><span class="kt">void</span><span class="p">))</span>
<span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBegin.html">PetscFunctionBegin</a></span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscCall.html">PetscCall</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscFunctionListFind.html">PetscFunctionListFind</a></span><span class="p">(</span><span class="n">obj</span><span class="o">-></span><span class="n">qlist</span><span class="p">,</span><span class="n">name</span><span class="p">,</span><span class="n">ptr</span><span class="p">));</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In addition to using the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscFunctionList.html">PetscFunctionList</a></span></code> mechanism to compose
functions into PETSc objects, it is also used to allow registration of
new class implementations; for example, new preconditioners.</p>
<p>PETSc code that calls composed functions should be done via</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscUseMethod.html">PetscUseMethod</a></span><span class="p">(</span><span class="n">obj</span><span class="p">,</span><span class="s">"method"</span><span class="p">,(</span><span class="n">Argument</span><span class="w"> </span><span class="n">types</span><span class="p">),(</span><span class="n">argument</span><span class="w"> </span><span class="n">variables</span><span class="p">));</span>
<span class="n"><a href="../manualpages/Sys/PetscTryMethod.html">PetscTryMethod</a></span><span class="p">(</span><span class="n">obj</span><span class="p">,</span><span class="s">"method"</span><span class="p">,(</span><span class="n">Argument</span><span class="w"> </span><span class="n">types</span><span class="p">),(</span><span class="n">argument</span><span class="w"> </span><span class="n">variables</span><span class="p">));</span>
</pre></div>
</div>
<p>For example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf"><a href="../manualpages/KSP/KSPGMRESSetRestart.html">KSPGMRESSetRestart</a></span><span class="p">(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="w"> </span><span class="n">ksp</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="w"> </span><span class="n">restart</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBegin.html">PetscFunctionBegin</a></span><span class="p">;</span>
<span class="w"> </span><span class="n">PetscValidLogicalCollectiveInt</span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="n">restart</span><span class="p">,</span><span class="mi">2</span><span class="p">);</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscTryMethod.html">PetscTryMethod</a></span><span class="p">(</span><span class="n">ksp</span><span class="p">,</span><span class="s">"KSPGMRESSetRestart_C"</span><span class="p">,(</span><span class="n"><a href="../manualpages/KSP/KSP.html">KSP</a></span><span class="p">,</span><span class="n"><a href="../manualpages/Sys/PetscInt.html">PetscInt</a></span><span class="p">),(</span><span class="n">ksp</span><span class="p">,</span><span class="n">restart</span><span class="p">));</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionReturn.html">PetscFunctionReturn</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PETSC_SUCCESS</a></span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils notranslate"><span class="pre">Try</span></code> variant skips the function call if the method has not been composed with
the object while the <code class="docutils notranslate"><span class="pre">Use</span></code> version generates an error in that case.
See also, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscUseTypeMethod.html">PetscUseTypeMethod</a>()</span></code>, and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscTryTypeMethod.html">PetscTryTypeMethod</a>()</span></code>.</p>
</section>
<section id="simple-petsc-objects">
<h3>Simple PETSc Objects<a class="headerlink" href="#simple-petsc-objects" title="Link to this heading">#</a></h3>
<p>Some simple PETSc objects do not need <code class="docutils notranslate"><span class="pre">PETSCHEADER</span></code> and the associated
functionality. These objects are internally named as <code class="docutils notranslate"><span class="pre">_n_<class></span></code> as
opposed to <code class="docutils notranslate"><span class="pre">_p_<class></span></code>, for example, <code class="docutils notranslate"><span class="pre">_n_PetscFunctionList</span></code> vs <code class="docutils notranslate"><span class="pre">_p_Vec</span></code>.</p>
</section>
</section>
<section id="petsc-packages">
<h2>PETSc Packages<a class="headerlink" href="#petsc-packages" title="Link to this heading">#</a></h2>
<p>The PETSc source code is divided into the following library-level
packages: <code class="docutils notranslate"><span class="pre">Sys</span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Vec/Vec.html">Vec</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Mat/Mat.html">Mat</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/DM/DM.html">DM</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/SNES/SNES.html">SNES</a></span></code>, <code class="docutils notranslate"><span class="pre"><a href="../manualpages/TS/TS.html">TS</a></span></code>,
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/Tao/Tao.html">Tao</a></span></code>. Each of these has a directory under the <code class="docutils notranslate"><span class="pre">src</span></code> directory in
the PETSc tree and, optionally, can be compiled into separate libraries.
Each package defines one or more classes; for example, the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code>
package defines the <code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSP.html">KSP</a></span></code> and <code class="docutils notranslate"><span class="pre"><a href="../manualpages/PC/PC.html">PC</a></span></code> classes, as well as several
utility classes. In addition, each library-level package may contain
several class-level packages associated with individual classes in the
library-level package. In general, most “important” classes in PETSc
have their own class level package. Each package provides a registration
function <code class="docutils notranslate"><span class="pre">XXXInitializePackage()</span></code>, for example
<code class="docutils notranslate"><span class="pre"><a href="../manualpages/KSP/KSPInitializePackage.html">KSPInitializePackage</a>()</span></code>, which registers all the classes and events
for that package. Each package also registers a finalization routine,
<code class="docutils notranslate"><span class="pre">XXXFinalizePackage()</span></code>, that releases all the resources used in
registering the package, using <code class="docutils notranslate"><span class="pre"><a href="../manualpages/Sys/PetscRegisterFinalize.html">PetscRegisterFinalize</a>()</span></code>. The
registration for each package is performed “on demand” the first time a
class in the package is utilized. This is handled, for example, with
code such as</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n"><a href="../manualpages/Sys/PetscErrorCode.html">PetscErrorCode</a></span><span class="w"> </span><span class="nf"><a href="../manualpages/Vec/VecCreate.html">VecCreate</a></span><span class="p">(</span><span class="n"><a href="../manualpages/Sys/MPI_Comm.html">MPI_Comm</a></span><span class="w"> </span><span class="n">comm</span><span class="p">,</span><span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="o">*</span><span class="n">vec</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Vec/Vec.html">Vec</a></span><span class="w"> </span><span class="n">v</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Sys/PetscFunctionBegin.html">PetscFunctionBegin</a></span><span class="p">;</span>
<span class="w"> </span><span class="n">PetscAssertPointer</span><span class="p">(</span><span class="n">vec</span><span class="p">,</span><span class="mi">2</span><span class="p">);</span>
<span class="w"> </span><span class="o">*</span><span class="n">vec</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>
<span class="w"> </span><span class="n"><a href="../manualpages/Vec/VecInitializePackage.html">VecInitializePackage</a></span><span class="p">();</span>
<span class="w"> </span><span class="p">...</span>
</pre></div>
</div>
</section>
</section>
</article>
<footer class="prev-next-footer">
<div class="prev-next-area">
<a class="left-prev"
href="kernel.html"
title="previous page">
<i class="fa-solid fa-angle-left"></i>
<div class="prev-next-info">
<p class="prev-next-subtitle">previous</p>
<p class="prev-next-title">The PETSc Kernel</p>
</div>
</a>
<a class="right-next"
href="callbacks.html"
title="next page">
<div class="prev-next-info">
<p class="prev-next-subtitle">next</p>
<p class="prev-next-title">How the Solvers Handle User Provided Callbacks</p>
</div>
<i class="fa-solid fa-angle-right"></i>
</a>
</div>
</footer>
</div>
<div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">
<div class="sidebar-secondary-item">
<div
id="pst-page-navigation-heading-2"
class="page-toc tocsection onthispage">
<i class="fa-solid fa-list"></i> On this page
</div>
<nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#introduction">Introduction</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#organization-of-the-source-code">Organization of the Source Code</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#common-object-header">Common Object Header</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#common-object-functions">Common Object Functions</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#object-function-implementation">Object Function Implementation</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#compose-and-query-objects">Compose and Query Objects</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#compose-and-query-functions">Compose and Query Functions</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#simple-petsc-objects">Simple PETSc Objects</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#petsc-packages">PETSc Packages</a></li>
</ul>
</nav></div>
<div class="sidebar-secondary-item">
<div class="tocsection editthispage">
<a href="https://gitlab.com/petsc/petsc/-/edit/release/doc/developers/objects.md">
<i class="fa-solid fa-pencil"></i>
Edit on GitLab
</a>
</div>
</div>
<div class="sidebar-secondary-item">
<div class="tocsection sourcelink">
<a href="../_sources/developers/objects.md.txt">
<i class="fa-solid fa-file-lines"></i> Show Source
</a>
</div>
</div>
</div></div>
</div>
<footer class="bd-footer-content">
</footer>
</main>
</div>
</div>
<!-- Scripts loaded after <body> so the DOM is not blocked -->
<script src="../_static/scripts/bootstrap.js?digest=bd9e20870c6007c4c509"></script>
<script src="../_static/scripts/pydata-sphinx-theme.js?digest=bd9e20870c6007c4c509"></script>
<footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
<div class="footer-items__start">
<div class="footer-item">
<p class="copyright">
© Copyright 1991-2025, UChicago Argonne, LLC and the PETSc Development Team.
<br/>
</p>
</div>
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
<br/>
</p>
</div>
</div>
<div class="footer-items__end">
<div class="footer-item">
<p class="theme-version">
Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.1.
</p></div>
<div class="footer-item"><p class="last-updated">
Last updated on 2025-04-30T13:10:40-0500 (v3.23.1).
<br/>
</p></div>
</div>
</div>
</footer>
</body>
</html>
|