File: MatCreateShell.html

package info (click to toggle)
petsc 3.10.3%2Bdfsg1-5
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 209,064 kB
  • sloc: ansic: 587,333; python: 29,696; makefile: 12,445; fortran: 11,626; f90: 9,677; cpp: 8,768; sh: 1,027; xml: 621; objc: 445; csh: 194; java: 13
file content (159 lines) | stat: -rw-r--r-- 8,929 bytes parent folder | download 
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
 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Mat/MatCreateShell.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>MatCreateShell</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
   <div id="version" align=right><b>petsc-3.10.3 2018-12-18</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.10.3 v3.10.3 docs/manualpages/Mat/MatCreateShell.html "><small>Report Typos and Errors</small></a></div>
<A NAME="MatCreateShell"><H1>MatCreateShell</H1></A>
Creates a new matrix class for use with a user-defined private data storage format. 
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscmat.h" 
<A HREF="../Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A>  <A HREF="../Mat/MatCreateShell.html#MatCreateShell">MatCreateShell</A>(<A HREF="../Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</A> comm,<A HREF="../Sys/PetscInt.html#PetscInt">PetscInt</A> m,<A HREF="../Sys/PetscInt.html#PetscInt">PetscInt</A> n,<A HREF="../Sys/PetscInt.html#PetscInt">PetscInt</A> M,<A HREF="../Sys/PetscInt.html#PetscInt">PetscInt</A> N,void *ctx,<A HREF="../Mat/Mat.html#Mat">Mat</A> *A)
</PRE>
Collective on <A HREF="../Sys/MPI_Comm.html#MPI_Comm">MPI_Comm</A>
<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>comm </B></TD><TD>- MPI communicator
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>m </B></TD><TD>- number of local rows (must be given)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>n </B></TD><TD>- number of local columns (must be given)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>M </B></TD><TD>- number of global rows (may be <A HREF="../Sys/PETSC_DETERMINE.html#PETSC_DETERMINE">PETSC_DETERMINE</A>)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>N </B></TD><TD>- number of global columns (may be <A HREF="../Sys/PETSC_DETERMINE.html#PETSC_DETERMINE">PETSC_DETERMINE</A>)
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>ctx </B></TD><TD>- pointer to data needed by the shell matrix routines
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Output Parameter</FONT></H3>
<DT><B>A </B> -the matrix
<br>
<P>

<P>
<H3><FONT COLOR="#CC3333">Usage</FONT></H3>
<pre>
   extern int mult(<A HREF="../Mat/Mat.html#Mat">Mat</A>,<A HREF="../Vec/Vec.html#Vec">Vec</A>,<A HREF="../Vec/Vec.html#Vec">Vec</A>);
</pre>
<pre>
   <A HREF="../Mat/MatCreateShell.html#MatCreateShell">MatCreateShell</A>(comm,m,n,M,N,ctx,&amp;mat);
</pre>
<pre>
   <A HREF="../Mat/MatShellSetOperation.html#MatShellSetOperation">MatShellSetOperation</A>(mat,MATOP_MULT,(void(*)(void))mult);
</pre>
<pre>
   [ Use matrix for operations that have been set ]
</pre>
<pre>
   <A HREF="../Mat/MatDestroy.html#MatDestroy">MatDestroy</A>(mat);
</pre>
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
The shell matrix type is intended to provide a simple class to use
with <A HREF="../KSP/KSP.html#KSP">KSP</A> (such as, for use with matrix-free methods). You should not
use the shell type if you plan to define a complete matrix class.
<P>
<H3><FONT COLOR="#CC3333">Fortran Notes</FONT></H3>
To use this from Fortran with a ctx you must write an interface definition for this
function and for <A HREF="../Mat/MatShellGetContext.html#MatShellGetContext">MatShellGetContext</A>() that tells Fortran the Fortran derived data type you are passing
in as the ctx argument.
<P>
PETSc requires that matrices and vectors being used for certain
operations are partitioned accordingly.  For example, when
creating a shell matrix, A, that supports parallel matrix-vector
products using <A HREF="../Mat/MatMult.html#MatMult">MatMult</A>(A,x,y) the user should set the number
of local matrix rows to be the number of local elements of the
corresponding result vector, y. Note that this is information is
required for use of the matrix interface routines, even though
the shell matrix may not actually be physically partitioned.
For example,
<P>
<pre>
</pre>
<pre>
    <A HREF="../Vec/Vec.html#Vec">Vec</A> x, y
</pre>
<pre>
    extern int mult(<A HREF="../Mat/Mat.html#Mat">Mat</A>,<A HREF="../Vec/Vec.html#Vec">Vec</A>,<A HREF="../Vec/Vec.html#Vec">Vec</A>);
</pre>
<pre>
    <A HREF="../Mat/Mat.html#Mat">Mat</A> A
</pre>
<pre>
</pre>
<pre>
    <A HREF="../Vec/VecCreateMPI.html#VecCreateMPI">VecCreateMPI</A>(comm,<A HREF="../Sys/PETSC_DECIDE.html#PETSC_DECIDE">PETSC_DECIDE</A>,M,&amp;y);
