File: KSPSetOperators.html

package info (click to toggle)
petsc 3.7.5%2Bdfsg1-4
links: PTS, VCS
area: main
in suites: stretch
size: 163,864 kB
ctags: 618,438
sloc: ansic: 515,133; python: 29,793; makefile: 20,458; fortran: 18,998; cpp: 6,515; f90: 3,914; sh: 1,012; xml: 621; objc: 445; csh: 240; java: 13
file content (131 lines) | stat: -rw-r--r-- 9,127 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/KSP/KSPSetOperators.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>KSPSetOperators</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
   <div id="version" align=right><b>petsc-3.7.5 2017-01-01</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.7.5 v3.7.5 docs/manualpages/KSP/KSPSetOperators.html "><small>Report Typos and Errors</small></a></div>
<A NAME="KSPSetOperators"><H1>KSPSetOperators</H1></A>
Sets the matrix associated with the linear system and a (possibly) different one associated with the preconditioner. 
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
#include "petscksp.h" 
PetscErrorCode  KSPSetOperators(KSP ksp,Mat Amat,Mat Pmat)
</PRE>
Collective on <A HREF="../KSP/KSP.html#KSP">KSP</A> and <A HREF="../Mat/Mat.html#Mat">Mat</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>ksp </B></TD><TD>- the <A HREF="../KSP/KSP.html#KSP">KSP</A> context
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>Amat </B></TD><TD>- the matrix that defines the linear system
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>Pmat </B></TD><TD>- the matrix to be used in constructing the preconditioner, usually the same as Amat.
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#CC3333">Notes</FONT></H3>
<P>
If you know the operator Amat has a null space you can use <A HREF="../Mat/MatSetNullSpace.html#MatSetNullSpace">MatSetNullSpace</A>() and <A HREF="../Mat/MatSetTransposeNullSpace.html#MatSetTransposeNullSpace">MatSetTransposeNullSpace</A>() to supply the null
space to Amat and the <A HREF="../KSP/KSP.html#KSP">KSP</A> solvers will automatically use that null space as needed during the solution process.
<P>
All future calls to <A HREF="../KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</A>() must use the same size matrices!
<P>
Passing a NULL for Amat or Pmat removes the matrix that is currently used.
<P>
If you wish to replace either Amat or Pmat but leave the other one untouched then
first call <A HREF="../KSP/KSPGetOperators.html#KSPGetOperators">KSPGetOperators</A>() to get the one you wish to keep, call <A HREF="../Sys/PetscObjectReference.html#PetscObjectReference">PetscObjectReference</A>()
on it and then pass it back in in your call to <A HREF="../KSP/KSPSetOperators.html#KSPSetOperators">KSPSetOperators</A>().
<P>

<P>
Alternative usage: If the operators have NOT been set with <A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>() then the operators
are created in <A HREF="../PC/PC.html#PC">PC</A> and returned to the user. In this case, if both operators
mat and pmat are requested, two DIFFERENT operators will be returned. If
only one is requested both operators in the <A HREF="../PC/PC.html#PC">PC</A> will be the same (i.e. as
if one had called <A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>() with the same argument for both Mats).
The user must set the sizes of the returned matrices and their type etc just
as if the user created them with <A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(). For example,
<P>
<pre>
        <A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCGetOperators.html#PCGetOperators">PCGetOperators</A>(ksp/pc,&amp;mat,NULL); is equivalent to
</pre>
<pre>
          set size, type, etc of mat
</pre>
<P>
<pre>
        <A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(comm,&amp;mat);
</pre>
<pre>
        <A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>(ksp/pc,mat,mat);
</pre>
<pre>
        <A HREF="../Sys/PetscObjectDereference.html#PetscObjectDereference">PetscObjectDereference</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)mat);
</pre>
<pre>
          set size, type, etc of mat
</pre>
<P>
and
<P>
<pre>
        <A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCGetOperators.html#PCGetOperators">PCGetOperators</A>(ksp/pc,&amp;mat,&amp;pmat); is equivalent to
</pre>
<pre>
          set size, type, etc of mat and pmat
</pre>
<P>
<pre>
        <A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(comm,&amp;mat);
</pre>
<pre>
        <A HREF="../Mat/MatCreate.html#MatCreate">MatCreate</A>(comm,&amp;pmat);
</pre>
<pre>
        <A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>(ksp/pc,mat,pmat);
</pre>
<pre>
        <A HREF="../Sys/PetscObjectDereference.html#PetscObjectDereference">PetscObjectDereference</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)mat);
</pre>
<pre>
        <A HREF="../Sys/PetscObjectDereference.html#PetscObjectDereference">PetscObjectDereference</A>((<A HREF="../Sys/PetscObject.html#PetscObject">PetscObject</A>)pmat);
