long-term maintenance improvement for runTime selection tables

See merge request !481

STYLE: use alias to mark partialFaceAreaWeightAMI deprecation after v2012

- this makes the lookup and use of tables slightly cleaner and
  provides a hook for update (compat) messages

  The singleton-style method returns the function pointer directly,
  or nullptr on not-found.

  NEW access method (mnemonic: 'ctor' prefix for constructors)

  ```
  auto* ctorPtr = dictionaryConstructorTable(modelType);

  if (!ctorPtr)
  {
      ...
  }

  return autoPtr<myModel>(ctorPtr(dict, ...));
  ```

  OLD method, which also still works, but without any compat handling:

  ```
  auto ctorIter = dictionaryConstructorTablePtr_->cfind(modelType);

  if (!ctorIter.found())
  {
      ...
  }

  return autoPtr<myModel>(ctorIter()(dict, ...));
  ```

- a Pstream::master with a Pstream::parRun guard in case Pstream has
  not yet been initialised, as will be the case for low-level messages
  during startup.

- propagate relativeName handling into IOstreams

- improves future maintenance, avoids code/macro duplication

- better distinction between content and storage type
  by appending 'Type' to the typedef.

    old: 'Class::abcConstructorTable* tablePtr'
    new: 'Class::abcConstructorTableType* tablePtr'

  Was rarely used in any exposed code.

BREAKING: LESdelta::New with additional table

- parameter change to dictionaryConstructorTableType
  (was dictionaryConstructorTable)

- getThermoOrDie: returns constructor pointer, or FatalError.
  Better isolation and avoids additional template/typename previously
  needed with ambiguous method name (lookupThermo).

- makeThermoName: centralize dictionary -> stringified name

- splitThermoName: use stringOps functionality

ENH: proudmanAcousticPower - extended to operate on mean turbulence fields

See merge request !485

Andrew Heather authored 3 years ago and Mark OLESEN committed 3 years ago

Example using mean turbulence fields (mean fields should be available e.g. from
a fieldAverage function object)

    proudmanAcousticPower1
    {
        // Mandatory entries (unmodifiable)
        type        proudmanAcousticPower;
        libs        (fieldFunctionObjects);

        ...

        // Turbulence field names (if not retrieved from the turb model)
        k           kMean;
        epsilon     epsilonMean;
        omega       none; // omegaMean
    }

- was taking from the current head instead from specified commit-ish

ENH: add -debian=NUM convenience option to foamPackRelease

STYLE: relocate compile begin/end messages

COMP: suppress more clang warnings (needed for boost)

- simplify handling of warnings for surfaceBooleanFeatures

- provide a plain stream() method on messageStream to reduce reliance
  on casting operators and slightly opaque operator()() calls etc

- support alternative stream for messageStream serial output.
  This can be used to support local redirection of output.
  For example,

     refPtr<OFstream> logging;   // or autoPtr, unique_ptr etc

     // Later...
     Info.stream(logging.get())
        << "Detailed output ..." << endl;

  This will use the stdout semantics in the normal case, or allow
  redirection to an output file if a target output stream is defined,
  but still effectively use /dev/null on non-master processes.

  This is mostly the same as this ternary

      (logging ? *logging : Info())

  except that the ternary could be incorrect on sub-processes,
  requires more typing etc.

ENH: use case-relative names of dictionary, IOstream for FatalIOError

- normally yields more easily understandable information

STYLE: more consistent noexcept for dictionary and entry

- argList::envExecutable() static method.
  This is identical to getEnv("FOAM_EXECUTABLE"), where the name of
  the executable has typically been set from the argList construction.

  Provides a singleton access to this value from locations that
  do not have knowledge of the originating command args (argList).
  This is a similar rationale as for the argList::envGlobalPath() static.

- additional argList::envRelativePath() static method.

- make -dry-run handling more central and easier to use by adding into
  argList itself.

STYLE: drop handling of -srcDoc (v1706 option)

- replaced with -doc-source for 1712 and never used much anyhow

- prune unneeded demandDrivenData.H includes

- for compilers such as gcc and clang, may have several different
  variants installed on the computer. Use WM_COMPILER_CONTROL to
  specify the preferred variant.

  Eg,
      WM_COMPILER=Gcc
      WM_COMPILER_CONTROL="version=8"

      will compile with "gcc-8" and "g++-8"

  Good practice would be to tag output directory names with the
  version too. Eg

      WM_COMPILER=Clang110
      WM_COMPILER_CONTROL="version=11.0"

STYLE: modify message for change of gcc -> clang (darwin)

BUG: collated: threaded writing accesses out-of-scope. Fixes #2257.

See merge request !494

- reflects updates for List, globalIndex handling etc

- using the proximityRegions filter when there is no enclosing surface
  to segregate domains causes a surface of zero-faces to be created.

  In most cases, this means that a simpler proximityFaces filter would
  have been more appropriate. To increase overall robustness, revert
  to the simpler proximityFaces filter logic when the proximityRegions
  would otherwise result in zero faces (globally seen).

- reuse single component buffer within an Ensight output method.
  Use direct UPstream read/write to avoid Pstream char buffers

- replace blocking transfer with scheduled for Ensight cloud output

- use the new updates to globalIndex to manage the bookkeeping

