.gitignore

@@ -39,8 +39,12 @@ solaris*Gcc*/
 SunOS*Gcc*/
 platforms/
 
-# Reinstate wmake/rules that might look like build directories
-!wmake/rules/*/
+# Top-level build directories
+/build/
+/platforms/
+
+# Reinstate wmake rules that might look like build directories
+!/wmake/rules/*/
 
 # doxygen generated documentation
 doc/Doxygen/html
@@ -58,10 +62,12 @@ doc/Doxygen/DTAGS
 /etc/prefs.sh
 /etc/config.csh/prefs.csh
 /etc/config.sh/prefs.sh
+/wmake/rules/General/mplibUSER*
 
 # Source packages - anywhere
 *.tar.bz2
 *.tar.gz
+*.tar.xz
 *.tar
 *.tgz
 *.gtgz
@@ -75,9 +81,10 @@ doc/Doxygen/DTAGS
 # Ignore .tags in the main directory
 /.tags
 
-# Ignore eclipse project files in the main directory
+# Ignore project files in the main directory
 /.cproject
 /.project
+/.dir-locals.el
 
 # Ignore the test directory
 /tutorialsTest

Allwmake

 #!/bin/sh
-cd ${0%/*} || exit 1    # Run from this directory
-
-# Parse arguments for library compilation
-. $WM_PROJECT_DIR/wmake/scripts/AllwmakeParseArguments
-
-wmakeCheckPwd "$WM_PROJECT_DIR" || {
-    echo "Allwmake error: Current directory is not \$WM_PROJECT_DIR"
-    echo "    The environment variables are inconsistent with the installation."
-    echo "    Check the OpenFOAM entries in your dot-files and source them."
+# Run from OPENFOAM top-level directory only
+cd ${0%/*} && wmakeCheckPwd "$WM_PROJECT_DIR" 2>/dev/null || {
+    echo "Error (${0##*/}) : not located in \$WM_PROJECT_DIR"
+    echo "    Check your OpenFOAM environment and installation"
     exit 1
 }
