- allows reuse for other purposes

- simply combines (rootPath()/globalCaseName())

Style changes:
    - use lookupObjectRef instead of using const_cast
    - use tmp::New factory

General:
    * -roots, -hostRoots, -fileHandler

Specific:
    * -to <coordinateSystem> -from <coordinateSystem>

- Display -help-compat when compatibility or ignored options are available

STYLE: capitalization of options text

- avoids compiler ambiguity when virtual methods such as
  IOdictionary::read() exist.

- the method was introduced in 1806, and was thus not yet widely used

- add additional control via a Foam::infoDetailLevel flag, which is
  supported by a 'DetailLevel' macro.  Eg,

      DetailLevel << "some information" << nl

- When infoDetailLevel is zero, the stdout for all Foam::system() calls
  are also redirected to stderr to prevent child output from
  appearing on the parent.

- close stdin before exec in system call.

- make the purpose more explicit, and reduces some work for the
  compiler as well.

- controlled by the the 'printExecutionFormat' InfoSwitch in
  etc/controlDict

      // Style for "ExecutionTime = " output
      // - 0 = seconds (with trailing 's')
      // - 1 = day-hh:mm:ss

   ExecutionTime = 112135.2 s  ClockTime = 113017 s

   ExecutionTime = 1-07:08:55.20  ClockTime = 1-07:23:37

- Callable via the new Time::printExecutionTime() method,
  which also helps to reduce clutter in the applications.
  Eg,

     runTime.printExecutionTime(Info);

  vs

     Info<< "ExecutionTime = " << runTime.elapsedCpuTime() << " s"
         << "  ClockTime = " << runTime.elapsedClockTime() << " s"
         << nl << endl;

--

ENH: return elapsedClockTime() and clockTimeIncrement as double

- previously returned as time_t, which is less portable.

- IOstreamOption class to encapsulate format, compression, version.
  This is ordered to avoid internal padding in the structure, which
  reduces several bytes of memory overhead for stream objects
  and other things using this combination of data.

  Byte-sizes:
      old  IOstream:48  PstreamBuffers:88  Time:928
      new  IOstream:24  PstreamBuffers:72  Time:904

====

STYLE: remove support for deprecated uncompressed/compressed selectors

In older versions, the system/controlDict used these types of
specifications:

    writeCompression uncompressed;
    writeCompression compressed;

As of DEC-2009, these were deprecated in favour of using normal switch
names:

    writeCompression true;
    writeCompression false;
    writeCompression on;
    writeCompression off;

Now removed these deprecated names and treat like any other unknown
input and issue a warning. Eg,

   Unknown compression specifier 'compressed', assuming no compression

====

STYLE: provide Enum of stream format names (ascii, binary)

====

COMP: fixed incorrect IFstream construct in FIREMeshReader

- spurious bool argument (presumably meant as uncompressed) was being
  implicitly converted to a versionNumber. Now caught by making
  IOstreamOption::versionNumber constructor explicit.

- bad version specifier in changeDictionary

- avoid clockTime in favour of clockValue.

- avoid allocations when profiling is not active.

- replace hashing with manual pointer lists

- in many cases can just use lookupOrDefault("key", bool) instead of
  lookupOrDefault<bool> or lookupOrDefault<Switch> since reading a
  bool from an Istream uses the Switch(Istream&) anyhow

STYLE: relocated Switch string names into file-local scope

Improve alignment of its behaviour with std::unique_ptr

  - element_type typedef
  - release() method - identical to ptr() method
  - get() method to get the pointer without checking and without releasing it.
  - operator*() for dereferencing

Method name changes

  - renamed rawPtr() to get()
  - renamed rawRef() to ref(), removed unused const version.

Removed methods/operators

  - assignment from a raw pointer was deleted (was rarely used).
    Can be convenient, but uncontrolled and potentially unsafe.
    Do allow assignment from a literal nullptr though, since this
    can never leak (and also corresponds to the unique_ptr API).

Additional methods

  - clone() method: forwards to the clone() method of the underlying
    data object with argument forwarding.

  - reset(autoPtr&&) as an alternative to operator=(autoPtr&&)

STYLE: avoid implicit conversion from autoPtr to object type in many places