</pre>
<pre>
          set size, type, etc of mat and pmat
</pre>
<P>
The rational for this support is so that when creating a <A HREF="../TS/TS.html#TS">TS</A>, <A HREF="../SNES/SNES.html#SNES">SNES</A>, or <A HREF="../KSP/KSP.html#KSP">KSP</A> the hierarchy
of underlying objects (i.e. <A HREF="../SNES/SNES.html#SNES">SNES</A>, <A HREF="../KSP/KSP.html#KSP">KSP</A>, <A HREF="../PC/PC.html#PC">PC</A>, <A HREF="../Mat/Mat.html#Mat">Mat</A>) and their livespans can be completely
managed by the top most level object (i.e. the <A HREF="../TS/TS.html#TS">TS</A>, <A HREF="../SNES/SNES.html#SNES">SNES</A>, or <A HREF="../KSP/KSP.html#KSP">KSP</A>). Another way to look
at this is when you create a <A HREF="../SNES/SNES.html#SNES">SNES</A> you do not NEED to create a <A HREF="../KSP/KSP.html#KSP">KSP</A> and attach it to
the <A HREF="../SNES/SNES.html#SNES">SNES</A> object (the <A HREF="../SNES/SNES.html#SNES">SNES</A> object manages it for you). Similarly when you create a <A HREF="../KSP/KSP.html#KSP">KSP</A>
you do not need to attach a <A HREF="../PC/PC.html#PC">PC</A> to it (the <A HREF="../KSP/KSP.html#KSP">KSP</A> object manages the <A HREF="../PC/PC.html#PC">PC</A> object for you).
Thus, why should YOU have to create the <A HREF="../Mat/Mat.html#Mat">Mat</A> and attach it to the <A HREF="../SNES/SNES.html#SNES">SNES</A>/<A HREF="../KSP/KSP.html#KSP">KSP</A>/<A HREF="../PC/PC.html#PC">PC</A>, when
it can be created for you?
<P>
<H3><FONT COLOR="#CC3333">Keywords</FONT></H3>
 <A HREF="../KSP/KSP.html#KSP">KSP</A>, set, operators, matrix, preconditioner, linear system
<BR>
<P>
<H3><FONT COLOR="#CC3333">See Also</FONT></H3>
 <A HREF="../KSP/KSPSolve.html#KSPSolve">KSPSolve</A>(), <A HREF="../KSP/KSPGetPC.html#KSPGetPC">KSPGetPC</A>(), <A HREF="../PC/PCGetOperators.html#PCGetOperators">PCGetOperators</A>(), <A HREF="../PC/PCSetOperators.html#PCSetOperators">PCSetOperators</A>(), <A HREF="../KSP/KSPGetOperators.html#KSPGetOperators">KSPGetOperators</A>(), <A HREF="../KSP/KSPSetComputeOperators.html#KSPSetComputeOperators">KSPSetComputeOperators</A>(), <A HREF="../KSP/KSPSetComputeInitialGuess.html#KSPSetComputeInitialGuess">KSPSetComputeInitialGuess</A>(), <A HREF="../KSP/KSPSetComputeRHS.html#KSPSetComputeRHS">KSPSetComputeRHS</A>()
<BR><P><B><P><B><FONT COLOR="#CC3333">Level:</FONT></B>beginner
<BR><FONT COLOR="#CC3333">Location:</FONT></B><A HREF="../../../src/ksp/ksp/interface/itcreate.c.html#KSPSetOperators">src/ksp/ksp/interface/itcreate.c</A>
<BR><A HREF="./index.html">Index of all KSP 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>
<P><H3><FONT COLOR="#CC3333">Examples</FONT></H3>
<A HREF="../../../src/ksp/pc/examples/tutorials/ex1.c.html">src/ksp/pc/examples/tutorials/ex1.c.html</A><BR>
<A HREF="../../../src/ksp/pc/examples/tutorials/ex2.c.html">src/ksp/pc/examples/tutorials/ex2.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex1.c.html">src/ksp/ksp/examples/tutorials/ex1.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex2.c.html">src/ksp/ksp/examples/tutorials/ex2.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex3.c.html">src/ksp/ksp/examples/tutorials/ex3.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex4.c.html">src/ksp/ksp/examples/tutorials/ex4.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex5.c.html">src/ksp/ksp/examples/tutorials/ex5.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex6.c.html">src/ksp/ksp/examples/tutorials/ex6.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex7.c.html">src/ksp/ksp/examples/tutorials/ex7.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex8.c.html">src/ksp/ksp/examples/tutorials/ex8.c.html</A><BR>
<A HREF="../../../src/ksp/ksp/examples/tutorials/ex9.c.html">src/ksp/ksp/examples/tutorials/ex9.c.html</A><BR>
</BODY></HTML>