/[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 2760 by artak, Thu Nov 19 05:22:45 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: 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: AMLI coarsening method by Ruge and Stueben
98      @cvar NO_PRECONDITIONER: no preconditioner is applied.      :cvar AGGREGATION_COARSENING: AMLI coarsening using (symmetric) aggregation
99        :cvar MIN_COARSE_MATRIX_SIZE: minimum size of the coarsest level matrix to use direct solver.
100        :cvar NO_PRECONDITIONER: no preconditioner is applied.
101      """      """
102      DEFAULT= 0      DEFAULT= 0
103      DIRECT= 1      DIRECT= 1
# Line 134  class SolverOptions(object): Line 136  class SolverOptions(object):
136      AGGREGATION_COARSENING=35      AGGREGATION_COARSENING=35
137      NO_PRECONDITIONER=36      NO_PRECONDITIONER=36
138      MIN_COARSE_MATRIX_SIZE=37      MIN_COARSE_MATRIX_SIZE=37
139            AMLI=38    
140    
141      def __init__(self):      def __init__(self):
142          self.setLevelMax()          self.setLevelMax()
143          self.setCoarseningThreshold()          self.setCoarseningThreshold()
# Line 196  class SolverOptions(object): Line 199  class SolverOptions(object):
199                  out+="\nCoarsening threshold = %e"%self.getMinCoarseMatrixSize()                  out+="\nCoarsening threshold = %e"%self.getMinCoarseMatrixSize()
200                  out+="\nMinimum size of the coarsest level matrix = %e"%self.getCoarseningThreshold()                  out+="\nMinimum size of the coarsest level matrix = %e"%self.getCoarseningThreshold()
201                  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())
202              if self.getPreconditioner() == self.GAUSS_SEIDEL:              if self.getPreconditioner() == self.AMLI:
203                    out+="\nMaximum number of levels = %s"%self.LevelMax()
204                    out+="\nCoarsening method = %s"%self.getName(self.getCoarsening())
205                    out+="\nCoarsening threshold = %e"%self.getMinCoarseMatrixSize()
206                    out+="\nMinimum size of the coarsest level matrix = %e"%self.getCoarseningThreshold()
207                    out+="\nNumber of pre / post sweeps = %s / %s, %s"%(self.getNumPreSweeps(), self.getNumPostSweeps(), self.getNumSweeps())
208            if self.getPreconditioner() == self.GAUSS_SEIDEL:
209                  out+="\nNumber of sweeps = %s"%self.getNumSweeps()                  out+="\nNumber of sweeps = %s"%self.getNumSweeps()
210              if self.getPreconditioner() == self.ILUT:              if self.getPreconditioner() == self.ILUT:
211                  out+="\nDrop tolerance = %e"%self.getDropTolerance()                  out+="\nDrop tolerance = %e"%self.getDropTolerance()
# Line 209  class SolverOptions(object): Line 218  class SolverOptions(object):
218          """          """
219          returns the name of a given key          returns the name of a given key
220                    
221          @param key: a valid key          :param key: a valid key
222          """          """
223          if key == self.DEFAULT: return "DEFAULT"          if key == self.DEFAULT: return "DEFAULT"
224          if key == self.DIRECT: return "DIRECT"          if key == self.DIRECT: return "DIRECT"
# Line 233  class SolverOptions(object): Line 242  class SolverOptions(object):
242          if key == self.ITERATIVE: return "ITERATIVE"          if key == self.ITERATIVE: return "ITERATIVE"
243          if key == self.PASO: return "PASO"          if key == self.PASO: return "PASO"
244          if key == self.AMG: return "AMG"          if key == self.AMG: return "AMG"
245            if key == self.AMLI: return "AMLI"
246          if key == self.REC_ILU: return "REC_ILU"          if key == self.REC_ILU: return "REC_ILU"
247          if key == self.TRILINOS: return "TRILINOS"          if key == self.TRILINOS: return "TRILINOS"
248          if key == self.NONLINEAR_GMRES: return "NONLINEAR_GMRES"          if key == self.NONLINEAR_GMRES: return "NONLINEAR_GMRES"
# Line 253  class SolverOptions(object): Line 263  class SolverOptions(object):
263          """          """
264          resets the diagnostics          resets the diagnostics
265                    
266          @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.
267          @type all: C{bool}          :type all: ``bool``
268          """          """
269          self.__num_iter=None          self.__num_iter=None
270          self.__num_level=None          self.__num_level=None
271          self.__num_inner_iter=None          self.__num_inner_iter=None
272          self.__time=None          self.__time=None
273          self.__set_up_time=None          self.__set_up_time=None
274            self.__net_time=None
275          self.__residual_norm=None          self.__residual_norm=None
276          self.__converged=None          self.__converged=None
277          if all:          if all:
# Line 268  class SolverOptions(object): Line 279  class SolverOptions(object):
279              self.__cum_num_iter=0              self.__cum_num_iter=0
280              self.__cum_time=0              self.__cum_time=0
281              self.__cum_set_up_time=0              self.__cum_set_up_time=0
282                self.__cum_net_time=0
283    
284      def _updateDiagnostics(self, name, value):      def _updateDiagnostics(self, name, value):
285          """          """
286          Updates diagnostic information          Updates diagnostic information
287                    
288          @param name: name of  diagnostic information          :param name: name of  diagnostic information
289          @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".
290          @param vale: new value of the diagnostic information          :param value: new value of the diagnostic information
291          @note: this function is used by a solver to report diagnostics informations.          :note: this function is used by a solver to report diagnostics informations.
292          """          """
293          if name == "num_iter":          if name == "num_iter":
294              self.__num_iter=int(value)              self.__num_iter=int(value)
295              self.__cum_num_iter+=self.__num_iter              self.__cum_num_iter+=self.__num_iter
296          if name == "num_level":          if name == "num_level":
297              self.__num_iter=int(value)              self.__num_level=int(value)
298          if name == "num_inner_iter":          if name == "num_inner_iter":
299              self.__num_inner_iter=int(value)              self.__num_inner_iter=int(value)
300              self.__cum_num_inner_iter+=self.__num_inner_iter              self.__cum_num_inner_iter+=self.__num_inner_iter
# Line 292  class SolverOptions(object): Line 304  class SolverOptions(object):
304          if name == "set_up_time":          if name == "set_up_time":
305              self.__set_up_time=float(value)              self.__set_up_time=float(value)
306              self.__cum_set_up_time+=self.__set_up_time              self.__cum_set_up_time+=self.__set_up_time
307            if name == "net_time":
308                self.__net_time=float(value)
309                self.__cum_net_time+=self.__net_time
310          if name == "residual_norm":          if name == "residual_norm":
311              self.__residual_norm=float(value)              self.__residual_norm=float(value)
312          if name == "converged":          if name == "converged":
313              self.__converged = (value == True)              self.__converged = (value == True)
314      def getDiagnostics(self, name):      def getDiagnostics(self, name):
315          """          """
316          Returns the diagnostic information C{name}          Returns the diagnostic information ``name``. Possible values are:
317                    
318          @param name: name of diagnostic information where      - "num_iter": the number of iteration steps
         - "num_iter": the number of iteration steps  
