Skip to content

Changes

Page history
STYLE: relocate /guides/upgrade as /upgrade authored by Mark OLESEN's avatar Mark OLESEN 
- leave /guides/upgrade as symlink
Show whitespace changes
Inline Side-by-side
upgrade/v1912-Developer-Upgrade-Guide.md 0 → 100644
View page @ f7fda162
<!-- --- title: Developer Upgrade Guide (OpenFOAM-v1912) -->
[![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_]]
## Deprecation and Removal
### Deprecated Methods
- Silently deprecate string methods `startsWith()`, `endsWith()` (added
2016) in favour of `starts_with()`, `ends_with()` names. This aligns
with C++20 already and allows these implementations to be removed
in a few years.
- Silently deprecate string method `removeTrailing()` in favour of the
single character variant of `removeEnd()` to reduce the number of
method names.
### Removed Methods
- Removed the const versions of the string methods `removeRepeated()`
and `removeTrailing()`, which were never used but could be the
source of confusion with the modifying versions of the same names.
- Removed `token` assignment from a raw word or string pointer.
This was deprecated 2017-11 and now removed.
For this type of content transfer, move assignment should be used
instead of stealing pointers.
- Removed pointer-style `->` dereferencing for HashTable iterators.
This syntax was added 2019-04, but consistent addressing with
support for wrapped pointer types (eg, autoPtr, std::unique_ptr) has
proven to be less robust than desired.
- Remove deprecated HashTable iterator `object()` method.
Was only used internally and was superseded by the `val()` method
in an earlier version.
### Removed Items
- The pre-C++11 `Xfer` has now been removed.
It was deprecated and slated for removal 2018-03.
- Removed the particle PropertyTypes (introduced in 2016 for adios).
Proved to be difficult to use, manage and maintain.
## Changes in definition
### Contiguous
- Replaced previous use of `contiguous<T>()` as a global function with
`is_contiguous<T>` as a traits class. For some advanced user code,
this can be a breaking change, but greatly improves the ability to
define general traits and to inherit from them.
Previously something like the following was required:
```
template<>
bool contiguous<FixedList<bool, 2>>() { return true; }
template<>
bool contiguous<FixedList<int_8, 2>>() { return true; }
...
```
This repetitious and error-prone definition is now replaced with a
more direct and succinct form:
```
template<class T, unsigned N>
struct is_contiguous<FixedList<T, N>> : struct is_contiguous<T> {};
```
An future benefit of the new structure is that it provides a static
constexpr `value`, which allows its use in template expressions.
The change in definition is accompanied by a slight name change from
`contiguous` to `is_contiguous`, which should assist in identifying
upgraded code.
When defining the contiguous characteristics, the `is_contiguous_label`
and the `is_contiguous_scalar` forms may also be relevant.
These are special traits for handling data of homogeneous components
of the respective types.
### keyType
- The keyType type (literal/regex) is now handled as an enum instead
of bool, which makes its somewhat clearer, allows more future
options and provides better alignment with the wordRe class.
## Changes in behaviour
### All classes
The default behaviour is to treat self-assignment as a no-op instead
of a `FatalError`. In a small minor cases self-assignment _could_
indicate a programming error, but in other cases it may be entirely
correct. The `std::min()` function, for example, returns a const
reference, and the following code should behave correctly:
```
a = std::min(a, b);
```
### Dictionary
- support search options on more dictionary methods. For example,
to specify literal matches for sub-dictionary methods:
```
isDict(key, keyType::REGEX)
optionalSubDict(key, keyType::REGEX)
subDict(key, keyType::REGEX)
subOrEmptyDict(key, keyType::REGEX, mandatory)
```
- The addition of an optional match type (LITERAL vs REGEX) for
dictionary::subOrEmptyDict() represents a *minor* breaking change.
Within OpenFOAM itself, this only affected a single line of code.
- old: `subOrEmptyDict(key, bool=false)`
- new: `subOrEmptyDict(key, keyType::option=keyType::REGEX, bool=false)`
### HashTable
- previously allowed mapped value modification with a const iterator.
However, this can lead to incorrect access patterns.
Now tie the constness of the mapped value to that of the iterator.
- `set` instead of `insert` a `std::initializer_list` into HashTable.
This handles duplicate entries by overwriting, which corresponds more
closely to the notion of assignment.
### Random
- The constructor for Random is now explicit to prevent automatic
construction from a `label`.
## General
- The newly added `FatalErrorInLookup`, `FatalIOErrorInLookup`
macros should be used in code `New()` selectors using a lookup.
See [code patterns][code-patterns].
- The new `InfoErr` stream behaves like `Info` but with output to
stderr instead of stdout.
### argList handling
When retrieving argList options, can now use `get<..>()` instead of
`opt<...>()` or the very old `optionRead`. This improves similarity
with dictionary methods - making it easy to transfer code - and helps
reduce the number of different method names.
### Stream reading
- The `getLine()` method now allows an alternative delimiter with the
default be a newline. This makes reading files easier in some
situations.
## Operators
- additional xorOp, bitXorOp, xorEqOp, bitXorEqOp reduction operators
and flipBoolOp for negation.
- scalarOps with divide-by-zero protection.
Functor versions of floor/ceil/round for scalar.
- added cmptMagSqr for scalars, VectorSpace, Fields. This operation
can be useful when constructing matrix norms.
- min/max compare/reduction operators for Tuple2 first() that
only compare the first element. This can be useful when building a
temporary aggregate for reduction.
- improve syncTools handling of bitSet/PackedList types with
additional support for face sync/swap of boundary values. This
allows use of bitSet instead of boolList in more places
- The `Foam::name()` can now also be used with a pointer to return the
memory address formatted in hexadecimal. This is useful for
obtaining detailed object information.
## tmp, tmpNrc
- The `tmp` and `tmpNrc` classes now support `reset()`, move
assignment and allow explicit test as bool (same as valid). This not
only improves similarity to autoPtr, but can also simplify coding.
For example,
```
tmp<volScalarField> tfield;
// sometime later...
tfield.reset
(
volScalarField::New("myfield", mesh, dimensionedScalar(Zero))
);
```
## Random generators
New generator classes for uniform/gaussian random numbers, which can be
used in combination with std::generate, or as a substitute unary
operator to supply random numbers for std::transform.
## Enum
- The `Enum` class now has additional methods to make it more dynamic.
The class was originally only used for constant data, but by adding
some elementary methods (empty, clear, append) it is now possible to
use in more situations where a tiny Map/HashTable replacement is
desirable. The new methods can be combined with null-constructed to
have a simple low-weight cache of word/int lookups.
The std::ostream output can be used before other parts of the
OpenFOAM streams have been created.
## HashTable and HashSet
- HashTable values are now read in-situ to avoid copying.
- HashTable uses emplace when generating zero-initialized values for
its `operator()`
- HashSet (backed by HashTable) use emplace to avoid unneeded argument.
- global min(), max(), minMax() functions taking a labelHashSet and an
optional limit. For example,
```
labelHashSet set = ...;
Info<< "min is " << min(set) << nl;
Info<< "max (non-negative) " << max(set, 0) << nl;
```
## Matrix Methods
- longer method names for accessing Matrix number of rows/cols.
The names `mRows()`/`nRows()` and `nCols()` are less ambiguous than
`m()` and `n()`, which have been know to have swapped naming
conventions.
## Lists
- For SubList and SubField, support assign from zero.
- Support SubField +=, -=, *=, /= operators.
- Support construct SubList from UList (as per SubField)
## Adjustment for VectorSpace
- add data/cdata to VectorSpace for consistency with FixedList etc
- additional col/row access methods for Tensor, Tensor2D
- additional diagonal access methods for Tensor
- support transposed construction of Tensor from a set of vectors
## Fields
- Improved boolList functions for negate() and component() that make
it behave more like the other field types. It also now has a
boolIOField version that allows boolFields to be registered.
- Add field operations for complex
- `zip`, `unzip`. This release has an extensive additional
functionality for handling combining scalar fields into vector or
tensor fields (a `zip` operation) and for extracting scalar fields
from vector or tensor fields (an `unzip` operation). The fields may
be plain fields, complex fields or GeometricFields. The _unzip_
functions have `unzipCol`, `unzipRow` and `unzipDiag` variants.
- The new `FieldOps` namespace contains a variety of methods to
assign field values with _unary_ or _binary_ functions, as well
as different forms for handling _ternary_ conditionals with fields.
- A general findMinData/findMaxData algorithm in FieldOps namespace.
## Lagrangian
- The new top-level `cloud::nParcels()` method permits quick determination
of cloud sizes, even when retrieved from an registry as a simple `cloud`.
```
cloud* cldPtr = mesh.cfindObject<cloud>("myCloud");
label nParcels = (cldPtr ? cldPtr->nParcels() : 0);
```
- The new `cloud::readObjects(const objectRegistry&)` method can be
used to populate clouds with cloud data that has been provided by a
non-file transport.
----
[expressions]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Expressions.md
[code-patterns]: /coding/patterns/patterns
[upgrade-guide]: /upgrade/upgrade
[v1912-notes]: https://www.openfoam.com/releases/openfoam-v1912/