/[escript]/branches/symbolic_from_3470/escript/py_src/linearPDEs.py
ViewVC logotype

Diff of /branches/symbolic_from_3470/escript/py_src/linearPDEs.py

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

revision 2624 by lgao, Thu Aug 6 03:09:03 2009 UTC revision 2625 by jfenwick, Fri Aug 21 06:30:25 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 REC_ILU: recursive ILU0
90      @cvar GAUSS_SEIDEL: Gauss-Seidel solver      :cvar RILU: relaxed ILU0
91      @cvar DEFAULT_REORDERING: the reordering method recommended by the solver      :cvar GAUSS_SEIDEL: Gauss-Seidel solver
92      @cvar SUPER_LU: the Super_LU solver package      :cvar DEFAULT_REORDERING: the reordering method recommended by the solver
93      @cvar PASTIX: the Pastix direct solver_package      :cvar SUPER_LU: the Super_LU solver package
94      @cvar YAIR_SHAPIRA_COARSENING: AMG coarsening method by Yair-Shapira      :cvar PASTIX: the Pastix direct solver_package
95      @cvar RUGE_STUEBEN_COARSENING: AMG coarsening method by Ruge and Stueben      :cvar YAIR_SHAPIRA_COARSENING: AMG coarsening method by Yair-Shapira
96      @cvar AGGREGATION_COARSENING: AMG coarsening using (symmetric) aggregation      :cvar RUGE_STUEBEN_COARSENING: AMG coarsening method by Ruge and Stueben
97      @cvar MIN_COARSE_MATRIX_SIZE: minimum size of the coarsest level matrix to use direct solver.      :cvar AGGREGATION_COARSENING: AMG coarsening using (symmetric) aggregation
98      @cvar NO_PRECONDITIONER: no preconditioner is applied.      :cvar MIN_COARSE_MATRIX_SIZE: minimum size of the coarsest level matrix to use direct solver.
99        :cvar NO_PRECONDITIONER: no preconditioner is applied.
100      """      """
101      DEFAULT= 0      DEFAULT= 0
102      DIRECT= 1      DIRECT= 1
# Line 209  class SolverOptions(object): Line 210  class SolverOptions(object):
210          """          """
211          returns the name of a given key          returns the name of a given key
212                    
213          @param key: a valid key          :param key: a valid key
214          """          """
215          if key == self.DEFAULT: return "DEFAULT"          if key == self.DEFAULT: return "DEFAULT"
216          if key == self.DIRECT: return "DIRECT"          if key == self.DIRECT: return "DIRECT"
# Line 253  class SolverOptions(object): Line 254  class SolverOptions(object):
254          """          """
255          resets the diagnostics          resets the diagnostics
256                    
257          @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.
258          @type all: C{bool}          :type all: ``bool``
259          """          """
260          self.__num_iter=None          self.__num_iter=None
261          self.__num_level=None          self.__num_level=None
# Line 275  class SolverOptions(object): Line 276  class SolverOptions(object):
276          """          """
277          Updates diagnostic information          Updates diagnostic information
278                    
279          @param name: name of  diagnostic information          :param name: name of  diagnostic information
280          @type name: C{str} in the list "num_iter", "num_level", "num_inner_iter", "time", "set_up_time", "net_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".
281          @param vale: new value of the diagnostic information          :param value: new value of the diagnostic information
282          @note: this function is used by a solver to report diagnostics informations.          :note: this function is used by a solver to report diagnostics informations.
283          """          """
284          if name == "num_iter":          if name == "num_iter":
285              self.__num_iter=int(value)              self.__num_iter=int(value)
# Line 303  class SolverOptions(object): Line 304  class SolverOptions(object):
304              self.__converged = (value == True)              self.__converged = (value == True)
305      def getDiagnostics(self, name):      def getDiagnostics(self, name):
306          """          """
307          Returns the diagnostic information C{name}          Returns the diagnostic information ``name``. Possible values are:
308                    
309          @param name: name of diagnostic information where      - "num_iter": the number of iteration steps
         - "num_iter": the number of iteration steps  
310          - "cum_num_iter": the cumulative number of iteration steps          - "cum_num_iter": the cumulative number of iteration steps
311          - "num_level": the number of level in multi level solver          - "num_level": the number of level in multi level solver
312          - "num_inner_iter": the number of inner iteration steps          - "num_inner_iter": the number of inner iteration steps
# Line 318  class SolverOptions(object): Line 318  class SolverOptions(object):
318          - "net_time": net execution time, excluding setup time for the solver and execution time for preconditioner          - "net_time": net execution time, excluding setup time for the solver and execution time for preconditioner
319          - "cum_net_time": cumulative net execution time          - "cum_net_time": cumulative net execution time
320          - "residual_norm": norm of the final residual          - "residual_norm": norm of the final residual
321          - "converged": return self.__converged              - "converged": return self.__converged
322          @type name: C{str} in the list "num_iter", "num_level", "num_inner_iter", "time", "set_up_time", "net_time", "residual_norm", "converged".      
323          @return: requested value. C{None} is returned if the value is undefined.      
324          @note: If the solver has thrown an exception diagnostic values have an undefined status.          
325            :param name: name of diagnostic information to return
326            :type name: ``str`` in the list above.
327            :return: requested value. ``None`` is returned if the value is undefined.
328            :note: If the solver has thrown an exception diagnostic values have an undefined status.
329          """          """
330          if name == "num_iter": return self.__num_iter          if name == "num_iter": return self.__num_iter
331          elif name == "cum_num_iter": return self.__cum_num_iter          elif name == "cum_num_iter": return self.__cum_num_iter
# Line 340  class SolverOptions(object): Line 344  class SolverOptions(object):
344              raise ValueError,"unknown diagnostic item %s"%name              raise ValueError,"unknown diagnostic item %s"%name
345      def hasConverged(self):      def hasConverged(self):
346          """          """
347          Returns C{True} if the last solver call has been finalized successfully.          Returns ``True`` if the last solver call has been finalized successfully.
348          @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.
349          """          """
350          return self.getDiagnostics("converged")          return self.getDiagnostics("converged")
351      def setCoarsening(self,method=0):      def setCoarsening(self,method=0):
352          """          """
353          Sets the key of the coarsening method to be applied in AMG.          Sets the key of the coarsening method to be applied in AMG.
354    
355          @param method: selects the coarsening method .          :param method: selects the coarsening method .
356          @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}  
357          """          """
358      if method==None: method=0      if method==None: method=0
359          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 361  class SolverOptions(object): Line 364  class SolverOptions(object):
364          """          """
365          Returns the key of the coarsening algorithm to be applied AMG.          Returns the key of the coarsening algorithm to be applied AMG.
366    
367          @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}  
368          """          """
369          return self.__coarsening          return self.__coarsening
370                
# Line 370  class SolverOptions(object): Line 372  class SolverOptions(object):
372          """          """
373          Sets the minumum size of the coarsest level matrix in AMG.          Sets the minumum size of the coarsest level matrix in AMG.
374    
375          @param size: minumum size of the coarsest level matrix .          :param size: minumum size of the coarsest level matrix .
376          @type size: positive C{int} or C{None}          :type size: positive ``int`` or ``None``
377          """          """
378          size=int(size)          size=int(size)
379          if size<0:          if size<0:
# Line 383  class SolverOptions(object): Line 385  class SolverOptions(object):
385          """          """
386          Returns the minumum size of the coarsest level matrix in AMG.          Returns the minumum size of the coarsest level matrix in AMG.
387    
388          @rtype: C{int}          :rtype: ``int``
389          """          """
390          return self.__MinCoarseMatrixSize          return self.__MinCoarseMatrixSize
391                
# Line 391  class SolverOptions(object): Line 393  class SolverOptions(object):
393          """          """
394          Sets the preconditioner to be used.          Sets the preconditioner to be used.
395    
396          @param preconditioner: key of the preconditioner to be used.          :param preconditioner: key of the preconditioner to be used.
397          @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`,
398                                      L{SolverOptions.AMG}, L{SolverOptions.REC_ILU}, L{SolverOptions.GAUSS_SEIDEL}, L{SolverOptions.RILU},                                      `SolverOptions.AMG`, `SolverOptions.REC_ILU`, `SolverOptions.GAUSS_SEIDEL`, `SolverOptions.RILU`,
399                                      L{SolverOptions.NO_PRECONDITIONER}                                      `SolverOptions.NO_PRECONDITIONER`
400          @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.  
401          """          """
402      if preconditioner==None: preconditioner=10      if preconditioner==None: preconditioner=10
403          if not preconditioner in [ SolverOptions.SSOR, SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI,          if not preconditioner in [ SolverOptions.SSOR, SolverOptions.ILU0, SolverOptions.ILUT, SolverOptions.JACOBI,
# Line 408  class SolverOptions(object): Line 409  class SolverOptions(object):
409          """          """
410          Returns key of the preconditioner to be used.          Returns key of the preconditioner to be used.
411    
412          @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`,
413                                      L{SolverOptions.AMG}, L{SolverOptions.REC_ILU}, L{SolverOptions.GAUSS_SEIDEL}, L{SolverOptions.RILU},                                      `SolverOptions.AMG`, `SolverOptions.REC_ILU`, `SolverOptions.GAUSS_SEIDEL`, `SolverOptions.RILU`,
414                                      L{SolverOptions.NO_PRECONDITIONER}                                      `SolverOptions.NO_PRECONDITIONER`
415          """          """
416          return self.__preconditioner          return self.__preconditioner
417      def setSolverMethod(self, method=0):      def setSolverMethod(self, method=0):
418          """          """
419          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
420          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
421          solver should be used.          solver should be used.
422    
423          @param method: key of the solver method to be used.          :param method: key of the solver method to be used.
424          @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`,
425                          L{SolverOptions.CR}, L{SolverOptions.CGS}, L{SolverOptions.BICGSTAB}, L{SolverOptions.SSOR},                          `SolverOptions.CR`, `SolverOptions.CGS`, `SolverOptions.BICGSTAB`, `SolverOptions.SSOR`,
426                          L{SolverOptions.GMRES}, L{SolverOptions.PRES20}, L{SolverOptions.LUMPING}, L{SolverOptions.ITERATIVE},                          `SolverOptions.GMRES`, `SolverOptions.PRES20`, `SolverOptions.LUMPING`, `SolverOptions.ITERATIVE`,
427                          L{SolverOptions.AMG}, L{SolverOptions.NONLINEAR_GMRES}, L{SolverOptions.TFQMR}, L{SolverOptions.MINRES},                          `SolverOptions.AMG`, `SolverOptions.NONLINEAR_GMRES`, `SolverOptions.TFQMR`, `SolverOptions.MINRES`,
428                          L{SolverOptions.GAUSS_SEIDEL}                          `SolverOptions.GAUSS_SEIDEL`
429          @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.  
430          """          """
431      if method==None: method=0      if method==None: method=0
432          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 439  class SolverOptions(object): Line 439  class SolverOptions(object):
439          """          """
440          Returns key of the solver method to be used.          Returns key of the solver method to be used.
441    
442          @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`,
443                          L{SolverOptions.CR}, L{SolverOptions.CGS}, L{SolverOptions.BICGSTAB}, L{SolverOptions.SSOR},                          `SolverOptions.CR`, `SolverOptions.CGS`, `SolverOptions.BICGSTAB`, `SolverOptions.SSOR`,
444                          L{SolverOptions.GMRES}, L{SolverOptions.PRES20}, L{SolverOptions.LUMPING}, L{SolverOptions.ITERATIVE},                          `SolverOptions.GMRES`, `SolverOptions.PRES20`, `SolverOptions.LUMPING`, `SolverOptions.ITERATIVE`,
445                          L{SolverOptions.AMG}, L{SolverOptions.NONLINEAR_GMRES}, L{SolverOptions.TFQMR}, L{SolverOptions.MINRES},                          `SolverOptions.AMG`, `SolverOptions.NONLINEAR_GMRES`, `SolverOptions.TFQMR`, `SolverOptions.MINRES`,
446                          L{SolverOptions.GAUSS_SEIDEL}                          `SolverOptions.GAUSS_SEIDEL`
447          """          """
448          return self.__method          return self.__method
449                    
# Line 451  class SolverOptions(object): Line 451  class SolverOptions(object):
451          """          """
452          Sets the solver package to be used as a solver.            Sets the solver package to be used as a solver.  
453    
454          @param package: key of the solver package to be used.          :param package: key of the solver package to be used.
455          @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`
456          @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.
457          """          """
458      if package==None: package=0      if package==None: package=0
459          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 463  class SolverOptions(object): Line 463  class SolverOptions(object):
463          """          """
464          Returns the solver package key          Returns the solver package key
465    
466          @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`
467          """          """
468          return self.__package          return self.__package
469      def setReordering(self,ordering=30):      def setReordering(self,ordering=30):
# Line 471  class SolverOptions(object): Line 471  class SolverOptions(object):
471          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
472          to optimize compute time and storage use during elimination.          to optimize compute time and storage use during elimination.
473    
474          @param ordering: selects the reordering strategy.          :param ordering: selects the reordering strategy.
475          @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}  
476          """          """
477          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]:
478               raise ValueError,"unknown reordering strategy %s"%ordering               raise ValueError,"unknown reordering strategy %s"%ordering
# Line 482  class SolverOptions(object): Line 481  class SolverOptions(object):
481          """          """
482          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.
483    
484          @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}  
485          """          """
486          return self.__reordering          return self.__reordering
487      def setRestart(self,restart=None):      def setRestart(self,restart=None):
488          """          """
489          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.
490    
491          @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.
492                          restart is performed.          :type restart: ``int`` or ``None``
         @type restart: C{int} or C{None}  
