Specifies the gravitational body force.


AcuSolve Command


GRAVITY("name") {parameters...}


User-given name.


type (enumerated) [=none]
Type of the gravitational body force.
No gravity.
constant or const
Constant gravity. Requires gravity.
piecewise_linear or linear
Piecewise linear curve fit. Requires curve_fit_values and curve_fit_variable.
cubic_spline or spline
Cubic spline curve fit. Requires curve_fit_values and curve_fit_variable.
user_function or user
User-defined function. Requires user_function, user_values and user_strings.
gravity (array) [={0,0,0}]
The constant value of the gravity force. This array must have exactly three components in the global xyz coordinate system. Used with constant type. Note that gravity and gravitational_acceleration under EQUATION are cumulative.
curve_fit_values or curve_values (array) [={0,0,0,0}]
A four-column array of independent-variable/gravity data values. Used with piecewise_linear and cubic_spline types.
curve_fit_variable or curve_var (enumerated) [no default]
Independent variable of the curve fit. Used with piecewise_linear and cubic_spline types.
x_coordinate or xcrd
X-component of coordinates.
y_coordinate or ycrd
Y-component of coordinates.
z_coordinate or zcrd
Z-component of coordinates.
x_reference_coordinate or xrefcrd
X-component of reference coordinates.
y_reference_coordinate or yrefcrd
Y-component of reference coordinates.
z_reference_coordinate or zrefcrd
Z-component of reference coordinates.
x_velocity or xvel
X-component of velocity.
y_velocity or yvel
Y-component of velocity.
z_velocity or zvel
Z-component of velocity.
velocity_magnitude or vel_mag
Velocity magnitude.
pressure or pres
temperature or temp
eddy_viscosity or eddy
Turbulence eddy viscosity.
kinetic_energy or tke
Turbulence kinetic energy.
velocity_scale or tvel
Transition velocity scale.
dissipation_rate or teps
Turbulence dissipation rate.
eddy_frequency or tomega
Turbulence frequency.
intermittency or tintc
Transition intermittency.
transition_re_theta or treth
Transition Re-Theta.
species_1 or spec1
Species 1.
species_2 or spec2
Species 2.
species_3 or spec3
Species 3.
species_4 or spec4
Species 4.
species_5 or spec5
Species 5.
species_6 or spec6
Species 6.
species_7 or spec7
Species 7.
species_8 or spec8
Species 8.
species_9 or spec9
Species 9.
mesh_x_displacement or mesh_xdisp
X-component of mesh displacement.
mesh_y_displacement or mesh_ydisp
Y-component of mesh displacement.
mesh_z_displacement or mesh_zdisp
Z-component of mesh displacement.
mesh_displacement_magnitude or mesh_disp_mag
Mesh displacement magnitude.
mesh_x_velocity or mesh_xvel
X-component of mesh velocity.
mesh_y_velocity or mesh_yvel
Y-component of mesh velocity.
mesh_z_velocity or mesh_zvel
Z-component of mesh velocity.
mesh_velocity_magnitude or mesh_vel_mag
Mesh velocity magnitude.
user_function or user (string) [no default]
Name of the user-defined function. Used with user_function type.
user_values (array) [={}]
Array of values to be passed to the user-defined function. Used with user_function type.
user_strings (list) [={}]
Array of strings to be passed to the user-defined function. Used with user_function type.
multiplier_function (string) [=none]
User-given name of the multiplier function for scaling the viscosity. If none, no scaling is performed.


