- if desired to create a tar-file without a _patch value in its name.

- add a '-SPDP' option

- remove the '-archOption' for forcing a '-m32' build on 64-bit
  architecture, which is now considered too obscure.
  Must edit files manually if this option is really required.

A set of libraries and executables creating a workflow for performing
gradient-based optimisation loops. The main executable (adjointOptimisationFoam)
solves the flow (primal) equations, followed by the adjoint equations and,
eventually, the computation of sensitivity derivatives.

Current functionality supports the solution of the adjoint equations for
incompressible turbulent flows, including the adjoint to the Spalart-Allmaras
turbulence model and the adjoint to the nutUSpaldingWallFunction, [1], [2].

Sensitivity derivatives are computed with respect to the normal displacement of
boundary wall nodes/faces (the so-called sensitivity maps) following the
Enhanced Surface Integrals (E-SI) formulation, [3].

The software was developed by PCOpt/NTUA and FOSS GP, with contributions from

Dr. Evangelos Papoutsis-Kiachagias,
Konstantinos Gkaragounis,
Professor Kyriakos Giannakoglou,
Andy Heather

and contributions in earlier version from

Dr. Ioannis Kavvadias,
Dr. Alexandros Zymaris,
Dr. Dimitrios Papadimitriou

[1] A.S. Zymaris, D.I. Papadimitriou, K.C. Giannakoglou, and C. Othmer.
Continuous adjoint approach to the Spalart-Allmaras turbulence model for
incompressible flows. Computers & Fluids, 38(8):1528–1538, 2009.

[2] E.M. Papoutsis-Kiachagias and K.C. Giannakoglou. Continuous adjoint methods
for turbulent flows, applied to shape and topology optimization: Industrial
applications. 23(2):255–299, 2016.

[3] I.S. Kavvadias, E.M. Papoutsis-Kiachagias, and K.C. Giannakoglou. On the
proper treatment of grid sensitivities in continuous adjoint methods for shape
optimization. Journal of Computational Physics, 301:1–18, 2015.

Integration into the official OpenFOAM release by OpenCFD

- options '-n' and '-np' are synonymous, but some mpiexec versions may
  only recognize '-n' and not '-np'

- adapted from the 'foamGet' utility authored by Chris Greenshields

ENH: add -prefs option to pass in a preferences configuration file

- reduces installation clutter, allows easier cross-referencing

- remove older deprecated scripts (foamDebugSwitches, foamGraph*)

- was WM_PROJECT_API in the environment and FOAM_API in dictionaries.

  Make these both consistently FOAM_API.
  This is a non-breaking change, since the value of WM_PROJECT_API
  (added in 1812) and/or FOAM_API is purely informative.
  For the current correct values, always use

    * foamEtcFile -show-api
    * wmakeBuildInfo -show-api

- older emacs tools into legacy
- old process tools

* Less frequently used scripts into bin/tools/

  - findEmptyMake
  - foamAllHC
  - foamUpdateCaseFileHeader

* Infrastructure file (only used by foamNewApp)

  - wmake/wmakeFilesAndOptions -> wmake/scripts/wmakeFilesAndOptions

* Merge wmakeRoot convenience as 'wmake -pwd'
* Remove obsolete wmakePrintBuild (superseded by wmakeBuildInfo)
* Remove unused mergeHistory file

Previously silently accepted '-o' as being equivalent to '-output',
but the former could be misinterpreted meaning an output file (which
it is not) instead of an output directory.

- was WM_PROJECT_API in the environment and FOAM_API in dictionaries.

  Make these both consistently FOAM_API.
  This is a non-breaking change, since the value of WM_PROJECT_API
  (added in 1812) and/or FOAM_API is purely informative.
  For the current correct values, always use

    * foamEtcFile -show-api
    * wmakeBuildInfo -show-api

- this scripts are largely pre-git era and not used much anymore.
  Relocate to a legacy/ sub-directory while we see if there are
  actually any still being used.

- the utility had automatic triangulation removed some time ago, but
  never changed its name.

- catch old uses with a surfaceMeshTriangulate deprecated script

- now use findEtcEntry() instead to handle file or directory.

  Added findEtcEntries(), which provides provides a common code basis
  for findEtcDirs(), findEtcFiles() ...

- restrict to text between "^[Oo]ptions:" and "-help-full" to avoid
  potential issues when more text is introduced in the usage output.

- now needs local 'set' instead of 'setenv'

- fixed inconsistency in edit of ParaView_VERSION for csh version

- now consider options '-hostRoots', '-roots' to be advanced options
  that don't need to be in the cache

- The usage claimed '-output=', but was using '--output=' for the
  output file.  Rectify to use single dash as documented.

- provide default WM_DIR if not already set, to improve robustness if a
  reduced environment is used

- add etc/ to WM_PROJECT_SITE search. This makes the site directory
  structure consistent with the OpenFOAM structure.
  Eg,

      WM_PROJECT_SITE/etc/..
      WM_PROJECT_SITE/bin/..
      WM_PROJECT_SITE/platforms/..

- Don't set/export WM_OSTYPE.  The default is POSIX and is properly
  defaulted throughout, including in CMakeLists-OpenFOAM.txt (also for
  Catalyst)

