# Diff of /trunk/doc/user/Models.tex

revision 2473 by gross, Tue May 26 02:26:52 2009 UTC revision 2474 by gross, Tue Jun 16 06:32:15 2009 UTC
# Line 81  S p =  B A^{-1} G Line 81  S p =  B A^{-1} G
81
82  with the Schur complement \index{Schur complement} $S=BA^{-1}B^{*}$. This problem can be solved iteratively  with the Schur complement \index{Schur complement} $S=BA^{-1}B^{*}$. This problem can be solved iteratively
83  with the preconditioner $\hat{S}$ defined as $q=\hat{S}^{-1}p$ by solving  with the preconditioner $\hat{S}$ defined as $q=\hat{S}^{-1}p$ by solving
84     \label{P PREC}
85  \frac{1}{\eta}q = p  \frac{1}{\eta}q = p
86
87  see~\cite{ELMAN} for more details. Note that the residual for the current approximation $p$ is given as  see~\cite{ELMAN} for more details. Note that the residual for the current approximation $p$ is given as
# Line 128  ATOL = \epsilon \frac{\|\sqrt{v^{0}\hack Line 128  ATOL = \epsilon \frac{\|\sqrt{v^{0}\hack
128
129  \subsection{Functions}  \subsection{Functions}
130
132  opens the Stokes problem\index{Stokes problem} on the \Domain domain. The approximation  opens the Stokes problem\index{Stokes problem} on the \Domain domain. The approximation
133  order needs to be two.  order needs to be two.
135    the tolerances for all subproblems are set automatically.
136  \end{classdesc}  \end{classdesc}
137
# Line 142  the values of \var{fixed_u_mask}. The me Line 144  the values of \var{fixed_u_mask}. The me
144  \Data class objects.  \Data class objects.
145  \end{methoddesc}  \end{methoddesc}
146
147  \begin{methoddesc}[StokesProblemCartesian]{solve}{v,p,  \begin{methoddesc}[StokesProblemCartesian]{solve}{v,p
148  \optional{max_iter=20, \optional{verbose=False, \optional{usePCG=True}}}}  \optional{, max_iter=100 \optional{, verbose=False \optional{, usePCG=True }}}}
149  solves the problem and return approximations for velocity and pressure.  solves the problem and return approximations for velocity and pressure.
150  The arguments \var{v} and \var{p} define initial guess. The values of \var{v} marked  The arguments \var{v} and \var{p} define initial guess. The values of \var{v} marked
# Line 151  If \var{usePCG} is set to \True Line 153  If \var{usePCG} is set to \True
153  reconditioned conjugate gradient method (PCG) \index{preconditioned conjugate gradient method!PCG}  scheme is used. Otherwise the problem is solved generalized minimal residual method (GMRES) \index{generalized minimal residual method!GMRES}. In most cases  reconditioned conjugate gradient method (PCG) \index{preconditioned conjugate gradient method!PCG}  scheme is used. Otherwise the problem is solved generalized minimal residual method (GMRES) \index{generalized minimal residual method!GMRES}. In most cases
154  the PCG scheme is more efficient.  the PCG scheme is more efficient.
155  \var{max_iter} defines the maximum number of iteration steps.  \var{max_iter} defines the maximum number of iteration steps.
156
157  If \var{verbose} is set to \True informations on the progress of of the solver are printed.  If \var{verbose} is set to \True informations on the progress of of the solver are printed.
158  \end{methoddesc}  \end{methoddesc}
159
# Line 165  returns the current relative tolerance. Line 168  returns the current relative tolerance.
168  sets the absolute tolerance for the error in the relevant norm. The tolerance must be non-negative. Typically the  sets the absolute tolerance for the error in the relevant norm. The tolerance must be non-negative. Typically the
169  absolute talerance is set to 0.  absolute talerance is set to 0.
170  \end{methoddesc}  \end{methoddesc}
171
172  \begin{methoddesc}[StokesProblemCartesian]{getAbsoluteTolerance}{}  \begin{methoddesc}[StokesProblemCartesian]{getAbsoluteTolerance}{}
173  sreturns the current absolute tolerance.  sreturns the current absolute tolerance.
174  \end{methoddesc}  \end{methoddesc}
175  \begin{methoddesc}[StokesProblemCartesian]{setSubProblemTolerance}{\optional{rtol=None}}
176  sets the tolerance to solve the involved PDEs. The subtolerance \var{rtol} should not be choosen to large  \begin{methoddesc}[StokesProblemCartesian]{getSolverOptionsVelocity}{}
177  in order to avoid feed back of errors in the subproblem solution into the outer iteration.  returns the solver options used  solve the equations~(\ref{V CALC}) for velocity.
178  On the otherhand is choosen to small compute time is wasted.  \end{methoddesc}
179  If \var{rtol} is set to \var{None} the sub-tolerance is set automatically depending on the
180  tolerance choosen for the oter iteration.  \begin{methoddesc}[StokesProblemCartesian]{getSolverOptionsPressure}{}
181    returns the solver options used  solve the equation~(\label{P PREC}) for pressure.
182  \end{methoddesc}  \end{methoddesc}
183  \begin{methoddesc}[StokesProblemCartesian]{getSubProblemTolerance}{}
184  return the tolerance for the involved PDEs.  \begin{methoddesc}[StokesProblemCartesian]{getSolverOptionsDiv}{}
185    set the solver options for solving the equation to project the divergence of the velocity onto the function space of pressure.
186  \end{methoddesc}  \end{methoddesc}
187
188
189  \subsection{Example: Lit Driven Cavity}  \subsection{Example: Lit Driven Cavity}
190   The following script \file{lit\hackscore driven\hackscore cavity.py}   The following script \file{lit\hackscore driven\hackscore cavity.py}
191  \index{scripts!\file{helmholtz.py}} which is available in the \ExampleDirectory  \index{scripts!\file{helmholtz.py}} which is available in the \ExampleDirectory
# Line 334  The problem is that ATOL is depending on Line 341  The problem is that ATOL is depending on
341  to get a first value for ATOL. If the stopping crierion is met in the PCG iteration, a new $v$ is calculated from the current pressure approximation and ATOL is recalculated. If \ref{DARCY STOP} is still fullfilled the calculation is terminated and $(v,p)$ is returned. Otherwise PCG is restarted with a new ATOL.  to get a first value for ATOL. If the stopping crierion is met in the PCG iteration, a new $v$ is calculated from the current pressure approximation and ATOL is recalculated. If \ref{DARCY STOP} is still fullfilled the calculation is terminated and $(v,p)$ is returned. Otherwise PCG is restarted with a new ATOL.
342
343  \subsection{Functions}  \subsection{Functions}
345  opens the Darcy flux problem\index{Darcy flux} on the \Domain domain.  opens the Darcy flux problem\index{Darcy flux} on the \Domain domain.
346    If \var{adaptSubTolerance} is set to \True,
347    the relative tolerances for solving~(\ref{DARCY V FORM}),~(\ref{UPDATE W})
348    and~(\ref{UPDATE P}) are set automatically.
349  \end{classdesc}  \end{classdesc}
350
351  \begin{methoddesc}[DarcyFlow]{setValue}{\optional{f=None, \optional{g=None, \optional{location_of_fixed_pressure=None, \optional{location_of_fixed_flux=None, \optional{permeability=None}}}}}}  \begin{methoddesc}[DarcyFlow]{setValue}{\optional{f=None, \optional{g=None, \optional{location_of_fixed_pressure=None, \optional{location_of_fixed_flux=None, \optional{permeability=None}}}}}}
352  assigns values to the model parameters. Values can be assigned using various calls - in particular  assigns values to the model parameters. Values can be assigned using various calls - in particular
353  in a time dependend problem only values that change over time needs to be reset. The permability can be defined as scalar (isotropic), a vector (orthotropic) or a matrix (anisotropic).  in a time dependend problem only values that change over time needs to be reset. The permability can be defined as scalar (isotropic), a vector (orthotropic) or a matrix (anisotropic).
# Line 360  sets the relative tolerance \mbox{rtol} Line 371  sets the relative tolerance \mbox{rtol}
371  sets the absolute tolerance \mbox{atol} in \ref{DARCY ATOL DEF}.  sets the absolute tolerance \mbox{atol} in \ref{DARCY ATOL DEF}.
372  \end{methoddesc}  \end{methoddesc}
373
374  \begin{methoddesc}[DarcyFlow]{setSubProblemTolerance}{\optional{rtol=None}}  \begin{methoddesc}[DarcyFlow]{getSolverOptionsFlux}{}
375  sets the relative tolerance used to solve the involved PDEs. If no argument is given,  Returns the solver options used to solve the flux problems~(\ref{DARCY V FORM}) and~(\ref{UPDATE W}). Use the returned \SolverOptions object to control the solution algorithms. If the adaption of subtolerance is choosen, the tolerance will
376  the square of the current relative tolerance is used. The sub-problem tolerance should be choosen as large as possible to minimize the compute time. However, a too large value for the sub-problem tolerance may lead to slow convergence or even dibergence in the outer iteration.  be overwritten before the solver is called.
377  \end{methoddesc}  \end{methoddesc}
378
379  \begin{methoddesc}[DarcyFlow]{solve}{u0,p0, \optional{max_iter=100, \optional{verbose=False \optional{sub_rtol=1.e-8}}}}  \begin{methoddesc}[DarcyFlow]{getSolverOptionsPressure}{}
380    Returns the solver options used to solve the pressure problems~(\ref{UPDATE P}).
381    Use the returned \SolverOptions object to control the solution algorithms. If the adaption of subtolerance is choosen, the tolerance will
382    be overwritten before the solver is called.
383    \end{methoddesc}
384
385    \begin{methoddesc}[DarcyFlow]{solve}{u0,p0, \optional{max_iter=100, \optional{verbose=False}}}
386  solves the problem. and returns approximations for the flux $v$ and the pressure $p$.  solves the problem. and returns approximations for the flux $v$ and the pressure $p$.
387  \var{u0} and \var{p0} define initial guess for flux and pressure. Values marked  \var{u0} and \var{p0} define initial guess for flux and pressure. Values marked
388  by positive values \var{location_of_fixed_flux} and \var{location_of_fixed_pressure}, respectively, are kept unchanged.  by positive values \var{location_of_fixed_flux} and \var{location_of_fixed_pressure}, respectively, are kept unchanged. \var{max_iter} sets the maximum number of iterations steps allowed for solving the coupled problem.
389  \end{methoddesc}  \end{methoddesc}
390
391
# Line 540  domain Line 557  domain
557  \optional{, p=0  \optional{, p=0
558  \optional{, t=0  \optional{, t=0
559  \optional{, numMaterials=1  \optional{, numMaterials=1
560  \optional{, verbose=True}}}}}}}  \optional{, verbose=True
562    }}}}}}}}
563  opens an incompressible, isotropic flow problem in Cartesian cooridninates  opens an incompressible, isotropic flow problem in Cartesian cooridninates
564  on the domain \var{domain}.  on the domain \var{domain}.
565  \var{stress},  \var{stress},
# Line 549  on the domain \var{domain}. Line 568  on the domain \var{domain}.
568  \var{t} set the initial deviatoric stress, velocity, pressure and time.  \var{t} set the initial deviatoric stress, velocity, pressure and time.
569  \var{numMaterials} specifies the number of materials used in the power law  \var{numMaterials} specifies the number of materials used in the power law
570  model. Some progress information are printed if \var{verbose} is set to  model. Some progress information are printed if \var{verbose} is set to
571  \True.  \True. If \var{adaptSubTolerance} is equal to True the tolerances for subproblems are set automatically.
572  \end{classdesc}  \end{classdesc}
573
574  \begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getDomain}{}  \begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{getDomain}{}
# Line 597  Sets the tolerance used to terminate the Line 616  Sets the tolerance used to terminate the
616  Sets the relative tolerance for the incompressible solver, see \class{StokesProblemCartesian} for details.  Sets the relative tolerance for the incompressible solver, see \class{StokesProblemCartesian} for details.
617  \end{methoddesc}  \end{methoddesc}
618
619  \begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setFlowSubTolerance}{tol=1.e-8}  \begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setElasticShearModulus}{mu=None}
Sets the relative tolerance for the subsolver of the flow solver, see
\class{StokesProblemCartesian} for details.\begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setElasticShearModulus}{mu=None}
620  Sets the elastic shear modulus $\mu$. If \var{mu} is set to None (default) elasticity is not applied.  Sets the elastic shear modulus $\mu$. If \var{mu} is set to None (default) elasticity is not applied.
621  \end{methoddesc}  \end{methoddesc}
\end{methoddesc}
622
623  \begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setEtaTolerance=}{rtol=1.e-8}  \begin{methoddesc}[IncompressibleIsotropicFlowCartesian]{setEtaTolerance=}{rtol=1.e-8}
624  sets the relative tolerance for the effectice viscosity. Iteration on a time step is completed if the realtive of the effective viscosity is less than \var{rtol}.  sets the relative tolerance for the effectice viscosity. Iteration on a time step is completed if the realtive of the effective viscosity is less than \var{rtol}.

Legend:
 Removed from v.2473 changed lines Added in v.2474