319          - "cum_num_iter": the cumulative number of iteration steps          - "cum_num_iter": the cumulative number of iteration steps
320          - "num_level": the number of level in multi level solver          - "num_level": the number of level in multi level solver
321          - "num_inner_iter": the number of inner iteration steps          - "num_inner_iter": the number of inner iteration steps
# Line 310  class SolverOptions(object): Line 324  class SolverOptions(object):
324          - "cum_time": cumulative execution time          - "cum_time": cumulative execution time
325          - "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
326          - "cum_set_up_time": cumulative time to set up of the solver          - "cum_set_up_time": cumulative time to set up of the solver
327            - "net_time": net execution time, excluding setup time for the solver and execution time for preconditioner
328            - "cum_net_time": cumulative net execution time
329          - "residual_norm": norm of the final residual          - "residual_norm": norm of the final residual
330          - "converged": return self.__converged              - "converged": return self.__converged
331          @type name: C{str} in the list "num_iter", "num_level", "num_inner_iter", "time", "set_up_time", "residual_norm", "converged".      
332          @return: requested value. C{None} is returned if the value is undefined.      
333          @note: If the solver has thrown an exception diagnostic values have an undefined status.          
334            :param name: name of diagnostic information to return
335            :type name: ``str`` in the list above.
336            :return: requested value. ``None`` is returned if the value is undefined.
337            :note: If the solver has thrown an exception diagnostic values have an undefined status.
338          """          """
339          if name == "num_iter": return self.__num_iter          if name == "num_iter": return self.__num_iter
340          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 345  class SolverOptions(object):
345          elif name == "cum_time": return self.__cum_time          elif name == "cum_time": return self.__cum_time
346          elif name == "set_up_time": return self.__set_up_time          elif name == "set_up_time": return self.__set_up_time
347          elif name == "cum_set_up_time": return self.__cum_set_up_time          elif name == "cum_set_up_time": return self.__cum_set_up_time
348            elif name == "net_time": return self.__net_time
349            elif name == "cum_net_time": return self.__cum_net_time
350          elif name == "residual_norm": return self.__residual_norm          elif name == "residual_norm": return self.__residual_norm
351          elif name == "converged": return self.__converged                elif name == "converged": return self.__converged      
352          else:          else:
353              raise ValueError,"unknown diagnostic item %s"%name              raise ValueError,"unknown diagnostic item %s"%name
354      def hasConverged(self):      def hasConverged(self):
355          """          """
356          Returns C{True} if the last solver call has been finalized successfully.          Returns ``True`` if the last solver call has been finalized successfully.
357          @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.
358          """          """
359          return self.getDiagnostics("converged")          return self.getDiagnostics("converged")
360      def setCoarsening(self,method=0):      def setCoarsening(self,method=0):
361          """          """
362          Sets the key of the coarsening method to be applied in AMG.          Sets the key of the coarsening method to be applied in AMG.
363    
364          @param method: selects the coarsening method .          :param method: selects the coarsening method .
365          @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}  
366          """          """
367      if method==None: method=0      if method==None: method=0
368          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]:
# Line 352  class SolverOptions(object): Line 373  class SolverOptions(object):
373          """          """
374          Returns the key of the coarsening algorithm to be applied AMG.          Returns the key of the coarsening algorithm to be applied AMG.
375    
376          @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}  
377          """          """
378          return self.__coarsening          return self.__coarsening
379                
# Line 361  class SolverOptions(object): Line 381  class SolverOptions(object):
381          """          """
382          Sets the minumum size of the coarsest level matrix in AMG.          Sets the minumum size of the coarsest level matrix in AMG.
383    
384          @param size: minumum size of the coarsest level matrix .          :param size: minumum size of the coarsest level matrix .
385          @type size: positive C{int} or C{None}          :type size: positive ``int`` or ``None``
386          """          """
387          size=int(size)          size=int(size)
388          if size<0:          if size<0:
# Line 374  class SolverOptions(object): Line 394  class SolverOptions(object):
394          """          """
395          Returns the minumum size of the coarsest level matrix in AMG.          Returns the minumum size of the coarsest level matrix in AMG.
396    
397          @rtype: C{int}          :rtype: ``int``
398          """          """
399          return self.__MinCoarseMatrixSize          return self.__MinCoarseMatrixSize
400                
# Line 382  class SolverOptions(object): Line 402  class SolverOptions(object):
402          """          """
403          Sets the preconditioner to be used.          Sets the preconditioner to be used.
404    
405          @param preconditioner: key of the preconditioner to be used.          :param preconditioner: key of the preconditioner to be used.
406          @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`,
407                                      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`,
408                                      L{SolverOptions.NO_PRECONDITIONER}                                      `SolverOptions.NO_PRECONDITIONER`
409          @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.  
410          """          """
411      if preconditioner==None: preconditioner=10      if preconditioner==None: preconditioner=10
412          if not preconditioner in [ SolverOptions.SSOR, SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI,          if not preconditioner in [ SolverOptions.SSOR, SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI,
413                                      SolverOptions.AMG, SolverOptions.REC_ILU, SolverOptions.GAUSS_SEIDEL, SolverOptions.RILU,                                      SolverOptions.AMG, SolverOptions.AMLI, SolverOptions.REC_ILU, SolverOptions.GAUSS_SEIDEL, SolverOptions.RILU,
414                                      SolverOptions.NO_PRECONDITIONER] :                                      SolverOptions.NO_PRECONDITIONER] :
415               raise ValueError,"unknown preconditioner %s"%preconditioner               raise ValueError,"unknown preconditioner %s"%preconditioner
416          self.__preconditioner=preconditioner              self.__preconditioner=preconditioner    
# Line 399  class SolverOptions(object): Line 418  class SolverOptions(object):
418          """          """
419          Returns key of the preconditioner to be used.          Returns key of the preconditioner to be used.
420    
421          @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`,
422                                      L{SolverOptions.AMG}, L{SolverOptions.REC_ILU}, L{SolverOptions.GAUSS_SEIDEL}, L{SolverOptions.RILU},                                      `SolverOptions.AMG`, `SolverOptions.REC_ILU`, `SolverOptions.GAUSS_SEIDEL`, `SolverOptions.RILU`,
423                                      L{SolverOptions.NO_PRECONDITIONER}                                      `SolverOptions.NO_PRECONDITIONER`
424          """          """
425          return self.__preconditioner          return self.__preconditioner
426      def setSolverMethod(self, method=0):      def setSolverMethod(self, method=0):
427          """          """
428          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
429          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
430          solver should be used.          solver should be used.
431    
432          @param method: key of the solver method to be used.          :param method: key of the solver method to be used.
433          @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`,
434                          L{SolverOptions.CR}, L{SolverOptions.CGS}, L{SolverOptions.BICGSTAB}, L{SolverOptions.SSOR},                          `SolverOptions.CR`, `SolverOptions.CGS`, `SolverOptions.BICGSTAB`, `SolverOptions.SSOR`,
435                          L{SolverOptions.GMRES}, L{SolverOptions.PRES20}, L{SolverOptions.LUMPING}, L{SolverOptions.ITERATIVE},                          `SolverOptions.GMRES`, `SolverOptions.PRES20`, `SolverOptions.LUMPING`, `SolverOptions.ITERATIVE`,
436                          L{SolverOptions.AMG}, L{SolverOptions.NONLINEAR_GMRES}, L{SolverOptions.TFQMR}, L{SolverOptions.MINRES},                          `SolverOptions.AMG`, `SolverOptions.NONLINEAR_GMRES`, `SolverOptions.TFQMR`, `SolverOptions.MINRES`,
437                          L{SolverOptions.GAUSS_SEIDEL}                          `SolverOptions.GAUSS_SEIDEL`
438          @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.  
439          """          """
440      if method==None: method=0      if method==None: method=0
441          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 448  class SolverOptions(object):
448          """          """
449          Returns key of the solver method to be used.          Returns key of the solver method to be used.
450    
451          @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`,
452                          L{SolverOptions.CR}, L{SolverOptions.CGS}, L{SolverOptions.BICGSTAB}, L{SolverOptions.SSOR},                          `SolverOptions.CR`, `SolverOptions.CGS`, `SolverOptions.BICGSTAB`, `SolverOptions.SSOR`,
453                          L{SolverOptions.GMRES}, L{SolverOptions.PRES20}, L{SolverOptions.LUMPING}, L{SolverOptions.ITERATIVE},                          `SolverOptions.GMRES`, `SolverOptions.PRES20`, `SolverOptions.LUMPING`, `SolverOptions.ITERATIVE`,
454                          L{SolverOptions.AMG}, L{SolverOptions.NONLINEAR_GMRES}, L{SolverOptions.TFQMR}, L{SolverOptions.MINRES},                          `SolverOptions.AMG`, `SolverOptions.NONLINEAR_GMRES`, `SolverOptions.TFQMR`, `SolverOptions.MINRES`,
455                          L{SolverOptions.GAUSS_SEIDEL}                          `SolverOptions.GAUSS_SEIDEL`
456          """          """
457          return self.__method          return self.__method
458                    
# Line 442  class SolverOptions(object): Line 460  class SolverOptions(object):
460          """          """
461          Sets the solver package to be used as a solver.            Sets the solver package to be used as a solver.  
462    
463          @param package: key of the solver package to be used.          :param package: key of the solver package to be used.
464          @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`
465          @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.
466          """          """
467      if package==None: package=0      if package==None: package=0
468          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 472  class SolverOptions(object):
472          """          """
473          Returns the solver package key          Returns the solver package key
474    
475          @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`
476          """          """
477          return self.__package          return self.__package
478      def setReordering(self,ordering=30):      def setReordering(self,ordering=30):
# Line 462  class SolverOptions(object): Line 480  class SolverOptions(object):
480          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
481          to optimize compute time and storage use during elimination.          to optimize compute time and storage use during elimination.
482    
483          @param ordering: selects the reordering strategy.          :param ordering: selects the reordering strategy.
484          @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}  
485          """          """
486          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]:
487               raise ValueError,"unknown reordering strategy %s"%ordering               raise ValueError,"unknown reordering strategy %s"%ordering
# Line 473  class SolverOptions(object): Line 490  class SolverOptions(object):
490          """          """
491          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.
492    
493          @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}  
494          """          """
495          return self.__reordering          return self.__reordering
496      def setRestart(self,restart=None):      def setRestart(self,restart=None):
497          """          """
498          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.
499    
500          @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.
501                          restart is performed.          :type restart: ``int`` or ``None``
         @type restart: C{int} or C{None}  
502          """          """
503          if restart == None:          if restart == None:
504              self.__restart=restart              self.__restart=restart
# Line 496  class SolverOptions(object): Line 511  class SolverOptions(object):
511      def getRestart(self):      def getRestart(self):
512          """          """
513          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.
514          If C{None} is returned no restart is performed.          If ``None`` is returned no restart is performed.
515    
516          @rtype: C{int} or C{None}          :rtype: ``int`` or ``None``
517          """          """
518          if self.__restart < 0:          if self.__restart < 0:
519              return None              return None
# Line 515  class SolverOptions(object): Line 530  class SolverOptions(object):
530          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
531          the faster GMRES converged but          the faster GMRES converged but
532    
533          @param truncation: truncation          :param truncation: truncation
534          @type truncation: C{int}          :type truncation: ``int``
535          """          """
536          truncation=int(truncation)          truncation=int(truncation)
537          if truncation<1:          if truncation<1:
# Line 526  class SolverOptions(object): Line 541  class SolverOptions(object):
541          """          """
542          Returns the number of residuals in GMRES to be stored for orthogonalization          Returns the number of residuals in GMRES to be stored for orthogonalization
543    
544          @rtype: C{int}          :rtype: ``int``
545          """          """
546          return self.__truncation          return self.__truncation
547      def setInnerIterMax(self,iter_max=10):      def setInnerIterMax(self,iter_max=10):
548          """          """
549          Sets the maximum number of iteration steps for the inner iteration.          Sets the maximum number of iteration steps for the inner iteration.
550    
551          @param iter_max: maximum number of inner iterations          :param iter_max: maximum number of inner iterations
552          @type iter_max: C{int}          :type iter_max: ``int``
553          """          """
554          iter_max=int(iter_max)          iter_max=int(iter_max)
555          if iter_max<1:          if iter_max<1:
# Line 544  class SolverOptions(object): Line 559  class SolverOptions(object):
559          """          """
560          Returns maximum number of inner iteration steps          Returns maximum number of inner iteration steps
561    
562          @rtype: C{int}          :rtype: ``int``
563          """          """
564          return self.__inner_iter_max          return self.__inner_iter_max
565      def setIterMax(self,iter_max=100000):      def setIterMax(self,iter_max=100000):
566          """          """
567          Sets the maximum number of iteration steps          Sets the maximum number of iteration steps
568    
569          @param iter_max: maximum number of iteration steps          :param iter_max: maximum number of iteration steps
570          @type iter_max: C{int}          :type iter_max: ``int``
571          """          """
572          iter_max=int(iter_max)          iter_max=int(iter_max)
573          if iter_max<1:          if iter_max<1:
# Line 562  class SolverOptions(object): Line 577  class SolverOptions(object):
577          """          """
578          Returns maximum number of iteration steps          Returns maximum number of iteration steps
579    
580          @rtype: C{int}          :rtype: ``int``
581          """          """
582          return self.__iter_max          return self.__iter_max
583      def setLevelMax(self,level_max=10):      def setLevelMax(self,level_max=3):
584          """          """
585          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
586    
587          @param level_max: maximum number of levels          :param level_max: maximum number of levels
588          @type level_max: C{int}          :type level_max: ``int``
589          """          """
590          level_max=int(level_max)          level_max=int(level_max)
591          if level_max<0:          if level_max<0:
# Line 580  class SolverOptions(object): Line 595  class SolverOptions(object):
595          """          """
596          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
597    
598          @rtype: C{int}          :rtype: ``int``
599          """          """
600          return self.__level_max          return self.__level_max
601      def setCoarseningThreshold(self,theta=0.05):      def setCoarseningThreshold(self,theta=0.25):
602          """          """
603          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
604    
605          @param theta: threshold for coarsening          :param theta: threshold for coarsening
606          @type theta: positive C{float}          :type theta: positive ``float``
607          """          """
608          theta=float(theta)          theta=float(theta)
609          if theta<0 or theta>1:          if theta<0 or theta>1:
# Line 598  class SolverOptions(object): Line 613  class SolverOptions(object):
613          """          """
614          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
615    
616          @rtype: C{float}          :rtype: ``float``
617          """          """
618          return self.__coarsening_threshold          return self.__coarsening_threshold
619      def setNumSweeps(self,sweeps=2):      def setNumSweeps(self,sweeps=2):
620          """          """
621          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.
622    
623          @param sweeps: number of sweeps          :param sweeps: number of sweeps
624          @type theta: positive C{int}          :type sweeps: positive ``int``
625          """          """
626          sweeps=int(sweeps)          sweeps=int(sweeps)
627          if sweeps<1:          if sweeps<1:
# Line 616  class SolverOptions(object): Line 631  class SolverOptions(object):
631          """          """
632          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.
633    
634          @rtype: C{int}          :rtype: ``int``
635          """          """
636          return self.__sweeps          return self.__sweeps
637      def setNumPreSweeps(self,sweeps=2):      def setNumPreSweeps(self,sweeps=2):
638          """          """
639          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
640    
641          @param sweeps: number of sweeps          :param sweeps: number of sweeps
642          @type theta: positive C{int}          :type sweeps: positive ``int``
643          """          """
644          sweeps=int(sweeps)          sweeps=int(sweeps)
645          if sweeps<1:          if sweeps<1:
# Line 634  class SolverOptions(object): Line 649  class SolverOptions(object):
649          """          """
650          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
651    
652          @rtype: C{int}          :rtype: ``int``
653          """          """
654          return self.__pre_sweeps          return self.__pre_sweeps
655      def setNumPostSweeps(self,sweeps=2):      def setNumPostSweeps(self,sweeps=2):
656          """          """
657          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
658    
659          @param sweeps: number of sweeps          :param sweeps: number of sweeps
660          @type theta: positive C{int}          :type sweeps: positive ``int``
661          """          """
662          sweeps=int(sweeps)          sweeps=int(sweeps)
663          if sweeps<1:          if sweeps<1:
# Line 652  class SolverOptions(object): Line 667  class SolverOptions(object):
667          """          """
668          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
669    
670          @rtype: C{int}          :rtype: ``int``
671          """          """
672          return self.__post_sweeps          return self.__post_sweeps
673    
# Line 660  class SolverOptions(object): Line 675  class SolverOptions(object):
675          """          """
676          Sets the relative tolerance for the solver          Sets the relative tolerance for the solver
677    
678          @param rtol: relative tolerance          :param rtol: relative tolerance
679          @type rtol: non-negative C{float}          :type rtol: non-negative ``float``
680          """          """
681          rtol=float(rtol)          rtol=float(rtol)
682          if rtol<0 or rtol>1:          if rtol<0 or rtol>1:
# Line 671  class SolverOptions(object): Line 686  class SolverOptions(object):
686          """          """
687          Returns the relative tolerance for the solver          Returns the relative tolerance for the solver
688    
689          @rtype: C{float}          :rtype: ``float``
690          """          """
691          return self.__tolerance          return self.__tolerance
692      def setAbsoluteTolerance(self,atol=0.):      def setAbsoluteTolerance(self,atol=0.):
693          """          """
694          Sets the absolute tolerance for the solver          Sets the absolute tolerance for the solver
695    
696          @param atol:  absolute tolerance          :param atol:  absolute tolerance
697          @type atol: non-negative C{float}          :type atol: non-negative ``float``
698          """          """
699          atol=float(atol)          atol=float(atol)
700          if atol<0:          if atol<0:
# Line 689  class SolverOptions(object): Line 704  class SolverOptions(object):
704          """          """
705          Returns the absolute tolerance for the solver          Returns the absolute tolerance for the solver
706    
707          @rtype: C{float}          :rtype: ``float``
708          """          """
709          return self.__absolute_tolerance          return self.__absolute_tolerance
710    
711      def setInnerTolerance(self,rtol=0.9):      def setInnerTolerance(self,rtol=0.9):
712          """          """
713           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.  
714    
715          @param rtol: inner relative tolerance          :param rtol: inner relative tolerance
716          @type rtol: positive C{float}          :type rtol: positive ``float``
717          """          """
718          rtol=float(rtol)          rtol=float(rtol)
719          if rtol<=0 or rtol>1:          if rtol<=0 or rtol>1:
# Line 709  class SolverOptions(object): Line 723  class SolverOptions(object):
723          """          """
724          Returns the relative tolerance for an inner iteration scheme          Returns the relative tolerance for an inner iteration scheme
725    
726          @rtype: C{float}          :rtype: ``float``
727          """          """
728          return self.__inner_tolerance          return self.__inner_tolerance
729      def setDropTolerance(self,drop_tol=0.01):      def setDropTolerance(self,drop_tol=0.01):
730          """          """
731          Sets the relative drop tolerance in ILUT          Sets the relative drop tolerance in ILUT
732    
733          @param drop_tol: drop tolerance          :param drop_tol: drop tolerance
734          @type drop_tol: positive C{float}          :type drop_tol: positive ``float``
735          """          """
736          drop_tol=float(drop_tol)          drop_tol=float(drop_tol)
737          if drop_tol<=0 or drop_tol>1:          if drop_tol<=0 or drop_tol>1:
# Line 727  class SolverOptions(object): Line 741  class SolverOptions(object):
741          """          """
742          Returns the relative drop tolerance in ILUT          Returns the relative drop tolerance in ILUT
743    
744          @rtype: C{float}          :rtype: ``float``
745          """          """
746          return self.__drop_tolerance          return self.__drop_tolerance
747      def setDropStorage(self,storage=2.):      def setDropStorage(self,storage=2.):
748          """          """
749          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
750          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.
751    
752          @param storage: allowed storage increase          :param storage: allowed storage increase
753          @type storage: C{float}          :type storage: ``float``
754          """          """
755          storage=float(storage)          storage=float(storage)
756          if storage<1:          if storage<1:
# Line 747  class SolverOptions(object): Line 761  class SolverOptions(object):
761          """          """
762          Returns the maximum allowed increase in storage for ILUT          Returns the maximum allowed increase in storage for ILUT
763    
764          @rtype: C{float}          :rtype: ``float``
765          """          """
766          return self.__drop_storage          return self.__drop_storage
767      def setRelaxationFactor(self,factor=0.3):      def setRelaxationFactor(self,factor=0.3):
768          """          """
769          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.
770    
771          @param factor: relaxation factor          :param factor: relaxation factor
772          @type factor: C{float}          :type factor: ``float``
773          @note: RILU with a relaxation factor 0 is identical to ILU0          :note: RILU with a relaxation factor 0 is identical to ILU0
774          """          """
775          factor=float(factor)          factor=float(factor)
776          if factor<0:          if factor<0:
# Line 767  class SolverOptions(object): Line 781  class SolverOptions(object):
781          """          """
782          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.
783    
784          @rtype: C{float}          :rtype: ``float``
785          """          """
786          return self.__relaxation          return self.__relaxation
787      def isSymmetric(self):      def isSymmetric(self):
788          """          """
789          Checks if symmetry of the  coefficient matrix is indicated.          Checks if symmetry of the  coefficient matrix is indicated.
790    
791          @return: True if a symmetric PDE is indicated, False otherwise          :return: True if a symmetric PDE is indicated, False otherwise
792          @rtype: C{bool}          :rtype: ``bool``
793          """          """
794          return self.__symmetric          return self.__symmetric
795      def setSymmetryOn(self):      def setSymmetryOn(self):
# Line 790  class SolverOptions(object): Line 804  class SolverOptions(object):
804          self.__symmetric=False          self.__symmetric=False
805      def setSymmetry(self,flag=False):      def setSymmetry(self,flag=False):
806          """          """
807          Sets the symmetry flag for the coefficient matrix to C{flag}.          Sets the symmetry flag for the coefficient matrix to ``flag``.
808    
809          @param flag: If True, the symmetry flag is set otherwise reset.          :param flag: If True, the symmetry flag is set otherwise reset.
810          @type flag: C{bool}          :type flag: ``bool``
811          """          """
812          if flag:          if flag:
813              self.setSymmetryOn()              self.setSymmetryOn()
# Line 801  class SolverOptions(object): Line 815  class SolverOptions(object):
815              self.setSymmetryOff()              self.setSymmetryOff()
816      def isVerbose(self):      def isVerbose(self):
817          """          """
818          Returns C{True} if the solver is expected to be verbose.          Returns ``True`` if the solver is expected to be verbose.
819    
820          @return: True if verbosity of switched on.          :return: True if verbosity of switched on.
821          @rtype: C{bool}          :rtype: ``bool``
822          """          """
823          return self.__verbose          return self.__verbose
824    
# Line 820  class SolverOptions(object): Line 834  class SolverOptions(object):
834          self.__verbose=False          self.__verbose=False
835      def setVerbosity(self,verbose=False):      def setVerbosity(self,verbose=False):
836          """          """
837          Sets the verbosity flag for the solver to C{flag}.          Sets the verbosity flag for the solver to ``flag``.
838    
839          @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.
840          @type flag: C{bool}          :type verbose: ``bool``
841          """          """
842          if verbose:          if verbose:
843              self.setVerbosityOn()              self.setVerbosityOn()
# Line 832  class SolverOptions(object): Line 846  class SolverOptions(object):
846                    
847      def adaptInnerTolerance(self):      def adaptInnerTolerance(self):
848          """          """
849          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.
850          Otherwise the inner tolerance set by L{setInnerTolerance} is used.          Otherwise the inner tolerance set by `setInnerTolerance` is used.
851    
852          @return: C{True} if inner tolerance adaption is chosen.          :return: ``True`` if inner tolerance adaption is chosen.
853          @rtype: C{bool}          :rtype: ``bool``
854          """          """
855          return self.__adapt_inner_tolerance          return self.__adapt_inner_tolerance
856    
# Line 854  class SolverOptions(object): Line 868  class SolverOptions(object):
868          """          """
869          Sets a flag to indicate automatic selection of the inner tolerance.          Sets a flag to indicate automatic selection of the inner tolerance.
870    
871          @param adapt: If C{True}, the inner tolerance is selected automatically.          :param adapt: If ``True``, the inner tolerance is selected automatically.
872          @type adapt: C{bool}          :type adapt: ``bool``
873          """          """
874          if adapt:          if adapt:
875              self.setInnerToleranceAdaptionOn()              self.setInnerToleranceAdaptionOn()
# Line 864  class SolverOptions(object): Line 878  class SolverOptions(object):
878    
879      def acceptConvergenceFailure(self):      def acceptConvergenceFailure(self):
880          """          """
881          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
882          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
883          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
884          continue even if the returned the solution does not necessarily meet the          continue even if the returned the solution does not necessarily meet the
885          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
886          last call to the solver was successful.          last call to the solver was successful.
887    
888          @return: C{True} if a failure to achieve convergence is accepted.          :return: ``True`` if a failure to achieve convergence is accepted.
889          @rtype: C{bool}          :rtype: ``bool``
890          """          """
891          return self.__accept_convergence_failure          return self.__accept_convergence_failure
892    
# Line 890  class SolverOptions(object): Line 904  class SolverOptions(object):
904          """          """
905          Sets a flag to indicate the acceptance of a failure of convergence.          Sets a flag to indicate the acceptance of a failure of convergence.
906    
907          @param accept: If C{True}, any failure to achieve convergence is accepted.          :param accept: If ``True``, any failure to achieve convergence is accepted.
908          @type accept: C{bool}          :type accept: ``bool``
909          """          """
910          if accept:          if accept:
911              self.setAcceptanceConvergenceFailureOn()              self.setAcceptanceConvergenceFailureOn()
# Line 927  class PDECoef(object): Line 941  class PDECoef(object):
941      """      """
942      A class for describing a PDE coefficient.      A class for describing a PDE coefficient.
943    
944      @cvar INTERIOR: indicator that coefficient is defined on the interior of      :cvar INTERIOR: indicator that coefficient is defined on the interior of
945                      the PDE domain                      the PDE domain
946      @cvar BOUNDARY: indicator that coefficient is defined on the boundary of      :cvar BOUNDARY: indicator that coefficient is defined on the boundary of
947                      the PDE domain                      the PDE domain
948      @cvar CONTACT: indicator that coefficient is defined on the contact region      :cvar CONTACT: indicator that coefficient is defined on the contact region
949                     within the PDE domain                     within the PDE domain
950      @cvar INTERIOR_REDUCED: indicator that coefficient is defined on the      :cvar INTERIOR_REDUCED: indicator that coefficient is defined on the
951                              interior of the PDE domain using a reduced                              interior of the PDE domain using a reduced
952                              integration order                              integration order
953      @cvar BOUNDARY_REDUCED: indicator that coefficient is defined on the      :cvar BOUNDARY_REDUCED: indicator that coefficient is defined on the
954                              boundary of the PDE domain using a reduced                              boundary of the PDE domain using a reduced
955                              integration order                              integration order
956      @cvar CONTACT_REDUCED: indicator that coefficient is defined on the contact      :cvar CONTACT_REDUCED: indicator that coefficient is defined on the contact
957                             region within the PDE domain using a reduced                             region within the PDE domain using a reduced
958                             integration order                             integration order
959      @cvar SOLUTION: indicator that coefficient is defined through a solution of      :cvar SOLUTION: indicator that coefficient is defined through a solution of
960                      the PDE                      the PDE
961      @cvar REDUCED: indicator that coefficient is defined through a reduced      :cvar REDUCED: indicator that coefficient is defined through a reduced
962                     solution of the PDE                     solution of the PDE
963      @cvar BY_EQUATION: indicator that the dimension of the coefficient shape is      :cvar BY_EQUATION: indicator that the dimension of the coefficient shape is
964                         defined by the number of PDE equations                         defined by the number of PDE equations
965      @cvar BY_SOLUTION: indicator that the dimension of the coefficient shape is      :cvar BY_SOLUTION: indicator that the dimension of the coefficient shape is
966                         defined by the number of PDE solutions                         defined by the number of PDE solutions
967      @cvar BY_DIM: indicator that the dimension of the coefficient shape is      :cvar BY_DIM: indicator that the dimension of the coefficient shape is
968                    defined by the spatial dimension                    defined by the spatial dimension
969      @cvar OPERATOR: indicator that the the coefficient alters the operator of      :cvar OPERATOR: indicator that the the coefficient alters the operator of
970                      the PDE                      the PDE
971      @cvar RIGHTHANDSIDE: indicator that the the coefficient alters the right      :cvar RIGHTHANDSIDE: indicator that the the coefficient alters the right
972                           hand side of the PDE                           hand side of the PDE
973      @cvar BOTH: indicator that the the coefficient alters the operator as well      :cvar BOTH: indicator that the the coefficient alters the operator as well
974                  as the right hand side of the PDE                  as the right hand side of the PDE
975    
976      """      """
# Line 979  class PDECoef(object): Line 993  class PDECoef(object):
993         """         """
994         Initialises a PDE coefficient type.         Initialises a PDE coefficient type.
995    
996         @param where: describes where the coefficient lives         :param where: describes where the coefficient lives
997         @type where: one of L{INTERIOR}, L{BOUNDARY}, L{CONTACT}, L{SOLUTION},         :type where: one of `INTERIOR`, `BOUNDARY`, `CONTACT`, `SOLUTION`,
998                      L{REDUCED}, L{INTERIOR_REDUCED}, L{BOUNDARY_REDUCED},                      `REDUCED`, `INTERIOR_REDUCED`, `BOUNDARY_REDUCED`,
999                      L{CONTACT_REDUCED}                      `CONTACT_REDUCED`
1000         @param pattern: describes the shape of the coefficient and how the shape         :param pattern: describes the shape of the coefficient and how the shape
1001                         is built for a given spatial dimension and numbers of                         is built for a given spatial dimension and numbers of
1002                         equations and solutions in then PDE. For instance,                         equations and solutions in then PDE. For instance,
1003                         (L{BY_EQUATION},L{BY_SOLUTION},L{BY_DIM}) describes a                         (`BY_EQUATION`,`BY_SOLUTION`,`BY_DIM`) describes a
1004                         rank 3 coefficient which is instantiated as shape (3,2,2)                         rank 3 coefficient which is instantiated as shape (3,2,2)
1005                         in case of three equations and two solution components                         in case of three equations and two solution components
1006                         on a 2-dimensional domain. In the case of single equation                         on a 2-dimensional domain. In the case of single equation
1007                         and a single solution component the shape components                         and a single solution component the shape components
1008                         marked by L{BY_EQUATION} or L{BY_SOLUTION} are dropped.                         marked by `BY_EQUATION` or `BY_SOLUTION` are dropped.
1009                         In this case the example would be read as (2,).                         In this case the example would be read as (2,).
1010         @type pattern: C{tuple} of L{BY_EQUATION}, L{BY_SOLUTION}, L{BY_DIM}         :type pattern: ``tuple`` of `BY_EQUATION`, `BY_SOLUTION`, `BY_DIM`
1011         @param altering: indicates what part of the PDE is altered if the         :param altering: indicates what part of the PDE is altered if the
1012                          coefficient is altered                          coefficient is altered
1013         @type altering: one of L{OPERATOR}, L{RIGHTHANDSIDE}, L{BOTH}         :type altering: one of `OPERATOR`, `RIGHTHANDSIDE`, `BOTH`
1014         """         """
1015         super(PDECoef, self).__init__()         super(PDECoef, self).__init__()
1016         self.what=where         self.what=where
# Line 1012  class PDECoef(object): Line 1026  class PDECoef(object):
1026    
1027      def getFunctionSpace(self,domain,reducedEquationOrder=False,reducedSolutionOrder=False):      def getFunctionSpace(self,domain,reducedEquationOrder=False,reducedSolutionOrder=False):
1028         """         """
1029         Returns the L{FunctionSpace<escript.FunctionSpace>} of the coefficient.         Returns the `FunctionSpace` of the coefficient.
1030    
1031         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1032         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1033         @param reducedEquationOrder: True to indicate that reduced order is used         :param reducedEquationOrder: True to indicate that reduced order is used
1034                                      to represent the equation                                      to represent the equation
1035         @type reducedEquationOrder: C{bool}         :type reducedEquationOrder: ``bool``
1036         @param reducedSolutionOrder: True to indicate that reduced order is used         :param reducedSolutionOrder: True to indicate that reduced order is used
1037                                      to represent the solution                                      to represent the solution
1038         @type reducedSolutionOrder: C{bool}         :type reducedSolutionOrder: ``bool``
1039         @return: L{FunctionSpace<escript.FunctionSpace>} of the coefficient         :return: `FunctionSpace` of the coefficient
1040         @rtype: L{FunctionSpace<escript.FunctionSpace>}         :rtype: `FunctionSpace`
1041         """         """
1042         if self.what==self.INTERIOR:         if self.what==self.INTERIOR:
1043              return escript.Function(domain)              return escript.Function(domain)
# Line 1049  class PDECoef(object): Line 1063  class PDECoef(object):
1063         """         """
1064         Returns the value of the coefficient.         Returns the value of the coefficient.
1065    
1066         @return: value of the coefficient         :return: value of the coefficient
1067         @rtype: L{Data<escript.Data>}         :rtype: `Data`
1068         """         """
1069         return self.value         return self.value
1070    
# Line 1058  class PDECoef(object): Line 1072  class PDECoef(object):
1072         """         """
1073         Sets the value of the coefficient to a new value.         Sets the value of the coefficient to a new value.
1074    
1075         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1076         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1077         @param numEquations: number of equations of the PDE         :param numEquations: number of equations of the PDE
1078         @type numEquations: C{int}         :type numEquations: ``int``
1079         @param numSolutions: number of components of the PDE solution         :param numSolutions: number of components of the PDE solution
1080         @type numSolutions: C{int}         :type numSolutions: ``int``
1081         @param reducedEquationOrder: True to indicate that reduced order is used         :param reducedEquationOrder: True to indicate that reduced order is used
1082                                      to represent the equation                                      to represent the equation
1083         @type reducedEquationOrder: C{bool}         :type reducedEquationOrder: ``bool``
1084         @param reducedSolutionOrder: True to indicate that reduced order is used         :param reducedSolutionOrder: True to indicate that reduced order is used
1085                                      to represent the solution                                      to represent the solution
1086         @type reducedSolutionOrder: C{bool}         :type reducedSolutionOrder: ``bool``
1087         @param newValue: number of components of the PDE solution         :param newValue: number of components of the PDE solution
1088         @type newValue: any object that can be converted into a         :type newValue: any object that can be converted into a
1089                         L{Data<escript.Data>} object with the appropriate shape                         `Data` object with the appropriate shape
1090                         and L{FunctionSpace<escript.FunctionSpace>}                         and `FunctionSpace`
1091         @raise IllegalCoefficientValue: if the shape of the assigned value does         :raise IllegalCoefficientValue: if the shape of the assigned value does
1092                                         not match the shape of the coefficient                                         not match the shape of the coefficient
1093         @raise IllegalCoefficientFunctionSpace: if unable to interpolate value         :raise IllegalCoefficientFunctionSpace: if unable to interpolate value
1094                                                 to appropriate function space                                                 to appropriate function space
1095         """         """
1096         if newValue==None:         if newValue==None:
# Line 1099  class PDECoef(object): Line 1113  class PDECoef(object):
1113          """          """
1114          Checks if the coefficient alters the operator of the PDE.          Checks if the coefficient alters the operator of the PDE.
1115    
1116          @return: True if the operator of the PDE is changed when the          :return: True if the operator of the PDE is changed when the
1117                   coefficient is changed                   coefficient is changed
1118          @rtype: C{bool}          :rtype: ``bool``
1119          """          """
1120          if self.altering==self.OPERATOR or self.altering==self.BOTH:          if self.altering==self.OPERATOR or self.altering==self.BOTH:
1121              return not None              return not None
# Line 1112  class PDECoef(object): Line 1126  class PDECoef(object):
1126          """          """
1127          Checks if the coefficient alters the right hand side of the PDE.          Checks if the coefficient alters the right hand side of the PDE.
1128    
1129          @rtype: C{bool}          :rtype: ``bool``
1130          @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
1131                   coefficient is changed, C{None} otherwise.                   coefficient is changed, ``None`` otherwise.
1132          """          """
1133          if self.altering==self.RIGHTHANDSIDE or self.altering==self.BOTH:          if self.altering==self.RIGHTHANDSIDE or self.altering==self.BOTH:
1134              return not None              return not None
# Line 1126  class PDECoef(object): Line 1140  class PDECoef(object):
1140         Tries to estimate the number of equations and number of solutions if         Tries to estimate the number of equations and number of solutions if
1141         the coefficient has the given shape.         the coefficient has the given shape.
1142    
1143         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1144         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1145         @param shape: suggested shape of the coefficient         :param shape: suggested shape of the coefficient
1146         @type shape: C{tuple} of C{int} values         :type shape: ``tuple`` of ``int`` values
1147         @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
1148                  the coefficient has given shape. If no appropriate numbers                  the coefficient has given shape. If no appropriate numbers
1149                  could be identified, C{None} is returned                  could be identified, ``None`` is returned
1150         @rtype: C{tuple} of two C{int} values or C{None}         :rtype: ``tuple`` of two ``int`` values or ``None``
1151         """         """
1152         dim=domain.getDim()         dim=domain.getDim()
1153         if len(shape)>0:         if len(shape)>0:
# Line 1174  class PDECoef(object): Line 1188  class PDECoef(object):
1188         Checks if the coefficient allows to estimate the number of solution         Checks if the coefficient allows to estimate the number of solution
1189         components.         components.
1190    
1191         @return: True if the coefficient allows an estimate of the number of         :return: True if the coefficient allows an estimate of the number of
1192                  solution components, False otherwise                  solution components, False otherwise
1193         @rtype: C{bool}         :rtype: ``bool``
1194         """         """
1195         for i in self.pattern:         for i in self.pattern:
1196               if i==self.BY_SOLUTION: return True               if i==self.BY_SOLUTION: return True
# Line 1186  class PDECoef(object): Line 1200  class PDECoef(object):
1200         """         """
1201         Checks if the coefficient allows to estimate the number of equations.         Checks if the coefficient allows to estimate the number of equations.
1202    
1203         @return: True if the coefficient allows an estimate of the number of         :return: True if the coefficient allows an estimate of the number of
1204                  equations, False otherwise                  equations, False otherwise
1205         @rtype: C{bool}         :rtype: ``bool``
1206         """         """
1207         for i in self.pattern:         for i in self.pattern:
1208               if i==self.BY_EQUATION: return True               if i==self.BY_EQUATION: return True
# Line 1199  class PDECoef(object): Line 1213  class PDECoef(object):
1213        Compares two tuples of possible number of equations and number of        Compares two tuples of possible number of equations and number of
1214        solutions.        solutions.
1215    
1216        @param t1: the first tuple        :param t1: the first tuple
1217        @param t2: the second tuple        :param t2: the second tuple
1218        @return: 0, 1, or -1        :return: 0, 1, or -1
1219        """        """
1220    
1221        dif=t1[0]+t1[1]-(t2[0]+t2[1])        dif=t1[0]+t1[1]-(t2[0]+t2[1])
# Line 1213  class PDECoef(object): Line 1227  class PDECoef(object):
1227         """         """
1228         Builds the required shape of the coefficient.         Builds the required shape of the coefficient.
1229    
1230         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1231         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1232         @param numEquations: number of equations of the PDE         :param numEquations: number of equations of the PDE
1233         @type numEquations: C{int}         :type numEquations: ``int``
1234         @param numSolutions: number of components of the PDE solution         :param numSolutions: number of components of the PDE solution
1235         @type numSolutions: C{int}         :type numSolutions: ``int``
1236         @return: shape of the coefficient         :return: shape of the coefficient
1237         @rtype: C{tuple} of C{int} values         :rtype: ``tuple`` of ``int`` values
1238         """         """
1239         dim=domain.getDim()         dim=domain.getDim()
1240         s=()         s=()
# Line 1238  class PDECoef(object): Line 1252  class PDECoef(object):
1252  class LinearProblem(object):  class LinearProblem(object):
1253     """     """
1254     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
1255     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
1256     L{Domain<escript.Domain>} object. The problem can be given as a single     `Domain` object. The problem can be given as a single
1257     equation or as a system of equations.     equation or as a system of equations.
1258    
1259     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
1260     a problem of the form     a problem of the form
1261    
1262     M{L u=f}     *L u=f*
1263    
1264     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
1265     problem will be solved to get the unknown M{u}.     problem will be solved to get the unknown *u*.
1266    
1267     """     """
1268     def __init__(self,domain,numEquations=None,numSolutions=None,debug=False):     def __init__(self,domain,numEquations=None,numSolutions=None,debug=False):
1269       """       """
1270       Initializes a linear problem.       Initializes a linear problem.
1271    
1272       @param domain: domain of the PDE       :param domain: domain of the PDE
1273       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
1274       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
1275                            equations is extracted from the coefficients.                            equations is extracted from the coefficients.
1276       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
1277                            of solution components is extracted from the                            of solution components is extracted from the
1278                            coefficients.                            coefficients.
1279       @param debug: if True debug information is printed       :param debug: if True debug information is printed
1280    
1281       """       """
1282       super(LinearProblem, self).__init__()       super(LinearProblem, self).__init__()
# Line 1292  class LinearProblem(object): Line 1306  class LinearProblem(object):
1306       """       """
1307       Returns a string representation of the PDE.       Returns a string representation of the PDE.
1308    
1309       @return: a simple representation of the PDE       :return: a simple representation of the PDE
1310       @rtype: C{str}       :rtype: ``str``
1311       """       """
1312       return "<LinearProblem %d>"%id(self)       return "<LinearProblem %d>"%id(self)
1313     # ==========================================================================     # ==========================================================================
# Line 1313  class LinearProblem(object): Line 1327  class LinearProblem(object):
1327    
1328     def setDebug(self, flag):     def setDebug(self, flag):
1329       """       """
1330       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.
1331    
1332       @param flag: desired debug status       :param flag: desired debug status
1333       @type flag: C{bool}       :type flag: ``bool``
1334       """       """
1335       if flag:       if flag:
1336           self.setDebugOn()           self.setDebugOn()
# Line 1327  class LinearProblem(object): Line 1341  class LinearProblem(object):
1341       """       """
1342       Prints the text message if debug mode is switched on.       Prints the text message if debug mode is switched on.
1343    
1344       @param text: message to be printed       :param text: message to be printed
1345       @type text: C{string}       :type text: ``string``
1346       """       """
1347       if self.__debug: print "%s: %s"%(str(self),text)       if self.__debug: print "%s: %s"%(str(self),text)
1348    
# Line 1339  class LinearProblem(object): Line 1353  class LinearProblem(object):
1353         """         """
1354         Introduces new coefficients into the problem.         Introduces new coefficients into the problem.
1355    
1356         Use::         Use:
1357    
1358         p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))         p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))
1359    
1360         to introduce the coefficients M{A} ans M{B}.         to introduce the coefficients *A* and *B*.
1361         """         """
1362         for name, type in coeff.items():         for name, type in coeff.items():
1363             if not isinstance(type,PDECoef):             if not isinstance(type,PDECoef):
# Line 1356  class LinearProblem(object): Line 1370  class LinearProblem(object):
1370       """       """
1371       Returns the domain of the PDE.       Returns the domain of the PDE.
1372    
1373       @return: the domain of the PDE       :return: the domain of the PDE
1374       @rtype: L{Domain<escript.Domain>}       :rtype: `Domain`
1375       """       """
1376       return self.__domain       return self.__domain
1377     def getDomainStatus(self):     def getDomainStatus(self):
# Line 1373  class LinearProblem(object): Line 1387  class LinearProblem(object):
1387       return self.__system_status       return self.__system_status
1388     def setSystemStatus(self,status=None):     def setSystemStatus(self,status=None):
1389       """       """
1390       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
1391       current status of the domain is used.       current status of the domain is used.
1392       """       """
1393       if status == None:       if status == None:
# Line 1385  class LinearProblem(object): Line 1399  class LinearProblem(object):
1399       """       """
1400       Returns the spatial dimension of the PDE.       Returns the spatial dimension of the PDE.
1401    
1402       @return: the spatial dimension of the PDE domain       :return: the spatial dimension of the PDE domain
1403       @rtype: C{int}       :rtype: ``int``
1404       """       """
1405       return self.getDomain().getDim()       return self.getDomain().getDim()
1406    
# Line 1394  class LinearProblem(object): Line 1408  class LinearProblem(object):
1408       """       """
1409       Returns the number of equations.       Returns the number of equations.
1410    
1411       @return: the number of equations       :return: the number of equations
1412       @rtype: C{int}       :rtype: ``int``
1413       @raise UndefinedPDEError: if the number of equations is not specified yet       :raise UndefinedPDEError: if the number of equations is not specified yet
1414       """       """
1415       if self.__numEquations==None:       if self.__numEquations==None:
1416           if self.__numSolutions==None:           if self.__numSolutions==None:
# Line 1409  class LinearProblem(object): Line 1423  class LinearProblem(object):
1423       """       """
1424       Returns the number of unknowns.       Returns the number of unknowns.
1425    
1426       @return: the number of unknowns       :return: the number of unknowns
1427       @rtype: C{int}       :rtype: ``int``
1428       @raise UndefinedPDEError: if the number of unknowns is not specified yet       :raise UndefinedPDEError: if the number of unknowns is not specified yet
1429       """       """
1430       if self.__numSolutions==None:       if self.__numSolutions==None:
1431          if self.__numEquations==None:          if self.__numEquations==None:
# Line 1424  class LinearProblem(object): Line 1438  class LinearProblem(object):
1438       """       """
1439       Returns the status of order reduction for the equation.       Returns the status of order reduction for the equation.
1440    
1441       @return: True if reduced interpolation order is used for the       :return: True if reduced interpolation order is used for the
1442                representation of the equation, False otherwise                representation of the equation, False otherwise
1443       @rtype: L{bool}       :rtype: `bool`
1444       """       """
1445       return self.__reduce_equation_order       return self.__reduce_equation_order
1446    
# Line 1434  class LinearProblem(object): Line 1448  class LinearProblem(object):
1448       """       """
1449       Returns the status of order reduction for the solution.       Returns the status of order reduction for the solution.
1450    
1451       @return: True if reduced interpolation order is used for the       :return: True if reduced interpolation order is used for the
1452                representation of the solution, False otherwise                representation of the solution, False otherwise
1453       @rtype: L{bool}       :rtype: `bool`
1454       """       """
1455       return self.__reduce_solution_order       return self.__reduce_solution_order
1456    
1457     def getFunctionSpaceForEquation(self):     def getFunctionSpaceForEquation(self):
1458       """       """
1459       Returns the L{FunctionSpace<escript.FunctionSpace>} used to discretize       Returns the `FunctionSpace` used to discretize
1460       the equation.       the equation.
1461    
1462       @return: representation space of equation       :return: representation space of equation
1463       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1464       """       """
1465       if self.reduceEquationOrder():       if self.reduceEquationOrder():
1466           return escript.ReducedSolution(self.getDomain())           return escript.ReducedSolution(self.getDomain())
# Line 1455  class LinearProblem(object): Line 1469  class LinearProblem(object):
1469    
1470     def getFunctionSpaceForSolution(self):     def getFunctionSpaceForSolution(self):
1471       """       """
1472       Returns the L{FunctionSpace<escript.FunctionSpace>} used to represent       Returns the `FunctionSpace` used to represent
1473       the solution.       the solution.
1474    
1475       @return: representation space of solution       :return: representation space of solution
1476       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1477       """       """
1478       if self.reduceSolutionOrder():       if self.reduceSolutionOrder():
1479           return escript.ReducedSolution(self.getDomain())           return escript.ReducedSolution(self.getDomain())
# Line 1473  class LinearProblem(object): Line 1487  class LinearProblem(object):
1487         """         """
1488         Sets the solver options.         Sets the solver options.
1489    
1490         @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.
1491         @type options: L{SolverOptions} or C{None}         :type options: `SolverOptions` or ``None``
1492         @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`.
1493         """         """
1494         if options==None:         if options==None:
1495            self.__solver_options=SolverOptions()            self.__solver_options=SolverOptions()
# Line 1489  class LinearProblem(object): Line 1503  class LinearProblem(object):
1503         """         """
1504         Returns the solver options         Returns the solver options
1505        
1506         @rtype: L{SolverOptions}         :rtype: `SolverOptions`
1507         """         """
1508         self.__solver_options.setSymmetry(self.__sym)         self.__solver_options.setSymmetry(self.__sym)
1509         return self.__solver_options         return self.__solver_options
# Line 1498  class LinearProblem(object): Line 1512  class LinearProblem(object):
1512        """        """
1513        Checks if matrix lumping is the current solver method.        Checks if matrix lumping is the current solver method.
1514    
1515        @return: True if the current solver method is lumping        :return: True if the current solver method is lumping
1516        @rtype: C{bool}        :rtype: ``bool``
1517        """        """
1518        return self.getSolverOptions().getSolverMethod()==self.getSolverOptions().LUMPING        return self.getSolverOptions().getSolverMethod()==self.getSolverOptions().LUMPING
1519     # ==========================================================================     # ==========================================================================
# Line 1509  class LinearProblem(object): Line 1523  class LinearProblem(object):
1523        """        """
1524        Checks if symmetry is indicated.        Checks if symmetry is indicated.
1525    
1526        @return: True if a symmetric PDE is indicated, False otherwise        :return: True if a symmetric PDE is indicated, False otherwise
1527        @rtype: C{bool}        :rtype: ``bool``
1528        @note: the method is equivalent to use getSolverOptions().isSymmetric()        :note: the method is equivalent to use getSolverOptions().isSymmetric()
1529        """        """
1530        self.getSolverOptions().isSymmetric()        self.getSolverOptions().isSymmetric()
1531    
1532     def setSymmetryOn(self):     def setSymmetryOn(self):
1533        """        """
1534        Sets the symmetry flag.        Sets the symmetry flag.
1535        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1536        """        """
1537        self.__sym=True        self.__sym=True
1538        self.getSolverOptions().setSymmetryOn()        self.getSolverOptions().setSymmetryOn()
# Line 1526  class LinearProblem(object): Line 1540  class LinearProblem(object):
1540     def setSymmetryOff(self):     def setSymmetryOff(self):
1541        """        """
1542        Clears the symmetry flag.        Clears the symmetry flag.
1543        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1544        """        """
1545        self.__sym=False        self.__sym=False
1546        self.getSolverOptions().setSymmetryOff()        self.getSolverOptions().setSymmetryOff()
1547    
1548     def setSymmetry(self,flag=False):     def setSymmetry(self,flag=False):
1549        """        """
1550        Sets the symmetry flag to C{flag}.        Sets the symmetry flag to ``flag``.
1551    
1552        @param flag: If True, the symmetry flag is set otherwise reset.        :param flag: If True, the symmetry flag is set otherwise reset.
1553        @type flag: C{bool}        :type flag: ``bool``
1554        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1555        """        """
1556        self.getSolverOptions().setSymmetry(flag)        self.getSolverOptions().setSymmetry(flag)
1557     # ==========================================================================     # ==========================================================================
# Line 1547  class LinearProblem(object): Line 1561  class LinearProblem(object):
1561       """       """
1562       Switches reduced order on for solution and equation representation.       Switches reduced order on for solution and equation representation.
1563    
1564       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1565                            been set                            been set
1566       """       """
1567       self.setReducedOrderForSolutionOn()       self.setReducedOrderForSolutionOn()
# Line 1557  class LinearProblem(object): Line 1571  class LinearProblem(object):
1571       """       """
1572       Switches reduced order off for solution and equation representation       Switches reduced order off for solution and equation representation
1573    
1574       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1575                            been set                            been set
1576       """       """
1577       self.setReducedOrderForSolutionOff()       self.setReducedOrderForSolutionOff()
# Line 1568  class LinearProblem(object): Line 1582  class LinearProblem(object):
1582       Sets order reduction state for both solution and equation representation       Sets order reduction state for both solution and equation representation
1583       according to flag.       according to flag.
1584    
1585       @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
1586                    and equation representation, otherwise or if flag is not                    and equation representation, otherwise or if flag is not
1587                    present order reduction is switched off                    present order reduction is switched off
1588       @type flag: C{bool}       :type flag: ``bool``
1589       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1590                            been set                            been set
1591       """       """
1592       self.setReducedOrderForSolutionTo(flag)       self.setReducedOrderForSolutionTo(flag)
# Line 1583  class LinearProblem(object): Line 1597  class LinearProblem(object):
1597       """       """
1598       Switches reduced order on for solution representation.       Switches reduced order on for solution representation.
1599    
1600       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1601                            been set                            been set
1602       """       """
1603       if not self.__reduce_solution_order:       if not self.__reduce_solution_order:
# Line 1597  class LinearProblem(object): Line 1611  class LinearProblem(object):
1611       """       """
1612       Switches reduced order off for solution representation       Switches reduced order off for solution representation
1613    
1614       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1615                            been set.                            been set.
1616       """       """
1617       if self.__reduce_solution_order:       if self.__reduce_solution_order:
# Line 1611  class LinearProblem(object): Line 1625  class LinearProblem(object):
1625       """       """
1626       Sets order reduction state for solution representation according to flag.       Sets order reduction state for solution representation according to flag.
1627    
1628       @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
1629                    solution representation, otherwise or if flag is not present                    solution representation, otherwise or if flag is not present
1630                    order reduction is switched off                    order reduction is switched off
1631       @type flag: C{bool}       :type flag: ``bool``
1632       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1633                            been set                            been set
1634       """       """
1635       if flag:       if flag:
# Line 1627  class LinearProblem(object): Line 1641  class LinearProblem(object):
1641       """       """
1642       Switches reduced order on for equation representation.       Switches reduced order on for equation representation.
1643    
1644       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1645                            been set                            been set
1646       """       """
1647       if not self.__reduce_equation_order:       if not self.__reduce_equation_order:
# Line 1641  class LinearProblem(object): Line 1655  class LinearProblem(object):
1655       """       """
1656       Switches reduced order off for equation representation.       Switches reduced order off for equation representation.
1657    
1658       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1659                            been set                            been set
1660       """       """
1661       if self.__reduce_equation_order:       if self.__reduce_equation_order:
# Line 1655  class LinearProblem(object): Line 1669  class LinearProblem(object):
1669       """       """
1670       Sets order reduction state for equation representation according to flag.       Sets order reduction state for equation representation according to flag.
1671    
1672       @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
1673                    equation representation, otherwise or if flag is not present                    equation representation, otherwise or if flag is not present
1674                    order reduction is switched off                    order reduction is switched off
1675       @type flag: C{bool}       :type flag: ``bool``
1676       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1677                            been set                            been set
1678       """       """
1679       if flag:       if flag:
# Line 1676  class LinearProblem(object): Line 1690  class LinearProblem(object):
1690        """        """
1691        Tests a coefficient for symmetry.        Tests a coefficient for symmetry.
1692    
1693        @param name: name of the coefficient        :param name: name of the coefficient
1694        @type name: C{str}        :type name: ``str``
1695        @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
1696                        which break the symmetry is printed.                        which break the symmetry is printed.
1697        @type verbose: C{bool}        :type verbose: ``bool``
1698        @return: True if coefficient C{name} is symmetric        :return: True if coefficient ``name`` is symmetric
1699        @rtype: C{bool}        :rtype: ``bool``
1700        """        """
1701        SMALL_TOLERANCE=util.EPSILON*10.        SMALL_TOLERANCE=util.EPSILON*10.
1702        A=self.getCoefficient(name)        A=self.getCoefficient(name)
# Line 1723  class LinearProblem(object): Line 1737  class LinearProblem(object):
1737        """        """
1738        Tests two coefficients for reciprocal symmetry.        Tests two coefficients for reciprocal symmetry.
1739    
1740        @param name0: name of the first coefficient        :param name0: name of the first coefficient
1741        @type name0: C{str}        :type name0: ``str``
1742        @param name1: name of the second coefficient        :param name1: name of the second coefficient
1743        @type name1: C{str}        :type name1: ``str``
1744        @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
1745                        which break the symmetry is printed                        which break the symmetry is printed
1746        @type verbose: C{bool}        :type verbose: ``bool``
1747        @return: True if coefficients C{name0} and C{name1} are reciprocally        :return: True if coefficients ``name0`` and ``name1`` are reciprocally
1748                 symmetric.                 symmetric.
1749        @rtype: C{bool}        :rtype: ``bool``
1750        """        """
1751        SMALL_TOLERANCE=util.EPSILON*10.        SMALL_TOLERANCE=util.EPSILON*10.
1752        B=self.getCoefficient(name0)        B=self.getCoefficient(name0)
# Line 1781  class LinearProblem(object): Line 1795  class LinearProblem(object):
1795    
1796     def getCoefficient(self,name):     def getCoefficient(self,name):
1797       """       """
1798       Returns the value of the coefficient C{name}.       Returns the value of the coefficient ``name``.
1799    
1800       @param name: name of the coefficient requested       :param name: name of the coefficient requested
1801       @type name: C{string}       :type name: ``string``
1802       @return: the value of the coefficient       :return: the value of the coefficient
1803       @rtype: L{Data<escript.Data>}       :rtype: `Data`
1804       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1805       """       """
1806       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1807           return self.__COEFFICIENTS[name].getValue()           return self.__COEFFICIENTS[name].getValue()
# Line 1796  class LinearProblem(object): Line 1810  class LinearProblem(object):
1810    
1811     def hasCoefficient(self,name):     def hasCoefficient(self,name):
1812       """       """
1813       Returns True if C{name} is the name of a coefficient.       Returns True if ``name`` is the name of a coefficient.
1814    
1815       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1816       @type name: C{string}       :type name: ``string``
1817       @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,
1818                False otherwise                False otherwise
1819       @rtype: C{bool}       :rtype: ``bool``
1820       """       """
1821       return self.__COEFFICIENTS.has_key(name)       return self.__COEFFICIENTS.has_key(name)
1822    
1823     def createCoefficient(self, name):     def createCoefficient(self, name):
1824       """       """
1825       Creates a L{Data<escript.Data>} object corresponding to coefficient       Creates a `Data` object corresponding to coefficient
1826       C{name}.       ``name``.
1827    
1828       @return: the coefficient C{name} initialized to 0       :return: the coefficient ``name`` initialized to 0
1829       @rtype: L{Data<escript.Data>}       :rtype: `Data`
1830       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1831       """       """
1832       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1833          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 1836  class LinearProblem(object):
1836    
1837     def getFunctionSpaceForCoefficient(self,name):     def getFunctionSpaceForCoefficient(self,name):
1838       """       """
1839       Returns the L{FunctionSpace<escript.FunctionSpace>} to be used for       Returns the `FunctionSpace` to be used for
1840       coefficient C{name}.       coefficient ``name``.
1841    
1842       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1843       @type name: C{string}       :type name: ``string``
1844       @return: the function space to be used for coefficient C{name}       :return: the function space to be used for coefficient ``name``
1845       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1846       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1847       """       """
1848       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1849          return self.__COEFFICIENTS[name].getFunctionSpace(self.getDomain())          return self.__COEFFICIENTS[name].getFunctionSpace(self.getDomain())
# Line 1838  class LinearProblem(object): Line 1852  class LinearProblem(object):
1852    
1853     def getShapeOfCoefficient(self,name):     def getShapeOfCoefficient(self,name):
1854       """       """
1855       Returns the shape of the coefficient C{name}.       Returns the shape of the coefficient ``name``.
1856    
1857       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1858       @type name: C{string}       :type name: ``string``
1859       @return: the shape of the coefficient C{name}       :return: the shape of the coefficient ``name``
1860       @rtype: C{tuple} of C{int}       :rtype: ``tuple`` of ``int``
1861       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1862       """       """
1863       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1864          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 1874  class LinearProblem(object):
1874    
1875     def alteredCoefficient(self,name):     def alteredCoefficient(self,name):
1876       """       """
1877       Announces that coefficient C{name} has been changed.       Announces that coefficient ``name`` has been changed.
1878    
1879       @param name: name of the coefficient affected       :param name: name of the coefficient affected
1880       @type name: C{string}       :type name: ``string``
1881       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1882       @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
1883              system as constraints are applied to the solved system.              system as constraints are applied to the solved system.
1884       """       """
1885       if self.hasCoefficient(name):       if self.hasCoefficient(name):
# Line 1972  class LinearProblem(object): Line 1986  class LinearProblem(object):
1986       """       """
1987       Returns the operator of the linear problem.       Returns the operator of the linear problem.
1988    
1989       @return: the operator of the problem       :return: the operator of the problem
1990       """       """
1991       return self.getSystem()[0]       return self.getSystem()[0]
1992    
# Line 1980  class LinearProblem(object): Line 1994  class LinearProblem(object):
1994       """       """
1995       Returns the right hand side of the linear problem.       Returns the right hand side of the linear problem.
1996    
1997       @return: the right hand side of the problem       :return: the right hand side of the problem
1998       @rtype: L{Data<escript.Data>}       :rtype: `Data`
1999       """       """
2000       return self.getSystem()[1]       return self.getSystem()[1]
2001    
# Line 2064  class LinearProblem(object): Line 2078  class LinearProblem(object):
2078             if self.isUsingLumping():             if self.isUsingLumping():
2079                 self.__operator.setToZero()                 self.__operator.setToZero()
2080             else:             else:
2081                 self.__operator.resetValues()                 if self.getOperatorType() == self.getRequiredOperatorType():
2082                       self.__operator.resetValues()
2083                   else:
2084                       self.__operator=self.createOperator()
2085                   self.__operator_type=self.getRequiredOperatorType()
2086             self.trace("Operator reset to zero")             self.trace("Operator reset to zero")
2087    
2088     def getCurrentOperator(self):     def getCurrentOperator(self):
# Line 2077  class LinearProblem(object): Line 2095  class LinearProblem(object):
2095        """        """
2096        Sets new values to coefficients.        Sets new values to coefficients.
2097    
2098        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
2099        """        """
2100        # check if the coefficients are  legal:        # check if the coefficients are  legal:
2101        for i in coefficients.iterkeys():        for i in coefficients.iterkeys():
# Line 2136  class LinearProblem(object): Line 2154  class LinearProblem(object):
2154        """        """
2155        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.
2156    
2157        @note: Typically this method is overwritten when implementing a        :note: Typically this method is overwritten when implementing a
2158               particular linear problem.               particular linear problem.
2159        """        """
2160        return None        return None
# Line 2145  class LinearProblem(object): Line 2163  class LinearProblem(object):
2163         """         """
2164         Returns an instance of a new operator.         Returns an instance of a new operator.
2165    
2166         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2167                linear problem.                linear problem.
2168         """         """
2169         return escript.Operator()         return escript.Operator()
# Line 2154  class LinearProblem(object): Line 2172  class LinearProblem(object):
2172        """        """
2173        Tests the PDE for symmetry.        Tests the PDE for symmetry.
2174    
2175        @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
2176                        which break the symmetry is printed                        which break the symmetry is printed
2177        @type verbose: C{bool}        :type verbose: ``bool``
2178        @return: True if the problem is symmetric        :return: True if the problem is symmetric
2179        @rtype: C{bool}        :rtype: ``bool``
2180        @note: Typically this method is overwritten when implementing a        :note: Typically this method is overwritten when implementing a
2181               particular linear problem.               particular linear problem.
2182        """        """
2183        out=True        out=True
# Line 2169  class LinearProblem(object): Line 2187  class LinearProblem(object):
2187         """         """
2188         Returns the solution of the problem.         Returns the solution of the problem.
2189    
2190         @return: the solution         :return: the solution
2191         @rtype: L{Data<escript.Data>}         :rtype: `Data`
2192    
2193         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2194                linear problem.                linear problem.
2195         """         """
2196         return self.getCurrentSolution()         return self.getCurrentSolution()
# Line 2181  class LinearProblem(object): Line 2199  class LinearProblem(object):
2199         """         """
2200         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
2201    
2202         @return: the discrete version of the PDE         :return: the discrete version of the PDE
2203         @rtype: C{tuple} of L{Operator,<escript.Operator>} and L{Data<escript.Data>}.         :rtype: ``tuple`` of `Operator` and `Data`.
2204    
2205         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2206                linear problem.                linear problem.
2207         """         """
2208         return (self.getCurrentOperator(), self.getCurrentRightHandSide())         return (self.getCurrentOperator(), self.getCurrentRightHandSide())
# Line 2192  class LinearProblem(object): Line 2210  class LinearProblem(object):
2210  class LinearPDE(LinearProblem):  class LinearPDE(LinearProblem):
2211     """     """
2212     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
2213     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
2214     L{Domain<escript.Domain>} object.     `Domain` object.
2215    
2216     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
2217     is defined in the following form:     is defined in the following form:
2218    
2219     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)*
2220    
2221     where M{grad(F)} denotes the spatial derivative of M{F}. Einstein's     where *grad(F)* denotes the spatial derivative of *F*. Einstein's
2222     summation convention, ie. summation over indexes appearing twice in a term     summation convention, ie. summation over indexes appearing twice in a term
2223     of a sum performed, is used.     of a sum performed, is used.
2224     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
2225     through L{Data<escript.Data>} objects in L{Function<escript.Function>} and     through `Data` objects in `Function` and
2226     the coefficients M{A_reduced}, M{B_reduced}, M{C_reduced}, M{D_reduced},     the coefficients *A_reduced*, *B_reduced*, *C_reduced*, *D_reduced*,
2227     M{X_reduced} and M{Y_reduced} have to be specified through     *X_reduced* and *Y_reduced* have to be specified through
2228     L{Data<escript.Data>} objects in L{ReducedFunction<escript.ReducedFunction>}.     `Data` objects in `ReducedFunction`.
2229     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
2230     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*,
2231     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
2232     M{D}, M{D_reduced}, M{Y} and M{Y_reduced} are scalar.     *D*, *D_reduced*, *Y* and *Y_reduced* are scalar.
2233    
2234     The following natural boundary conditions are considered:     The following natural boundary conditions are considered:
2235    
2236     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*
2237    
2238     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*,
2239     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
2240     PDE. The coefficients M{d} and M{y} are each a scalar in     PDE. The coefficients *d* and *y* are each a scalar in
2241     L{FunctionOnBoundary<escript.FunctionOnBoundary>} and the coefficients     `FunctionOnBoundary` and the coefficients
2242     M{d_reduced} and M{y_reduced} are each a scalar in     *d_reduced* and *y_reduced* are each a scalar in
2243     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
2244    
2245     Constraints for the solution prescribe the value of the solution at certain     Constraints for the solution prescribe the value of the solution at certain
2246     locations in the domain. They have the form     locations in the domain. They have the form
2247    
2248     M{u=r} where M{q>0}     *u=r* where *q>0*
2249    
2250     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
2251     defining where the constraint is applied. The constraints override any     defining where the constraint is applied. The constraints override any
2252     other condition set by the PDE or the boundary condition.     other condition set by the PDE or the boundary condition.
2253    
2254     The PDE is symmetrical if     The PDE is symmetrical if
2255    
2256     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]*
2257     and M{B_reduced[j]=C_reduced[j]}     and *B_reduced[j]=C_reduced[j]*
2258    
2259     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
2260     form     form
2261    
2262     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]*
2263    
2264     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
2265     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
2266     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.
2267     The natural boundary conditions take the form:     The natural boundary conditions take the form:
2268    
2269     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]*
2270    
2271     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
2272     L{FunctionOnBoundary<escript.FunctionOnBoundary>}. The coefficients     `FunctionOnBoundary`. The coefficients
2273     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
2274     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
2275    
2276     Constraints take the form     Constraints take the form
2277    
2278     M{u[i]=r[i]}  where  M{q[i]>0}     *u[i]=r[i]*  where  *q[i]>0*
2279    
2280     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
2281     necessarily all components must have a constraint.     necessarily all components must have a constraint.
2282    
2283     The system of PDEs is symmetrical if     The system of PDEs is symmetrical if
2284    
2285        - M{A[i,j,k,l]=A[k,l,i,j]}        - *A[i,j,k,l]=A[k,l,i,j]*
2286        - 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]*
2287        - M{B[i,j,k]=C[k,i,j]}        - *B[i,j,k]=C[k,i,j]*
2288        - M{B_reduced[i,j,k]=C_reduced[k,i,j]}        - *B_reduced[i,j,k]=C_reduced[k,i,j]*
2289        - M{D[i,k]=D[i,k]}        - *D[i,k]=D[i,k]*
2290        - M{D_reduced[i,k]=D_reduced[i,k]}        - *D_reduced[i,k]=D_reduced[i,k]*
2291        - M{d[i,k]=d[k,i]}        - *d[i,k]=d[k,i]*
2292        - M{d_reduced[i,k]=d_reduced[k,i]}        - *d_reduced[i,k]=d_reduced[k,i]*
2293    
2294     L{LinearPDE} also supports solution discontinuities over a contact region     `LinearPDE` also supports solution discontinuities over a contact region
2295     in the domain. To specify the conditions across the discontinuity we are     in the domain. To specify the conditions across the discontinuity we are
2296     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
2297     and several components of the solution, is defined as     and several components of the solution, is defined as
2298    
2299     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]*
2300    
2301     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
2302    
2303     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]*
2304    
2305     In the context of discontinuities M{n} denotes the normal on the     In the context of discontinuities *n* denotes the normal on the
2306     discontinuity pointing from side 0 towards side 1 calculated from     discontinuity pointing from side 0 towards side 1 calculated from
2307     L{getNormal<escript.FunctionSpace.getNormal>} of L{FunctionOnContactZero<escript.FunctionOnContactZero>}.     `FunctionSpace.getNormal` of `FunctionOnContactZero`.
2308     For a system of PDEs the contact condition takes the form     For a system of PDEs the contact condition takes the form
2309    
2310     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]*
2311    
2312     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
2313     discontinuity, respectively. M{jump(u)}, which is the difference of the     discontinuity, respectively. *jump(u)*, which is the difference of the
2314     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
2315     discontinuity along the normal calculated by L{jump<util.jump>}.     discontinuity along the normal calculated by `jump`.
2316     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
2317     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
2318     L{FunctionOnContactOne<escript.FunctionOnContactOne>}.     `FunctionOnContactOne`.
2319     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*
2320     is of rank one both in L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>}     is of rank one both in `ReducedFunctionOnContactZero`
2321     or L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     or `ReducedFunctionOnContactOne`.
2322     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
2323     condition takes the form     condition takes the form
2324    
2325     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)*
2326    
2327     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
2328     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
2329     L{FunctionOnContactOne<escript.FunctionOnContactOne>} and the coefficient     `FunctionOnContactOne` and the coefficient
2330     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
2331     L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or     `ReducedFunctionOnContactZero` or
2332     L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     `ReducedFunctionOnContactOne`.
2333    
2334     Typical usage::     Typical usage::
2335    
# Line 2325  class LinearPDE(LinearProblem): Line 2343  class LinearPDE(LinearProblem):
2343       """       """
2344       Initializes a new linear PDE.       Initializes a new linear PDE.
2345    
2346       @param domain: domain of the PDE       :param domain: domain of the PDE
2347       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2348       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
2349                            equations is extracted from the PDE coefficients.                            equations is extracted from the PDE coefficients.
2350       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
2351                            of solution components is extracted from the PDE                            of solution components is extracted from the PDE
2352                            coefficients.                            coefficients.
2353       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2354    
2355       """       """
2356       super(LinearPDE, self).__init__(domain,numEquations,numSolutions,debug)       super(LinearPDE, self).__init__(domain,numEquations,numSolutions,debug)
# Line 2367  class LinearPDE(LinearProblem): Line 2385  class LinearPDE(LinearProblem):
2385       """       """
2386       Returns the string representation of the PDE.       Returns the string representation of the PDE.
2387    
2388       @return: a simple representation of the PDE       :return: a simple representation of the PDE
2389       @rtype: C{str}       :rtype: ``str``
2390       """       """
2391       return "<LinearPDE %d>"%id(self)       return "<LinearPDE %d>"%id(self)
2392    
# Line 2383  class LinearPDE(LinearProblem): Line 2401  class LinearPDE(LinearProblem):
2401        """        """
2402        Tests the PDE for symmetry.        Tests the PDE for symmetry.
2403    
2404        @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
2405                        which break the symmetry is printed.                        which break the symmetry is printed.
2406        @type verbose: C{bool}        :type verbose: ``bool``
2407        @return: True if the PDE is symmetric        :return: True if the PDE is symmetric
2408        @rtype: L{bool}        :rtype: `bool`
2409        @note: This is a very expensive operation. It should be used for        :note: This is a very expensive operation. It should be used for
2410               degugging only! The symmetry flag is not altered.               degugging only! The symmetry flag is not altered.
2411        """        """
2412        out=True        out=True
# Line 2421  class LinearPDE(LinearProblem): Line 2439  class LinearPDE(LinearProblem):
2439         """         """
2440         Returns the solution of the PDE.         Returns the solution of the PDE.
2441    
2442         @return: the solution         :return: the solution
2443         @rtype: L{Data<escript.Data>}         :rtype: `Data`
2444         """         """
2445         option_class=self.getSolverOptions()         option_class=self.getSolverOptions()
2446         if not self.isSolutionValid():         if not self.isSolutionValid():
# Line 2439  class LinearPDE(LinearProblem): Line 2457  class LinearPDE(LinearProblem):
2457         """         """
2458         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
2459    
2460         @return: the discrete version of the PDE         :return: the discrete version of the PDE
2461         @rtype: C{tuple} of L{Operator,<escript.Operator>} and         :rtype: ``tuple`` of `Operator` and
2462                 L{Data<escript.Data>}                 `Data`
2463         """         """
2464         if not self.isOperatorValid() or not self.isRightHandSideValid():         if not self.isOperatorValid() or not self.isRightHandSideValid():
2465            if self.isUsingLumping():            if self.isUsingLumping():
# Line 2616  class LinearPDE(LinearProblem): Line 2634  class LinearPDE(LinearProblem):
2634        """        """
2635        Applies the constraints defined by q and r to the PDE.        Applies the constraints defined by q and r to the PDE.
2636    
2637        @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
2638                         constraint                         constraint
2639        @type rhs_only: C{bool}        :type rhs_only: ``bool``
2640        """        """
2641        q=self.getCoefficient("q")        q=self.getCoefficient("q")
2642        r=self.getCoefficient("r")        r=self.getCoefficient("r")
# Line 2646  class LinearPDE(LinearProblem): Line 2664  class LinearPDE(LinearProblem):
2664        """        """
2665        Sets new values to coefficients.        Sets new values to coefficients.
2666    
2667        @param coefficients: new values assigned to coefficients        :param coefficients: new values assigned to coefficients
2668        @keyword A: value for coefficient C{A}        :keyword A: value for coefficient ``A``
2669        @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
2670                 L{Function<escript.Function>}                 `Function`
2671        @keyword A_reduced: value for coefficient C{A_reduced}        :keyword A_reduced: value for coefficient ``A_reduced``
2672        @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`
2673                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2674        @keyword B: value for coefficient C{B}        :keyword B: value for coefficient ``B``
2675        @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
2676                 L{Function<escript.Function>}                 `Function`
2677        @keyword B_reduced: value for coefficient C{B_reduced}        :keyword B_reduced: value for coefficient ``B_reduced``
2678        @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`
2679                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2680        @keyword C: value for coefficient C{C}        :keyword C: value for coefficient ``C``
2681        @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
2682                 L{Function<escript.Function>}                 `Function`
2683        @keyword C_reduced: value for coefficient C{C_reduced}        :keyword C_reduced: value for coefficient ``C_reduced``
2684        @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`
2685                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2686        @keyword D: value for coefficient C{D}        :keyword D: value for coefficient ``D``
2687        @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
2688                 L{Function<escript.Function>}                 `Function`
2689        @keyword D_reduced: value for coefficient C{D_reduced}        :keyword D_reduced: value for coefficient ``D_reduced``
2690        @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`
2691                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2692        @keyword X: value for coefficient C{X}        :keyword X: value for coefficient ``X``
2693        @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
2694                 L{Function<escript.Function>}                 `Function`
2695        @keyword X_reduced: value for coefficient C{X_reduced}        :keyword X_reduced: value for coefficient ``X_reduced``
2696        @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`
2697                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2698        @keyword Y: value for coefficient C{Y}        :keyword Y: value for coefficient ``Y``
2699        @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
2700                 L{Function<escript.Function>}                 `Function`
2701        @keyword Y_reduced: value for coefficient C{Y_reduced}        :keyword Y_reduced: value for coefficient ``Y_reduced``
2702        @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`
2703                         object on L{ReducedFunction<escript.Function>}                         object on `ReducedFunction`
2704        @keyword d: value for coefficient C{d}        :keyword d: value for coefficient ``d``
2705        @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
2706                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
2707        @keyword d_reduced: value for coefficient C{d_reduced}        :keyword d_reduced: value for coefficient ``d_reduced``
2708        @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`
2709                         object on L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `ReducedFunctionOnBoundary`
2710        @keyword y: value for coefficient C{y}        :keyword y: value for coefficient ``y``
2711        @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
2712                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
2713        @keyword d_contact: value for coefficient C{d_contact}        :keyword d_contact: value for coefficient ``d_contact``
2714        @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`
2715                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>}                         object on `FunctionOnContactOne`
2716                         or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         or `FunctionOnContactZero`
2717        @keyword d_contact_reduced: value for coefficient C{d_contact_reduced}        :keyword d_contact_reduced: value for coefficient ``d_contact_reduced``
2718        @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`
2719                                 object on L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}                                 object on `ReducedFunctionOnContactOne`
2720                                 or L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>}                                 or `ReducedFunctionOnContactZero`
2721        @keyword y_contact: value for coefficient C{y_contact}        :keyword y_contact: value for coefficient ``y_contact``
2722        @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`
2723                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>}                         object on `FunctionOnContactOne`
2724                         or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         or `FunctionOnContactZero`
2725        @keyword y_contact_reduced: value for coefficient C{y_contact_reduced}        :keyword y_contact_reduced: value for coefficient ``y_contact_reduced``
2726        @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`
2727                                 object on L{ReducedFunctionOnContactOne<escript.FunctionOnContactOne>}                                 object on `ReducedFunctionOnContactOne`
2728                                 or L{ReducedFunctionOnContactZero<escript.FunctionOnContactZero>}                                 or `ReducedFunctionOnContactZero`
2729        @keyword r: values prescribed to the solution at the locations of        :keyword r: values prescribed to the solution at the locations of
2730                    constraints                    constraints
2731        @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
2732                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
2733                 depending on whether reduced order is used for the solution                 depending on whether reduced order is used for the solution
2734        @keyword q: mask for location of constraints        :keyword q: mask for location of constraints
2735        @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
2736                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
2737                 depending on whether reduced order is used for the                 depending on whether reduced order is used for the
2738                 representation of the equation                 representation of the equation
2739        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
2740        """        """
2741        super(LinearPDE,self).setValue(**coefficients)        super(LinearPDE,self).setValue(**coefficients)
2742        # check if the systrem is inhomogeneous:        # check if the systrem is inhomogeneous:
# Line 2735  class LinearPDE(LinearProblem): Line 2753  class LinearPDE(LinearProblem):
2753       """       """
2754       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.
2755    
2756       @param u: argument in the residual calculation. It must be representable       :param u: argument in the residual calculation. It must be representable
2757                 in L{self.getFunctionSpaceForSolution()}. If u is not present                 in `self.getFunctionSpaceForSolution()`. If u is not present
2758                 or equals C{None} the current solution is used.                 or equals ``None`` the current solution is used.
2759       @type u: L{Data<escript.Data>} or None       :type u: `Data` or None
2760       @return: residual of u       :return: residual of u
2761       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2762       """       """
2763       if u==None:       if u==None:
2764          return self.getOperator()*self.getSolution()-self.getRightHandSide()          return self.getOperator()*self.getSolution()-self.getRightHandSide()
# Line 2749  class LinearPDE(LinearProblem): Line 2767  class LinearPDE(LinearProblem):
2767    
2768     def getFlux(self,u=None):     def getFlux(self,u=None):
2769       """       """
2770       Returns the flux M{J} for a given M{u}.       Returns the flux *J* for a given *u*.
2771    
2772       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]*
2773    
2774       or       or
2775    
2776       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]*
2777    
2778       @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
2779                 current solution is used.                 current solution is used.
2780       @type u: L{Data<escript.Data>} or None       :type u: `Data` or None
2781       @return: flux       :return: flux
2782       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2783       """       """
2784       if u==None: u=self.getSolution()       if u==None: u=self.getSolution()
2785       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 2793  class LinearPDE(LinearProblem):
2793  class Poisson(LinearPDE):  class Poisson(LinearPDE):
2794     """     """
2795     Class to define a Poisson equation problem. This is generally a     Class to define a Poisson equation problem. This is generally a
2796     L{LinearPDE} of the form     `LinearPDE` of the form
2797    
2798     M{-grad(grad(u)[j])[j] = f}     *-grad(grad(u)[j])[j] = f*
2799    
2800     with natural boundary conditions     with natural boundary conditions
2801    
2802     M{n[j]*grad(u)[j] = 0 }     *n[j]*grad(u)[j] = 0*
2803    
2804     and constraints:     and constraints:
2805    
2806     M{u=0} where M{q>0}     *u=0* where *q>0*
2807    
2808     """     """
2809    
# Line 2793  class Poisson(LinearPDE): Line 2811  class Poisson(LinearPDE):
2811       """       """
2812       Initializes a new Poisson equation.       Initializes a new Poisson equation.
2813    
2814       @param domain: domain of the PDE       :param domain: domain of the PDE
2815       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2816       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2817    
2818       """       """
2819       super(Poisson, self).__init__(domain,1,1,debug)       super(Poisson, self).__init__(domain,1,1,debug)
# Line 2808  class Poisson(LinearPDE): Line 2826  class Poisson(LinearPDE):
2826       """       """
2827       Sets new values to coefficients.       Sets new values to coefficients.
2828    
2829       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
2830       @keyword f: value for right hand side M{f}       :keyword f: value for right hand side *f*
2831       @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
2832                on L{Function<escript.Function>}                on `Function`
2833       @keyword q: mask for location of constraints       :keyword q: mask for location of constraints
2834       @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`
2835                object on L{Solution<escript.Solution>} or                object on `Solution` or
2836                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2837                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2838       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
2839       """       """
2840       super(Poisson, self).setValue(**coefficients)       super(Poisson, self).setValue(**coefficients)
2841    
2842    
2843     def getCoefficient(self,name):     def getCoefficient(self,name):
2844       """       """
2845       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
2846    
2847       @param name: name of the coefficient requested       :param name: name of the coefficient requested
2848       @type name: C{string}       :type name: ``string``
2849       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
2850       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2851       @raise IllegalCoefficient: invalid coefficient name       :raise IllegalCoefficient: invalid coefficient name
2852       @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
2853              equation onto the general PDE.              equation onto the general PDE.
2854       """       """
2855       if name == "A" :       if name == "A" :
# Line 2846  class Poisson(LinearPDE): Line 2864  class Poisson(LinearPDE):
2864  class Helmholtz(LinearPDE):  class Helmholtz(LinearPDE):
2865     """     """
2866     Class to define a Helmholtz equation problem. This is generally a     Class to define a Helmholtz equation problem. This is generally a
2867     L{LinearPDE} of the form     `LinearPDE` of the form
2868    
2869     M{S{omega}*u - grad(k*grad(u)[j])[j] = f}     *omega*u - grad(k*grad(u)[j])[j] = f*
2870    
2871     with natural boundary conditions     with natural boundary conditions
2872    
2873     M{k*n[j]*grad(u)[j] = g- S{alpha}u }     *k*n[j]*grad(u)[j] = g- alphau*
2874    
2875     and constraints:     and constraints:
2876    
2877     M{u=r} where M{q>0}     *u=r* where *q>0*
2878    
2879     """     """
2880    
# Line 2864  class Helmholtz(LinearPDE): Line 2882  class Helmholtz(LinearPDE):
2882       """       """
2883       Initializes a new Helmholtz equation.       Initializes a new Helmholtz equation.
2884    
2885       @param domain: domain of the PDE       :param domain: domain of the PDE
2886       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2887       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2888    
2889       """       """
2890       super(Helmholtz, self).__init__(domain,1,1,debug)       super(Helmholtz, self).__init__(domain,1,1,debug)
# Line 2884  class Helmholtz(LinearPDE): Line 2902  class Helmholtz(LinearPDE):
2902       """       """
2903       Sets new values to coefficients.       Sets new values to coefficients.
2904    
2905       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
2906       @keyword omega: value for coefficient M{S{omega}}       :keyword omega: value for coefficient *omega*
2907       @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`
2908                    object on L{Function<escript.Function>}                    object on `Function`
2909       @keyword k: value for coefficient M{k}       :keyword k: value for coefficient *k*
2910       @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
2911                on L{Function<escript.Function>}                on `Function`
2912       @keyword f: value for right hand side M{f}       :keyword f: value for right hand side *f*
2913       @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
2914                on L{Function<escript.Function>}                on `Function`
2915       @keyword alpha: value for right hand side M{S{alpha}}       :keyword alpha: value for right hand side *alpha*
2916       @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`
2917                    object on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                    object on `FunctionOnBoundary`
2918       @keyword g: value for right hand side M{g}       :keyword g: value for right hand side *g*
2919       @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
2920                on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                on `FunctionOnBoundary`
2921       @keyword r: prescribed values M{r} for the solution in constraints       :keyword r: prescribed values *r* for the solution in constraints
2922       @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
2923                on L{Solution<escript.Solution>} or                on `Solution` or
2924                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2925                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2926       @keyword q: mask for the location of constraints       :keyword q: mask for the location of constraints
2927       @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
2928                on L{Solution<escript.Solution>} or                on `Solution` or
2929                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2930                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2931       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
2932       """       """
2933       super(Helmholtz, self).setValue(**coefficients)       super(Helmholtz, self).setValue(**coefficients)
2934    
2935     def getCoefficient(self,name):     def getCoefficient(self,name):
2936       """       """
2937       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
2938    
2939       @param name: name of the coefficient requested       :param name: name of the coefficient requested
2940       @type name: C{string}       :type name: ``string``
2941       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
2942       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2943       @raise IllegalCoefficient: invalid name       :raise IllegalCoefficient: invalid name
2944       """       """
2945       if name == "A" :       if name == "A" :
2946           if self.getCoefficient("k").isEmpty():           if self.getCoefficient("k").isEmpty():
# Line 2948  class LameEquation(LinearPDE): Line 2966  class LameEquation(LinearPDE):
2966     """     """
2967     Class to define a Lame equation problem. This problem is defined as:     Class to define a Lame equation problem. This problem is defined as:
2968    
2969     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]*
2970    
2971     with natural boundary conditions:     with natural boundary conditions:
2972    
2973     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]*
2974    
2975     and constraints:     and constraints:
2976    
2977     M{u[i]=r[i]} where M{q[i]>0}     *u[i]=r[i]* where *q[i]>0*
2978    
2979     """     """
2980    
# Line 2964  class LameEquation(LinearPDE): Line 2982  class LameEquation(LinearPDE):
2982        """        """
2983        Initializes a new Lame equation.        Initializes a new Lame equation.
2984    
2985        @param domain: domain of the PDE        :param domain: domain of the PDE
2986        @type domain: L{Domain<escript.Domain>}        :type domain: `Domain`
2987        @param debug: if True debug information is printed        :param debug: if True debug information is printed
2988    
2989        """        """
2990        super(LameEquation, self).__init__(domain,\        super(LameEquation, self).__init__(domain,\
# Line 2982  class LameEquation(LinearPDE): Line 3000  class LameEquation(LinearPDE):
3000       """       """
3001       Sets new values to coefficients.       Sets new values to coefficients.
3002    
3003       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
3004       @keyword lame_mu: value for coefficient M{S{mu}}       :keyword lame_mu: value for coefficient *mu*
3005       @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`
3006                      object on L{Function<escript.Function>}                      object on `Function`
3007       @keyword lame_lambda: value for coefficient M{S{lambda}}       :keyword lame_lambda: value for coefficient *lambda*
3008       @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`
3009                          object on L{Function<escript.Function>}                          object on `Function`
3010       @keyword F: value for internal force M{F}       :keyword F: value for internal force *F*
3011       @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
3012                on L{Function<escript.Function>}                on `Function`
3013       @keyword sigma: value for initial stress M{S{sigma}}       :keyword sigma: value for initial stress *sigma*
3014       @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`
3015                    object on L{Function<escript.Function>}                    object on `Function`
3016       @keyword f: value for external force M{f}       :keyword f: value for external force *f*
3017       @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
3018                on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                on `FunctionOnBoundary`
3019       @keyword r: prescribed values M{r} for the solution in constraints       :keyword r: prescribed values *r* for the solution in constraints
3020       @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
3021                on L{Solution<escript.Solution>} or                on `Solution` or
3022                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
3023                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
3024       @keyword q: mask for the location of constraints       :keyword q: mask for the location of constraints
3025       @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
3026                on L{Solution<escript.Solution>} or                on `Solution` or
3027                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
3028                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
3029       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
3030       """       """
3031       super(LameEquation, self).setValues(**coefficients)       super(LameEquation, self).setValues(**coefficients)
3032    
3033     def getCoefficient(self,name):     def getCoefficient(self,name):
3034       """       """
3035       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
3036    
3037       @param name: name of the coefficient requested       :param name: name of the coefficient requested
3038       @type name: C{string}       :type name: ``string``
3039       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
3040       @rtype: L{Data<escript.Data>}       :rtype: `Data`
3041       @raise IllegalCoefficient: invalid coefficient name       :raise IllegalCoefficient: invalid coefficient name
3042       """       """
3043       out =self.createCoefficient("A")       out =self.createCoefficient("A")
3044       if name == "A" :       if name == "A" :
# Line 3057  def LinearSinglePDE(domain,debug=False): Line 3075  def LinearSinglePDE(domain,debug=False):
3075     """     """
3076     Defines a single linear PDE.     Defines a single linear PDE.
3077    
3078     @param domain: domain of the PDE     :param domain: domain of the PDE
3079     @type domain: L{Domain<escript.Domain>}     :type domain: `Domain`
3080     @param debug: if True debug information is printed     :param debug: if True debug information is printed
3081     @rtype: L{LinearPDE}     :rtype: `LinearPDE`
3082     """     """
3083     return LinearPDE(domain,numEquations=1,numSolutions=1,debug=debug)     return LinearPDE(domain,numEquations=1,numSolutions=1,debug=debug)
3084    
# Line 3068  def LinearPDESystem(domain,debug=False): Line 3086  def LinearPDESystem(domain,debug=False):
3086     """     """
3087     Defines a system of linear PDEs.     Defines a system of linear PDEs.
3088    
3089     @param domain: domain of the PDEs     :param domain: domain of the PDEs
3090     @type domain: L{Domain<escript.Domain>}     :type domain: `Domain`
3091     @param debug: if True debug information is printed     :param debug: if True debug information is printed
3092     @rtype: L{LinearPDE}     :rtype: `LinearPDE`
3093     """     """
3094     return LinearPDE(domain,numEquations=domain.getDim(),numSolutions=domain.getDim(),debug=debug)     return LinearPDE(domain,numEquations=domain.getDim(),numSolutions=domain.getDim(),debug=debug)
3095    
# Line 3080  class TransportPDE(LinearProblem): Line 3098  class TransportPDE(LinearProblem):
3098     """     """
3099     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,
3100     time dependent, second order PDE for an unknown, non-negative,     time dependent, second order PDE for an unknown, non-negative,
3101     time-dependent function M{u} on a given domain defined through a     time-dependent function *u* on a given domain defined through a
3102     L{Domain<escript.Domain>} object.     `Domain` object.
3103    
3104     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
3105     problem is defined in the following form:     problem is defined in the following form:
3106    
3107     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)*
3108    
3109     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
3110     spatial derivative of M{F}. Einstein's summation convention,  ie. summation     spatial derivative of *F*. Einstein's summation convention,  ie. summation
3111     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.
3112     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
3113     specified through L{Data<escript.Data>} objects in L{Function<escript.Function>}     specified through `Data` objects in `Function`
3114     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*,
3115     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
3116     L{Data<escript.Data>} objects in L{ReducedFunction<escript.ReducedFunction>}.     `Data` objects in `ReducedFunction`.
3117     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
3118     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
3119     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
3120     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
3121     scalar.     scalar.
3122    
3123     The following natural boundary conditions are considered:     The following natural boundary conditions are considered:
3124    
3125     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*
3126    
3127     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*,
3128     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
3129     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
3130     L{FunctionOnBoundary<escript.FunctionOnBoundary>} and the coefficients     `FunctionOnBoundary` and the coefficients
3131     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
3132     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
3133    
3134     Constraints for the solution prescribing the value of the solution at     Constraints for the solution prescribing the value of the solution at
3135     certain locations in the domain have the form     certain locations in the domain have the form
3136    
3137     M{u_t=r} where M{q>0}     *u_t=r* where *q>0*
3138    
3139     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
3140     defining where the constraint is applied. The constraints override any other     defining where the constraint is applied. The constraints override any other
3141     condition set by the transport problem or the boundary condition.     condition set by the transport problem or the boundary condition.
3142    
3143     The transport problem is symmetrical if     The transport problem is symmetrical if
3144    
3145     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
3146     M{B_reduced[j]=C_reduced[j]}     *B_reduced[j]=C_reduced[j]*
3147    
3148     For a system and a solution with several components the transport problem     For a system and a solution with several components the transport problem
3149     has the form     has the form
3150    
3151     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]*
3152    
3153     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
3154     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*,
3155     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
3156     rank one. The natural boundary conditions take the form:     rank one. The natural boundary conditions take the form:
3157    
3158     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*
3159    
3160     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
3161     all in L{FunctionOnBoundary<escript.FunctionOnBoundary>}. The coefficients     all in `FunctionOnBoundary`. The coefficients
3162     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
3163     one all in L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     one all in `ReducedFunctionOnBoundary`.
3164    
3165     Constraints take the form     Constraints take the form
3166    
3167     M{u[i]_t=r[i]} where M{q[i]>0}     *u[i]_t=r[i]* where *q[i]>0*
3168    
3169     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
3170     necessarily all components must have a constraint.     necessarily all components must have a constraint.
3171    
3172     The transport problem is symmetrical if     The transport problem is symmetrical if
3173    
3174        - M{M[i,k]=M[i,k]}        - *M[i,k]=M[i,k]*
3175        - M{M_reduced[i,k]=M_reduced[i,k]}        - *M_reduced[i,k]=M_reduced[i,k]*
3176        - M{A[i,j,k,l]=A[k,l,i,j]}        - *A[i,j,k,l]=A[k,l,i,j]*
3177        - 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]*
3178        - M{B[i,j,k]=C[k,i,j]}        - *B[i,j,k]=C[k,i,j]*
3179        - M{B_reduced[i,j,k]=C_reduced[k,i,j]}        - *B_reduced[i,j,k]=C_reduced[k,i,j]*
3180        - M{D[i,k]=D[i,k]}        - *D[i,k]=D[i,k]*
3181        - M{D_reduced[i,k]=D_reduced[i,k]}        - *D_reduced[i,k]=D_reduced[i,k]*
3182        - M{m[i,k]=m[k,i]}        - *m[i,k]=m[k,i]*
3183        - M{m_reduced[i,k]=m_reduced[k,i]}        - *m_reduced[i,k]=m_reduced[k,i]*
3184        - M{d[i,k]=d[k,i]}        - *d[i,k]=d[k,i]*
3185        - M{d_reduced[i,k]=d_reduced[k,i]}        - *d_reduced[i,k]=d_reduced[k,i]*
3186    
3187     L{TransportPDE} also supports solution discontinuities over a contact region     `TransportPDE` also supports solution discontinuities over a contact region
3188     in the domain. To specify the conditions across the discontinuity we are     in the domain. To specify the conditions across the discontinuity we are
3189     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
3190     several components of the solution, is defined as     several components of the solution, is defined as
3191    
3192     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]*
3193    
3194     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
3195    
3196     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]*
3197    
3198     In the context of discontinuities M{n} denotes the normal on the     In the context of discontinuities *n* denotes the normal on the
3199     discontinuity pointing from side 0 towards side 1 calculated from     discontinuity pointing from side 0 towards side 1 calculated from
3200     L{getNormal<escript.FunctionSpace.getNormal>} of L{FunctionOnContactZero<escript.FunctionOnContactZero>}.     `FunctionSpace.getNormal` of `FunctionOnContactZero`.
3201     For a system of transport problems the contact condition takes the form     For a system of transport problems the contact condition takes the form
3202    
3203     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]*
3204    
3205     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
3206     discontinuity, respectively. M{jump(u)}, which is the difference of the     discontinuity, respectively. *jump(u)*, which is the difference of the
3207     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
3208     discontinuity along the normal calculated by L{jump<util.jump>}.     discontinuity along the normal calculated by `jump`.
3209     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
3210     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or L{FunctionOnContactOne<escript.FunctionOnContactOne>}.     both in `FunctionOnContactZero` or `FunctionOnContactOne`.
3211     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*
3212     is of rank one both in L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     is of rank one both in `ReducedFunctionOnContactZero` or `ReducedFunctionOnContactOne`.
3213     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
3214     condition takes the form     condition takes the form
3215    
3216     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)*
3217    
3218     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
3219     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
3220     L{FunctionOnContactOne<escript.FunctionOnContactOne>} and the coefficient     `FunctionOnContactOne` and the coefficient
3221     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
3222     L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or     `ReducedFunctionOnContactZero` or
3223     L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     `ReducedFunctionOnContactOne`.
3224    
3225     Typical usage::     Typical usage::
3226    
# Line 3219  class TransportPDE(LinearProblem): Line 3237  class TransportPDE(LinearProblem):
3237       """       """
3238       Initializes a transport problem.       Initializes a transport problem.
3239    
3240       @param domain: domain of the PDE       :param domain: domain of the PDE
3241       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
3242       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
3243                            equations is extracted from the coefficients.                            equations is extracted from the coefficients.
3244       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
3245                            of solution components is extracted from the                            of solution components is extracted from the
3246                            coefficients.                            coefficients.
3247       @param debug: if True debug information is printed       :param debug: if True debug information is printed
3248       @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.
3249       @type useBackwardEuler: C{bool}       :type useBackwardEuler: ``bool``
3250       """       """
3251       if useBackwardEuler:       if useBackwardEuler:
3252           self.__useBackwardEuler=True           self.__useBackwardEuler=True
# Line 3272  class TransportPDE(LinearProblem): Line 3290  class TransportPDE(LinearProblem):
3290       """       """
3291       Returns the string representation of the transport problem.       Returns the string representation of the transport problem.
3292    
3293       @return: a simple representation of the transport problem       :return: a simple representation of the transport problem
3294       @rtype: C{str}       :rtype: ``str``
3295       """       """
3296       return "<TransportPDE %d>"%id(self)       return "<TransportPDE %d>"%id(self)
3297    
3298     def useBackwardEuler(self):     def useBackwardEuler(self):
3299        """        """
3300        Returns true if backward Euler is used. Otherwise false is returned.        Returns true if backward Euler is used. Otherwise false is returned.
3301        @rtype: bool        :rtype: bool
3302        """        """
3303        return self.__useBackwardEuler        return self.__useBackwardEuler
3304    
# Line 3289  class TransportPDE(LinearProblem): Line 3307  class TransportPDE(LinearProblem):
3307        """        """
3308        Tests the transport problem for symmetry.        Tests the transport problem for symmetry.
3309    
3310        @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
3311                        which break the symmetry is printed.                        which break the symmetry is printed.
3312        @type verbose: C{bool}        :type verbose: ``bool``
3313        @return:  True if the PDE is symmetric        :return:  True if the PDE is symmetric
3314        @rtype: C{bool}        :rtype: ``bool``
3315        @note: This is a very expensive operation. It should be used for        :note: This is a very expensive operation. It should be used for
3316               degugging only! The symmetry flag is not altered.               degugging only! The symmetry flag is not altered.
3317        """        """
3318        out=True        out=True
# Line 3318  class TransportPDE(LinearProblem): Line 3336  class TransportPDE(LinearProblem):
3336        """        """
3337        Sets new values to coefficients.        Sets new values to coefficients.
3338    
3339        @param coefficients: new values assigned to coefficients        :param coefficients: new values assigned to coefficients
3340        @keyword M: value for coefficient C{M}        :keyword M: value for coefficient ``M``
3341        @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
3342                 L{Function<escript.Function>}                 `Function`
3343        @keyword M_reduced: value for coefficient C{M_reduced}        :keyword M_reduced: value for coefficient ``M_reduced``
3344        @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`
3345                         object on L{Function<escript.ReducedFunction>}                         object on `Function`
3346        @keyword A: value for coefficient C{A}        :keyword A: value for coefficient ``A``
3347        @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
3348                 L{Function<escript.Function>}                 `Function`
3349        @keyword A_reduced: value for coefficient C{A_reduced}        :keyword A_reduced: value for coefficient ``A_reduced``
3350        @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`
3351                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3352        @keyword B: value for coefficient C{B}        :keyword B: value for coefficient ``B``
3353        @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
3354                 L{Function<escript.Function>}                 `Function`
3355        @keyword B_reduced: value for coefficient C{B_reduced}        :keyword B_reduced: value for coefficient ``B_reduced``
3356        @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`
3357                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3358        @keyword C: value for coefficient C{C}        :keyword C: value for coefficient ``C``
3359        @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
3360                 L{Function<escript.Function>}                 `Function`
3361        @keyword C_reduced: value for coefficient C{C_reduced}        :keyword C_reduced: value for coefficient ``C_reduced``
3362        @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`
3363                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3364        @keyword D: value for coefficient C{D}        :keyword D: value for coefficient ``D``
3365        @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
3366                 L{Function<escript.Function>}                 `Function`
3367        @keyword D_reduced: value for coefficient C{D_reduced}        :keyword D_reduced: value for coefficient ``D_reduced``
3368        @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`
3369                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3370        @keyword X: value for coefficient C{X}        :keyword X: value for coefficient ``X``
3371        @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
3372                 L{Function<escript.Function>}                 `Function`
3373        @keyword X_reduced: value for coefficient C{X_reduced}        :keyword X_reduced: value for coefficient ``X_reduced``
3374        @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`
3375                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3376        @keyword Y: value for coefficient C{Y}        :keyword Y: value for coefficient ``Y``
3377        @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
3378                 L{Function<escript.Function>}                 `Function`
3379        @keyword Y_reduced: value for coefficient C{Y_reduced}        :keyword Y_reduced: value for coefficient ``Y_reduced``
3380        @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`
3381                         object on L{ReducedFunction<escript.Function>}                         object on `ReducedFunction`
3382        @keyword m: value for coefficient C{m}        :keyword m: value for coefficient ``m``
3383        @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
3384                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3385        @keyword m_reduced: value for coefficient C{m_reduced}        :keyword m_reduced: value for coefficient ``m_reduced``
3386        @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`
3387                         object on L{FunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `FunctionOnBoundary`
3388        @keyword d: value for coefficient C{d}        :keyword d: value for coefficient ``d``
3389        @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
3390                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3391        @keyword d_reduced: value for coefficient C{d_reduced}        :keyword d_reduced: value for coefficient ``d_reduced``
3392        @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`
3393                         object on L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `ReducedFunctionOnBoundary`
3394        @keyword y: value for coefficient C{y}        :keyword y: value for coefficient ``y``
3395        @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
3396                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3397        @keyword d_contact: value for coefficient C{d_contact}        :keyword d_contact: value for coefficient ``d_contact``
3398        @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`
3399                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>} or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         object on `FunctionOnContactOne` or `FunctionOnContactZero`
3400        @keyword d_contact_reduced: value for coefficient C{d_contact_reduced}        :keyword d_contact_reduced: value for coefficient ``d_contact_reduced``
3401        @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`
3402        @keyword y_contact: value for coefficient C{y_contact}        :keyword y_contact: value for coefficient ``y_contact``
3403        @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`
3404                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>} or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         object on `FunctionOnContactOne` or `FunctionOnContactZero`
3405        @keyword y_contact_reduced: value for coefficient C{y_contact_reduced}        :keyword y_contact_reduced: value for coefficient ``y_contact_reduced``
3406        @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`
3407        @keyword r: values prescribed to the solution at the locations of constraints        :keyword r: values prescribed to the solution at the locations of constraints
3408        @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
3409                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
3410                 depending on whether reduced order is used for the solution                 depending on whether reduced order is used for the solution
3411        @keyword q: mask for the location of constraints        :keyword q: mask for the location of constraints
3412        @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
3413                 L{Solution<escript.Solution>} or                 `Solution` or
3414                 L{ReducedSolution<escript.ReducedSolution>} depending on whether                 `ReducedSolution` depending on whether
3415                 reduced order is used for the representation of the equation                 reduced order is used for the representation of the equation
3416        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
3417        """        """
3418        super(TransportPDE,self).setValue(**coefficients)        super(TransportPDE,self).setValue(**coefficients)
3419    
# Line 3419  class TransportPDE(LinearProblem): Line 3437  class TransportPDE(LinearProblem):
3437         """         """
3438         Sets the initial solution.         Sets the initial solution.
3439    
3440         @param u: new initial solution         :param u: new initial solution
3441         @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`
3442                  object on L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                  object on `Solution` or `ReducedSolution`
3443         @note: C{u} must be non-negative         :note: ``u`` must be non-negative
3444         """         """
3445         u2=util.interpolate(u,self.getFunctionSpaceForSolution())         u2=util.interpolate(u,self.getFunctionSpaceForSolution())
3446         if self.getNumSolutions() == 1:         if self.getNumSolutions() == 1:
# Line 3437  class TransportPDE(LinearProblem): Line 3455  class TransportPDE(LinearProblem):
3455        """        """
3456        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.
3457    
3458        @return: a code to indicate the type of transport problem scheme used        :return: a code to indicate the type of transport problem scheme used
3459        @rtype: C{float}        :rtype: ``float``
3460        """        """
3461        solver_options=self.getSolverOptions()        solver_options=self.getSolverOptions()
3462        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())
3463    
3464     def getUnlimitedTimeStepSize(self):     def getUnlimitedTimeStepSize(self):
3465        """        """
3466        Returns the value returned by the C{getSafeTimeStepSize} method to        Returns the value returned by the ``getSafeTimeStepSize`` method to
3467        indicate no limit on the safe time step size.        indicate no limit on the safe time step size.
3468    
3469         @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
3470                  step size                  step size
3471         @rtype: C{float}         :rtype: ``float``
3472         @note: Typically the biggest positive float is returned         :note: Typically the biggest positive float is returned
3473        """        """
3474        return self.getOperator().getUnlimitedTimeStepSize()        return self.getOperator().getUnlimitedTimeStepSize()
3475    
# Line 3459  class TransportPDE(LinearProblem): Line 3477  class TransportPDE(LinearProblem):
3477         """         """
3478         Returns a safe time step size to do the next time step.         Returns a safe time step size to do the next time step.
3479    
3480         @return: safe time step size         :return: safe time step size
3481         @rtype: C{float}         :rtype: ``float``
3482         @note: If not C{getSafeTimeStepSize()} < C{getUnlimitedTimeStepSize()}         :note: If not ``getSafeTimeStepSize()`` < ``getUnlimitedTimeStepSize()``
3483                any time step size can be used.                any time step size can be used.
3484         """         """
3485         return self.getOperator().getSafeTimeStepSize()         return self.getOperator().getSafeTimeStepSize()
# Line 3470  class TransportPDE(LinearProblem): Line 3488  class TransportPDE(LinearProblem):
3488         """         """
3489         Sets the weighting factor used to insert the constraints into the problem         Sets the weighting factor used to insert the constraints into the problem
3490    
3491         @param value: value for the weighting factor         :param value: value for the weighting factor
3492         @type value: large positive C{float}         :type value: large positive ``float``
3493         """         """
3494         if not value>0:         if not value>0:
3495           raise ValueError,"weighting factor needs to be positive."           raise ValueError,"weighting factor needs to be positive."
# Line 3481  class TransportPDE(LinearProblem): Line 3499  class TransportPDE(LinearProblem):
3499     def getConstraintWeightingFactor(self):     def getConstraintWeightingFactor(self):
3500         """         """
3501         returns the weighting factor used to insert the constraints into the problem         returns the weighting factor used to insert the constraints into the problem
3502         @return: value for the weighting factor         :return: value for the weighting factor
3503         @rtype: C{float}         :rtype: ``float``
3504         """         """
3505         return self.__constraint_factor         return self.__constraint_factor
3506     #====================================================================     #====================================================================
# Line 3490  class TransportPDE(LinearProblem): Line 3508  class TransportPDE(LinearProblem):
3508         """         """
3509         Returns the solution of the problem.         Returns the solution of the problem.
3510    
3511         @return: the solution         :return: the solution
3512         @rtype: L{Data<escript.Data>}         :rtype: `Data`
3513         """         """
3514         option_class=self.getSolverOptions()         option_class=self.getSolverOptions()
3515         if dt<=0:         if dt<=0:
# Line 3504  class TransportPDE(LinearProblem): Line 3522  class TransportPDE(LinearProblem):
3522         """         """
3523         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
3524    
3525         @return: the discrete version of the PDE         :return: the discrete version of the PDE
3526         @rtype: C{tuple} of L{Operator,<escript.Operator>} and         :rtype: ``tuple`` of `Operator` and
3527                 L{Data<escript.Data>}                 `Data`
3528    
3529         """         """
3530         if not self.isOperatorValid() or not self.isRightHandSideValid():         if not self.isOperatorValid() or not self.isRightHandSideValid():
# Line 3552  class TransportPDE(LinearProblem): Line 3570  class TransportPDE(LinearProblem):
3570    
3571     def setDebug(self, flag):     def setDebug(self, flag):
3572       """       """
3573       Switches debug output on if C{flag} is True,       Switches debug output on if ``flag`` is True,
3574       otherwise it is switched off.       otherwise it is switched off.
3575    
3576       @param flag: desired debug status       :param flag: desired debug status
3577       @type flag: C{bool}       :type flag: ``bool``
3578       """       """
3579       if flag:       if flag:
3580           self.setDebugOn()           self.setDebugOn()

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

  ViewVC Help
Powered by ViewVC 1.1.26