This command specifies the gravitational body force or like terms applied to the momentum equation:(1)
where ρ is the density, u is the velocity vector, p is the pressure, is the viscous stress tensor and g is the gravity vector defined here. GRAVITY commands are referenced by BODY_FORCE commands, which in turn are referenced by ELEMENT_SET commands:
GRAVITY( "my gravity" ) {
    type                               = constant
    gravity                            = { 0, -9.81, 0 }
BODY_FORCE( "my body force" ) {
    gravity                            = "my gravity"
ELEMENT_SET( "fluid with gravity" ) {
    body_force                         = "my body force"

This example defines a constant gravitational acceleration in the y direction.

A constant gravity applies a spatially uniform gravity vector to an element set, as in the above example.

Gravity models of types piecewise_linear and cubic_spline may be used to define gravity as a function of a single independent variable. For example,
GRAVITY( "curve fit gravity" ) {
    type                               = piecewise_linear
    curve_fit_values                   = { 0., 0., 0., 0. ;
                                          10., 0., 0., -1. ;
                                          20., 0., 0., 0. ; }
    curve_fit_variable                 = x_coordinate

defines a gravity force in the z direction as a function of the x coordinate. The curve_fit_values parameter is a four-column array corresponding to the independent variable and the x, y, and z components of gravity in the global xyz coordinate system. The independent variable values must be given in ascending order. The limit point values of the curve fit are used when curve_fit_variable falls outside of the curve fit limits.

The curve_fit_values data may be read from a file. For the above example, the curve fit values may be placed in a file, say
0.       0.        0.        0.
10.       0.        0.       -1.
20.       0.        0.        0.
and read by:
GRAVITY( "curve fit gravity" ) {
    type                               = piecewise_linear
    curve_fit_values                   = Read( "" )
    curve_fit_variable                 = x coordinate

A gravity of type user_function may be used to model more complex behaviors; see the AcuSolve User-Defined Functions Manual for a detailed description of user-defined functions.

For example, consider the case where gravity is a linear function of species 1 and species 2. Then the input command may be given by:
GRAVITY( "UDF gravity" ) {
    type                               = user_function
    user_function                      = "usrGravityExample"
    user_values                        = { 1., 1.5 } # proportionality constants
where the user-defined function "usrGravityExample" may be implemented as follows:
#include "acusim.h"
#include "udf.h"

UDF_PROTOTYPE( usrGravityExample ) ;                              /* function prototype               */

Void usrGravityExample (
   UdfHd                udfHd,                                    /* Opaque handle for accessing data */
   Real*                outVec,                                   /* Output vector                    */
   Integer              nItems,                                   /* Number of elements               */
   Integer              vecDim                                    /* = 3 (for three components)       */
) {
   Integer              elem ;                                    /* an element counter               */
   Real                 coef1 ;                                   /* scaling factor 1                 */
   Real                 coef2 ;                                   /* scaling factor 2                 */
   Real*                spec ;                                    /* species vector                   */
   Real*                spec1 ;                                   /* species 1 vector                 */
   Real*                spec2 ;                                   /* species 2 vector                 */
   Real*                usrVals ;                                 /* user values                      */
   Real*                xGrav ;                                   /* x-component of gravity           */
   Real*                yGrav ;                                   /* y-component of gravity           */
   Real*                zGrav ;                                   /* z-component of gravity           */

   udfCheckNumUsrVals( udfHd, 2 ) ;                               /* check for error                  */
   usrVals              = udfGetUsrVals( udfHd ) ;                /* get the user vals                */
   coef1                = usrVals[0] ;                            /* get coef. 1                      */
   coef2                = usrVals[1] ;                            /* get coef. 2                      */
   spec                 = udfGetElmData( udfHd, UDF_ELM_SPECIES ) /* get the user vals                */
   spec1                = &spec[0*nItems] ;                       /* localize species1                */
   spec2                = &spec[1*nItems] ;                       /* localize species2                */
   xGrav                = &outVec[0*nItems] ;                     /* localized xGrav                  */
   yGrav                = &outVec[1*nItems] ;                     /* localized yGrav                  */
   zGrav                = &outVec[2*nItems] ;                     /* localized zGrav                  */
   for ( elem = 0 ; elem < nItems ; elem++ ) {
         xGrav[elem] = coef1 * spec1[elem] + coef2 * spec2[elem] ;
         yGrav[elem] = 0 ;
         zGrav[elem] = 0 ;
} /* end of usrGravityExample() */

The dimension of the returned gravity vector, outVec, is the number of elements times three.

The multiplier_function parameter may be used to uniformly scale all gravity values. The value of this parameter refers to the user-given name of a MULTIPLIER_FUNCTION command in the input file; see the MULTIPLIER_FUNCTION command for an example.

Note that, for thermal problems with the Boussinesq approximation, the gravity is scaled by the product of the expansivity and the temperature minus reference temperature; see the DENSITY_MODEL command for more details.