- avoid dependency on etc/openfoam (location may change)

- with the current handling of small edges (finite-area), the LSQ
  vectors can result in singular/2D tensors. However, the regular
  2D handling in field inv() only detects based on the first element.

  Provide a 'failsafe' inv() method for symmTensor and tensor that
  follows a similar logic for avoiding zero determinates, but it is
  applied on a per element basis, instead of deciding based on the
  first field element.

  The symmTensor::inv(bool) and tensor::inv(bool) methods have a
  fairly modest additional overhead.

- unroll the field inv() function to avoid creating an intermediate
  field.  Reduce the number of operations when adjusting/re-adjusting
  the diagonal.

- for cases where a 3D tensor is being used to represent 2D content,
  the determinant is zero. Can use inv2D(excludeDirection) to compensate
  and invert as if it were only 2D.

ENH: consistent definitions for magSqr of symmTensors, diagSqr() norm

COMP: return scalar not component type for magSqr

- had inconsistent definitions with SymmTensor returning the component
  type and Tensor returning scalar. Only evident with complex.

- had an optimisation to skip attempted reading for zero-sized
  patches. But this leads to inconsistency in the code branching, thus
  removing it.

- when only a partial stacktrace is desirable.

ENH: add stack trace decorators

- the 0-th frame is always printStack(), so skip that and emit
  some headers/footers instead. Eg,

  [stack trace]
  =============
  #1  Foam::SymmTensor<double> Foam::inv<double>(...)
  #2  Foam::inv(Foam::UList<Foam::SymmTensor<double>> const&) ...
  ...
  =============

- data_bytes(), size_bytes() methods to support broadcasting or
  gather/scatter content. Additional construct from raw bytes
  to support transmitting content.

- can be easier to specify than copying into a dimensioned type.

  Eg,
      volSymmTensorField(io, mesh, Zero, dimLength);

      fluxFieldType
      (
          io
          mesh,
          Zero,
          Uf.dimensions()*dimArea/dimTime
      );

  vs
      volSymmTensorField
      (
          io,
          mesh,
          dimensionedSymmTensor("0", dimLength, Zero)
      );

      fluxFieldType
      (
          io
          mesh,
          dimensioned<typename flux<Type>::type>
          (
              Uf.dimensions()*dimArea/dimTime, Zero
          )
      );

- missed consistency in a few places.

- return nullptr (with automatic conversion to tmp) on failures
  instead of tmp<....>(nullptr), for cleaner coding.

INT: add support for an 'immovable' tmp pointer

- this idea is from openfoam.org, to allow creation of a tmp that is
  protected from having its memory reclaimed in field operations

ENH: tmp NewImmovable factory method, forwards as immovable/movable

mattijs authored 2 years ago and Mark OLESEN committed 2 years ago

- no-op implementations, but makes the call to
  GeometricBoundaryField::evaluate() less dependent on PatchField type

- add updated()/manipulatedMatrix() methods to faePatchField,
  fvsPatchField etc. These are mostly no-ops, but provide name
  compatible with fvPatchField etc.

- self-documenting

- similar to UPstream::parRun(), the setter returns the previous value.

  The accessors are prefixed with 'comm':
  Eg, commGlobal(), commWarn(), commWorld(), commSelf().
  This distinguishes them from any existing variables (eg, worldComm)
  and arguably more similar to MPI_COMM_WORLD etc...

  If demand-driven communicators are added in the future, the function
  call syntax can help encapsulate that.

  Previously:

      const label oldWarnComm = UPstream::warnComm;
      const label oldWorldComm = UPstream::worldComm;
      UPstream::warnComm = myComm;
      UPstream::worldComm = myComm;
      ...

      UPstream::warnComm = oldWarnComm;
      UPstream::worldComm = oldWorldComm;

  Now:
      const label oldWarnComm = UPstream::commWarn(myComm);
      const label oldWorldComm = UPstream::commWorld(myComm);
      ...

      UPstream::commWarn(oldWarnComm);
      UPstream::commWorld(oldWorldComm);

STYLE: check (warnComm >= 0) instead of (warnComm != -1)

- deprecate timeVaryingUniformFixed (now redundant)

- base level now explicity equivalent to LAZY_READ with overriding as
  required

- clearer documentation for reading of "value" for faPatchField

- constructing with valueRequired as a bool is still supported,
  but now also support more refined requirements
  (eg, NO_READ, MUST_READ, LAZY_READ)

- continue with LAZY_READ for finite-area fields

STYLE: use readValueEntry and Field assign to simplify code

ENH: improved point-cell and cell-point topology methods (#2715)

See merge request !597

ENH: construct or reset boundBox from zero_one for a 0-1 unit cube

ENH: add some testing timings (for !596 and #2715)

ENH: support VTK output of procIDs for point data for some writers

TUT: areaWrite for drippingChair

- interpret as '-decomposeParDict xyz' for simpler scripting:
  A empty value ("") as well as "none" or "false" values are ignored.

  Eg,
      unset decompDict
      if some_condition; then decompDict=decomposeParDict-12; fi

      runParallel -decompose-dict=$decompDict ...

ENH: more generous when scanning decomposeParDict for numberOfSubdomains

- assume file is in system/ directory if not otherwise found

- this helps isolate selection of PEX vs NBX, for potential migration
  to a hybrid PEX

STYLE: more generous handling of procIDs on non-master (globalIndex)

- useful when regular contents are to be read via an IOobject and
  returned.

  Eg,  dictionary propsDict(IOdictionary::readContents(dictIO));
  vs.  dictionary propsDict(static_cast<dictionary&&>(IOdictionary(dictIO)));

  Commonly these would have simply been constructed directly as the
  IO container:

  eg,  IOdictionary propsDict(dictIO);

  However, that style may not ensure proper move semantics for return
  types.

  Now,
  =====
      labelList decomp(labelIOList::readContents(io));
      ... something
      return decomp;
  =====

  Previously,
  =====
      labelIOList decomp(io);

      // Hope for the best...
      return decomp;

      // Or be explicit and ensure elision occurs...
      return labelList(std::move(static_cast<labelList&>(decomp)));
  =====

  Note:
       labelList list(labelIOList(io));

       looks like a good idea, but generally fails to compile

STYLE: split off primitiveMesh::calcCellPoints internal

- for easier reworking (#2715)

- the iterator/const_iterator now skip any nullptr entries,
  which enables the following code to work even if the PtrList
  contains nullptr:

  for (const auto& intf : interfaces)
  {
      // Do something
      ...
  }

- this is a change in behaviour compared to OpenFOAM-v2212 and earlier,
  but is non-breaking:
  * Lists without null entries will traverse exactly as before.
  * Lists with null entries will now traverse correctly without
    provoking a FatalError.

- random access was unused.
  Retaining it would impede reimplementing iterators to only iterate
  across non-null items.

- naming as per bitSet (ie, find_first, find_next) that work with list
  indices.
- relocate bounds checked access into detail. Add at() accessor

- allows unambiguous of count() for other classes.
  Naming as per std::shared_ptr.

STYLE: qualify use_count() and unique() methods with the refCount base

- clearer/consistent meaning

STYLE: document edge parameters as 'vertex' (not point)

- edge is also used for graph edges or connection edges etc.