The majority of input parameters now support automatic unit conversion.
Units are specified within square brackets, either before or after the
value. Primitive parameters (e.g., scalars, vectors, tensors, ...),
dimensioned types, fields, Function1-s and Function2-s all support unit
conversion in this way.
Unit conversion occurs on input only. OpenFOAM writes out all fields and
parameters in standard units. It is recommended to use '.orig' files in
the 0 directory to preserve user-readable input if those files are being
modified by pre-processing applications (e.g., setFields).
For example, to specify a volumetric flow rate inlet boundary in litres
per second [l/s], rather than metres-cubed per second [m^3/s], in 0/U:
boundaryField
{
inlet
{
type flowRateInletVelocity;
volumetricFlowRate 0.1 [l/s];
value $internalField;
}
...
}
Or, to specify the pressure field in bar, in 0/p:
internalField uniform 1 [bar];
Or, to convert the parameters of an Arrhenius reaction rate from a
cm-mol-kcal unit system, in constant/chemistryProperties:
reactions
{
methaneReaction
{
type irreversibleArrhenius;
reaction "CH4^0.2 + 2O2^1.3 = CO2 + 2H2O";
A 6.7e12 [(mol/cm^3)^-0.5/s];
beta 0;
Ea 48.4 [kcal/mol];
}
}
Or, to define a time-varying outlet pressure using a CSV file in which
the pressure column is in mega-pascals [MPa], in 0/p:
boundaryField
{
outlet
{
type uniformFixedValue;
value
{
type table;
format csv;
nHeaderLine 1;
units ([s] [MPa]); // <-- new units entry
columns (0 1);
mergeSeparators no;
file "data/pressure.csv";
outOfBounds clamp;
interpolationScheme linear;
}
}
...
}
(Note also that a new 'columns' entry replaces the old 'refColumn' and
'componentColumns'. This is is considered to be more intuitive, and has
a consistent syntax with the new 'units' entry. 'columns' and
'componentColumns' have been retained for backwards compatibility and
will continue to work for the time being.)
Unit definitions can be added in the global or case controlDict files.
See UnitConversions in $WM_PROJECT_DIR/etc/controlDict for examples.
Currently available units include:
Standard: kg m s K kmol A Cd
Derived: Hz N Pa J W g um mm cm km l ml us ms min hr mol
rpm bar atm kPa MPa cal kcal cSt cP % rad rot deg
A user-time unit is also provided if user-time is in operation. This
allows it to be specified locally whether a parameter relates to
real-time or to user-time. For example, to define a mass source that
ramps up from a given engine-time (in crank-angle-degrees [CAD]) over a
duration in real-time, in constant/fvModels:
massSource1
{
type massSource;
points ((1 2 3));
massFlowRate
{
type scale;
scale linearRamp;
start 20 [CAD];
duration 50 [ms];
value 0.1 [g/s];
}
}
Specified units will be checked against the parameter's dimensions where
possible, and an error generated if they are not consistent. For the
dimensions to be available for this check, the code requires
modification, and work propagating this change across OpenFOAM is
ongoing. Unit conversions are still possible without these changes, but
the validity of such conversions will not be checked.
Units are no longer permitted in 'dimensions' entries in field files.
These 'dimensions' entries can now, instead, take the names of
dimensions. The names of the available dimensions are:
Standard: mass length time temperature
moles current luminousIntensity
Derived: area volume rate velocity momentum acceleration density
force energy power pressure kinematicPressure
compressibility gasConstant specificHeatCapacity
kinematicViscosity dynamicViscosity thermalConductivity
volumetricFlux massFlux
So, for example, a 0/epsilon file might specify the dimensions as
follows:
dimensions [energy/mass/time];
And a 0/alphat file might have:
dimensions [thermalConductivity/specificHeatCapacity];
*** Development Notes ***
A unit conversion can construct trivially from a dimension set,
resulting in a "standard" unit with a conversion factor of one. This
means the functions which perform unit conversion on read can be
provided dimension sets or unit conversion objects interchangeably.
A basic `dict.lookup<vector>("Umean")` call will do unit conversion, but
it does not know the parameter's dimensions, so it cannot check the
validity of the supplied units. A corresponding lookup function has been
added in which the dimensions or units can be provided; in this case the
corresponding call would be `dict.lookup<vector>("Umean", dimVelocity)`.
This function enables additional checking and should be used wherever
possible.
Function1-s and Function2-s have had their constructors and selectors
changed so that dimensions/units must be specified by calling code. In
the case of Function1, two unit arguments must be given; one for the
x-axis and one for the value-axis. For Function2-s, three must be
provided.
In some cases, it is desirable (or at least established practice), that
a given non-standard unit be used in the absence of specific
user-defined units. Commonly this includes reading angles in degrees
(rather than radians) and reading times in user-time (rather than
real-time). The primitive lookup functions and Function1 and Function2
selectors both support specifying a non-standard default unit. For
example, `theta_ = dict.lookup<scalar>("theta", unitDegrees)` will read
an angle in degrees by default. If this is done within a model which
also supports writing then the write call must be modified accordingly
so that the data is also written out in degrees. Overloads of writeEntry
have been created for this purpose. In this case, the angle theta should
be written out with `writeEntry(os, "theta", unitDegrees, theta_)`.
Function1-s and Function2-s behave similarly, but with greater numbers
of dimensions/units arguments as before.
The non-standard user-time unit can be accessed by a `userUnits()`
method that has been added to Time. Use of this user-time unit in the
construction of Function1-s should prevent the need for explicit
user-time conversion in boundary conditions and sub-models and similar.
Some models might contain non-typed stream-based lookups of the form
`dict.lookup("p0") >> p0_` (e.g., in a re-read method), or
`Umean_(dict.lookup("Umean"))` (e.g., in an initialiser list). These
calls cannot facilitate unit conversion and are therefore discouraged.
They should be replaced with
`p0_ = dict.lookup<scalar>("p0", dimPressure)` and
`Umean_(dict.lookup<vector>("Umean", dimVelocity))` and similar whenever
they are found.
Coded functionality now supports basic un-typed substitutions from the
surrounding dictionary. For example:
value 1.2345;
#codeExecute
{
scalar s = $value;
...
};
It also now supports the more functional typed substitutions, such as:
direction (1 0 0);
#codeExecute
{
vector v = $<vector>direction;
...
};
These substitutions are now possible in all code blocks. Blocks with
access to the dictionary (e.g., #codeRead) will do a lookup which will
not require re-compilation if the value is changed. Blocks without
access to the dictionary will have the value directly substituted, and
will require recompilation when the value is changed.
Description
Executes primitiveMesh::checkMesh(true) every execute time for which the
mesh changed, i.e. moved or changed topology.
Useful to check the correctness of changing and morphing meshes.
Usage
\table
Property | Description | Required | Default value
type | type name: checkMesh | yes |
noTopology | Skip checking the mesh topology | no | false
allTopology | Check all addressing | no | false
allGeometry | Check all geometry | no | false
writeSurfaces | Reconstruct and write problem faces | no | false
surfaceFormat | Format for problem faceSets | no | vtk
writeSets | Reconstruct and write problem points | no | false
setFormat | Format used to write the problem pointSets | no | vtk
nonOrthThreshold | Threshold for non-orthogonality errors | no | 70 deg
skewThreshold | Threshold for reporting skewness errors | no | 4
stopAt | Stops the run if any mesh checks fail | no | endTime
\endtable
The optional \c stopAt option may be set to
- endTime : Continue running on error
- noWriteNow : Stops the run on error without write
- writeNow : Stops the run on error and writes fields
- nextWrite : Stops the run at the next write time on error
Example of checkMesh specification:
\verbatim
checkMesh
{
type checkMesh;
libs ("libutilityFunctionObjects.so");
executeControl timeStep;
executeInterval 10;
allGeometry true;
allTopology true;
writeSurfaces true;
surfaceFormat vtk;
writeSets true;
setFormat vtk;
stopAt writeNow;
}
\endverbatim
or using the standard configuration file:
\verbatim
#includeFunc checkMesh(executeInterval=10, allGeometry=true)
\endverbatim
Now both the checkMesh utility and functionObject operate in the same manner
with the same controls, executing the same checkGeometry and checkTopology
functions from the new meshCheck library. The controls have been updated and
made more consistent and flexible, in particular by the addition of optional
user specification for the non-orthogonality and skewness error thresholds:
Application
checkMesh
Description
Checks validity of a mesh.
Usage
\b checkMesh [OPTION]
Options:
- \par noTopology
Skip checking the mesh topology
- \par -allTopology
Check all (including non finite-volume specific) addressing
- \par -allGeometry
Check all (including non finite-volume specific) geometry
- \par -meshQuality
Check against user defined (in \a system/meshQualityDict) quality
settings
- \par -region \<name\>
Specify an alternative mesh region.
- \par -writeSurfaces
Reconstruct cellSets and faceSets of problem faces and write to
postProcessing directory.
- \par -surfaceFormat <format>
Format used to write the cellSets and faceSets surfaces
e.g. vtk or ensight.
- \par -writeSets
Reconstruct pointSets of problem points nd write to
postProcessing directory.
- \par -setFormat <format>
Format used to write the pointSets
e.g. vtk or ensight.
- \par -nonOrthThreshold <threshold value in degrees>
Threshold in degrees for reporting non-orthogonality errors,
default: 70"
- \par -skewThreshold <threshold value>
Threshold for reporting skewness errors, default: 4.
Class
Foam::functionObjects::checkMesh
Description
Executes primitiveMesh::checkMesh(true) every execute time for which the
mesh changed, i.e. moved or changed topology.
Useful to check the correctness of changing and morphing meshes.
Usage
\table
Property | Description | Required | Default value
type | type name: checkMesh | yes |
noTopology | Skip checking the mesh topology | no | false
allTopology | Check all addressing | no | false
allGeometry | Check all geometry | no | false
writeSurfaces | Reconstruct and write problem faces | no | false
surfaceFormat | Format for problem faceSets | no | vtk
writeSets | Reconstruct and write problem points | no | false
setFormat | Format used to write the problem pointSets | no | vtk
nonOrthThreshold | Threshold for non-orthogonality errors | no | 70 deg
skewThreshold | Threshold for reporting skewness errors | no | 4
\endtable
Example of checkMesh specification:
\verbatim
checkMesh
{
type checkMesh;
libs ("libutilityFunctionObjects.so");
executeControl timeStep;
executeInterval 10;
allGeometry true;
allTopology true;
writeSurfaces true;
surfaceFormat vtk;
writeSets true;
setFormat vtk;
}
\endverbatim
or using the standard configuration file:
\verbatim
#includeFunc checkMesh(executeInterval=10, allGeometry=true)
\endverbatim
When the parallel switch is set false (the default), the system call is executed
only on the master processor, if true it is executed on all processors.
Patch contributed by Stanislau Stasheuski, Aalto University.
Specific names have been given for expand functions. Unused functions
have been removed, and functions only used locally have been removed
from the namespace. Documentation has been corrected. Default and
alternative value handling has been removed from code template
expansion.
Class
Foam::functionObjects::checkMesh
Description
Executes primitiveMesh::checkMesh(true) every execute time for which the
mesh changed, i.e. moved or changed topology.
Useful to check the correctness of changing and morphing meshes.
Example of checkMesh specification:
\verbatim
checkMesh
{
type checkMesh;
libs ("libutilityFunctionObjects.so");
executeControl timeStep;
executeInterval 10;
}
\endverbatim
or using the standard configuration file:
\verbatim
#includeFunc checkMesh(executeInterval=10)
\endverbatim
Can be used with any solver supporting mesh-motion, in particular the movingMesh
solver module, to check the mesh quality following morphing and/or topology
change.
This is useful to write results before a case fails due to uncontrollable
automatic time-step reduction, usually caused by unstable pressure-velocity
coupling.
Class
Foam::functionObjects::stopAtTimeStep
Description
Stops the run if the time-step drops below the specified value in seconds
and optionally write results before stopping.
The following actions are supported:
- noWriteNow
- writeNow (default)
- nextWrite
Examples of function object specification:
\verbatim
stop
{
type stopAtTimeStep;
libs ("libutilityFunctionObjects.so");
minDeltaT 1e-8;
action writeNow;
}
\endverbatim
will write the fields and stop if the time-step drops below 1e-8s.
Usage
\table
Property | Description | Required | Default value
type | type name: stopAtTimeStep | yes |
minDeltaT | Minimum time-step [s] | yes |
action | Action executed | no | writeNow
\endtable
The timeName() function simply returns the dimensionedScalar::name() which holds
the user-time name of the current time and now that timeName() is no longer
virtual the dimensionedScalar::name() can be called directly. The timeName()
function implementation is maintained for backward-compatibility.
Also changed the keyword timeVsFile to the more logical fileVsTime with
backward-compatibility.
Class
Foam::functionObjects::timeActivatedFileUpdate
Description
Performs a file copy/replacement once a specified time has been reached.
Usage
Example usage to update the fvSolution dictionary at 0.1, 0.2 and 0.3s
during the run:
\verbatim
fileUpdate1
{
type timeActivatedFileUpdate;
libs ("libutilityFunctionObjects.so");
writeControl timeStep;
writeInterval 1;
fileToUpdate "$FOAM_CASE/system/fvSolution";
fileVsTime
(
(-1 "$FOAM_CASE/system/fvSolution.0")
(0.10 "$FOAM_CASE/system/fvSolution.10")
(0.20 "$FOAM_CASE/system/fvSolution.20")
(0.35 "$FOAM_CASE/system/fvSolution.35")
);
}
\endverbatim
Resolves bug-report https://bugs.openfoam.org/view.php?id=3938
so that the specification of time-step and write-interval are in user-time,
consistent with the controlDict.
Class
Foam::functionObjects::setTimeStepFunctionObject
Description
Updates the time step as a Function1 of time.
If the case is running with userTime specified in controlDict then the
time-step values returned by the Function1 are assumed to be in user-time
rather than real-time.
Class
Foam::functionObjects::setWriteIntervalFunctionObject
Description
Updates the writeInterval as a Function1 of time.
If the case is running with userTime specified in controlDict then the write
interval values returned by the Function1 are assumed to be in user-time
rather than real-time.
Resolves bug-report https://bugs.openfoam.org/view.php?id=3904
With this change each functionObject provides the list of fields required so
that the postProcess utility can pre-load them before executing the list of
functionObjects. This provides a more convenient interface than using the
-field or -fields command-line options to postProcess which are now redundant.
replacing the virtual functions overridden in engineTime.
Now the userTime conversion function in Time is specified in system/controlDict
such that the solver as well as all pre- and post-processing tools also operate
correctly with the chosen user-time.
For example the user-time and rpm in the tutorials/combustion/XiEngineFoam/kivaTest case are
now specified in system/controlDict:
userTime
{
type engine;
rpm 1500;
}
The default specification is real-time:
userTime
{
type real;
}
but this entry can be omitted as the real-time class is instantiated
automatically if the userTime entry is not present in system/controlDict.
used to check the existence of and open an object file, read and check the
header without constructing the object.
'typeIOobject' operates in an equivalent and consistent manner to 'regIOobject'
but the type information is provided by the template argument rather than via
virtual functions for which the derived object would need to be constructed,
which is the case for 'regIOobject'.
'typeIOobject' replaces the previous separate functions 'typeHeaderOk' and
'typeFilePath' with a single consistent interface.
setTimeStep is now compatible with a 'writeControl adjustableRunTime;'
setting in the systemControlDict. If 'adjustableRunTime' is selected
then the time-step values set by this function object will not be
exactly as specified, but write intervals will be matched exactly.
All function object time adjustment is now done during the execute
methods, so the specific setTimeStep hooks have been removed.
All function objects now re-read as a result of run-time modifications
to the system/controlDict.
Function objects that write log files (via the logFiles class) will now
generate a new postProcessing/<funcName>/<time> directory as a result of
either restart or run-time modification. Log files will therefore never
be overwritten by restart or run-time modification, except for when a
case is restarted at the same time as a previous execution (e.g.,
repeated runs at the start time).
Description
Updates the writeInterval as a Function1 of time.
Examples of function object specification:
\verbatim
setWriteInterval
{
type setWriteInterval;
libs ("libutilityFunctionObjects.so");
writeInterval table
(
(0 0.005)
(0.1 0.005)
(0.1001 0.01)
(0.2 0.01)
(0.2001 0.02)
);
}
\endverbatim
will cause results to be written every 0.005s between 0 and 0.1s, every
0.01s between 0.1 and 0.2s and every 0.02s thereafter.
This avoids attempting to write temporary fields before they have been created.
The executeAtStart can be set to 'yes' in the writeObjects dictionary or the
functions
{
#includeFunc writeObjects(executeAtStart = yes, <field1>, <field2>...)
}
This is a slight modification of the previous commit. All cached
temporary fields are now written to disk with the name enclosed by
"tmp<...>". This still allows for automatically constructed
field names to be read by paraFoam and other post-processing tools. It
also creates a consistent convention for naming all cached temporary
fields that are written to disk.
for example
cacheTemporaryObjects
(
"((1|((1|(1|A(U)))-H(1)))-(1|A(U)))"
);
functions
{
#includeFunc writeObjects(regExp=off, "((1|((1|(1|A(U)))-H(1)))-(1|A(U)))")
}
writes the temporary field with the name
"expr((1|((1|(1|A(U)))-H(1)))-(1|A(U)))" so that it can be read by paraFoam and
other post-processing tools.
Description
Stops the run when the specified clock time in second has been reached
and optionally write results before stopping.
The following actions are supported:
- noWriteNow
- writeNow
- nextWrite (default)
Examples of function object specification:
\verbatim
stop
{
type stopAtClockTime;
libs ("libutilityFunctionObjects.so");
stopTime 10;
action writeNow;
}
\endverbatim
will stop the run at the next write after the file "stop" is created in the
case directory.
Usage
\table
Property | Description | Required | Default value
type | type name: stopAtClockTime | yes |
stopTime | Maximum elapsed time [s] | yes |
action | Action executed | no | nextWrite
\endtable
By default the case stops following the next write but stopping immediately with
or without writing are also options.
The stopAtFile functionObject derived from stopAt stops the run when a file
predefined file is created in the case directory:
Description
Stops the run when the specified file is created in the case directory.
The default name of the trigger file is \c $FOAM_CASE/<name> where \c
<name> is the name of the functionObject entry and the default action is \c
nextWrite.
Currently the following action types are supported:
- noWriteNow
- writeNow
- nextWrite
Examples of function object specification:
\verbatim
stop
{
type stopAtFile;
libs ("libutilityFunctionObjects.so");
}
\endverbatim
will stop the run at the next write after the file "stop" is created in the
case directory.
\verbatim
stop
{
type stopAtFile;
libs ("libutilityFunctionObjects.so");
file "$FOAM_CASE/stop";
action writeNow;
}
\endverbatim
will write the fields and stop the run when the file "stop" is created in
the case directory.
Usage
\table
Property | Description | Required | Default value
type | type name: stopAtFile | yes |
file | Trigger file path name | no | $FOAM_CASE/<name>
action | Action executed | no | nextWrite
\endtable
For example in the new tutorial case:
tutorials/incompressible/pimpleFoam/laminar/pitzDailyPulse
a cosine bell velocity pulse is specified at the inlet by directly defining the
code for it:
inlet
{
type uniformFixedValue;
uniformValue coded;
name pulse;
codeInclude
#{
#include "mathematicalConstants.H"
#};
code
#{
return vector
(
0.5*(1 - cos(constant::mathematical::twoPi*min(x/0.3, 1))),
0,
0
);
#};
}
which is then compiled automatically and linked into the running pimpleFoam
dynamically and executed to set the inlet velocity.