- existing implementation has the following:

     operator const T&() const { return operator*(); }

  which means that the following code works:

       autoPtr<mapPolyMesh> map = ...;
       updateMesh(*map);    // OK: explicit dereferencing
       updateMesh(map());   // OK: explicit dereferencing
       updateMesh(map);     // OK: implicit dereferencing

  for clarity it may preferable to avoid the implicit dereferencing

- prefer operator* to operator() when deferenced a return value
  so it is clearer that a pointer is involve and not a function call
  etc    Eg,   return *meshPtr_;  vs.  return meshPtr_();

- remove writeLagrangianCoordinates as InfoSwitch, since this is
  something that a regular user should not be able to disable.

- add copy construct from UList

- remove copy construct from dissimilar types.

  This templated constructor was too generous in what it accepted.
  For the special cases where a copy constructor is required with
  a change in the data type, now use the createList factory method,
  which accepts a unary operator. Eg,

      auto scalars = scalarList::createList
      (
          labels,
          [](const label& val){ return 1.5*val; }
      );

- use succincter method names that more closely resemble dictionary
  and HashTable method names. This improves method name consistency
  between classes and also requires less typing effort:

    args.found(optName)        vs.  args.optionFound(optName)
    args.readIfPresent(..)     vs.  args.optionReadIfPresent(..)
    ...
    args.opt<scalar>(optName)  vs.  args.optionRead<scalar>(optName)
    args.read<scalar>(index)   vs.  args.argRead<scalar>(index)

- the older method names forms have been retained for code compatibility,
  but are now deprecated

- now avoid Istream and token mechanism in favour of a simpler string
  parser. This makes the code clearer, smaller, robuster.

- provide convenience ge/gt/le/lt static constructors for scalarRange
  for using bounds directly with specifying via a string parameter.

- scalarRange, scalarRanges now follow the unary predicate pattern
  (using an operator() for testing). This allows their reuse in
  other contexts. Eg, for filtering operations:

      myHash.filterValues(scalarRange::ge(100));

- remove unused scalarRanges methods that were specific to handling
  lists of time values. These were superseded by timeSelector methods
  several versions ago.

- check for excess input on command-line arguments

- reduce fileHandler warning verbosity when the output banner is
  disabled

- relocate some standard functionality to TimePaths to allow a lighter
  means of managing time directories without using the entire Time
  mechanism.

- optional enableLibs for Time construction (default is on)
  and a corresponding argList::noLibs() and "-no-libs" option

STYLE:

- mark Time::outputTime() as deprecated MAY-2016

- use pre-increment for runTime, although there is no difference in
  behaviour or performance.

- similar idea as subCycleTime but without sub-dividing the time
  interval or incrementing time itself

- expose the names of write and stopAt controls for reuse elsewhere and
  provide a stopAtControls enum for 'unknown'

- track the requested number of sub-cycles (was previously a bool)

- in most cases already checked valid() so don't need additional check
  for setting an existing pointer

Improvements to existing functionality
--------------------------------------
  - MPI is initialised without thread support if it is not needed e.g. uncollated
  - Use native c++11 threading; avoids problem with static destruction order.
  - etc/cellModels now only read if needed.
  - etc/controlDict can now be read from the environment variable FOAM_CONTROLDICT
  - Uniform files (e.g. '0/uniform/time') are now read only once on the master only
    (with the masterUncollated or collated file handlers)
  - collated format writes to 'processorsNNN' instead of 'processors'.  The file
    format is unchanged.
  - Thread buffer and file buffer size are no longer limited to 2Gb.

The global controlDict file contains parameters for file handling.  Under some
circumstances, e.g. running in parallel on a system without NFS, the user may
need to set some parameters, e.g. fileHandler, before the global controlDict
file is read from file.  To support this, OpenFOAM now allows the global
controlDict to be read as a string set to the FOAM_CONTROLDICT environment
variable.

The FOAM_CONTROLDICT environment variable can be set to the content the global
controlDict file, e.g. from a sh/bash shell:

    export FOAM_CONTROLDICT=$(foamDictionary $FOAM_ETC/controlDict)

FOAM_CONTROLDICT can then be passed to mpirun using the -x option, e.g.:

    mpirun -np 2 -x FOAM_CONTROLDICT simpleFoam -parallel

