merged source:branches/documentation@5299 to source:trunk@5299

git-svn-id: svn+ssh://code.matforge.org/fipy/trunk@5300 d80e17d7-ff13-0410-a124-85740d801063
usnistgov · Aug 16, 2012 · 9784a7a · 9784a7a
2 parents 3395eae + df597ce
commit 9784a7a
Show file tree

Hide file tree

Showing 47 changed files with 1,355 additions and 302 deletions.
diff --git a/INSTALLATION.txt b/INSTALLATION.txt
@@ -168,10 +168,8 @@ If necessary, you can download_ and install it for your platform
 .. note::
 
    :term:`FiPy` requires at least version 2.4.x of :term:`Python`. See
-   :ref:`RunningUnderPython3` for instructions on how to run
-   :term:`FiPy` with `Python 3.x`_.
+   the specialized instructions if you wish to :ref:`RunUnderPython3`.
 
-.. _Python 3.x:   http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://docs.python.org/py3k/
 .. _download: http://www.nist.gov/cgi-bin/exit_nist.cgi?url=http://www.python.org/download/
 
 :term:`Python` along with many of :term:`FiPy`'s required and optional

diff --git a/README.txt b/README.txt
@@ -54,25 +54,91 @@ necessary.
 
 The significant changes since version 2.1 are:
 
+- :ref:`CoupledEquations` are now supported.
+- A more robust mechanism for specifying :ref:`BoundaryConditions` is now 
+  used.
+- Most :class:`~fipy.meshes.mesh.Mesh`\es can be partitioned by 
+  :ref:`MeshingWithGmsh`.
+- :ref:`PYAMG` and :ref:`SCIPY` have been added to the :ref:`SOLVERS`.
+- FiPy is capable of :ref:`RunningUnderPython3`.
+- "getter" and "setter" methods have been pervasively changed to Python 
+  properties.
+- The test suite now runs much faster.
 - Tests can now be run on a full install using `fipy.test()`.
-- Grid classes now take an `Lx` argument. 
 - The functions of the :mod:`~fipy.tools.numerix` module are no longer 
   included in the :mod:`fipy` namespace. See :mod:`examples.updating.update2_0to3_0` 
   for details.
-- Support for Python 3. Please see :ref:`RunningUnderPython3` for details.
+- Equations containing a :class:`~fipy.terms.transientTerm.TransientTerm`,
+  must specify the timestep by passing a ``dt=`` argument when calling
+  :meth:`~fipy.terms.term.Term.solve` or :meth:`~fipy.terms.term.Term.sweep`.
 
 Tickets fixed in this release::
 
