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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMGetCompatibility.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>DMGetCompatibility</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<div id="version" align=right><b>petsc-3.14.5 2021-03-03</b></div>
<div id="bugreport" align=right><a href="mailto:petsc-maint@mcs.anl.gov?subject=Typo or Error in Documentation &body=Please describe the typo or error in the documentation: petsc-3.14.5 v3.14.5 docs/manualpages/DM/DMGetCompatibility.html "><small>Report Typos and Errors</small></a></div>
<A NAME="DMGetCompatibility"><H1>DMGetCompatibility</H1></A>
determine if two DMs are compatible
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscdm.h"
#include "petscdmlabel.h"
#include "petscds.h"
<A HREF="../Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> <A HREF="../DM/DMGetCompatibility.html#DMGetCompatibility">DMGetCompatibility</A>(<A HREF="../DM/DM.html#DM">DM</A> dm1,<A HREF="../DM/DM.html#DM">DM</A> dm2,<A HREF="../Sys/PetscBool.html#PetscBool">PetscBool</A> *compatible,<A HREF="../Sys/PetscBool.html#PetscBool">PetscBool</A> *set)
</PRE>
Collective
<P>
<H3><FONT COLOR="#CC3333">Input Parameters</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>dm1 </B></TD><TD>- the first <A HREF="../DM/DM.html#DM">DM</A>
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>dm2 </B></TD><TD>- the second <A HREF="../DM/DM.html#DM">DM</A>
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Output Parameters</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>compatible </B></TD><TD>- whether or not the two DMs are compatible
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>set </B></TD><TD>- whether or not the compatible value was set
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
Two DMs are deemed compatible if they represent the same parallel decomposition
of the same topology. This implies that the section (field data) on one
"makes sense" with respect to the topology and parallel decomposition of the other.
Loosely speaking, compatible DMs represent the same domain and parallel
decomposition, but hold different data.
<P>
Typically, one would confirm compatibility if intending to simultaneously iterate
over a pair of vectors obtained from different DMs.
<P>
For example, two <A HREF="../DMDA/DMDA.html#DMDA">DMDA</A> objects are compatible if they have the same local
and global sizes and the same stencil width. They can have different numbers
of degrees of freedom per node. Thus, one could use the node numbering from
either <A HREF="../DM/DM.html#DM">DM</A> in bounds for a loop over vectors derived from either <A HREF="../DM/DM.html#DM">DM</A>.
<P>
Consider the operation of summing data living on a 2-dof <A HREF="../DMDA/DMDA.html#DMDA">DMDA</A> to data living
on a 1-dof <A HREF="../DMDA/DMDA.html#DMDA">DMDA</A>, which should be compatible, as in the following snippet.
<PRE>
...
ierr = <A HREF="../DM/DMGetCompatibility.html#DMGetCompatibility">DMGetCompatibility</A>(da1,da2,&compatible,&set);<A HREF="../Sys/CHKERRQ.html#CHKERRQ">CHKERRQ</A>(ierr);
if (set && compatible) {
ierr = <A HREF="../DMDA/DMDAVecGetArrayDOF.html#DMDAVecGetArrayDOF">DMDAVecGetArrayDOF</A>(da1,vec1,&arr1);<A HREF="../Sys/CHKERRQ.html#CHKERRQ">CHKERRQ</A>(ierr);
ierr = <A HREF="../DMDA/DMDAVecGetArrayDOF.html#DMDAVecGetArrayDOF">DMDAVecGetArrayDOF</A>(da2,vec2,&arr2);<A HREF="../Sys/CHKERRQ.html#CHKERRQ">CHKERRQ</A>(ierr);
ierr = <A HREF="../DMDA/DMDAGetCorners.html#DMDAGetCorners">DMDAGetCorners</A>(da1,&x,&y,NULL,&m,&n,NULL);<A HREF="../Sys/CHKERRQ.html#CHKERRQ">CHKERRQ</A>(ierr);
for (j=y; j<y+n; ++j) {
for (i=x; i<x+m, ++i) {
arr1[j][i][0] = arr2[j][i][0] + arr2[j][i][1];
}
}
ierr = <A HREF="../DMDA/DMDAVecRestoreArrayDOF.html#DMDAVecRestoreArrayDOF">DMDAVecRestoreArrayDOF</A>(da1,vec1,&arr1);<A HREF="../Sys/CHKERRQ.html#CHKERRQ">CHKERRQ</A>(ierr);
ierr = <A HREF="../DMDA/DMDAVecRestoreArrayDOF.html#DMDAVecRestoreArrayDOF">DMDAVecRestoreArrayDOF</A>(da2,vec2,&arr2);<A HREF="../Sys/CHKERRQ.html#CHKERRQ">CHKERRQ</A>(ierr);
} else {
<A HREF="../Sys/SETERRQ.html#SETERRQ">SETERRQ</A>(<A HREF="../Sys/PetscObjectComm.html#PetscObjectComm">PetscObjectComm</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)da1,PETSC_ERR_ARG_INCOMP,"<A HREF="../DMDA/DMDA.html#DMDA">DMDA</A> objects incompatible");
}
...
</PRE>
<P>
Checking compatibility might be expensive for a given implementation of <A HREF="../DM/DM.html#DM">DM</A>,
or might be impossible to unambiguously confirm or deny. For this reason,
this function may decline to determine compatibility, and hence users should
always check the "set" output parameter.
<P>
A <A HREF="../DM/DM.html#DM">DM</A> is always compatible with itself.
<P>
In the current implementation, DMs which live on "unequal" communicators
(MPI_UNEQUAL in the terminology of MPI_Comm_compare()) are always deemed
incompatible.
<P>
This function is labeled "Collective," as information about all subdomains
is required on each rank. However, in <A HREF="../DM/DM.html#DM">DM</A> implementations which store all this
information locally, this function may be merely "Logically Collective".
<P>
<H3><FONT COLOR="#CC3333">Developer Notes</FONT></H3>
Compatibility is assumed to be a symmetric concept; <A HREF="../DM/DM.html#DM">DM</A> A is compatible with <A HREF="../DM/DM.html#DM">DM</A> B
iff B is compatible with A. Thus, this function checks the implementations
of both dm and dmc (if they are of different types), attempting to determine
compatibility. It is left to <A HREF="../DM/DM.html#DM">DM</A> implementers to ensure that symmetry is
preserved. The simplest way to do this is, when implementing type-specific
logic for this function, is to check for existing logic in the implementation
of other <A HREF="../DM/DM.html#DM">DM</A> types and let *set = <A HREF="../Sys/PETSC_FALSE.html#PETSC_FALSE">PETSC_FALSE</A> if found.
<P>
<P>
<H3><FONT COLOR="#CC3333">See Also</FONT></H3>
<A HREF="../DM/DM.html#DM">DM</A>, <A HREF="../DMDA/DMDACreateCompatibleDMDA.html#DMDACreateCompatibleDMDA">DMDACreateCompatibleDMDA</A>(), <A HREF="../DMSTAG/DMStagCreateCompatibleDMStag.html#DMStagCreateCompatibleDMStag">DMStagCreateCompatibleDMStag</A>()
<BR><P><B></B><H3><FONT COLOR="#CC3333">Level</FONT></H3>advanced<BR>
<H3><FONT COLOR="#CC3333">Location</FONT></H3>
</B><A HREF="../../../src/dm/interface/dm.c.html#DMGetCompatibility">src/dm/interface/dm.c</A>
<P><H3><FONT COLOR="CC3333">Implementations</FONT></H3><A HREF="../../../src/dm/impls/da/da.c.html#DMGetCompatibility_DA">DMGetCompatibility_DA in src/dm/impls/da/da.c</A><BR>
<A HREF="../../../src/dm/impls/stag/stag.c.html#DMGetCompatibility_Stag">DMGetCompatibility_Stag in src/dm/impls/stag/stag.c</A><BR>
<BR><A HREF="./index.html">Index of all DM routines</A>
<BR><A HREF="../../index.html">Table of Contents for all manual pages</A>
<BR><A HREF="../singleindex.html">Index of all manual pages</A>
</BODY></HTML>
|