- UPstream::mpiGather (MPI_Gather)   - used by Pstream::listGatherValues
- UPstream::mpiScatter (MPI_Scatter) - used by Pstream::listScatterValues

  These are much simpler forms for gather/scatter of fixed-sized
  contiguous types data types (eg, primitives, simple pairs etc).

  In the gather form, creates a list of gathered values on the master
  process. The subranks have a list size of zero.

  Similarly, scatter will distribute a list of values to single values
  on each process.

  Instead of

      labelList sendSizes(Pstream::nProcs());
      sendSizes[Pstream::myProcNo()] = sendData.size();
      Pstream::gatherList(sendSizes);

  Can write

      const labelList sendSizes
      (
          UPstream::listGatherValues<label>(sendData.size())
      );

  // Less code, lower overhead and list can be const.

  For scattering an individual value only,
  instead of

      labelList someValues;
      if (Pstream::master()) someValues = ...;

      Pstream::gatherList(sendSizes);
      const label localValue
      (
          someValues[Pstream::myProcNo()]
      );

  Can write

      labelList someValues;
      if (Pstream::master()) someValues = ...;

      Pstream::gatherList(sendSizes);
      const label localValue
      (
          UPstream::listScatterValues<label>(someValues)
      );

   Can of course also mix listGatherValues to assemble a list on master
   and use Pstream::scatterList to distribute.

ENH: adjusted globalIndex gather methods

- added mpiGather() method [contiguous data only] using MPI_Gatherv

- respect localSize if gathering master data to ensure that a
  request for 0 master elements is properly handled.

- Pstreams can be ascii/binary but are always currentVersion

- rename UIPstream externalBuf_ to 'recvBuf_' for similar naming as
  PstreamBuffers and symmetry with UOPstream::sendBuf_

- specific enum size for commsType (for more compact structures in the
  future). Default construct lists items.

BUG: possible incidental indexing in UIPstream::read(char*, std::streamsize)

- raw reading had been split into beginRawRead(), readRaw().
  However, this could change the current input position (due to word
  boundary alignment), even if the expected count is zero. Make a
  no-op for count == 0. This mirrors UOPstream::write behaviour.

- construct or reset from a list of local sizes. It is generally
  easier and safer to assemble sizes and let globalIndex determine the
  corresponding offsets, when working with raw values.

- Can use reset() from sizes or fine-tune offsets with setLocalSize()
  instead of using the potentially more fragile non-const access to
  the offsets.

- add globalIndex const_iterator to iterate across the access ranges.
  This is makes it simpler to use with the List slice() method to
  access or operate on a sub-section of list.

  For example,
      scalarField allValues = ...;
      globalIndex procAccess = ...;

      for (const labelRange& range : procAccess)
      {
          someOutput(allValues.slice(range));
      }

- the size of a List often requires adjustment prior to an operation,
  but old values (if any) are not of interest and will be overwritten.

  In these cases can use the _nocopy versions to avoid additional memory
  overhead of the intermediate list and the copy/move overhead of
  retaining the old values (that we will subsequently discard anyhow).

  No equivalent for PtrList/UPtrList - this would be too fragile.

- add swap DynamicField with DynamicList

BUG: fixed Dynamic{Field,List} setCapacity corner case

- for the case when the newly requested capacity coincides with the
  current addressable size, the resize of the underlying list would have
  been bypassed - ie, the real capacity was not actually changed.

- remove (unused) PtrDynList setCapacity method as too fragile

- previously returned the range slice as a UList,
  but this prevents convenient assignment.
  Apply similar handling for Field/SubField

  Allows the following

     labelRange range(...);
     fullList.slice(range) = identity(range.size());

  and

     fullList.slice(range) = UIndirectList<T>(other, addr);

ENH: create SubList from full FixedList (simplifies interface)

- allow default constructed SubList. Use shallowCopy to 'reset' later

- simply adds in the reinterpret_cast, which simplifies coding for
  binary data movement.
  Name complements the size_bytes() method for contiguous data

STYLE: container IO.C files into main headers for better visibility

STYLE: include CompactListList.H in polyTopoChange

- avoids future mismatches if the CompactListList template signature
  changes

GIT: relocate CompactListList into CompactLists/ directory

- useSubMesh() - name as per fvMeshSubsetProxy.
  Setter methods take a parameter instead of direct access.

 - encapsulates toggling

STYLE: noexcept for some Time methods

- previously used an indirect patch to get the sampling locations,
  but this doesn't take account of the face flips. Now use
  the faceZone intrinsic for generating a properly flipped patch
  and provide the sampling locations separately.

STYLE: adjust compatiblity header for surfaceMeshWriter

- it is now possible to include the selected mpi version in the
  top-level bashrc or prefs.sh file. For example,

      WM_MPLIB=OPENMPI-4.1.1  or  WM_MPLIB=openmpi-4.1.1

  after evaluation of the config.sh/mpi, this will define

      WM_MPLIB=OPENMPI-4.1.1  and  FOAM_MPI=openmpi-4.1.1

  During the wmake, the mpi-rules will first load the MPI 'family'
  rules (OPENMPI in this example) before trying to load
  version-specific rules if they exist.

  NOTE: the regular user-defined prefs system is unaffected by this
  change. This means it is still possible to use a file such as
  'prefs.openmpi' to define the preferred version instead or as well.
  However, it does mean inconsistent naming can be specified.
  For example, specify WM_MPLIB=OPENMPI-4.1.1 at the top-level but
  actually have FOAM_MPI=openmpi-4.0.6 in the prefs.openmpi file.
  This will make the value of WM_MPLIB misleading.

CONFIG: foamConfigurePaths support for sys-openmpi major version

C...