-
-[ -n "$FOAM_EXT_LIBBIN" ] || {
-    echo "Allwmake error: FOAM_EXT_LIBBIN not set"
-    echo "    Check the OpenFOAM entries in your dot-files and source them."
+[ -d "$WM_PROJECT_DIR" -a -f "$WM_PROJECT_DIR/etc/bashrc" ] || {
+    echo "Error (${0##*/}) : WM_PROJECT_DIR appears to be incorrect"
+    echo "    Check your OpenFOAM environment and installation"
     exit 1
 }
 
-# Compile wmake support applications
-(cd wmake/src && make)
+# Parse arguments for library compilation
+. $WM_PROJECT_DIR/wmake/scripts/AllwmakeParseArguments
+
+#------------------------------------------------------------------------------
+echo "========================================"
+date "+%Y-%m-%d %H:%M:%S %z" 2>/dev/null || echo "date is unknown"
+echo "Starting ${WM_PROJECT_DIR##*/} ${0##*}"
+echo "  $WM_COMPILER $WM_COMPILER_TYPE compiler"
+echo "  ${WM_OPTIONS}, with ${WM_MPLIB} ${FOAM_MPI}"
+echo
+
+# Compile wmake tools
+(cd "${WM_DIR:-wmake}/src" && make)
 
 # Compile ThirdParty libraries and applications
 if [ -d "$WM_THIRD_PARTY_DIR" ]
 then
     $WM_THIRD_PARTY_DIR/Allwmake
 else
-    echo "Allwmake: no ThirdParty directory found - skipping"
+    echo "No ThirdParty directory found - skipping"
 fi
 
-# Compile OpenFOAM libraries and applications
+echo "========================================"
+echo "Compile OpenFOAM libraries"
+echo
 src/Allwmake $targetType $*
 
-# Compile OpenFOAM libraries and applications
+echo "========================================"
+echo "Compile OpenFOAM applications"
+echo
 applications/Allwmake $targetType $*
 
-
+# Some summary information
+echo
+date "+%Y-%m-%d %H:%M:%S %z" 2>/dev/null || echo "date is unknown"
+echo "========================================"
+echo "  ${WM_PROJECT_DIR##*/}"
+echo "  $WM_COMPILER $WM_COMPILER_TYPE compiler"
+echo "  ${WM_OPTIONS}, with ${WM_MPLIB} ${FOAM_MPI}"
+echo
 #------------------------------------------------------------------------------

BuildIssues.txt

+OpenFOAM-1706
+==================
+Known Build Issues
+==================
+
+---------------------
+Intel MPI (Gcc/Clang)
+---------------------
+
+  Either I_MPI_ROOT or MPI_ROOT can be used to specify the Intel-MPI
+  installation directory path.
+
+  The ThirdParty build of ptscotch uses `mpiicc` for Intel-MPI
+  instead of the usual `mpicc`.
+  When gcc or clang are used, it is highly likely that the
+  I_MPI_CC environment variable also needs to be set accordingly.
+
+  See `mpiicc -help` for more information about environment variables.
+
+
+--------------
+Intel Compiler
+--------------
+
+  Since OpenFOAM uses C++11, a fairly recent version is required.
+  The Intel compiler - icc (ICC) 17.0.1 20161005 is ok, but the
+  initial release - icc (ICC) 17.0.0 20160721 - has a bug that
+  will result in these types of error messages.
+
+    MatrixSpaceI.H(492): error: no instance of overloaded function
+    "Foam::MatrixSpace<Form, Cmpt, Mrows, Ncols>::Block<SubTensor,
+    BRowStart, BColStart>::operator=" matches the specified type
+
+
+---
+VTK
+---
+
+If using the runTimePostProcessing to create on-the-fly images, you
+can simply just compile ParaView and these libraries will be used.
+
+If you elect to use a separate VTK compilation (for example for
+off-screen rendering), it is advisable to reuse the VTK libraries that
+are provided with ParaView by making an appropriate symlink
+prior to using makeVTK. This doesn't just reduce disk-space, but works
+much better than using the VTK tar file.
+
+Using runTimePostProcessing with the 'plain' VTK libraries does
+generally work, but does not exit cleanly:
+
+    symbol lookup error: .../linux64Gcc/VTK-7.1.0/lib/libvtkCommonExecutionModel-7.1.so.1:
+    undefined symbol: _ZN33vtkFilteringInformationKeyManager13ClassFinalizeEv
+
+    symbol lookup error: .../linux64Gcc/VTK-7.1.0/lib/libvtkCommonDataModel-7.1.so.1:
+    undefined symbol: _ZN49vtkInformationQuadratureSchemeDefinitionVectorKeyD1Ev
+
+This error appears to be suppressed if VTK is compiled with a Debug build-type.
+
+
+-------------------------
+Building on older systems
+-------------------------
+
+If the system gcc is too old for building OpenFOAM, a third-party gcc or
+clang/llvm installation can be used. If building clang/llvm, note that
+there are also minimum gcc/g++ requirements there:
+
+   Min gcc/g++
+   ===========   ==========
+    4.4          llvm-3.4.2
+    4.7          llvm-3.5.2 - llvm-3.7.0
+
+
+If your system compiler is too old to build the minimum required gcc or
+clang/llvm, it is just simply too old.
+
+
+-------------------------
+Building with spack
+-------------------------
+
+If you are building with spack, note that the depends_on for paraview
+resolves poorly. The +qt dependency (for building the reader module)
+may need to be specified as a preference by including the following in
+your `~/.spack/packages.yaml` file:
+
+    packages:
+        paraview:
+            variants: +qt
+
+It appears that spack will otherwise ignore any paraview+qt version
+and attempt to install a paraview~qt version instead.
+
+--

README.md

+# About OpenFOAM
+OpenFOAM is a free, open source CFD software [released and developed primarily by OpenCFD Ltd](http://www.openfoam.com) since 2004. It has a large user base across most areas of engineering and science, from both commercial and academic organisations. OpenFOAM has an extensive range of features to solve anything from complex fluid flows involving chemical reactions, turbulence and heat transfer, to acoustics, solid mechanics and electromagnetics.  [More...](http://www.openfoam.com/documentation)
+
+OpenFOAM+ is professionally released every six months to include customer sponsored developments and contributions from the community, including the OpenFOAM Foundation. Releases designated OpenFOAM+ contain several man years of client-sponsored developments of which much has been transferred to, but not released in the OpenFOAM Foundation branch.
+
+
+# Copyright
+OpenFOAM is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.  See the file COPYING in this directory or [http://www.gnu.org/licenses/](http://www.gnu.org/licenses), for a description of the GNU General Public License terms under which you can copy the files.
+
+
+# OpenFOAM Trademark
+OpenCFD Ltd grants use of the OpenFOAM trademark by Third Parties on a licence basis. ESI Group and the OpenFOAM Foundation Ltd are currently permitted to use the Name and agreed Domain Name. For information on trademark use, please refer to the [trademark policy guidelines](http://www.openfoam.com/legal/trademark-policy.php).
+
+Please [contact OpenCFD](http://www.openfoam.com/contact) if you have any questions on the use of the OpenFOAM trademark.
+
+Violations of the Trademark are continuously monitored, and will be duly prosecuted.
+
+
+# Useful Links
+- [Download and installation instructions](http://www.openfoam.com/download/)
+- [Documentation](http://www.openfoam.com/documentation)
+- [Reporting bugs/issues/feature requests](http://www.openfoam.com/code/bug-reporting.php)
+- [OpenFOAM Community](http://www.openfoam.com/community/)
+- [Contacting OpenCFD](http://www.openfoam.com/contact/)
+
+Copyright 2016-2017 OpenCFD Ltd

README.org

-#                            -*- mode: org; -*-
-#
-#+TITLE:     README for [[http://openfoam.org/download/source][OpenFOAM-dev]]
-#+AUTHOR:               The OpenFOAM Foundation
-#+DATE:                     20th June 2016
-#+LINK:                  http://openfoam.org
-#+OPTIONS: author:nil ^:{}
-# Copyright (c) 2015-2016 OpenFOAM Foundation.
-
-* About OpenFOAM
-  OpenFOAM is a free, open source computational fluid dynamics (CFD) software
-  package released by the OpenFOAM Foundation. It has a large user base across
-  most areas of engineering and science, from both commercial and academic
-  organisations. OpenFOAM has an extensive range of features to solve anything
-  from complex fluid flows involving chemical reactions, turbulence and heat
-  transfer, to solid dynamics and electromagnetics.
-
-* Copyright
-  OpenFOAM is free software: you can redistribute it and/or modify it under the
-  terms of the GNU General Public License as published by the Free Software
-  Foundation, either version 3 of the License, or (at your option) any later
-  version.  See the file =COPYING= in this directory or
-  [[http://www.gnu.org/licenses/]], for a description of the GNU General Public
-  License terms under which you can copy the files.
-
-* [[http://OpenFOAM.org/download/source][Download and installation instructions]]
-* [[http://OpenFOAM.org/docs][Documentation]]
-* [[http://OpenFOAM.github.io/Documentation-dev/html][Source code documentation]]
-* [[http://OpenFOAM.github.io/Documentation-dev/html/codingStyleGuide.html][OpenFOAM C++ Style Guide]]
-* [[http://OpenFOAM.org/bugs][Reporting bugs in OpenFOAM]]
-* [[http://openfoam.org/contact][Contacting the OpenFOAM Foundation]]

applications/Allwmake

 #!/bin/sh
-cd ${0%/*} || exit 1    # Run from this directory
-
-# Parse arguments for library compilation
-. $WM_PROJECT_DIR/wmake/scripts/AllwmakeParseArguments
-
-wmakeCheckPwd "$WM_PROJECT_DIR/applications" || {
-    echo "Allwmake error: Current directory is not \$WM_PROJECT_DIR/applications"
-    echo "    The environment variables are inconsistent with the installation."
-    echo "    Check the OpenFOAM entries in your dot-files and source them."
+# Run from OPENFOAM applications/ directory only
+cd ${0%/*} && wmakeCheckPwd "$WM_PROJECT_DIR/applications" 2>/dev/null || {
+    echo "Error (${0##*/}) : not located in \$WM_PROJECT_DIR/applications"
+    echo "    Check your OpenFOAM environment and installation"
     exit 1
 }
-
-[ -n "$FOAM_EXT_LIBBIN" ] || {
-    echo "Allwmake error: FOAM_EXT_LIBBIN not set"
-    echo "    Check the OpenFOAM entries in your dot-files and source them."
+[ -d "$WM_PROJECT_DIR" -a -f "$WM_PROJECT_DIR/etc/bashrc" ] || {
+    echo "Error (${0##*/}) : WM_PROJECT_DIR appears to be incorrect"
+    echo "    Check your OpenFOAM environment and installation"
     exit 1
 }
 
-set -x
+# Parse arguments for library compilation
+. $WM_PROJECT_DIR/wmake/scripts/AllwmakeParseArguments
+
+#------------------------------------------------------------------------------
 
 wmake -all $targetType solvers
 wmake -all $targetType utilities
 
-
 #------------------------------------------------------------------------------

applications/solvers/DNS/DNSSolversDoc.H

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2015 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it under
+    the terms of the GNU General Public License as published by the Free
+    Software Foundation, either version 3 of the License, or (at your option)
+    any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT ANY
+    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+    FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+    details.
+
+    You should have received a copy of the GNU General Public License along with
+    OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\defgroup grpDNSSolvers Direct Numerical Simulation solvers
+@{
+    \ingroup grpSolvers
+    This group contains Direct Numerical Simulation (DNS) solvers.
+@}
+
+\*---------------------------------------------------------------------------*/

applications/solvers/DNS/dnsFoam/Allwmake

+#!/bin/sh
+cd ${0%/*} || exit 1    # run from this directory
+
+if [ -f "$FFTW_ARCH_PATH/include/fftw3.h" ] || \
+   [ "${FFTW_ARCH_PATH##*-}" = system -a -f "/usr/include/fftw3.h" ]
+then
+    wmake
+else
+    echo "==> skip dnsFoam solver (no FFTW)"
+fi
+
+#------------------------------------------------------------------------------

applications/solvers/DNS/dnsFoam/dnsFoam.C

@@ -24,6 +24,9 @@ License
 Application
     dnsFoam
 
+Group
+    grpDNSSolvers
+
 Description
     Direct numerical simulation solver for boxes of isotropic turbulence.
 

applications/solvers/basic/basicSolversDoc.H

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2015 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it under
+    the terms of the GNU General Public License as published by the Free
+    Software Foundation, either version 3 of the License, or (at your option)
+    any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT ANY
+    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+    FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+    details.
+
+    You should have received a copy of the GNU General Public License along with
+    OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+\defgroup grpBasicSolvers Basic solvers
+@{
+    \ingroup grpSolvers
+    This group contains basic solvers.
+@}
+
+\*---------------------------------------------------------------------------*/

applications/solvers/basic/laplacianFoam/Make/options

@@ -4,4 +4,5 @@ EXE_INC = \
 
 EXE_LIBS = \
     -lfiniteVolume \
+    -lfvOptions \
     -lmeshTools

applications/solvers/basic/laplacianFoam/createFields.H

-    Info<< "Reading field T\n" << endl;
+Info<< "Reading field T\n" << endl;
 
-    volScalarField T
+volScalarField T
+(
+    IOobject
     (
-        IOobject
-        (
-            "T",
-            runTime.timeName(),
-            mesh,
-            IOobject::MUST_READ,
-            IOobject::AUTO_WRITE
-        ),
-        mesh
-    );
+        "T",
+        runTime.timeName(),
+        mesh,
+        IOobject::MUST_READ,
+        IOobject::AUTO_WRITE
+    ),
+    mesh
+);
 
 
-    Info<< "Reading transportProperties\n" << endl;
+Info<< "Reading transportProperties\n" << endl;
 
-    IOdictionary transportProperties
+IOdictionary transportProperties
+(
+    IOobject
     (
-        IOobject
-        (
-            "transportProperties",
-            runTime.constant(),
-            mesh,
-            IOobject::MUST_READ_IF_MODIFIED,
-            IOobject::NO_WRITE
-        )
-    );
+        "transportProperties",
+        runTime.constant(),
+        mesh,
+        IOobject::MUST_READ_IF_MODIFIED,
+        IOobject::NO_WRITE
+    )
+);
 
 
-    Info<< "Reading diffusivity DT\n" << endl;
+Info<< "Reading diffusivity DT\n" << endl;
 
-    dimensionedScalar DT
-    (
-        transportProperties.lookup("DT")
-    );
+dimensionedScalar DT
+(
+    "DT",
+    dimArea/dimTime,
+    transportProperties
+);

applications/solvers/basic/laplacianFoam/laplacianFoam.C

@@ -24,8 +24,30 @@ License
 Application
     laplacianFoam
 
+Group
+    grpBasicSolvers
+
 Description
-    Solves a simple Laplace equation, e.g. for thermal diffusion in a solid.
+    Laplace equation solver for a scalar quantity.
+
+    \heading Solver details
+    The solver is applicable to, e.g. for thermal diffusion in a solid.  The
+    equation is given by:
+
+    \f[
+        \ddt{T}  = \div \left( D_T \grad T \right)
+    \f]
+
+    Where:
+    \vartable
+        T     | Scalar field which is solved for, e.g. temperature
+        D_T   | Diffusion coefficient
+    \endvartable
+
+    \heading Required fields
+    \plaintable
+        T     | Scalar field which is solved for, e.g. temperature
+    \endplaintable
 
 \*---------------------------------------------------------------------------*/
 

applications/solvers/basic/laplacianFoam/overLaplacianDyMFoam/Make/files

+laplacianDyMFoam.C
+
+EXE = $(FOAM_APPBIN)/overLaplacianDyMFoam

applications/solvers/basic/laplacianFoam/overLaplacianDyMFoam/Make/options

+EXE_INC = \
+    -I$(LIB_SRC)/finiteVolume/lnInclude \
+    -I$(LIB_SRC)/dynamicFvMesh/lnInclude \
+    -I$(LIB_SRC)/overset/lnInclude \
+    -I$(LIB_SRC)/meshTools/lnInclude
+
+EXE_LIBS = \
+    -loverset

applications/solvers/basic/laplacianFoam/overLaplacianDyMFoam/createFields.H

+    Info<< "Reading field T\n" << endl;
+
+    volScalarField T
+    (
+        IOobject
+        (
+            "T",
+            runTime.timeName(),
+            mesh,
+            IOobject::MUST_READ,
+            IOobject::AUTO_WRITE
+        ),
+        mesh
+    );
+
+    // Add overset specific interpolations
+    {
+        dictionary oversetDict;
+        oversetDict.add("T", true);
+
+        const_cast<dictionary&>
+        (
+            mesh.schemesDict()
+        ).add
+        (
+            "oversetInterpolationRequired",
+            oversetDict,
+            true
+        );
+    }
+
+
+    Info<< "Reading transportProperties\n" << endl;
+
+    IOdictionary transportProperties
+    (
+        IOobject
+        (
+            "transportProperties",
+            runTime.constant(),
+            mesh,
+            IOobject::MUST_READ_IF_MODIFIED,
+            IOobject::NO_WRITE
+        )
+    );
+
+
+    Info<< "Reading diffusivity DT\n" << endl;
+
+    dimensionedScalar DT
+    (
+        transportProperties.lookup("DT")
+    );

applications/solvers/basic/laplacianFoam/overLaplacianDyMFoam/laplacianDyMFoam.C

+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | Copyright (C) 2011-2015 OpenFOAM Foundation
+     \\/     M anipulation  | Copyright (C) 2016-2017 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+License
+    This file is part of OpenFOAM.
+
+    OpenFOAM is free software: you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
+    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+    for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
+
+Application
+    laplacianFoam
+
+Group
+    grpBasicSolvers
+
+Description
+    Laplace equation solver for a scalar quantity.
+
+    \heading Solver details
+    The solver is applicable to, e.g. for thermal diffusion in a solid.  The
+    equation is given by:
+
+    \f[
+        \ddt{T}  = \div \left( D_T \grad T \right)
+    \f]
+
+    Where:
+    \vartable
+        T     | Scalar field which is solved for, e.g. temperature
+        D_T   | Diffusion coefficient
+    \endvartable
+
+    \heading Required fields
+    \plaintable
+        T     | Scalar field which is solved for, e.g. temperature
+    \endplaintable
+
+\*---------------------------------------------------------------------------*/
+
+#include "fvCFD.H"
+#include "fvOptions.H"
+#include "simpleControl.H"
+#include "dynamicFvMesh.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+int main(int argc, char *argv[])
+{
+    #include "setRootCase.H"
+
+    #include "createTime.H"
+    #include "createNamedDynamicFvMesh.H"
+
+    simpleControl simple(mesh);
+
+    #include "createFields.H"
+    #include "createFvOptions.H"
+
+    // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+    Info<< "\nCalculating temperature distribution\n" << endl;
+
+    while (simple.loop())
+    {
+        Info<< "Time = " << runTime.timeName() << nl << endl;
+
+        mesh.update();
+
+        while (simple.correctNonOrthogonal())
+        {
+            fvScalarMatrix TEqn
+            (
+                fvm::ddt(T) - fvm::laplacian(DT, T)
+             ==
+                fvOptions(T)
+            );
+
+            fvOptions.constrain(TEqn);
+            TEqn.solve();
+            fvOptions.correct(T);
+        }
+
+        #include "write.H"
+
+        Info<< "ExecutionTime = " << runTime.elapsedCpuTime() << " s"
+            << "  ClockTime = " << runTime.elapsedClockTime() << " s"
+            << nl << endl;
+    }
+
+    Info<< "End\n" << endl;
+
+    return 0;
+}
+
+
+// ************************************************************************* //

applications/solvers/basic/laplacianFoam/overLaplacianDyMFoam/write.H

+    if (runTime.outputTime())
+    {
+        volVectorField gradT(fvc::grad(T));
+
+        volScalarField gradTx
+        (
+            IOobject
+            (
+                "gradTx",
+                runTime.timeName(),
+                mesh,
+                IOobject::NO_READ,
+                IOobject::AUTO_WRITE
+            ),
+            gradT.component(vector::X)
+        );
+
+        volScalarField gradTy
+        (
+            IOobject
+            (
+                "gradTy",
+                runTime.timeName(),
+                mesh,
+                IOobject::NO_READ,
+                IOobject::AUTO_WRITE
+            ),
+            gradT.component(vector::Y)
+        );
+
+        volScalarField gradTz
+        (
+            IOobject
+            (
+                "gradTz",
+                runTime.timeName(),
+                mesh,
+                IOobject::NO_READ,
+                IOobject::AUTO_WRITE
+            ),
+            gradT.component(vector::Z)
+        );
+
+
+        runTime.write();
+    }

applications/solvers/basic/potentialFoam/createFields.H

@@ -12,6 +12,7 @@ volVectorField U
     mesh
 );
 
+// Initialise the velocity internal field to zero
 U = dimensionedVector("0", U.dimensions(), Zero);
 
 surfaceScalarField phi
@@ -34,7 +35,9 @@ if (args.optionFound("initialiseUBCs"))
 }
 
 
-// Default name for the pressure field
+// Construct a pressure field
+// If it is available read it otherwise construct from the velocity BCs
+// converting fixed-value BCs to zero-gradient and vice versa.
 word pName("p");
 
 // Update name of the pressure field from the command-line option
@@ -55,6 +58,9 @@ forAll(U.boundaryField(), patchi)
     }
 }
 
+// Note that registerObject is false for the pressure field. The pressure
+// field in this solver doesn't have a physical value during the solution.
+// It shouldn't be looked up and used by sub models or boundary conditions.
 Info<< "Constructing pressure field " << pName << nl << endl;
 volScalarField p
 (
@@ -64,7 +70,8 @@ volScalarField p
         runTime.timeName(),
         mesh,
         IOobject::READ_IF_PRESENT,
-        IOobject::NO_WRITE
+        IOobject::NO_WRITE,
+        false
     ),
     mesh,
     dimensionedScalar(pName, sqr(dimVelocity), 0),

applications/solvers/basic/potentialFoam/potentialFoam.C

@@ -24,13 +24,66 @@ License
 Application
     potentialFoam
 
+Group
+    grpBasicSolvers
+
 Description
     Potential flow solver which solves for the velocity potential, to
     calculate the flux-field, from which the velocity field is obtained by
     reconstructing the flux.
 
-    This application is particularly useful to generate starting fields for
-    Navier-Stokes codes.
+    \heading Solver details
+    The potential flow solution is typically employed to generate initial fields
+    for full Navier-Stokes codes.  The flow is evolved using the equation:
+
+    \f[
+        \laplacian \Phi = \div(\vec{U})
+    \f]
+
+    Where:
+    \vartable
+        \Phi      | Velocity potential [m2/s]
+        \vec{U}   | Velocity [m/s]
+    \endvartable
+
+    The corresponding pressure field could be calculated from the divergence
+    of the Euler equation:
+
+    \f[
+        \laplacian p + \div(\div(\vec{U}\otimes\vec{U})) = 0
+    \f]
+
+    but this generates excessive pressure variation in regions of large
+    velocity gradient normal to the flow direction.  A better option is to
+    calculate the pressure field corresponding to velocity variation along the
+    stream-lines:
+
+    \f[
+        \laplacian p + \div(\vec{F}\cdot\div(\vec{U}\otimes\vec{U})) = 0
+    \f]
+    where the flow direction tensor \f$\vec{F}\f$ is obtained from
+    \f[
+        \vec{F} = \hat{\vec{U}}\otimes\hat{\vec{U}}
+    \f]
+
+    \heading Required fields
+    \plaintable
+        U         | Velocity [m/s]
+    \endplaintable
+
+    \heading Optional fields
+    \plaintable
+        p         | Kinematic pressure [m2/s2]
+        Phi       | Velocity potential [m2/s]
+                  | Generated from p (if present) or U if not present
+    \endplaintable
+
+    \heading Options
+    \plaintable
+        -writep   | write the Euler pressure
+        -writePhi | Write the final velocity potential
+        -initialiseUBCs | Update the velocity boundaries before solving for Phi
+    \endplaintable
 
 \*---------------------------------------------------------------------------*/
 
@@ -57,13 +110,13 @@ int main(int argc, char *argv[])
     argList::addBoolOption
     (
         "writePhi",
-        "Write the velocity potential field"
+        "Write the final velocity potential field"
     );
 
     argList::addBoolOption
     (
         "writep",
-        "Calculate and write the pressure field"
+        "Calculate and write the Euler pressure field"
     );
 
     argList::addBoolOption
@@ -133,7 +186,7 @@ int main(int argc, char *argv[])
         Phi.write();
     }
 
-    // Calculate the pressure field
+    // Calculate the pressure field from the Euler equation
     if (args.optionFound("writep"))
     {
         Info<< nl << "Calculating approximate pressure field" << endl;