- previously only defined for cell-cutting version, now for
  iso-surface version too

TUT: remove old transform/coordinateSystem syntax

Minor clean-up

- override casename, procesorCase flags to guarantee reconstructed
case to be written to the undecomposed directory
- alternative is to construct a Zero mesh on the undecomposed
runTime and add all other bits to that but that has not been
pursued

- for blockMesh meshing and as snappyHexMesh geometry
  (adjust the igloo aspect ratio)

- code reduction, documentation, code stubs for spheroid (#1901)

- make searchableSurfaceCollection available as 'collection'
  for consistency with other objects

Previously the coordinate system functionality was split between
coordinateSystem and coordinateRotation. The coordinateRotation stored
the rotation tensor and handled all tensor transformations.

The functionality has now been revised and consolidated into the
coordinateSystem classes. The sole purpose of coordinateRotation
is now just to provide a selectable mechanism of how to define the
rotation tensor (eg, axis-angle, euler angles, local axes) for user
input, but after providing the appropriate rotation tensor it has
no further influence on the transformations.

--

The coordinateSystem class now contains an origin and a base rotation
tensor directly and various transformation methods.

  - The origin represents the "shift" for a local coordinate system.

  - The base rotation tensor represents the "tilt" or orientation
    of the local coordinate system in general (eg, for mapping
    positions), but may require position-dependent tensors when
    transforming vectors and tensors.

For some coordinate systems (currently the cylindrical coordinate system),
the rotation tensor required for rotating a vector or tensor is
position-dependent.

The new coordinateSystem and its derivates (cartesian, cylindrical,
indirect) now provide a uniform() method to define if the rotation
tensor is position dependent/independent.

The coordinateSystem transform and invTransform methods are now
available in two-parameter forms for obtaining position-dependent
rotation tensors. Eg,

      ... = cs.transform(globalPt, someVector);

In some cases it can be useful to use query uniform() to avoid
storage of redundant values.

      if (cs.uniform())
      {
          vector xx = cs.transform(someVector);
      }
      else
      {
          List<vector> xx = cs.transform(manyPoints, someVector);
      }

Support transform/invTransform for common data types:
   (scalar, vector, sphericalTensor, symmTensor, tensor).

====================
  Breaking Changes
====================

- These changes to coordinate systems and rotations may represent
  a breaking change for existing user coding.

- Relocating the rotation tensor into coordinateSystem itself means
  that the coordinate system 'R()' method now returns the rotation
  directly instead of the coordinateRotation. The method name 'R()'
  was chosen for consistency with other low-level entities (eg,
  quaternion).

  The following changes will be needed in coding:

      Old:  tensor rot = cs.R().R();
      New:  tensor rot = cs.R();

      Old:  cs.R().transform(...);
      New:  cs.transform(...);

  Accessing the runTime selectable coordinateRotation
  has moved to the rotation() method:

      Old:  Info<< "Rotation input: " << cs.R() << nl;
      New:  Info<< "Rotation input: " << cs.rotation() << nl;

- Naming consistency changes may also cause code to break.

      Old:  transformVector()
      New:  transformPrincipal()

  The old method name transformTensor() now simply becomes transform().

====================
  New methods
====================

For operations requiring caching of the coordinate rotations, the
'R()' method can be used with multiple input points:

       tensorField rots(cs.R(somePoints));

   and later

       Foam::transformList(rots, someVectors);

The rotation() method can also be used to change the rotation tensor
via a new coordinateRotation definition (issue #879).

The new methods transformPoint/invTransformPoint provide
transformations with an origin offset using Cartesian for both local
and global points. These can be used to determine the local position
based on the origin/rotation without interpreting it as a r-theta-z
value, for example.

================
  Input format
================

- Streamline dictionary input requirements

  * The default type is cartesian.
  * The default rotation type is the commonly used axes rotation
    specification (with e1/e2/3), which is assumed if the 'rotation'
    sub-dictionary does not exist.

    Example,

    Compact specification:

        coordinateSystem
        {
            origin  (0 0 0);
            e2      (0 1 0);
            e3      (0.5 0 0.866025);
        }

    Full specification (also accepts the longer 'coordinateRotation'
    sub-dictionary name):

        coordinateSystem
        {
            type    cartesian;
            origin  (0 0 0);

            rotation
            {
                type    axes;
                e2      (0 1 0);
                e3      (0.5 0 0.866025);
            }
        }

   This simplifies the input for many cases.

- Additional rotation specification 'none' (an identity rotation):

      coordinateSystem
      {
          origin  (0 0 0);
          rotation { type none; }
      }

- Additional rotation specification 'axisAngle', which is similar
  to the -rotate-angle option for transforming points (issue #660).
  For some cases this can be more intuitive.

  For example,

      rotation
      {
          type    axisAngle;
          axis    (0 1 0);
          angle   30;
      }
  vs.
      rotation
      {
          type    axes;
          e2      (0 1 0);
          e3      (0.5 0 0.866025);
      }

- shorter names (or older longer names) for the coordinate rotation
  specification.

     euler         EulerRotation
     starcd        STARCDRotation
     axes          axesRotation

================
  Coding Style
================
- use Foam::coordSystem namespace for categories of coordinate systems
  (cartesian, cylindrical, indirect). This reduces potential name
  clashes and makes a clearer declaration. Eg,

      coordSystem::cartesian csys_;

  The older names (eg, cartesianCS, etc) remain available via typedefs.

- added coordinateRotations namespace for better organization and
  reduce potential name clashes.

- improve doxygen entries for searchable surfaces.

- support selection of searchable surfaces with shorter names.
  Eg,
      type   box | cylinder | ...;
  vs  type   searchableBox | searchableCylinder | ...;

  Within decomposeParDict, it is now possible to specify a different
  decomposition method, methods coefficients or number of subdomains
  for each region individually.

  The top-level numberOfSubdomains remains mandatory, since this
  specifies the number of domains for the entire simulation.
  The individual regions may use the same number or fewer domains.

  Any optional method coefficients can be specified in a general
  "coeffs" entry or a method-specific one, eg "metisCoeffs".

  For multiLevel, only the method-specific "multiLevelCoeffs" dictionary
  is used, and is also mandatory.

----

ENH: shortcut specification for multiLevel.

  In addition to the longer dictionary form, it is also possible to
  use a shorter notation for multiLevel decomposition when the same
  decomposition method applies to each level.

- consistent versions in headers

- although this has been supported for many years, the tutorials
  continued to use "convertToMeters" entry, which is specific to blockMesh.
  The "scale" is more consistent with other dictionaries.

ENH:
- ignore "scale 0;" (treat as no scaling) for blockMeshDict,
  consistent with use elsewhere.

    #includeEtc "caseDicts/setConstraintTypes"
 vs.
    #include "${WM_PROJECT_DIR}/etc/caseDicts/setConstraintTypes"

Original commit message:
------------------------

Parallel IO: New collated file format

When an OpenFOAM simulation runs in parallel, the data for decomposed fields and
mesh(es) has historically been stored in multiple files within separate
directories for each processor.  Processor directories are named 'processorN',
where N is the processor number.

This commit introduces an alternative "collated" file format where the data for
each decomposed field (and mesh) is collated into a single file, which is
written and read on the master processor.  The files are stored in a single
directory named 'processors'.

The new format produces significantly fewer files - one per field, instead of N
per field.  For large parallel cases, this avoids the restriction on the number
of open files imposed by the operating system limits.

The file writing can be threaded allowing the simulation to continue running
while the data is being written to file.  NFS (Network File System) is not
needed when using the the collated format and additionally, there is an option
to run without NFS with the original uncollated approach, known as
"masterUncollated".

The controls for the file handling are in the OptimisationSwitches of
etc/controlDict:

OptimisationSwitches
{
    ...

    //- Parallel IO file handler
    //  uncollated (default), collated or masterUncollated
    fileHandler uncollated;

    //- collated: thread buffer size for queued file writes.
    //  If set to 0 or not sufficient for the file size threading is not used.
    //  Default: 2e9
    maxThreadFileBufferSize 2e9;

    //- masterUncollated: non-blocking buffer size.
    //  If the file exceeds this buffer size scheduled transfer is used.
    //  Default: 2e9
    maxMasterFileBufferSize 2e9;
}

When using the collated file handling, memory is allocated for the data in the
thread.  maxThreadFileBufferSize sets the maximum size of memory in bytes that
is allocated.  If the data exceeds this size, the write does not use threading.

When using the masterUncollated file handling, non-blocking MPI communication
requires a sufficiently large memory buffer on the master node.
maxMasterFileBufferSize sets the maximum size in bytes of the buffer.  If the
data exceeds this size, the system uses scheduled communication.

The installation defaults for the fileHandler choice, maxThreadFileBufferSize
and maxMasterFileBufferSize (set in etc/controlDict) can be over-ridden within
the case controlDict file, like other parameters.  Additionally the fileHandler
can be set by:
- the "-fileHandler" command line argument;
- a FOAM_FILEHANDLER environment variable.

A foamFormatConvert utility allows users to convert files between the collated
and uncollated formats, e.g.
    mpirun -np 2 foamFormatConvert -parallel -fileHandler uncollated

An example case demonstrating the file handling methods is provided in:
$FOAM_TUTORIALS/IO/fileHandling

The work was undertaken by Mattijs Janssens, in collaboration with Henry Weller.

Resolves bug-report http://bugs.openfoam.org/view.php?id=2314

using a run-time selectable preconditioner

References:
    Van der Vorst, H. A. (1992).
    Bi-CGSTAB: A fast and smoothly converging variant of Bi-CG
    for the solution of nonsymmetric linear systems.
    SIAM Journal on scientific and Statistical Computing, 13(2), 631-644.

    Barrett, R., Berry, M. W., Chan, T. F., Demmel, J., Donato, J.,
    Dongarra, J., Eijkhout, V., Pozo, R., Romine, C. & Van der Vorst, H.
    (1994).
    Templates for the solution of linear systems:
    building blocks for iterative methods
    (Vol. 43). Siam.

See also: https://en.wikipedia.org/wiki/Biconjugate_gradient_stabilized_method

Tests have shown that PBiCGStab with the DILU preconditioner is more
robust, reliable and shows faster convergence (~2x) than PBiCG with
DILU, in particular in parallel where PBiCG occasionally diverges.

This remarkable improvement over PBiCG prompted the update of all
tutorial cases currently using PBiCG to use PBiCGStab instead.  If any
issues arise with this update please report on Mantis: http://bugs.openfoam.org