493          """          """
494          if restart == None:          if restart == None:
495              self.__restart=restart              self.__restart=restart
# Line 505  class SolverOptions(object): Line 502  class SolverOptions(object):
502      def getRestart(self):      def getRestart(self):
503          """          """
504          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.
505          If C{None} is returned no restart is performed.          If ``None`` is returned no restart is performed.
506    
507          @rtype: C{int} or C{None}          :rtype: ``int`` or ``None``
508          """          """
509          if self.__restart < 0:          if self.__restart < 0:
510              return None              return None
# Line 524  class SolverOptions(object): Line 521  class SolverOptions(object):
521          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
522          the faster GMRES converged but          the faster GMRES converged but
523    
524          @param truncation: truncation          :param truncation: truncation
525          @type truncation: C{int}          :type truncation: ``int``
526          """          """
527          truncation=int(truncation)          truncation=int(truncation)
528          if truncation<1:          if truncation<1:
# Line 535  class SolverOptions(object): Line 532  class SolverOptions(object):
532          """          """
533          Returns the number of residuals in GMRES to be stored for orthogonalization          Returns the number of residuals in GMRES to be stored for orthogonalization
534    
535          @rtype: C{int}          :rtype: ``int``
536          """          """
537          return self.__truncation          return self.__truncation
538      def setInnerIterMax(self,iter_max=10):      def setInnerIterMax(self,iter_max=10):
539          """          """
540          Sets the maximum number of iteration steps for the inner iteration.          Sets the maximum number of iteration steps for the inner iteration.
541    
542          @param iter_max: maximum number of inner iterations          :param iter_max: maximum number of inner iterations
543          @type iter_max: C{int}          :type iter_max: ``int``
544          """          """
545          iter_max=int(iter_max)          iter_max=int(iter_max)
546          if iter_max<1:          if iter_max<1:
# Line 553  class SolverOptions(object): Line 550  class SolverOptions(object):
550          """          """
551          Returns maximum number of inner iteration steps          Returns maximum number of inner iteration steps
552    
553          @rtype: C{int}          :rtype: ``int``
554          """          """
555          return self.__inner_iter_max          return self.__inner_iter_max
556      def setIterMax(self,iter_max=100000):      def setIterMax(self,iter_max=100000):
557          """          """
558          Sets the maximum number of iteration steps          Sets the maximum number of iteration steps
559    
560          @param iter_max: maximum number of iteration steps          :param iter_max: maximum number of iteration steps
561          @type iter_max: C{int}          :type iter_max: ``int``
562          """          """
563          iter_max=int(iter_max)          iter_max=int(iter_max)
564          if iter_max<1:          if iter_max<1:
# Line 571  class SolverOptions(object): Line 568  class SolverOptions(object):
568          """          """
569          Returns maximum number of iteration steps          Returns maximum number of iteration steps
570    
571          @rtype: C{int}          :rtype: ``int``
572          """          """
573          return self.__iter_max          return self.__iter_max
574      def setLevelMax(self,level_max=10):      def setLevelMax(self,level_max=10):
575          """          """
576          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
577    
578          @param level_max: maximum number of levels          :param level_max: maximum number of levels
579          @type level_max: C{int}          :type level_max: ``int``
580          """          """
581          level_max=int(level_max)          level_max=int(level_max)
582          if level_max<0:          if level_max<0:
# Line 589  class SolverOptions(object): Line 586  class SolverOptions(object):
586          """          """
587          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
588    
589          @rtype: C{int}          :rtype: ``int``
590          """          """
591          return self.__level_max          return self.__level_max
592      def setCoarseningThreshold(self,theta=0.05):      def setCoarseningThreshold(self,theta=0.05):
593          """          """
594          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
595    
596          @param theta: threshold for coarsening          :param theta: threshold for coarsening
597          @type theta: positive C{float}          :type theta: positive ``float``
598          """          """
599          theta=float(theta)          theta=float(theta)
600          if theta<0 or theta>1:          if theta<0 or theta>1:
# Line 607  class SolverOptions(object): Line 604  class SolverOptions(object):
604          """          """
605          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
606    
607          @rtype: C{float}          :rtype: ``float``
608          """          """
609          return self.__coarsening_threshold          return self.__coarsening_threshold
610      def setNumSweeps(self,sweeps=2):      def setNumSweeps(self,sweeps=2):
611          """          """
612          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.
613    
614          @param sweeps: number of sweeps          :param sweeps: number of sweeps
615          @type theta: positive C{int}          :type sweeps: positive ``int``
616          """          """
617          sweeps=int(sweeps)          sweeps=int(sweeps)
618          if sweeps<1:          if sweeps<1:
# Line 625  class SolverOptions(object): Line 622  class SolverOptions(object):
622          """          """
623          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.
624    
625          @rtype: C{int}          :rtype: ``int``
626          """          """
627          return self.__sweeps          return self.__sweeps
628      def setNumPreSweeps(self,sweeps=2):      def setNumPreSweeps(self,sweeps=2):
629          """          """
630          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
631    
632          @param sweeps: number of sweeps          :param sweeps: number of sweeps
633          @type theta: positive C{int}          :type sweeps: positive ``int``
634          """          """
635          sweeps=int(sweeps)          sweeps=int(sweeps)
636          if sweeps<1:          if sweeps<1:
# Line 643  class SolverOptions(object): Line 640  class SolverOptions(object):
640          """          """
641          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
642    
643          @rtype: C{int}          :rtype: ``int``
644          """          """
645          return self.__pre_sweeps          return self.__pre_sweeps
646      def setNumPostSweeps(self,sweeps=2):      def setNumPostSweeps(self,sweeps=2):
647          """          """
648          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
649    
650          @param sweeps: number of sweeps          :param sweeps: number of sweeps
651          @type theta: positive C{int}          :type sweeps: positive ``int``
652          """          """
653          sweeps=int(sweeps)          sweeps=int(sweeps)
654          if sweeps<1:          if sweeps<1:
# Line 661  class SolverOptions(object): Line 658  class SolverOptions(object):
658          """          """
659          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
660    
661          @rtype: C{int}          :rtype: ``int``
662          """          """
663          return self.__post_sweeps          return self.__post_sweeps
664    
# Line 669  class SolverOptions(object): Line 666  class SolverOptions(object):
666          """          """
667          Sets the relative tolerance for the solver          Sets the relative tolerance for the solver
668    
669          @param rtol: relative tolerance          :param rtol: relative tolerance
670          @type rtol: non-negative C{float}          :type rtol: non-negative ``float``
671          """          """
672          rtol=float(rtol)          rtol=float(rtol)
673          if rtol<0 or rtol>1:          if rtol<0 or rtol>1:
# Line 680  class SolverOptions(object): Line 677  class SolverOptions(object):
677          """          """
678          Returns the relative tolerance for the solver          Returns the relative tolerance for the solver
679    
680          @rtype: C{float}          :rtype: ``float``
681          """          """
682          return self.__tolerance          return self.__tolerance
683      def setAbsoluteTolerance(self,atol=0.):      def setAbsoluteTolerance(self,atol=0.):
684          """          """
685          Sets the absolute tolerance for the solver          Sets the absolute tolerance for the solver
686    
687          @param atol:  absolute tolerance          :param atol:  absolute tolerance
688          @type atol: non-negative C{float}          :type atol: non-negative ``float``
689          """          """
690          atol=float(atol)          atol=float(atol)
691          if atol<0:          if atol<0:
# Line 698  class SolverOptions(object): Line 695  class SolverOptions(object):
695          """          """
696          Returns the absolute tolerance for the solver          Returns the absolute tolerance for the solver
697    
698          @rtype: C{float}          :rtype: ``float``
699          """          """
700          return self.__absolute_tolerance          return self.__absolute_tolerance
701    
702      def setInnerTolerance(self,rtol=0.9):      def setInnerTolerance(self,rtol=0.9):
703          """          """
704           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.  
705    
706          @param rtol: inner relative tolerance          :param rtol: inner relative tolerance
707          @type rtol: positive C{float}          :type rtol: positive ``float``
708          """          """
709          rtol=float(rtol)          rtol=float(rtol)
710          if rtol<=0 or rtol>1:          if rtol<=0 or rtol>1:
# Line 718  class SolverOptions(object): Line 714  class SolverOptions(object):
714          """          """
715          Returns the relative tolerance for an inner iteration scheme          Returns the relative tolerance for an inner iteration scheme
716    
717          @rtype: C{float}          :rtype: ``float``
718          """          """
719          return self.__inner_tolerance          return self.__inner_tolerance
720      def setDropTolerance(self,drop_tol=0.01):      def setDropTolerance(self,drop_tol=0.01):
721          """          """
722          Sets the relative drop tolerance in ILUT          Sets the relative drop tolerance in ILUT
723    
724          @param drop_tol: drop tolerance          :param drop_tol: drop tolerance
725          @type drop_tol: positive C{float}          :type drop_tol: positive ``float``
726          """          """
727          drop_tol=float(drop_tol)          drop_tol=float(drop_tol)
728          if drop_tol<=0 or drop_tol>1:          if drop_tol<=0 or drop_tol>1:
# Line 736  class SolverOptions(object): Line 732  class SolverOptions(object):
732          """          """
733          Returns the relative drop tolerance in ILUT          Returns the relative drop tolerance in ILUT
734    
735          @rtype: C{float}          :rtype: ``float``
736          """          """
737          return self.__drop_tolerance          return self.__drop_tolerance
738      def setDropStorage(self,storage=2.):      def setDropStorage(self,storage=2.):
739          """          """
740          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
741          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.
742    
743          @param storage: allowed storage increase          :param storage: allowed storage increase
744          @type storage: C{float}          :type storage: ``float``
745          """          """
746          storage=float(storage)          storage=float(storage)
747          if storage<1:          if storage<1:
# Line 756  class SolverOptions(object): Line 752  class SolverOptions(object):
752          """          """
753          Returns the maximum allowed increase in storage for ILUT          Returns the maximum allowed increase in storage for ILUT
754    
755          @rtype: C{float}          :rtype: ``float``
756          """          """
757          return self.__drop_storage          return self.__drop_storage
758      def setRelaxationFactor(self,factor=0.3):      def setRelaxationFactor(self,factor=0.3):
759          """          """
760          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.
761    
762          @param factor: relaxation factor          :param factor: relaxation factor
763          @type factor: C{float}          :type factor: ``float``
764          @note: RILU with a relaxation factor 0 is identical to ILU0          :note: RILU with a relaxation factor 0 is identical to ILU0
765          """          """
766          factor=float(factor)          factor=float(factor)
767          if factor<0:          if factor<0:
# Line 776  class SolverOptions(object): Line 772  class SolverOptions(object):
772          """          """
773          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.
774    
775          @rtype: C{float}          :rtype: ``float``
776          """          """
777          return self.__relaxation          return self.__relaxation
778      def isSymmetric(self):      def isSymmetric(self):
779          """          """
780          Checks if symmetry of the  coefficient matrix is indicated.          Checks if symmetry of the  coefficient matrix is indicated.
781    
782          @return: True if a symmetric PDE is indicated, False otherwise          :return: True if a symmetric PDE is indicated, False otherwise
783          @rtype: C{bool}          :rtype: ``bool``
784          """          """
785          return self.__symmetric          return self.__symmetric
786      def setSymmetryOn(self):      def setSymmetryOn(self):
# Line 799  class SolverOptions(object): Line 795  class SolverOptions(object):
795          self.__symmetric=False          self.__symmetric=False
796      def setSymmetry(self,flag=False):      def setSymmetry(self,flag=False):
797          """          """
798          Sets the symmetry flag for the coefficient matrix to C{flag}.          Sets the symmetry flag for the coefficient matrix to ``flag``.
799    
800          @param flag: If True, the symmetry flag is set otherwise reset.          :param flag: If True, the symmetry flag is set otherwise reset.
801          @type flag: C{bool}          :type flag: ``bool``
802          """          """
803          if flag:          if flag:
804              self.setSymmetryOn()              self.setSymmetryOn()
# Line 810  class SolverOptions(object): Line 806  class SolverOptions(object):
806              self.setSymmetryOff()              self.setSymmetryOff()
807      def isVerbose(self):      def isVerbose(self):
808          """          """
809          Returns C{True} if the solver is expected to be verbose.          Returns ``True`` if the solver is expected to be verbose.
810    
811          @return: True if verbosity of switched on.          :return: True if verbosity of switched on.
812          @rtype: C{bool}          :rtype: ``bool``
813          """          """
814          return self.__verbose          return self.__verbose
815    
# Line 829  class SolverOptions(object): Line 825  class SolverOptions(object):
825          self.__verbose=False          self.__verbose=False
826      def setVerbosity(self,verbose=False):      def setVerbosity(self,verbose=False):
827          """          """
828          Sets the verbosity flag for the solver to C{flag}.          Sets the verbosity flag for the solver to ``flag``.
829    
830          @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.
831          @type flag: C{bool}          :type verbose: ``bool``
832          """          """
833          if verbose:          if verbose:
834              self.setVerbosityOn()              self.setVerbosityOn()
# Line 841  class SolverOptions(object): Line 837  class SolverOptions(object):
837                    
838      def adaptInnerTolerance(self):      def adaptInnerTolerance(self):
839          """          """
840          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.
841          Otherwise the inner tolerance set by L{setInnerTolerance} is used.          Otherwise the inner tolerance set by `setInnerTolerance` is used.
842    
843          @return: C{True} if inner tolerance adaption is chosen.          :return: ``True`` if inner tolerance adaption is chosen.
844          @rtype: C{bool}          :rtype: ``bool``
845          """          """
846          return self.__adapt_inner_tolerance          return self.__adapt_inner_tolerance
847    
# Line 863  class SolverOptions(object): Line 859  class SolverOptions(object):
859          """          """
860          Sets a flag to indicate automatic selection of the inner tolerance.          Sets a flag to indicate automatic selection of the inner tolerance.
861    
862          @param adapt: If C{True}, the inner tolerance is selected automatically.          :param adapt: If ``True``, the inner tolerance is selected automatically.
863          @type adapt: C{bool}          :type adapt: ``bool``
864          """          """
865          if adapt:          if adapt:
866              self.setInnerToleranceAdaptionOn()              self.setInnerToleranceAdaptionOn()
# Line 873  class SolverOptions(object): Line 869  class SolverOptions(object):
869    
870      def acceptConvergenceFailure(self):      def acceptConvergenceFailure(self):
871          """          """
872          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
873          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
874          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
875          continue even if the returned the solution does not necessarily meet the          continue even if the returned the solution does not necessarily meet the
876          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
877          last call to the solver was successful.          last call to the solver was successful.
878    
879          @return: C{True} if a failure to achieve convergence is accepted.          :return: ``True`` if a failure to achieve convergence is accepted.
880          @rtype: C{bool}          :rtype: ``bool``
881          """          """
882          return self.__accept_convergence_failure          return self.__accept_convergence_failure
883    
# Line 899  class SolverOptions(object): Line 895  class SolverOptions(object):
895          """          """
896          Sets a flag to indicate the acceptance of a failure of convergence.          Sets a flag to indicate the acceptance of a failure of convergence.
897    
898          @param accept: If C{True}, any failure to achieve convergence is accepted.          :param accept: If ``True``, any failure to achieve convergence is accepted.
899          @type accept: C{bool}          :type accept: ``bool``
900          """          """
901          if accept:          if accept:
902              self.setAcceptanceConvergenceFailureOn()              self.setAcceptanceConvergenceFailureOn()
# Line 936  class PDECoef(object): Line 932  class PDECoef(object):
932      """      """
933      A class for describing a PDE coefficient.      A class for describing a PDE coefficient.
934    
935      @cvar INTERIOR: indicator that coefficient is defined on the interior of      :cvar INTERIOR: indicator that coefficient is defined on the interior of
936                      the PDE domain                      the PDE domain
937      @cvar BOUNDARY: indicator that coefficient is defined on the boundary of      :cvar BOUNDARY: indicator that coefficient is defined on the boundary of
938                      the PDE domain                      the PDE domain
939      @cvar CONTACT: indicator that coefficient is defined on the contact region      :cvar CONTACT: indicator that coefficient is defined on the contact region
940                     within the PDE domain                     within the PDE domain
941      @cvar INTERIOR_REDUCED: indicator that coefficient is defined on the      :cvar INTERIOR_REDUCED: indicator that coefficient is defined on the
942                              interior of the PDE domain using a reduced                              interior of the PDE domain using a reduced
943                              integration order                              integration order
944      @cvar BOUNDARY_REDUCED: indicator that coefficient is defined on the      :cvar BOUNDARY_REDUCED: indicator that coefficient is defined on the
945                              boundary of the PDE domain using a reduced                              boundary of the PDE domain using a reduced
946                              integration order                              integration order
947      @cvar CONTACT_REDUCED: indicator that coefficient is defined on the contact      :cvar CONTACT_REDUCED: indicator that coefficient is defined on the contact
948                             region within the PDE domain using a reduced                             region within the PDE domain using a reduced
949                             integration order                             integration order
950      @cvar SOLUTION: indicator that coefficient is defined through a solution of      :cvar SOLUTION: indicator that coefficient is defined through a solution of
951                      the PDE                      the PDE
952      @cvar REDUCED: indicator that coefficient is defined through a reduced      :cvar REDUCED: indicator that coefficient is defined through a reduced
953                     solution of the PDE                     solution of the PDE
954      @cvar BY_EQUATION: indicator that the dimension of the coefficient shape is      :cvar BY_EQUATION: indicator that the dimension of the coefficient shape is
955                         defined by the number of PDE equations                         defined by the number of PDE equations
956      @cvar BY_SOLUTION: indicator that the dimension of the coefficient shape is      :cvar BY_SOLUTION: indicator that the dimension of the coefficient shape is
957                         defined by the number of PDE solutions                         defined by the number of PDE solutions
958      @cvar BY_DIM: indicator that the dimension of the coefficient shape is      :cvar BY_DIM: indicator that the dimension of the coefficient shape is
959                    defined by the spatial dimension                    defined by the spatial dimension
960      @cvar OPERATOR: indicator that the the coefficient alters the operator of      :cvar OPERATOR: indicator that the the coefficient alters the operator of
961                      the PDE                      the PDE
962      @cvar RIGHTHANDSIDE: indicator that the the coefficient alters the right      :cvar RIGHTHANDSIDE: indicator that the the coefficient alters the right
963                           hand side of the PDE                           hand side of the PDE
964      @cvar BOTH: indicator that the the coefficient alters the operator as well      :cvar BOTH: indicator that the the coefficient alters the operator as well
965                  as the right hand side of the PDE                  as the right hand side of the PDE
966    
967      """      """
# Line 988  class PDECoef(object): Line 984  class PDECoef(object):
984         """         """
985         Initialises a PDE coefficient type.         Initialises a PDE coefficient type.
986    
987         @param where: describes where the coefficient lives         :param where: describes where the coefficient lives
988         @type where: one of L{INTERIOR}, L{BOUNDARY}, L{CONTACT}, L{SOLUTION},         :type where: one of `INTERIOR`, `BOUNDARY`, `CONTACT`, `SOLUTION`,
989                      L{REDUCED}, L{INTERIOR_REDUCED}, L{BOUNDARY_REDUCED},                      `REDUCED`, `INTERIOR_REDUCED`, `BOUNDARY_REDUCED`,
990                      L{CONTACT_REDUCED}                      `CONTACT_REDUCED`
991         @param pattern: describes the shape of the coefficient and how the shape         :param pattern: describes the shape of the coefficient and how the shape
992                         is built for a given spatial dimension and numbers of                         is built for a given spatial dimension and numbers of
993                         equations and solutions in then PDE. For instance,                         equations and solutions in then PDE. For instance,
994                         (L{BY_EQUATION},L{BY_SOLUTION},L{BY_DIM}) describes a                         (`BY_EQUATION`,`BY_SOLUTION`,`BY_DIM`) describes a
995                         rank 3 coefficient which is instantiated as shape (3,2,2)                         rank 3 coefficient which is instantiated as shape (3,2,2)
996                         in case of three equations and two solution components                         in case of three equations and two solution components
997                         on a 2-dimensional domain. In the case of single equation                         on a 2-dimensional domain. In the case of single equation
998                         and a single solution component the shape components                         and a single solution component the shape components
999                         marked by L{BY_EQUATION} or L{BY_SOLUTION} are dropped.                         marked by `BY_EQUATION` or `BY_SOLUTION` are dropped.
1000                         In this case the example would be read as (2,).                         In this case the example would be read as (2,).
1001         @type pattern: C{tuple} of L{BY_EQUATION}, L{BY_SOLUTION}, L{BY_DIM}         :type pattern: ``tuple`` of `BY_EQUATION`, `BY_SOLUTION`, `BY_DIM`
1002         @param altering: indicates what part of the PDE is altered if the         :param altering: indicates what part of the PDE is altered if the
1003                          coefficient is altered                          coefficient is altered
1004         @type altering: one of L{OPERATOR}, L{RIGHTHANDSIDE}, L{BOTH}         :type altering: one of `OPERATOR`, `RIGHTHANDSIDE`, `BOTH`
1005         """         """
1006         super(PDECoef, self).__init__()         super(PDECoef, self).__init__()
1007         self.what=where         self.what=where
# Line 1021  class PDECoef(object): Line 1017  class PDECoef(object):
1017    
1018      def getFunctionSpace(self,domain,reducedEquationOrder=False,reducedSolutionOrder=False):      def getFunctionSpace(self,domain,reducedEquationOrder=False,reducedSolutionOrder=False):
1019         """         """
1020         Returns the L{FunctionSpace<escript.FunctionSpace>} of the coefficient.         Returns the `FunctionSpace` of the coefficient.
1021    
1022         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1023         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1024         @param reducedEquationOrder: True to indicate that reduced order is used         :param reducedEquationOrder: True to indicate that reduced order is used
1025                                      to represent the equation                                      to represent the equation
1026         @type reducedEquationOrder: C{bool}         :type reducedEquationOrder: ``bool``
1027         @param reducedSolutionOrder: True to indicate that reduced order is used         :param reducedSolutionOrder: True to indicate that reduced order is used
1028                                      to represent the solution                                      to represent the solution
1029         @type reducedSolutionOrder: C{bool}         :type reducedSolutionOrder: ``bool``
1030         @return: L{FunctionSpace<escript.FunctionSpace>} of the coefficient         :return: `FunctionSpace` of the coefficient
1031         @rtype: L{FunctionSpace<escript.FunctionSpace>}         :rtype: `FunctionSpace`
1032         """         """
1033         if self.what==self.INTERIOR:         if self.what==self.INTERIOR:
1034              return escript.Function(domain)              return escript.Function(domain)
# Line 1058  class PDECoef(object): Line 1054  class PDECoef(object):
1054         """         """
1055         Returns the value of the coefficient.         Returns the value of the coefficient.
1056    
1057         @return: value of the coefficient         :return: value of the coefficient
1058         @rtype: L{Data<escript.Data>}         :rtype: `Data`
1059         """         """
1060         return self.value         return self.value
1061    
# Line 1067  class PDECoef(object): Line 1063  class PDECoef(object):
1063         """         """
1064         Sets the value of the coefficient to a new value.         Sets the value of the coefficient to a new value.
1065    
1066         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1067         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1068         @param numEquations: number of equations of the PDE         :param numEquations: number of equations of the PDE
1069         @type numEquations: C{int}         :type numEquations: ``int``
1070         @param numSolutions: number of components of the PDE solution         :param numSolutions: number of components of the PDE solution
1071         @type numSolutions: C{int}         :type numSolutions: ``int``
1072         @param reducedEquationOrder: True to indicate that reduced order is used         :param reducedEquationOrder: True to indicate that reduced order is used
1073                                      to represent the equation                                      to represent the equation
1074         @type reducedEquationOrder: C{bool}         :type reducedEquationOrder: ``bool``
1075         @param reducedSolutionOrder: True to indicate that reduced order is used         :param reducedSolutionOrder: True to indicate that reduced order is used
1076                                      to represent the solution                                      to represent the solution
1077         @type reducedSolutionOrder: C{bool}         :type reducedSolutionOrder: ``bool``
1078         @param newValue: number of components of the PDE solution         :param newValue: number of components of the PDE solution
1079         @type newValue: any object that can be converted into a         :type newValue: any object that can be converted into a
1080                         L{Data<escript.Data>} object with the appropriate shape                         `Data` object with the appropriate shape
1081                         and L{FunctionSpace<escript.FunctionSpace>}                         and `FunctionSpace`
1082         @raise IllegalCoefficientValue: if the shape of the assigned value does         :raise IllegalCoefficientValue: if the shape of the assigned value does
1083                                         not match the shape of the coefficient                                         not match the shape of the coefficient
1084         @raise IllegalCoefficientFunctionSpace: if unable to interpolate value         :raise IllegalCoefficientFunctionSpace: if unable to interpolate value
1085                                                 to appropriate function space                                                 to appropriate function space
1086         """         """
1087         if newValue==None:         if newValue==None:
# Line 1108  class PDECoef(object): Line 1104  class PDECoef(object):
1104          """          """
1105          Checks if the coefficient alters the operator of the PDE.          Checks if the coefficient alters the operator of the PDE.
1106    
1107          @return: True if the operator of the PDE is changed when the          :return: True if the operator of the PDE is changed when the
1108                   coefficient is changed                   coefficient is changed
1109          @rtype: C{bool}          :rtype: ``bool``
1110          """          """
1111          if self.altering==self.OPERATOR or self.altering==self.BOTH:          if self.altering==self.OPERATOR or self.altering==self.BOTH:
1112              return not None              return not None
# Line 1121  class PDECoef(object): Line 1117  class PDECoef(object):
1117          """          """
1118          Checks if the coefficient alters the right hand side of the PDE.          Checks if the coefficient alters the right hand side of the PDE.
1119    
1120          @rtype: C{bool}          :rtype: ``bool``
1121          @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
1122                   coefficient is changed, C{None} otherwise.                   coefficient is changed, ``None`` otherwise.
1123          """          """
1124          if self.altering==self.RIGHTHANDSIDE or self.altering==self.BOTH:          if self.altering==self.RIGHTHANDSIDE or self.altering==self.BOTH:
1125              return not None              return not None
# Line 1135  class PDECoef(object): Line 1131  class PDECoef(object):
1131         Tries to estimate the number of equations and number of solutions if         Tries to estimate the number of equations and number of solutions if
1132         the coefficient has the given shape.         the coefficient has the given shape.
1133    
1134         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1135         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1136         @param shape: suggested shape of the coefficient         :param shape: suggested shape of the coefficient
1137         @type shape: C{tuple} of C{int} values         :type shape: ``tuple`` of ``int`` values
1138         @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
1139                  the coefficient has given shape. If no appropriate numbers                  the coefficient has given shape. If no appropriate numbers
1140                  could be identified, C{None} is returned                  could be identified, ``None`` is returned
1141         @rtype: C{tuple} of two C{int} values or C{None}         :rtype: ``tuple`` of two ``int`` values or ``None``
1142         """         """
1143         dim=domain.getDim()         dim=domain.getDim()
1144         if len(shape)>0:         if len(shape)>0:
# Line 1183  class PDECoef(object): Line 1179  class PDECoef(object):
1179         Checks if the coefficient allows to estimate the number of solution         Checks if the coefficient allows to estimate the number of solution
1180         components.         components.
1181    
1182         @return: True if the coefficient allows an estimate of the number of         :return: True if the coefficient allows an estimate of the number of
1183                  solution components, False otherwise                  solution components, False otherwise
1184         @rtype: C{bool}         :rtype: ``bool``
1185         """         """
1186         for i in self.pattern:         for i in self.pattern:
1187               if i==self.BY_SOLUTION: return True               if i==self.BY_SOLUTION: return True
# Line 1195  class PDECoef(object): Line 1191  class PDECoef(object):
1191         """         """
1192         Checks if the coefficient allows to estimate the number of equations.         Checks if the coefficient allows to estimate the number of equations.
1193    
1194         @return: True if the coefficient allows an estimate of the number of         :return: True if the coefficient allows an estimate of the number of
1195                  equations, False otherwise                  equations, False otherwise
1196         @rtype: C{bool}         :rtype: ``bool``
1197         """         """
1198         for i in self.pattern:         for i in self.pattern:
1199               if i==self.BY_EQUATION: return True               if i==self.BY_EQUATION: return True
# Line 1208  class PDECoef(object): Line 1204  class PDECoef(object):
1204        Compares two tuples of possible number of equations and number of        Compares two tuples of possible number of equations and number of
1205        solutions.        solutions.
1206    
1207        @param t1: the first tuple        :param t1: the first tuple
1208        @param t2: the second tuple        :param t2: the second tuple
1209        @return: 0, 1, or -1        :return: 0, 1, or -1
1210        """        """
1211    
1212        dif=t1[0]+t1[1]-(t2[0]+t2[1])        dif=t1[0]+t1[1]-(t2[0]+t2[1])
# Line 1222  class PDECoef(object): Line 1218  class PDECoef(object):
1218         """         """
1219         Builds the required shape of the coefficient.         Builds the required shape of the coefficient.
1220    
1221         @param domain: domain on which the PDE uses the coefficient         :param domain: domain on which the PDE uses the coefficient
1222         @type domain: L{Domain<escript.Domain>}         :type domain: `Domain`
1223         @param numEquations: number of equations of the PDE         :param numEquations: number of equations of the PDE
1224         @type numEquations: C{int}         :type numEquations: ``int``
1225         @param numSolutions: number of components of the PDE solution         :param numSolutions: number of components of the PDE solution
1226         @type numSolutions: C{int}         :type numSolutions: ``int``
1227         @return: shape of the coefficient         :return: shape of the coefficient
1228         @rtype: C{tuple} of C{int} values         :rtype: ``tuple`` of ``int`` values
1229         """         """
1230         dim=domain.getDim()         dim=domain.getDim()
1231         s=()         s=()
# Line 1247  class PDECoef(object): Line 1243  class PDECoef(object):
1243  class LinearProblem(object):  class LinearProblem(object):
1244     """     """
1245     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
1246     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
1247     L{Domain<escript.Domain>} object. The problem can be given as a single     `Domain` object. The problem can be given as a single
1248     equation or as a system of equations.     equation or as a system of equations.
1249    
1250     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
1251     a problem of the form     a problem of the form
1252    
1253     M{L u=f}     *L u=f*
1254    
1255     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
1256     problem will be solved to get the unknown M{u}.     problem will be solved to get the unknown *u*.
1257    
1258     """     """
1259     def __init__(self,domain,numEquations=None,numSolutions=None,debug=False):     def __init__(self,domain,numEquations=None,numSolutions=None,debug=False):
1260       """       """
1261       Initializes a linear problem.       Initializes a linear problem.
1262    
1263       @param domain: domain of the PDE       :param domain: domain of the PDE
1264       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
1265       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
1266                            equations is extracted from the coefficients.                            equations is extracted from the coefficients.
1267       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
1268                            of solution components is extracted from the                            of solution components is extracted from the
1269                            coefficients.                            coefficients.
1270       @param debug: if True debug information is printed       :param debug: if True debug information is printed
1271    
1272       """       """
1273       super(LinearProblem, self).__init__()       super(LinearProblem, self).__init__()
# Line 1301  class LinearProblem(object): Line 1297  class LinearProblem(object):
1297       """       """
1298       Returns a string representation of the PDE.       Returns a string representation of the PDE.
1299    
1300       @return: a simple representation of the PDE       :return: a simple representation of the PDE
1301       @rtype: C{str}       :rtype: ``str``
1302       """       """
1303       return "<LinearProblem %d>"%id(self)       return "<LinearProblem %d>"%id(self)
1304     # ==========================================================================     # ==========================================================================
# Line 1322  class LinearProblem(object): Line 1318  class LinearProblem(object):
1318    
1319     def setDebug(self, flag):     def setDebug(self, flag):
1320       """       """
1321       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.
1322    
1323       @param flag: desired debug status       :param flag: desired debug status
1324       @type flag: C{bool}       :type flag: ``bool``
1325       """       """
1326       if flag:       if flag:
1327           self.setDebugOn()           self.setDebugOn()
# Line 1336  class LinearProblem(object): Line 1332  class LinearProblem(object):
1332       """       """
1333       Prints the text message if debug mode is switched on.       Prints the text message if debug mode is switched on.
1334    
1335       @param text: message to be printed       :param text: message to be printed
1336       @type text: C{string}       :type text: ``string``
1337       """       """
1338       if self.__debug: print "%s: %s"%(str(self),text)       if self.__debug: print "%s: %s"%(str(self),text)
1339    
# Line 1348  class LinearProblem(object): Line 1344  class LinearProblem(object):
1344         """         """
1345         Introduces new coefficients into the problem.         Introduces new coefficients into the problem.
1346    
1347         Use::         Use:
1348    
1349         p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))         p.introduceCoefficients(A=PDECoef(...), B=PDECoef(...))
1350    
1351         to introduce the coefficients M{A} ans M{B}.         to introduce the coefficients *A* and *B*.
1352         """         """
1353         for name, type in coeff.items():         for name, type in coeff.items():
1354             if not isinstance(type,PDECoef):             if not isinstance(type,PDECoef):
# Line 1365  class LinearProblem(object): Line 1361  class LinearProblem(object):
1361       """       """
1362       Returns the domain of the PDE.       Returns the domain of the PDE.
1363    
1364       @return: the domain of the PDE       :return: the domain of the PDE
1365       @rtype: L{Domain<escript.Domain>}       :rtype: `Domain`
1366       """       """
1367       return self.__domain       return self.__domain
1368     def getDomainStatus(self):     def getDomainStatus(self):
# Line 1382  class LinearProblem(object): Line 1378  class LinearProblem(object):
1378       return self.__system_status       return self.__system_status
1379     def setSystemStatus(self,status=None):     def setSystemStatus(self,status=None):
1380       """       """
1381       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
1382       current status of the domain is used.       current status of the domain is used.
1383       """       """
1384       if status == None:       if status == None:
# Line 1394  class LinearProblem(object): Line 1390  class LinearProblem(object):
1390       """       """
1391       Returns the spatial dimension of the PDE.       Returns the spatial dimension of the PDE.
1392    
1393       @return: the spatial dimension of the PDE domain       :return: the spatial dimension of the PDE domain
1394       @rtype: C{int}       :rtype: ``int``
1395       """       """
1396       return self.getDomain().getDim()       return self.getDomain().getDim()
1397    
# Line 1403  class LinearProblem(object): Line 1399  class LinearProblem(object):
1399       """       """
1400       Returns the number of equations.       Returns the number of equations.
1401    
1402       @return: the number of equations       :return: the number of equations
1403       @rtype: C{int}       :rtype: ``int``
1404       @raise UndefinedPDEError: if the number of equations is not specified yet       :raise UndefinedPDEError: if the number of equations is not specified yet
1405       """       """
1406       if self.__numEquations==None:       if self.__numEquations==None:
1407           if self.__numSolutions==None:           if self.__numSolutions==None:
# Line 1418  class LinearProblem(object): Line 1414  class LinearProblem(object):
1414       """       """
1415       Returns the number of unknowns.       Returns the number of unknowns.
1416    
1417       @return: the number of unknowns       :return: the number of unknowns
1418       @rtype: C{int}       :rtype: ``int``
1419       @raise UndefinedPDEError: if the number of unknowns is not specified yet       :raise UndefinedPDEError: if the number of unknowns is not specified yet
1420       """       """
1421       if self.__numSolutions==None:       if self.__numSolutions==None:
1422          if self.__numEquations==None:          if self.__numEquations==None:
# Line 1433  class LinearProblem(object): Line 1429  class LinearProblem(object):
1429       """       """
1430       Returns the status of order reduction for the equation.       Returns the status of order reduction for the equation.
1431    
1432       @return: True if reduced interpolation order is used for the       :return: True if reduced interpolation order is used for the
1433                representation of the equation, False otherwise                representation of the equation, False otherwise
1434       @rtype: L{bool}       :rtype: `bool`
1435       """       """
1436       return self.__reduce_equation_order       return self.__reduce_equation_order
1437    
# Line 1443  class LinearProblem(object): Line 1439  class LinearProblem(object):
1439       """       """
1440       Returns the status of order reduction for the solution.       Returns the status of order reduction for the solution.
1441    
1442       @return: True if reduced interpolation order is used for the       :return: True if reduced interpolation order is used for the
1443                representation of the solution, False otherwise                representation of the solution, False otherwise
1444       @rtype: L{bool}       :rtype: `bool`
1445       """       """
1446       return self.__reduce_solution_order       return self.__reduce_solution_order
1447    
1448     def getFunctionSpaceForEquation(self):     def getFunctionSpaceForEquation(self):
1449       """       """
1450       Returns the L{FunctionSpace<escript.FunctionSpace>} used to discretize       Returns the `FunctionSpace` used to discretize
1451       the equation.       the equation.
1452    
1453       @return: representation space of equation       :return: representation space of equation
1454       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1455       """       """
1456       if self.reduceEquationOrder():       if self.reduceEquationOrder():
1457           return escript.ReducedSolution(self.getDomain())           return escript.ReducedSolution(self.getDomain())
# Line 1464  class LinearProblem(object): Line 1460  class LinearProblem(object):
1460    
1461     def getFunctionSpaceForSolution(self):     def getFunctionSpaceForSolution(self):
1462       """       """
1463       Returns the L{FunctionSpace<escript.FunctionSpace>} used to represent       Returns the `FunctionSpace` used to represent
1464       the solution.       the solution.
1465    
1466       @return: representation space of solution       :return: representation space of solution
1467       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1468       """       """
1469       if self.reduceSolutionOrder():       if self.reduceSolutionOrder():
1470           return escript.ReducedSolution(self.getDomain())           return escript.ReducedSolution(self.getDomain())
# Line 1482  class LinearProblem(object): Line 1478  class LinearProblem(object):
1478         """         """
1479         Sets the solver options.         Sets the solver options.
1480    
1481         @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.
1482         @type options: L{SolverOptions} or C{None}         :type options: `SolverOptions` or ``None``
1483         @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`.
1484         """         """
1485         if options==None:         if options==None:
1486            self.__solver_options=SolverOptions()            self.__solver_options=SolverOptions()
# Line 1498  class LinearProblem(object): Line 1494  class LinearProblem(object):
1494         """         """
1495         Returns the solver options         Returns the solver options
1496        
1497         @rtype: L{SolverOptions}         :rtype: `SolverOptions`
1498         """         """
1499         self.__solver_options.setSymmetry(self.__sym)         self.__solver_options.setSymmetry(self.__sym)
1500         return self.__solver_options         return self.__solver_options
# Line 1507  class LinearProblem(object): Line 1503  class LinearProblem(object):
1503        """        """
1504        Checks if matrix lumping is the current solver method.        Checks if matrix lumping is the current solver method.
1505    
1506        @return: True if the current solver method is lumping        :return: True if the current solver method is lumping
1507        @rtype: C{bool}        :rtype: ``bool``
1508        """        """
1509        return self.getSolverOptions().getSolverMethod()==self.getSolverOptions().LUMPING        return self.getSolverOptions().getSolverMethod()==self.getSolverOptions().LUMPING
1510     # ==========================================================================     # ==========================================================================
# Line 1518  class LinearProblem(object): Line 1514  class LinearProblem(object):
1514        """        """
1515        Checks if symmetry is indicated.        Checks if symmetry is indicated.
1516    
1517        @return: True if a symmetric PDE is indicated, False otherwise        :return: True if a symmetric PDE is indicated, False otherwise
1518        @rtype: C{bool}        :rtype: ``bool``
1519        @note: the method is equivalent to use getSolverOptions().isSymmetric()        :note: the method is equivalent to use getSolverOptions().isSymmetric()
1520        """        """
1521        self.getSolverOptions().isSymmetric()        self.getSolverOptions().isSymmetric()
1522    
1523     def setSymmetryOn(self):     def setSymmetryOn(self):
1524        """        """
1525        Sets the symmetry flag.        Sets the symmetry flag.
1526        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1527        """        """
1528        self.__sym=True        self.__sym=True
1529        self.getSolverOptions().setSymmetryOn()        self.getSolverOptions().setSymmetryOn()
# Line 1535  class LinearProblem(object): Line 1531  class LinearProblem(object):
1531     def setSymmetryOff(self):     def setSymmetryOff(self):
1532        """        """
1533        Clears the symmetry flag.        Clears the symmetry flag.
1534        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1535        """        """
1536        self.__sym=False        self.__sym=False
1537        self.getSolverOptions().setSymmetryOff()        self.getSolverOptions().setSymmetryOff()
1538    
1539     def setSymmetry(self,flag=False):     def setSymmetry(self,flag=False):
1540        """        """
1541        Sets the symmetry flag to C{flag}.        Sets the symmetry flag to ``flag``.
1542    
1543        @param flag: If True, the symmetry flag is set otherwise reset.        :param flag: If True, the symmetry flag is set otherwise reset.
1544        @type flag: C{bool}        :type flag: ``bool``
1545        @note: The method overwrites the symmetry flag set by the solver options        :note: The method overwrites the symmetry flag set by the solver options
1546        """        """
1547        self.getSolverOptions().setSymmetry(flag)        self.getSolverOptions().setSymmetry(flag)
1548     # ==========================================================================     # ==========================================================================
# Line 1556  class LinearProblem(object): Line 1552  class LinearProblem(object):
1552       """       """
1553       Switches reduced order on for solution and equation representation.       Switches reduced order on for solution and equation representation.
1554    
1555       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1556                            been set                            been set
1557       """       """
1558       self.setReducedOrderForSolutionOn()       self.setReducedOrderForSolutionOn()
# Line 1566  class LinearProblem(object): Line 1562  class LinearProblem(object):
1562       """       """
1563       Switches reduced order off for solution and equation representation       Switches reduced order off for solution and equation representation
1564    
1565       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1566                            been set                            been set
1567       """       """
1568       self.setReducedOrderForSolutionOff()       self.setReducedOrderForSolutionOff()
# Line 1577  class LinearProblem(object): Line 1573  class LinearProblem(object):
1573       Sets order reduction state for both solution and equation representation       Sets order reduction state for both solution and equation representation
1574       according to flag.       according to flag.
1575    
1576       @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
1577                    and equation representation, otherwise or if flag is not                    and equation representation, otherwise or if flag is not
1578                    present order reduction is switched off                    present order reduction is switched off
1579       @type flag: C{bool}       :type flag: ``bool``
1580       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1581                            been set                            been set
1582       """       """
1583       self.setReducedOrderForSolutionTo(flag)       self.setReducedOrderForSolutionTo(flag)
# Line 1592  class LinearProblem(object): Line 1588  class LinearProblem(object):
1588       """       """
1589       Switches reduced order on for solution representation.       Switches reduced order on for solution representation.
1590    
1591       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1592                            been set                            been set
1593       """       """
1594       if not self.__reduce_solution_order:       if not self.__reduce_solution_order:
# Line 1606  class LinearProblem(object): Line 1602  class LinearProblem(object):
1602       """       """
1603       Switches reduced order off for solution representation       Switches reduced order off for solution representation
1604    
1605       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1606                            been set.                            been set.
1607       """       """
1608       if self.__reduce_solution_order:       if self.__reduce_solution_order:
# Line 1620  class LinearProblem(object): Line 1616  class LinearProblem(object):
1616       """       """
1617       Sets order reduction state for solution representation according to flag.       Sets order reduction state for solution representation according to flag.
1618    
1619       @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
1620                    solution representation, otherwise or if flag is not present                    solution representation, otherwise or if flag is not present
1621                    order reduction is switched off                    order reduction is switched off
1622       @type flag: C{bool}       :type flag: ``bool``
1623       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1624                            been set                            been set
1625       """       """
1626       if flag:       if flag:
# Line 1636  class LinearProblem(object): Line 1632  class LinearProblem(object):
1632       """       """
1633       Switches reduced order on for equation representation.       Switches reduced order on for equation representation.
1634    
1635       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1636                            been set                            been set
1637       """       """
1638       if not self.__reduce_equation_order:       if not self.__reduce_equation_order:
# Line 1650  class LinearProblem(object): Line 1646  class LinearProblem(object):
1646       """       """
1647       Switches reduced order off for equation representation.       Switches reduced order off for equation representation.
1648    
1649       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1650                            been set                            been set
1651       """       """
1652       if self.__reduce_equation_order:       if self.__reduce_equation_order:
# Line 1664  class LinearProblem(object): Line 1660  class LinearProblem(object):
1660       """       """
1661       Sets order reduction state for equation representation according to flag.       Sets order reduction state for equation representation according to flag.
1662    
1663       @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
1664                    equation representation, otherwise or if flag is not present                    equation representation, otherwise or if flag is not present
1665                    order reduction is switched off                    order reduction is switched off
1666       @type flag: C{bool}       :type flag: ``bool``
1667       @raise RuntimeError: if order reduction is altered after a coefficient has       :raise RuntimeError: if order reduction is altered after a coefficient has
1668                            been set                            been set
1669       """       """
1670       if flag:       if flag:
# Line 1685  class LinearProblem(object): Line 1681  class LinearProblem(object):
1681        """        """
1682        Tests a coefficient for symmetry.        Tests a coefficient for symmetry.
1683    
1684        @param name: name of the coefficient        :param name: name of the coefficient
1685        @type name: C{str}        :type name: ``str``
1686        @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
1687                        which break the symmetry is printed.                        which break the symmetry is printed.
1688        @type verbose: C{bool}        :type verbose: ``bool``
1689        @return: True if coefficient C{name} is symmetric        :return: True if coefficient ``name`` is symmetric
1690        @rtype: C{bool}        :rtype: ``bool``
1691        """        """
1692        SMALL_TOLERANCE=util.EPSILON*10.        SMALL_TOLERANCE=util.EPSILON*10.
1693        A=self.getCoefficient(name)        A=self.getCoefficient(name)
# Line 1732  class LinearProblem(object): Line 1728  class LinearProblem(object):
1728        """        """
1729        Tests two coefficients for reciprocal symmetry.        Tests two coefficients for reciprocal symmetry.
1730    
1731        @param name0: name of the first coefficient        :param name0: name of the first coefficient
1732        @type name0: C{str}        :type name0: ``str``
1733        @param name1: name of the second coefficient        :param name1: name of the second coefficient
1734        @type name1: C{str}        :type name1: ``str``
1735        @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
1736                        which break the symmetry is printed                        which break the symmetry is printed
1737        @type verbose: C{bool}        :type verbose: ``bool``
1738        @return: True if coefficients C{name0} and C{name1} are reciprocally        :return: True if coefficients ``name0`` and ``name1`` are reciprocally
1739                 symmetric.                 symmetric.
1740        @rtype: C{bool}        :rtype: ``bool``
1741        """        """
1742        SMALL_TOLERANCE=util.EPSILON*10.        SMALL_TOLERANCE=util.EPSILON*10.
1743        B=self.getCoefficient(name0)        B=self.getCoefficient(name0)
# Line 1790  class LinearProblem(object): Line 1786  class LinearProblem(object):
1786    
1787     def getCoefficient(self,name):     def getCoefficient(self,name):
1788       """       """
1789       Returns the value of the coefficient C{name}.       Returns the value of the coefficient ``name``.
1790    
1791       @param name: name of the coefficient requested       :param name: name of the coefficient requested
1792       @type name: C{string}       :type name: ``string``
1793       @return: the value of the coefficient       :return: the value of the coefficient
1794       @rtype: L{Data<escript.Data>}       :rtype: `Data`
1795       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1796       """       """
1797       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1798           return self.__COEFFICIENTS[name].getValue()           return self.__COEFFICIENTS[name].getValue()
# Line 1805  class LinearProblem(object): Line 1801  class LinearProblem(object):
1801    
1802     def hasCoefficient(self,name):     def hasCoefficient(self,name):
1803       """       """
1804       Returns True if C{name} is the name of a coefficient.       Returns True if ``name`` is the name of a coefficient.
1805    
1806       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1807       @type name: C{string}       :type name: ``string``
1808       @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,
1809                False otherwise                False otherwise
1810       @rtype: C{bool}       :rtype: ``bool``
1811       """       """
1812       return self.__COEFFICIENTS.has_key(name)       return self.__COEFFICIENTS.has_key(name)
1813    
1814     def createCoefficient(self, name):     def createCoefficient(self, name):
1815       """       """
1816       Creates a L{Data<escript.Data>} object corresponding to coefficient       Creates a `Data` object corresponding to coefficient
1817       C{name}.       ``name``.
1818    
1819       @return: the coefficient C{name} initialized to 0       :return: the coefficient ``name`` initialized to 0
1820       @rtype: L{Data<escript.Data>}       :rtype: `Data`
1821       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1822       """       """
1823       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1824          return escript.Data(0.,self.getShapeOfCoefficient(name),self.getFunctionSpaceForCoefficient(name))          return escript.Data(0.,self.getShapeOfCoefficient(name),self.getFunctionSpaceForCoefficient(name))
# Line 1831  class LinearProblem(object): Line 1827  class LinearProblem(object):
1827    
1828     def getFunctionSpaceForCoefficient(self,name):     def getFunctionSpaceForCoefficient(self,name):
1829       """       """
1830       Returns the L{FunctionSpace<escript.FunctionSpace>} to be used for       Returns the `FunctionSpace` to be used for
1831       coefficient C{name}.       coefficient ``name``.
1832    
1833       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1834       @type name: C{string}       :type name: ``string``
1835       @return: the function space to be used for coefficient C{name}       :return: the function space to be used for coefficient ``name``
1836       @rtype: L{FunctionSpace<escript.FunctionSpace>}       :rtype: `FunctionSpace`
1837       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1838       """       """
1839       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1840          return self.__COEFFICIENTS[name].getFunctionSpace(self.getDomain())          return self.__COEFFICIENTS[name].getFunctionSpace(self.getDomain())
# Line 1847  class LinearProblem(object): Line 1843  class LinearProblem(object):
1843    
1844     def getShapeOfCoefficient(self,name):     def getShapeOfCoefficient(self,name):
1845       """       """
1846       Returns the shape of the coefficient C{name}.       Returns the shape of the coefficient ``name``.
1847    
1848       @param name: name of the coefficient enquired       :param name: name of the coefficient enquired
1849       @type name: C{string}       :type name: ``string``
1850       @return: the shape of the coefficient C{name}       :return: the shape of the coefficient ``name``
1851       @rtype: C{tuple} of C{int}       :rtype: ``tuple`` of ``int``
1852       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1853       """       """
1854       if self.hasCoefficient(name):       if self.hasCoefficient(name):
1855          return self.__COEFFICIENTS[name].getShape(self.getDomain(),self.getNumEquations(),self.getNumSolutions())          return self.__COEFFICIENTS[name].getShape(self.getDomain(),self.getNumEquations(),self.getNumSolutions())
# Line 1869  class LinearProblem(object): Line 1865  class LinearProblem(object):
1865    
1866     def alteredCoefficient(self,name):     def alteredCoefficient(self,name):
1867       """       """
1868       Announces that coefficient C{name} has been changed.       Announces that coefficient ``name`` has been changed.
1869    
1870       @param name: name of the coefficient affected       :param name: name of the coefficient affected
1871       @type name: C{string}       :type name: ``string``
1872       @raise IllegalCoefficient: if C{name} is not a coefficient of the PDE       :raise IllegalCoefficient: if ``name`` is not a coefficient of the PDE
1873       @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
1874              system as constraints are applied to the solved system.              system as constraints are applied to the solved system.
1875       """       """
1876       if self.hasCoefficient(name):       if self.hasCoefficient(name):
# Line 1981  class LinearProblem(object): Line 1977  class LinearProblem(object):
1977       """       """
1978       Returns the operator of the linear problem.       Returns the operator of the linear problem.
1979    
1980       @return: the operator of the problem       :return: the operator of the problem
1981       """       """
1982       return self.getSystem()[0]       return self.getSystem()[0]
1983    
# Line 1989  class LinearProblem(object): Line 1985  class LinearProblem(object):
1985       """       """
1986       Returns the right hand side of the linear problem.       Returns the right hand side of the linear problem.
1987    
1988       @return: the right hand side of the problem       :return: the right hand side of the problem
1989       @rtype: L{Data<escript.Data>}       :rtype: `Data`
1990       """       """
1991       return self.getSystem()[1]       return self.getSystem()[1]
1992    
# Line 2090  class LinearProblem(object): Line 2086  class LinearProblem(object):
2086        """        """
2087        Sets new values to coefficients.        Sets new values to coefficients.
2088    
2089        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
2090        """        """
2091        # check if the coefficients are  legal:        # check if the coefficients are  legal:
2092        for i in coefficients.iterkeys():        for i in coefficients.iterkeys():
# Line 2149  class LinearProblem(object): Line 2145  class LinearProblem(object):
2145        """        """
2146        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.
2147    
2148        @note: Typically this method is overwritten when implementing a        :note: Typically this method is overwritten when implementing a
2149               particular linear problem.               particular linear problem.
2150        """        """
2151        return None        return None
# Line 2158  class LinearProblem(object): Line 2154  class LinearProblem(object):
2154         """         """
2155         Returns an instance of a new operator.         Returns an instance of a new operator.
2156    
2157         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2158                linear problem.                linear problem.
2159         """         """
2160         return escript.Operator()         return escript.Operator()
# Line 2167  class LinearProblem(object): Line 2163  class LinearProblem(object):
2163        """        """
2164        Tests the PDE for symmetry.        Tests the PDE for symmetry.
2165    
2166        @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
2167                        which break the symmetry is printed                        which break the symmetry is printed
2168        @type verbose: C{bool}        :type verbose: ``bool``
2169        @return: True if the problem is symmetric        :return: True if the problem is symmetric
2170        @rtype: C{bool}        :rtype: ``bool``
2171        @note: Typically this method is overwritten when implementing a        :note: Typically this method is overwritten when implementing a
2172               particular linear problem.               particular linear problem.
2173        """        """
2174        out=True        out=True
# Line 2182  class LinearProblem(object): Line 2178  class LinearProblem(object):
2178         """         """
2179         Returns the solution of the problem.         Returns the solution of the problem.
2180    
2181         @return: the solution         :return: the solution
2182         @rtype: L{Data<escript.Data>}         :rtype: `Data`
2183    
2184         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2185                linear problem.                linear problem.
2186         """         """
2187         return self.getCurrentSolution()         return self.getCurrentSolution()
# Line 2194  class LinearProblem(object): Line 2190  class LinearProblem(object):
2190         """         """
2191         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
2192    
2193         @return: the discrete version of the PDE         :return: the discrete version of the PDE
2194         @rtype: C{tuple} of L{Operator,<escript.Operator>} and L{Data<escript.Data>}.         :rtype: ``tuple`` of `Operator` and `Data`.
2195    
2196         @note: This method is overwritten when implementing a particular         :note: This method is overwritten when implementing a particular
2197                linear problem.                linear problem.
2198         """         """
2199         return (self.getCurrentOperator(), self.getCurrentRightHandSide())         return (self.getCurrentOperator(), self.getCurrentRightHandSide())
# Line 2205  class LinearProblem(object): Line 2201  class LinearProblem(object):
2201  class LinearPDE(LinearProblem):  class LinearPDE(LinearProblem):
2202     """     """
2203     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
2204     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
2205     L{Domain<escript.Domain>} object.     `Domain` object.
2206    
2207     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
2208     is defined in the following form:     is defined in the following form:
2209    
2210     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)*
2211    
2212     where M{grad(F)} denotes the spatial derivative of M{F}. Einstein's     where *grad(F)* denotes the spatial derivative of *F*. Einstein's
2213     summation convention, ie. summation over indexes appearing twice in a term     summation convention, ie. summation over indexes appearing twice in a term
2214     of a sum performed, is used.     of a sum performed, is used.
2215     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
2216     through L{Data<escript.Data>} objects in L{Function<escript.Function>} and     through `Data` objects in `Function` and
2217     the coefficients M{A_reduced}, M{B_reduced}, M{C_reduced}, M{D_reduced},     the coefficients *A_reduced*, *B_reduced*, *C_reduced*, *D_reduced*,
2218     M{X_reduced} and M{Y_reduced} have to be specified through     *X_reduced* and *Y_reduced* have to be specified through
2219     L{Data<escript.Data>} objects in L{ReducedFunction<escript.ReducedFunction>}.     `Data` objects in `ReducedFunction`.
2220     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
2221     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*,
2222     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
2223     M{D}, M{D_reduced}, M{Y} and M{Y_reduced} are scalar.     *D*, *D_reduced*, *Y* and *Y_reduced* are scalar.
2224    
2225     The following natural boundary conditions are considered:     The following natural boundary conditions are considered:
2226    
2227     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*
2228    
2229     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*,
2230     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
2231     PDE. The coefficients M{d} and M{y} are each a scalar in     PDE. The coefficients *d* and *y* are each a scalar in
2232     L{FunctionOnBoundary<escript.FunctionOnBoundary>} and the coefficients     `FunctionOnBoundary` and the coefficients
2233     M{d_reduced} and M{y_reduced} are each a scalar in     *d_reduced* and *y_reduced* are each a scalar in
2234     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
2235    
2236     Constraints for the solution prescribe the value of the solution at certain     Constraints for the solution prescribe the value of the solution at certain
2237     locations in the domain. They have the form     locations in the domain. They have the form
2238    
2239     M{u=r} where M{q>0}     *u=r* where *q>0*
2240    
2241     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
2242     defining where the constraint is applied. The constraints override any     defining where the constraint is applied. The constraints override any
2243     other condition set by the PDE or the boundary condition.     other condition set by the PDE or the boundary condition.
2244    
2245     The PDE is symmetrical if     The PDE is symmetrical if
2246    
2247     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]*
2248     and M{B_reduced[j]=C_reduced[j]}     and *B_reduced[j]=C_reduced[j]*
2249    
2250     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
2251     form     form
2252    
2253     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]*
2254    
2255     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
2256     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
2257     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.
2258     The natural boundary conditions take the form:     The natural boundary conditions take the form:
2259    
2260     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]*
2261    
2262     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
2263     L{FunctionOnBoundary<escript.FunctionOnBoundary>}. The coefficients     `FunctionOnBoundary`. The coefficients
2264     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
2265     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
2266    
2267     Constraints take the form     Constraints take the form
2268    
2269     M{u[i]=r[i]}  where  M{q[i]>0}     *u[i]=r[i]*  where  *q[i]>0*
2270    
2271     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
2272     necessarily all components must have a constraint.     necessarily all components must have a constraint.
2273    
2274     The system of PDEs is symmetrical if     The system of PDEs is symmetrical if
2275    
2276        - M{A[i,j,k,l]=A[k,l,i,j]}        - *A[i,j,k,l]=A[k,l,i,j]*
2277        - 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]*
2278        - M{B[i,j,k]=C[k,i,j]}        - *B[i,j,k]=C[k,i,j]*
2279        - M{B_reduced[i,j,k]=C_reduced[k,i,j]}        - *B_reduced[i,j,k]=C_reduced[k,i,j]*
2280        - M{D[i,k]=D[i,k]}        - *D[i,k]=D[i,k]*
2281        - M{D_reduced[i,k]=D_reduced[i,k]}        - *D_reduced[i,k]=D_reduced[i,k]*
2282        - M{d[i,k]=d[k,i]}        - *d[i,k]=d[k,i]*
2283        - M{d_reduced[i,k]=d_reduced[k,i]}        - *d_reduced[i,k]=d_reduced[k,i]*
2284    
2285     L{LinearPDE} also supports solution discontinuities over a contact region     `LinearPDE` also supports solution discontinuities over a contact region
2286     in the domain. To specify the conditions across the discontinuity we are     in the domain. To specify the conditions across the discontinuity we are
2287     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
2288     and several components of the solution, is defined as     and several components of the solution, is defined as
2289    
2290     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]*
2291    
2292     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
2293    
2294     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]*
2295    
2296     In the context of discontinuities M{n} denotes the normal on the     In the context of discontinuities *n* denotes the normal on the
2297     discontinuity pointing from side 0 towards side 1 calculated from     discontinuity pointing from side 0 towards side 1 calculated from
2298     L{getNormal<escript.FunctionSpace.getNormal>} of L{FunctionOnContactZero<escript.FunctionOnContactZero>}.     `FunctionSpace.getNormal` of `FunctionOnContactZero`.
2299     For a system of PDEs the contact condition takes the form     For a system of PDEs the contact condition takes the form
2300    
2301     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]*
2302    
2303     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
2304     discontinuity, respectively. M{jump(u)}, which is the difference of the     discontinuity, respectively. *jump(u)*, which is the difference of the
2305     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
2306     discontinuity along the normal calculated by L{jump<util.jump>}.     discontinuity along the normal calculated by `jump`.
2307     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
2308     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
2309     L{FunctionOnContactOne<escript.FunctionOnContactOne>}.     `FunctionOnContactOne`.
2310     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*
2311     is of rank one both in L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>}     is of rank one both in `ReducedFunctionOnContactZero`
2312     or L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     or `ReducedFunctionOnContactOne`.
2313     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
2314     condition takes the form     condition takes the form
2315    
2316     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)*
2317    
2318     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
2319     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
2320     L{FunctionOnContactOne<escript.FunctionOnContactOne>} and the coefficient     `FunctionOnContactOne` and the coefficient
2321     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
2322     L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or     `ReducedFunctionOnContactZero` or
2323     L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     `ReducedFunctionOnContactOne`.
2324    
2325     Typical usage::     Typical usage::
2326    
# Line 2338  class LinearPDE(LinearProblem): Line 2334  class LinearPDE(LinearProblem):
2334       """       """
2335       Initializes a new linear PDE.       Initializes a new linear PDE.
2336    
2337       @param domain: domain of the PDE       :param domain: domain of the PDE
2338       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2339       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
2340                            equations is extracted from the PDE coefficients.                            equations is extracted from the PDE coefficients.
2341       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
2342                            of solution components is extracted from the PDE                            of solution components is extracted from the PDE
2343                            coefficients.                            coefficients.
2344       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2345    
2346       """       """
2347       super(LinearPDE, self).__init__(domain,numEquations,numSolutions,debug)       super(LinearPDE, self).__init__(domain,numEquations,numSolutions,debug)
# Line 2380  class LinearPDE(LinearProblem): Line 2376  class LinearPDE(LinearProblem):
2376       """       """
2377       Returns the string representation of the PDE.       Returns the string representation of the PDE.
2378    
2379       @return: a simple representation of the PDE       :return: a simple representation of the PDE
2380       @rtype: C{str}       :rtype: ``str``
2381       """       """
2382       return "<LinearPDE %d>"%id(self)       return "<LinearPDE %d>"%id(self)
2383    
# Line 2396  class LinearPDE(LinearProblem): Line 2392  class LinearPDE(LinearProblem):
2392        """        """
2393        Tests the PDE for symmetry.        Tests the PDE for symmetry.
2394    
2395        @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
2396                        which break the symmetry is printed.                        which break the symmetry is printed.
2397        @type verbose: C{bool}        :type verbose: ``bool``
2398        @return: True if the PDE is symmetric        :return: True if the PDE is symmetric
2399        @rtype: L{bool}        :rtype: `bool`
2400        @note: This is a very expensive operation. It should be used for        :note: This is a very expensive operation. It should be used for
2401               degugging only! The symmetry flag is not altered.               degugging only! The symmetry flag is not altered.
2402        """        """
2403        out=True        out=True
# Line 2434  class LinearPDE(LinearProblem): Line 2430  class LinearPDE(LinearProblem):
2430         """         """
2431         Returns the solution of the PDE.         Returns the solution of the PDE.
2432    
2433         @return: the solution         :return: the solution
2434         @rtype: L{Data<escript.Data>}         :rtype: `Data`
2435         """         """
2436         option_class=self.getSolverOptions()         option_class=self.getSolverOptions()
2437         if not self.isSolutionValid():         if not self.isSolutionValid():
# Line 2452  class LinearPDE(LinearProblem): Line 2448  class LinearPDE(LinearProblem):
2448         """         """
2449         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
2450    
2451         @return: the discrete version of the PDE         :return: the discrete version of the PDE
2452         @rtype: C{tuple} of L{Operator,<escript.Operator>} and         :rtype: ``tuple`` of `Operator` and
2453                 L{Data<escript.Data>}                 `Data`
2454         """         """
2455         if not self.isOperatorValid() or not self.isRightHandSideValid():         if not self.isOperatorValid() or not self.isRightHandSideValid():
2456            if self.isUsingLumping():            if self.isUsingLumping():
# Line 2629  class LinearPDE(LinearProblem): Line 2625  class LinearPDE(LinearProblem):
2625        """        """
2626        Applies the constraints defined by q and r to the PDE.        Applies the constraints defined by q and r to the PDE.
2627    
2628        @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
2629                         constraint                         constraint
2630        @type rhs_only: C{bool}        :type rhs_only: ``bool``
2631        """        """
2632        q=self.getCoefficient("q")        q=self.getCoefficient("q")
2633        r=self.getCoefficient("r")        r=self.getCoefficient("r")
# Line 2659  class LinearPDE(LinearProblem): Line 2655  class LinearPDE(LinearProblem):
2655        """        """
2656        Sets new values to coefficients.        Sets new values to coefficients.
2657    
2658        @param coefficients: new values assigned to coefficients        :param coefficients: new values assigned to coefficients
2659        @keyword A: value for coefficient C{A}        :keyword A: value for coefficient ``A``
2660        @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
2661                 L{Function<escript.Function>}                 `Function`
2662        @keyword A_reduced: value for coefficient C{A_reduced}        :keyword A_reduced: value for coefficient ``A_reduced``
2663        @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`
2664                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2665        @keyword B: value for coefficient C{B}        :keyword B: value for coefficient ``B``
2666        @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
2667                 L{Function<escript.Function>}                 `Function`
2668        @keyword B_reduced: value for coefficient C{B_reduced}        :keyword B_reduced: value for coefficient ``B_reduced``
2669        @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`
2670                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2671        @keyword C: value for coefficient C{C}        :keyword C: value for coefficient ``C``
2672        @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
2673                 L{Function<escript.Function>}                 `Function`
2674        @keyword C_reduced: value for coefficient C{C_reduced}        :keyword C_reduced: value for coefficient ``C_reduced``
2675        @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`
2676                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2677        @keyword D: value for coefficient C{D}        :keyword D: value for coefficient ``D``
2678        @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
2679                 L{Function<escript.Function>}                 `Function`
2680        @keyword D_reduced: value for coefficient C{D_reduced}        :keyword D_reduced: value for coefficient ``D_reduced``
2681        @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`
2682                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2683        @keyword X: value for coefficient C{X}        :keyword X: value for coefficient ``X``
2684        @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
2685                 L{Function<escript.Function>}                 `Function`
2686        @keyword X_reduced: value for coefficient C{X_reduced}        :keyword X_reduced: value for coefficient ``X_reduced``
2687        @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`
2688                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
2689        @keyword Y: value for coefficient C{Y}        :keyword Y: value for coefficient ``Y``
2690        @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
2691                 L{Function<escript.Function>}                 `Function`
2692        @keyword Y_reduced: value for coefficient C{Y_reduced}        :keyword Y_reduced: value for coefficient ``Y_reduced``
2693        @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`
2694                         object on L{ReducedFunction<escript.Function>}                         object on `ReducedFunction`
2695        @keyword d: value for coefficient C{d}        :keyword d: value for coefficient ``d``
2696        @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
2697                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
2698        @keyword d_reduced: value for coefficient C{d_reduced}        :keyword d_reduced: value for coefficient ``d_reduced``
2699        @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`
2700                         object on L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `ReducedFunctionOnBoundary`
2701        @keyword y: value for coefficient C{y}        :keyword y: value for coefficient ``y``
2702        @type y: any type that can be cast to a L{Data<escript.Data>} object on        :type y: any type that can be cast to a `Data` object on
2703                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
2704        @keyword d_contact: value for coefficient C{d_contact}        :keyword d_contact: value for coefficient ``d_contact``
2705        @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`
2706                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>}                         object on `FunctionOnContactOne`
2707                         or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         or `FunctionOnContactZero`
2708        @keyword d_contact_reduced: value for coefficient C{d_contact_reduced}        :keyword d_contact_reduced: value for coefficient ``d_contact_reduced``
2709        @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`
2710                                 object on L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}                                 object on `ReducedFunctionOnContactOne`
2711                                 or L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>}                                 or `ReducedFunctionOnContactZero`
2712        @keyword y_contact: value for coefficient C{y_contact}        :keyword y_contact: value for coefficient ``y_contact``
2713        @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`
2714                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>}                         object on `FunctionOnContactOne`
2715                         or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         or `FunctionOnContactZero`
2716        @keyword y_contact_reduced: value for coefficient C{y_contact_reduced}        :keyword y_contact_reduced: value for coefficient ``y_contact_reduced``
2717        @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`
2718                                 object on L{ReducedFunctionOnContactOne<escript.FunctionOnContactOne>}                                 object on `ReducedFunctionOnContactOne`
2719                                 or L{ReducedFunctionOnContactZero<escript.FunctionOnContactZero>}                                 or `ReducedFunctionOnContactZero`
2720        @keyword r: values prescribed to the solution at the locations of        :keyword r: values prescribed to the solution at the locations of
2721                    constraints                    constraints
2722        @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
2723                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
2724                 depending on whether reduced order is used for the solution                 depending on whether reduced order is used for the solution
2725        @keyword q: mask for location of constraints        :keyword q: mask for location of constraints
2726        @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
2727                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
2728                 depending on whether reduced order is used for the                 depending on whether reduced order is used for the
2729                 representation of the equation                 representation of the equation
2730        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
2731        """        """
2732        super(LinearPDE,self).setValue(**coefficients)        super(LinearPDE,self).setValue(**coefficients)
2733        # check if the systrem is inhomogeneous:        # check if the systrem is inhomogeneous:
# Line 2748  class LinearPDE(LinearProblem): Line 2744  class LinearPDE(LinearProblem):
2744       """       """
2745       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.
2746    
2747       @param u: argument in the residual calculation. It must be representable       :param u: argument in the residual calculation. It must be representable
2748                 in L{self.getFunctionSpaceForSolution()}. If u is not present                 in `self.getFunctionSpaceForSolution()`. If u is not present
2749                 or equals C{None} the current solution is used.                 or equals ``None`` the current solution is used.
2750       @type u: L{Data<escript.Data>} or None       :type u: `Data` or None
2751       @return: residual of u       :return: residual of u
2752       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2753       """       """
2754       if u==None:       if u==None:
2755          return self.getOperator()*self.getSolution()-self.getRightHandSide()          return self.getOperator()*self.getSolution()-self.getRightHandSide()
# Line 2762  class LinearPDE(LinearProblem): Line 2758  class LinearPDE(LinearProblem):
2758    
2759     def getFlux(self,u=None):     def getFlux(self,u=None):
2760       """       """
2761       Returns the flux M{J} for a given M{u}.       Returns the flux *J* for a given *u*.
2762    
2763       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]*
2764    
2765       or       or
2766    
2767       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]*
2768    
2769       @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
2770                 current solution is used.                 current solution is used.
2771       @type u: L{Data<escript.Data>} or None       :type u: `Data` or None
2772       @return: flux       :return: flux
2773       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2774       """       """
2775       if u==None: u=self.getSolution()       if u==None: u=self.getSolution()
2776       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 2788  class LinearPDE(LinearProblem): Line 2784  class LinearPDE(LinearProblem):
2784  class Poisson(LinearPDE):  class Poisson(LinearPDE):
2785     """     """
2786     Class to define a Poisson equation problem. This is generally a     Class to define a Poisson equation problem. This is generally a
2787     L{LinearPDE} of the form     `LinearPDE` of the form
2788    
2789     M{-grad(grad(u)[j])[j] = f}     *-grad(grad(u)[j])[j] = f*
2790    
2791     with natural boundary conditions     with natural boundary conditions
2792    
2793     M{n[j]*grad(u)[j] = 0 }     *n[j]*grad(u)[j] = 0*
2794    
2795     and constraints:     and constraints:
2796    
2797     M{u=0} where M{q>0}     *u=0* where *q>0*
2798    
2799     """     """
2800    
# Line 2806  class Poisson(LinearPDE): Line 2802  class Poisson(LinearPDE):
2802       """       """
2803       Initializes a new Poisson equation.       Initializes a new Poisson equation.
2804    
2805       @param domain: domain of the PDE       :param domain: domain of the PDE
2806       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2807       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2808    
2809       """       """
2810       super(Poisson, self).__init__(domain,1,1,debug)       super(Poisson, self).__init__(domain,1,1,debug)
# Line 2821  class Poisson(LinearPDE): Line 2817  class Poisson(LinearPDE):
2817       """       """
2818       Sets new values to coefficients.       Sets new values to coefficients.
2819    
2820       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
2821       @keyword f: value for right hand side M{f}       :keyword f: value for right hand side *f*
2822       @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
2823                on L{Function<escript.Function>}                on `Function`
2824       @keyword q: mask for location of constraints       :keyword q: mask for location of constraints
2825       @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`
2826                object on L{Solution<escript.Solution>} or                object on `Solution` or
2827                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2828                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2829       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
2830       """       """
2831       super(Poisson, self).setValue(**coefficients)       super(Poisson, self).setValue(**coefficients)
2832    
2833    
2834     def getCoefficient(self,name):     def getCoefficient(self,name):
2835       """       """
2836       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
2837    
2838       @param name: name of the coefficient requested       :param name: name of the coefficient requested
2839       @type name: C{string}       :type name: ``string``
2840       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
2841       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2842       @raise IllegalCoefficient: invalid coefficient name       :raise IllegalCoefficient: invalid coefficient name
2843       @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
2844              equation onto the general PDE.              equation onto the general PDE.
2845       """       """
2846       if name == "A" :       if name == "A" :
# Line 2859  class Poisson(LinearPDE): Line 2855  class Poisson(LinearPDE):
2855  class Helmholtz(LinearPDE):  class Helmholtz(LinearPDE):
2856     """     """
2857     Class to define a Helmholtz equation problem. This is generally a     Class to define a Helmholtz equation problem. This is generally a
2858     L{LinearPDE} of the form     `LinearPDE` of the form
2859    
2860     M{S{omega}*u - grad(k*grad(u)[j])[j] = f}     *omega*u - grad(k*grad(u)[j])[j] = f*
2861    
2862     with natural boundary conditions     with natural boundary conditions
2863    
2864     M{k*n[j]*grad(u)[j] = g- S{alpha}u }     *k*n[j]*grad(u)[j] = g- alphau*
2865    
2866     and constraints:     and constraints:
2867    
2868     M{u=r} where M{q>0}     *u=r* where *q>0*
2869    
2870     """     """
2871    
# Line 2877  class Helmholtz(LinearPDE): Line 2873  class Helmholtz(LinearPDE):
2873       """       """
2874       Initializes a new Helmholtz equation.       Initializes a new Helmholtz equation.
2875    
2876       @param domain: domain of the PDE       :param domain: domain of the PDE
2877       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
2878       @param debug: if True debug information is printed       :param debug: if True debug information is printed
2879    
2880       """       """
2881       super(Helmholtz, self).__init__(domain,1,1,debug)       super(Helmholtz, self).__init__(domain,1,1,debug)
# Line 2897  class Helmholtz(LinearPDE): Line 2893  class Helmholtz(LinearPDE):
2893       """       """
2894       Sets new values to coefficients.       Sets new values to coefficients.
2895    
2896       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
2897       @keyword omega: value for coefficient M{S{omega}}       :keyword omega: value for coefficient *omega*
2898       @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`
2899                    object on L{Function<escript.Function>}                    object on `Function`
2900       @keyword k: value for coefficient M{k}       :keyword k: value for coefficient *k*
2901       @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
2902                on L{Function<escript.Function>}                on `Function`
2903       @keyword f: value for right hand side M{f}       :keyword f: value for right hand side *f*
2904       @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
2905                on L{Function<escript.Function>}                on `Function`
2906       @keyword alpha: value for right hand side M{S{alpha}}       :keyword alpha: value for right hand side *alpha*
2907       @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`
2908                    object on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                    object on `FunctionOnBoundary`
2909       @keyword g: value for right hand side M{g}       :keyword g: value for right hand side *g*
2910       @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
2911                on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                on `FunctionOnBoundary`
2912       @keyword r: prescribed values M{r} for the solution in constraints       :keyword r: prescribed values *r* for the solution in constraints
2913       @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
2914                on L{Solution<escript.Solution>} or                on `Solution` or
2915                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2916                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2917       @keyword q: mask for the location of constraints       :keyword q: mask for the location of constraints
2918       @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
2919                on L{Solution<escript.Solution>} or                on `Solution` or
2920                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
2921                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
2922       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
2923       """       """
2924       super(Helmholtz, self).setValue(**coefficients)       super(Helmholtz, self).setValue(**coefficients)
2925    
2926     def getCoefficient(self,name):     def getCoefficient(self,name):
2927       """       """
2928       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
2929    
2930       @param name: name of the coefficient requested       :param name: name of the coefficient requested
2931       @type name: C{string}       :type name: ``string``
2932       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
2933       @rtype: L{Data<escript.Data>}       :rtype: `Data`
2934       @raise IllegalCoefficient: invalid name       :raise IllegalCoefficient: invalid name
2935       """       """
2936       if name == "A" :       if name == "A" :
2937           if self.getCoefficient("k").isEmpty():           if self.getCoefficient("k").isEmpty():
# Line 2961  class LameEquation(LinearPDE): Line 2957  class LameEquation(LinearPDE):
2957     """     """
2958     Class to define a Lame equation problem. This problem is defined as:     Class to define a Lame equation problem. This problem is defined as:
2959    
2960     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]*
2961    
2962     with natural boundary conditions:     with natural boundary conditions:
2963    
2964     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]*
2965    
2966     and constraints:     and constraints:
2967    
2968     M{u[i]=r[i]} where M{q[i]>0}     *u[i]=r[i]* where *q[i]>0*
2969    
2970     """     """
2971    
# Line 2977  class LameEquation(LinearPDE): Line 2973  class LameEquation(LinearPDE):
2973        """        """
2974        Initializes a new Lame equation.        Initializes a new Lame equation.
2975    
2976        @param domain: domain of the PDE        :param domain: domain of the PDE
2977        @type domain: L{Domain<escript.Domain>}        :type domain: `Domain`
2978        @param debug: if True debug information is printed        :param debug: if True debug information is printed
2979    
2980        """        """
2981        super(LameEquation, self).__init__(domain,\        super(LameEquation, self).__init__(domain,\
# Line 2995  class LameEquation(LinearPDE): Line 2991  class LameEquation(LinearPDE):
2991       """       """
2992       Sets new values to coefficients.       Sets new values to coefficients.
2993    
2994       @param coefficients: new values assigned to coefficients       :param coefficients: new values assigned to coefficients
2995       @keyword lame_mu: value for coefficient M{S{mu}}       :keyword lame_mu: value for coefficient *mu*
2996       @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`
2997                      object on L{Function<escript.Function>}                      object on `Function`
2998       @keyword lame_lambda: value for coefficient M{S{lambda}}       :keyword lame_lambda: value for coefficient *lambda*
2999       @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`
3000                          object on L{Function<escript.Function>}                          object on `Function`
3001       @keyword F: value for internal force M{F}       :keyword F: value for internal force *F*
3002       @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
3003                on L{Function<escript.Function>}                on `Function`
3004       @keyword sigma: value for initial stress M{S{sigma}}       :keyword sigma: value for initial stress *sigma*
3005       @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`
3006                    object on L{Function<escript.Function>}                    object on `Function`
3007       @keyword f: value for external force M{f}       :keyword f: value for external force *f*
3008       @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
3009                on L{FunctionOnBoundary<escript.FunctionOnBoundary>}                on `FunctionOnBoundary`
3010       @keyword r: prescribed values M{r} for the solution in constraints       :keyword r: prescribed values *r* for the solution in constraints
3011       @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
3012                on L{Solution<escript.Solution>} or                on `Solution` or
3013                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
3014                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
3015       @keyword q: mask for the location of constraints       :keyword q: mask for the location of constraints
3016       @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
3017                on L{Solution<escript.Solution>} or                on `Solution` or
3018                L{ReducedSolution<escript.ReducedSolution>} depending on whether                `ReducedSolution` depending on whether
3019                reduced order is used for the representation of the equation                reduced order is used for the representation of the equation
3020       @raise IllegalCoefficient: if an unknown coefficient keyword is used       :raise IllegalCoefficient: if an unknown coefficient keyword is used
3021       """       """
3022       super(LameEquation, self).setValues(**coefficients)       super(LameEquation, self).setValues(**coefficients)
3023    
3024     def getCoefficient(self,name):     def getCoefficient(self,name):
3025       """       """
3026       Returns the value of the coefficient C{name} of the general PDE.       Returns the value of the coefficient ``name`` of the general PDE.
3027    
3028       @param name: name of the coefficient requested       :param name: name of the coefficient requested
3029       @type name: C{string}       :type name: ``string``
3030       @return: the value of the coefficient C{name}       :return: the value of the coefficient ``name``
3031       @rtype: L{Data<escript.Data>}       :rtype: `Data`
3032       @raise IllegalCoefficient: invalid coefficient name       :raise IllegalCoefficient: invalid coefficient name
3033       """       """
3034       out =self.createCoefficient("A")       out =self.createCoefficient("A")
3035       if name == "A" :       if name == "A" :
# Line 3070  def LinearSinglePDE(domain,debug=False): Line 3066  def LinearSinglePDE(domain,debug=False):
3066     """     """
3067     Defines a single linear PDE.     Defines a single linear PDE.
3068    
3069     @param domain: domain of the PDE     :param domain: domain of the PDE
3070     @type domain: L{Domain<escript.Domain>}     :type domain: `Domain`
3071     @param debug: if True debug information is printed     :param debug: if True debug information is printed
3072     @rtype: L{LinearPDE}     :rtype: `LinearPDE`
3073     """     """
3074     return LinearPDE(domain,numEquations=1,numSolutions=1,debug=debug)     return LinearPDE(domain,numEquations=1,numSolutions=1,debug=debug)
3075    
# Line 3081  def LinearPDESystem(domain,debug=False): Line 3077  def LinearPDESystem(domain,debug=False):
3077     """     """
3078     Defines a system of linear PDEs.     Defines a system of linear PDEs.
3079    
3080     @param domain: domain of the PDEs     :param domain: domain of the PDEs
3081     @type domain: L{Domain<escript.Domain>}     :type domain: `Domain`
3082     @param debug: if True debug information is printed     :param debug: if True debug information is printed
3083     @rtype: L{LinearPDE}     :rtype: `LinearPDE`
3084     """     """
3085     return LinearPDE(domain,numEquations=domain.getDim(),numSolutions=domain.getDim(),debug=debug)     return LinearPDE(domain,numEquations=domain.getDim(),numSolutions=domain.getDim(),debug=debug)
3086    
# Line 3093  class TransportPDE(LinearProblem): Line 3089  class TransportPDE(LinearProblem):
3089     """     """
3090     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,
3091     time dependent, second order PDE for an unknown, non-negative,     time dependent, second order PDE for an unknown, non-negative,
3092     time-dependent function M{u} on a given domain defined through a     time-dependent function *u* on a given domain defined through a
3093     L{Domain<escript.Domain>} object.     `Domain` object.
3094    
3095     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
3096     problem is defined in the following form:     problem is defined in the following form:
3097    
3098     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)*
3099    
3100     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
3101     spatial derivative of M{F}. Einstein's summation convention,  ie. summation     spatial derivative of *F*. Einstein's summation convention,  ie. summation
3102     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.
3103     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
3104     specified through L{Data<escript.Data>} objects in L{Function<escript.Function>}     specified through `Data` objects in `Function`
3105     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*,
3106     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
3107     L{Data<escript.Data>} objects in L{ReducedFunction<escript.ReducedFunction>}.     `Data` objects in `ReducedFunction`.
3108     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
3109     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
3110     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
3111     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
3112     scalar.     scalar.
3113    
3114     The following natural boundary conditions are considered:     The following natural boundary conditions are considered:
3115    
3116     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*
3117    
3118     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*,
3119     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
3120     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
3121     L{FunctionOnBoundary<escript.FunctionOnBoundary>} and the coefficients     `FunctionOnBoundary` and the coefficients
3122     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
3123     L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     `ReducedFunctionOnBoundary`.
3124    
3125     Constraints for the solution prescribing the value of the solution at     Constraints for the solution prescribing the value of the solution at
3126     certain locations in the domain have the form     certain locations in the domain have the form
3127    
3128     M{u_t=r} where M{q>0}     *u_t=r* where *q>0*
3129    
3130     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
3131     defining where the constraint is applied. The constraints override any other     defining where the constraint is applied. The constraints override any other
3132     condition set by the transport problem or the boundary condition.     condition set by the transport problem or the boundary condition.
3133    
3134     The transport problem is symmetrical if     The transport problem is symmetrical if
3135    
3136     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
3137     M{B_reduced[j]=C_reduced[j]}     *B_reduced[j]=C_reduced[j]*
3138    
3139     For a system and a solution with several components the transport problem     For a system and a solution with several components the transport problem
3140     has the form     has the form
3141    
3142     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]*
3143    
3144     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
3145     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*,
3146     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
3147     rank one. The natural boundary conditions take the form:     rank one. The natural boundary conditions take the form:
3148    
3149     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*
3150    
3151     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
3152     all in L{FunctionOnBoundary<escript.FunctionOnBoundary>}. The coefficients     all in `FunctionOnBoundary`. The coefficients
3153     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
3154     one all in L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}.     one all in `ReducedFunctionOnBoundary`.
3155    
3156     Constraints take the form     Constraints take the form
3157    
3158     M{u[i]_t=r[i]} where M{q[i]>0}     *u[i]_t=r[i]* where *q[i]>0*
3159    
3160     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
3161     necessarily all components must have a constraint.     necessarily all components must have a constraint.
3162    
3163     The transport problem is symmetrical if     The transport problem is symmetrical if
3164    
3165        - M{M[i,k]=M[i,k]}        - *M[i,k]=M[i,k]*
3166        - M{M_reduced[i,k]=M_reduced[i,k]}        - *M_reduced[i,k]=M_reduced[i,k]*
3167        - M{A[i,j,k,l]=A[k,l,i,j]}        - *A[i,j,k,l]=A[k,l,i,j]*
3168        - 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]*
3169        - M{B[i,j,k]=C[k,i,j]}        - *B[i,j,k]=C[k,i,j]*
3170        - M{B_reduced[i,j,k]=C_reduced[k,i,j]}        - *B_reduced[i,j,k]=C_reduced[k,i,j]*
3171        - M{D[i,k]=D[i,k]}        - *D[i,k]=D[i,k]*
3172        - M{D_reduced[i,k]=D_reduced[i,k]}        - *D_reduced[i,k]=D_reduced[i,k]*
3173        - M{m[i,k]=m[k,i]}        - *m[i,k]=m[k,i]*
3174        - M{m_reduced[i,k]=m_reduced[k,i]}        - *m_reduced[i,k]=m_reduced[k,i]*
3175        - M{d[i,k]=d[k,i]}        - *d[i,k]=d[k,i]*
3176        - M{d_reduced[i,k]=d_reduced[k,i]}        - *d_reduced[i,k]=d_reduced[k,i]*
3177    
3178     L{TransportPDE} also supports solution discontinuities over a contact region     `TransportPDE` also supports solution discontinuities over a contact region
3179     in the domain. To specify the conditions across the discontinuity we are     in the domain. To specify the conditions across the discontinuity we are
3180     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
3181     several components of the solution, is defined as     several components of the solution, is defined as
3182    
3183     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]*
3184    
3185     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
3186    
3187     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]*
3188    
3189     In the context of discontinuities M{n} denotes the normal on the     In the context of discontinuities *n* denotes the normal on the
3190     discontinuity pointing from side 0 towards side 1 calculated from     discontinuity pointing from side 0 towards side 1 calculated from
3191     L{getNormal<escript.FunctionSpace.getNormal>} of L{FunctionOnContactZero<escript.FunctionOnContactZero>}.     `FunctionSpace.getNormal` of `FunctionOnContactZero`.
3192     For a system of transport problems the contact condition takes the form     For a system of transport problems the contact condition takes the form
3193    
3194     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]*
3195    
3196     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
3197     discontinuity, respectively. M{jump(u)}, which is the difference of the     discontinuity, respectively. *jump(u)*, which is the difference of the
3198     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
3199     discontinuity along the normal calculated by L{jump<util.jump>}.     discontinuity along the normal calculated by `jump`.
3200     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
3201     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or L{FunctionOnContactOne<escript.FunctionOnContactOne>}.     both in `FunctionOnContactZero` or `FunctionOnContactOne`.
3202     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*
3203     is of rank one both in L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     is of rank one both in `ReducedFunctionOnContactZero` or `ReducedFunctionOnContactOne`.
3204     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
3205     condition takes the form     condition takes the form
3206    
3207     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)*
3208    
3209     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
3210     both in L{FunctionOnContactZero<escript.FunctionOnContactZero>} or     both in `FunctionOnContactZero` or
3211     L{FunctionOnContactOne<escript.FunctionOnContactOne>} and the coefficient     `FunctionOnContactOne` and the coefficient
3212     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
3213     L{ReducedFunctionOnContactZero<escript.ReducedFunctionOnContactZero>} or     `ReducedFunctionOnContactZero` or
3214     L{ReducedFunctionOnContactOne<escript.ReducedFunctionOnContactOne>}.     `ReducedFunctionOnContactOne`.
3215    
3216     Typical usage::     Typical usage::
3217    
# Line 3232  class TransportPDE(LinearProblem): Line 3228  class TransportPDE(LinearProblem):
3228       """       """
3229       Initializes a transport problem.       Initializes a transport problem.
3230    
3231       @param domain: domain of the PDE       :param domain: domain of the PDE
3232       @type domain: L{Domain<escript.Domain>}       :type domain: `Domain`
3233       @param numEquations: number of equations. If C{None} the number of       :param numEquations: number of equations. If ``None`` the number of
3234                            equations is extracted from the coefficients.                            equations is extracted from the coefficients.
3235       @param numSolutions: number of solution components. If C{None} the number       :param numSolutions: number of solution components. If ``None`` the number
3236                            of solution components is extracted from the                            of solution components is extracted from the
3237                            coefficients.                            coefficients.
3238       @param debug: if True debug information is printed       :param debug: if True debug information is printed
3239       @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.
3240       @type useBackwardEuler: C{bool}       :type useBackwardEuler: ``bool``
3241       """       """
3242       if useBackwardEuler:       if useBackwardEuler:
3243           self.__useBackwardEuler=True           self.__useBackwardEuler=True
# Line 3285  class TransportPDE(LinearProblem): Line 3281  class TransportPDE(LinearProblem):
3281       """       """
3282       Returns the string representation of the transport problem.       Returns the string representation of the transport problem.
3283    
3284       @return: a simple representation of the transport problem       :return: a simple representation of the transport problem
3285       @rtype: C{str}       :rtype: ``str``
3286       """       """
3287       return "<TransportPDE %d>"%id(self)       return "<TransportPDE %d>"%id(self)
3288    
3289     def useBackwardEuler(self):     def useBackwardEuler(self):
3290        """        """
3291        Returns true if backward Euler is used. Otherwise false is returned.        Returns true if backward Euler is used. Otherwise false is returned.
3292        @rtype: bool        :rtype: bool
3293        """        """
3294        return self.__useBackwardEuler        return self.__useBackwardEuler
3295    
# Line 3302  class TransportPDE(LinearProblem): Line 3298  class TransportPDE(LinearProblem):
3298        """        """
3299        Tests the transport problem for symmetry.        Tests the transport problem for symmetry.
3300    
3301        @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
3302                        which break the symmetry is printed.                        which break the symmetry is printed.
3303        @type verbose: C{bool}        :type verbose: ``bool``
3304        @return:  True if the PDE is symmetric        :return:  True if the PDE is symmetric
3305        @rtype: C{bool}        :rtype: ``bool``
3306        @note: This is a very expensive operation. It should be used for        :note: This is a very expensive operation. It should be used for
3307               degugging only! The symmetry flag is not altered.               degugging only! The symmetry flag is not altered.
3308        """        """
3309        out=True        out=True
# Line 3331  class TransportPDE(LinearProblem): Line 3327  class TransportPDE(LinearProblem):
3327        """        """
3328        Sets new values to coefficients.        Sets new values to coefficients.
3329    
3330        @param coefficients: new values assigned to coefficients        :param coefficients: new values assigned to coefficients
3331        @keyword M: value for coefficient C{M}        :keyword M: value for coefficient ``M``
3332        @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
3333                 L{Function<escript.Function>}                 `Function`
3334        @keyword M_reduced: value for coefficient C{M_reduced}        :keyword M_reduced: value for coefficient ``M_reduced``
3335        @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`
3336                         object on L{Function<escript.ReducedFunction>}                         object on `Function`
3337        @keyword A: value for coefficient C{A}        :keyword A: value for coefficient ``A``
3338        @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
3339                 L{Function<escript.Function>}                 `Function`
3340        @keyword A_reduced: value for coefficient C{A_reduced}        :keyword A_reduced: value for coefficient ``A_reduced``
3341        @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`
3342                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3343        @keyword B: value for coefficient C{B}        :keyword B: value for coefficient ``B``
3344        @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
3345                 L{Function<escript.Function>}                 `Function`
3346        @keyword B_reduced: value for coefficient C{B_reduced}        :keyword B_reduced: value for coefficient ``B_reduced``
3347        @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`
3348                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3349        @keyword C: value for coefficient C{C}        :keyword C: value for coefficient ``C``
3350        @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
3351                 L{Function<escript.Function>}                 `Function`
3352        @keyword C_reduced: value for coefficient C{C_reduced}        :keyword C_reduced: value for coefficient ``C_reduced``
3353        @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`
3354                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3355        @keyword D: value for coefficient C{D}        :keyword D: value for coefficient ``D``
3356        @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
3357                 L{Function<escript.Function>}                 `Function`
3358        @keyword D_reduced: value for coefficient C{D_reduced}        :keyword D_reduced: value for coefficient ``D_reduced``
3359        @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`
3360                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3361        @keyword X: value for coefficient C{X}        :keyword X: value for coefficient ``X``
3362        @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
3363                 L{Function<escript.Function>}                 `Function`
3364        @keyword X_reduced: value for coefficient C{X_reduced}        :keyword X_reduced: value for coefficient ``X_reduced``
3365        @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`
3366                         object on L{ReducedFunction<escript.ReducedFunction>}                         object on `ReducedFunction`
3367        @keyword Y: value for coefficient C{Y}        :keyword Y: value for coefficient ``Y``
3368        @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
3369                 L{Function<escript.Function>}                 `Function`
3370        @keyword Y_reduced: value for coefficient C{Y_reduced}        :keyword Y_reduced: value for coefficient ``Y_reduced``
3371        @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`
3372                         object on L{ReducedFunction<escript.Function>}                         object on `ReducedFunction`
3373        @keyword m: value for coefficient C{m}        :keyword m: value for coefficient ``m``
3374        @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
3375                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3376        @keyword m_reduced: value for coefficient C{m_reduced}        :keyword m_reduced: value for coefficient ``m_reduced``
3377        @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`
3378                         object on L{FunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `FunctionOnBoundary`
3379        @keyword d: value for coefficient C{d}        :keyword d: value for coefficient ``d``
3380        @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
3381                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3382        @keyword d_reduced: value for coefficient C{d_reduced}        :keyword d_reduced: value for coefficient ``d_reduced``
3383        @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`
3384                         object on L{ReducedFunctionOnBoundary<escript.ReducedFunctionOnBoundary>}                         object on `ReducedFunctionOnBoundary`
3385        @keyword y: value for coefficient C{y}        :keyword y: value for coefficient ``y``
3386        @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
3387                 L{FunctionOnBoundary<escript.FunctionOnBoundary>}                 `FunctionOnBoundary`
3388        @keyword d_contact: value for coefficient C{d_contact}        :keyword d_contact: value for coefficient ``d_contact``
3389        @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`
3390                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>} or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         object on `FunctionOnContactOne` or `FunctionOnContactZero`
3391        @keyword d_contact_reduced: value for coefficient C{d_contact_reduced}        :keyword d_contact_reduced: value for coefficient ``d_contact_reduced``
3392        @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`
3393        @keyword y_contact: value for coefficient C{y_contact}        :keyword y_contact: value for coefficient ``y_contact``
3394        @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`
3395                         object on L{FunctionOnContactOne<escript.FunctionOnContactOne>} or L{FunctionOnContactZero<escript.FunctionOnContactZero>}                         object on `FunctionOnContactOne` or `FunctionOnContactZero`
3396        @keyword y_contact_reduced: value for coefficient C{y_contact_reduced}        :keyword y_contact_reduced: value for coefficient ``y_contact_reduced``
3397        @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`
3398        @keyword r: values prescribed to the solution at the locations of constraints        :keyword r: values prescribed to the solution at the locations of constraints
3399        @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
3400                 L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                 `Solution` or `ReducedSolution`
3401                 depending on whether reduced order is used for the solution                 depending on whether reduced order is used for the solution
3402        @keyword q: mask for the location of constraints        :keyword q: mask for the location of constraints
3403        @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
3404                 L{Solution<escript.Solution>} or                 `Solution` or
3405                 L{ReducedSolution<escript.ReducedSolution>} depending on whether                 `ReducedSolution` depending on whether
3406                 reduced order is used for the representation of the equation                 reduced order is used for the representation of the equation
3407        @raise IllegalCoefficient: if an unknown coefficient keyword is used        :raise IllegalCoefficient: if an unknown coefficient keyword is used
3408        """        """
3409        super(TransportPDE,self).setValue(**coefficients)        super(TransportPDE,self).setValue(**coefficients)
3410    
# Line 3432  class TransportPDE(LinearProblem): Line 3428  class TransportPDE(LinearProblem):
3428         """         """
3429         Sets the initial solution.         Sets the initial solution.
3430    
3431         @param u: new initial solution         :param u: new initial solution
3432         @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`
3433                  object on L{Solution<escript.Solution>} or L{ReducedSolution<escript.ReducedSolution>}                  object on `Solution` or `ReducedSolution`
3434         @note: C{u} must be non-negative         :note: ``u`` must be non-negative
3435         """         """
3436         u2=util.interpolate(u,self.getFunctionSpaceForSolution())         u2=util.interpolate(u,self.getFunctionSpaceForSolution())
3437         if self.getNumSolutions() == 1:         if self.getNumSolutions() == 1:
# Line 3450  class TransportPDE(LinearProblem): Line 3446  class TransportPDE(LinearProblem):
3446        """        """
3447        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.
3448    
3449        @return: a code to indicate the type of transport problem scheme used        :return: a code to indicate the type of transport problem scheme used
3450        @rtype: C{float}        :rtype: ``float``
3451        """        """
3452        solver_options=self.getSolverOptions()        solver_options=self.getSolverOptions()
3453        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())
3454    
3455     def getUnlimitedTimeStepSize(self):     def getUnlimitedTimeStepSize(self):
3456        """        """
3457        Returns the value returned by the C{getSafeTimeStepSize} method to        Returns the value returned by the ``getSafeTimeStepSize`` method to
3458        indicate no limit on the safe time step size.        indicate no limit on the safe time step size.
3459    
3460         @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
3461                  step size                  step size
3462         @rtype: C{float}         :rtype: ``float``
3463         @note: Typically the biggest positive float is returned         :note: Typically the biggest positive float is returned
3464        """        """
3465        return self.getOperator().getUnlimitedTimeStepSize()        return self.getOperator().getUnlimitedTimeStepSize()
3466    
# Line 3472  class TransportPDE(LinearProblem): Line 3468  class TransportPDE(LinearProblem):
3468         """         """
3469         Returns a safe time step size to do the next time step.         Returns a safe time step size to do the next time step.
3470    
3471         @return: safe time step size         :return: safe time step size
3472         @rtype: C{float}         :rtype: ``float``
3473         @note: If not C{getSafeTimeStepSize()} < C{getUnlimitedTimeStepSize()}         :note: If not ``getSafeTimeStepSize()`` < ``getUnlimitedTimeStepSize()``
3474                any time step size can be used.                any time step size can be used.
3475         """         """
3476         return self.getOperator().getSafeTimeStepSize()         return self.getOperator().getSafeTimeStepSize()
# Line 3483  class TransportPDE(LinearProblem): Line 3479  class TransportPDE(LinearProblem):
3479         """         """
3480         Sets the weighting factor used to insert the constraints into the problem         Sets the weighting factor used to insert the constraints into the problem
3481    
3482         @param value: value for the weighting factor         :param value: value for the weighting factor
3483         @type value: large positive C{float}         :type value: large positive ``float``
3484         """         """
3485         if not value>0:         if not value>0:
3486           raise ValueError,"weighting factor needs to be positive."           raise ValueError,"weighting factor needs to be positive."
# Line 3494  class TransportPDE(LinearProblem): Line 3490  class TransportPDE(LinearProblem):
3490     def getConstraintWeightingFactor(self):     def getConstraintWeightingFactor(self):
3491         """         """
3492         returns the weighting factor used to insert the constraints into the problem         returns the weighting factor used to insert the constraints into the problem
3493         @return: value for the weighting factor         :return: value for the weighting factor
3494         @rtype: C{float}         :rtype: ``float``
3495         """         """
3496         return self.__constraint_factor         return self.__constraint_factor
3497     #====================================================================     #====================================================================
# Line 3503  class TransportPDE(LinearProblem): Line 3499  class TransportPDE(LinearProblem):
3499         """         """
3500         Returns the solution of the problem.         Returns the solution of the problem.
3501    
3502         @return: the solution         :return: the solution
3503         @rtype: L{Data<escript.Data>}         :rtype: `Data`
3504         """         """
3505         option_class=self.getSolverOptions()         option_class=self.getSolverOptions()
3506         if dt<=0:         if dt<=0:
# Line 3517  class TransportPDE(LinearProblem): Line 3513  class TransportPDE(LinearProblem):
3513         """         """
3514         Returns the operator and right hand side of the PDE.         Returns the operator and right hand side of the PDE.
3515    
3516         @return: the discrete version of the PDE         :return: the discrete version of the PDE
3517         @rtype: C{tuple} of L{Operator,<escript.Operator>} and         :rtype: ``tuple`` of `Operator` and
3518                 L{Data<escript.Data>}                 `Data`
3519    
3520         """         """
3521         if not self.isOperatorValid() or not self.isRightHandSideValid():         if not self.isOperatorValid() or not self.isRightHandSideValid():
# Line 3565  class TransportPDE(LinearProblem): Line 3561  class TransportPDE(LinearProblem):
3561    
3562     def setDebug(self, flag):     def setDebug(self, flag):
3563       """       """
3564       Switches debug output on if C{flag} is True,       Switches debug output on if ``flag`` is True,
3565       otherwise it is switched off.       otherwise it is switched off.
3566    
3567       @param flag: desired debug status       :param flag: desired debug status
3568       @type flag: C{bool}       :type flag: ``bool``
3569       """       """
3570       if flag:       if flag:
3571           self.setDebugOn()           self.setDebugOn()

Legend:
Removed from v.2624  
changed lines
  Added in v.2625

  ViewVC Help
Powered by ViewVC 1.1.26