OpenFOAM® Developer Upgrade Guide

OpenFOAM®  Developer Upgrade Guide

This guide is for developers looking for assistance in upgrading their OpenFOAM developments to more recent versions of OpenFOAM. Note: this is a live-document and will be continuously updated.

Changes for OpenFOAM v1706

API changes

Heat transfer

  • The thermodynamics library converted from a mole-to mass-basis, see commit abc50e21
  • Energy source term renamed from Sh to Qdot

Library restructuring

  • the edgeMesh library has been relocated to the meshTools library
  • the cachedRandom and Random classes have been consolidated into a single Random class, mainly using the API from the previous cachedRandom class

Core changes

Reworked low-level containers
Several lower-level containers and classes have been added or reworked for this version, with HashTable and HashSet receiving the largest visible changes. Many containers have been adjusted to allow use of C++11 range-based fors.
C++11 related
Containers now behave better with C++11 type-deduction, with the effect that it is now easier to iterate over many types of containers with a range-based for.
New code macros
forAllIters() and forAllConstIters() programming macros are the counterpart to forAllIter() and forAllConstIter(), but use C++11 type-deduction. This makes for easier coding, e.g.

Map<labelHashSet> lookup;

// Standard macro:
forAllConstIter(Map<labelHashSet>, lookup, iter)  .... 

// New macro, with type-deduction:
forAllConstIters(lookup, iter)  .... 

The C++11 range-based for now works with HashSet as expected:

labelHashSet hashed;
for (label item : hashed)  .... 

New and updated helper classes

Enum class
Provides functionality similar to NamedEnum, but handles arbitrary enumeration values and subsets of enumeration values.
The labelRange class has increased flexibility and better behaviour as an iterator. Among other things, it can now be used as an initializer for label or scalar lists. e.g.,

labelRange range(100, 1500);  // ie, values from 100 to 1599
scalarList list(range.begin(), range.end());


It is now possible to easily access a slice of any list using a pair of labels. For example, to set 10 values to 100, starting at position 5:

list[5,10] = 100
Flat output
It is now possible to specify the length when list output in ASCII is broken with line breaks. This is typically useful when displaying choices for the user. The flatOutput wrapper suppresses all line breaks. For example,

Info<<"hashed: " << flatOutput(myHashSet) << endl;
  • The reorder and inplaceReorder functions now have an additional prune option to allow simultaneously reordering and truncation of lists.
  • The subsetList and inplaceSubsetList functions can now be used with predicates, including lambda functions.
  • A new inplaceUniqueSort function for sorting and removal of duplicates in lists.


Improved flexibility
These classes have been extensively modified to improve their flexibility with many new filtering methods and additional iterator methods: filterKeys, filterValues, filterEntries, retain, lookup, countKeys etc.. The filters can accept any predicate, including C++11 lambda functions.
The HashSet iterators now return the hashed key instead of the nil value.
Accessing a non-existent entry now returns -1 instead of failing.

String and regex matching

All classes derived from a string or that can match a string now have a unary predicate operator for string comparison or matching. This makes it easier to write generic matching and filtering code.

Changes for OpenFOAM v1612+

Geometric field access

The following examples show manipulation of scalar fields; similar constructs are used for other primitive types, i.e. vector, sphericalTensor, symmTensor and tensor classes.

Internal field


const scalarField& isf = field.internalField();
scalarField& isf = field.internalField();

const scalarField& isf = field.primitiveField();
scalarField& isf = field.primitiveFieldRef();

Dimensioned internal field


const volScalarField::DimensionedInternalField& dsf = field.dimensionedInternalField();
volScalarField::DimensionedInternalField& dsf = field.dimensionedInternalField();

const volScalarField::Internal& dsf = field()();
const volScalarField::Internal& dsf = field.internalField();
volScalarField::Internal& dsf = field.ref();

Boundary field


const volScalarField::GeometricBoundaryField& bsf = field.boundaryField();
volScalarField::GeometricBoundaryField& bsf = field.boundaryField();

const volScalarField::Boundary& bsf = field.boundaryField();
volScalarField::Boundary& bsf = field.boundaryFieldRef();

Patch field


fvPatchScalarField& psf = ...
const volScalarField::DimensionedInternalField& dsf = psf.dimensionedInternalField();

const scalarField& psif = psf.internalField();

fvPatchScalarField& psf = ...
const volScalarField::Internal& dsf = psf.internalField();

const scalarField& psif = psf.primitiveField();

Temporary fields


tmp<volScalarField> tField = ...
volScalarField& non_const_field = tField();
const volScalarField& const_field = tField();

tmp<volScalarField> tField = ...
volScalarField& non_const_field = tField().ref();
const volScalarField& const_field = tField();

Function objects
functionObjectState -> stateFunctionObject