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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/PC/PCTelescopeSetUseCoarseDM.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>PCTelescopeSetUseCoarseDM</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/PC/PCTelescopeSetUseCoarseDM.html "><small>Report Typos and Errors</small></a></div>
<A NAME="PCTelescopeSetUseCoarseDM"><H1>PCTelescopeSetUseCoarseDM</H1></A>
Set a flag to query the <A HREF="../DM/DM.html#DM">DM</A> attached to the <A HREF="../PC/PC.html#PC">PC</A> if it also has a coarse <A HREF="../DM/DM.html#DM">DM</A>
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscksp.h"
#include "petscdm.h"
<A HREF="../Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> <A HREF="../PC/PCTelescopeSetUseCoarseDM.html#PCTelescopeSetUseCoarseDM">PCTelescopeSetUseCoarseDM</A>(<A HREF="../PC/PC.html#PC">PC</A> pc,<A HREF="../Sys/PetscBool.html#PetscBool">PetscBool</A> v)
</PRE>
Not Collective
<P>
<H3><FONT COLOR="#CC3333">Input Parameter</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>pc </B></TD><TD>- the preconditioner context
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Output Parameter</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>v </B></TD><TD>- Use <A HREF="../Sys/PETSC_FALSE.html#PETSC_FALSE">PETSC_FALSE</A> to ignore any coarse <A HREF="../DM/DM.html#DM">DM</A>
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
When you have specified to use a coarse <A HREF="../DM/DM.html#DM">DM</A>, the communicator used to create the sub-<A HREF="../KSP/KSP.html#KSP">KSP</A> within PCTelescope
will be that of the coarse <A HREF="../DM/DM.html#DM">DM</A>. Hence the flags -pc_telescope_reduction_factor and
-pc_telescope_subcomm_type will no longer have any meaning.
It is required that the communicator associated with the parent (fine) and the coarse <A HREF="../DM/DM.html#DM">DM</A> are of different sizes.
An error will occur of the size of the communicator associated with the coarse <A HREF="../DM/DM.html#DM">DM</A>
is the same as that of the parent <A HREF="../DM/DM.html#DM">DM</A>.
Furthermore, it is required that the communicator on the coarse <A HREF="../DM/DM.html#DM">DM</A> is a sub-communicator of the parent.
This will be checked at the time the preconditioner is setup and an error will occur if
the coarse <A HREF="../DM/DM.html#DM">DM</A> does not define a sub-communicator of that used by the parent <A HREF="../DM/DM.html#DM">DM</A>.
<P>
The particular Telescope setup invoked when using a coarse <A HREF="../DM/DM.html#DM">DM</A> is agnostic with respect to the type of
the <A HREF="../DM/DM.html#DM">DM</A> used (e.g. it supports DMSHELL, <A HREF="../DMPLEX/DMPLEX.html#DMPLEX">DMPLEX</A>, etc).
<P>
Support is currently only provided for the case when you are using <A HREF="../KSP/KSPSetComputeOperators.html#KSPSetComputeOperators">KSPSetComputeOperators</A>()
<P>
The user is required to compose a function with the parent <A HREF="../DM/DM.html#DM">DM</A> to facilitate the transfer of fields (<A HREF="../Vec/Vec.html#Vec">Vec</A>) between the different decompositions defined by the fine and coarse DMs.
In the user code, this is achieved via
<PRE>
{
<A HREF="../DM/DM.html#DM">DM</A> dm_fine;
<A HREF="../Sys/PetscObjectCompose.html#PetscObjectCompose">PetscObjectCompose</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)dm_fine,"PCTelescopeFieldScatter",your_field_scatter_method);
}
</PRE>
The signature of the user provided field scatter method is
<PRE>
<A HREF="../Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> your_field_scatter_method(<A HREF="../DM/DM.html#DM">DM</A> dm_fine,<A HREF="../Vec/Vec.html#Vec">Vec</A> x_fine,<A HREF="../Vec/ScatterMode.html#ScatterMode">ScatterMode</A> mode,<A HREF="../DM/DM.html#DM">DM</A> dm_coarse,<A HREF="../Vec/Vec.html#Vec">Vec</A> x_coarse);
</PRE>
The user must provide support for both mode = <A HREF="../Vec/SCATTER_FORWARD.html#SCATTER_FORWARD">SCATTER_FORWARD</A> and mode = <A HREF="../Vec/SCATTER_REVERSE.html#SCATTER_REVERSE">SCATTER_REVERSE</A>.
<A HREF="../Vec/SCATTER_FORWARD.html#SCATTER_FORWARD">SCATTER_FORWARD</A> implies the direction of transfer is from the parent (fine) <A HREF="../DM/DM.html#DM">DM</A> to the coarse <A HREF="../DM/DM.html#DM">DM</A>.
<P>
Optionally, the user may also compose a function with the parent <A HREF="../DM/DM.html#DM">DM</A> to facilitate the transfer
of state variables between the fine and coarse DMs.
In the context of a finite element discretization, an example state variable might be
values associated with quadrature points within each element.
A user provided state scatter method is composed via
<PRE>
{
<A HREF="../DM/DM.html#DM">DM</A> dm_fine;
<A HREF="../Sys/PetscObjectCompose.html#PetscObjectCompose">PetscObjectCompose</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)dm_fine,"PCTelescopeStateScatter",your_state_scatter_method);
}
</PRE>
The signature of the user provided state scatter method is
<PRE>
<A HREF="../Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> your_state_scatter_method(<A HREF="../DM/DM.html#DM">DM</A> dm_fine,<A HREF="../Vec/ScatterMode.html#ScatterMode">ScatterMode</A> mode,<A HREF="../DM/DM.html#DM">DM</A> dm_coarse);
</PRE>
<A HREF="../Vec/SCATTER_FORWARD.html#SCATTER_FORWARD">SCATTER_FORWARD</A> implies the direction of transfer is from the fine <A HREF="../DM/DM.html#DM">DM</A> to the coarse <A HREF="../DM/DM.html#DM">DM</A>.
The user is only required to support mode = <A HREF="../Vec/SCATTER_FORWARD.html#SCATTER_FORWARD">SCATTER_FORWARD</A>.
No assumption is made about the data type of the state variables.
These must be managed by the user and must be accessible from the <A HREF="../DM/DM.html#DM">DM</A>.
<P>
Care must be taken in defining the user context passed to <A HREF="../KSP/KSPSetComputeOperators.html#KSPSetComputeOperators">KSPSetComputeOperators</A>() which is to be
associated with the sub-<A HREF="../KSP/KSP.html#KSP">KSP</A> residing within PCTelescope.
In general, PCTelescope assumes that the context on the fine and coarse <A HREF="../DM/DM.html#DM">DM</A> used with
<A HREF="../KSP/KSPSetComputeOperators.html#KSPSetComputeOperators">KSPSetComputeOperators</A>() should be "similar" in type or origin.
Specifically the following rules are used to infer what context on the sub-<A HREF="../KSP/KSP.html#KSP">KSP</A> should be.
<P>
First the contexts from the <A HREF="../KSP/KSP.html#KSP">KSP</A> and the fine and coarse DMs are retrieved.
Note that the special case of a DMSHELL context is queried.
<P>
<PRE>
<A HREF="../KSP/DMKSPGetComputeOperators.html#DMKSPGetComputeOperators">DMKSPGetComputeOperators</A>(dm_fine,&dmfine_kspfunc,&dmfine_kspctx);
<A HREF="../DM/DMGetApplicationContext.html#DMGetApplicationContext">DMGetApplicationContext</A>(dm_fine,&dmfine_appctx);
<A HREF="../DM/DMShellGetContext.html#DMShellGetContext">DMShellGetContext</A>(dm_fine,&dmfine_shellctx);
<A HREF="../DM/DMGetApplicationContext.html#DMGetApplicationContext">DMGetApplicationContext</A>(dm_coarse,&dmcoarse_appctx);
<A HREF="../DM/DMShellGetContext.html#DMShellGetContext">DMShellGetContext</A>(dm_coarse,&dmcoarse_shellctx);
</PRE>
<P>
<H3><FONT COLOR="#CC3333">The following rules are then enforced</FONT></H3>
<P>
<H3><FONT COLOR="#CC3333">1. If dmfine_kspctx = NULL, then we provide a NULL pointer as the context for the sub-KSP</FONT></H3>
<A HREF="../KSP/KSPSetComputeOperators.html#KSPSetComputeOperators">KSPSetComputeOperators</A>(sub_ksp,dmfine_kspfunc,NULL);
<P>
2. If dmfine_kspctx != NULL and dmfine_kspctx == dmfine_appctx,
<H3><FONT COLOR="#CC3333">check that dmcoarse_appctx is also non-NULL. If this is true, then</FONT></H3>
<A HREF="../KSP/KSPSetComputeOperators.html#KSPSetComputeOperators">KSPSetComputeOperators</A>(sub_ksp,dmfine_kspfunc,dmcoarse_appctx);
<P>
3. If dmfine_kspctx != NULL and dmfine_kspctx == dmfine_shellctx,
<H3><FONT COLOR="#CC3333">check that dmcoarse_shellctx is also non-NULL. If this is true, then</FONT></H3>
<A HREF="../KSP/KSPSetComputeOperators.html#KSPSetComputeOperators">KSPSetComputeOperators</A>(sub_ksp,dmfine_kspfunc,dmcoarse_shellctx);
<P>
If neither of the above three tests passed, then PCTelescope cannot safely determine what
context should be provided to <A HREF="../KSP/KSPSetComputeOperators.html#KSPSetComputeOperators">KSPSetComputeOperators</A>() for use with the sub-<A HREF="../KSP/KSP.html#KSP">KSP</A>.
In this case, an additional mechanism is provided via a composed function which will return
the actual context to be used. To use this feature you must compose the "getter" function
with the coarse <A HREF="../DM/DM.html#DM">DM</A>, e.g.
<PRE>
{
<A HREF="../DM/DM.html#DM">DM</A> dm_coarse;
<A HREF="../Sys/PetscObjectCompose.html#PetscObjectCompose">PetscObjectCompose</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)dm_coarse,"PCTelescopeGetCoarseDMKSPContext",your_coarse_context_getter);
}
</PRE>
The signature of the user provided method is
<PRE>
<A HREF="../Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> your_coarse_context_getter(<A HREF="../DM/DM.html#DM">DM</A> dm_coarse,void **your_kspcontext);
</PRE>
<P>
<P>
<P><B></B><H3><FONT COLOR="#CC3333">Level</FONT></H3>advanced<BR>
<H3><FONT COLOR="#CC3333">Location</FONT></H3>
</B><A HREF="../../../src/ksp/pc/impls/telescope/telescope.c.html#PCTelescopeSetUseCoarseDM">src/ksp/pc/impls/telescope/telescope.c</A>
<P><H3><FONT COLOR="#CC3333">Examples</FONT></H3>
<A HREF="../../../src/ksp/ksp/tutorials/ex73.c.html">src/ksp/ksp/tutorials/ex73.c.html</A><BR>
<P><H3><FONT COLOR="CC3333">Implementations</FONT></H3><A HREF="../../../src/ksp/pc/impls/telescope/telescope.c.html#PCTelescopeSetUseCoarseDM_Telescope">PCTelescopeSetUseCoarseDM_Telescope in src/ksp/pc/impls/telescope/telescope.c</A><BR>
<BR><A HREF="./index.html">Index of all PC 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>
|
