|
|
<!-- --- title: Developer Upgrade Guide (OpenFOAM-v1906) -->
|
|
|
|
|
|
[Back to Upgrade Guides](/guides/upgrade/upgrade)
|
|
|
|
|
|
## Deprecation and Removal
|
|
|
|
|
|
As part of code evolution, some methods become obsolete or are
|
|
|
superseded by new methods. To assist in code migration we have added
|
|
|
`FOAM_DEPRECATED` macros that are used in some places to emit
|
|
|
compile-time warnings and alert the use about the use of deprecated
|
|
|
methods. The user is advised to heed such warnings since this is good
|
|
|
indication that functionality has changed or that a method may be
|
|
|
slated for removal in a future version. In some rarer circumstances a
|
|
|
method may be explicitly tagged as `= delete` to prevent the compiler
|
|
|
from using the method at all.
|
|
|
|
|
|
### Deprecated Methods
|
|
|
|
|
|
- The linked-list iterator now has a `good()` method for testing its
|
|
|
validity and its rarely used `found()` method has been deprecated
|
|
|
since testing the validity is independent of searching *per se*.
|
|
|
|
|
|
- The `hashedWordList::contains()` method is now tagged as deprecated
|
|
|
(identical to the `found()` method). The `contains()` method is a
|
|
|
remnant from when hashedWordList was generalized from a speciesTable
|
|
|
(2010-10).
|
|
|
|
|
|
- The `Foam::findIndex()` global function is tagged as deprecated. This
|
|
|
functionality has been superseded by `find()` or `found()` methods
|
|
|
on the list containers themselves.
|
|
|
|
|
|
- The face/triangle `normal()` methods are tagged as deprecated.
|
|
|
|
|
|
In v1812, the distinction between areaNormal and unitNormal
|
|
|
was propagated through out the code, but some user code may well
|
|
|
remain that uses the `normal()` method. By providing a compile-time
|
|
|
deprecation message, the user is alerted to possible ambiguities or
|
|
|
optimization potential. In older versions, the `normal()` always meant
|
|
|
the area-normal for certain of these primitives and an additional
|
|
|
division by its magnitude would be required to obtain the unit-normal.
|
|
|
Now it is possible to distinguish between both meanings and use
|
|
|
area-normal or unit-normal as appropriate.
|
|
|
|
|
|
|
|
|
### Removed Methods
|
|
|
|
|
|
- removed deprecated `bitSet::used()` method
|
|
|
|
|
|
The `used()` method was for transitional compatibility with the now
|
|
|
defunct PackedBoolList.
|
|
|
|
|
|
The canonical method name for returning a labelList of *on* bits is
|
|
|
`toc()` or identically `sortedToc()`.
|
|
|
|
|
|
- remove the unused and deprecated `emptyList()` casting function.
|
|
|
This function is disllowed by many modern compilers and is no longer
|
|
|
used within OpenFOAM - was deprecated 2018-07.
|
|
|
|
|
|
|
|
|
### Removed Items
|
|
|
|
|
|
- The reader library and configuration files for EnSight have been removed
|
|
|
since the reading of OpenFOAM files has been been supported directly
|
|
|
from within EnSight for several versions already.
|
|
|
|
|
|
- very old legacy tools (including pre-git packaging tools) have been
|
|
|
removed. Also remove very old deprecated scripts
|
|
|
(eg, `foamDebugSwitches`, `foamGraph*`).
|
|
|
|
|
|
- deprecation scripts, such as those suggesting the use of
|
|
|
`postProcess`, have been removed and the information transferred to
|
|
|
wiki content. This reduces installation clutter and enables easier
|
|
|
cross-referencing.
|
|
|
|
|
|
|
|
|
## Changes in definition
|
|
|
|
|
|
- Previously `mag()` returned a `scalar`, but now it returns the
|
|
|
`magType` of the underlying arithmetic primitive (or respective
|
|
|
pTraits). This change means, for example, that the magnitude of a
|
|
|
`doubleVector` remains `double`, even when using single-precision for
|
|
|
the definition of `scalar`.
|
|
|
Adjusted return values of `sumSqr()` accordingly.
|
|
|
|
|
|
- Historically had complex::one defined as `1+1i`. This has been
|
|
|
removed and replaced with `pTraits<complex>::one`, which is
|
|
|
defined as `1+0i` for more consistency with the concept of one to
|
|
|
have a real component only.
|
|
|
|
|
|
- Removed the `!` operator for complex conjugate in favour of using
|
|
|
the member function directly or the `~` operator.
|
|
|
|
|
|
- `PtrList::set(label)` now returns a const pointer instead of a bool.
|
|
|
This can still be tested as a bool, but also adds the ability
|
|
|
to *peek* at the contents.
|
|
|
|
|
|
|
|
|
## Changes in behaviour
|
|
|
|
|
|
### wordRes
|
|
|
|
|
|
The `wordRes::uniq()` method previously just removed duplicate
|
|
|
literals, but now removes all duplicates. Now uses a linear search
|
|
|
internally instead of the previous wordHashSet implementation, since
|
|
|
lists are normally fairly small and mostly just have unique entries
|
|
|
anyhow. This reduces the overall overhead.
|
|
|
|
|
|
|
|
|
## Namespace changes
|
|
|
|
|
|
- Now have `vtk::Tools` as a namespace instead of a class, which
|
|
|
allows localized extension of functionality.
|
|
|
|
|
|
|
|
|
## HashTable and HashSet
|
|
|
|
|
|
It seems that barely a release goes by without some adjustments to
|
|
|
HashTable or HashSet. This release is no exception.
|
|
|
|
|
|
HashTable now supports move insert/set and emplace insertion for
|
|
|
improved memory efficiency and to support hash tables of non-copyable
|
|
|
objects (eg, std::unique_ptr).
|
|
|
|
|
|
The reorganization of HashTable internals as further improved
|
|
|
functionality and cleaner future code maintenance. The
|
|
|
HashTable/HashSet *payloads* (a pair of values for HashTable, or a
|
|
|
single value for HashSet) now have their own output capabilities.
|
|
|
This reduces code clutter and adds intrinsic output handling of
|
|
|
pointers and pointer-like objects (eg, `autoPtr`, `std::unique_ptr`),
|
|
|
which means that the following type of code should simply work
|
|
|
without any additional intervention:
|
|
|
```
|
|
|
HashTable<T*> tbl;
|
|
|
os << tbl;
|
|
|
```
|
|
|
|
|
|
The HashTable iterators have been moderately revamped:
|
|
|
- a `good()` method as a synonym for `found()` to test validity.
|
|
|
|
|
|
- a `val()` method for symmetry with the `key()` method, and for less
|
|
|
typing than the older `object()` method.
|
|
|
|
|
|
- now also aware of pointer-content payload and can be dereferenced
|
|
|
directly. For example:
|
|
|
```
|
|
|
HashTable<regIOobject*> tbl = ...;
|
|
|
|
|
|
const auto iter = tbl.cfind("something");
|
|
|
|
|
|
if (iter.good())
|
|
|
{
|
|
|
iter->write();
|
|
|
}
|
|
|
```
|
|
|
|
|
|
|
|
|
- Added `HashSet::test()` for method name compatibility with `bitSet`
|
|
|
and `boolList`
|
|
|
|
|
|
|
|
|
## Safer use of NullObject
|
|
|
|
|
|
- The size of the nullObject singleton has been increased from to 8
|
|
|
bytes to 32 bytes of zeros to ensure that most reinterpret casting
|
|
|
will not result in objects that reference arbitrary memory.
|
|
|
|
|
|
In previous versions, the following code would result in unsafe
|
|
|
behaviour:
|
|
|
```
|
|
|
const labelList& myList = labelList::null();
|
|
|
|
|
|
Info<< myList.size() << nl; // OK since size is the first parameter
|
|
|
|
|
|
SubList<label>(myList, 0); // Unsafe
|
|
|
```
|
|
|
|
|
|
The SubList usage could become unsafe since the pointer from the
|
|
|
labelList::null() would be whatever happened to be in memory
|
|
|
immediately after the NullObject singleton.
|
|
|
|
|
|
Expanding the size of the singleton avoids many of these possible
|
|
|
issues. We can now safely use labelList::null() instead of
|
|
|
emptyLabelList for return values. No special treatment required for
|
|
|
lists.
|
|
|
|
|
|
Possible replacements:
|
|
|
```
|
|
|
if (notNull(list) && list.size()) -> if (list.size())
|
|
|
if (isNull(list) || list.empty()) -> if (list.empty())
|
|
|
```
|
|
|
The receiver may still wish to handle differently to distinguish
|
|
|
between a null list and an empty list, but no additional special
|
|
|
protection is required when obtaining sizes, traversing, outputting
|
|
|
etc.
|
|
|
|
|
|
|
|
|
## Improvements in complex
|
|
|
|
|
|
- additional construct/assignment methods for complex.
|
|
|
Including add construction from and conversion to std::complex,
|
|
|
which allows easier wrapping of functions.
|
|
|
|
|
|
- add `Foam::sin()`, `Foam::cos()`, ... functions for complex
|
|
|
|
|
|
|
|
|
## Adjustment for VectorSpace
|
|
|
|
|
|
- iterators have been added to VectorSpace, which adds support for
|
|
|
various STL operations:
|
|
|
* sorting, filling, find min/max element etc.
|
|
|
* for-range iteration
|
|
|
|
|
|
|
|
|
## Improvements for input checks
|
|
|
|
|
|
### Dictionary
|
|
|
|
|
|
To support the continuing drive for tighter input error checking,
|
|
|
additional dictionary checking methods have been added that support
|
|
|
acceptance checks (predicates) on the input values. These can be used
|
|
|
to verify the validity of input values. For example,
|
|
|
```
|
|
|
dict.getCheck<label>("nIters", greaterOp1<label>(0));
|
|
|
dict.getCheck<scalar>("relax", scalarMinMax::zero_one());
|
|
|
```
|
|
|
|
|
|
The dictionary `writeOptionalEntries` configuration flag is now an
|
|
|
integer instead of a bool, to allow triggering of Fatal if default
|
|
|
values are used. This can be used local for particularly stringent
|
|
|
checking.
|
|
|
|
|
|
|
|
|
### dimensionedType
|
|
|
|
|
|
Additional read guards and constructors have been added to
|
|
|
`dimensionedType` to improve error detection and to simplify the
|
|
|
calling sequences. Similarly, there are additional read, readIfPresent
|
|
|
methods with alternative lookup names.
|
|
|
|
|
|
For example,
|
|
|
- before
|
|
|
```
|
|
|
dimensionedScalar rhoMax
|
|
|
(
|
|
|
dimensionedScalar::lookupOrDefault
|
|
|
(
|
|
|
"rhoMax",
|
|
|
pimple.dict(),
|
|
|
dimDensity,
|
|
|
GREAT
|
|
|
)
|
|
|
);
|
|
|
```
|
|
|
- after
|
|
|
```
|
|
|
dimensionedScalar rhoMax("rhoMax", dimDensity, GREAT, pimple.dict());
|
|
|
```
|
|
|
|
|
|
- The Istream related constructors are now marked with compile-time
|
|
|
deprecated warnings since these bypass possible read guards.
|
|
|
|
|
|
|
|
|
## Function Objects
|
|
|
|
|
|
- Inserted a new `timeFunctionObject` virtual class in the inheritance
|
|
|
hierarchy. This is simply a `functionObject` with an additional
|
|
|
`Time` reference, which is a combination frequently used by concrete
|
|
|
functionObjects.
|
|
|
|
|
|
- Remove objects handling is now included in `timeFunctionObject`
|
|
|
and `regionFunctionObject` to make it easier to implement
|
|
|
functionObject or field object removal.
|
|
|
|
|
|
|
|
|
## Changes in Lists
|
|
|
|
|
|
### Output - List
|
|
|
|
|
|
The line-breaks for `UList` output is now compile-time configurable
|
|
|
via ListPolicy details. The switch between a short list (space separated)
|
|
|
and a long list (newline separated) is now more configurable.
|
|
|
|
|
|
For commonly used types that often have short content (eg, word, wordRes,
|
|
|
keyType), the line breaks are suppressed. Previously this would only
|
|
|
have been the case for data types with contiguous content.
|
|
|
|
|
|
|
|
|
### Output - FixedList
|
|
|
|
|
|
Remove uniform compact output for FixedList. A FixedList is generally
|
|
|
small so there is little advantage in a compact output form for
|
|
|
uniform content. For example, `2{-1}` versus `(-1 -1)`. By avoiding
|
|
|
this compact form we obtain output that is also consistent with
|
|
|
Tuple2, for example.
|
|
|
|
|
|
|
|
|
### ListOps
|
|
|
|
|
|
Add ListOps find/found accepting a unary predicate, which increases its
|
|
|
variety of use. For example,
|
|
|
```
|
|
|
if (ListOps::found(list, matcher))
|
|
|
{
|
|
|
...
|
|
|
}
|
|
|
```
|
|
|
Instead of a more resource-intensive, and more opaque alternative:
|
|
|
```
|
|
|
if (!findStrings(matcher, list).empty())
|
|
|
{
|
|
|
...
|
|
|
}
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PtrList, PtrListOps
|
|
|
|
|
|
|
|
|
- PtrDynList support for move append list, which can be used
|
|
|
to concatenate pointer lists into a single one
|
|
|
|
|
|
- Construction of PtrList from a List of pointers, taking ownership.
|
|
|
This can be useful when upgrading code. For example,
|
|
|
```
|
|
|
List<polyPatch*> oldList = ...;
|
|
|
PtrList<polyPatch> newList(oldList);
|
|
|
...
|
|
|
```
|
|
|
|
|
|
- PtrList now has a release() method, for similarity to autoPtr and
|
|
|
unique_ptr and clearer in purpose than using `set(i,nullptr)`.
|
|
|
|
|
|
|
|
|
- support squeezing out (removing) null pointers from a UPtrList, to
|
|
|
remove gaps and compact lists.
|
|
|
|
|
|
- support sorting operations for pointer lists (PtrListOps)
|
|
|
|
|
|
|
|
|
### Indirect Lists
|
|
|
|
|
|
|
|
|
Indirect lists have been generalized to support different addressing
|
|
|
types.
|
|
|
|
|
|
- The new SliceList type can be used for stride-based
|
|
|
addressing into existing lists.
|
|
|
|
|
|
- The new SortList type can use used in some places as a lightweight alternative
|
|
|
to SortableList to have the convenience of bundling data and sort
|
|
|
indices together, but while operating on existing data lists.
|
|
|
In other situations, it can be useful as an alternative to
|
|
|
`Foam::sortedOrder`. For example,
|
|
|
|
|
|
```
|
|
|
pointField points = ...;
|
|
|
|
|
|
labelList order;
|
|
|
sortedOrder(points, order);
|
|
|
|
|
|
forAll(order, i)
|
|
|
{
|
|
|
points[order[i]] = ...;
|
|
|
}
|
|
|
```
|
|
|
Can be replaced with the following (with the same memory overhead)
|
|
|
```
|
|
|
pointField points = ...;
|
|
|
|
|
|
SortList<point> sortedPoints(points);
|
|
|
|
|
|
for (point& pt : sortedPoints)
|
|
|
{
|
|
|
pt = ...;
|
|
|
}
|
|
|
```
|
|
|
|
|
|
|
|
|
## Ranges
|
|
|
|
|
|
|
|
|
### labelRange
|
|
|
|
|
|
Can now use `+=` and `-=` operators for resizing a labelRange.
|
|
|
Can construct a labelRange from a MinMax range.
|
|
|
|
|
|
|
|
|
### scalarRange
|
|
|
|
|
|
The scalarRange received additional static methods (`ge0`, `gt0`,
|
|
|
`zero_one`, ...), which makes it more convenient to use as a predicate
|
|
|
when checking input values.
|
|
|
|
|
|
|
|
|
### sliceRange
|
|
|
|
|
|
The new `sliceRange` class is similar to `labelRange`, but with a stride.
|
|
|
It can be used to define slices (of lists, fields, ..) or as a range specifier
|
|
|
for a for-loop. For example,
|
|
|
```
|
|
|
for (label i : sliceRange(0, 10, 3))
|
|
|
{
|
|
|
...
|
|
|
}
|
|
|
```
|
|
|
|
|
|
|
|
|
### MinMax
|
|
|
|
|
|
The new `MinMax` container provides the framework for handling value
|
|
|
ranges. The corresponding `minMax()`, `gMinMax()`, etc functions can
|
|
|
be used to conveniently extract min/max values and handle parallel
|
|
|
reductions. Since the minMax evaluates during its operation, this
|
|
|
makes it more efficient for cases where both min/max values are
|
|
|
required since it avoids looping twice through the data.
|
|
|
|
|
|
- Implemented for lists, fields, field-fields, DimensionedField,
|
|
|
GeometricField (parallel reducing, with boundaries).
|
|
|
|
|
|
The `MinMax` container can also function as range predicate for input
|
|
|
checking.
|
|
|
|
|
|
|
|
|
Associated with `MinMax` is the `clip()` field function, which
|
|
|
provides a more efficient, single-pass operation to apply lower/upper
|
|
|
limits on single or multiple values. Examples,
|
|
|
|
|
|
1.
|
|
|
```
|
|
|
scalarMinMax limiter(0, 1);
|
|
|
limiter.clip(value)
|
|
|
```
|
|
|
This returns a const-ref to the value if within the range, or else
|
|
|
returns the appropriate lower/upper limit
|
|
|
|
|
|
2.
|
|
|
```
|
|
|
limiter.inplaceClip(value);
|
|
|
```
|
|
|
Modifies the value if necessary to be within lower/upper limit
|
|
|
|
|
|
Function calls,
|
|
|
|
|
|
1.
|
|
|
```
|
|
|
clip(value, limiter)
|
|
|
```
|
|
|
returns a copy after applying lower/upper limit
|
|
|
|
|
|
2.
|
|
|
```
|
|
|
clip(values, limiter)
|
|
|
```
|
|
|
returns a tmp<Field> of clipped values
|
|
|
|
|
|
|
|
|
|
|
|
## Pair, Tuple2 improvements
|
|
|
|
|
|
Now supports move constructors, construct from `std::pair` and
|
|
|
input/output of `std::pair` to make for easier interactions with
|
|
|
data structures used in other codes.
|
|
|
|
|
|
|
|
|
## Dense Matrices
|
|
|
|
|
|
This release has several improvements for dense matrices.
|
|
|
|
|
|
- iterators, begin/end, empty() methods for STL behaviour.
|
|
|
|
|
|
- access methods consistent with other OpenFOAM containers:
|
|
|
* data(), cdata(), uniform()
|
|
|
|
|
|
- construct/assign moveable
|
|
|
|
|
|
- Can recover matrix storage for re-use elsewhere.
|
|
|
For example, to populate values with 2D i-j addressing and later
|
|
|
release it as flat linear storage.
|
|
|
|
|
|
- additional inplace operations `+=`, `-=`, `*=`, `/=` to avoid
|
|
|
copying
|
|
|
|
|
|
- support both matrix/column-vector and row-vector/matrix
|
|
|
multiplication. Methods names consistent with lduMatrix:
|
|
|
```
|
|
|
Matrix::Amul -> A*x [matrix][col-vector]
|
|
|
Matrix::Tmul -> x*A [row-vector][matrix]
|
|
|
```
|
|
|
|
|
|
- support LLTMatrix, QRMatrix solve of indirect lists
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[v1906-notes]: https://www.openfoam.com/releases/openfoam-v1906/ |