/[escript]/trunk/escript/py_src/linearPDEs.py
ViewVC logotype

Diff of /trunk/escript/py_src/linearPDEs.py

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2549 by jfenwick, Mon Jul 20 06:43:47 2009 UTC revision 2816 by artak, Thu Dec 10 02:09:43 2009 UTC
# Line 21  __url__="https://launchpad.net/escript-f Line 21  __url__="https://launchpad.net/escript-f
21    
22  """  """
23  The module provides an interface to define and solve linear partial  The module provides an interface to define and solve linear partial
24  differential equations (PDEs) and Transport problems within L{escript}.  differential equations (PDEs) and Transport problems within `escript`.
25  L{linearPDEs} does not provide any solver capabilities in itself but hands the  `linearPDEs` does not provide any solver capabilities in itself but hands the
26  PDE over to the PDE solver library defined through the L{Domain<escript.Domain>}  PDE over to the PDE solver library defined through the `Domain`
27  of the PDE. The general interface is provided through the L{LinearPDE} class.  of the PDE. The general interface is provided through the `LinearPDE` class.
28  L{TransportProblem} provides an interface to initial value problems dominated  `TransportProblem` provides an interface to initial value problems dominated
29  by its advective terms.  by its advective terms.
30    
31  @var __author__: name of author  :var __author__: name of author
32  @var __copyright__: copyrights  :var __copyright__: copyrights
33  @var __license__: licence agreement  :var __license__: licence agreement
34  @var __url__: url entry point on documentation  :var __url__: url entry point on documentation
35  @var __version__: version  :var __version__: version
36  @var __date__: date of the version  :var __date__: date of the version
37  """  """
38    
39  import math  import math
# Line 52  class SolverOptions(object): Line 52  class SolverOptions(object):
52            
53      Typical usage is      Typical usage is
54            
55      opts=SolverOptions()      ::
56      print opts      
57      opts.resetDiagnostics()        opts=SolverOptions()
58      u=solver(opts)        print opts
59      print "number of iteration steps: =",opts.getDiagnostics("num_iter")        opts.resetDiagnostics()
60              u=solver(opts)
61          print "number of iteration steps: =",opts.getDiagnostics("num_iter")
62      @cvar DEFAULT: The default method used to solve the system of linear equations  
63      @cvar DIRECT: The direct solver based on LDU factorization      :cvar DEFAULT: The default method used to solve the system of linear equations
64      @cvar CHOLEVSKY: The direct solver based on LDLt factorization (can only be applied for symmetric PDEs)      :cvar DIRECT: The direct solver based on LDU factorization
65      @cvar PCG: The preconditioned conjugate gradient method (can only be applied for symmetric PDEs)      :cvar CHOLEVSKY: The direct solver based on LDLt factorization (can only be applied for symmetric PDEs)
66      @cvar CR: The conjugate residual method      :cvar PCG: The preconditioned conjugate gradient method (can only be applied for symmetric PDEs)
67      @cvar CGS: The conjugate gradient square method      :cvar CR: The conjugate residual method
68      @cvar BICGSTAB: The stabilized Bi-Conjugate Gradient method      :cvar CGS: The conjugate gradient square method
69      @cvar TFQMR: Transport Free Quasi Minimal Residual method      :cvar BICGSTAB: The stabilized Bi-Conjugate Gradient method
70      @cvar MINRES: Minimum residual method      :cvar TFQMR: Transport Free Quasi Minimal Residual method
71      @cvar SSOR: The symmetric over-relaxation method      :cvar MINRES: Minimum residual method
72      @cvar ILU0: The incomplete LU factorization preconditioner with no fill-in      :cvar SSOR: The symmetric over-relaxation method
73      @cvar ILUT: The incomplete LU factorization preconditioner with fill-in      :cvar ILU0: The incomplete LU factorization preconditioner with no fill-in
74      @cvar JACOBI: The Jacobi preconditioner      :cvar ILUT: The incomplete LU factorization preconditioner with fill-in
75      @cvar GMRES: The Gram-Schmidt minimum residual method      :cvar JACOBI: The Jacobi preconditioner
76      @cvar PRES20: Special GMRES with restart after 20 steps and truncation after 5 residuals      :cvar GMRES: The Gram-Schmidt minimum residual method
77      @cvar LUMPING: Matrix lumping      :cvar PRES20: Special GMRES with restart after 20 steps and truncation after 5 residuals
78      @cvar NO_REORDERING: No matrix reordering allowed      :cvar LUMPING: Matrix lumping
79      @cvar MINIMUM_FILL_IN: Reorder matrix to reduce fill-in during factorization      :cvar NO_REORDERING: No matrix reordering allowed
80      @cvar NESTED_DISSECTION: Reorder matrix to improve load balancing during factorization      :cvar MINIMUM_FILL_IN: Reorder matrix to reduce fill-in during factorization
81      @cvar PASO: PASO solver package      :cvar NESTED_DISSECTION: Reorder matrix to improve load balancing during factorization
82      @cvar SCSL: SGI SCSL solver library      :cvar PASO: PASO solver package
83      @cvar MKL: Intel's MKL solver library      :cvar SCSL: SGI SCSL solver library
84      @cvar UMFPACK: The UMFPACK library      :cvar MKL: Intel's MKL solver library
85      @cvar TRILINOS: The TRILINOS parallel solver class library from Sandia National Labs      :cvar UMFPACK: The UMFPACK library
86      @cvar ITERATIVE: The default iterative solver      :cvar TRILINOS: The TRILINOS parallel solver class library from Sandia National Labs
87      @cvar AMG: Algebraic Multi Grid      :cvar ITERATIVE: The default iterative solver
88      @cvar REC_ILU: recursive ILU0      :cvar AMG: Algebraic Multi Grid
89      @cvar RILU: relaxed ILU0      :cvar AMLI: Algebraic Multi Level Iteration
90      @cvar GAUSS_SEIDEL: Gauss-Seidel solver      :cvar REC_ILU: recursive ILU0
91      @cvar DEFAULT_REORDERING: the reordering method recommended by the solver      :cvar RILU: relaxed ILU0
92      @cvar SUPER_LU: the Super_LU solver package      :cvar GAUSS_SEIDEL: Gauss-Seidel solver
93      @cvar PASTIX: the Pastix direct solver_package      :cvar DEFAULT_REORDERING: the reordering method recommended by the solver
94      @cvar YAIR_SHAPIRA_COARSENING: AMG coarsening method by Yair-Shapira      :cvar SUPER_LU: the Super_LU solver package
95      @cvar RUGE_STUEBEN_COARSENING: AMG coarsening method by Ruge and Stueben      :cvar PASTIX: the Pastix direct solver_package
96      @cvar AGGREGATION_COARSENING: AMG coarsening using (symmetric) aggregation      :cvar YAIR_SHAPIRA_COARSENING: AMG and AMLI coarsening method by Yair-Shapira
97      @cvar MIN_COARSE_MATRIX_SIZE: minimum size of the coarsest level matrix to use direct solver.      :cvar RUGE_STUEBEN_COARSENING: AMG and AMLI coarsening method by Ruge and Stueben
98      @cvar NO_PRECONDITIONER: no preconditioner is applied.      :cvar AGGREGATION_COARSENING: AMG and AMLI coarsening using (symmetric) aggregation
99        :cvar STANDARD_COARSENING: AMG and AMLI standard coarsening using mesure of importance of the unknowns
100        :cvar MIN_COARSE_MATRIX_SIZE: minimum size of the coarsest level matrix to use direct solver.
101        :cvar NO_PRECONDITIONER: no preconditioner is applied.
102      """      """
103      DEFAULT= 0      DEFAULT= 0
104      DIRECT= 1      DIRECT= 1
# Line 134  class SolverOptions(object): Line 137  class SolverOptions(object):
137      AGGREGATION_COARSENING=35      AGGREGATION_COARSENING=35
138      NO_PRECONDITIONER=36      NO_PRECONDITIONER=36
139      MIN_COARSE_MATRIX_SIZE=37      MIN_COARSE_MATRIX_SIZE=37
140            AMLI=38
141        STANDARD_COARSENING=39
142    
143      def __init__(self):      def __init__(self):
144          self.setLevelMax()          self.setLevelMax()
145          self.setCoarseningThreshold()          self.setCoarseningThreshold()
# Line 196  class SolverOptions(object): Line 201  class SolverOptions(object):
201                  out+="\nCoarsening threshold = %e"%self.getMinCoarseMatrixSize()                  out+="\nCoarsening threshold = %e"%self.getMinCoarseMatrixSize()
202                  out+="\nMinimum size of the coarsest level matrix = %e"%self.getCoarseningThreshold()                  out+="\nMinimum size of the coarsest level matrix = %e"%self.getCoarseningThreshold()
203                  out+="\nNumber of pre / post sweeps = %s / %s, %s"%(self.getNumPreSweeps(), self.getNumPostSweeps(), self.getNumSweeps())                  out+="\nNumber of pre / post sweeps = %s / %s, %s"%(self.getNumPreSweeps(), self.getNumPostSweeps(), self.getNumSweeps())
204              if self.getPreconditioner() == self.GAUSS_SEIDEL:              if self.getPreconditioner() == self.AMLI:
205                    out+="\nMaximum number of levels = %s"%self.LevelMax()
206                    out+="\nCoarsening method = %s"%self.getName(self.getCoarsening())
207                    out+="\nCoarsening threshold = %e"%self.getMinCoarseMatrixSize()
208                    out+="\nMinimum size of the coarsest level matrix = %e"%self.getCoarseningThreshold()
209                    out+="\nNumber of pre / post sweeps = %s / %s, %s"%(self.getNumPreSweeps(), self.getNumPostSweeps(), self.getNumSweeps())
210            if self.getPreconditioner() == self.GAUSS_SEIDEL:
211                  out+="\nNumber of sweeps = %s"%self.getNumSweeps()                  out+="\nNumber of sweeps = %s"%self.getNumSweeps()
212              if self.getPreconditioner() == self.ILUT:              if self.getPreconditioner() == self.ILUT:
213                  out+="\nDrop tolerance = %e"%self.getDropTolerance()                  out+="\nDrop tolerance = %e"%self.getDropTolerance()
# Line 209  class SolverOptions(object): Line 220  class SolverOptions(object):
220          """          """
221          returns the name of a given key          returns the name of a given key
222                    
223          @param key: a valid key          :param key: a valid key
224          """          """
225          if key == self.DEFAULT: return "DEFAULT"          if key == self.DEFAULT: return "DEFAULT"
226          if key == self.DIRECT: return "DIRECT"          if key == self.DIRECT: return "DIRECT"
# Line 233  class SolverOptions(object): Line 244  class SolverOptions(object):
244          if key == self.ITERATIVE: return "ITERATIVE"          if key == self.ITERATIVE: return "ITERATIVE"
245          if key == self.PASO: return "PASO"          if key == self.PASO: return "PASO"
246          if key == self.AMG: return "AMG"          if key == self.AMG: return "AMG"
247            if key == self.AMLI: return "AMLI"
248          if key == self.REC_ILU: return "REC_ILU"          if key == self.REC_ILU: return "REC_ILU"
249          if key == self.TRILINOS: return "TRILINOS"          if key == self.TRILINOS: return "TRILINOS"
250          if key == self.NONLINEAR_GMRES: return "NONLINEAR_GMRES"          if key == self.NONLINEAR_GMRES: return "NONLINEAR_GMRES"
# Line 245  class SolverOptions(object): Line 257  class SolverOptions(object):
257          if key == self.PASTIX: return "PASTIX"          if key == self.PASTIX: return "PASTIX"
258          if key == self.YAIR_SHAPIRA_COARSENING: return "YAIR_SHAPIRA_COARSENING"          if key == self.YAIR_SHAPIRA_COARSENING: return "YAIR_SHAPIRA_COARSENING"
259          if key == self.RUGE_STUEBEN_COARSENING: return "RUGE_STUEBEN_COARSENING"          if key == self.RUGE_STUEBEN_COARSENING: return "RUGE_STUEBEN_COARSENING"
260            if key == self.STANDARD_COARSENING: return "STANDARD_COARSENING"
261          if key == self.AGGREGATION_COARSENING: return "AGGREGATION_COARSENING"          if key == self.AGGREGATION_COARSENING: return "AGGREGATION_COARSENING"
262          if key == self.NO_PRECONDITIONER: return "NO_PRECONDITIONER"          if key == self.NO_PRECONDITIONER: return "NO_PRECONDITIONER"
263          if key == self.MIN_COARSE_MATRIX_SIZE: return "MIN_COARSE_MATRIX_SIZE"          if key == self.MIN_COARSE_MATRIX_SIZE: return "MIN_COARSE_MATRIX_SIZE"
# Line 253  class SolverOptions(object): Line 266  class SolverOptions(object):
266          """          """
267          resets the diagnostics          resets the diagnostics
268                    
269          @param all: if C{all} is C{True} all diagnostics including accumulative counters are reset.          :param all: if ``all`` is ``True`` all diagnostics including accumulative counters are reset.
270          @type all: C{bool}          :type all: ``bool``
271          """          """
272          self.__num_iter=None          self.__num_iter=None
273          self.__num_level=None          self.__num_level=None
274          self.__num_inner_iter=None          self.__num_inner_iter=None
275          self.__time=None          self.__time=None
276          self.__set_up_time=None          self.__set_up_time=None
277            self.__net_time=None
278          self.__residual_norm=None          self.__residual_norm=None
279          self.__converged=None          self.__converged=None
280          if all:          if all:
# Line 268  class SolverOptions(object): Line 282  class SolverOptions(object):
282              self.__cum_num_iter=0              self.__cum_num_iter=0
283              self.__cum_time=0              self.__cum_time=0
284              self.__cum_set_up_time=0              self.__cum_set_up_time=0
285                self.__cum_net_time=0
286    
287      def _updateDiagnostics(self, name, value):      def _updateDiagnostics(self, name, value):
288          """          """
289          Updates diagnostic information          Updates diagnostic information
290                    
291          @param name: name of  diagnostic information          :param name: name of  diagnostic information
292          @type name: C{str} in the list "num_iter", "num_level", "num_inner_iter", "time", "set_up_time", "residual_norm", "converged".          :type name: ``str`` in the list "num_iter", "num_level", "num_inner_iter", "time", "set_up_time", "net_time", "residual_norm", "converged".
293          @param vale: new value of the diagnostic information          :param value: new value of the diagnostic information
294          @note: this function is used by a solver to report diagnostics informations.          :note: this function is used by a solver to report diagnostics informations.
295          """          """
296          if name == "num_iter":          if name == "num_iter":
297              self.__num_iter=int(value)              self.__num_iter=int(value)
298              self.__cum_num_iter+=self.__num_iter              self.__cum_num_iter+=self.__num_iter
299          if name == "num_level":          if name == "num_level":
300              self.__num_iter=int(value)              self.__num_level=int(value)
301          if name == "num_inner_iter":          if name == "num_inner_iter":
302              self.__num_inner_iter=int(value)              self.__num_inner_iter=int(value)
303              self.__cum_num_inner_iter+=self.__num_inner_iter              self.__cum_num_inner_iter+=self.__num_inner_iter
# Line 292  class SolverOptions(object): Line 307  class SolverOptions(object):
307          if name == "set_up_time":          if name == "set_up_time":
308              self.__set_up_time=float(value)              self.__set_up_time=float(value)
309              self.__cum_set_up_time+=self.__set_up_time              self.__cum_set_up_time+=self.__set_up_time
310            if name == "net_time":
311                self.__net_time=float(value)
312                self.__cum_net_time+=self.__net_time
313          if name == "residual_norm":          if name == "residual_norm":
314              self.__residual_norm=float(value)              self.__residual_norm=float(value)
315          if name == "converged":          if name == "converged":
316              self.__converged = (value == True)              self.__converged = (value == True)
317      def getDiagnostics(self, name):      def getDiagnostics(self, name):
318          """          """
319          Returns the diagnostic information C{name}          Returns the diagnostic information ``name``. Possible values are:
320                    
321          @param name: name of diagnostic information where      - "num_iter": the number of iteration steps
         - "num_iter": the number of iteration steps  
322          - "cum_num_iter": the cumulative number of iteration steps          - "cum_num_iter": the cumulative number of iteration steps
323          - "num_level": the number of level in multi level solver          - "num_level": the number of level in multi level solver
324          - "num_inner_iter": the number of inner iteration steps          - "num_inner_iter": the number of inner iteration steps
# Line 310  class SolverOptions(object): Line 327  class SolverOptions(object):
327          - "cum_time": cumulative execution time          - "cum_time": cumulative execution time
328          - "set_up_time": time to set up of the solver, typically this includes factorization and reordering          - "set_up_time": time to set up of the solver, typically this includes factorization and reordering
329          - "cum_set_up_time": cumulative time to set up of the solver          - "cum_set_up_time": cumulative time to set up of the solver
330            - "net_time": net execution time, excluding setup time for the solver and execution time for preconditioner
331            - "cum_net_time": cumulative net execution time
332          - "residual_norm": norm of the final residual          - "residual_norm": norm of the final residual
333          - "converged": return self.__converged              - "converged": return self.__converged
334          @type name: C{str} in the list "num_iter", "num_level", "num_inner_iter", "time", "set_up_time", "residual_norm", "converged".      
335          @return: requested value. C{None} is returned if the value is undefined.      
336          @note: If the solver has thrown an exception diagnostic values have an undefined status.          
337            :param name: name of diagnostic information to return
338            :type name: ``str`` in the list above.
339            :return: requested value. ``None`` is returned if the value is undefined.
340            :note: If the solver has thrown an exception diagnostic values have an undefined status.
341          """          """
342          if name == "num_iter": return self.__num_iter          if name == "num_iter": return self.__num_iter
343          elif name == "cum_num_iter": return self.__cum_num_iter          elif name == "cum_num_iter": return self.__cum_num_iter
# Line 325  class SolverOptions(object): Line 348  class SolverOptions(object):
348          elif name == "cum_time": return self.__cum_time          elif name == "cum_time": return self.__cum_time
349          elif name == "set_up_time": return self.__set_up_time          elif name == "set_up_time": return self.__set_up_time
350          elif name == "cum_set_up_time": return self.__cum_set_up_time          elif name == "cum_set_up_time": return self.__cum_set_up_time
351            elif name == "net_time": return self.__net_time
352            elif name == "cum_net_time": return self.__cum_net_time
353          elif name == "residual_norm": return self.__residual_norm          elif name == "residual_norm": return self.__residual_norm
354          elif name == "converged": return self.__converged                elif name == "converged": return self.__converged      
355          else:          else:
356              raise ValueError,"unknown diagnostic item %s"%name              raise ValueError,"unknown diagnostic item %s"%name
357      def hasConverged(self):      def hasConverged(self):
358          """          """
359          Returns C{True} if the last solver call has been finalized successfully.          Returns ``True`` if the last solver call has been finalized successfully.
360          @note: if an exception has been thrown by the solver the status of this flag is undefined.          :note: if an exception has been thrown by the solver the status of this flag is undefined.
361          """          """
362          return self.getDiagnostics("converged")          return self.getDiagnostics("converged")
363      def setCoarsening(self,method=0):      def setCoarsening(self,method=0):
364          """          """
365          Sets the key of the coarsening method to be applied in AMG.          Sets the key of the coarsening method to be applied in AMG.
366    
367          @param method: selects the coarsening method .          :param method: selects the coarsening method .
368          @type method: in {SolverOptions.DEFAULT}, L{SolverOptions.YAIR_SHAPIRA_COARSENING},          :type method: in {SolverOptions.DEFAULT}, `SolverOptions.YAIR_SHAPIRA_COARSENING`,  `SolverOptions.RUGE_STUEBEN_COARSENING`, `SolverOptions.AGGREGATION_COARSENING`
         L{SolverOptions.RUGE_STUEBEN_COARSENING}, L{SolverOptions.AGGREGATION_COARSENING}  
369          """          """
370      if method==None: method=0      if method==None: method=0
371          if not method in [self.DEFAULT, self.YAIR_SHAPIRA_COARSENING, self.RUGE_STUEBEN_COARSENING, self.AGGREGATION_COARSENING]:          if not method in [self.DEFAULT, self.YAIR_SHAPIRA_COARSENING, self.RUGE_STUEBEN_COARSENING, self.AGGREGATION_COARSENING, self.STANDARD_COARSENING,]:
372               raise ValueError,"unknown coarsening method %s"%method               raise ValueError,"unknown coarsening method %s"%method
373          self.__coarsening=method          self.__coarsening=method
374            
# Line 352  class SolverOptions(object): Line 376  class SolverOptions(object):
376          """          """
377          Returns the key of the coarsening algorithm to be applied AMG.          Returns the key of the coarsening algorithm to be applied AMG.
378    
379          @rtype: in the list L{SolverOptions.DEFAULT}, L{SolverOptions.YAIR_SHAPIRA_COARSENING},          :rtype: in the list `SolverOptions.DEFAULT`, `SolverOptions.YAIR_SHAPIRA_COARSENING`,         `SolverOptions.RUGE_STUEBEN_COARSENING`, `SolverOptions.AGGREGATION_COARSENING`
         L{SolverOptions.RUGE_STUEBEN_COARSENING}, L{SolverOptions.AGGREGATION_COARSENING}  
