Commit 4e2d990b authored by Kutalmis Bercin's avatar Kutalmis Bercin
Browse files

DOC: forces/forceCoeffs: improve header documentation

parent 90c6eb77
......@@ -31,132 +31,236 @@ Group
grpForcesFunctionObjects
Description
Extends the \c forces functionObject by providing coefficients for:
- drag, side and lift forces (Cd, Cs, and Cl)
- roll, pitch and yaw moments (CmRoll, CmPitch, and CmYaw)
- front and rear axle force contributions (C(f) and C(r)) wherein
Computes force and moment coefficients over a given
list of patches, and optionally over given porous zones.
The following coefficients can be selected and output:
\verbatim
Cd | Drag coefficient
Cs | Side-force coefficient
Cl | Lift coefficient
CmRoll | Roll-moment coefficient
CmPitch | Pitch-moment coefficient
CmYaw | Yaw-moment coefficient
\endverbatim
The force coefficients can also be optionally output
in terms of their front and rear axle constituents:
\verbatim
Cd(f/r) = 0.5*Cd \pm CmRoll
Cs(f/r) = 0.5*Cs \pm CmYaw
Cl(f/r) = 0.5*Cl \pm CmPitch
Cd{f,r} = 0.5*Cd {+,-} CmRoll
Cs{f,r} = 0.5*Cs {+,-} CmYaw
Cl{f,r} = 0.5*Cl {+,-} CmPitch
\endverbatim
where \c f and \c r represent front and rear axles, respectively.
Force and moment coefficients are output
in their total and constituent components:
- total force and moment coefficients
- pressure contributions
- viscous contributions
- porous resistance contributions (optional)
Force and moment coefficients can be computed and output in:
- the global Cartesian coordinate system (default)
- a user-defined Cartesian coordinate system
Force and moment coefficients can also be equidistant-spatially
'binned' over given patches. See the following link for the details:
- \link binModel.H \endlink
Operands:
\table
Operand | Type | Location
input | - | -
output file | dat | $FOAM_CASE/postProcessing/\<FO\>/\<time\>/\<file\>s
output field | volVectorField | $FOAM_CASE/\<time\>/\<outField\>s
\endtable
The data can optionally be output into bins, defined in a given direction.
where \c \<file\>s:
\verbatim
coefficient.dat | Integrated coefficients over all patches
\endverbatim
The binned data provides the total and consitituent components per bin:
- total coefficient
- pressure coefficient contribution
- viscous coefficient contribution
- porous coefficient contribution
If a bin model is activated, additional \c \<file\>s are output:
\verbatim
CdBin.dat | Drag coefficient bins
CsBin.dat | Side-force coefficient bins
ClBin.dat | Lift coefficient bins
CmRollBin.dat | Roll-moment coefficient bins
CmPitchBin.dat | Pitch moment coefficient bins
CmYawBin.dat | Yaw-moment coefficient bins
\endverbatim
Data is written into multiple files in the
postProcessing/\<functionObjectName\> directory:
- coefficient.dat : integrated coefficients over all geometries
- CdBin.dat : drag coefficient bins
- CsBin.dat : side coefficient bins
- ClBin.dat : lift coefficient bins
- CmRollBin.dat : roll moment coefficient bins
- CmPitchBin.dat : pitch moment coefficient bins
- CmYawBin.dat : yaw moment coefficient bins
where \c \<outField\>s:
\verbatim
forceCoeff | Force coefficient field
momentCoeff | Moment coefficient field
\endverbatim
Usage
Example of function object specification:
Minimal example by using \c system/controlDict.functions:
\verbatim
forceCoeffs1
{
type forceCoeffs;
libs (forces);
...
log yes;
writeFields yes;
patches (walls);
// Mandatory entries (unmodifiable)
type forceCoeffs;
libs (forces);
// Mandatory entries (runtime modifiable)
patches (<patch1> ... <patchN>); // (wall1 "(wall2|wall3)");
magUInf 100;
lRef 3.5;
Aref 2.2;
// Optional entries (runtime modifiable)
directForceDensity false;
porosity false;
writeFields false;
forceCoeffs (Cd Cs Cl);
momentCoeffs (CmRoll CmPitch CmYaw);
frontRearForceCoeffs (Cdf Csf Clf Cdr Csr Clr);
// Conditional mandatory entries (runtime modifiable)
// Cartesian coordinate system specification when evaluating
// force and moment coefficients, either of the below
// Option-1, i.e. the centre of rotation
// by inherently using e3=(0 0 1) and e1=(1 0 0)
CofR (0 0 0); // Centre of rotation
dragDir (1 0 0);
liftDir (0 0 1);
// Option-2, i.e. local coordinate system specification
origin (0 0 0);
e1 (1 0 0);
e3 (0 0 1); // (e1, e2) or (e2, e3) or (e3, e1)
// Option-3, i.e. general coordinate system specification
coordinateSystem
{
type cartesian;
origin (0 0 0);
rotation
{
type axes;
e3 (0 0 1);
e1 (1 0 0); // (e1, e2) or (e2, e3) or (e3, e1)
}
}
// input keywords for directions of force/moment coefficients
// refer below for options, and relations
// Conditional optional entries (runtime modifiable)
magUInf 100;
lRef 3.5;
Aref 2.2;
porosity no;
// if directForceDensity == true
fD <fDName>;
binData
{
nBin 20;
direction (1 0 0);
cumulative yes;
}
// if directForceDensity == false
p <pName>;
U <UName>;
rho <rhoName>;
rhoInf 1; // redundant for incompressible-flow cases
pRef 0;
// Inherited entries
...
}
\endverbatim
Where the entries comprise:
where the entries mean:
\table
Property | Description | Required | Default
type | Type name: forceCoeffs | yes |
log | Write force data to standard output | no | no
writeFields | Write force,moment coefficient fields | no | no
patches | Patches included in the forces calculation | yes |
magUInf | Free stream velocity magnitude | yes |
rhoInf | Free stream density | for compressible cases |
lRef | Reference length scale for moment calculations | yes |
Aref | Reference area | yes |
porosity | Include porosity contributions | no | false
Property | Description | Type | Reqd | Deflt
type | Type name: forceCoeffs | word | yes | -
libs | Library name: forces | word | yes | -
patches | Names of operand patches | wordList | yes | -
magUInf | Reference velocity magnitude | scalar | yes | -
lRef | Reference length scale for moment <!--
--> calculations | scalar | yes | -
Aref | Reference area | scalar | yes | -
directForceDensity | Flag to directly supply force <!--
--> density - see below | bool | no | false
porosity | Flag to include porosity contributions | bool | no | false
writeFields | Flag to write force and moment fields | bool | no | false
forceCoeffs | Names of operand force coefficients <!--
--> - see below | wordList | no | all
momentCoeffs | Names of operand moment coefficients <!--
--> - see below | wordList | no | all
frontRearForceCoeffs | Names of operand front- and <!--
--> rear-axle force coefficients - see below <!--
--> | wordList | no | none
CofR | Centre of rotation | vector | cndtnl | -
origin | Origin of coordinate system | vector | cndtnl | -
e3 | e3 coordinate axis | vector | cndtnl | -
e1 | e1 coordinate axis | vector | cndtnl | -
coordinateSystem | Coordinate system specifier | dictionary | cndtnl | -
fD | Name of force density field | word | cndtnl-no | fD
p | Name of pressure field | word | cndtnl-no | p
U | Name of velocity field | word | cndtnl-no | U
rho | Name of density field | word | cndtnl-no | rho
rhoInf | Value of reference density | scalar | cndtnl-yes | -
pRef | Value of reference pressure | scalar | cndtnl-no | 0
\endtable
Bin data is optional, but if the dictionary is present, the entries must
be defined according to following:
\table
nBin | Number of data bins | yes |
direction | Direction along which bins are defined | yes |
cumulative | Bin data accumulated with incresing distance | yes |
\endtable
Input of force/moment coefficient directions:
- require an origin, and two orthogonal directions; the remaining orthogonal
direction is determined accordingly.
- can be added by the three options below.
Options for the \c forceCoeffs entry:
\verbatim
CofR (0 0 0); // Centre of rotation
dragDir (1 0 0);
liftDir (0 0 1);
Cd | Drag coefficient
Cs | Side-force coefficient
Cl | Lift coefficient
\endverbatim
Options for the \c momentCoeffs entry:
\verbatim
origin (0 0 0);
e1 (1 0 0);
e3 (0 0 1); // combinations: (e1, e2) or (e2, e3) or (e3, e1)
CmRoll | Roll-moment coefficient
CmPitch | Pitch-moment coefficient
CmYaw | Yaw-moment coefficient
\endverbatim
Options for the \c frontRearForceCoeffs entry:
\verbatim
coordinateSystem
{
origin (0 0 0);
rotation
{
type axes;
e1 (1 0 0);
e3 (0 0 1); // combinations: (e1, e2) or (e2, e3) or (e3, e1)
}
}
Cdf | Front-axle drag coefficient
Csf | Front-axle side-force coefficient
Clf | Front-axle lift coefficient
Cdr | Rear-axle drag coefficient
Csr | Rear-axle side-force coefficient
Clr | Rear-axle lift coefficient
\endverbatim
The default direction relations are shown below:
The inherited entries are elaborated in:
- \link functionObject.H \endlink
- \link writeFile.H \endlink
- \link binModel.H \endlink
- \link coordinateSystem.H \endlink
Note
- \c rhoInf is always redundant for incompressible computations.
That is, \c rhoInf is always equal to 1 in incompressible
computations no matter which input value is assigned to \c rhoInf.
The value of \c rhoInf is only used for compressible computations.
- \c writeControl and \c writeInterval entries of function
object do control when to output force and moment files.
- \c writeControl and \c writeInterval entries of \c controlDict
do control when to output force and moment fields.
- Binning is not supported for force and moment fields,
and for front-axle and rear-axle coefficients.
- Input for force/moment coefficient directions
require an origin and two orthogonal directions where
the remaining orthogonal direction is automatically computed.
- The default direction relations are shown below:
\table
Property | Description | Alias | Direction
dragDir | Drag direction | e1 | (1 0 0)
sideDir | Side force direction | e2 | (0 1 0)
liftDir | Lift direction | e3 | (0 0 1)
rollAxis | Roll axis | e1 | (1 0 0)
pitchAxis | Pitch axis | e2 | (0 1 0)
yawAxis | Yaw axis | e3 | (0 0 1)
Property | Description | Alias | Direction
dragDir | Drag direction | e1 | (1 0 0)
sideDir | Side force direction | e2 | (0 1 0)
liftDir | Lift direction | e3 | (0 0 1)
rollAxis | Roll axis | e1 | (1 0 0)
pitchAxis | Pitch axis | e2 | (0 1 0)
yawAxis | Yaw axis | e3 | (0 0 1)
\endtable
See also
Foam::functionObject
Foam::functionObjects::timeControl
Foam::functionObjects::forces
- Foam::functionObject
- Foam::functionObjects::forces
- Foam::functionObjects::writeFile
- Foam::binModel
SourceFiles
forceCoeffs.C
......
......@@ -31,105 +31,155 @@ Group
grpForcesFunctionObjects
Description
Calculates the forces and moments by integrating the pressure and
skin-friction forces over a given list of patches, and the resistance
from porous zones.
Forces and moments are calculated in a global Cartesian coordinate system
by default, or using a user-defined system. Contributions can be 'binned'
according to a user-defined number of uniform-width collection zones (bins)
that span the input geometries, oriented by a user-defined direction vector.
Results are written to multiple files as a function of time in the
postProcessing/\<functionObjectName\> directory:
- force.dat : forces
- moment.dat : moments
- forceBin.dat : force bins
- momentBin.dat : moment bins
Computes forces and moments over a given list of patches by integrating
pressure and viscous forces and moments, and optionally resistance forces
and moments from porous zones.
Usage
Example of function object specification:
\verbatim
forces1
{
type forces;
libs (forces);
...
log yes;
writeFields yes;
patches (walls);
binData
{
nBin 20;
direction (1 0 0);
cumulative yes;
}
}
\endverbatim
Forces and moments are output in their total and constituent components:
- total forces and moments
- pressure contributions
- viscous contributions
- porous resistance contributions (optional)
Where the entries comprise:
\table
Property | Description | Required | Default value
type | Type name: forces | yes |
log | Write force data to standard output | no | no
writeFields | Write the force and moment fields | no | no
patches | Patches included in the forces calculation | yes |
p | Pressure field name | no | p
U | Velocity field name | no | U
rho | Density field name (see below) | no | rho
CofR | Centre of rotation (see below) | no |
porosity | flag to include porosity contributions | no | no
directForceDensity | Force density supplied directly (see below)|no|no
fD | Name of force density field (see below) | no | fD
\endtable
Forces and moments can be computed and output in:
- the global Cartesian coordinate system (default)
- a user-defined Cartesian coordinate system
Forces and moments can also be equidistant-spatially 'binned'
over given patches. See the following link for the details:
- \link binModel.H \endlink
Bin data is optional, but if the dictionary is present, the entries must
be defined according o
Operands:
\table
nBin | number of data bins | yes |
direction | direction along which bins are defined | yes |
cumulative | bin data accumulated with incresing distance | yes |
Operand | Type | Location
input | - | -
output file | dat | $FOAM_CASE/postProcessing/\<FO\>/\<time\>/\<file\>s
output field | volVectorField | $FOAM_CASE/\<time\>/\<outField\>s
\endtable
Note
- For incompressible cases, set \c rho to \c rhoInf. You will then be
required to provide a \c rhoInf value corresponding to the free-stream
constant density.
- If the force density is supplied directly, set the \c directForceDensity
flag to 'yes', and supply the force density field using the \c
fDName entry
- The centre of rotation (CofR) for moment calculations can either be
specified by an \c CofR entry, or be taken from origin of the local
coordinate system. For example,
where \c \<file\>s:
\verbatim
CofR (0 0 0);
force.dat | Forces
moment.dat | Moments
\endverbatim
or
If a bin model is activated, additional \c \<file\>s are output:
\verbatim
origin (0 0 0);
e1 (0 1 0);
e3 (0 0 1);
forceBin.dat | Force bins
momentBin.dat | Moment bins
\endverbatim
or
where \c \<outField\>s:
\verbatim
coordinateSystem
{
origin (0 0 0);
rotation
force | Force field
moment | Moment field
\endverbatim
Usage
Minimal example by using \c system/controlDict.functions:
\verbatim
forces1
{
// Mandatory entries (unmodifiable)
type forces;
libs (forces);
// Mandatory entries (runtime modifiable)
patches (<patch1> ... <patchN>); // (wall1 "(wall2|wall3)");
// Optional entries (runtime modifiable)
directForceDensity false;
porosity false;
writeFields false;
// Conditional mandatory entries (runtime modifiable)
// Cartesian coordinate system specification when
// evaluating forces and moments, either of the below
// Option-1, i.e. the centre of rotation
// by inherently using e3=(0 0 1) and e1=(1 0 0)
CofR (0 0 0); // Centre of rotation
// Option-2, i.e. local coordinate system specification
origin (0 0 0);
e1 (1 0 0);
e3 (0 0 1); // (e1, e2) or (e2, e3) or (e3, e1)
// Option-3, i.e. general coordinate system specification
coordinateSystem
{
type axes;
e3 (0 0 1);
e1 (1 0 0);
type cartesian;
origin (0 0 0);
rotation
{
type axes;
e3 (0 0 1);
e1 (1 0 0); // (e1, e2) or (e2, e3) or (e3, e1)
}
}
}
// Conditional optional entries (runtime modifiable)
// if directForceDensity == true
fD <fDName>;
// if directForceDensity == false
p <pName>;
U <UName>;
rho <rhoName>;
rhoInf 1; // enabled if rho=rhoInf
pRef 0;
// Inherited entries
...
}
\endverbatim
where the entries mean:
\table
Property | Description | Type | Rqd | Deflt
type | Type name: forces | word | yes | -
libs | Library name: forces | word | yes | -
patches | Names of operand patches | wordList | yes | -
directForceDensity | Flag to directly supply force density <!--
--> - see below | bool | no | false
porosity | Flag to include porosity contributions | bool | no | false
writeFields | Flag to write force and moment fields | bool | no | false
CofR | Centre of rotation | vector | cndtnl | -
origin | Origin of coordinate system | vector | cndtnl | -
e3 | e3 coordinate axis | vector | cndtnl | -
e1 | e1 coordinate axis | vector | cndtnl | -
coordinateSystem | Coordinate system specifier | dictionary | cndtnl | -
fD | Name of force density field | word | cndtnl-no | fD
p | Name of pressure field | word | cndtnl-no | p
U | Name of velocity field | word | cndtnl-no | U
rho | Name of density field | word | cndtnl-no | rho
rhoInf | Value of reference density | scalar | cndtnl-yes | -
pRef | Value of reference pressure | scalar | cndtnl-no | 0
\endtable
The inherited entries are elaborated in:
- \link functionObject.H \endlink
- \link writeFile.H \endlink
- \link binModel.H \endlink
- \link coordinateSystem.H \endlink
Note
- For incompressible cases, set \c rho to \c rhoInf.
You will then be required to provide a \c rhoInf
value corresponding to the constant freestream density.
- \c writeControl and \c writeInterval entries of function
object do control when to output force and moment files.
- \c writeControl and \c writeInterval entries of \c controlDict
do control when to output force and moment fields.
- Binning is not supported for force and moment fields.
See also
Foam::functionObject
Foam::functionObjects::fvMeshFunctionObject
Foam::functionObjects::writeFile
Foam::functionObjects::timeControl
- Foam::functionObject
- Foam::functionObjects::fvMeshFunctionObject
- Foam::functionObjects::writeFile
- Foam::binModel
SourceFiles
forces.C
......@@ -164,15 +214,15 @@ class forces
{
protected:
// Protected data
// Protected Data
//- Bin model
autoPtr<binModel> binModelPtr_;
//- Pressure, viscous and porous force per bin
//- Forces per bin (i.e. pressure, viscous and porous)
List<Field<vector>> forces_;
//- Pressure, viscous and porous moment per bin
//- Moments per bin (i.e. pressure, viscous and porous)
List<Field<vector>> moments_;
//- Integrated force constituents
......@@ -186,19 +236,19 @@ protected:
// File streams
//- Forces
//- File stream for forces
autoPtr<OFstream> forceFilePtr_;
//- Moments
//- File stream for moments
autoPtr<OFstream> momentFilePtr_;
// Read from dictionary
//- Coordinate system used when evaluating forces/moments
//- Coordinate system used when evaluating forces and moments
coordSystem::cartesian coordSys_;
//- Patches to integrate forces over
//- Names of operand patches
labelHashSet patchSet_;
//- Reference density needed for incompressible calculations
......@@ -213,22 +263,22 @@ protected:
//- Name of velocity field
word UName_;
//- Name of density field (optional)
//- Name of density field
word rhoName_;
//- The name of the force density (fD) field
//- Name of force density field
word fDName_;