[version 12][version 11][version 10][version 9][version 8][version 7][version 6]
4.7 Case management tools
There are a set of applications and scripts that help with managing case files and help the user find and set keyword data entries in case files. The tools are described in the following sections.
4.7.1 General file management
There are some tools for general management of case files, including foamListTimes, foamCleanCase and foamCloneCase. A case includes configuration files for various processes such as meshing, case initialisation, simulation and post-processing. Each process generates new data files in various directories, e.g. mesh data is stored in constant/polyMesh, CFD results in time directories, and further post-processing in a postProcessing directory.
The foamListTimes utility lists the time directories for a case, omitting the 0 directory by default. Prior to re-running a CFD simulation, it can be useful to delete the results from the previous simulation. The foamListTimes utility provides this function through the -rm option which deletes the listed time directories, executed by the following command.
foamListTimes -rm
The foamCleanCase script aims to reset the case files to their original state, removing all files generated during a workflow including the meshing, post-processing. It deletes directories including: postProcessing and VTK; the constant/polyMesh directory; processor directories from parallel decomposition; and, dynamicCode for run-time compiled code. The script is simply run as follows.
foamCleanCase
The foamCloneCase script creates a new case, by copying the 0, system and constant directories from an existing case. The copied case is ready to run since the mesh is copied through the constant directory. If the original case is set up to run in parallel, the processor directories can also be copied using the -processor option. The basic command is executed simply as follows, where oldCase refers to an existing case directory.
4.7.2 The foamDictionary utility
The foamDictionary utility offers several options for printing, editing and adding keyword entries in case files. The utility is executed with a case dictionary file as an argument, e.g. from within a case directory on the fvSchemes file.
foamDictionary system/fvSchemes
FoamFile { format ascii; class dictionary; location "system"; object fvSchemes; } ddtSchemes { default steadyState; } gradSchemes { default Gauss linear; grad(U) cellLimited Gauss linear 1; } divSchemes { default none; div(phi,U) bounded Gauss linearUpwind grad(U); turbulence bounded Gauss limitedLinear 1; div(phi,k) $turbulence; div(phi,epsilon) $turbulence; div(phi,omega) $turbulence; div(phi,v2) $turbulence; div((nuEff*dev2(T(grad(U))))) Gauss linear; div(nonlinearStress) Gauss linear; } laplacianSchemes { default Gauss linear corrected; } interpolationSchemes { default linear; } snGradSchemes { default corrected; }
The output includes the macros before expansion, indicated by the $ symbol, e.g. $turbulence. The macros can be expanded by the -expand option as shown below
foamDictionary -expand system/fvSchemes
The -entry option prints the entry for a particular keyword, expanding the macros by default, e.g. divSchemes in the example below
foamDictionary -entry divSchemes system/fvSchemes
divSchemes { default none; div(phi,U) bounded Gauss linearUpwind grad(U); turbulence bounded Gauss limitedLinear 1; div(phi,k) $turbulence; div(phi,epsilon) $turbulence; div(phi,omega) $turbulence; div(phi,v2) $turbulence; div((nuEff*dev2(T(grad(U))))) Gauss linear; div(nonlinearStress) Gauss linear; }
The “/” syntax allows access to keywords with levels of sub-dictionary. For example, the div(phi,U) keyword can be accessed within the divSchemes sub-dictionary by the following command.
foamDictionary -entry "divSchemes/div(phi,U)" system/fvSchemes
div(phi,U) bounded Gauss linearUpwind grad(U);
The -value option prints only the entry.
foamDictionary -entry "divSchemes/div(phi,U)" -value system/fvSchemes
bounded Gauss linearUpwind grad(U)
The -keywords option prints only the keywords.
foamDictionary -entry divSchemes -keywords system/fvSchemes
default div(phi,U) div(phi,k) div(phi,epsilon) div(phi,omega) div(phi,v2) div((nuEff*dev2(T(grad(U))))) div(nonlinearStress)
foamDictionary can set entries with the -set option. If the user wishes to change the div(phi,U) to the upwind scheme, they can enter the following.
foamDictionary -entry "divSchemes/div(phi,U)" \
-set "bounded Gauss upwind" system/fvSchemes
foamDictionary -set "startFrom=startTime, startTime=0" \
system/controlDict
foamDictionary can add entries with the -add option. If the user wishes to add an entry named turbulence to divSchemes with the upwind scheme, they can enter the following.
foamDictionary -entry "divSchemes/turbulence" \
-add "bounded Gauss upwind" system/fvSchemes
4.7.3 The foamSearch script
The foamSearch script, demonstrated extensively in section 4.5 , uses foamDictionary to extract and sort keyword entries from all files of a specified name in a specified dictionary. The -c option counts the number of entries of each type, e.g. the user could searche for the choice of solver for the p equation in all the fvSolution files in the tutorials.
foamSearch -c $FOAM_TUTORIALS fvSolution solvers/p/solver
64 solver GAMG;
2 solver PBiCGStab;
26 solver PCG;
5 solver smoothSolver;
4.7.4 The foamGet script
The foamGet script copies configuration files into a case quickly and conveniently. The user must be inside a case directory to run the script or identify the case directory with the -case option. Its operation can be described using the pitzDailySteady case described in section 2.1 . The example begins by copying the case directory as follows:
run
cp -r $FOAM_TUTORIALS/modules/incompressibleFluid/pitzDailySteady .
cd pitzDailySteady
blockMesh
foamPostProcess -list
foamGet patchFlowRate
patch outlet;
functions
{
...
//#includeFunc writeObjects(kEpsilon:G) // existing entry
#includeFunc patchFlowRate
}
4.7.5 The foamInfo script
The foamInfo script provides quick information and examples relating to thing in OpenFOAM that the user can “select”. The selections include models (including boundary conditions and packaged function objects), solver modules, applications and scripts. For example, foamInfo prints information about the incompressibleFluid solver module by typing the following:
foamInfo incompressibleFluid
foamInfo flowRateInletVelocity
When the user requests information about a model with foamInfo, it attempts to provide a list of other models in the “family”. For example, if the user requests information about the kEpsilon turbulence model by
foamInfo kEpsilon
Model
This appears to be the 'kEpsilon' model of the 'RAS' family.
The models in the 'RAS' family are:
+ kEpsilon
+ kOmega
+ kOmega2006
+ kOmegaSST
+ kOmegaSSTLM
+ kOmegaSSTSAS
+ LaunderSharmaKE
+ LRR
+ RAS
+ realizableKE
+ RNGkEpsilon
+ SpalartAllmaras
+ SSG
+ v2f
foamInfo clouds
foamInfo limitTemperature
foamInfo linearRamp
foamInfo triSurfaceMesh
foamInfo Function1
foamInfo searchableSurfaces
4.7.6 The foamToC utility
The foamToC utility lists all the options in OpenFOAM which the user can select through input files. The functionality overlaps with foamInfo to some extent but foamToC produces more definitive reporting since it is an OpenFOAM application which directly interrogates the run-time selection tables in the compiled libraries. The “ToC” in the name is an abbreviation for “Table of Contents.”
As well as providing general options to interrogate anything in OpenFOAM, foamToC includes specific options that replicate most of the “-list…” options included in application solvers prior to v11. These options included: -listScalarBCs and -listVectorBCs to list boundary conditions; -listFunctionObjects to list functionObjects; -listFvModels to list fvModels; and, -listFvConstraints to list fvConstraints. The equivalent options in foamToC are listed below, with an additional -solvers option:
-
-scalarBCs and -vectorBCs to list boundary conditions;
-
-functionObjects to list functionObjects;
-
-fvModels to list fvModels;
-
-fvConstraints to list fvConstraints; and,
-
-solvers to list the solver modules.
For example, with the last option, foamToC prints the following output
>> foamToC -fvConstraints fvConstraints: Contents of table fvConstraint: bound libfvConstraints.so fixedTemperatureConstraint libfvConstraints.so fixedValueConstraint libfvConstraints.so limitMag libfvConstraints.so limitPressure libfvConstraints.so limitTemperature libfvConstraints.so meanVelocityForce libfvConstraints.so patchMeanVelocityForce libfvConstraints.so zeroDimensionalFixedPressure libfvConstraints.so
Each fvConstraint is listed in the left column with the library to which it belongs in the right column. The options listed above essentially invoke the more general -table option that lists the contents of a run-time selection table. The -fvConstraints option is equivalent to the following command which lists the items in the fvConstraint table.
foamToC -table fvConstraint
foamToC -tables
foamToC
-
-noLibs: only loads the core libOpenFOAM.so library by default.
-
-solver <solver>: only loads libraries associated with the specified solver module <solver>.
-
-libs '("lib1.so" ... "libN.so")': additionally pre-loads specified libraries, e.g. customised libraries of the user.
An important use of foamToC is to enable users to find alternative models to the one currently configured for their case. The challenge is to find the table that contains the models they wish to list. The -search option helps with this, since it takes an entry, e.g. a model, and reports the table in which it belongs. For example, if the user was familiar with the BirdCarreau model for viscosity and wished to list alternative non-Newtonian models, they could first issue the following command.
>> foamToC -search BirdCarreau
BirdCarreau is in table
generalisedNewtonianViscosityModel libmomentumTransportModels.so
>> foamToC -table generalisedNewtonianViscosityModel
Contents of table generalisedNewtonianViscosityModel:
BirdCarreau libmomentumTransportModels.so
Casson libmomentumTransportModels.so
CrossPowerLaw libmomentumTransportModels.so
HerschelBulkley libmomentumTransportModels.so
Newtonian libmomentumTransportModels.so
powerLaw libmomentumTransportModels.so
strainRateFunction libmomentumTransportModels.so
foamToC -solvers
foamToC -table solver
kEpsilon is in table
RAS
RAScompressibleMomentumTransportModel
RASincompressibleMomentumTransportModel
RASphaseCompressibleMomentumTransportModel
RASphaseIncompressibleMomentumTransportModel
foamToC -table RASincompressibleMomentumTransportModel
4.7.7 The foamUnits script
The foamUnits utility provides details of named units and dimensional units, described in sections 4.2.7 and 4.2.6 , respectively. Users can list the named units by running with the -list option, i.e.
foamUnits -list
Basic units: [kg] [m] [s] [K] [kmol] [A] [Cd]
Derived units: [Hz] [N] [Pa] [J] [W]
...
foamUnits -list -dimensions
Base dimensions: [mass] [length] [time] [temperature] [moles] ...
Derived dimensions:
[area] [volume] [rate] [velocity] [momentum]
...
foamUnits cal
Unit [cal]
+ Base unit = [J]
+ Conversion factor = 4.184
foamUnits -dimension energy
Dimension [energy]
+ Base dimensions = [force*length]
4.7.8 The foamFind script
The foamFind script searches for files in OpenFOAM. It can simply provide the location of files by printing their filename including the path. Alternatively it can print the entire file into the terminal, print lines matching a search string or open the file in a text editor. The script is principally used to locate source code files (so perhaps does not fall much under “Case Management”, the title of this section of the guide).
For example, if a user wished to locate the file wallHeatFlux.C, they could simply type
foamFind wallHeatFlux.C
File: $FOAM_SRC//functionObjects/field/wallHeatFlux/wallHeatFlux.C
foamFind -print wallHeatFlux.C
foamFind wallHeatFlux.C -print # Alternatively
foamFind wallHeatFlux.C -print | less
-
click the space bar, page up, page down keys to scroll;
-
enter line number after “:” to jump to a line;
-
enter “/” followed by a string to search for the string, e.g. /calc to search for “calc”;
-
enter “q” to quit.
A file can also be opened in a file editor using the -editor option. For this option to work, the user’s environment must include an $EDITOR environment variable set to the user’s editor of choice. For example, to set the gedit editor, the user could add the following to their $HOME/.bashrc file:
export EDITOR=gedit
foamFind wallHeatFlux.C -edit
The foamFind script includes the -search option to print lines of a file matching a string, e.g. to search “heat”:
foamFind wallHeatFlux.C -search heat
foamFind wallHeatFlux.C -isearch heat
foamFind wallHeatFlux.C -isearch heat -numbers
The source code is ultimately compiled with wmake as described in section 3.2 . The instructions for wmake are included in the files and options files in an associated Make directory. The foamFind script include two options, -files and -options, which return the files and options files, respectively, associated with the source code file. The following command would locate the options file associated with wallHeatFlux:
foamFind wallHeatFlux.C -options
By default, foamFind is searching for source code files so begins its search from the $FOAM_SRC directory within the OpenFOAM installation. Alternative directories for the search can be specified with the following options:
-
-applications: the $FOAM_APP (applications) directory;
-
-modules: the $FOAM_MODULES (modules) directory;
-
-tutorial: the $FOAM_TUTORIALS (tutorials) directory;
The -dir option also allows the user to specify any other directory.
The foamFind script could find multiple files of the same name in a single search, e.g. looking for createFields.H in the $FOAM_APP directory by:
foamFind -applications createFields.H -print