- leave /guides/upgrade as symlink

upgrade/v2006-Developer-Upgrade-Guide.md

+<!-- --- title: Developer Upgrade Guide (OpenFOAM-v2006) -->
+
+[![home](/icons/home.svg "wiki home")](/home)
+[![upgrade](/icons/chevrons-up.svg "upgrade guide")][upgrade-guide]
+[![code](/icons/code.svg "coding patterns")][code-patterns]
+
+[[_TOC_]]
+
+## General
+
+- Added `using std::unique_ptr` into the `Foam` namespace within
+  in stdFoam.H (and autoPtr.H) to ensure general availability
+  as `Foam::unique_ptr` or `std::unique_ptr`. Change some
+  old-style handling using _demand-driven-data_ or autoPtr to use
+  `unique_ptr`, especially in low-level containers.
+
+
+## Deprecation and Removal
+
+### Deprecated Methods
+
+- silently deprecate the `env()` function in favour of `hasEnv()` for
+  testing existence of an environment with a non-zero length.
+  This naming is makes the purpose more explicit, and more similar to
+  `getEnv()`, `setEnv()` naming.
+- compile-time deprecation warning for objectRegistry methods
+  `lookupObjectPtr()` and `lookupObjectRefPtr()` that were previous
+  silently deprecated (2018-10) in favour of `findObject()` and
+  `getObjectPtr()`, respectively.
+
+
+### Removed Methods
+
+#### Switch::asText()
+
+Remove the Switch `asText()` method which was replaced by
+`c_str()` and `str()` several versions ago.
+
+
+#### invariantIII()
+
+The function templates [SymmTensor2D.invariantIII()](https://develop.openfoam.com/Development/openfoam/-/blob/OpenFOAM-v1912/src/OpenFOAM/primitives/SymmTensor2D/SymmTensor2DI.H#L354) and [Tensor2D.invariantIII()](https://develop.openfoam.com/Development/openfoam/-/blob/OpenFOAM-v1912/src/OpenFOAM/primitives/Tensor2D/Tensor2DI.H#L586) were removed since the third invariant does not exist for 2-by-2 matrices (see 66b02ca5ca770f).
+
+### Removed Items
+
+- The surfMesh samplers have been removed.
+  These provided a means of sampling and holding surface values
+  internally, but are now redundant with the changes in surface sampling
+  introduced in OpenFOAM-v1906.
+
+
+## Changes in definition
+
+- The template parameters for PrimitivePatch have been simplified from
+  four parameters to two parameters.
+  Does not appear to affect any _normal_ user coding.
+
+
+## Changes in behaviour
+
+### Analytical eigendecomposition
+
+In OpenFOAM, eigenvalues and eigenvectors of a given [tensor](https://develop.openfoam.com/Development/openfoam/-/blob/OpenFOAM-v1912/src/OpenFOAM/primitives/Tensor/tensor/tensor.H)/[tensor2D](https://develop.openfoam.com/Development/openfoam/-/blob/OpenFOAM-v1912/src/OpenFOAM/primitives/Tensor2D/tensor2D/tensor2D.H) have been computed by explicit algebraic expressions. However, there has been three issues prior to `v2006`:
+
+- Complex-type eigenvalues and eigenvectors were not allowed from `tensor`/`tensor2D`.
+- The eigendecomposition algorithms for `tensor`/`tensor2D` were numerically fragile to a considerable extent.
+- No eigendecomposition algorithm was available for [symmTensor](https://develop.openfoam.com/Development/openfoam/-/blob/OpenFOAM-v1912/src/OpenFOAM/primitives/SymmTensor/symmTensor/symmTensor.H)/[symmTensor2D](https://develop.openfoam.com/Development/openfoam/-/blob/OpenFOAM-v1912/src/OpenFOAM/primitives/SymmTensor2D/symmTensor2D/symmTensor2D.H).
+
+In `v2006`:
+
+- New eigendecomposition algorithms were provided for `symmTensor`/`symmTensor2D`.
+- The return types of analytical eigendecomposition algorithms were ensured to be mathematically consistent (see 55e7da670c2dab46ac):
+  - `tensor` and `tensor2D` now return only complex eigenvalues and eigenvectors.
+  - `symmTensor` and `symmTensor2D` now return only scalar eigenvalues and eigenvectors.
+- The fragility of the eigendecomposition algorithms was considerably reduced particularly by improving the numerical stability of polynomial root finding algorithms (see 8ca724fffa81f4d338f, 55e7da670c2dab46).
+- Header documentation, and test applications carrying out bitwise comparisons with external software were considerably improved to prevent any unannounced changes in input/output behaviour (see 55e7da670c2dab46, 6a53794e0a68ed9, 66b02ca5ca7, 8ca724fffa81f).
+
+### invariantII()
+
+The algorithms computing the second invariant in the function templates [Tensor2D.invariantII()](https://develop.openfoam.com/Development/openfoam/-/blob/OpenFOAM-v1912/src/OpenFOAM/primitives/Tensor2D/Tensor2DI.H#L568) and [SymmTensor2D.invariantII()](https://develop.openfoam.com/Development/openfoam/-/blob/OpenFOAM-v1912/src/OpenFOAM/primitives/SymmTensor2D/SymmTensor2DI.H#L338) were corrected to produce the correct output (see 66b02ca5ca770).
+
+
+### Dictionary
+
+- unify use of dictionary method names.<br>
+  In previous releases introduced various types of dictionary _"get"_
+  methods, include `getOrDefault`. Now complete the transition and use
+  `getOrDefault` everywhere that previously had `lookupOrDefault`.
+  This avoids mixed usage of the two methods that are identical in
+  behaviour, makes for shorter names, and promotes the distinction
+  between _"lookup"_ access (ie, return a token stream, locate and
+  return an entry) and _"get"_ access (ie, the above with conversion to
+  concrete types such as `scalar`, `label` etc).
+
+- added single parameter dictionary `writeEntry()` method.<br>
+  The dictionary knows its own name (dictName), which can be used when
+  writing content.
+
+
+### argList
+
+- Extend argList handling to include predicate checks
+- Further align naming of argList methods with dictionary method names.
+- Silently deprecate two-parameter get() method in favour of the
+  more familiar getOrDefault.
+- Silently deprecate `opt()` method in favour of `get()`
+
+
+### Strings
+
+- stringListOps with whitelist/blacklist matching
+- stringOps inplaceRemoveSpace() and string replaceAny() methods.<br>
+  The `replaceAny()` method takes a search string and a replacement
+  character. The replacement character can also be a nul char ('\0'),
+  which simply removes the characters. Some possible uses:
+  - Replace reserved characters
+    ```
+    str.replaceAny("<>:", '_');
+    ```
+  - Remove shell meta-characters or reserved filesystem characters
+    ```
+    str.replaceAny("*?<>{}[]:", '\0');
+    ```
+
+
+### Streams
+
+- Additional `ISstream::getLine()` accepting a `nullptr`.<br>
+  This passes through to `std::istream::ignore` to support read
+  and discarding of lines _without_ buffering their content.
+
+
+#### IOstreamOption
+
+- Support default values for format/compress enum lookups.<br>
+  Avoids situations where the preferred default format is not ASCII.
+  For example, with the dictionary input:
+  ```
+  format binar;
+  ```
+  The typing mistake would previously have caused formatEnum to
+  default to ASCII. We can now properly control its default
+  behaviour:
+  ```
+  IOstream::formatEnum(dict.get<word>("format"), IOstream::BINARY);
+  ```
+
+
+#### IOstreamOption for constructing streams
+
+- The stream constructors now accept `IOstreamOption` to conveniently
+  bundle IO options as a single parameter.
+- Use IOstreamOption for writeObject() calls.
+
+  Both of these changes reduce the number of parameters that are being
+  passed around and allow future additions into the IOstreamOption
+  with mininal effort.
+
+
+### regIOobject
+
+The `store()` method now also ***registers*** the object.
+  Previously the `store()` method would just set the ownedByRegistry flag
+  without ensuring that it was available for lookup.
+  Now ensure that it is indeed also registered first.
+
+- Support register/store of `tmp<T>` items.
+  The tmp parameter is not cleared, but changed from PTR to CREF
+  to allow further use.
+
+The implicit registration allows code simplification. Using the
+`GeometricField::New` factory method, for example:
+
+
+#### Old Code
+```
+volScalarField* ptr = new volScalarField
+(
+    IOobject
+    (
+        fieldName,
+        mesh.time().timeName(),
+        mesh,
+        IOobject::NO_READ,
+        IOobject::NO_WRITE,
+        true  // Register
+    ),
+    mesh,
+    dimless,
+    zeroGradientFvPatchField<scalar>::typeName
+);
+ptr->store();
+```
+
+#### New Code
+```
+auto tptr = volScalarField::New
+(
+    fieldName,
+    mesh,
+    dimless,
+    zeroGradientFvPatchField<scalar>::typeName
+);
+regIOobject::store(tptr);
+```
+_or even_
+```
+regIOobject::store
+(
+    volScalarField::New
+    (
+        fieldName,
+        mesh,
+        dimless,
+        zeroGradientFvPatchField<scalar>::typeName
+    )
+);
+```
+
+
+## List types
+
+- added IndirectSubList to provide indirect access to a sub-section of
+  a list. This is somewhat less efficient than a Foam::SubList, but
+  supports the following:
+  * adjustment of its addressing range after construction
+  * recovery of the original, underlying list at any time
+
+  This can be more convenient for some coding cases.
+  For example,
+  ```
+  template<class Addr>
+  void renumberFaces(IndirectListBase<face, Addr>& faces, ...);
+  ```
+  which can be called for
+  * Specific faces:<br>
+    `UIndirectList<face>(mesh.faces(), facesToChange)`
+  * A sub-range of faces:<br>
+    `IndirectSubList<face>(mesh.faces(), pp.range())`
+  * All faces:<br>
+    `IndirectSubList<face>(mesh.faces())`
+
+
+### Switch
+
+Alignment Switch methods more with Enum to include `find()`, `found()`
+static methods and constructors with failsafe option.
+
+The `find()` method makes for clearer coding:
+
+Old
+```
+Switch sw(some_string, true); // NB: true = allowBad
+if (sw.valid()) ...
+```
+Now
+```
+Switch sw = Switch::find(some_string);
+
+if (sw.good()) ...
+```
+or
+```
+if (Switch::found(some_string)) ...
+```
+
+Improve construct from dictionary to handle all valid token types.
+Previously just read in a word.
+
+
+### clockTime, clockValue
+
+- inline and extend clockValue, clockTime
+
+- mostly wraps std::chrono so can inline much of it, which is potentially
+  helpful when used for inner timings.
+
+- add elapsedTime() method for direct cast to double and for
+  naming similarity with wall-clock method.
+
+
+Potential breaking change (minor):
+
+- clockValue construct with a bool parameter is now simply tagged
+  dispatch (value is ignored) and always queries the current clock
+  value. This avoids needless branching.
+  Since this constructor form has primarily been used internally (eg,
+  clockTime), breakages in user code are not expected.
+
+
+### dimensionedType - additional dimensionedType constructors
+
+- construct from dimension/value, defaulting name from value, which
+  can be convenient for these type of operations:
+  ```
+  max(.., dimensionedScalar(somedims, 0.5))
+  ```
+
+- construct from dimension/one, forwarding to `pTraits<T>::one`,
+  which can be convenient for constructors:
+  ```
+  volScalarField(..., dimensionedScalar(somedims, one{}))
+  ```
+
+
+[code-patterns]: /coding/patterns/patterns
+[upgrade-guide]: /upgrade/upgrade
+
+[v2006-notes]: https://www.openfoam.com/releases/openfoam-v2006/