</pre>
<pre>
    <A HREF="../Vec/VecCreateMPI.html#VecCreateMPI">VecCreateMPI</A>(comm,<A HREF="../Sys/PETSC_DECIDE.html#PETSC_DECIDE">PETSC_DECIDE</A>,N,&amp;x);
</pre>
<pre>
    <A HREF="../Vec/VecGetLocalSize.html#VecGetLocalSize">VecGetLocalSize</A>(y,&amp;m);
</pre>
<pre>
    <A HREF="../Vec/VecGetLocalSize.html#VecGetLocalSize">VecGetLocalSize</A>(x,&amp;n);
</pre>
<pre>
    <A HREF="../Mat/MatCreateShell.html#MatCreateShell">MatCreateShell</A>(comm,m,n,M,N,ctx,&amp;A);
</pre>
<pre>
    <A HREF="../Mat/MatShellSetOperation.html#MatShellSetOperation">MatShellSetOperation</A>(mat,MATOP_MULT,(void(*)(void))mult);
</pre>
<pre>
    <A HREF="../Mat/MatMult.html#MatMult">MatMult</A>(A,x,y);
</pre>
<pre>
    <A HREF="../Mat/MatDestroy.html#MatDestroy">MatDestroy</A>(A);
</pre>
<pre>
    <A HREF="../Vec/VecDestroy.html#VecDestroy">VecDestroy</A>(y); <A HREF="../Vec/VecDestroy.html#VecDestroy">VecDestroy</A>(x);
</pre>
<pre>
</pre>
<P>
<P>
<A HREF="../Mat/MATSHELL.html#MATSHELL">MATSHELL</A> handles <A HREF="../Mat/MatShift.html#MatShift">MatShift</A>(), <A HREF="../Mat/MatDiagonalSet.html#MatDiagonalSet">MatDiagonalSet</A>(), <A HREF="../Mat/MatDiagonalScale.html#MatDiagonalScale">MatDiagonalScale</A>(), <A HREF="../Mat/MatAXPY.html#MatAXPY">MatAXPY</A>(), and <A HREF="../Mat/MatScale.html#MatScale">MatScale</A>() internally so these
operations cannot be overwritten unless <A HREF="../Mat/MatShellSetManageScalingShifts.html#MatShellSetManageScalingShifts">MatShellSetManageScalingShifts</A>() is called.
<P>
<P>
For rectangular matrices do all the scalings and shifts make sense?
<P>
<H3><FONT COLOR="#CC3333">Developers Notes</FONT></H3>
Regarding shifting and scaling. The general form is
<P>
diag(left)(vscale*A + diag(dshift) + vshift I)diag(right)
<P>
The order you apply the operations is important. For example if you have a dshift then
apply a <A HREF="../Mat/MatScale.html#MatScale">MatScale</A>(s) you get s*vscale*A + s*diag(shift). But if you first scale and then shift
you get s*vscale*A + diag(shift)
<P>
A is the user provided function.
<P>
<H3><FONT COLOR="#CC3333">Keywords</FONT></H3>
 matrix, shell, create
<BR>
<P>
<H3><FONT COLOR="#CC3333">See Also</FONT></H3>
 <A HREF="../Mat/MatShellSetOperation.html#MatShellSetOperation">MatShellSetOperation</A>(), <A HREF="../Mat/MatHasOperation.html#MatHasOperation">MatHasOperation</A>(), <A HREF="../Mat/MatShellGetContext.html#MatShellGetContext">MatShellGetContext</A>(), <A HREF="../Mat/MatShellSetContext.html#MatShellSetContext">MatShellSetContext</A>(), <A HREF="../Mat/MATSHELL.html#MATSHELL">MATSHELL</A>, <A HREF="../Mat/MatShellSetManageScalingShifts.html#MatShellSetManageScalingShifts">MatShellSetManageScalingShifts</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/mat/impls/shell/shell.c.html#MatCreateShell">src/mat/impls/shell/shell.c</A>
<P><H3><FONT COLOR="#CC3333">Examples</FONT></H3>
<A HREF="../../../src/mat/examples/tutorials/ex6f.F90.html">src/mat/examples/tutorials/ex6f.F90.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex14f.F90.html">src/ksp/ksp/examples/tutorials/ex14f.F90.html</A><BR>
<A HREF="../../../src/ts/examples/tutorials/ex22f_mf.F90.html">src/ts/examples/tutorials/ex22f_mf.F90.html</A><BR>
<A HREF="../../../src/tao/unconstrained/examples/tutorials/eptorsion1.c.html">src/tao/unconstrained/examples/tutorials/eptorsion1.c.html</A><BR>
<A HREF="../../../src/tao/bound/examples/tutorials/plate2.c.html">src/tao/bound/examples/tutorials/plate2.c.html</A><BR>
<A HREF="../../../src/tao/pde_constrained/examples/tutorials/elliptic.c.html">src/tao/pde_constrained/examples/tutorials/elliptic.c.html</A><BR>
<A HREF="../../../src/tao/pde_constrained/examples/tutorials/parabolic.c.html">src/tao/pde_constrained/examples/tutorials/parabolic.c.html</A><BR>
<A HREF="../../../src/tao/pde_constrained/examples/tutorials/hyperbolic.c.html">src/tao/pde_constrained/examples/tutorials/hyperbolic.c.html</A><BR>
<BR><A HREF="./index.html">Index of all Mat 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>