- Use the OPENFOAM define (eg, 1806, 1812), which normally corresponds
  to a major release, to define an API level. This remains consistent
  within a release cycle and means that it is possible to manage
  several sub-versions and continue to have a consistent lookup.

  The current API value is updated automatically during the build
  and cached as meta data for later use, even when the wmake/ directory
  is missing or OpenFOAM has not yet be initialized.

  The version information reported on program start or with -help
  usage adjusted to reflect this. The build tag from git now also
  carries the date as being more meaningful to trace than a hash
  value.

- Update etc/bashrc and etc/cshrc to obtain the project directory
  directly instead of via its prefix directory. The value obtained
  corresponds to an absolute path, from which the prefix directory
  can be obtained.

  The combination of these changes removes the reliance on any
  particular directory naming convention.
  For example,

     With an 1812 version (API level):

     WM_PROJECT_VERSION=myVersion

     installed as /some/path/somewhere/openfoam-mySandbox

  This makes the -prefix, -foamInstall, -projectVersion, -version
  values of foamEtcFiles, and similar entries for foamConfigurePaths
  superfluous.

  WM_PROJECT_INST_DIR is no longer required or used

ENH: improve handling and discovery of ThirdParty

- improve the flexibility and reusability of ThirdParty packs to cover
  various standard use cases:

    1. Unpacking initial release tar files with two parallel directories
       - OpenFOAM-v1812/
       - ThirdParty-v1812/

    2. With an adjusted OpenFOAM directory name, for whatever reason
       - OpenFOAM-v1812-myCustom/
       - openfoam-1812-other-info/

    3. Operating with/without ThirdParty directory

  To handle these use cases, the following discovery is used.

  Note PROJECT = the OpenFOAM directory `$WM_PROJECT_DIR`
       PREFIX = the parent directory
       VERSION = `$WM_PROJECT_VERSION`
       API = `$WM_PROJECT_API`, as per `foamEtcFiles -show-api`

   0. PROJECT/ThirdParty
      - for single-directory installations

   1. PREFIX/ThirdParty-VERSION
      - this corresponds to the traditional approach

   2. PREFIX/ThirdParty-vAPI
      - allows for an updated value of VERSION (eg, v1812-myCustom)
        without requiring a renamed ThirdParty. The API value
        would still be '1812' and the original ThirdParty-v1812/
        would be found.

   3. PREFIX/ThirdParty-API
      - this is the same as the previous example, but using an unadorned
        API value. This also makes sense if the chosen version name also
        uses the unadorned API value in its naming
        (eg, 1812-patch190131, 1812.19W03)

   4. PREFIX/ThirdParty-common
      - permits maximum reuse for various versions, but only for
        experienced user who are aware of potential version
        incompatibilities

   Directory existence is checked as is the presence of an Allwmake file
   or a platforms/ directory. This reduces the potential of false positive
   matches and limits the selection to directories that are either
   with sources (has the Allwmake file), or pre-compiled binaries (has
   the platforms/ directory).

   If none of the explored directories are found to be suitable,
   it reverts to using a PROJECT/ThirdParty dummy location since
   this is within the project source tree and can be trusted to
   have no negative side-effects.

ENH: add csh support to foamConfigurePaths

- this removes the previously experienced inconsistence in config file
  contents.

REMOVED: foamExec

- was previously used when switching versions and before the
  bashrc/cshrc discovery logic was added. It is now obsolete.

- check if the first argument corresponds to an OpenFOAM value for
  'true' (as per Switch).
  True == 't', 'y', 'true', 'yes', 'on'. Everything else is not true.

- when the first argument is '-dict', it initializes the value
  with a query via foamDictionary.
  Eg,
       isTrue -dict mydict -entry parallel

   ==> value=$(foamDictionary mydict -entry parallel -value)
       isTrue $value

   a missing entry is silently treated as false.

ENH: add getNumberOfPatchFaces function in RunFunctions

- simple extraction of nFaces from boundary file for given patch/region

- was PREFIX/site, now PROJECT/site

  This avoids several issues when installing OpenFOAM in clusters
  without an intermediate OpenFOAM-specific installation prefix.

  The 'site' directory may have a reserved meaning in these situations
  and it is undesirable to 'leak' upwards into the parent directory to
  look for configuration files.

  Placing the default within the project directory avoids this.
  Alternative locations can be given via the WM_PROJECT_SITE variable.

- removed reliance on ParaView_INCLUDE_DIR variable for conveying the
  major.minor version information when compiling. This can be somewhat
  fragile and also adds variable that is an unnecessary when running
  (only used when compiling).

  Instead use `have_pvplugin_support` function in paraviewFunctions
  wmake script to determine the maj.min from the PV_PLUGIN_PATH
  since we have already defined the output path there with paraview
  maj.min numbering.

  Can now build with paraview from the operating system,
  provided that it has develop headers available.

      ParaView_VERSION=system

  In the etc/config.sh/paraview setup, the maj.min is taken from
  the corresponding `paraview --version` output and used when
  defining the PV_PLUGIN_PATH.

  During the build, the include path taken from `paraview-config`
  for a system installation, from the guess installation root
  of the paraview binary, or ParaView_DIR otherwise.

NB: using a system ParaView for building runTimePostProcessing is unsupported.

- these types of builds appear to have various library resolution issues
  (eg, libexpat not being loaded). Additionally, the build logic does
  not yet cover this type of use case.

- skip /, /bin, /usr/bin ... as potential filters.