-    171	update the mayavi viewer to use  mayavi 2
-    286	'matplotlib: list index out of range' when no title given, but only sometimes
-    197	~binOp doesn't work on branches/version-2_0
-    194	`easy_install` instructions for MacOSX are broken
-    192	broken setuptools url with python 2.6
-    184	The FiPy webpage seems to be broken on Internet Explorer
-    168	Switch documentation to use `:math:` directive
-    198	FiPy2.0.2 LinearJORSolver.__init__  calls Solver rather than PysparseSolver
-    199	`gmshExport.exportAsMesh()` doesn't work
-    195	broken arithmetic face to cell distance calculations
+    45  Navier Stokes
+    85  CellVariable hasOld() should set self.old
+    101 Grids should take Lx, Ly, Lz arguments
+    145 tests should be run with fipy.tests()
+    177 remove ones and zeros from numerix.py
+    178 Default time steps should be infinite
+    291 term multiplication changes result
+    296 FAQ gives bad guidance for anisotropic diffusion
+    297 Use physical velocity in the manual/FAQ
+    298 mesh manipulation of periodic meshes leads to errors
+    299 Give helpfull error on - or / of meshes
+    301 wrong cell to cell normal in periodic meshes
+    302 gnuplot1d gives error on plot of facevariable
+    309 pypi is failing
+    312 Fresh FiPy gives ""ImportError: No viewers found"""
+    314 Absence of enthought.tvtk causes test failures
+    319 mesh in FiPy name space
+    324 --pysparse configuration should never attempt MPI imports
+    327 factoryMeshes.py not up to date with respect to keyword arguments
+    331 changed constraints don't propagate
+    332 anisotropic diffusion and constraints don't mix
+    333 `--Trilinos --no-pysparse` uses PySparse?!?
+    336 Profile and merge reconstrain branch
+    339 close out reconstrain branch
+    341 Fix fipy.terms._BinaryTerm test failure in parallel
+    343 diffusionTerm(var=var1).solver(var=var0) should fail sensibly
+    346 TeX is wrong in examples.phase.quaternary
+    348 Include Benny's improved interpolation patch
+    354 GmshExport is not tested and does not work
+    355 Introduce mesh.x as shorthand for mesh.cellCenters[0] etc
+    356 GmshImport should support all element types
+    357 GmshImport should read element colors
+    363 Reduce the run times for chemotaxis tests
+    366 tests take *too* long!!!
+    369 Make DiffusionTermNoCorrection the default
+    370 Epetra Norm2 failure in parallel
+    373 remove deprecated `steps=` from Solver
+    376 remove deprecated `diffusionTerm=` argument to ConvectionTerm
+    377 remove deprecated `NthOrderDiffusionTerm`
+    380 remove deprecated Variable.transpose()
+    381 remove deprecated viewers.make()
+    382 get running in Py3k
+    384 gmsh importer and gmsh tests don't clean up after themselves
+    385 `diffusionTerm._test()` requires PySparse
+    390 Improve test reporting to avoid inconsequential buildbot failures
+    391 efficiency_test chokes on liquidVapor2D.py
+    393 two `--scipy` failures
+    395 `--pysparse --inline` failures
+    417 Memory consumption growth with repeated meshing, especially with Gmsh
+    418 Viewers not working when plotting meshes with zero cells in parallel
+    419 examples/cahnHilliard/mesh2D.py broken with --trilinos
+    420 Epetra.PyComm() broken on Debian
+    421 cellVariable.min() broken in parallel
+    426 Add in parallel buildbot testing on more than 2 processors
+    427 Slow PyAMG solutions
+    434 Gmsh I/O
+    438 changes to gmshImport.py caused --inline problems
+    439 gmshImport tests fail on Windows due to shared file
+    441 Explicit convetion terms should fail when the equation has no TransientTerm (dt=None)
+    445 getFaceCenters() should return a FaceVariable
+    446 constraining values with ImplictSourceTerm not documented?
+    448 Gmsh2D does not respect background mesh
+    452 Gmsh background mesh doesn't work in parallel
+    453 faceValue as FaceCenters gives inline failures
+    454 Py3k and Windows test failures
 
 .. warning::
 

diff --git a/documentation/FAQ.txt b/documentation/FAQ.txt
@@ -97,7 +97,7 @@ How do I represent a `...` term that *doesn't* involve the dependent variable?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is important to realize that, even though an expression may
-superficially resemble one of those shown above, if the dependent variable
+superficially resemble one of those shown in :ref:`section:discretization`, if the dependent variable
 *for that PDE* does not appear in the appropriate place, then that
 term should be treated as a source.
 
@@ -193,6 +193,12 @@ For :term:`FiPy`'s purposes, however, this term represents the convection of
 >>> eq = TransientTerm() == (DiffusionTerm(coeff=D1) 
 ...                          + <Specific>ConvectionTerm(coeff=D2 * xi.faceGrad))
 
+.. note::
+
+   With the advent of :ref:`CoupledEquations` in FiPy 3.x, it is now
+   possible to represent both terms with
+   :class:`~fipy.terms.diffusionTerm.DiffusionTerm`.
+
 What if the coefficient of a term depends on the variable that I'm solving for?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -296,9 +302,11 @@ want, and then issue supplemental commands for the underlying plotting
 package. The better option is to make a "subclass" of the :term:`FiPy`
 :class:`Viewer <viewer.AbstractViewer>` that comes closest to producing the image you want. You can
 then override just the behavior you wan to change, while letting :term:`FiPy` do
-most of the heavy lifting. See :mod:`examples.phase.anisotropy` for an
-example of creating a custom :term:`Matplotlib` :class:`Viewer 
-<viewer.AbstractViewer>` class.
+most of the heavy lifting. See :mod:`examples.phase.anisotropy` and
+:mod:`examples.phase.polyxtal` for examples of creating a custom
+:term:`Matplotlib` :class:`Viewer <viewer.AbstractViewer>` class; see
+:mod:`examples.cahnHilliard.sphere` for an example of creating a custom
+:term:`Mayavi` :class:`Viewer <viewer.AbstractViewer>` class.
 
 .. _FAQ-IterationsTimestepsSweeps:
 
@@ -390,7 +398,7 @@ sweeps
   Sweeps are used to achieve better solutions in
   :mod:`examples.diffusion.mesh1D`, 
   :mod:`examples.phase.simple`, 
-  :mod:`examples.phase.binary`, and :mod:`examples.flow.stokesCavity`.
+  :mod:`examples.phase.binaryCoupled`, and :mod:`examples.flow.stokesCavity`.
 
 timesteps
   This outermost layer of repetition is of most practical interest to
@@ -436,7 +444,7 @@ timesteps
   chosen based on the expected interfacial velocity in
   :mod:`examples.phase.simple`. The timestep is gradually
   increased as the kinetics slow down in
-  :mod:`examples.cahnHilliard.mesh2D`.
+  :mod:`examples.cahnHilliard.mesh2DCoupled`.
 
 Finally, we can (and often do) combine all three layers of repetition:
 
@@ -496,111 +504,7 @@ How do I represent boundary conditions?
 
 .. currentmodule:: fipy.variables.cellVariable
 
-How do I represent a fixed value (Dirichlet) boundary condition?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use the :meth:`~CellVariable.constrain` method. For
-example, to fix `var` to have a value of `2` along the upper surface of a domain,
-use
-
->>> var.constrain(2., where=mesh.facesTop)
-
-.. note:: 
-
-   The old equivalent
-   :class:`~fipy.boundaryConditions.fixedValue.FixedValue` boundary
-   condition is now deprecated.
-
-How do I apply a (Neumann) fixed gradient boundary condition?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use the :attr:`~.CellVariable.faceGrad`.\ :meth:`~fipy.variables.variable.Variable.constrain`
-method. For example, to fix `var` to have a gradient of `(0,2)` along the upper
-surface of a 2D domain, use
-
->>> var.faceGrad.constrain(((0,),(2,)), where=mesh.facesTop)
-
-How do I apply a fixed flux boundary condition?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Generally this can be implemented with a judicious use of
-:attr:`~.CellVariable.faceGrad`.\ :meth:`~fipy.variables.variable.Variable.constrain`.
-Failing that, an exterior flux term can be added to the equation. Firstly,
-set the terms' coefficients to be zero on the exterior faces,
-
->>> diffCoeff.constrain(0., mesh.exteriorFaces)
->>> convCoeff.constrain(0., mesh.exteriorFaces)
-
-then create an equation with an extra term to account for the exterior flux,
-
->>> eqn = (TransientTerm() + ConvectionTerm(convCoeff) 
-...        == DiffusionCoeff(diffCoeff)
-...        + (mesh.exteriorFaces * exteriorFlux).divergence)
-
-where `exteriorFlux` is a rank 1
-:class:`~fipy.variables.faceVariable.FaceVariable`.
-
-.. note:: 
-
-   The old equivalent :class:`~fipy.boundaryConditions.fixedFlux.FixedFlux`
-   boundary condition is now deprecated.
-
-How do I apply an outlet or inlet boundary condition?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Convection terms default to a no flux boundary condition unless the
-exterior faces are associated with a constraint, in which case either
-an inlet or an outlet boundary condition is applied depending on the
-flow direction.
-
-How do I apply spatially varying boundary conditions?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The use of spatial varying boundary conditions is best demonstrated with an
-example. Given a 2D equation in the domain :math:`0 < x < 1` and :math:`0 < y < 1` with
-boundary conditions,
-
-.. math::
-
-  \phi = \left\{
-            \begin{aligned} 
-                xy &\quad \text{on $x>1/2$ and $y>1/2$} \\
-                \vec{n} \cdot \vec{F} = 0 &\quad \text{elsewhere}
-            \end{aligned}
-        \right.
-
-where :math:`\vec{F}` represents the flux. The boundary conditions in :term:`FiPy` can
-be written with the following code,
-
->>> x, y = mesh.faceCenters
->>> mask =  ((x < 0.5) | (y < 0.5))
->>> var.faceGrad.constrain(0, where=mesh.exteriorFaces & mask)
->>> var.constrain(x * y, where=mesh.exteriorFaces & ~mask)
-
-then
-
->>> eqn.solve(...)
-
-Further demonstrations of spatially varying boundary condition can be found
-in :mod:`examples.diffusion.mesh20x20`
-and :mod:`examples.diffusion.circle`
-
-.. %    http://thread.gmane.org/gmane.comp.python.fipy/726
-   %    http://thread.gmane.org/gmane.comp.python.fipy/846
-
-   %    \subsection{Fourth order boundary conditions}
-
-   %    http://thread.gmane.org/gmane.comp.python.fipy/923
-
-   %    \subsection{Periodic boundary conditions}
-
-   %    http://thread.gmane.org/gmane.comp.python.fipy/135
-
-   %    \subsection{Time dependent boundary conditions}
-
-   %    http://thread.gmane.org/gmane.comp.python.fipy/2
-
-   %    \subsection{Internal boundary conditions}
+See the :ref:`BoundaryConditions` section for more details.
 
 What does this error message mean?
 ----------------------------------