380          """          """
381          return self.__coarsening          return self.__coarsening
382                
# Line 361  class SolverOptions(object): Line 384  class SolverOptions(object):
384          """          """
385          Sets the minumum size of the coarsest level matrix in AMG.          Sets the minumum size of the coarsest level matrix in AMG.
386    
387          @param size: minumum size of the coarsest level matrix .          :param size: minumum size of the coarsest level matrix .
388          @type size: positive C{int} or C{None}          :type size: positive ``int`` or ``None``
389          """          """
390          size=int(size)          size=int(size)
391          if size<0:          if size<0:
# Line 374  class SolverOptions(object): Line 397  class SolverOptions(object):
397          """          """
398          Returns the minumum size of the coarsest level matrix in AMG.          Returns the minumum size of the coarsest level matrix in AMG.
399    
400          @rtype: C{int}          :rtype: ``int``
401          """          """
402          return self.__MinCoarseMatrixSize          return self.__MinCoarseMatrixSize
403                
# Line 382  class SolverOptions(object): Line 405  class SolverOptions(object):
405          """          """
406          Sets the preconditioner to be used.          Sets the preconditioner to be used.
407    
408          @param preconditioner: key of the preconditioner to be used.          :param preconditioner: key of the preconditioner to be used.
409          @type preconditioner: in L{SolverOptions.SSOR}, L{SolverOptions.ILU0}, L{SolverOptions.ILUT}, L{SolverOptions.JACOBI},          :type preconditioner: in `SolverOptions.SSOR`, `SolverOptions.ILU0`, `SolverOptions.ILUT`, `SolverOptions.JACOBI`,
410                                      L{SolverOptions.AMG}, L{SolverOptions.REC_ILU}, L{SolverOptions.GAUSS_SEIDEL}, L{SolverOptions.RILU},                                      `SolverOptions.AMG`, `SolverOptions.AMLI`, `SolverOptions.REC_ILU`, `SolverOptions.GAUSS_SEIDEL`, `SolverOptions.RILU`,
411                                      L{SolverOptions.NO_PRECONDITIONER}                                      `SolverOptions.NO_PRECONDITIONER`
412          @note: Not all packages support all preconditioner. It can be assumed that a package makes a reasonable choice if it encounters          :note: Not all packages support all preconditioner. It can be assumed that a package makes a reasonable choice if it encounters an unknown preconditioner.
         an unknown preconditioner.  
413          """          """
414      if preconditioner==None: preconditioner=10      if preconditioner==None: preconditioner=10
415          if not preconditioner in [ SolverOptions.SSOR, SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI,          if not preconditioner in [ SolverOptions.SSOR, SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI,
416                                      SolverOptions.AMG, SolverOptions.REC_ILU, SolverOptions.GAUSS_SEIDEL, SolverOptions.RILU,                                      SolverOptions.AMG, SolverOptions.AMLI, SolverOptions.REC_ILU, SolverOptions.GAUSS_SEIDEL, SolverOptions.RILU,
417                                      SolverOptions.NO_PRECONDITIONER] :                                      SolverOptions.NO_PRECONDITIONER] :
418               raise ValueError,"unknown preconditioner %s"%preconditioner               raise ValueError,"unknown preconditioner %s"%preconditioner
419          self.__preconditioner=preconditioner              self.__preconditioner=preconditioner    
# Line 399  class SolverOptions(object): Line 421  class SolverOptions(object):
421          """          """
422          Returns key of the preconditioner to be used.          Returns key of the preconditioner to be used.
423    
424          @rtype: in the list L{SolverOptions.SSOR}, L{SolverOptions.ILU0}, L{SolverOptions.ILUT}, L{SolverOptions.JACOBI},          :rtype: in the list `SolverOptions.SSOR`, `SolverOptions.ILU0`, `SolverOptions.ILUT`, `SolverOptions.JACOBI`,
425                                      L{SolverOptions.AMG}, L{SolverOptions.REC_ILU}, L{SolverOptions.GAUSS_SEIDEL}, L{SolverOptions.RILU},                                      `SolverOptions.AMG`, `SolverOptions.REC_ILU`, `SolverOptions.GAUSS_SEIDEL`, `SolverOptions.RILU`,
426                                      L{SolverOptions.NO_PRECONDITIONER}                                      `SolverOptions.NO_PRECONDITIONER`
427          """          """
428          return self.__preconditioner          return self.__preconditioner
429      def setSolverMethod(self, method=0):      def setSolverMethod(self, method=0):
430          """          """
431          Sets the solver method to be used. Use C{method}=C{SolverOptions.DIRECT} to indicate that a direct rather than an iterative          Sets the solver method to be used. Use ``method``=``SolverOptions.DIRECT`` to indicate that a direct rather than an iterative
432          solver should be used and Use C{method}=C{SolverOptions.ITERATIVE} to indicate that an iterative rather than a direct          solver should be used and Use ``method``=``SolverOptions.ITERATIVE`` to indicate that an iterative rather than a direct
433          solver should be used.          solver should be used.
434    
435          @param method: key of the solver method to be used.          :param method: key of the solver method to be used.
436          @type method: in L{SolverOptions.DEFAULT}, L{SolverOptions.DIRECT}, L{SolverOptions.CHOLEVSKY}, L{SolverOptions.PCG},          :type method: in `SolverOptions.DEFAULT`, `SolverOptions.DIRECT`, `SolverOptions.CHOLEVSKY`, `SolverOptions.PCG`,
437                          L{SolverOptions.CR}, L{SolverOptions.CGS}, L{SolverOptions.BICGSTAB}, L{SolverOptions.SSOR},                          `SolverOptions.CR`, `SolverOptions.CGS`, `SolverOptions.BICGSTAB`, `SolverOptions.SSOR`,
438                          L{SolverOptions.GMRES}, L{SolverOptions.PRES20}, L{SolverOptions.LUMPING}, L{SolverOptions.ITERATIVE},                          `SolverOptions.GMRES`, `SolverOptions.PRES20`, `SolverOptions.LUMPING`, `SolverOptions.ITERATIVE`,
439                          L{SolverOptions.AMG}, L{SolverOptions.NONLINEAR_GMRES}, L{SolverOptions.TFQMR}, L{SolverOptions.MINRES},                          `SolverOptions.AMG`, `SolverOptions.NONLINEAR_GMRES`, `SolverOptions.TFQMR`, `SolverOptions.MINRES`,
440                          L{SolverOptions.GAUSS_SEIDEL}                          `SolverOptions.GAUSS_SEIDEL`
441          @note: Not all packages support all solvers. It can be assumed that a package makes a reasonable choice if it encounters          :note: Not all packages support all solvers. It can be assumed that a package makes a reasonable choice if it encounters an unknown solver method.
         an unknown solver method.  