Note that while this avoids the need for NFS to read the OpenFOAM configuration
the executable still needs to load shared libraries which must either be copied
locally or available via NFS or equivalent.

New: Multiple IO ranks
----------------------
The masterUncollated and collated fileHandlers can now use multiple ranks for
writing e.g.:

    mpirun -np 6 simpleFoam -parallel -ioRanks '(0 3)'

In this example ranks 0 ('processor0') and 3 ('processor3') now handle all the
I/O.  Rank 0 handles 0,1,2 and rank 3 handles 3,4,5.  The set of IO ranks should always
include 0 as first element and be sorted in increasing order.

The collated fileHandler uses the directory naming processorsNNN_XXX-YYY where
NNN is the total number of processors and XXX and YYY are first and last
processor in the rank, e.g. in above example the directories would be

    processors6_0-2
    processors6_3-5

and each of the collated files in these contains data of the local ranks
only. The same naming also applies when e.g. running decomposePar:

decomposePar -fileHandler collated -ioRanks '(0 3)'

New: Distributed data
---------------------

The individual root directories can be placed on different hosts with different
paths if necessary.  In the current framework it is necessary to specify the
root per slave process but this has been simplified with the option of specifying
the root per host with the -hostRoots command line option:

    mpirun -np 6 simpleFoam -parallel -ioRanks '(0 3)' \
        -hostRoots '("machineA" "/tmp/" "machineB" "/tmp")'

The hostRoots option is followed by a list of machine name + root directory, the
machine name can contain regular expressions.

New: hostCollated
-----------------

The new hostCollated fileHandler automatically sets the 'ioRanks' according to
the host name with the lowest rank e.g. to run simpleFoam on 6 processors with
ranks 0-2 on machineA and ranks 3-5 on machineB with the machines specified in
the hostfile:

    mpirun -np 6 --hostfile hostfile simpleFoam -parallel -fileHandler hostCollated

This is equivalent to

    mpirun -np 6 --hostfile hostfile simpleFoam -parallel -fileHandler collated -ioRanks '(0 3)'

This example will write directories:

    processors6_0-2/
    processors6_3-5/

A typical example would use distributed data e.g. no two nodes, machineA and
machineB, each with three processes:

    decomposePar -fileHandler collated -case cavity

    # Copy case (constant/*, system/*, processors6/) to master:
    rsync -a cavity machineA:/tmp/

    # Create root on slave:
    ssh machineB mkdir -p /tmp/cavity

    # Run
    mpirun --hostfile hostfile icoFoam \
        -case /tmp/cavity -parallel -fileHandler hostCollated \
        -hostRoots '("machineA" "/tmp" "machineB" "/tmp")'

Contributed by Mattijs Janssens

- use allocator class to wrap the stream pointers instead of passing
  them into ISstream, OSstream and using a dynamic cast to delete
  then. This is especially important if we will have a bidirectional
  stream (can't delete twice!).

STYLE:

- file stream constructors with std::string (C++11)

- for rewind, explicit about in|out direction. This is not currently
  important, but avoids surprises with any future bidirectional access.

- combined string streams in StringStream.H header.
  Similar to <sstream> include that has both input and output string
  streams.

- since the cpu/sys information is invariant, it doesn't make much
  sense to emit by default at every time-step.

Henry Weller authored Aug 17, 2017 and Andrew Heather committed Aug 17, 2017

Resolves bug-report https://bugs.openfoam.org/view.php?id=2667

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.

- patch from Bernhard Gschaider

- patch from Bernhard Gschaider

- consistent use of watchIndex vs watchFd

Fixed by setting flag which then gets queried by Time. Fixes #420.

Using

decomposePar -copyZero

The mesh is decomposed as usual but the '0' directory is recursively copied to
the 'processor.*' directories rather than decomposing the fields.  This is a
convenient option to handle cases where the initial field files are generic and
can be used for serial or parallel running.  See for example the
incompressible/simpleFoam/motorBike tutorial case.

- do not enable function objects by default if there is no means of
  disabling them.

Compressing and decompressing binary files introduces a significant IO overhead
without a providing significant reduction in file-size.