|
|
<!-- --- title: User 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_]]
|
|
|
|
|
|
## Configuration / Environment
|
|
|
|
|
|
### Cleaner bashrc/cshrc
|
|
|
|
|
|
The bashrc/cshrc files have been modestly restructured to improve
|
|
|
readability and reduce the potential for inadvertent edits of the
|
|
|
wrong entries. Nonetheless, we _highly encourage_ the use of `prefs.sh`
|
|
|
and `prefs.csh` files for making persistent configuration changes
|
|
|
instead of editing the bashrc/cshrc files. More items have been tagged
|
|
|
as _advanced_ / _legacy_ and moved further out of reach.
|
|
|
|
|
|
### Change in default development version naming
|
|
|
|
|
|
The default _development_ version was previously designated `plus`.
|
|
|
This has now changed to `com` as part of the
|
|
|
[repository migration](/Repository-migration).
|
|
|
This informal naming convention is now also noted in the bashrc file:
|
|
|
```
|
|
|
# [WM_PROJECT_VERSION] - A human-readable version name
|
|
|
# A development version is often named 'com' - as in www.openfoam.com
|
|
|
export WM_PROJECT_VERSION=com
|
|
|
```
|
|
|
This change affects the following directory locations:
|
|
|
- `$WM_PROJECT_USER_DIR`
|
|
|
- `$FOAM_RUN`
|
|
|
- `$FOAM_USER_APPBIN`, `$FOAM_USER_LIBBIN`
|
|
|
|
|
|
If you have been using the `run` _alias_ in the development version,
|
|
|
the location will also have changed accordingly.
|
|
|
|
|
|
|
|
|
### Relaxed environment
|
|
|
|
|
|
For a cleaner environment and cleaner look, the `WM_COMPILER_TYPE` and
|
|
|
`WM_COMPILER_OPTION` are now allowed to be unset or empty.
|
|
|
|
|
|
- An unset `WM_COMPILER_TYPE` is treated as equivalent to a **system**
|
|
|
compiler.
|
|
|
- An unset `WM_COMPILER_OPTION` is treated _internally_ (in
|
|
|
the make rules) as "Opt" (optimised).
|
|
|
If used with unset values, it will build as if "Opt" had been
|
|
|
specified (eg, `-O2`) but the target directories names will
|
|
|
shorter (eg, `linux64GccDPInt32`).
|
|
|
|
|
|
|
|
|
### Easier processor-specific handling
|
|
|
|
|
|
It is now easier to deal with different processor-specific builds with
|
|
|
fewer file modifications.
|
|
|
For example, to create Broadwell-specific options:
|
|
|
```
|
|
|
$ cd wmake/rules/linux64Gcc
|
|
|
$ cp c++Opt c++OptBdw
|
|
|
```
|
|
|
edit this file and then use WM_COMPILE_OPTION=OptBdw in the `prefs.sh`
|
|
|
before re-sourcing the OpenFOAM environment.
|
|
|
|
|
|
Since OpenFOAM is purely C++ code, there is no need to apply special
|
|
|
processor-specific optimizations for C code (the regular `-O2`
|
|
|
optimization is fine) since these components only appear as part of the
|
|
|
wmake build toolchain itself.
|
|
|
|
|
|
See [compiler versions][compiler-versions] for information on
|
|
|
approaches to dealing with different versions of a compiler family.
|
|
|
|
|
|
|
|
|
### More information about settings
|
|
|
|
|
|
The `wmake` options to display the compiler settings have been
|
|
|
extended to include `-show-path-cxx` and `-version`.
|
|
|
|
|
|
When working with external tools, simply knowing the compiler family
|
|
|
(eg, `wmake -show-cxx`) may be insufficient. In some cases, the
|
|
|
fully-qualified path is necessary.
|
|
|
```
|
|
|
$ wmake -show-path-cxx
|
|
|
/usr/bin/clang++-9
|
|
|
```
|
|
|
This can also be useful when verifying that the correct compiler is
|
|
|
indeed configured. Note that the usage for many of these options is
|
|
|
only displayed with the `wmake -help-full` option.
|
|
|
|
|
|
The `-version` option (or `--version`) is identical to `-show-api`,
|
|
|
but with naming consistent with other system tools.
|
|
|
```
|
|
|
$ wmake -version
|
|
|
1912
|
|
|
```
|
|
|
|
|
|
When using the top-level OpenFOAM `Allwmake` build, the paths of the
|
|
|
standard build tools (such as flex, m4, make etc) are now reported.
|
|
|
This is helpful when diagnosing when things have gone wrong
|
|
|
(eg, a tool has been found from the wrong location).
|
|
|
|
|
|
|
|
|
### Tracking pre-packed sources
|
|
|
|
|
|
If you are working from pre-packed sources (eg, from a [sourceforge
|
|
|
tar-file][sourceforge]), more information is retained to help you
|
|
|
determine which source code version you are using.
|
|
|
|
|
|
- `META-INFO/api-info` (since v1812) contains information about the
|
|
|
API level (eg, 1912 - the release version) and the patch level for
|
|
|
the last bugfix.
|
|
|
|
|
|
- `META-INFO/build-info` (also since v1812) is now also shipped with a
|
|
|
snapshot of the information from the source code revision used to
|
|
|
build the tar-file. This convey the information during later later
|
|
|
re-compilation without git to improve tracking beyond simply
|
|
|
referring to the patch level. This information is tagged with an
|
|
|
underscore to distinguish from _real_ build information from git.
|
|
|
|
|
|
- `META-INFO/manifest.txt` should be included in the tar-file.
|
|
|
This generated file contains the SHA1 values of the packages files.
|
|
|
To quickly see which files have changed between OpenFOAM-v1912.tgz
|
|
|
and OpenFOAM-v1912_xyz.tgz, simply look at the differences in the
|
|
|
manifest files with `diff`, `kdiff3` or your favourite tool.
|
|
|
|
|
|
|
|
|
### ParaView with Mesa
|
|
|
|
|
|
If building runTimePostProcessing with VTK libraries from a ParaView
|
|
|
build, the `ParaView_MESA_DIR` environment variable can now be used to
|
|
|
direct which set of ParaView libraries are to be used, instead of the
|
|
|
normal ones found under ParaView_DIR that likely use hardware
|
|
|
rendering. This addition does not remove any of the burden of setting up
|
|
|
specialized library paths for the run-time use of the libraries, but
|
|
|
does ensure that they are properly selected during compilation.
|
|
|
|
|
|
|
|
|
## Input Dictionaries
|
|
|
|
|
|
### Variables
|
|
|
|
|
|
- Now accept `/` when reading variables without requiring a
|
|
|
surrounding `{}`
|
|
|
|
|
|
- Fixed some degenerate parsing cases when the first character is
|
|
|
already not a valid variable character. For example, `$"abc"` would
|
|
|
have previously parsed as a `$"` variable, even although a double
|
|
|
quote is not a valid variable character. Now emits a warning and
|
|
|
parses as a `$` token and a string token.
|
|
|
|
|
|
|
|
|
### Expressions
|
|
|
|
|
|
A major change for dictionary input is provided by the new `#eval`
|
|
|
directive, which is associated with the addition of
|
|
|
[_expressions_][expressions] in OpenFOAM-v1912. For many purposes this
|
|
|
can replace `#calc` with a significant gain in speed.
|
|
|
|
|
|
Despite the similarity in purpose, the `#eval` uses a completely
|
|
|
different approach than `#calc`. Whereas `#calc` uses external code
|
|
|
compilation to create code for evaluation, `#eval` uses builtin
|
|
|
parsing and evaluation for the purpose. This makes the evaluation
|
|
|
***much, much*** faster since it eliminates the system call for code
|
|
|
compilation. Even for a dictionary with only 10 evaluations, the
|
|
|
difference is significant: `16s` for `#calc` versus only `0.02s` for
|
|
|
`#eval`.
|
|
|
|
|
|
This capability will hopefully change the way you view dictionaries!
|
|
|
```
|
|
|
kgh 700;
|
|
|
split 0.4;
|
|
|
|
|
|
inlet1
|
|
|
{
|
|
|
type flowRateInletVelocity;
|
|
|
massFlowRate constant #eval{ $split * $kgh / 3600 };
|
|
|
}
|
|
|
|
|
|
inlet2
|
|
|
{
|
|
|
type flowRateInletVelocity;
|
|
|
massFlowRate constant #eval{ (1-$split) * $kgh / 3600 };
|
|
|
}
|
|
|
```
|
|
|
Of course, there are many more creative ways to use this capability:
|
|
|
```
|
|
|
base 700;
|
|
|
range 20;
|
|
|
// range #eval{ round($base * 0.0625) };
|
|
|
split 0.3; // Override default 50-50 split
|
|
|
seed 4576;
|
|
|
|
|
|
inlet1
|
|
|
{
|
|
|
type flowRateInletVelocity;
|
|
|
massFlowRate constant
|
|
|
#eval
|
|
|
#{
|
|
|
(${split:-0.5}) * ($base + $range*rand($seed)) / 3600
|
|
|
#};
|
|
|
}
|
|
|
|
|
|
// Randomize some more
|
|
|
seed #eval{1000*rand($seed)};
|
|
|
seed #eval{1000*rand($seed)};
|
|
|
seed #eval{1000*rand($seed)};
|
|
|
seed #eval{1000*rand($seed)};
|
|
|
seed #eval{1000*rand($seed)};
|
|
|
|
|
|
inlet2
|
|
|
{
|
|
|
type flowRateInletVelocity;
|
|
|
massFlowRate constant
|
|
|
#eval
|
|
|
#{
|
|
|
(1-${split:-0.5}) * ($base + $range*rand($seed)) / 3600
|
|
|
#};
|
|
|
}
|
|
|
|
|
|
#remove (seed);
|
|
|
```
|
|
|
Or even just to conveniently recalculate things:
|
|
|
```
|
|
|
angle 37.5;
|
|
|
angle #eval{ degToRad($angle) };
|
|
|
```
|
|
|
|
|
|
It is also possible to embed mathematical evaluation into regular string
|
|
|
expansions if that is what you need:
|
|
|
```
|
|
|
#include "<system>/sampling${{ round(${flowRate:-5} * 100) }}";
|
|
|
```
|
|
|
|
|
|
|
|
|
### String input
|
|
|
|
|
|
In places that expect _string_ input, it is now possible to use _word_
|
|
|
input instead when there are no separators or special characters.
|
|
|
For example, instead of
|
|
|
```
|
|
|
file "theInputFile.txt";
|
|
|
```
|
|
|
can now simply use as a _word_:
|
|
|
```
|
|
|
file theInputFile.txt;
|
|
|
```
|
|
|
|
|
|
This change helps further reduce _clutter_ in the dictionary `libs`
|
|
|
entries. In OpenFOAM-v1906 we already made this easier by
|
|
|
automatically handling the usual `lib` prefix and the `.so` suffix
|
|
|
(also making it less confusing when swapping files between Linux, OS-X
|
|
|
and MS-Windows). With the new string handling, any of the following
|
|
|
are possible:
|
|
|
- libs ("libsampling.so");
|
|
|
- libs ("libsampling");
|
|
|
- libs ("sampling");
|
|
|
- libs (sampling);
|
|
|
|
|
|
|
|
|
Another consequency of [_expressions_][expressions] is that string
|
|
|
expansions can now include mathematical evaluations. For example,
|
|
|
```
|
|
|
"repeat ${{5 * 7}} times or ${{ pow(3, 10) }}"
|
|
|
```
|
|
|
|
|
|
|
|
|
### Improved reporting for optional dictionary entries
|
|
|
|
|
|
Additional information about _default_ dictionary inputs can be useful
|
|
|
when diagnosing models and issues. This capability has been in
|
|
|
OpenFOAM for a several versions (it is attached to the
|
|
|
`writeOptionalEntries` InfoSwitch), but the format of the output was
|
|
|
less than useful.
|
|
|
The output is now directed to `stderr` (to allow clearer separation
|
|
|
from regular output) and is formatted with dictionary name, keyword
|
|
|
and the default value used. For example,
|
|
|
```
|
|
|
Dictionary: <case>/0/nut.boundaryField.wall Entry: Cmu Default: 0.09
|
|
|
Dictionary: <case>/0/nut.boundaryField.wall Entry: kappa Default: 0.41
|
|
|
Dictionary: <case>/0/nut.boundaryField.wall Entry: E Default: 9.8
|
|
|
```
|
|
|
|
|
|
Note that this option will create a significant amount of output and
|
|
|
will normally be used sparingly or in combination with a `-dry-run`
|
|
|
option to limit the output.
|
|
|
|
|
|
|
|
|
### blockMesh
|
|
|
|
|
|
Unknown to most people, the blockMesh `convertToMeters` keyword was
|
|
|
superseded by the more succinct `scale` keyword many years ago
|
|
|
(October 2008 to be precise). As part of our regular dictionary
|
|
|
maintenance tasks, we have now marked it as an obsolete but compatible
|
|
|
keyword. A warning message inform you that it is 108 months (9 years)
|
|
|
out of date - as a gentle hint to upgrade sometime soon - but it is
|
|
|
actually even older than that!
|
|
|
|
|
|
|
|
|
### writeControl - system/controlDict
|
|
|
|
|
|
The simulation `writeControl` can now be specified as `none` for
|
|
|
special cases when normal writing is to be completely disabled and
|
|
|
replaced with alternate means (eg, via a function object).
|
|
|
|
|
|
|
|
|
## Sampling
|
|
|
|
|
|
The changes to sampling are not as significant as they were for
|
|
|
OpenFOAM-v1906, but have nonetheless received some bugfixes and
|
|
|
updates.
|
|
|
|
|
|
- The distanceSurface sampler is more generous when pre-filtering cell
|
|
|
selections, which elminates gaps in the extracted surface.
|
|
|
|
|
|
- The isoSurface regularise/filtering now supports different types of
|
|
|
filtering options (previous it was simply a boolean). The older use
|
|
|
of a boolean continues to be supported.
|
|
|
|
|
|
- The distanceSurface sample and cutting plane can now also use the
|
|
|
isoSurfaceTopo algorithm. The new `isoAlgorithm` keyword controls
|
|
|
which algorithm is used.
|
|
|
|
|
|
- Efficiency improvements for isoSurfaceTopo erosion following the
|
|
|
adaptations in the openfoam.org code.
|
|
|
|
|
|
- Improve time-handling for collated ensight surface writer
|
|
|
|
|
|
- Allow invariant surfaces for sampling.
|
|
|
This is an **expert** feature (use with caution), for example when
|
|
|
sampling on a static patch while some motion occurs elsewhere but
|
|
|
that motion does not affect the sampled surface. Used in
|
|
|
combination with the ensight writer to reduce output file sizes.
|
|
|
|
|
|
- Robustness improvements for the Ensight surface reader, which is
|
|
|
used in the noise utility.
|
|
|
|
|
|
- Streamlines: add bidirectional tracking
|
|
|
|
|
|
- runTimePostProcessing - additional culling options
|
|
|
|
|
|
|
|
|
## Command-line options
|
|
|
|
|
|
|
|
|
### openfoam session
|
|
|
|
|
|
The `openfoam` session is a wrapper script:
|
|
|
```
|
|
|
Open an interactive bash session with an OpenFOAM environment,
|
|
|
or run an OpenFOAM application (with arguments) after first sourcing
|
|
|
the OpenFOAM etc/bashrc file from the project directory.
|
|
|
```
|
|
|
|
|
|
The idea is to provide an easy way for a user or sysadmin to have an
|
|
|
_on demand_ OpenFOAM environment without modifying central or user
|
|
|
bashrc files. The wrappers (which are hidden away under the
|
|
|
`bin/tools` directory) can be called directly with their path, but
|
|
|
usually they will be configured and installed in a central location.
|
|
|
Using the openSUSE rpms, we have the following files:
|
|
|
```
|
|
|
/usr/bin/openfoam -> openfoam-1912
|
|
|
/usr/bin/openfoam-1812
|
|
|
/usr/bin/openfoam-1906
|
|
|
/usr/bin/openfoam-1912
|
|
|
```
|
|
|
Starting _without_ an OpenFOAM environment. We call `openfoam`
|
|
|
```
|
|
|
$ openfoam
|
|
|
Using: OpenFOAM-com (patch=0) - visit www.openfoam.com
|
|
|
Arch: linux64GccDPInt32Opt (mpi=openmpi-system)
|
|
|
OpenFOAM shell session - use exit to quit
|
|
|
|
|
|
```
|
|
|
In this case the version (`com`) tells us that the developer seems to
|
|
|
be using a pre-release version for the documentation. However, the
|
|
|
session sets the prompt with the value of the OpenFOAM API in use:
|
|
|
```
|
|
|
OpenFOAM-1912:~/
|
|
|
user$ _
|
|
|
```
|
|
|
The format of the prompt also serves as a reminder that we may wish to
|
|
|
exit this interactive shell at some point.
|
|
|
|
|
|
We can also use the same session command to source the OpenFOAM
|
|
|
environment, run a single command and exit. For example, we wish to
|
|
|
use an OpenFOAM conversion utility:
|
|
|
```
|
|
|
$ openfoam surfaceTransformPoints -scale 0.001 input.obj output.obj
|
|
|
```
|
|
|
If different types of OpenFOAM installations are available, the command
|
|
|
could be used to call an OpenFOAM program from the other installation:
|
|
|
```
|
|
|
$ openfoam -dp -int64 snappyHexMesh
|
|
|
```
|
|
|
|
|
|
|
|
|
### Command-line loading of libraries
|
|
|
|
|
|
The `-lib` option is available to all OpenFOAM solvers and compiled
|
|
|
utilities (see the `-help-full` output for the respective
|
|
|
application). This option can be useful for preloading of libraries,
|
|
|
for utilities that do not use `system/controlDict`, or when additional
|
|
|
library is needed but it is too annoying to edit `system/controlDict`
|
|
|
just for that.
|
|
|
|
|
|
The `-lib` option can be repeated to define multiple libraries:
|
|
|
```
|
|
|
-lib lib1 -lib lib2 -lib lib3
|
|
|
```
|
|
|
It can also use as a *captured* list with OpenFOAM's standard argument
|
|
|
list handling:
|
|
|
```
|
|
|
-lib '(' lib1 lib2 lib3 ')'
|
|
|
-lib \( lib1 lib2 lib3 \)
|
|
|
```
|
|
|
Or as single argument list with implicit List splitting:
|
|
|
```
|
|
|
-lib '(lib1 lib2 lib3)'
|
|
|
```
|
|
|
|
|
|
|
|
|
### Command-line setting debug/info
|
|
|
|
|
|
The `-debug-switch`, `-info-switch`, `-opt-switch` options are
|
|
|
available to all OpenFOAM solvers and compiled utilities (see the
|
|
|
`-help-full` output for the respective application). They can
|
|
|
be repeated multiple times on the command-line.
|
|
|
|
|
|
These new command-line options provide quick access to *most* of
|
|
|
OpenFOAM's switches, without the burden of editing the global
|
|
|
`etc/controlDict` or adding case-local entries to the
|
|
|
`system/controlDict`. If mixing command-line switches and case-local
|
|
|
entries, note that since the command-line switches are applied before
|
|
|
the case-loca ones.
|
|
|
|
|
|
Here are some examples of where they might be useful:
|
|
|
|
|
|
- Obtaining the default dictionary values for a simulation
|
|
|
```
|
|
|
$ simpleFoam -info-switch writeOptionalEntries -dry-run
|
|
|
```
|
|
|
|
|
|
- Deep-level debugging of the `#eval` directive in a dictionary:
|
|
|
```
|
|
|
$ foamDictionary -debug-switch fieldExpr=4 -expand mydict
|
|
|
```
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
|
[sourceforge]: https://sourceforge.net/projects/openfoam/files/
|
|
|
[compiler-versions]: /building#different-compiler-versions
|
|
|
|
|
|
[expressions]: https://develop.openfoam.com/Development/openfoam/blob/develop/doc/Expressions.md
|
|
|
|
|
|
[v1906-user]: /upgrade/v1906-User-Upgrade-Guide
|
|
|
[v1906-devel]: /upgrade/v1906-Developer-Upgrade-Guide
|
|
|
|
|
|
[code-patterns]: /coding/patterns/patterns
|
|
|
[upgrade-guide]: /upgrade/upgrade
|
|
|
|
|
|
[v1912-notes]: https://www.openfoam.com/releases/openfoam-v1912/ |