442          """          """
443      if method==None: method=0      if method==None: method=0
444          if not method in [ SolverOptions.DEFAULT, SolverOptions.DIRECT, SolverOptions.CHOLEVSKY, SolverOptions.PCG,          if not method in [ SolverOptions.DEFAULT, SolverOptions.DIRECT, SolverOptions.CHOLEVSKY, SolverOptions.PCG,
# Line 430  class SolverOptions(object): Line 451  class SolverOptions(object):
451          """          """
452          Returns key of the solver method to be used.          Returns key of the solver method to be used.
453    
454          @rtype: in the list L{SolverOptions.DEFAULT}, L{SolverOptions.DIRECT}, L{SolverOptions.CHOLEVSKY}, L{SolverOptions.PCG},          :rtype: in the list `SolverOptions.DEFAULT`, `SolverOptions.DIRECT`, `SolverOptions.CHOLEVSKY`, `SolverOptions.PCG`,
455                          L{SolverOptions.CR}, L{SolverOptions.CGS}, L{SolverOptions.BICGSTAB}, L{SolverOptions.SSOR},                          `SolverOptions.CR`, `SolverOptions.CGS`, `SolverOptions.BICGSTAB`, `SolverOptions.SSOR`,
456                          L{SolverOptions.GMRES}, L{SolverOptions.PRES20}, L{SolverOptions.LUMPING}, L{SolverOptions.ITERATIVE},                          `SolverOptions.GMRES`, `SolverOptions.PRES20`, `SolverOptions.LUMPING`, `SolverOptions.ITERATIVE`,
457                          L{SolverOptions.AMG}, L{SolverOptions.NONLINEAR_GMRES}, L{SolverOptions.TFQMR}, L{SolverOptions.MINRES},                          `SolverOptions.AMG`, `SolverOptions.NONLINEAR_GMRES`, `SolverOptions.TFQMR`, `SolverOptions.MINRES`,
458                          L{SolverOptions.GAUSS_SEIDEL}                          `SolverOptions.GAUSS_SEIDEL`
459          """          """
460          return self.__method          return self.__method
461                    
# Line 442  class SolverOptions(object): Line 463  class SolverOptions(object):
463          """          """
464          Sets the solver package to be used as a solver.            Sets the solver package to be used as a solver.  
465    
466          @param package: key of the solver package to be used.          :param package: key of the solver package to be used.
467          @type package: in L{SolverOptions.DEFAULT}, L{SolverOptions.PASO}, L{SolverOptions.SUPER_LU}, L{SolverOptions.PASTIX}, L{SolverOptions.MKL}, L{SolverOptions.UMFPACK}, L{SolverOptions.TRILINOS}          :type package: in `SolverOptions.DEFAULT`, `SolverOptions.PASO`, `SolverOptions.SUPER_LU`, `SolverOptions.PASTIX`, `SolverOptions.MKL`, `SolverOptions.UMFPACK`, `SolverOptions.TRILINOS`
468          @note: Not all packages are support on all implementation. An exception may be thrown on some platforms if a particular is requested.          :note: Not all packages are support on all implementation. An exception may be thrown on some platforms if a particular is requested.
469          """          """
470      if package==None: package=0      if package==None: package=0
471          if not package in [SolverOptions.DEFAULT, SolverOptions.PASO, SolverOptions.SUPER_LU, SolverOptions.PASTIX, SolverOptions.MKL, SolverOptions.UMFPACK, SolverOptions.TRILINOS]:          if not package in [SolverOptions.DEFAULT, SolverOptions.PASO, SolverOptions.SUPER_LU, SolverOptions.PASTIX, SolverOptions.MKL, SolverOptions.UMFPACK, SolverOptions.TRILINOS]:
# Line 454  class SolverOptions(object): Line 475  class SolverOptions(object):
475          """          """
476          Returns the solver package key          Returns the solver package key
477    
478          @rtype: in the list L{SolverOptions.DEFAULT}, L{SolverOptions.PASO}, L{SolverOptions.SUPER_LU}, L{SolverOptions.PASTIX}, L{SolverOptions.MKL}, L{SolverOptions.UMFPACK}, L{SolverOptions.TRILINOS}          :rtype: in the list `SolverOptions.DEFAULT`, `SolverOptions.PASO`, `SolverOptions.SUPER_LU`, `SolverOptions.PASTIX`, `SolverOptions.MKL`, `SolverOptions.UMFPACK`, `SolverOptions.TRILINOS`
479          """          """
480          return self.__package          return self.__package
481      def setReordering(self,ordering=30):      def setReordering(self,ordering=30):
# Line 462  class SolverOptions(object): Line 483  class SolverOptions(object):
483          Sets the key of the reordering method to be applied if supported by the solver. Some direct solvers support reordering          Sets the key of the reordering method to be applied if supported by the solver. Some direct solvers support reordering
484          to optimize compute time and storage use during elimination.          to optimize compute time and storage use during elimination.
485    
486          @param ordering: selects the reordering strategy.          :param ordering: selects the reordering strategy.
487          @type ordering: in L{SolverOptions.NO_REORDERING}, L{SolverOptions.NO_REORDERING},          :type ordering: in `SolverOptions.NO_REORDERING`, `SolverOptions.NO_REORDERING`, `SolverOptions.NO_REORDERING`, `SolverOptions.DEFAULT_REORDERING`
         L{SolverOptions.NO_REORDERING}, L{SolverOptions.DEFAULT_REORDERING}  
488          """          """
489          if not ordering in [self.NO_REORDERING, self.MINIMUM_FILL_IN, self.NESTED_DISSECTION, self.DEFAULT_REORDERING]:          if not ordering in [self.NO_REORDERING, self.MINIMUM_FILL_IN, self.NESTED_DISSECTION, self.DEFAULT_REORDERING]:
490               raise ValueError,"unknown reordering strategy %s"%ordering               raise ValueError,"unknown reordering strategy %s"%ordering
# Line 473  class SolverOptions(object): Line 493  class SolverOptions(object):
493          """          """
494          Returns the key of the reordering method to be applied if supported by the solver.          Returns the key of the reordering method to be applied if supported by the solver.
495    
496          @rtype: in the list L{SolverOptions.NO_REORDERING}, L{SolverOptions.NO_REORDERING},          :rtype: in the list `SolverOptions.NO_REORDERING`, `SolverOptions.NO_REORDERING`,  `SolverOptions.NO_REORDERING`, `SolverOptions.DEFAULT_REORDERING`
         L{SolverOptions.NO_REORDERING}, L{SolverOptions.DEFAULT_REORDERING}  
497          """          """
498          return self.__reordering          return self.__reordering
499      def setRestart(self,restart=None):      def setRestart(self,restart=None):
500          """          """
501          Sets the number of iterations steps after which GMRES is performing a restart.          Sets the number of iterations steps after which GMRES is performing a restart.
502    
503          @param restart: number of iteration steps after which to perform a restart. If equal to C{None} no          :param restart: number of iteration steps after which to perform a restart. If equal to ``None`` no restart is performed.
504                          restart is performed.          :type restart: ``int`` or ``None``
         @type restart: C{int} or C{None}  
505          """          """
506          if restart == None:          if restart == None:
507              self.__restart=restart              self.__restart=restart
# Line 496  class SolverOptions(object): Line 514  class SolverOptions(object):
514      def getRestart(self):      def getRestart(self):
515          """          """
516          Returns the number of iterations steps after which GMRES is performing a restart.          Returns the number of iterations steps after which GMRES is performing a restart.
517          If C{None} is returned no restart is performed.          If ``None`` is returned no restart is performed.
518    
519          @rtype: C{int} or C{None}          :rtype: ``int`` or ``None``
520          """          """
521          if self.__restart < 0:          if self.__restart < 0:
522              return None              return None
# Line 515  class SolverOptions(object): Line 533  class SolverOptions(object):
533          Sets the number of residuals in GMRES to be stored for orthogonalization.  The more residuals are stored          Sets the number of residuals in GMRES to be stored for orthogonalization.  The more residuals are stored
534          the faster GMRES converged but          the faster GMRES converged but
535    
536          @param truncation: truncation          :param truncation: truncation
537          @type truncation: C{int}          :type truncation: ``int``
538          """          """
539          truncation=int(truncation)          truncation=int(truncation)
540          if truncation<1:          if truncation<1:
# Line 526  class SolverOptions(object): Line 544  class SolverOptions(object):
544          """          """
545          Returns the number of residuals in GMRES to be stored for orthogonalization          Returns the number of residuals in GMRES to be stored for orthogonalization
546    
547          @rtype: C{int}          :rtype: ``int``
548          """          """
549          return self.__truncation          return self.__truncation
550      def setInnerIterMax(self,iter_max=10):      def setInnerIterMax(self,iter_max=10):
551          """          """
552          Sets the maximum number of iteration steps for the inner iteration.          Sets the maximum number of iteration steps for the inner iteration.
553    
554          @param iter_max: maximum number of inner iterations          :param iter_max: maximum number of inner iterations
555          @type iter_max: C{int}          :type iter_max: ``int``
556          """          """
557          iter_max=int(iter_max)          iter_max=int(iter_max)
558          if iter_max<1:          if iter_max<1:
# Line 544  class SolverOptions(object): Line 562  class SolverOptions(object):
562          """          """
563          Returns maximum number of inner iteration steps          Returns maximum number of inner iteration steps
564    
565          @rtype: C{int}          :rtype: ``int``
566          """          """
567          return self.__inner_iter_max          return self.__inner_iter_max
568      def setIterMax(self,iter_max=100000):      def setIterMax(self,iter_max=100000):
569          """          """
570          Sets the maximum number of iteration steps          Sets the maximum number of iteration steps
571    
572          @param iter_max: maximum number of iteration steps          :param iter_max: maximum number of iteration steps
573          @type iter_max: C{int}          :type iter_max: ``int``
574          """          """
575          iter_max=int(iter_max)          iter_max=int(iter_max)
576          if iter_max<1:          if iter_max<1:
# Line 562  class SolverOptions(object): Line 580  class SolverOptions(object):
580          """          """
581          Returns maximum number of iteration steps          Returns maximum number of iteration steps
582    
583          @rtype: C{int}          :rtype: ``int``
584          """          """
585          return self.__iter_max          return self.__iter_max
586      def setLevelMax(self,level_max=10):      def setLevelMax(self,level_max=3):
587          """          """
588          Sets the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner          Sets the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner
589    
590          @param level_max: maximum number of levels          :param level_max: maximum number of levels
591          @type level_max: C{int}          :type level_max: ``int``
592          """          """
593          level_max=int(level_max)          level_max=int(level_max)
594          if level_max<0:          if level_max<0:
# Line 580  class SolverOptions(object): Line 598  class SolverOptions(object):
598          """          """
599          Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner          Returns the maximum number of coarsening levels to be used in an algebraic multi level solver or preconditioner
600    
601          @rtype: C{int}          :rtype: ``int``
602          """          """
603          return self.__level_max          return self.__level_max
604      def setCoarseningThreshold(self,theta=0.05):      def setCoarseningThreshold(self,theta=0.25):
605          """          """
606          Sets the threshold for coarsening in the algebraic multi level solver or preconditioner          Sets the threshold for coarsening in the algebraic multi level solver or preconditioner
607    
608          @param theta: threshold for coarsening          :param theta: threshold for coarsening
609          @type theta: positive C{float}          :type theta: positive ``float``
610          """          """
611          theta=float(theta)          theta=float(theta)
612          if theta<0 or theta>1:          if theta<0 or theta>1:
# Line 598  class SolverOptions(object): Line 616  class SolverOptions(object):
616          """          """
617          Returns the threshold for coarsening in the algebraic multi level solver or preconditioner          Returns the threshold for coarsening in the algebraic multi level solver or preconditioner
618    
619          @rtype: C{float}          :rtype: ``float``
620          """          """
621          return self.__coarsening_threshold          return self.__coarsening_threshold
622      def setNumSweeps(self,sweeps=2):      def setNumSweeps(self,sweeps=2):
623          """          """
624          Sets the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.          Sets the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.
625    
626          @param sweeps: number of sweeps          :param sweeps: number of sweeps
627          @type theta: positive C{int}          :type sweeps: positive ``int``
628          """          """
629          sweeps=int(sweeps)          sweeps=int(sweeps)
630          if sweeps<1:          if sweeps<1:
# Line 616  class SolverOptions(object): Line 634  class SolverOptions(object):
634          """          """
635          Returns the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.          Returns the number of sweeps in a Jacobi or Gauss-Seidel/SOR preconditioner.
636    
637          @rtype: C{int}          :rtype: ``int``
638          """          """
639          return self.__sweeps          return self.__sweeps
640      def setNumPreSweeps(self,sweeps=2):      def setNumPreSweeps(self,sweeps=2):
641          """          """
642          Sets the number of sweeps in the pre-smoothing step of a multi level solver or preconditioner          Sets the number of sweeps in the pre-smoothing step of a multi level solver or preconditioner
643    
644          @param sweeps: number of sweeps          :param sweeps: number of sweeps
645          @type theta: positive C{int}          :type sweeps: positive ``int``
646          """          """
647          sweeps=int(sweeps)          sweeps=int(sweeps)
648          if sweeps<1:          if sweeps<1:
# Line 634  class SolverOptions(object): Line 652  class SolverOptions(object):
652          """          """
653          Returns he number of sweeps in the pre-smoothing step of a multi level solver or preconditioner          Returns he number of sweeps in the pre-smoothing step of a multi level solver or preconditioner
654    
655          @rtype: C{int}          :rtype: ``int``
656          """          """
657          return self.__pre_sweeps          return self.__pre_sweeps
658      def setNumPostSweeps(self,sweeps=2):      def setNumPostSweeps(self,sweeps=2):
659          """          """
660          Sets the number of sweeps in the post-smoothing step of a multi level solver or preconditioner          Sets the number of sweeps in the post-smoothing step of a multi level solver or preconditioner
661    
662          @param sweeps: number of sweeps          :param sweeps: number of sweeps
663          @type theta: positive C{int}          :type sweeps: positive ``int``
664          """          """
665          sweeps=int(sweeps)          sweeps=int(sweeps)
666          if sweeps<1:          if sweeps<1:
# Line 652  class SolverOptions(object): Line 670  class SolverOptions(object):
670          """          """
671          Returns he number of sweeps in the post-smoothing step of a multi level solver or preconditioner          Returns he number of sweeps in the post-smoothing step of a multi level solver or preconditioner
672    
673          @rtype: C{int}          :rtype: ``int``
674          """          """
675          return self.__post_sweeps          return self.__post_sweeps
676    
# Line 660  class SolverOptions(object): Line 678  class SolverOptions(object):
678          """          """
679          Sets the relative tolerance for the solver          Sets the relative tolerance for the solver
680    
681          @param rtol: relative tolerance          :param rtol: relative tolerance
682          @type rtol: non-negative C{float}          :type rtol: non-negative ``float``
683          """          """
684          rtol=float(rtol)          rtol=float(rtol)
685          if rtol<0 or rtol>1:          if rtol<0 or rtol>1:
# Line 671  class SolverOptions(object): Line 689  class SolverOptions(object):
689          """          """
690          Returns the relative tolerance for the solver          Returns the relative tolerance for the solver
691    
692          @rtype: C{float}          :rtype: ``float``
693          """          """
694          return self.__tolerance          return self.__tolerance
695      def setAbsoluteTolerance(self,atol=0.):      def setAbsoluteTolerance(self,atol=0.):
696          """          """
697          Sets the absolute tolerance for the solver          Sets the absolute tolerance for the solver
698    
699          @param atol:  absolute tolerance          :param atol:  absolute tolerance
700          @type atol: non-negative C{float}          :type atol: non-negative ``float``
701          """          """
702          atol=float(atol)          atol=float(atol)
703          if atol<0:          if atol<0:
# Line 689  class SolverOptions(object): Line 707  class SolverOptions(object):
707          """          """
708          Returns the absolute tolerance for the solver          Returns the absolute tolerance for the solver
709    
710          @rtype: C{float}          :rtype: ``float``
711          """          """
712          return self.__absolute_tolerance          return self.__absolute_tolerance
713    
714      def setInnerTolerance(self,rtol=0.9):      def setInnerTolerance(self,rtol=0.9):
715          """          """
716           Sets the relative tolerance for an inner iteration scheme for instance           Sets the relative tolerance for an inner iteration scheme for instance on the coarsest level in a multi-level scheme.
         on the coarsest level in a multi-level scheme.  
717    
718          @param rtol: inner relative tolerance          :param rtol: inner relative tolerance
719          @type rtol: positive C{float}          :type rtol: positive ``float``
720          """          """
721          rtol=float(rtol)          rtol=float(rtol)
722          if rtol<=0 or rtol>1:          if rtol<=0 or rtol>1:
# Line 709  class SolverOptions(object): Line 726  class SolverOptions(object):
726          """          """
727          Returns the relative tolerance for an inner iteration scheme          Returns the relative tolerance for an inner iteration scheme
728    
729          @rtype: C{float}          :rtype: ``float``
730          """          """
731          return self.__inner_tolerance          return self.__inner_tolerance
732      def setDropTolerance(self,drop_tol=0.01):      def setDropTolerance(self,drop_tol=0.01):
733          """          """
734          Sets the relative drop tolerance in ILUT          Sets the relative drop tolerance in ILUT
735    
736          @param drop_tol: drop tolerance          :param drop_tol: drop tolerance
737          @type drop_tol: positive C{float}          :type drop_tol: positive ``float``
738          """          """
739          drop_tol=float(drop_tol)          drop_tol=float(drop_tol)
740          if drop_tol<=0 or drop_tol>1:          if drop_tol<=0 or drop_tol>1:
# Line 727  class SolverOptions(object): Line 744  class SolverOptions(object):
744          """          """
745          Returns the relative drop tolerance in ILUT          Returns the relative drop tolerance in ILUT
746    
747          @rtype: C{float}          :rtype: ``float``
748          """          """
749          return self.__drop_tolerance          return self.__drop_tolerance
750      def setDropStorage(self,storage=2.):      def setDropStorage(self,storage=2.):
751          """          """
752          Sets the maximum allowed increase in storage for ILUT. C{storage}=2 would mean that          Sets the maximum allowed increase in storage for ILUT. ``storage`` =2 would mean that
753          a doubling of the storage needed for the coefficient matrix is allowed in the ILUT factorization.          a doubling of the storage needed for the coefficient matrix is allowed in the ILUT factorization.
754    
755          @param storage: allowed storage increase          :param storage: allowed storage increase
756          @type storage: C{float}          :type storage: ``float``
757          """          """
758          storage=float(storage)          storage=float(storage)
759          if storage<1:          if storage<1:
# Line 747  class SolverOptions(object): Line 764  class SolverOptions(object):
764          """          """
765          Returns the maximum allowed increase in storage for ILUT          Returns the maximum allowed increase in storage for ILUT
766    
767          @rtype: C{float}          :rtype: ``float``
768          """          """
769          return self.__drop_storage          return self.__drop_storage
770      def setRelaxationFactor(self,factor=0.3):      def setRelaxationFactor(self,factor=0.3):
771          """          """
772          Sets the relaxation factor used to add dropped elements in RILU to the main diagonal.          Sets the relaxation factor used to add dropped elements in RILU to the main diagonal.
773    
774          @param factor: relaxation factor          :param factor: relaxation factor
775          @type factor: C{float}          :type factor: ``float``
776          @note: RILU with a relaxation factor 0 is identical to ILU0          :note: RILU with a relaxation factor 0 is identical to ILU0
777          """          """
778          factor=float(factor)          factor=float(factor)
779          if factor<0:          if factor<0:
# Line 767  class SolverOptions(object): Line 784  class SolverOptions(object):
784          """          """
785          Returns the relaxation factor used to add dropped elements in RILU to the main diagonal.          Returns the relaxation factor used to add dropped elements in RILU to the main diagonal.
786    
787          @rtype: C{float}          :rtype: ``float``
788          """          """
789          return self.__relaxation          return self.__relaxation
790      def isSymmetric(self):      def isSymmetric(self):
791          """          """
792          Checks if symmetry of the  coefficient matrix is indicated.          Checks if symmetry of the  coefficient matrix is indicated.
793    
794          @return: True if a symmetric PDE is indicated, False otherwise          :return: True if a symmetric PDE is indicated, False otherwise
795          @rtype: C{bool}          :rtype: ``bool``
796          """          """
797          return self.__symmetric          return self.__symmetric
798      def setSymmetryOn(self):      def setSymmetryOn(self):
# Line 790  class SolverOptions(object): Line 807  class SolverOptions(object):
807          self.__symmetric=False          self.__symmetric=False
808      def setSymmetry(self,flag=False):      def setSymmetry(self,flag=False):
809          """          """
810          Sets the symmetry flag for the coefficient matrix to C{flag}.          Sets the symmetry flag for the coefficient matrix to ``flag``.
811    
812          @param flag: If True, the symmetry flag is set otherwise reset.          :param flag: If True, the symmetry flag is set otherwise reset.
813          @type flag: C{bool}          :type flag: ``bool``
814          """          """
815          if flag:          if flag:
816              self.setSymmetryOn()              self.setSymmetryOn()
# Line 801  class SolverOptions(object): Line 818  class SolverOptions(object):
818              self.setSymmetryOff()              self.setSymmetryOff()
819      def isVerbose(self):      def isVerbose(self):
820          """          """
821          Returns C{True} if the solver is expected to be verbose.          Returns ``True`` if the solver is expected to be verbose.
822    
823          @return: True if verbosity of switched on.          :return: True if verbosity of switched on.
824          @rtype: C{bool}          :rtype: ``bool``
825          """          """
826          return self.__verbose          return self.__verbose
827    
# Line 820  class SolverOptions(object): Line 837  class SolverOptions(object):
837          self.__verbose=False          self.__verbose=False
838      def setVerbosity(self,verbose=False):      def setVerbosity(self,verbose=False):
839          """          """
840          Sets the verbosity flag for the solver to C{flag}.          Sets the verbosity flag for the solver to ``flag``.
841    
842          @param flag: If C{True}, the verbosity of the solver is switched on.          :param verbose: If ``True``, the verbosity of the solver is switched on.
843          @type flag: C{bool}          :type verbose: ``bool``
844          """          """
845          if verbose:          if verbose:
846              self.setVerbosityOn()              self.setVerbosityOn()
# Line 832  class SolverOptions(object): Line 849  class SolverOptions(object):
849                    
850      def adaptInnerTolerance(self):      def adaptInnerTolerance(self):
851          """          """
852          Returns C{True} if the tolerance of the inner solver is selected automatically.          Returns ``True`` if the tolerance of the inner solver is selected automatically.
853          Otherwise the inner tolerance set by L{setInnerTolerance} is used.          Otherwise the inner tolerance set by `setInnerTolerance` is used.
854    
855          @return: C{True} if inner tolerance adaption is chosen.          :return: ``True`` if inner tolerance adaption is chosen.
856          @rtype: C{bool}          :rtype: ``bool``
857          """          """
858          return self.__adapt_inner_tolerance          return self.__adapt_inner_tolerance
859    
# Line 854  class SolverOptions(object): Line 871  class SolverOptions(object):
871          """          """
872          Sets a flag to indicate automatic selection of the inner tolerance.          Sets a flag to indicate automatic selection of the inner tolerance.
873    
874          @param adapt: If C{True}, the inner tolerance is selected automatically.          :param adapt: If ``True``, the inner tolerance is selected automatically.
875          @type adapt: C{bool}          :type adapt: ``bool``
876          """          """
877          if adapt:          if adapt:
878              self.setInnerToleranceAdaptionOn()              self.setInnerToleranceAdaptionOn()
# Line 864  class SolverOptions(object): Line 881  class SolverOptions(object):
881    
882      def acceptConvergenceFailure(self):      def acceptConvergenceFailure(self):
883          """          """
884          Returns C{True} if a failure to meet the stopping criteria within the          Returns ``True`` if a failure to meet the stopping criteria within the
885          given number of iteration steps is not raising in exception. This is useful          given number of iteration steps is not raising in exception. This is useful
886          if a solver is used in a non-linear context where the non-linear solver can          if a solver is used in a non-linear context where the non-linear solver can
887          continue even if the returned the solution does not necessarily meet the          continue even if the returned the solution does not necessarily meet the
888          stopping criteria. One can use the L{hasConverged} method to check if the          stopping criteria. One can use the `hasConverged` method to check if the
889          last call to the solver was successful.          last call to the solver was successful.
890    
891          @return: C{True} if a failure to achieve convergence is accepted.          :return: ``True`` if a failure to achieve convergence is accepted.
892          @rtype: C{bool}          :rtype: ``bool``
893          """          """
894          return self.__accept_convergence_failure          return self.__accept_convergence_failure
895    
# Line 890  class SolverOptions(object): Line 907  class SolverOptions(object):
907          """          """
908          Sets a flag to indicate the acceptance of a failure of convergence.          Sets a flag to indicate the acceptance of a failure of convergence.
909    
910          @param accept: If C{True}, any failure to achieve convergence is accepted.          :param accept: If ``True``, any failure to achieve convergence is accepted.
911          @type accept: C{bool}          :type accept: ``bool``
912          """          """
913          if accept:          if accept:
914              self.setAcceptanceConvergenceFailureOn()              self.setAcceptanceConvergenceFailureOn()
# Line 927  class PDECoef(object): Line 944  class PDECoef(object):
944      """      """
945      A class for describing a PDE coefficient.      A class for describing a PDE coefficient.
946    
947      @cvar INTERIOR: indicator that coefficient is defined on the interior of      :cvar INTERIOR: indicator that coefficient is defined on the interior of
948                      the PDE domain                      the PDE domain
949      @cvar BOUNDARY: indicator that coefficient is defined on the boundary of      :cvar BOUNDARY: indicator that coefficient is defined on the boundary of
950                      the PDE domain                      the PDE domain
951      @cvar CONTACT: indicator that coefficient is defined on the contact region      :cvar CONTACT: indicator that coefficient is defined on the contact region
952                     within the PDE domain                     within the PDE domain
953      @cvar INTERIOR_REDUCED: indicator that coefficient is defined on the      :cvar INTERIOR_REDUCED: indicator that coefficient is defined on the
954                              interior of the PDE domain using a reduced                              interior of the PDE domain using a reduced
955                              integration order                              integration order
956      @cvar BOUNDARY_REDUCED: indicator that coefficient is defined on the      :cvar BOUNDARY_REDUCED: indicator that coefficient is defined on the
957                              boundary of the PDE domain using a reduced                              boundary of the PDE domain using a reduced
958                              integration order                              integration order
959      @cvar CONTACT_REDUCED: indicator that coefficient is defined on the contact      :cvar CONTACT_REDUCED: indicator that coefficient is defined on the contact
960                             region within the PDE domain using a reduced                             region within the PDE domain using a reduced
961                             integration order                             integration order
962      @cvar SOLUTION: indicator that coefficient is defined through a solution of      :cvar SOLUTION: indicator that coefficient is defined through a solution of
963                      the PDE                      the PDE
964      @cvar REDUCED: indicator that coefficient is defined through a reduced      :cvar REDUCED: indicator that coefficient is defined through a reduced
965                     solution of the PDE                     solution of the PDE
966      @cvar BY_EQUATION: indicator that the dimension of the coefficient shape is      :cvar BY_EQUATION: indicator that the dimension of the coefficient shape is
967                         defined by the number of PDE equations                         defined by the number of PDE equations
968      @cvar BY_SOLUTION: indicator that the dimension of the coefficient shape is      :cvar BY_SOLUTION: indicator that the dimension of the coefficient shape is
969                         defined by the number of PDE solutions                         defined by the number of PDE solutions
970      @cvar BY_DIM: indicator that the dimension of the coefficient shape is      :cvar BY_DIM: indicator that the dimension of the coefficient shape is
971                    defined by the spatial dimension                    defined by the spatial dimension
972      @cvar OPERATOR: indicator that the the coefficient alters the operator of      :cvar OPERATOR: indicator that the the coefficient alters the operator of
973                      the PDE                      the PDE
974      @cvar RIGHTHANDSIDE: indicator that the the coefficient alters the right      :cvar RIGHTHANDSIDE: indicator that the the coefficient alters the right
975                           hand side of the PDE                           hand side of the PDE
976      @cvar BOTH: indicator that the the coefficient alters the operator as well      :cvar BOTH: indicator that the the coefficient alters the operator as well
977                  as the right hand side of the PDE                  as the right hand side of the PDE
978    
979      """      """
# Line 979  class PDECoef(object): Line 996  class PDECoef(object):
996         """         """
997         Initialises a PDE coefficient type.         Initialises a PDE coefficient type.
998    
999         @param where: describes where the coefficient lives         :param where: describes where the coefficient lives
1000         @type where: one of L{INTERIOR}, L{BOUNDARY}, L{CONTACT}, L{SOLUTION},         :type where: one of `INTERIOR`, `BOUNDARY`, `CONTACT`, `SOLUTION`,
1001                      L{REDUCED}, L{INTERIOR_REDUCED}, L{BOUNDARY_REDUCED},                      `REDUCED`, `INTERIOR_REDUCED`, `BOUNDARY_REDUCED`,
1002                      L{CONTACT_REDUCED}                      `CONTACT_REDUCED`
1003         @param pattern: describes the shape of the coefficient and how the shape         :param pattern: describes the shape of the coefficient and how the shape
1004                         is built for a given spatial dimension and numbers of                         is built for a given spatial dimension and numbers of
1005                         equations and solutions in then PDE. For instance,                         equations and solutions in then PDE. For instance,
1006                         (L{BY_EQUATION},L{BY_SOLUTION},L{BY_DIM}) describes a                         (`BY_EQUATION`,`BY_SOLUTION`,`BY_DIM`) describes a
1007                         rank 3 coefficient which is instantiated as shape (3,2,2)                         rank 3 coefficient which is instantiated as shape (3,2,2)
1008                         in case of three equations and two solution components                         in case of three equations and two solution components
1009                         on a 2-dimensional domain. In the case of single equation                         on a 2-dimensional domain. In the case of single equation
1010                         and a single solution component the shape components                         and a single solution component the shape components
1011                         marked by L{BY_EQUATION} or L{BY_SOLUTION} are dropped.                         marked by `BY_EQUATION` or `BY_SOLUTION` are dropped.
1012                         In this case the example would be read as (2,).                         In this case the example would be read as (2,).
1013         @type pattern: C{tuple} of L{BY_EQUATION}, L{BY_SOLUTION}, L{BY_DIM}         :type pattern: ``tuple`` of `BY_EQUATION`, `BY_SOLUTION`, `BY_DIM`
1014         @param altering: indicates what part of the PDE is altered if the         :param altering: indicates what part of the PDE is altered if the
1015                          coefficient is altered                          coefficient is altered
1016         @type altering: one of L{OPERATOR}, L{RIGHTHANDSIDE}, L{BOTH}         :type altering: one of `OPERATOR`, `RIGHTHANDSIDE`, `BOTH`
1017         """         """
1018         super(PDECoef, self).__init__()         super(PDECoef, self).__init__()
1019         self.what=where         self.what=where
# Line 1012  class PDECoef(object): Line 1029  class PDECoef(object):
1029    
1030      def getFunctionSpace(self,domain,reducedEquationOrder=False,reducedSolutionOrder=False):      def getFunctionSpace(self,domain,reducedEquationOrder=False,reducedSolutionOrder=False):
1031         """         """
1032         Returns the L{FunctionSpace<escript.FunctionSpace>} of the coefficient.         Returns the `FunctionSpace` of the coefficient.
1033    
1034         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1035         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1036         @param reducedEquationOrder: True to indicate that reduced order is used         :param reducedEquationOrder: True to indicate that reduced order is used
1037                                      to represent the equation                                      to represent the equation
1038         @type reducedEquationOrder: C{bool}         :type reducedEquationOrder: ``bool``
1039         @param reducedSolutionOrder: True to indicate that reduced order is used         :param reducedSolutionOrder: True to indicate that reduced order is used
1040                                      to represent the solution                                      to represent the solution
1041         @type reducedSolutionOrder: C{bool}         :type reducedSolutionOrder: ``bool``
1042         @return: L{FunctionSpace<escript.FunctionSpace>} of the coefficient         :return: `FunctionSpace` of the coefficient
1043         @rtype: L{FunctionSpace<escript.FunctionSpace>}         :rtype: `FunctionSpace`
1044         """         """
1045         if self.what==self.INTERIOR:         if self.what==self.INTERIOR:
1046              return escript.Function(domain)              return escript.Function(domain)
# Line 1049  class PDECoef(object): Line 1066  class PDECoef(object):
1066         """         """
1067         Returns the value of the coefficient.         Returns the value of the coefficient.
1068    
1069         @return: value of the coefficient         :return: value of the coefficient
1070         @rtype: L{Data<escript.Data>}         :rtype: `Data`
1071         """         """
1072         return self.value         return self.value
1073    
# Line 1058  class PDECoef(object): Line 1075  class PDECoef(object):
1075         """         """
1076         Sets the value of the coefficient to a new value.         Sets the value of the coefficient to a new value.
1077    
1078         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1079         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1080         @param numEquations: number of equations of the PDE         :param numEquations: number of equations of the PDE
1081         @type numEquations: C{int}         :type numEquations: ``int``
1082         @param numSolutions: number of components of the PDE solution         :param numSolutions: number of components of the PDE solution
1083         @type numSolutions: C{int}         :type numSolutions: ``int``
1084         @param reducedEquationOrder: True to indicate that reduced order is used         :param reducedEquationOrder: True to indicate that reduced order is used
1085                                      to represent the equation                                      to represent the equation
1086         @type reducedEquationOrder: C{bool}         :type reducedEquationOrder: ``bool``
1087         @param reducedSolutionOrder: True to indicate that reduced order is used         :param reducedSolutionOrder: True to indicate that reduced order is used
1088                                      to represent the solution                                      to represent the solution
1089         @type reducedSolutionOrder: C{bool}         :type reducedSolutionOrder: ``bool``
1090         @param newValue: number of components of the PDE solution         :param newValue: number of components of the PDE solution
1091         @type newValue: any object that can be converted into a         :type newValue: any object that can be converted into a
1092                         L{Data<escript.Data>} object with the appropriate shape                         `Data` object with the appropriate shape
1093                         and L{FunctionSpace<escript.FunctionSpace>}                         and `FunctionSpace`
1094         @raise IllegalCoefficientValue: if the shape of the assigned value does         :raise IllegalCoefficientValue: if the shape of the assigned value does
1095                                         not match the shape of the coefficient                                         not match the shape of the coefficient
1096         @raise IllegalCoefficientFunctionSpace: if unable to interpolate value         :raise IllegalCoefficientFunctionSpace: if unable to interpolate value
1097                                                 to appropriate function space                                                 to appropriate function space
1098         """         """
1099         if newValue==None:         if newValue==None:
# Line 1099  class PDECoef(object): Line 1116  class PDECoef(object):
1116          """          """
1117          Checks if the coefficient alters the operator of the PDE.          Checks if the coefficient alters the operator of the PDE.
1118    
1119          @return: True if the operator of the PDE is changed when the          :return: True if the operator of the PDE is changed when the
1120                   coefficient is changed                   coefficient is changed
1121          @rtype: C{bool}          :rtype: ``bool``
1122          """          """
1123          if self.altering==self.OPERATOR or self.altering==self.BOTH:          if self.altering==self.OPERATOR or self.altering==self.BOTH:
1124              return not None              return not None
# Line 1112  class PDECoef(object): Line 1129  class PDECoef(object):
1129          """          """
1130          Checks if the coefficient alters the right hand side of the PDE.          Checks if the coefficient alters the right hand side of the PDE.
1131    
1132          @rtype: C{bool}          :rtype: ``bool``
1133          @return: True if the right hand side of the PDE is changed when the          :return: True if the right hand side of the PDE is changed when the
1134                   coefficient is changed, C{None} otherwise.                   coefficient is changed, ``None`` otherwise.
1135          """          """
1136          if self.altering==self.RIGHTHANDSIDE or self.altering==self.BOTH:          if self.altering==self.RIGHTHANDSIDE or self.altering==self.BOTH:
1137              return not None              return not None
# Line 1126  class PDECoef(object): Line 1143  class PDECoef(object):
1143         Tries to estimate the number of equations and number of solutions if         Tries to estimate the number of equations and number of solutions if
1144         the coefficient has the given shape.         the coefficient has the given shape.
1145    
1146         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1147         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1148         @param shape: suggested shape of the coefficient         :param shape: suggested shape of the coefficient
1149         @type shape: C{tuple} of C{int} values         :type shape: ``tuple`` of ``int`` values
1150         @return: the number of equations and number of solutions of the PDE if         :return: the number of equations and number of solutions of the PDE if
1151                  the coefficient has given shape. If no appropriate numbers                  the coefficient has given shape. If no appropriate numbers
1152                  could be identified, C{None} is returned                  could be identified, ``None`` is returned
1153         @rtype: C{tuple} of two C{int} values or C{None}         :rtype: ``tuple`` of two ``int`` values or ``None``
1154         """         """
1155         dim=domain.getDim()         dim=domain.getDim()
1156         if len(shape)>0:         if len(shape)>0:
# Line 1174  class PDECoef(object): Line 1191  class PDECoef(object):
1191         Checks if the coefficient allows to estimate the number of solution         Checks if the coefficient allows to estimate the number of solution
1192         components.         components.
1193    
1194         @return: True if the coefficient allows an estimate of the number of         :return: True if the coefficient allows an estimate of the number of
1195                  solution components, False otherwise                  solution components, False otherwise
1196         @rtype: C{bool}         :rtype: ``bool``
1197         """         """
1198         for i in self.pattern:         for i in self.pattern:
1199               if i==self.BY_SOLUTION: return True               if i==self.BY_SOLUTION: return True
# Line 1186  class PDECoef(object): Line 1203  class PDECoef(object):
1203         """         """
1204         Checks if the coefficient allows to estimate the number of equations.         Checks if the coefficient allows to estimate the number of equations.
1205    
1206         @return: True if the coefficient allows an estimate of the number of         :return: True if the coefficient allows an estimate of the number of
1207                  equations, False otherwise                  equations, False otherwise
1208         @rtype: C{bool}         :rtype: ``bool``
1209         """         """
1210         for i in self.pattern:         for i in self.pattern:
1211               if i==self.BY_EQUATION: return True               if i==self.BY_EQUATION: return True
# Line 1199  class PDECoef(object): Line 1216  class PDECoef(object):
1216        Compares two tuples of possible number of equations and number of        Compares two tuples of possible number of equations and number of
1217        solutions.        solutions.
1218    
1219        @param t1: the first tuple        :param t1: the first tuple
1220        @param t2: the second tuple        :param t2: the second tuple
1221        @return: 0, 1, or -1        :return: 0, 1, or -1
1222        """        """
1223    
1224        dif=t1[0]+t1[1]-(t2[0]+t2[1])        dif=t1[0]+t1[1]-(t2[0]+t2[1])
# Line 1213  class PDECoef(object): Line 1230  class PDECoef(object):
1230         """         """
1231         Builds the required shape of the coefficient.         Builds the required shape of the coefficient.
1232    
1233         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1234         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1235         @param numEquations: number of equations of the PDE         :param numEquations: number of equations of the PDE
1236         @type numEquations: C{int}         :type numEquations: ``int``
1237         @param numSolutions: number of components of the PDE solution         :param numSolutions: number of components of the PDE solution
1238         @type numSolutions: C{int}         :type numSolutions: ``int``
1239         @return: shape of the coefficient         :return: shape of the coefficient
1240         @rtype: C{tuple} of C{int} values         :rtype: ``tuple`` of ``int`` values
1241         """         """
1242         dim=domain.getDim()         dim=domain.getDim()
1243         s=()         s=()
# Line 1238  class PDECoef(object): Line 1255  class PDECoef(object):
1255  class LinearProblem(object):  class LinearProblem(object):
1256     """     """
1257     This is the base class to define a general linear PDE-type problem for     This is the base class to define a general linear PDE-type problem for
1258     for an unknown function M{u} on a given domain defined through a     for an unknown function *u* on a given domain defined through a
1259     L{Domain<escript.Domain>} object. The problem can be given as a single     `Domain` object. The problem can be given as a single
1260     equation or as a system of equations.     equation or as a system of equations.
1261    
1262     The class assumes that some sort of assembling process is required to form     The class assumes that some sort of assembling process is required to form
1263     a problem of the form     a problem of the form
1264    
1265     M{L u=f}     *L u=f*
1266    
1267     where M{L} is an operator and M{f} is the right hand side. This operator     where *L* is an operator and *f* is the right hand side. This operator
1268     problem will be solved to get the unknown M{u}.     problem will be solved to get the unknown *u*.
1269    
1270     """     """
1271     def __init__(self,domain,numEquations=None,numSolutions=None,debug=False):     def __init__(self,domain,numEquations=None,numSolutions=None,debug=False):
1272       """       """
1273       Initializes a linear problem.       Initializes a linear problem.
1274    
1275       @param domain: domain of the PDE       :param domain: domain of the PDE
1276       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
1277       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
1278                            equations is extracted from the coefficients.                            equations is extracted from the coefficients.
1279       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
1280                            of solution components is extracted from the                            of solution components is extracted from the
1281                            coefficients.                            coefficients.
1282       @param debug: if True debug information is printed       :param debug: if True debug information is printed
1283    
1284       """       """
1285       super(LinearProblem, self).__init__()       super(LinearProblem, self).__init__()
# Line 1292  class LinearProblem(object): Line 1309  class LinearProblem(object):
1309       """       """
1310       Returns a string representation of the PDE.       Returns a string representation of the PDE.
1311    
1312       @return: a simple representation of the PDE       :return: a simple representation of the PDE
1313       @rtype: C{str}       :rtype: ``str``
1314       """       """
1315       return "<LinearProblem %d>"%id(self)       return "<LinearProblem %d>"%id(self)
1316     # ==========================================================================     # ==========================================================================
# Line 1313  class LinearProblem(object): Line 1330  class LinearProblem(object):
1330    
1331     def setDebug(self, flag):     def setDebug(self, flag):
1332       """       """
1333       Switches debug output on if C{flag} is True otherwise it is switched off.       Switches debug output on if ``flag`` is True otherwise it is switched off.
1334    
1335       @param flag: desired debug status       :param flag: desired debug status
1336       @type flag: C{bool}       :type flag: ``bool``
1337       """       """
1338       if flag:       if flag:
1339           self.setDebugOn()           self.setDebugOn()
# Line 1327  class LinearProblem(object): Line 1344  class LinearProblem(object):
1344       """       """
1345       Prints the text message if debug mode is switched on.       Prints the text message if debug mode is switched on.
1346    
1347       @param text: message to be printed       :param text: message to be printed
1348       @type text: C{string}       :type text: ``string``
1349       """       """
1350       if self.__debug: print "%s: %s"%(str(self),text)       if self.__debug: print "%s: %s"%(str(self),text)
1351    
# Line 1339  class LinearProblem(object): Line 1356  class LinearProblem(object):
1356         """         """
1357         Introduces new coefficients into the problem.         Introduces new coefficients into the problem.
1358    
1359         Use::         Use:
1360    
1361         p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))         p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))
1362    
1363         to introduce the coefficients M{A} ans M{B}.         to introduce the coefficients *A* and *B*.
1364         """         """
1365         for name, type in coeff.items():         for name, type in coeff.items():
1366             if not isinstance(type,PDECoef):             if not isinstance(type,PDECoef):
# Line 1356  class LinearProblem(object): Line 1373  class LinearProblem(object):
1373       """       """
1374       Returns the domain of the PDE.       Returns the domain of the PDE.
1375    
1376       @return: the domain of the PDE       :return: the domain of the PDE
1377       @rtype: L{Domain<escript.Domain>}       :rtype: `Domain`
1378       """       """
1379       return self.__domain       return self.__domain
1380     def getDomainStatus(self):     def getDomainStatus(self):
# Line 1373  class LinearProblem(object): Line 1390  class LinearProblem(object):
1390       return self.__system_status       return self.__system_status
1391     def setSystemStatus(self,status=None):     def setSystemStatus(self,status=None):
1392       """       """
1393       Sets the system status to C{status} if C{status} is not present the       Sets the system status to ``status`` if ``status`` is not present the
1394       current status of the domain is used.       current status of the domain is used.
1395       """       """
1396       if status == None:       if status == None:
# Line 1385  class LinearProblem(object): Line 1402  class LinearProblem(object):
1402       """       """
1403       Returns the spatial dimension of the PDE.       Returns the spatial dimension of the PDE.
1404    
1405       @return: the spatial dimension of the PDE domain       :return: the spatial dimension of the PDE domain
1406       @rtype: C{int}       :rtype: ``int``
1407       """       """
1408       return self.getDomain().getDim()       return self.getDomain().getDim()
1409    
# Line 1394  class LinearProblem(object): Line 1411  class LinearProblem(object):
1411       """       """
1412       Returns the number of equations.       Returns the number of equations.
1413    
1414       @return: the number of equations       :return: the number of equations
1415       @rtype: C{int}       :rtype: ``int``
1416       @raise UndefinedPDEError: if the number of equations is not specified yet       :raise UndefinedPDEError: if the number of equations is not specified yet
1417       """       """
1418       if self.__numEquations==None:       if self.__numEquations==None:
1419           if self.__numSolutions==None:           if self.__numSolutions==None:
# Line 1409  class LinearProblem(object): Line 1426  class LinearProblem(object):
1426       """       """
1427       Returns the number of unknowns.       Returns the number of unknowns.
1428    
1429       @return: the number of unknowns       :return: the number of unknowns
1430       @rtype: C{int}       :rtype: ``int``
1431       @raise UndefinedPDEError: if the number of unknowns is not specified yet       :raise UndefinedPDEError: if the number of unknowns is not specified yet
1432       """       """
1433       if self.__numSolutions==None:       if self.__numSolutions==None:
1434          if self.__numEquations==None:          if self.__numEquations==None:
# Line 1424  class LinearProblem(object): Line 1441  class LinearProblem(object):
1441       """       """
1442       Returns the status of order reduction for the equation.       Returns the status of order reduction for the equation.
1443    
1444       @return: True if reduced interpolation order is used for the       :return: True if reduced interpolation order is used for the
1445                representation of the equation, False otherwise                representation of the equation, False otherwise
1446       @rtype: L{bool}       :rtype: `bool`
1447       """       """
1448       return self.__reduce_equation_order       return self.__reduce_equation_order
1449    
# Line 1434  class LinearProblem(object): Line 1451  class LinearProblem(object):
1451       """       """
1452       Returns the status of order reduction for the solution.       Returns the status of order reduction for the solution.
1453    
1454       @return: True if reduced interpolation order is used for the       :return: True if reduced interpolation order is used for the
1455                representation of the solution, False otherwise                representation of the solution, False otherwise
1456       @rtype: L{bool}       :rtype: `bool`
1457       """       """
1458       return self.__reduce_solution_order       return self.__reduce_solution_order
1459    
1460     def getFunctionSpaceForEquation(self):     def getFunctionSpaceForEquation(self):
1461       """       """
1462       Returns the L{FunctionSpace<escript.FunctionSpace>} used to discretize       Returns the `FunctionSpace` used to discretize
1463       the equation.       the equation.
1464    
1465       @return: representation space of equation       :return: representation space of equation
1466       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1467       """       """
1468       if self.reduceEquationOrder():       if self.reduceEquationOrder():
1469           return escript.ReducedSolution(self.getDomain())           return escript.ReducedSolution(self.getDomain())
# Line 1455  class LinearProblem(object): Line 1472  class LinearProblem(object):
1472    
1473     def getFunctionSpaceForSolution(self):     def getFunctionSpaceForSolution(self):
1474       """       """
1475       Returns the L{FunctionSpace<escript.FunctionSpace>} used to represent       Returns the `FunctionSpace` used to represent
1476       the solution.       the solution.
1477    
1478       @return: representation space of solution       :return: representation space of solution
1479       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1480       """       """
1481       if self.reduceSolutionOrder():       if self.reduceSolutionOrder():
1482           return escript.ReducedSolution(self.getDomain())           return escript.ReducedSolution(self.getDomain())
# Line 1473  class LinearProblem(object): Line 1490  class LinearProblem(object):
1490         """         """
1491         Sets the solver options.         Sets the solver options.
1492    
1493         @param options: the new solver options. If equal C{None}, the solver options are set to the default.         :param options: the new solver options. If equal ``None``, the solver options are set to the default.
1494         @type options: L{SolverOptions} or C{None}         :type options: `SolverOptions` or ``None``
1495         @note: The symmetry flag of options is overwritten by the symmetry flag of the L{LinearProblem}.         :note: The symmetry flag of options is overwritten by the symmetry flag of the `LinearProblem`.
1496         """         """
1497         if options==None:         if options==None:
1498            self.__solver_options=SolverOptions()            self.__solver_options=SolverOptions()
# Line 1489  class LinearProblem(object): Line 1506  class LinearProblem(object):
1506         """         """
1507         Returns the solver options         Returns the solver options
1508        
1509         @rtype: L{SolverOptions}         :rtype: `SolverOptions`
1510         """         """
1511         self.__solver_options.setSymmetry(self.__sym)         self.__solver_options.setSymmetry(self.__sym)
1512         return self.__solver_options         return self.__solver_options
# Line 1498  class LinearProblem(object): Line 1515  class LinearProblem(object):
1515        """        """
1516        Checks if matrix lumping is the current solver method.        Checks if matrix lumping is the current solver method.
1517    
1518        @return: True if the current solver method is lumping        :return: True if the current solver method is lumping
1519        @rtype: C{bool}        :rtype: ``bool``
1520        """        """
1521        return self.getSolverOptions().getSolverMethod()==self.getSolverOptions().LUMPING        return self.getSolverOptions().getSolverMethod()==self.getSolverOptions().LUMPING
1522     # ==========================================================================     # ==========================================================================
# Line 1509  class LinearProblem(object): Line 1526  class LinearProblem(object):
1526        """        """
1527        Checks if symmetry is indicated.        Checks if symmetry is indicated.
1528    
1529        @return: True if a symmetric PDE is indicated, False otherwise        :return: True if a symmetric PDE is indicated, False otherwise
1530        @rtype: C{bool}        :rtype: ``bool``
1531        @note: the method is equivalent to use getSolverOptions().isSymmetric()        :note: the method is equivalent to use getSolverOptions().isSymmetric()
1532        """        """
1533        self.getSolverOptions().isSymmetric()        self.getSolverOptions().isSymmetric()
1534    
1535     def setSymmetryOn(self):     def setSymmetryOn(self):
1536        """        """
1537        Sets the symmetry flag.        Sets the symmetry flag.
1538        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1539        """        """
1540        self.__sym=True        self.__sym=True
1541        self.getSolverOptions().setSymmetryOn()        self.getSolverOptions().setSymmetryOn()
# Line 1526  class LinearProblem(object): Line 1543  class LinearProblem(object):
1543     def setSymmetryOff(self):     def setSymmetryOff(self):
1544        """        """
1545        Clears the symmetry flag.        Clears the symmetry flag.
1546        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1547        """        """
1548        self.__sym=False        self.__sym=False
1549        self.getSolverOptions().setSymmetryOff()        self.getSolverOptions().setSymmetryOff()
1550    
1551     def setSymmetry(self,flag=False):     def setSymmetry(self,flag=False):
1552        """        """
1553        Sets the symmetry flag to C{flag}.        Sets the symmetry flag to ``flag``.
1554    
1555        @param flag: If True, the symmetry flag is set otherwise reset.        :param flag: If True, the symmetry flag is set otherwise reset.
1556        @type flag: C{bool}        :type flag: ``bool``
1557        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1558        """        """
1559        self.getSolverOptions().setSymmetry(flag)        self.getSolverOptions().setSymmetry(flag)
1560     # ==========================================================================     # ==========================================================================
# Line 1547  class LinearProblem(object): Line 1564  class LinearProblem(object):
1564       """       """
1565       Switches reduced order on for solution and equation representation.       Switches reduced order on for solution and equation representation.
1566    
1567       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1568                            been set                            been set
1569       """       """
1570       self.setReducedOrderForSolutionOn()       self.setReducedOrderForSolutionOn()
# Line 1557  class LinearProblem(object): Line 1574  class LinearProblem(object):
1574       """       """
1575       Switches reduced order off for solution and equation representation       Switches reduced order off for solution and equation representation
1576    
1577       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1578                            been set                            been set
1579       """       """
1580       self.setReducedOrderForSolutionOff()       self.setReducedOrderForSolutionOff()
# Line 1568  class LinearProblem(object): Line 1585  class LinearProblem(object):
1585       Sets order reduction state for both solution and equation representation       Sets order reduction state for both solution and equation representation
1586       according to flag.       according to flag.
1587    
1588       @param flag: if True, the order reduction is switched on for both solution       :param flag: if True, the order reduction is switched on for both solution
1589                    and equation representation, otherwise or if flag is not                    and equation representation, otherwise or if flag is not
1590                    present order reduction is switched off                    present order reduction is switched off
1591       @type flag: C{bool}       :type flag: ``bool``
1592       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1593                            been set                            been set
1594       """       """
1595       self.setReducedOrderForSolutionTo(flag)       self.setReducedOrderForSolutionTo(flag)
# Line 1583  class LinearProblem(object): Line 1600  class LinearProblem(object):
1600       """       """
1601       Switches reduced order on for solution representation.       Switches reduced order on for solution representation.
1602    
1603       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1604                            been set                            been set
1605       """       """
1606       if not self.__reduce_solution_order:       if not self.__reduce_solution_order:
# Line 1597  class LinearProblem(object): Line 1614  class LinearProblem(object):
1614       """       """
1615       Switches reduced order off for solution representation       Switches reduced order off for solution representation
1616    
1617       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1618                            been set.                            been set.
1619       """       """
1620       if self.__reduce_solution_order:       if self.__reduce_solution_order:
# Line 1611  class LinearProblem(object): Line 1628  class LinearProblem(object):
1628       """       """
1629       Sets order reduction state for solution representation according to flag.       Sets order reduction state for solution representation according to flag.
1630    
1631       @param flag: if flag is True, the order reduction is switched on for       :param flag: if flag is True, the order reduction is switched on for
1632                    solution representation, otherwise or if flag is not present                    solution representation, otherwise or if flag is not present
1633                    order reduction is switched off                    order reduction is switched off
1634       @type flag: C{bool}       :type flag: ``bool``
1635       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1636                            been set                            been set
1637       """       """
1638       if flag:       if flag:
# Line 1627  class LinearProblem(object): Line 1644  class LinearProblem(object):
1644       """       """
1645       Switches reduced order on for equation representation.       Switches reduced order on for equation representation.
1646    
1647       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1648                            been set                            been set
1649       """       """
1650       if not self.__reduce_equation_order:       if not self.__reduce_equation_order:
# Line 1641  class LinearProblem(object): Line 1658  class LinearProblem(object):
1658       """       """
1659       Switches reduced order off for equation representation.       Switches reduced order off for equation representation.
1660    
1661       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1662                            been set                            been set
1663       """       """
1664       if self.__reduce_equation_order:       if self.__reduce_equation_order:
# Line 1655  class LinearProblem(object): Line 1672  class LinearProblem(object):
1672       """       """
1673       Sets order reduction state for equation representation according to flag.       Sets order reduction state for equation representation according to flag.
1674    
1675       @param flag: if flag is True, the order reduction is switched on for       :param flag: if flag is True, the order reduction is switched on for
1676                    equation representation, otherwise or if flag is not present                    equation representation, otherwise or if flag is not present
1677                    order reduction is switched off                    order reduction is switched off
1678       @type flag: C{bool}       :type flag: ``bool``
1679       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1680                            been set                            been set
1681       """       """
1682       if flag:       if flag:
# Line 1676  class LinearProblem(object): Line 1693  class LinearProblem(object):
1693        """        """
1694        Tests a coefficient for symmetry.        Tests a coefficient for symmetry.
1695    
1696        @param name: name of the coefficient        :param name: name of the coefficient
1697        @type name: C{str}        :type name: ``str``
1698        @param verbose: if set to True or not present a report on coefficients        :param verbose: if set to True or not present a report on coefficients
1699                        which break the symmetry is printed.                        which break the symmetry is printed.
1700        @type verbose: C{bool}        :type verbose: ``bool``
1701        @return: True if coefficient C{name} is symmetric        :return: True if coefficient ``name`` is symmetric
1702        @rtype: C{bool}        :rtype: ``bool``
1703        """        """
1704        SMALL_TOLERANCE=util.EPSILON*10.        SMALL_TOLERANCE=util.EPSILON*10.
1705        A=self.getCoefficient(name)        A=self.getCoefficient(name)
# Line 1723  class LinearProblem(object): Line 1740  class LinearProblem(object):
1740        """        """
1741        Tests two coefficients for reciprocal symmetry.        Tests two coefficients for reciprocal symmetry.
1742    
1743        @param name0: name of the first coefficient        :param name0: name of the first coefficient
1744        @type name0: C{str}        :type name0: ``str``
1745        @param name1: name of the second coefficient        :param name1: name of the second coefficient
1746        @type name1: C{str}        :type name1: ``str``
1747        @param verbose: if set to True or not present a report on coefficients        :param verbose: if set to True or not present a report on coefficients
1748                        which break the symmetry is printed                        which break the symmetry is printed
1749        @type verbose: C{bool}        :type verbose: ``bool``
1750        @return: True if coefficients C{name0} and C{name1} are reciprocally        :return: True if coefficients ``name0`` and ``name1`` are reciprocally
1751                 symmetric.                 symmetric.
1752        @rtype: C{bool}        :rtype: ``bool``
1753        """        """
1754        SMALL_TOLERANCE=util.EPSILON*10.        SMALL_TOLERANCE=util.EPSILON*10.
1755        B=self.getCoefficient(name0)        B=self.getCoefficient(name0)
# Line 1781  class LinearProblem(object): Line 1798  class LinearProblem(object):
1798    
1799     def getCoefficient(self,name):     def getCoefficient(self,name):
1800       """       """
1801       Returns the value of the coefficient C{name}.       Returns the value of the coefficient ``name``.
1802    
1803       @param name: name of the coefficient requested       :param name: name of the coefficient requested
1804       @type name: C{string}       :type name: ``string``
1805       @return: the value of the coefficient       :return: the value of the coefficient
1806       @rtype: L{Data<escript.Data>}       :rtype: `Data`
1807       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1808       """       """
1809       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1810           return self.__COEFFICIENTS[name].getValue()           return self.__COEFFICIENTS[name].getValue()
# Line 1796  class LinearProblem(object): Line 1813  class LinearProblem(object):
1813    
1814     def hasCoefficient(self,name):     def hasCoefficient(self,name):
1815       """       """
1816       Returns True if C{name} is the name of a coefficient.       Returns True if ``name`` is the name of a coefficient.
1817    
1818       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1819       @type name: C{string}       :type name: ``string``
1820       @return: True if C{name} is the name of a coefficient of the general PDE,       :return: True if ``name`` is the name of a coefficient of the general PDE,
1821                False otherwise                False otherwise
1822       @rtype: C{bool}       :rtype: ``bool``
1823       """       """
1824       return self.__COEFFICIENTS.has_key(name)       return self.__COEFFICIENTS.has_key(name)
1825    
1826     def createCoefficient(self, name):     def createCoefficient(self, name):
1827       """       """
1828       Creates a L{Data<escript.Data>} object corresponding to coefficient       Creates a `Data` object corresponding to coefficient
1829       C{name}.       ``name``.
1830    
1831       @return: the coefficient C{name} initialized to 0       :return: the coefficient ``name`` initialized to 0
1832       @rtype: L{Data<escript.Data>}       :rtype: `Data`
1833       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1834       """       """
1835       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1836          return escript.Data(0.,self.getShapeOfCoefficient(name),self.getFunctionSpaceForCoefficient(name))          return escript.Data(0.,self.getShapeOfCoefficient(name),self.getFunctionSpaceForCoefficient(name))
# Line 1822  class LinearProblem(object): Line 1839  class LinearProblem(object):
1839    
1840     def getFunctionSpaceForCoefficient(self,name):     def getFunctionSpaceForCoefficient(self,name):
1841       """       """
1842       Returns the L{FunctionSpace<escript.FunctionSpace>} to be used for       Returns the `FunctionSpace` to be used for
1843       coefficient C{name}.       coefficient ``name``.
1844    
1845       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1846       @type name: C{string}       :type name: ``string``
1847       @return: the function space to be used for coefficient C{name}       :return: the function space to be used for coefficient ``name``
1848       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1849       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1850       """       """
1851       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1852          return self.__COEFFICIENTS[name].getFunctionSpace(self.getDomain())          return self.__COEFFICIENTS[name].getFunctionSpace(self.getDomain())
# Line 1838  class LinearProblem(object): Line 1855  class LinearProblem(object):
1855    
1856     def getShapeOfCoefficient(self,name):     def getShapeOfCoefficient(self,name):
1857       """       """
1858       Returns the shape of the coefficient C{name}.       Returns the shape of the coefficient ``name``.
1859    
1860       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1861       @type name: C{string}       :type name: ``string``
1862       @return: the shape of the coefficient C{name}       :return: the shape of the coefficient ``name``
1863       @rtype: C{tuple} of C{int}       :rtype: ``tuple`` of ``int``
1864       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1865       """       """
1866       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1867          return self.__COEFFICIENTS[name].getShape(self.getDomain(),self.getNumEquations(),self.getNumSolutions())          return self.__COEFFICIENTS[name].getShape(self.getDomain(),self.getNumEquations(),self.getNumSolutions())
# Line 1860  class LinearProblem(object): Line 1877  class LinearProblem(object):
1877    
1878     def alteredCoefficient(self,name):     def alteredCoefficient(self,name):
1879       """       """
1880       Announces that coefficient C{name} has been changed.       Announces that coefficient ``name`` has been changed.
1881    
1882       @param name: name of the coefficient affected       :param name: name of the coefficient affected
1883       @type name: C{string}       :type name: ``string``
1884       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1885       @note: if C{name} is q or r, the method will not trigger a rebuild of the       :note: if ``name`` is q or r, the method will not trigger a rebuild of the
1886              system as constraints are applied to the solved system.              system as constraints are applied to the solved system.
1887       """       """
1888       if self.hasCoefficient(name):       if self.hasCoefficient(name):
# Line 1972  class LinearProblem(object): Line 1989  class LinearProblem(object):
1989       """       """
1990       Returns the operator of the linear problem.       Returns the operator of the linear problem.
1991    
1992       @return: the operator of the problem       :return: the operator of the problem
1993       """       """
1994       return self.getSystem()[0]       return self.getSystem()[0]
1995    
# Line 1980  class LinearProblem(object): Line 1997  class LinearProblem(object):
1997       """       """
1998       Returns the right hand side of the linear problem.       Returns the right hand side of the linear problem.
1999    
2000       @return: the right hand side of the problem       :return: the right hand side of the problem
2001       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2002       """       """
2003       return self.getSystem()[1]       return self.getSystem()[1]
2004    
# Line 2064  class LinearProblem(object): Line 2081  class LinearProblem(object):
2081             if self.isUsingLumping():             if self.isUsingLumping():
2082                 self.__operator.setToZero()                 self.__operator.setToZero()
2083             else:             else:
2084                 self.__operator.resetValues()                 if self.getOperatorType() == self.getRequiredOperatorType():
2085                       self.__operator.resetValues()
2086                   else:
2087                       self.__operator=self.createOperator()
2088                   self.__operator_type=self.getRequiredOperatorType()
2089             self.trace("Operator reset to zero")             self.trace("Operator reset to zero")
2090    
2091     def getCurrentOperator(self):     def getCurrentOperator(self):
# Line 2077  class LinearProblem(object): Line 2098  class LinearProblem(object):
2098        """        """
2099        Sets new values to coefficients.        Sets new values to coefficients.
2100    
2101        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
2102        """        """
2103        # check if the coefficients are  legal:        # check if the coefficients are  legal:
2104        for i in coefficients.iterkeys():        for i in coefficients.iterkeys():
# Line 2136  class LinearProblem(object): Line 2157  class LinearProblem(object):
2157        """        """
2158        Returns the system type which needs to be used by the current set up.        Returns the system type which needs to be used by the current set up.
2159    
2160        @note: Typically this method is overwritten when implementing a        :note: Typically this method is overwritten when implementing a
2161               particular linear problem.               particular linear problem.
2162        """        """
2163        return None        return None
# Line 2145  class LinearProblem(object): Line 2166  class LinearProblem(object):
2166         """         """
2167         Returns an instance of a new operator.         Returns an instance of a new operator.
2168    
2169         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2170                linear problem.                linear problem.
2171         """         """
2172         return escript.Operator()         return escript.Operator()
# Line 2154  class LinearProblem(object): Line 2175  class LinearProblem(object):
2175        """        """
2176        Tests the PDE for symmetry.        Tests the PDE for symmetry.
2177    
2178        @param verbose: if set to True or not present a report on coefficients        :param verbose: if set to True or not present a report on coefficients
2179                        which break the symmetry is printed                        which break the symmetry is printed
2180        @type verbose: C{bool}        :type verbose: ``bool``
2181        @return: True if the problem is symmetric        :return: True if the problem is symmetric
2182        @rtype: C{bool}        :rtype: ``bool``
2183        @note: Typically this method is overwritten when implementing a        :note: Typically this method is overwritten when implementing a
2184               particular linear problem.               particular linear problem.
2185        """        """
2186        out=True        out=True
# Line 2169  class LinearProblem(object): Line 2190  class LinearProblem(object):
2190         """         """
2191         Returns the solution of the problem.         Returns the solution of the problem.
2192    
2193         @return: the solution         :return: the solution
2194         @rtype: L{Data<escript.Data>}         :rtype: `Data`
2195    
2196         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2197                linear problem.                linear problem.
2198         """         """
2199         return self.getCurrentSolution()         return self.getCurrentSolution()
# Line 2181  class LinearProblem(object): Line 2202  class LinearProblem(object):
2202         """         """
2203         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
2204    
2205         @return: the discrete version of the PDE         :return: the discrete version of the PDE
2206         @rtype: C{tuple} of L{Operator,<escript.Operator>} and L{Data<escript.Data>}.         :rtype: ``tuple`` of `Operator` and `Data`.
2207    
2208         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2209                linear problem.                linear problem.
2210         """         """
2211         return (self.getCurrentOperator(), self.getCurrentRightHandSide())         return (self.getCurrentOperator(), self.getCurrentRightHandSide())
# Line 2192  class LinearProblem(object): Line 2213  class LinearProblem(object):
2213  class LinearPDE(LinearProblem):  class LinearPDE(LinearProblem):
2214     """     """
2215     This class is used to define a general linear, steady, second order PDE     This class is used to define a general linear, steady, second order PDE
2216     for an unknown function M{u} on a given domain defined through a     for an unknown function *u* on a given domain defined through a
2217     L{Domain<escript.Domain>} object.     `Domain` object.
2218    
2219     For a single PDE having a solution with a single component the linear PDE     For a single PDE having a solution with a single component the linear PDE
2220     is defined in the following form:     is defined in the following form:
2221    
2222     M{-(grad(A[j,l]+A_reduced[j,l])*grad(u)[l]+(B[j]+B_reduced[j])u)[j]+(C[l]+C_reduced[l])*grad(u)[l]+(D+D_reduced)=-grad(X+X_reduced)[j,j]+(Y+Y_reduced)}     *-(grad(A[j,l]+A_reduced[j,l])*grad(u)[l]+(B[j]+B_reduced[j])u)[j]+(C[l]+C_reduced[l])*grad(u)[l]+(D+D_reduced)=-grad(X+X_reduced)[j,j]+(Y+Y_reduced)*
2223    
2224     where M{grad(F)} denotes the spatial derivative of M{F}. Einstein's     where *grad(F)* denotes the spatial derivative of *F*. Einstein's
2225     summation convention, ie. summation over indexes appearing twice in a term     summation convention, ie. summation over indexes appearing twice in a term
2226     of a sum performed, is used.     of a sum performed, is used.
2227     The coefficients M{A}, M{B}, M{C}, M{D}, M{X} and M{Y} have to be specified     The coefficients *A*, *B*, *C*, *D*, *X* and *Y* have to be specified
2228     through L{Data<escript.Data>} objects in L{Function<escript.Function>} and     through `Data` objects in `Function` and
2229     the coefficients M{A_reduced}, M{B_reduced}, M{C_reduced}, M{D_reduced},     the coefficients *A_reduced*, *B_reduced*, *C_reduced*, *D_reduced*,
2230     M{X_reduced} and M{Y_reduced} have to be specified through     *X_reduced* and *Y_reduced* have to be specified through
2231     L{Data<escript.Data>} objects in L{ReducedFunction<escript.ReducedFunction>}.     `Data` objects in `ReducedFunction`.
2232     It is also allowed to use objects that can be converted into such     It is also allowed to use objects that can be converted into such
2233     L{Data<escript.Data>} objects. M{A} and M{A_reduced} are rank two, M{B},     `Data` objects. *A* and *A_reduced* are rank two, *B*,
2234     M{C}, M{X}, M{B_reduced}, M{C_reduced} and M{X_reduced} are rank one and     *C*, *X*, *B_reduced*, *C_reduced* and *X_reduced* are rank one and
2235     M{D}, M{D_reduced}, M{Y} and M{Y_reduced} are scalar.     *D*, *D_reduced*, *Y* and *Y_reduced* are scalar.
2236    
2237     The following natural boundary conditions are considered:     The following natural boundary conditions are considered:
2238    
2239     M{n[j]*((A[i,j]+A_reduced[i,j])*grad(u)[l]+(B+B_reduced)[j]*u)+(d+d_reduced)*u=n[j]*(X[j]+X_reduced[j])+y}     *n[j]*((A[i,j]+A_reduced[i,j])*grad(u)[l]+(B+B_reduced)[j]*u)+(d+d_reduced)*u=n[j]*(X[j]+X_reduced[j])+y*
2240    
2241     where M{n} is the outer normal field. Notice that the coefficients M{A},     where *n* is the outer normal field. Notice that the coefficients *A*,
2242     M{A_reduced}, M{B}, M{B_reduced}, M{X} and M{X_reduced} are defined in the     *A_reduced*, *B*, *B_reduced*, *X* and *X_reduced* are defined in the
2243     PDE. The coefficients M{d} and M{y} are each a scalar in     PDE. The coefficients *d* and *y* are each a scalar in
2244     L{FunctionOnBoundary<escript.FunctionOnBoundary>} and the coefficients     `FunctionOnBoundary` and the coefficients
2245     M{d_reduced} and M{y_reduced} are each a scalar in     *d_reduced* and *y_reduced* are each a scalar in
2246     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
2247    
2248     Constraints for the solution prescribe the value of the solution at certain     Constraints for the solution prescribe the value of the solution at certain
2249     locations in the domain. They have the form     locations in the domain. They have the form
2250    
2251     M{u=r} where M{q>0}     *u=r* where *q>0*
2252    
2253     M{r} and M{q} are each scalar where M{q} is the characteristic function     *r* and *q* are each scalar where *q* is the characteristic function
2254     defining where the constraint is applied. The constraints override any     defining where the constraint is applied. The constraints override any
2255     other condition set by the PDE or the boundary condition.     other condition set by the PDE or the boundary condition.
2256    
2257     The PDE is symmetrical if     The PDE is symmetrical if
2258    
2259     M{A[i,j]=A[j,i]}  and M{B[j]=C[j]} and M{A_reduced[i,j]=A_reduced[j,i]}     *A[i,j]=A[j,i]*  and *B[j]=C[j]* and *A_reduced[i,j]=A_reduced[j,i]*
2260     and M{B_reduced[j]=C_reduced[j]}     and *B_reduced[j]=C_reduced[j]*
2261    
2262     For a system of PDEs and a solution with several components the PDE has the     For a system of PDEs and a solution with several components the PDE has the
2263     form     form
2264    
2265     M{-grad((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k])[j]+(C[i,k,l]+C_reduced[i,k,l])*grad(u[k])[l]+(D[i,k]+D_reduced[i,k]*u[k] =-grad(X[i,j]+X_reduced[i,j])[j]+Y[i]+Y_reduced[i] }     *-grad((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k])[j]+(C[i,k,l]+C_reduced[i,k,l])*grad(u[k])[l]+(D[i,k]+D_reduced[i,k]*u[k] =-grad(X[i,j]+X_reduced[i,j])[j]+Y[i]+Y_reduced[i]*
2266    
2267     M{A} and M{A_reduced} are of rank four, M{B}, M{B_reduced}, M{C} and     *A* and *A_reduced* are of rank four, *B*, *B_reduced*, *C* and
2268     M{C_reduced} are each of rank three, M{D}, M{D_reduced}, M{X_reduced} and     *C_reduced* are each of rank three, *D*, *D_reduced*, *X_reduced* and
2269     M{X} are each of rank two and M{Y} and M{Y_reduced} are of rank one.     *X* are each of rank two and *Y* and *Y_reduced* are of rank one.
2270     The natural boundary conditions take the form:     The natural boundary conditions take the form:
2271    
2272     M{n[j]*((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k])+(d[i,k]+d_reduced[i,k])*u[k]=n[j]*(X[i,j]+X_reduced[i,j])+y[i]+y_reduced[i]}     *n[j]*((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k])+(d[i,k]+d_reduced[i,k])*u[k]=n[j]*(X[i,j]+X_reduced[i,j])+y[i]+y_reduced[i]*
2273    
2274     The coefficient M{d} is of rank two and M{y} is of rank one both in     The coefficient *d* is of rank two and *y* is of rank one both in
2275     L{FunctionOnBoundary<escript.FunctionOnBoundary>}. The coefficients     `FunctionOnBoundary`. The coefficients
2276     M{d_reduced} is of rank two and M{y_reduced} is of rank one both in     *d_reduced* is of rank two and *y_reduced* is of rank one both in
2277     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
2278    
2279     Constraints take the form     Constraints take the form
2280    
2281     M{u[i]=r[i]}  where  M{q[i]>0}     *u[i]=r[i]*  where  *q[i]>0*
2282    
2283     M{r} and M{q} are each rank one. Notice that at some locations not     *r* and *q* are each rank one. Notice that at some locations not
2284     necessarily all components must have a constraint.     necessarily all components must have a constraint.
2285    
2286     The system of PDEs is symmetrical if     The system of PDEs is symmetrical if
2287    
2288        - M{A[i,j,k,l]=A[k,l,i,j]}        - *A[i,j,k,l]=A[k,l,i,j]*
2289        - M{A_reduced[i,j,k,l]=A_reduced[k,l,i,j]}        - *A_reduced[i,j,k,l]=A_reduced[k,l,i,j]*
2290        - M{B[i,j,k]=C[k,i,j]}        - *B[i,j,k]=C[k,i,j]*
2291        - M{B_reduced[i,j,k]=C_reduced[k,i,j]}        - *B_reduced[i,j,k]=C_reduced[k,i,j]*
2292        - M{D[i,k]=D[i,k]}        - *D[i,k]=D[i,k]*
2293        - M{D_reduced[i,k]=D_reduced[i,k]}        - *D_reduced[i,k]=D_reduced[i,k]*
2294        - M{d[i,k]=d[k,i]}        - *d[i,k]=d[k,i]*
2295        - M{d_reduced[i,k]=d_reduced[k,i]}        - *d_reduced[i,k]=d_reduced[k,i]*
2296    
2297     L{LinearPDE} also supports solution discontinuities over a contact region     `LinearPDE` also supports solution discontinuities over a contact region
2298     in the domain. To specify the conditions across the discontinuity we are     in the domain. To specify the conditions across the discontinuity we are
2299     using the generalised flux M{J} which, in the case of a system of PDEs     using the generalised flux *J* which, in the case of a system of PDEs
2300     and several components of the solution, is defined as     and several components of the solution, is defined as
2301    
2302     M{J[i,j]=(A[i,j,k,l]+A_reduced[[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]-X[i,j]-X_reduced[i,j]}     *J[i,j]=(A[i,j,k,l]+A_reduced[[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]-X[i,j]-X_reduced[i,j]*
2303    
2304     For the case of single solution component and single PDE M{J} is defined as     For the case of single solution component and single PDE *J* is defined as
2305    
2306     M{J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[j]+(B[i]+B_reduced[i])*u-X[i]-X_reduced[i]}     *J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[j]+(B[i]+B_reduced[i])*u-X[i]-X_reduced[i]*
2307    
2308     In the context of discontinuities M{n} denotes the normal on the     In the context of discontinuities *n* denotes the normal on the
2309     discontinuity pointing from side 0 towards side 1 calculated from     discontinuity pointing from side 0 towards side 1 calculated from
2310     L{getNormal<escript.FunctionSpace.getNormal>} of L{FunctionOnContactZero<escript.FunctionOnContactZero>}.     `FunctionSpace.getNormal` of `FunctionOnContactZero`.
2311     For a system of PDEs the contact condition takes the form     For a system of PDEs the contact condition takes the form
2312    
2313     M{n[j]*J0[i,j]=n[j]*J1[i,j]=(y_contact[i]+y_contact_reduced[i])- (d_contact[i,k]+d_contact_reduced[i,k])*jump(u)[k]}     *n[j]*J0[i,j]=n[j]*J1[i,j]=(y_contact[i]+y_contact_reduced[i])- (d_contact[i,k]+d_contact_reduced[i,k])*jump(u)[k]*
2314    
2315     where M{J0} and M{J1} are the fluxes on side 0 and side 1 of the     where *J0* and *J1* are the fluxes on side 0 and side 1 of the
2316     discontinuity, respectively. M{jump(u)}, which is the difference of the     discontinuity, respectively. *jump(u)*, which is the difference of the
2317     solution at side 1 and at side 0, denotes the jump of M{u} across     solution at side 1 and at side 0, denotes the jump of *u* across
2318     discontinuity along the normal calculated by L{jump<util.jump>}.     discontinuity along the normal calculated by `jump`.
2319     The coefficient M{d_contact} is of rank two and M{y_contact} is of rank one     The coefficient *d_contact* is of rank two and *y_contact* is of rank one
2320     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
2321     L{FunctionOnContactOne<escript.FunctionOnContactOne>}.     `FunctionOnContactOne`.
2322     The coefficient M{d_contact_reduced} is of rank two and M{y_contact_reduced}     The coefficient *d_contact_reduced* is of rank two and *y_contact_reduced*
2323     is of rank one both in L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>}     is of rank one both in `ReducedFunctionOnContactZero`
2324     or L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     or `ReducedFunctionOnContactOne`.
2325     In case of a single PDE and a single component solution the contact     In case of a single PDE and a single component solution the contact
2326     condition takes the form     condition takes the form
2327    
2328     M{n[j]*J0_{j}=n[j]*J1_{j}=(y_contact+y_contact_reduced)-(d_contact+y_contact_reduced)*jump(u)}     *n[j]*J0_{j}=n[j]*J1_{j}=(y_contact+y_contact_reduced)-(d_contact+y_contact_reduced)*jump(u)*
2329    
2330     In this case the coefficient M{d_contact} and M{y_contact} are each scalar     In this case the coefficient *d_contact* and *y_contact* are each scalar
2331     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
2332     L{FunctionOnContactOne<escript.FunctionOnContactOne>} and the coefficient     `FunctionOnContactOne` and the coefficient
2333     M{d_contact_reduced} and M{y_contact_reduced} are each scalar both in     *d_contact_reduced* and *y_contact_reduced* are each scalar both in
2334     L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or     `ReducedFunctionOnContactZero` or
2335     L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     `ReducedFunctionOnContactOne`.
2336    
2337     Typical usage::     Typical usage::
2338    
# Line 2325  class LinearPDE(LinearProblem): Line 2346  class LinearPDE(LinearProblem):
2346       """       """
2347       Initializes a new linear PDE.       Initializes a new linear PDE.
2348    
2349       @param domain: domain of the PDE       :param domain: domain of the PDE
2350       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2351       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
2352                            equations is extracted from the PDE coefficients.                            equations is extracted from the PDE coefficients.
2353       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
2354                            of solution components is extracted from the PDE                            of solution components is extracted from the PDE
2355                            coefficients.                            coefficients.
2356       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2357    
2358       """       """
2359       super(LinearPDE, self).__init__(domain,numEquations,numSolutions,debug)       super(LinearPDE, self).__init__(domain,numEquations,numSolutions,debug)
# Line 2367  class LinearPDE(LinearProblem): Line 2388  class LinearPDE(LinearProblem):
2388       """       """
2389       Returns the string representation of the PDE.       Returns the string representation of the PDE.
2390    
2391       @return: a simple representation of the PDE       :return: a simple representation of the PDE
2392       @rtype: C{str}       :rtype: ``str``
2393       """       """
2394       return "<LinearPDE %d>"%id(self)       return "<LinearPDE %d>"%id(self)
2395    
# Line 2383  class LinearPDE(LinearProblem): Line 2404  class LinearPDE(LinearProblem):
2404        """        """
2405        Tests the PDE for symmetry.        Tests the PDE for symmetry.
2406    
2407        @param verbose: if set to True or not present a report on coefficients        :param verbose: if set to True or not present a report on coefficients
2408                        which break the symmetry is printed.                        which break the symmetry is printed.
2409        @type verbose: C{bool}        :type verbose: ``bool``
2410        @return: True if the PDE is symmetric        :return: True if the PDE is symmetric
2411        @rtype: L{bool}        :rtype: `bool`
2412        @note: This is a very expensive operation. It should be used for        :note: This is a very expensive operation. It should be used for
2413               degugging only! The symmetry flag is not altered.               degugging only! The symmetry flag is not altered.
2414        """        """
2415        out=True        out=True
# Line 2421  class LinearPDE(LinearProblem): Line 2442  class LinearPDE(LinearProblem):
2442         """         """
2443         Returns the solution of the PDE.         Returns the solution of the PDE.
2444    
2445         @return: the solution         :return: the solution
2446         @rtype: L{Data<escript.Data>}         :rtype: `Data`
2447         """         """
2448         option_class=self.getSolverOptions()         option_class=self.getSolverOptions()
2449         if not self.isSolutionValid():         if not self.isSolutionValid():
# Line 2439  class LinearPDE(LinearProblem): Line 2460  class LinearPDE(LinearProblem):
2460         """         """
2461         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
2462    
2463         @return: the discrete version of the PDE         :return: the discrete version of the PDE
2464         @rtype: C{tuple} of L{Operator,<escript.Operator>} and         :rtype: ``tuple`` of `Operator` and
2465                 L{Data<escript.Data>}                 `Data`
2466         """         """
2467         if not self.isOperatorValid() or not self.isRightHandSideValid():         if not self.isOperatorValid() or not self.isRightHandSideValid():
2468            if self.isUsingLumping():            if self.isUsingLumping():
# Line 2616  class LinearPDE(LinearProblem): Line 2637  class LinearPDE(LinearProblem):
2637        """        """
2638        Applies the constraints defined by q and r to the PDE.        Applies the constraints defined by q and r to the PDE.
2639    
2640        @param rhs_only: if True only the right hand side is altered by the        :param rhs_only: if True only the right hand side is altered by the
2641                         constraint                         constraint
2642        @type rhs_only: C{bool}        :type rhs_only: ``bool``
2643        """        """
2644        q=self.getCoefficient("q")        q=self.getCoefficient("q")
2645        r=self.getCoefficient("r")        r=self.getCoefficient("r")
# Line 2646  class LinearPDE(LinearProblem): Line 2667  class LinearPDE(LinearProblem):
2667        """        """
2668        Sets new values to coefficients.        Sets new values to coefficients.
2669    
2670        @param coefficients: new values assigned to coefficients        :param coefficients: new values assigned to coefficients
2671        @keyword A: value for coefficient C{A}        :keyword A: value for coefficient ``A``
2672        @type A: any type that can be cast to a L{Data<escript.Data>} object on        :type A: any type that can be cast to a `Data` object on
2673                 L{Function<escript.Function>}                 `Function`
2674        @keyword A_reduced: value for coefficient C{A_reduced}        :keyword A_reduced: value for coefficient ``A_reduced``
2675        @type A_reduced: any type that can be cast to a L{Data<escript.Data>}        :type A_reduced: any type that can be cast to a `Data`
2676                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2677        @keyword B: value for coefficient C{B}        :keyword B: value for coefficient ``B``
2678        @type B: any type that can be cast to a L{Data<escript.Data>} object on        :type B: any type that can be cast to a `Data` object on
2679                 L{Function<escript.Function>}                 `Function`
2680        @keyword B_reduced: value for coefficient C{B_reduced}        :keyword B_reduced: value for coefficient ``B_reduced``
2681        @type B_reduced: any type that can be cast to a L{Data<escript.Data>}        :type B_reduced: any type that can be cast to a `Data`
2682                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2683        @keyword C: value for coefficient C{C}        :keyword C: value for coefficient ``C``
2684        @type C: any type that can be cast to a L{Data<escript.Data>} object on        :type C: any type that can be cast to a `Data` object on
2685                 L{Function<escript.Function>}                 `Function`
2686        @keyword C_reduced: value for coefficient C{C_reduced}        :keyword C_reduced: value for coefficient ``C_reduced``
2687        @type C_reduced: any type that can be cast to a L{Data<escript.Data>}        :type C_reduced: any type that can be cast to a `Data`
2688                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2689        @keyword D: value for coefficient C{D}        :keyword D: value for coefficient ``D``
2690        @type D: any type that can be cast to a L{Data<escript.Data>} object on        :type D: any type that can be cast to a `Data` object on
2691                 L{Function<escript.Function>}                 `Function`
2692        @keyword D_reduced: value for coefficient C{D_reduced}        :keyword D_reduced: value for coefficient ``D_reduced``
2693        @type D_reduced: any type that can be cast to a L{Data<escript.Data>}        :type D_reduced: any type that can be cast to a `Data`
2694                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2695        @keyword X: value for coefficient C{X}        :keyword X: value for coefficient ``X``
2696        @type X: any type that can be cast to a L{Data<escript.Data>} object on        :type X: any type that can be cast to a `Data` object on
2697                 L{Function<escript.Function>}                 `Function`
2698        @keyword X_reduced: value for coefficient C{X_reduced}        :keyword X_reduced: value for coefficient ``X_reduced``
2699        @type X_reduced: any type that can be cast to a L{Data<escript.Data>}        :type X_reduced: any type that can be cast to a `Data`
2700                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2701        @keyword Y: value for coefficient C{Y}        :keyword Y: value for coefficient ``Y``
2702        @type Y: any type that can be cast to a L{Data<escript.Data>} object on        :type Y: any type that can be cast to a `Data` object on
2703                 L{Function<escript.Function>}                 `Function`
2704        @keyword Y_reduced: value for coefficient C{Y_reduced}        :keyword Y_reduced: value for coefficient ``Y_reduced``
2705        @type Y_reduced: any type that can be cast to a L{Data<escript.Data>}        :type Y_reduced: any type that can be cast to a `Data`
2706                         object on L{ReducedFunction<escript.Function>}                         object on `ReducedFunction`
2707        @keyword d: value for coefficient C{d}        :keyword d: value for coefficient ``d``
2708        @type d: any type that can be cast to a L{Data<escript.Data>} object on        :type d: any type that can be cast to a `Data` object on
2709                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
2710        @keyword d_reduced: value for coefficient C{d_reduced}        :keyword d_reduced: value for coefficient ``d_reduced``
2711        @type d_reduced: any type that can be cast to a L{Data<escript.Data>}        :type d_reduced: any type that can be cast to a `Data`
2712                         object on L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `ReducedFunctionOnBoundary`
2713        @keyword y: value for coefficient C{y}        :keyword y: value for coefficient ``y``
2714        @type y: any type that can be cast to a L{Data<escript.Data>} object on        :type y: any type that can be cast to a `Data` object on
2715                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
2716        @keyword d_contact: value for coefficient C{d_contact}        :keyword d_contact: value for coefficient ``d_contact``
2717        @type d_contact: any type that can be cast to a L{Data<escript.Data>}        :type d_contact: any type that can be cast to a `Data`
2718                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>}                         object on `FunctionOnContactOne`
2719                         or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         or `FunctionOnContactZero`
2720        @keyword d_contact_reduced: value for coefficient C{d_contact_reduced}        :keyword d_contact_reduced: value for coefficient ``d_contact_reduced``
2721        @type d_contact_reduced: any type that can be cast to a L{Data<escript.Data>}        :type d_contact_reduced: any type that can be cast to a `Data`
2722                                 object on L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}                                 object on `ReducedFunctionOnContactOne`
2723                                 or L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>}                                 or `ReducedFunctionOnContactZero`
2724        @keyword y_contact: value for coefficient C{y_contact}        :keyword y_contact: value for coefficient ``y_contact``
2725        @type y_contact: any type that can be cast to a L{Data<escript.Data>}        :type y_contact: any type that can be cast to a `Data`
2726                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>}                         object on `FunctionOnContactOne`
2727                         or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         or `FunctionOnContactZero`
2728        @keyword y_contact_reduced: value for coefficient C{y_contact_reduced}        :keyword y_contact_reduced: value for coefficient ``y_contact_reduced``
2729        @type y_contact_reduced: any type that can be cast to a L{Data<escript.Data>}        :type y_contact_reduced: any type that can be cast to a `Data`
2730                                 object on L{ReducedFunctionOnContactOne<escript.FunctionOnContactOne>}                                 object on `ReducedFunctionOnContactOne`
2731                                 or L{ReducedFunctionOnContactZero<escript.FunctionOnContactZero>}                                 or `ReducedFunctionOnContactZero`
2732        @keyword r: values prescribed to the solution at the locations of        :keyword r: values prescribed to the solution at the locations of
2733                    constraints                    constraints
2734        @type r: any type that can be cast to a L{Data<escript.Data>} object on        :type r: any type that can be cast to a `Data` object on
2735                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
2736                 depending on whether reduced order is used for the solution                 depending on whether reduced order is used for the solution
2737        @keyword q: mask for location of constraints        :keyword q: mask for location of constraints
2738        @type q: any type that can be cast to a L{Data<escript.Data>} object on        :type q: any type that can be cast to a `Data` object on
2739                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
2740                 depending on whether reduced order is used for the                 depending on whether reduced order is used for the
2741                 representation of the equation                 representation of the equation
2742        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
2743        """        """
2744        super(LinearPDE,self).setValue(**coefficients)        super(LinearPDE,self).setValue(**coefficients)
2745        # check if the systrem is inhomogeneous:        # check if the systrem is inhomogeneous:
# Line 2735  class LinearPDE(LinearProblem): Line 2756  class LinearPDE(LinearProblem):
2756       """       """
2757       Returns the residual of u or the current solution if u is not present.       Returns the residual of u or the current solution if u is not present.
2758    
2759       @param u: argument in the residual calculation. It must be representable       :param u: argument in the residual calculation. It must be representable
2760                 in L{self.getFunctionSpaceForSolution()}. If u is not present                 in `self.getFunctionSpaceForSolution()`. If u is not present
2761                 or equals C{None} the current solution is used.                 or equals ``None`` the current solution is used.
2762       @type u: L{Data<escript.Data>} or None       :type u: `Data` or None
2763       @return: residual of u       :return: residual of u
2764       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2765       """       """
2766       if u==None:       if u==None:
2767          return self.getOperator()*self.getSolution()-self.getRightHandSide()          return self.getOperator()*self.getSolution()-self.getRightHandSide()
# Line 2749  class LinearPDE(LinearProblem): Line 2770  class LinearPDE(LinearProblem):
2770    
2771     def getFlux(self,u=None):     def getFlux(self,u=None):
2772       """       """
2773       Returns the flux M{J} for a given M{u}.       Returns the flux *J* for a given *u*.
2774    
2775       M{J[i,j]=(A[i,j,k,l]+A_reduced[A[i,j,k,l]]*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])u[k]-X[i,j]-X_reduced[i,j]}       *J[i,j]=(A[i,j,k,l]+A_reduced[A[i,j,k,l]]*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])u[k]-X[i,j]-X_reduced[i,j]*
2776    
2777       or       or
2778    
2779       M{J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[l]+(B[j]+B_reduced[j])u-X[j]-X_reduced[j]}       *J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[l]+(B[j]+B_reduced[j])u-X[j]-X_reduced[j]*
2780    
2781       @param u: argument in the flux. If u is not present or equals L{None} the       :param u: argument in the flux. If u is not present or equals `None` the
2782                 current solution is used.                 current solution is used.
2783       @type u: L{Data<escript.Data>} or None       :type u: `Data` or None
2784       @return: flux       :return: flux
2785       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2786       """       """
2787       if u==None: u=self.getSolution()       if u==None: u=self.getSolution()
2788       return util.tensormult(self.getCoefficient("A"),util.grad(u,Funtion(self.getDomain))) \       return util.tensormult(self.getCoefficient("A"),util.grad(u,Funtion(self.getDomain))) \
# Line 2775  class LinearPDE(LinearProblem): Line 2796  class LinearPDE(LinearProblem):
2796  class Poisson(LinearPDE):  class Poisson(LinearPDE):
2797     """     """
2798     Class to define a Poisson equation problem. This is generally a     Class to define a Poisson equation problem. This is generally a
2799     L{LinearPDE} of the form     `LinearPDE` of the form
2800    
2801     M{-grad(grad(u)[j])[j] = f}     *-grad(grad(u)[j])[j] = f*
2802    
2803     with natural boundary conditions     with natural boundary conditions
2804    
2805     M{n[j]*grad(u)[j] = 0 }     *n[j]*grad(u)[j] = 0*
2806    
2807     and constraints:     and constraints:
2808    
2809     M{u=0} where M{q>0}     *u=0* where *q>0*
2810    
2811     """     """
2812    
# Line 2793  class Poisson(LinearPDE): Line 2814  class Poisson(LinearPDE):
2814       """       """
2815       Initializes a new Poisson equation.       Initializes a new Poisson equation.
2816    
2817       @param domain: domain of the PDE       :param domain: domain of the PDE
2818       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2819       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2820    
2821       """       """
2822       super(Poisson, self).__init__(domain,1,1,debug)       super(Poisson, self).__init__(domain,1,1,debug)
# Line 2808  class Poisson(LinearPDE): Line 2829  class Poisson(LinearPDE):
2829       """       """
2830       Sets new values to coefficients.       Sets new values to coefficients.
2831    
2832       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
2833       @keyword f: value for right hand side M{f}       :keyword f: value for right hand side *f*
2834       @type f: any type that can be cast to a L{Scalar<escript.Scalar>} object       :type f: any type that can be cast to a `Scalar` object
2835                on L{Function<escript.Function>}                on `Function`
2836       @keyword q: mask for location of constraints       :keyword q: mask for location of constraints
2837       @type q: any type that can be cast to a rank zero L{Data<escript.Data>}       :type q: any type that can be cast to a rank zero `Data`
2838                object on L{Solution<escript.Solution>} or                object on `Solution` or
2839                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2840                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2841       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
2842       """       """
2843       super(Poisson, self).setValue(**coefficients)       super(Poisson, self).setValue(**coefficients)
2844    
2845    
2846     def getCoefficient(self,name):     def getCoefficient(self,name):
2847       """       """
2848       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
2849    
2850       @param name: name of the coefficient requested       :param name: name of the coefficient requested
2851       @type name: C{string}       :type name: ``string``
2852       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
2853       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2854       @raise IllegalCoefficient: invalid coefficient name       :raise IllegalCoefficient: invalid coefficient name
2855       @note: This method is called by the assembling routine to map the Poisson       :note: This method is called by the assembling routine to map the Poisson
2856              equation onto the general PDE.              equation onto the general PDE.
2857       """       """
2858       if name == "A" :       if name == "A" :
# Line 2846  class Poisson(LinearPDE): Line 2867  class Poisson(LinearPDE):
2867  class Helmholtz(LinearPDE):  class Helmholtz(LinearPDE):
2868     """     """
2869     Class to define a Helmholtz equation problem. This is generally a     Class to define a Helmholtz equation problem. This is generally a
2870     L{LinearPDE} of the form     `LinearPDE` of the form
2871    
2872     M{S{omega}*u - grad(k*grad(u)[j])[j] = f}     *omega*u - grad(k*grad(u)[j])[j] = f*
2873    
2874     with natural boundary conditions     with natural boundary conditions
2875    
2876     M{k*n[j]*grad(u)[j] = g- S{alpha}u }     *k*n[j]*grad(u)[j] = g- alphau*
2877    
2878     and constraints:     and constraints:
2879    
2880     M{u=r} where M{q>0}     *u=r* where *q>0*
2881    
2882     """     """
2883    
# Line 2864  class Helmholtz(LinearPDE): Line 2885  class Helmholtz(LinearPDE):
2885       """       """
2886       Initializes a new Helmholtz equation.       Initializes a new Helmholtz equation.
2887    
2888       @param domain: domain of the PDE       :param domain: domain of the PDE
2889       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2890       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2891    
2892       """       """
2893       super(Helmholtz, self).__init__(domain,1,1,debug)       super(Helmholtz, self).__init__(domain,1,1,debug)
# Line 2884  class Helmholtz(LinearPDE): Line 2905  class Helmholtz(LinearPDE):
2905       """       """
2906       Sets new values to coefficients.       Sets new values to coefficients.
2907    
2908       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
2909       @keyword omega: value for coefficient M{S{omega}}       :keyword omega: value for coefficient *omega*
2910       @type omega: any type that can be cast to a L{Scalar<escript.Scalar>}       :type omega: any type that can be cast to a `Scalar`
2911                    object on L{Function<escript.Function>}                    object on `Function`
2912       @keyword k: value for coefficient M{k}       :keyword k: value for coefficient *k*
2913       @type k: any type that can be cast to a L{Scalar<escript.Scalar>} object       :type k: any type that can be cast to a `Scalar` object
2914                on L{Function<escript.Function>}                on `Function`
2915       @keyword f: value for right hand side M{f}       :keyword f: value for right hand side *f*
2916       @type f: any type that can be cast to a L{Scalar<escript.Scalar>} object       :type f: any type that can be cast to a `Scalar` object
2917                on L{Function<escript.Function>}                on `Function`
2918       @keyword alpha: value for right hand side M{S{alpha}}       :keyword alpha: value for right hand side *alpha*
2919       @type alpha: any type that can be cast to a L{Scalar<escript.Scalar>}       :type alpha: any type that can be cast to a `Scalar`
2920                    object on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                    object on `FunctionOnBoundary`
2921       @keyword g: value for right hand side M{g}       :keyword g: value for right hand side *g*
2922       @type g: any type that can be cast to a L{Scalar<escript.Scalar>} object       :type g: any type that can be cast to a `Scalar` object
2923                on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                on `FunctionOnBoundary`
2924       @keyword r: prescribed values M{r} for the solution in constraints       :keyword r: prescribed values *r* for the solution in constraints
2925       @type r: any type that can be cast to a L{Scalar<escript.Scalar>} object       :type r: any type that can be cast to a `Scalar` object
2926                on L{Solution<escript.Solution>} or                on `Solution` or
2927                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2928                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2929       @keyword q: mask for the location of constraints       :keyword q: mask for the location of constraints
2930       @type q: any type that can be cast to a L{Scalar<escript.Scalar>} object       :type q: any type that can be cast to a `Scalar` object
2931                on L{Solution<escript.Solution>} or                on `Solution` or
2932                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2933                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2934       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
2935       """       """
2936       super(Helmholtz, self).setValue(**coefficients)       super(Helmholtz, self).setValue(**coefficients)
2937    
2938     def getCoefficient(self,name):     def getCoefficient(self,name):
2939       """       """
2940       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
2941    
2942       @param name: name of the coefficient requested       :param name: name of the coefficient requested
2943       @type name: C{string}       :type name: ``string``
2944       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
2945       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2946       @raise IllegalCoefficient: invalid name       :raise IllegalCoefficient: invalid name
2947       """       """
2948       if name == "A" :       if name == "A" :
2949           if self.getCoefficient("k").isEmpty():           if self.getCoefficient("k").isEmpty():
# Line 2948  class LameEquation(LinearPDE): Line 2969  class LameEquation(LinearPDE):
2969     """     """
2970     Class to define a Lame equation problem. This problem is defined as:     Class to define a Lame equation problem. This problem is defined as:
2971    
2972     M{-grad(S{mu}*(grad(u[i])[j]+grad(u[j])[i]))[j] - grad(S{lambda}*grad(u[k])[k])[j] = F_i -grad(S{sigma}[ij])[j] }     *-grad(mu*(grad(u[i])[j]+grad(u[j])[i]))[j] - grad(lambda*grad(u[k])[k])[j] = F_i -grad(sigma[ij])[j]*
2973    
2974     with natural boundary conditions:     with natural boundary conditions:
2975    
2976     M{n[j]*(S{mu}*(grad(u[i])[j]+grad(u[j])[i]) + S{lambda}*grad(u[k])[k]) = f_i +n[j]*S{sigma}[ij] }     *n[j]*(mu*(grad(u[i])[j]+grad(u[j])[i]) + lambda*grad(u[k])[k]) = f_i +n[j]*sigma[ij]*
2977    
2978     and constraints:     and constraints:
2979    
2980     M{u[i]=r[i]} where M{q[i]>0}     *u[i]=r[i]* where *q[i]>0*
2981    
2982     """     """
2983    
# Line 2964  class LameEquation(LinearPDE): Line 2985  class LameEquation(LinearPDE):
2985        """        """
2986        Initializes a new Lame equation.        Initializes a new Lame equation.
2987    
2988        @param domain: domain of the PDE        :param domain: domain of the PDE
2989        @type domain: L{Domain<escript.Domain>}        :type domain: `Domain`
2990        @param debug: if True debug information is printed        :param debug: if True debug information is printed
2991    
2992        """        """
2993        super(LameEquation, self).__init__(domain,\        super(LameEquation, self).__init__(domain,\
# Line 2982  class LameEquation(LinearPDE): Line 3003  class LameEquation(LinearPDE):
3003       """       """
3004       Sets new values to coefficients.       Sets new values to coefficients.
3005    
3006       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
3007       @keyword lame_mu: value for coefficient M{S{mu}}       :keyword lame_mu: value for coefficient *mu*
3008       @type lame_mu: any type that can be cast to a L{Scalar<escript.Scalar>}       :type lame_mu: any type that can be cast to a `Scalar`
3009                      object on L{Function<escript.Function>}                      object on `Function`
3010       @keyword lame_lambda: value for coefficient M{S{lambda}}       :keyword lame_lambda: value for coefficient *lambda*
3011       @type lame_lambda: any type that can be cast to a L{Scalar<escript.Scalar>}       :type lame_lambda: any type that can be cast to a `Scalar`
3012                          object on L{Function<escript.Function>}                          object on `Function`
3013       @keyword F: value for internal force M{F}       :keyword F: value for internal force *F*
3014       @type F: any type that can be cast to a L{Vector<escript.Vector>} object       :type F: any type that can be cast to a `Vector` object
3015                on L{Function<escript.Function>}                on `Function`
3016       @keyword sigma: value for initial stress M{S{sigma}}       :keyword sigma: value for initial stress *sigma*
3017       @type sigma: any type that can be cast to a L{Tensor<escript.Tensor>}       :type sigma: any type that can be cast to a `Tensor`
3018                    object on L{Function<escript.Function>}                    object on `Function`
3019       @keyword f: value for external force M{f}       :keyword f: value for external force *f*
3020       @type f: any type that can be cast to a L{Vector<escript.Vector>} object       :type f: any type that can be cast to a `Vector` object
3021                on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                on `FunctionOnBoundary`
3022       @keyword r: prescribed values M{r} for the solution in constraints       :keyword r: prescribed values *r* for the solution in constraints
3023       @type r: any type that can be cast to a L{Vector<escript.Vector>} object       :type r: any type that can be cast to a `Vector` object
3024                on L{Solution<escript.Solution>} or                on `Solution` or
3025                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
3026                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
3027       @keyword q: mask for the location of constraints       :keyword q: mask for the location of constraints
3028       @type q: any type that can be cast to a L{Vector<escript.Vector>} object       :type q: any type that can be cast to a `Vector` object
3029                on L{Solution<escript.Solution>} or                on `Solution` or
3030                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
3031                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
3032       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
3033       """       """
3034       super(LameEquation, self).setValues(**coefficients)       super(LameEquation, self).setValues(**coefficients)
3035    
3036     def getCoefficient(self,name):     def getCoefficient(self,name):
3037       """       """
3038       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
3039    
3040       @param name: name of the coefficient requested       :param name: name of the coefficient requested
3041       @type name: C{string}       :type name: ``string``
3042       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
3043       @rtype: L{Data<escript.Data>}       :rtype: `Data`
3044       @raise IllegalCoefficient: invalid coefficient name       :raise IllegalCoefficient: invalid coefficient name
3045       """       """
3046       out =self.createCoefficient("A")       out =self.createCoefficient("A")
3047       if name == "A" :       if name == "A" :
# Line 3057  def LinearSinglePDE(domain,debug=False): Line 3078  def LinearSinglePDE(domain,debug=False):
3078     """     """
3079     Defines a single linear PDE.     Defines a single linear PDE.
3080    
3081     @param domain: domain of the PDE     :param domain: domain of the PDE
3082     @type domain: L{Domain<escript.Domain>}     :type domain: `Domain`
3083     @param debug: if True debug information is printed     :param debug: if True debug information is printed
3084     @rtype: L{LinearPDE}     :rtype: `LinearPDE`
3085     """     """
3086     return LinearPDE(domain,numEquations=1,numSolutions=1,debug=debug)     return LinearPDE(domain,numEquations=1,numSolutions=1,debug=debug)
3087    
# Line 3068  def LinearPDESystem(domain,debug=False): Line 3089  def LinearPDESystem(domain,debug=False):
3089     """     """
3090     Defines a system of linear PDEs.     Defines a system of linear PDEs.
3091    
3092     @param domain: domain of the PDEs     :param domain: domain of the PDEs
3093     @type domain: L{Domain<escript.Domain>}     :type domain: `Domain`
3094     @param debug: if True debug information is printed     :param debug: if True debug information is printed
3095     @rtype: L{LinearPDE}     :rtype: `LinearPDE`
3096     """     """
3097     return LinearPDE(domain,numEquations=domain.getDim(),numSolutions=domain.getDim(),debug=debug)     return LinearPDE(domain,numEquations=domain.getDim(),numSolutions=domain.getDim(),debug=debug)
3098    
# Line 3080  class TransportPDE(LinearProblem): Line 3101  class TransportPDE(LinearProblem):
3101     """     """
3102     This class is used to define a transport problem given by a general linear,     This class is used to define a transport problem given by a general linear,
3103     time dependent, second order PDE for an unknown, non-negative,     time dependent, second order PDE for an unknown, non-negative,
3104     time-dependent function M{u} on a given domain defined through a     time-dependent function *u* on a given domain defined through a
3105     L{Domain<escript.Domain>} object.     `Domain` object.
3106    
3107     For a single equation with a solution with a single component the transport     For a single equation with a solution with a single component the transport
3108     problem is defined in the following form:     problem is defined in the following form:
3109    
3110     M{(M+M_reduced)*u_t=-(grad(A[j,l]+A_reduced[j,l])*grad(u)[l]+(B[j]+B_reduced[j])u)[j]+(C[l]+C_reduced[l])*grad(u)[l]+(D+D_reduced)-grad(X+X_reduced)[j,j]+(Y+Y_reduced)}     *(M+M_reduced)*u_t=-(grad(A[j,l]+A_reduced[j,l]) * grad(u)[l]+(B[j]+B_reduced[j])u)[j]+(C[l]+C_reduced[l])*grad(u)[l]+(D+D_reduced)-grad(X+X_reduced)[j,j]+(Y+Y_reduced)*
3111    
3112     where M{u_t} denotes the time derivative of M{u} and M{grad(F)} denotes the     where *u_t* denotes the time derivative of *u* and *grad(F)* denotes the
3113     spatial derivative of M{F}. Einstein's summation convention,  ie. summation     spatial derivative of *F*. Einstein's summation convention,  ie. summation
3114     over indexes appearing twice in a term of a sum performed, is used.     over indexes appearing twice in a term of a sum performed, is used.
3115     The coefficients M{M}, M{A}, M{B}, M{C}, M{D}, M{X} and M{Y} have to be     The coefficients *M*, *A*, *B*, *C*, *D*, *X* and *Y* have to be
3116     specified through L{Data<escript.Data>} objects in L{Function<escript.Function>}     specified through `Data` objects in `Function`
3117     and the coefficients M{M_reduced}, M{A_reduced}, M{B_reduced}, M{C_reduced},     and the coefficients *M_reduced*, *A_reduced*, *B_reduced*, *C_reduced*,
3118     M{D_reduced}, M{X_reduced} and M{Y_reduced} have to be specified through     *D_reduced*, *X_reduced* and *Y_reduced* have to be specified through
3119     L{Data<escript.Data>} objects in L{ReducedFunction<escript.ReducedFunction>}.     `Data` objects in `ReducedFunction`.
3120     It is also allowed to use objects that can be converted into such     It is also allowed to use objects that can be converted into such
3121     L{Data<escript.Data>} objects. M{M} and M{M_reduced} are scalar, M{A} and     `Data` objects. *M* and *M_reduced* are scalar, *A* and
3122     M{A_reduced} are rank two, M{B}, M{C}, M{X}, M{B_reduced}, M{C_reduced} and     *A_reduced* are rank two, *B*, *C*, *X*, *B_reduced*, *C_reduced* and
3123     M{X_reduced} are rank one and M{D}, M{D_reduced}, M{Y} and M{Y_reduced} are     *X_reduced* are rank one and *D*, *D_reduced*, *Y* and *Y_reduced* are
3124     scalar.     scalar.
3125    
3126     The following natural boundary conditions are considered:     The following natural boundary conditions are considered:
3127    
3128     M{n[j]*((A[i,j]+A_reduced[i,j])*grad(u)[l]+(B+B_reduced)[j]*u+X[j]+X_reduced[j])+(d+d_reduced)*u+y+y_reduced=(m+m_reduced)*u_t}     *n[j]*((A[i,j]+A_reduced[i,j])*grad(u)[l]+(B+B_reduced)[j]*u+X[j]+X_reduced[j])+(d+d_reduced)*u+y+y_reduced=(m+m_reduced)*u_t*
3129    
3130     where M{n} is the outer normal field. Notice that the coefficients M{A},     where *n* is the outer normal field. Notice that the coefficients *A*,
3131     M{A_reduced}, M{B}, M{B_reduced}, M{X} and M{X_reduced} are defined in the     *A_reduced*, *B*, *B_reduced*, *X* and *X_reduced* are defined in the
3132     transport problem. The coefficients M{m}, M{d} and M{y} are each a scalar in     transport problem. The coefficients *m*, *d* and *y* are each a scalar in
3133     L{FunctionOnBoundary<escript.FunctionOnBoundary>} and the coefficients     `FunctionOnBoundary` and the coefficients
3134     M{m_reduced}, M{d_reduced} and M{y_reduced} are each a scalar in     *m_reduced*, *d_reduced* and *y_reduced* are each a scalar in
3135     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
3136    
3137     Constraints for the solution prescribing the value of the solution at     Constraints for the solution prescribing the value of the solution at
3138     certain locations in the domain have the form     certain locations in the domain have the form
3139    
3140     M{u_t=r} where M{q>0}     *u_t=r* where *q>0*
3141    
3142     M{r} and M{q} are each scalar where M{q} is the characteristic function     *r* and *q* are each scalar where *q* is the characteristic function
3143     defining where the constraint is applied. The constraints override any other     defining where the constraint is applied. The constraints override any other
3144     condition set by the transport problem or the boundary condition.     condition set by the transport problem or the boundary condition.
3145    
3146     The transport problem is symmetrical if     The transport problem is symmetrical if
3147    
3148     M{A[i,j]=A[j,i]} and M{B[j]=C[j]} and M{A_reduced[i,j]=A_reduced[j,i]} and     *A[i,j]=A[j,i]* and *B[j]=C[j]* and *A_reduced[i,j]=A_reduced[j,i]* and
3149     M{B_reduced[j]=C_reduced[j]}     *B_reduced[j]=C_reduced[j]*
3150    
3151     For a system and a solution with several components the transport problem     For a system and a solution with several components the transport problem
3152     has the form     has the form
3153    
3154     M{(M[i,k]+M_reduced[i,k])*u[k]_t=-grad((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k])[j]+(C[i,k,l]+C_reduced[i,k,l])*grad(u[k])[l]+(D[i,k]+D_reduced[i,k]*u[k]-grad(X[i,j]+X_reduced[i,j])[j]+Y[i]+Y_reduced[i] }     *(M[i,k]+M_reduced[i,k]) * u[k]_t=-grad((A[i,j,k,l]+A_reduced[i,j,k,l]) * grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k]) * u[k])[j]+(C[i,k,l]+C_reduced[i,k,l]) * grad(u[k])[l]+(D[i,k]+D_reduced[i,k] * u[k]-grad(X[i,j]+X_reduced[i,j])[j]+Y[i]+Y_reduced[i]*
3155    
3156     M{A} and M{A_reduced} are of rank four, M{B}, M{B_reduced}, M{C} and     *A* and *A_reduced* are of rank four, *B*, *B_reduced*, *C* and
3157     M{C_reduced} are each of rank three, M{M}, M{M_reduced}, M{D}, M{D_reduced},     *C_reduced* are each of rank three, *M*, *M_reduced*, *D*, *D_reduced*,
3158     M{X_reduced} and M{X} are each of rank two and M{Y} and M{Y_reduced} are of     *X_reduced* and *X* are each of rank two and *Y* and *Y_reduced* are of
3159     rank one. The natural boundary conditions take the form:     rank one. The natural boundary conditions take the form:
3160    
3161     M{n[j]*((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]+X[i,j]+X_reduced[i,j])+(d[i,k]+d_reduced[i,k])*u[k]+y[i]+y_reduced[i]= (m[i,k]+m_reduced[i,k])*u[k]_t}     *n[j]*((A[i,j,k,l]+A_reduced[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]+X[i,j]+X_reduced[i,j])+(d[i,k]+d_reduced[i,k])*u[k]+y[i]+y_reduced[i]= (m[i,k]+m_reduced[i,k])*u[k]_t*
3162    
3163     The coefficient M{d} and M{m} are of rank two and M{y} is of rank one with     The coefficient *d* and *m* are of rank two and *y* is of rank one with
3164     all in L{FunctionOnBoundary<escript.FunctionOnBoundary>}. The coefficients     all in `FunctionOnBoundary`. The coefficients
3165     M{d_reduced} and M{m_reduced} are of rank two and M{y_reduced} is of rank     *d_reduced* and *m_reduced* are of rank two and *y_reduced* is of rank
3166     one all in L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     one all in `ReducedFunctionOnBoundary`.
3167    
3168     Constraints take the form     Constraints take the form
3169    
3170     M{u[i]_t=r[i]} where M{q[i]>0}     *u[i]_t=r[i]* where *q[i]>0*
3171    
3172     M{r} and M{q} are each rank one. Notice that at some locations not     *r* and *q* are each rank one. Notice that at some locations not
3173     necessarily all components must have a constraint.     necessarily all components must have a constraint.
3174    
3175     The transport problem is symmetrical if     The transport problem is symmetrical if
3176    
3177        - M{M[i,k]=M[i,k]}        - *M[i,k]=M[i,k]*
3178        - M{M_reduced[i,k]=M_reduced[i,k]}        - *M_reduced[i,k]=M_reduced[i,k]*
3179        - M{A[i,j,k,l]=A[k,l,i,j]}        - *A[i,j,k,l]=A[k,l,i,j]*
3180        - M{A_reduced[i,j,k,l]=A_reduced[k,l,i,j]}        - *A_reduced[i,j,k,l]=A_reduced[k,l,i,j]*
3181        - M{B[i,j,k]=C[k,i,j]}        - *B[i,j,k]=C[k,i,j]*
3182        - M{B_reduced[i,j,k]=C_reduced[k,i,j]}        - *B_reduced[i,j,k]=C_reduced[k,i,j]*
3183        - M{D[i,k]=D[i,k]}        - *D[i,k]=D[i,k]*
3184        - M{D_reduced[i,k]=D_reduced[i,k]}        - *D_reduced[i,k]=D_reduced[i,k]*
3185        - M{m[i,k]=m[k,i]}        - *m[i,k]=m[k,i]*
3186        - M{m_reduced[i,k]=m_reduced[k,i]}        - *m_reduced[i,k]=m_reduced[k,i]*
3187        - M{d[i,k]=d[k,i]}        - *d[i,k]=d[k,i]*
3188        - M{d_reduced[i,k]=d_reduced[k,i]}        - *d_reduced[i,k]=d_reduced[k,i]*
3189    
3190     L{TransportPDE} also supports solution discontinuities over a contact region     `TransportPDE` also supports solution discontinuities over a contact region
3191     in the domain. To specify the conditions across the discontinuity we are     in the domain. To specify the conditions across the discontinuity we are
3192     using the generalised flux M{J} which, in the case of a system of PDEs and     using the generalised flux *J* which, in the case of a system of PDEs and
3193     several components of the solution, is defined as     several components of the solution, is defined as
3194    
3195     M{J[i,j]=(A[i,j,k,l]+A_reduced[[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]+X[i,j]+X_reduced[i,j]}     *J[i,j]=(A[i,j,k,l]+A_reduced[[i,j,k,l])*grad(u[k])[l]+(B[i,j,k]+B_reduced[i,j,k])*u[k]+X[i,j]+X_reduced[i,j]*
3196    
3197     For the case of single solution component and single PDE M{J} is defined as     For the case of single solution component and single PDE *J* is defined as
3198    
3199     M{J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[j]+(B[i]+B_reduced[i])*u+X[i]+X_reduced[i]}     *J[j]=(A[i,j]+A_reduced[i,j])*grad(u)[j]+(B[i]+B_reduced[i])*u+X[i]+X_reduced[i]*
3200    
3201     In the context of discontinuities M{n} denotes the normal on the     In the context of discontinuities *n* denotes the normal on the
3202     discontinuity pointing from side 0 towards side 1 calculated from     discontinuity pointing from side 0 towards side 1 calculated from
3203     L{getNormal<escript.FunctionSpace.getNormal>} of L{FunctionOnContactZero<escript.FunctionOnContactZero>}.     `FunctionSpace.getNormal` of `FunctionOnContactZero`.
3204     For a system of transport problems the contact condition takes the form     For a system of transport problems the contact condition takes the form
3205    
3206     M{n[j]*J0[i,j]=n[j]*J1[i,j]=(y_contact[i]+y_contact_reduced[i])- (d_contact[i,k]+d_contact_reduced[i,k])*jump(u)[k]}     *n[j]*J0[i,j]=n[j]*J1[i,j]=(y_contact[i]+y_contact_reduced[i])- (d_contact[i,k]+d_contact_reduced[i,k])*jump(u)[k]*
3207    
3208     where M{J0} and M{J1} are the fluxes on side 0 and side 1 of the     where *J0* and *J1* are the fluxes on side 0 and side 1 of the
3209     discontinuity, respectively. M{jump(u)}, which is the difference of the     discontinuity, respectively. *jump(u)*, which is the difference of the
3210     solution at side 1 and at side 0, denotes the jump of M{u} across     solution at side 1 and at side 0, denotes the jump of *u* across
3211     discontinuity along the normal calculated by L{jump<util.jump>}.     discontinuity along the normal calculated by `jump`.
3212     The coefficient M{d_contact} is of rank two and M{y_contact} is of rank one     The coefficient *d_contact* is of rank two and *y_contact* is of rank one
3213     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or L{FunctionOnContactOne<escript.FunctionOnContactOne>}.     both in `FunctionOnContactZero` or `FunctionOnContactOne`.
3214     The coefficient M{d_contact_reduced} is of rank two and M{y_contact_reduced}     The coefficient *d_contact_reduced* is of rank two and *y_contact_reduced*
3215     is of rank one both in L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     is of rank one both in `ReducedFunctionOnContactZero` or `ReducedFunctionOnContactOne`.
3216     In case of a single PDE and a single component solution the contact     In case of a single PDE and a single component solution the contact
3217     condition takes the form     condition takes the form
3218    
3219     M{n[j]*J0_{j}=n[j]*J1_{j}=(y_contact+y_contact_reduced)-(d_contact+y_contact_reduced)*jump(u)}     *n[j]*J0_{j}=n[j]*J1_{j}=(y_contact+y_contact_reduced)-(d_contact+y_contact_reduced)*jump(u)*
3220    
3221     In this case the coefficient M{d_contact} and M{y_contact} are each scalar     In this case the coefficient *d_contact* and *y_contact* are each scalar
3222     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
3223     L{FunctionOnContactOne<escript.FunctionOnContactOne>} and the coefficient     `FunctionOnContactOne` and the coefficient
3224     M{d_contact_reduced} and M{y_contact_reduced} are each scalar both in     *d_contact_reduced* and *y_contact_reduced* are each scalar both in
3225     L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or     `ReducedFunctionOnContactZero` or
3226     L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     `ReducedFunctionOnContactOne`.
3227    
3228     Typical usage::     Typical usage::
3229    
# Line 3219  class TransportPDE(LinearProblem): Line 3240  class TransportPDE(LinearProblem):
3240       """       """
3241       Initializes a transport problem.       Initializes a transport problem.
3242    
3243       @param domain: domain of the PDE       :param domain: domain of the PDE
3244       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
3245       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
3246                            equations is extracted from the coefficients.                            equations is extracted from the coefficients.
3247       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
3248                            of solution components is extracted from the                            of solution components is extracted from the
3249                            coefficients.                            coefficients.
3250       @param debug: if True debug information is printed       :param debug: if True debug information is printed
3251       @param useBackwardEuler: if set the backward Euler scheme is used. Otherwise the Crank-Nicholson scheme is applied. Note that backward Euler scheme will return a safe time step size which is practically infinity as the scheme is unconditional unstable. The Crank-Nicholson scheme provides a higher accuracy but requires to limit the time step size to be stable.       :param useBackwardEuler: if set the backward Euler scheme is used. Otherwise the Crank-Nicholson scheme is applied. Note that backward Euler scheme will return a safe time step size which is practically infinity as the scheme is unconditional unstable. The Crank-Nicholson scheme provides a higher accuracy but requires to limit the time step size to be stable.
3252       @type useBackwardEuler: C{bool}       :type useBackwardEuler: ``bool``
3253       """       """
3254       if useBackwardEuler:       if useBackwardEuler:
3255           self.__useBackwardEuler=True           self.__useBackwardEuler=True
# Line 3272  class TransportPDE(LinearProblem): Line 3293  class TransportPDE(LinearProblem):
3293       """       """
3294       Returns the string representation of the transport problem.       Returns the string representation of the transport problem.
3295    
3296       @return: a simple representation of the transport problem       :return: a simple representation of the transport problem
3297       @rtype: C{str}       :rtype: ``str``
3298       """       """
3299       return "<TransportPDE %d>"%id(self)       return "<TransportPDE %d>"%id(self)
3300    
3301     def useBackwardEuler(self):     def useBackwardEuler(self):
3302        """        """
3303        Returns true if backward Euler is used. Otherwise false is returned.        Returns true if backward Euler is used. Otherwise false is returned.
3304        @rtype: bool        :rtype: bool
3305        """        """
3306        return self.__useBackwardEuler        return self.__useBackwardEuler
3307    
# Line 3289  class TransportPDE(LinearProblem): Line 3310  class TransportPDE(LinearProblem):
3310        """        """
3311        Tests the transport problem for symmetry.        Tests the transport problem for symmetry.
3312    
3313        @param verbose: if set to True or not present a report on coefficients        :param verbose: if set to True or not present a report on coefficients
3314                        which break the symmetry is printed.                        which break the symmetry is printed.
3315        @type verbose: C{bool}        :type verbose: ``bool``
3316        @return:  True if the PDE is symmetric        :return:  True if the PDE is symmetric
3317        @rtype: C{bool}        :rtype: ``bool``
3318        @note: This is a very expensive operation. It should be used for        :note: This is a very expensive operation. It should be used for
3319               degugging only! The symmetry flag is not altered.               degugging only! The symmetry flag is not altered.
3320        """        """
3321        out=True        out=True
# Line 3318  class TransportPDE(LinearProblem): Line 3339  class TransportPDE(LinearProblem):
3339        """        """
3340        Sets new values to coefficients.        Sets new values to coefficients.
3341    
3342        @param coefficients: new values assigned to coefficients        :param coefficients: new values assigned to coefficients
3343        @keyword M: value for coefficient C{M}        :keyword M: value for coefficient ``M``
3344        @type M: any type that can be cast to a L{Data<escript.Data>} object on        :type M: any type that can be cast to a `Data` object on
3345                 L{Function<escript.Function>}                 `Function`
3346        @keyword M_reduced: value for coefficient C{M_reduced}        :keyword M_reduced: value for coefficient ``M_reduced``
3347        @type M_reduced: any type that can be cast to a L{Data<escript.Data>}        :type M_reduced: any type that can be cast to a `Data`
3348                         object on L{Function<escript.ReducedFunction>}                         object on `Function`
3349        @keyword A: value for coefficient C{A}        :keyword A: value for coefficient ``A``
3350        @type A: any type that can be cast to a L{Data<escript.Data>} object on        :type A: any type that can be cast to a `Data` object on
3351                 L{Function<escript.Function>}                 `Function`
3352        @keyword A_reduced: value for coefficient C{A_reduced}        :keyword A_reduced: value for coefficient ``A_reduced``
3353        @type A_reduced: any type that can be cast to a L{Data<escript.Data>}        :type A_reduced: any type that can be cast to a `Data`
3354                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3355        @keyword B: value for coefficient C{B}        :keyword B: value for coefficient ``B``
3356        @type B: any type that can be cast to a L{Data<escript.Data>} object on        :type B: any type that can be cast to a `Data` object on
3357                 L{Function<escript.Function>}                 `Function`
3358        @keyword B_reduced: value for coefficient C{B_reduced}        :keyword B_reduced: value for coefficient ``B_reduced``
3359        @type B_reduced: any type that can be cast to a L{Data<escript.Data>}        :type B_reduced: any type that can be cast to a `Data`
3360                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3361        @keyword C: value for coefficient C{C}        :keyword C: value for coefficient ``C``
3362        @type C: any type that can be cast to a L{Data<escript.Data>} object on        :type C: any type that can be cast to a `Data` object on
3363                 L{Function<escript.Function>}                 `Function`
3364        @keyword C_reduced: value for coefficient C{C_reduced}        :keyword C_reduced: value for coefficient ``C_reduced``
3365        @type C_reduced: any type that can be cast to a L{Data<escript.Data>}        :type C_reduced: any type that can be cast to a `Data`
3366                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3367        @keyword D: value for coefficient C{D}        :keyword D: value for coefficient ``D``
3368        @type D: any type that can be cast to a L{Data<escript.Data>} object on        :type D: any type that can be cast to a `Data` object on
3369                 L{Function<escript.Function>}                 `Function`
3370        @keyword D_reduced: value for coefficient C{D_reduced}        :keyword D_reduced: value for coefficient ``D_reduced``
3371        @type D_reduced: any type that can be cast to a L{Data<escript.Data>}        :type D_reduced: any type that can be cast to a `Data`
3372                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3373        @keyword X: value for coefficient C{X}        :keyword X: value for coefficient ``X``
3374        @type X: any type that can be cast to a L{Data<escript.Data>} object on        :type X: any type that can be cast to a `Data` object on
3375                 L{Function<escript.Function>}                 `Function`
3376        @keyword X_reduced: value for coefficient C{X_reduced}        :keyword X_reduced: value for coefficient ``X_reduced``
3377        @type X_reduced: any type that can be cast to a L{Data<escript.Data>}        :type X_reduced: any type that can be cast to a `Data`
3378                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3379        @keyword Y: value for coefficient C{Y}        :keyword Y: value for coefficient ``Y``
3380        @type Y: any type that can be cast to a L{Data<escript.Data>} object on        :type Y: any type that can be cast to a `Data` object on
3381                 L{Function<escript.Function>}                 `Function`
3382        @keyword Y_reduced: value for coefficient C{Y_reduced}        :keyword Y_reduced: value for coefficient ``Y_reduced``
3383        @type Y_reduced: any type that can be cast to a L{Data<escript.Data>}        :type Y_reduced: any type that can be cast to a `Data`
3384                         object on L{ReducedFunction<escript.Function>}                         object on `ReducedFunction`
3385        @keyword m: value for coefficient C{m}        :keyword m: value for coefficient ``m``
3386        @type m: any type that can be cast to a L{Data<escript.Data>} object on        :type m: any type that can be cast to a `Data` object on
3387                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3388        @keyword m_reduced: value for coefficient C{m_reduced}        :keyword m_reduced: value for coefficient ``m_reduced``
3389        @type m_reduced: any type that can be cast to a L{Data<escript.Data>}        :type m_reduced: any type that can be cast to a `Data`
3390                         object on L{FunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `FunctionOnBoundary`
3391        @keyword d: value for coefficient C{d}        :keyword d: value for coefficient ``d``
3392        @type d: any type that can be cast to a L{Data<escript.Data>} object on        :type d: any type that can be cast to a `Data` object on
3393                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3394        @keyword d_reduced: value for coefficient C{d_reduced}        :keyword d_reduced: value for coefficient ``d_reduced``
3395        @type d_reduced: any type that can be cast to a L{Data<escript.Data>}        :type d_reduced: any type that can be cast to a `Data`
3396                         object on L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `ReducedFunctionOnBoundary`
3397        @keyword y: value for coefficient C{y}        :keyword y: value for coefficient ``y``
3398        @type y: any type that can be cast to a L{Data<escript.Data>} object on        :type y: any type that can be cast to a `Data` object on
3399                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3400        @keyword d_contact: value for coefficient C{d_contact}        :keyword d_contact: value for coefficient ``d_contact``
3401        @type d_contact: any type that can be cast to a L{Data<escript.Data>}        :type d_contact: any type that can be cast to a `Data`
3402                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>} or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         object on `FunctionOnContactOne` or `FunctionOnContactZero`
3403        @keyword d_contact_reduced: value for coefficient C{d_contact_reduced}        :keyword d_contact_reduced: value for coefficient ``d_contact_reduced``
3404        @type d_contact_reduced: any type that can be cast to a L{Data<escript.Data>} object on L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>} or L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>}        :type d_contact_reduced: any type that can be cast to a `Data` object on `ReducedFunctionOnContactOne` or `ReducedFunctionOnContactZero`
3405        @keyword y_contact: value for coefficient C{y_contact}        :keyword y_contact: value for coefficient ``y_contact``
3406        @type y_contact: any type that can be cast to a L{Data<escript.Data>}        :type y_contact: any type that can be cast to a `Data`
3407                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>} or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         object on `FunctionOnContactOne` or `FunctionOnContactZero`
3408        @keyword y_contact_reduced: value for coefficient C{y_contact_reduced}        :keyword y_contact_reduced: value for coefficient ``y_contact_reduced``
3409        @type y_contact_reduced: any type that can be cast to a L{Data<escript.Data>} object on L{ReducedFunctionOnContactOne<escript.FunctionOnContactOne>} or L{ReducedFunctionOnContactZero<escript.FunctionOnContactZero>}        :type y_contact_reduced: any type that can be cast to a `Data` object on `ReducedFunctionOnContactOne` or `ReducedFunctionOnContactZero`
3410        @keyword r: values prescribed to the solution at the locations of constraints        :keyword r: values prescribed to the solution at the locations of constraints
3411        @type r: any type that can be cast to a L{Data<escript.Data>} object on        :type r: any type that can be cast to a `Data` object on
3412                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
3413                 depending on whether reduced order is used for the solution                 depending on whether reduced order is used for the solution
3414        @keyword q: mask for the location of constraints        :keyword q: mask for the location of constraints
3415        @type q: any type that can be cast to a L{Data<escript.Data>} object on        :type q: any type that can be cast to a `Data` object on
3416                 L{Solution<escript.Solution>} or                 `Solution` or
3417                 L{ReducedSolution<escript.ReducedSolution>} depending on whether                 `ReducedSolution` depending on whether
3418                 reduced order is used for the representation of the equation                 reduced order is used for the representation of the equation
3419        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
3420        """        """
3421        super(TransportPDE,self).setValue(**coefficients)        super(TransportPDE,self).setValue(**coefficients)
3422    
# Line 3419  class TransportPDE(LinearProblem): Line 3440  class TransportPDE(LinearProblem):
3440         """         """
3441         Sets the initial solution.         Sets the initial solution.
3442    
3443         @param u: new initial solution         :param u: new initial solution
3444         @type u: any object that can be interpolated to a L{Data<escript.Data>}         :type u: any object that can be interpolated to a `Data`
3445                  object on L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                  object on `Solution` or `ReducedSolution`
3446         @note: C{u} must be non-negative         :note: ``u`` must be non-negative
3447         """         """
3448         u2=util.interpolate(u,self.getFunctionSpaceForSolution())         u2=util.interpolate(u,self.getFunctionSpaceForSolution())
3449         if self.getNumSolutions() == 1:         if self.getNumSolutions() == 1:
# Line 3437  class TransportPDE(LinearProblem): Line 3458  class TransportPDE(LinearProblem):
3458        """        """
3459        Returns the system type which needs to be used by the current set up.        Returns the system type which needs to be used by the current set up.
3460    
3461        @return: a code to indicate the type of transport problem scheme used        :return: a code to indicate the type of transport problem scheme used
3462        @rtype: C{float}        :rtype: ``float``
3463        """        """
3464        solver_options=self.getSolverOptions()        solver_options=self.getSolverOptions()
3465        return self.getDomain().getTransportTypeId(solver_options.getSolverMethod(), solver_options.getPreconditioner(),solver_options.getPackage(), solver_options.isSymmetric())        return self.getDomain().getTransportTypeId(solver_options.getSolverMethod(), solver_options.getPreconditioner(),solver_options.getPackage(), solver_options.isSymmetric())
3466    
3467     def getUnlimitedTimeStepSize(self):     def getUnlimitedTimeStepSize(self):
3468        """        """
3469        Returns the value returned by the C{getSafeTimeStepSize} method to        Returns the value returned by the ``getSafeTimeStepSize`` method to
3470        indicate no limit on the safe time step size.        indicate no limit on the safe time step size.
3471    
3472         @return: the value used to indicate that no limit is set to the time         :return: the value used to indicate that no limit is set to the time
3473                  step size                  step size
3474         @rtype: C{float}         :rtype: ``float``
3475         @note: Typically the biggest positive float is returned         :note: Typically the biggest positive float is returned
3476        """        """
3477        return self.getOperator().getUnlimitedTimeStepSize()        return self.getOperator().getUnlimitedTimeStepSize()
3478    
# Line 3459  class TransportPDE(LinearProblem): Line 3480  class TransportPDE(LinearProblem):
3480         """         """
3481         Returns a safe time step size to do the next time step.         Returns a safe time step size to do the next time step.
3482    
3483         @return: safe time step size         :return: safe time step size
3484         @rtype: C{float}         :rtype: ``float``
3485         @note: If not C{getSafeTimeStepSize()} < C{getUnlimitedTimeStepSize()}         :note: If not ``getSafeTimeStepSize()`` < ``getUnlimitedTimeStepSize()``
3486                any time step size can be used.                any time step size can be used.
3487         """         """
3488         return self.getOperator().getSafeTimeStepSize()         return self.getOperator().getSafeTimeStepSize()
# Line 3470  class TransportPDE(LinearProblem): Line 3491  class TransportPDE(LinearProblem):
3491         """         """
3492         Sets the weighting factor used to insert the constraints into the problem         Sets the weighting factor used to insert the constraints into the problem
3493    
3494         @param value: value for the weighting factor         :param value: value for the weighting factor
3495         @type value: large positive C{float}         :type value: large positive ``float``
3496         """         """
3497         if not value>0:         if not value>0:
3498           raise ValueError,"weighting factor needs to be positive."           raise ValueError,"weighting factor needs to be positive."
# Line 3481  class TransportPDE(LinearProblem): Line 3502  class TransportPDE(LinearProblem):
3502     def getConstraintWeightingFactor(self):     def getConstraintWeightingFactor(self):
3503         """         """
3504         returns the weighting factor used to insert the constraints into the problem         returns the weighting factor used to insert the constraints into the problem
3505         @return: value for the weighting factor         :return: value for the weighting factor
3506         @rtype: C{float}         :rtype: ``float``
3507         """         """
3508         return self.__constraint_factor         return self.__constraint_factor
3509     #====================================================================     #====================================================================
# Line 3490  class TransportPDE(LinearProblem): Line 3511  class TransportPDE(LinearProblem):
3511         """         """
3512         Returns the solution of the problem.         Returns the solution of the problem.
3513    
3514         @return: the solution         :return: the solution
3515         @rtype: L{Data<escript.Data>}         :rtype: `Data`
3516         """         """
3517         option_class=self.getSolverOptions()         option_class=self.getSolverOptions()
3518         if dt<=0:         if dt<=0:
# Line 3504  class TransportPDE(LinearProblem): Line 3525  class TransportPDE(LinearProblem):
3525         """         """
3526         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
3527    
3528         @return: the discrete version of the PDE         :return: the discrete version of the PDE
3529         @rtype: C{tuple} of L{Operator,<escript.Operator>} and         :rtype: ``tuple`` of `Operator` and
3530                 L{Data<escript.Data>}                 `Data`
3531    
3532         """         """
3533         if not self.isOperatorValid() or not self.isRightHandSideValid():         if not self.isOperatorValid() or not self.isRightHandSideValid():
# Line 3552  class TransportPDE(LinearProblem): Line 3573  class TransportPDE(LinearProblem):
3573    
3574     def setDebug(self, flag):     def setDebug(self, flag):
3575       """       """
3576       Switches debug output on if C{flag} is True,       Switches debug output on if ``flag`` is True,
3577       otherwise it is switched off.       otherwise it is switched off.
3578    
3579       @param flag: desired debug status       :param flag: desired debug status
3580       @type flag: C{bool}       :type flag: ``bool``
3581       """       """
3582       if flag:       if flag:
3583           self.setDebugOn()           self.setDebugOn()

Legend:
Removed from v.2549  
changed lines
  Added in v.2816

  ViewVC Help
Powered by ViewVC 1.1.26