### 18.5.2. Data Acquisition Routines

#### 18.5.2.1. USER_GETVAR

The main application for `USER_GETVAR` is to provide derived variables, which are not accessible with CEL or operations on primitive and derived variables, and to provide material properties data. `USER_GETVAR` can be called from within user CEL functions to obtain a pointer to the latest solution fields for the locations on which the subroutine is currently operating. Note that USER_GETVAR obtains or computes its own copy of the data, and the returned pointer cannot be used to change the value of the solution fields. Note also that USER_GETVAR is not relevant to junction box routines.

Calls to USER_GETVAR have the following form:

          CALL USER_GETVAR('<VARIABLE_DESCRIPTION>',CRESLT,
         &                   <pVAR>,CZ,DZ,IZ,LZ,RZ)

where the arguments in the argument list are as follows:

- `<VARIABLE_DESCRIPTION>`: name of the variable for which `USER_GETVAR` is called, following the naming convention:

  `[<Field A>].[<Field B>].<Field C>.[<Field D>]`

  where:

  Field | Description
  --- | ---
  A | A valid name of one of the following objects: `FLUID`, `SOLID`, `FLUID PAIR`, or `MUSIG FLUID`
  B | A valid name of one of the following objects: `COMPONENT`, `SIZE GROUP`, `REACTION`
  C | A valid name of one of the following objects: `VARIABLE`, `ADDITIONAL VARIABLE`
  D | One of the following variable operators: `Magnitude`, `Gradient`, `Curl`, `Laplacian`, `Time Derivative`, `Transient Minimum`, `Transient Maximum`, `Transient Std Deviation`, `Transient RMS`, `Transient Average`, `Boundcon`, `magnitude`, `grad`, `curl`, `laplacian`, `dt`, `Trnmin`, `Trnmax`, `Trnsdv`, `Trnrms`, `Trnavg`, `hybrid`

  Note: The Laplacian operator does not work in `USER_GETVAR` in some situation.

  You should always add the fluid name even though, in some cases such as for the variable `Pressure`, it is not strictly necessary. The fluid name is required when specifying a phase-specific variable (in a multiphase case) and when specifying an algebraic Additional Variable (even for a single-phase case).

  The names are case sensitive. You can use long variable names (for example, Pressure) or short names as they appear in CEL (for example, p).

  You can also request whole vector and tensor entities (for example, `Air at STP.Velocity`) as well as components of these variables (for example, `Air at STP.Velocity u`).

  Examples:

  - `Pressure`: is the fluid pressure. Notice that no fluid tag is required.

  - `Pressure.Gradient`: is the pressure gradient in the fluid.

  - `Water at RTP.Density`: is the density of fluid `Water at RTP`

  - `Air.Nitrogen.Mass Fraction`: is the mass fraction of component `Nitrogen` in the multi-component fluid `Air`

  - `Water.Pollutant.Mass Fraction.Gradient`: is the gradient of the variable `Water.Pollutant.Mass Fraction`

  - `MyMusigFluid.Group1.Size Fraction`: is the size fraction of size group `Group1` in the MUSIG fluid `MyMusigFluid`

  - `Mixture.CO Oxidation.Molar Reaction Rate`: is the molar reaction rate of the reaction `CO Oxidation` in the reacting fluid `Mixture`.

- `CRESLT`: returned result key word containing the status of the `USER_GETVAR` call. After a successful call to `USER_GETVAR`, this variable will be `CRESLT='GOOD'`. The possible return codes are:

  CRESLT | Description
  --- | ---
  BADL | Variable cannot be computed on the current LOCALE
  CIRC | Variable has a circular reference
  CVAR | Variable solver name is not valid
  ENTY | Variable cannot be compute on the current ENTITY
  GOOD | Variable was successfully computed
  NAME | Variable user name is not valid
  RECP | Variable is valid but CFX-Solver could not find a formula to evaluate the variable
  IGET | Variable is valid and a formula exists, but the recipe could not be computed

  This variable MUST be checked after every call to USER_GETVAR and verify that is equal to GOOD; otherwise, there has been a failure and the caller should continue or stop at his/her discretion.

- `<pVAR>`: stack pointer to the variable if the call was successful. Otherwise, its value is undefined and will result in a segmentation violation if used.

- `CZ,DZ,IZ,LZ,RZ`: stacks.

For example:

          CALL USER_GETVAR('Water at RTP.Pressure.Gradient',CRESLT,
         &                 pPGRADIENT,CZ,DZ,IZ,LZ,RZ)
          IF (CRESLT.NE. 'GOOD') STOP

Depending on the locale, the gradients are provided as vertex gradients (for example, for initial conditions `LOCALE='VERTICES'`), element averaged gradients (for example, for source terms `LOCALE='IELGn'`) or face averaged gradients (for example, for boundary conditions `LOCALE='BELGn'`). For `'IELGn'` and `'BELGn'`, `USER_GETVAR` gathers the specified variable to the vertices of the `IELG` or `BELG` and then use the shape functions to calculate the gradients.

The following restrictions apply to the use of gradients or curls:

- Gradients (or Curl) on `'VERTICES'` are approximate at wall boundaries. This is because wall values are taken from the interior.

- The normal component of gradients on `'VERTICES'` is always zero on symmetry planes.

##### 18.5.2.1.1. Boundcon Operator

The “Boundcon” operator enables you to pick up boundary condition data for transport variables on boundary locales when applicable. By default, `USER_GETVAR` modifies the entity on a boundary locale to ensure that data can be obtained from the solution field, or a recipe if relevant. The use of this operator is targeted at experts as the precise effect is boundary condition, variable and equation dependent.

##### 18.5.2.1.2. Variable Shape and Dimensions

The shape of the returned variable depends on the variable type and specified operation. The following syntax is used for non-gradients:

    VAR(NCOMPT,NLOC)

with

- `NCOMPT`: number of tensor components of the variable. This is 1 for a scalar, 3 for a vector and 6 for a symmetric rank two tensor.

- `NLOC`: dimension of the locale.

For gradients and curls, the gradient/curl components appear first, with the tensor components appearing at the end, as follows:

    VAR(NGRAD,NLOC,NCOMPT)

with

- `NGRAD` = 3: number of gradient components in the result.

- `NLOC`: dimension of the locale.

- `NCOMPT`: number of tensor components of the variable. This is 1 for a scalar, 3 for a vector and 6 for a symmetric rank two tensor.

This leads to the following definitions:

- Scalar variable: `RZ(pVAR)` points to a variable `VAR(NLOC)`.

- Vector variable: `RZ(pVAR)` points to a variable `VAR(3,NLOC)`.

- Gradient of a scalar variable: `RZ(pVAR)` points to a variable `VAR(3,NLOC)`.

- Gradient of a vector variable: `RZ(pVAR)` points to a variable `VAR(3,NLOC,3)`.

The locale is always the locale for which the User CEL routine is called. It is not possible to call `USER_GETVAR` for non-local information (for example, using the face gradients on `BOUNDARY:Inlet` for the boundary condition specification of a variable on `BOUNDARY:Outlet`).

#### 18.5.2.2. USER_GET_GVAR

This utility enables the integrated global quantities, normally used in CEL, to be used from User Fortran. For example, one could obtain the mean pressure (over all partitions in the case of a parallel run).

Note: This utility may fail in parallel, if the utility routine is not called on every partition.

The integrated function notation used is similar to that in CEL. USER_GET_GVAR may be called from user CEL or junction box routines. However, note the following differences in its operation in these two contexts:

- When called from a junction box, the requested integrated quantity is recalculated.

- When called from a User CEL routine, the requested integrated quantity is recalculated only if it has not previously been calculated and saved. If it has previously been calculated and saved, then the previously calculated value is returned.

These differences in operation are due to parallel processing issues. It is safe to recalculate on junction boxes, as all parallel processes are synchronized in that case. However, user CEL routines are used during local assembly, where it is not possible to recompute global quantities in parallel. If such a quantity is requested from a user CEL routine during a parallel run, the code may hang. For this reason, it is recommended that you call USER_GET_GVAR only from junction box routines. For user CEL routines, it is better practice to obtain the required global quantities from call back routines in CEL, and pass these as arguments to the user CEL routine. An alternative workaround is also to call the required global quantity from a junction box that is called once per coefficient loop. It is then safe to request the quantity from user CEL.

Examples of the use of USER_GET_GVAR are available in User Junction Box Examples.

          SUBROUTINE USER_GET_GVAR (USER_VAR, USER_LOC, USER_OPER,
         &                       CRESLT, VAR, CZ,DZ,IZ,LZ,RZ)
    C
    CI USER_VAR:  User Name of variable or phase
    CI USER_LOC:  User Location.
    CI USER_OPER: Operation. e.g. 'maxVal'
    C
    CO CRESLT: Result, e.g. ‘GOOD’, ‘ERR’

Depending on the operation requested, USER_VAR may be specified as follows:

- USER_VAR = user variable name, for example, ‘Water at RTP.Temperature’

- USER_VAR = ‘ ‘ (blank), for example, for USER_OPER = ‘area’.

Depending on the operation requested, USER_LOC may specified as follows:

- USER_LOC = domain name, for example, ‘duct’

- USER_LOC = subdomain name, for example, ‘heated region’

- USER_LOC = boundary condition name, for example, ‘inlet’.

Allowed operations are tabulated and described below, together with allowed variable and location types.

USER_OPER | Allowed USER_VAR | Allowed USER_LOC | Description
--- | --- | --- | ---
area | blank | Any 2D region (such as a boundary or interface) | Area of a boundary or interface.
area_x area_y area_z | blank | Any 2D region (such as a boundary or interface) | The component of the normal area vector in the X, Y, or Z direction.
areaAve | variable | Any 2D region (such as a boundary or interface) | Area-weighted average of the variable on a 2D region.
areaInt | variable | Any 2D region (such as a boundary or interface) | Area-weighted integral of the variable over a 2D region.
ave | variable | Any 3D region (such as a domain or subdomain) | Arithmetic average of the variable within a 3D region.
force | blank | Any 2D region (such as a wall) | The magnitude of the force vector on a boundary[ 1 ].
force_x force_y force_z | blank | Any 2D region (such as a wall) | The component of the force vector in the X, Y, or Z direction[ 1 ].
mass | blank | Any 3D region (such as a domain or subdomain) | The total mass within a 3D region. This is fluid dependent.
massAve | variable | Any 3D region (such as a domain or subdomain) | Mass-weighted average of the variable on a 3D region.
massInt | variable | Any 3D region (such as a domain or subdomain) | The mass-weighted integration of the variable within a 3D region.
massFlow | blank | Any fluid surfaces (such as inlets and outlets) | Mass flow through a fluid surface.
massFlowAve | variable | Any fluid surfaces (such as inlets and outlets) | Mass flow weighted average of the variable on a fluid surface.
massFlowAveAbs | variable | Any fluid surfaces (such as inlets and outlets) | Absolute mass flow weighted average of the variable on a fluid surface.
massFlowInt | variable | Any fluid surfaces (such as inlets and outlets) | Mass flow weighted integration of the variable on a fluid surface.
maxVal | variable | Any 3D region (such as a domain or subdomain) | Maximum value of the variable within a 3D region.
minVal | variable | Any 3D region (such as a domain or subdomain) | Minimum value of the variable within a 3D region.

rbstate

variable long name for a rigid body state variable

The rigid body state variables are:

- `Position`,

  `Position X`,

  `Position Y`,

  `Position Z`

- `Linear Velocity`,

  `Linear Velocity X`,

  `Linear Velocity Y`,

  `Linear Velocity Z`

- `Linear Acceleration`,

  `Linear Acceleration X`,

  `Linear Acceleration Y`,

  `Linear Acceleration Z`

- `Euler Angle X`,

  `Euler Angle Y`,

  `Euler Angle Z`

- `Angular Velocity`,

  `Angular Velocity X`,

  `Angular Velocity Y`,

  `Angular Velocity Z`

- `Angular Acceleration`,

  `Angular Acceleration X`,

  `Angular Acceleration Y`,

  `Angular Acceleration Z`

For variables that do not include an axis name, the magnitude of the vector is returned. For example, if the variable is `Position`, the distance from the origin is returned.

Any rigid body object or any immersed solid domain that is governed by a rigid body solution.

Returns the position/velocity/acceleration or orientation/angular velocity/angular acceleration (or axis components of these) of a rigid body object or immersed solid that is governed by a rigid body solution. These quantities are with respect to the global coordinate frame.

rmsAve | variable | Any 2D region (such as a boundary or interface) | RMS average of the variable within a 2D region
sum | variable | Any 3D region (such as a domain or subdomain) | Sum of the variable over all 3D region vertices.
torque | blank | Any 2D region (such as a wall) | Magnitude of the torque vector on a 2D region.
torque_x torque_y torque_z | blank | Any 2D region (such as a wall) | Magnitude of the torque vector in the X, Y, or Z direction.
volume | blank | Any 3D region (such as a domain or subdomain) | The total volume of a 3D region.
volumeAve | variable | Any 3D region (such as a domain or subdomain) | Volume-weighted average of the variable on a domain.
volumeInt | variable | Any 3D region (such as a domain or subdomain) | Volume-weighted integration of the variable within a domain or subdomain.

1. When restarting from an initial value file, USER_GET_GVAR will return only the normal part of the force when called before or at the start of the first iteration (the first coefficient loop of the first timestep for a transient simulation). For all subsequent iterations the force returned will include both the normal and the tangential parts, that is, the solution converges to the correct result. The restart kink can be resolved by setting expert parameter "read boundary flows = t".

##### 18.5.2.2.1. USER_GET_GVAR with Multiphase Flow

If the USER_OPER is fluid-specific, various behaviors are possible depending on the USER_OPER type:

- For `massFlow` and `massFlowAve`, if the fluid prefix is not specified for the USER_OPER, then the bulk mass flows will be used

- For other fluid-specific functions, if a fluid-specific variable is specified and no fluid is specified for the USER_OPER, then the fluid specified for the variable will be assumed for the USER_OPER as well.

- For a fluid-specific USER_OPER that is specified, with a variable that is fluid-specific, and no fluid is specified for the variable, then the fluid specified for the USER_OPER will be assumed for the variable as well.

- If either the USER_OPER or variable are fluid-specific, and a prefix is not given for either, the solver will stop with an error.

USER_GET_GVAR multiphase examples are shown in the following table:

CEL Function | USER_OPER | USER_VAR | USER_LOC | Behavior
--- | --- | --- | --- | ---
`massFlow()@inlet` | massFlow | blank | inlet | Bulk mass flow rate through inlet
`Air.massFlow()@inlet` | Air.massFlow | blank | inlet | Air mass flow rate through inlet
`massFlowAve(p)@inlet` | massFlowAve | p | inlet | Bulk mass flow averaged pressure on inlet
`Air.massFlowAve(p)@inlet` | Air.massFlowAve | p | inlet | Air mass flow averaged pressure on inlet
`massFlowAve(vf)@inlet` | massFlowAve | vf | inlet | Error because no fluid specified
`massFlowAve(Air.vf)@inlet` | massFlowAve | Air.vf | inlet | Bulk mass flow averaged air volume fraction on inlet
`Air.massFlowAve(Air.vf)@inlet` | Air.massFlowAve | Air.vf | inlet | Air mass flow averaged air volume fraction on inlet
`Air.massFlowAve(vf)@inlet` | Air.massFlowAve | vf | inlet | Same as Air.massFlowAve(Air.vf) @ inlet

#### 18.5.2.3. USER_CALC_INFO

A simple routine, `USER_CALC_INFO` is provided for obtaining mesh locale information from within any user CEL function (it is not available from within junction box routines).

          SUBROUTINE USER_CALC_INFO (WHO,ACTION,CVAR,LOCALE,ENTITY,WHEN,
         & CALIAS,CERACT,CRESLT,
         & CZONE,ILOCS,ILOCF,IENTS,IENTF,
         & CZ,DZ,IZ,LZ,RZ)
    C
    CD Controls setting and getting of user data area and locale info.
    C
    CO WHO          : Name of routine making original call to GETVAR.
    CI ACTION       : 'SET', 'GET' & 'RELEASE'
    CO CVAR         : Solver Name of variable to be calculated by CEL call.
    CO LOCALE       : Solver Locale (vertices, elements, element set etc.)
    CO ENTITY       : Solver Entity (for element locales: integration point, etc.)
    CO WHEN         : The time & iteration for evaluation.
    CO CALIAS          : External variable name. Usually user provided for mass
    C                     :  fractions and additional variables.
    CO CERACT       : Action to be taken on an error occurring.
    CO CRESLT       : Result of attempt to calculate variable.
    CO CZONE        : Zone (if known) as context for AV links.
    CO ILOCS        : Number of first item of locale type (e.g. vertex or
    C                 element).
    CO ILOCF        : Number of last item of locale type.
    CO IENTS        : Number of first item of entity type (e.g. integration pt.)
    CO IENTF        : Number of last item of entity type.
    C                 For vertices, or ALL elements, IENTS=IENTF=1

This routine should be called only with `ACTION` set to `'GET'`. Each argument is then set with the data described above. The arguments can be declared as follows in the calling routine:

          CHARACTER*(MXDNAM) WHO, ACTION, CVAR, LOCALE, ENTITY, WHEN, CZONE
          CHARACTER*(120) CALIAS
          CHARACTER*(4) CERACT, CRESLT
          INTEGER ILOCS, ILOCF, IENTS, IENTF

Note that for `ACTION='GET'`, all other arguments are returned with output values, even `CERACT`, which in all other situations would be expected to be an input argument. Hence, do not attempt to code constant values for any arguments, except for `ACTION`.

Allowed solver LOCALE names are listed and described in the table below. m, n denote arbitrary integers:

LOCALE | Description
--- | ---
ZNm | zone m = domain m
VLm | volume m
VPm | volume patch m = subdomain m = a union of elementary volumes
VERTICES | all vertices on a zone
ELEMENTS | all elements on a zone
ELSm | element set m = set of elements of a fixed logical type
IELGm | interior element group m (a contiguous subset of an element set)
BCPm | boundary condition patch (BCP) m (a set of faces belonging to a boundary condition)
FCSm | face set m (a subset of a BCP consisting of faces of fixed logical type)
BELGm | boundary element group m = (a subset of elements of fixed logical type, coincident with a face set)

Allowed Solver ENTITY names are listed and described in the table below. m, n denote arbitrary integers:

ENTITY | Description
--- | ---
‘ ‘ | not specified, for example, if LOCALE = ‘VERTICES’
CENTRE = CENTER | centroids, for example, of elements on an element group, faces on a face set.
VXEL | element vertices, for example, on an interior or boundary element group.
IP | integration points, for example, on an interior or boundary element group.

#### 18.5.2.4. USER_GET_MESH_INFO

This subroutine stores useful geometric and mesh related scalar data under a directory named '/USER/'//CDIR. It does so by looking inside /FLOW/GEOMETRY/ and /FLOW/MESH/, and copying required data. It is available in user CEL and junction box routines.

    ------SUBROUTINE USER_GET_MESH_INFO (WHO,ACTION,CERACT,
         &                    WHEN,CZONE,LOCALE,CDIR,CRESLT,
         &                    CZ,DZ,IZ,LZ,RZ)
    CI WHO          : Name of routine making original call.
    CI ACTION       :’GET’ & ’DELETE’
    CI CERACT       : Error Action = ’STOP’, ’WARN’, ’SKIP’.
    CI WHEN         ; Only ’LATEST’ supported at present.
    CI CZONE        : Solver Zone Name   (blank for global information only)
    CI LOCALE       : Locale Name (blank for zonal  information only)
    CV CDIR         : Subdirectory name of /USER into which to put info.
    CO CRESLT       : Result = ‘GOOD’, ‘ERR’ or ‘DIR’.

The arguments are of type:

          CHARACTER*(*) WHO,ACTION,CEARCT,WHEN,CZONE,LOCALE,CDIR
          CHARACTER*(4) CRESLT

There are two ways in which you can choose a name for a directory under which to place the data. Either:

- Create a directory named CDIR below /USER, and pass the name down as an argument to USER_GET_MESH_INFO. In this case, the requested information is placed in the specified directory. For more information, see CFX Memory Management System (MMS) and Directories.

- Alternatively, if CDIR does not exist under /USER/, for example CDIR = ‘ ‘, when passed down to USER_GET_MESH_INFO, then the program generates a name for a directory in which to place the data. The generated name is of the form MESH_INFO/Czone/Locale/. This directory name will be passed back in the argument CDIR.

If you choose the second alternative, then CDIR must be declared to be sufficiently long to hold this directory name. If not, then an error is generated, and CRESLT = ‘DIR’ is returned.

Setting ACTION = ‘GET’ copies required data into the specified directory name. Setting ACTION = ‘DELETE’ deletes the directory. The data under CDIR can be subsequently obtained using the PEEK facilities. For details, see:

- CFX Memory Management System (MMS)

- Setting and Reading Individual Values.

Examples of use of USER_GET_MESH_INFO are available. For details, see USER_GET_MESH_INFO.

The data copied depends on your setting of CZONE and LOCALE as follows.

##### 18.5.2.4.1. Global Mesh Information: CZONE = ‘ ‘, LOCALE = ‘ ‘

If you specify blank zone and locale names, it is assumed that you require global mesh data. The information stored under CDIR is tabulated below:

Variable Name | Variable Type | Description
--- | --- | ---
NZN | INTEGER | total number of zones = domains
CZONE(NZN) | CHARACTER * (MXDNAM) | character array containing internal solver names of zones (These are of the form ‘ZNm’, m = integer.)
NVX | INTEGER | total number of vertices
NEL | INTEGER | total number of elements
NELS | INTEGER | total number of element sets
NIELG | INTEGER | total number of internal element groups
NBELG | INTEGER | total number of boundary element groups

##### 18.5.2.4.2. Zonal Information: CZONE = ‘ZNm’, LOCALE = ‘ ‘

If you specify a valid solver zone name, and a blank locale name, then it is assumed that you require mesh data specific to that zone. The information stored under CDIR is tabulated below:

Variable Name | Variable Type | Description
--- | --- | ---
PHYTYPE | CHARACTER * (MXDNAM) | zone physical type = ‘FLUID’ or ‘SOLID’
IZN | INTEGER | zone number
NDIM | INTEGER | number of spatial dimensions
NVL | INTEGER | number of volumes
NVP | INTEGER | number of volume patches = subdomains.
NSF | INTEGER | number of surfaces
NSP | INTEGER | number of surface patches
NBCP | INTEGER | number of boundary condition patches
CBCP(NBCP) | CHARACTER * (MXDNAM) | character array containing internal solver names of boundary condition patches. (These are of the form ‘BCPm’, m = integer.)
CVP(NVP) | CHARACTER * (MXDNAM) | character array containing internal solver names of volume patches = subdomains. (These are of the form ‘VPm’, m = integer.)
NVX | INTEGER | total number of vertices on this zone
NEL | INTEGER | total number of elements on this zone
NELS | INTEGER | total number of element sets on this zone
NIELG | INTEGER | total number of internal element groups on this zone
NBELG | INTEGER | total number of boundary element groups on this zone

##### 18.5.2.4.3. Boundary Condition Patch Information: CZONE = ‘ZNm’, LOCALE = ‘BCPn‘

If you specify a valid solver zone name, and a valid Boundary Condition Patch (BCP) name, then it is assumed that you require mesh data specific to that BCP. The information stored under CDIR is tabulated below:

Variable Name | Variable Type | Description
--- | --- | ---
PHYTYPE | CHARACTER * (MXDNAM) | BCP physical type = ‘INLET’ or ‘OUTLET’, ‘OPENING’, ‘WALL’, ‘SYMMETRY’, ‘PERIODIC’, ‘INTERFACE’
IBCP | INTEGER | boundary condition patch number

###### 18.5.2.4.3.1. Face Set Information: CZONE = ‘ZNm’, LOCALE = ‘FCSn‘

If you specify a valid solver zone name and a valid face set name, then it is assumed that you require mesh data specific to that face set. The information stored under CDIR is tabulated below:

Variable Name | Variable Type | Description
--- | --- | ---
CBCP | CHARACTER * (MXDNAM) | name of BCP to which the face set belongs
IBCP | INTEGER | number of BCP to which the face set belongs
ISFC_S | INTEGER | starting set face number for this face set
ISFC_F | INTEGER | finishing set face number for this face set

###### 18.5.2.4.3.2. Element Set or Element Group Information: CZONE = ‘ZNm’, LOCALE = ‘ELSn‘ or ‘IELGn‘ or ‘BELGn‘

If you specify a valid solver zone name, and a valid element set name, or element group name, then it is assumed that you require mesh data specific to that element set or element group. The information stored under CDIR is tabulated below:

Variable Name | Variable Type | Description
--- | --- | ---
IELS | INTEGER | element set number for an element set or interior element group = 0 for a boundary element group
IELG | INTEGER | interior element group number = 0 if not an interior element group
BELG | INTEGER | boundary element group number = 0 if not a boundary element group
NVXEL | INTEGER | number of vertices per element.
NFCEL | INTEGER | number of faces per element
NIPEL | INTEGER | number of integration points per element
IP1 | INTEGER | starting integration point number
IP2 | INTEGER | finishing integration point number
ISEL_S | INTEGER | starting set element number for an element set or an interior element group
ISEL_F | INTEGER | finishing set element number for an element set or an interior element group
ISFC_S | INTEGER | starting set face number for a boundary element group
ISFC_F | INTEGER | finishing set face number for a boundary element group

#### 18.5.2.5. USER_GET_MESHDATA

This routine is similar to `USER_GETVAR`, in that it obtains arrays containing mesh related data. The subroutine looks for the requested variable on the `/FLOW/MESH` stack, and returns a pointer to it, and its size.

          SUBROUTINE USER_GET_MESHDATA (WHAT,WHERE,CACTION,CERACT,CRESLT,
         &                              NVAR,pVAR, CZ,DZ,IZ,LZ,RZ)
    CI WHAT     : User name of variable.
    CI WHERE    : User name of locale.
    CI CACTION : Action = 'RETURN' or 'RELEASE'
    CI CERACT  : Error action = 'STOP', 'SKIP' or 'WARN'
    CO CRESLT  : Result of attempt to get variable, e.g. ’GOOD’ or ‘BADL’
    CO pVAR     : Address in stack for the result.
    CO NVAR     : Number of words in stack used for the variable.

The arguments are of type:

          CHARACTER*(*) WHAT, WHERE, CACTION, CERACT, CRESLT
          INETEGER NVAR
          __stack_point__ pVAR

USER_GET_MESHDATA is available only in user CEL routines. Also, the range of obtainable arrays depends on the current solver locale, which may be determined by a prior call. For details, see USER_CALC_INFO. If you try to access a variable on an invalid solver locale, then USER_GET_MESH_INFO returns CRESLT = ‘BADL’.

The table below lists permitted user mesh variable names and locations, and the permitted solver locales on which they may be obtained. It also describes the name, type, and shape of the associated solver variable that is returned. A description of the integer variables defining the array shape is available in USER_GET_MESH_INFO. The values of these variables may be obtained by a prior call to USER_GET_MESH_INFO.

Note that, unlike USER_GETVAR, this routine returns a pointer to the actual solver array, not a copy of it.

WHAT | WHERE | Permitted Solver Locales | Solver Array Shape | Variable Type | Description
--- | --- | --- | --- | --- | ---
Coordinates | Vertices | Any | Crdvx (NDIM, NVX) | REAL | Coordinates of mesh vertices
Coordinates | Integration Points | ELS*, IELG*, BELG* | CrdIp (ISEL_S:ISEL_F, NDIM, IP1:IP2) | REAL | Coordinates of integration points
Coordinates | Faces | BELG* | CrdFc (ISFC_S:ISFC_F, NDIM) | REAL | Coordinates of faces
Volume | Vertices | Any | ContVol (NVX) | REAL | Control cell volumes
Volume | Elements | ELS*, IELG*, BELG* | VolEl (ISEL_S:ISEL_F) | REAL | Element volumes
Volume | Sectors | ELS*, IELG*, BELG* | VolSec (ISEL_S:ISEL_F, NVxEl) | REAL | Control cell sector volumes
Area | Faces | FCS*, BELG* | ArFc (ISFC_S:ISFC_F) | REAL | Areas of faces
Area | Integration Points | BELG* | ArIp (ISFC_S:ISFC_F, IP1:IP2) | REAL | Areas of sectors surrounding boundary integration points
Normal Area Vector | Integration Points | ELS*, IELG*, BELG* | NarvIp (ISEL_S:ISEL_F, NDIM, IP1:IP2) | REAL | Inward-directed normal area vectors at integration points
Normal Area Vector | Faces | BELG* | NarvFc (ISFC_S:ISFC_F, NDIM) | REAL | Inward-directed normal area vectors at faces
Normal Unit Vector | Integration Points | IELS*, IELG*, BELG* | NunvIp (ISEL_S:ISEL_F, NDIM,IP1:IP2) | REAL | Inward-directed normal unit vector at integration points
Normal Unit Vector | Faces | BELG* | NunvIp (ISFC_S:ISFC_F, NDIM) | REAL | Inward-directed normal unit vector at faces
Near Wall Distance | Elements | BELG* | NWDIST (ISFC_S:ISFC_F) | REAL | Distance from element centroid to wall
Element-to-vertex Connectivity | Elements | ELS*, IELG*, BELG* | KVxEl (ISEL_S:ISEL_F, NVxEl) | INTEGER | List of vertex numbers connected to each element

Note: Before Release 17.0, a call to Fortran routine `USER_GET_MESHDATA` to get the near-wall distance would return the near-wall distance multiplied by a constant. The value of the constant depended on the choice of turbulence model. Starting with Release 17.0, a call to `USER_GET_MESHDATA` to get the near wall distance returns the (unmodified) near-wall distance. Note that the near-wall distance is evaluated as the distance from an element’s centroid to a boundary face, measured normal to the boundary face.

#### 18.5.2.6. USER_GET_PHYS_INFO

This routine gets physics information on zones and phases, and stores under the `/USER` data area. This subroutine stores useful physical model data under a directory named '/USER/'//CDIR. It does so by looking inside `/FLOW/PHYSICS/`, and copying required data. It is available in user CEL and junction box routines.

          SUBROUTINE USER_GET_PHYS_INFO (WHO,ACTION,CERACT,
         &                    WHEN,CZONE,CPHASE,CDIR,CRESLT,
         &                    CZ,DZ,IZ,LZ,RZ)
    CI WHO          : Name of routine making original call.
    CI ACTION       :’GET’ & ’DELETE’
    CI CERACT       : Error Action = ’STOP’, ’WARN’, ’SKIP’.
    CI WHEN         ; Only ’LATEST’ supported at present.
    CI CZONE        : Zone Name
    CI CPHASE       : Phase Name (blank for zonal information only)
    CV CDIR         : Subdirectory name of /USER into which to put info.
    CO CRESLT       : Result = ‘GOOD’, ‘ERR’ or ‘DIR’.

The arguments are of type:

          CHARACTER*(*) WHO,ACTION,CERACT,WHEN,CZONE,CPHASE,CDIR
          CHARACTER*(4) CRESLT

There are two ways in which you can choose a name for a directory under which to place the data. Either:

- Create a directory named CDIR below /USER, and pass the name down as an argument to USER_GET_PHYS_INFO. In this case, the requested information is placed in the specified directory. For more information, see CFX Memory Management System (MMS) and Directories.

- Alternatively, if CDIR does not exist under /USER/, for example CDIR = ‘ ‘, when passed down to USER_GET_PHYS_INFO, then the program generates a name for a directory in which to place the data. The generated name is of the form PHYS_INFO/Czone/Locale/. This directory name will be passed back in the argument CDIR.

If you choose the second alternative, then CDIR must be declared to be sufficiently long to hold this directory name. If not, then an error is generated, and CRESLT = ‘DIR’ is returned.

Setting ACTION = ‘GET’ copies required data into the specified directory name. Setting ACTION = ‘DELETE’ deletes the directory. The data under CDIR can be subsequently obtained using the PEEK facilities. For details, see:

- CFX Memory Management System (MMS)

- Setting and Reading Individual Values.

Examples of use of USER_GET_PHYS_INFO are available in the Junction Box 2 example. For details, see Junction Box Example 2: Integrated Residence Time Distribution.

The information copied depends on your setting of CZONE and CPHASE, as described below.

##### 18.5.2.6.1. Zonal Information: CZONE = ‘ZNm’, CPHASE = ‘ ‘

If you specify a valid solver zone name, and a blank phase name, then it is assumed that you require physical data specific to that zone. The information stored under CDIR is tabulated below:

Variable Names | Variable Type | Description
--- | --- | ---
PHYTYPE | CHARACTER * (MXDNAM) | zone physical type = ‘FLUID’ or ‘SOLID’
IZN | INTEGER | zone number
NPHASE | INTEGER | number of phases defined on the zone
PREF | REAL | reference pressure
TREF | REAL | reference temperature
GX, GY, GZ | REAL | components of gravity vector
CPHASE (NPHASE) | CHARACTER * (MXDNAM) | character array containing internal solver names of phases; of the form ‘FLm’, or ‘SLm’, m = integer, for fluid and solid phases respectively
CPP(NPP) | CHARACTER * (MXDNAM) | character array containing internal solver names of phase pairs; of the form ‘PPm’, m = integer

##### 18.5.2.6.2. Phase Information: CZONE = ‘ZNm’, CPHASE = ‘FLm‘ or ‘SLm’

If you specify a valid solver zone name, and a valid phase name, then it is assumed that you require physical data specific to that phase on that zone. The information stored under CDIR is tabulated below:

Variable Names | Variable Type | Description
--- | --- | ---
IPHASE | INTEGER | phase number
CMAT | CHARACTER * (MXDNAM) | internal solver name of material associated with this phase; of the form ‘MTm’, m = integer
CTURBM | CHARACTER * (MXDNAM) | internal solver name of turbulence model associated with this phase
CHEATM | CHARACTER * (MXDNAM) | internal solver name of beat transfer model associated with this phase
CBUOYM | CHARACTER * (MXDNAM) | internal solver name of buoyancy model associated with this phase
CCOMBM | CHARACTER * (MXDNAM) | internal solver name of combustion model associated with this phase
MORPHOLOGY | CHARACTER * (MXDNAM) | internal solver name of morphology associated with this phase

The table below translates internal solver names for physical models:

Variable Names | Variable Value | Description
--- | --- | ---
CTURBM | ‘ ’ | Laminar
CTURBM | ‘EVM:ALG:CX’ | Baldwin-Lomax
CTURBM | ‘EVM:ALG:DIS’ | Dispersed Phase Zero Equation model
CTURBM | ‘EVM:ALG:LES’ | LES (Smagorinsky)
CTURBM | ‘EVM:K-E’ | Standard k- model
CTURBM | ‘EVM:K-E:RNG’ | RNG model
CTURBM | ‘EVM:K-O’ | Wilcox model
CTURBM | ‘EVM:K-O:SST’ | Menter Shear Stress Transport (SST) model
CTURBM | ‘EVM:K-O:SST:DES’ | DES=Menter Shear Stress Transport (SST) model
CTURBM | ‘EVM:K-O:BSL’ | Menter Baseline (BSL) model
CTURBM | ‘EVM:EVT’ | Menter Eddy Viscosity Transport model
CTURBM | ‘RSM:TED’ | Reynolds stress model (Launder, Reece and Rodi)
CTURBM | ‘RSM:TED:SSG’ | SSG Reynolds stress model
CTURBM | ‘RSM:TED:QI’ | QI Reynolds stress model
CTURBM | ‘RSM:TEF’ | Reynolds Stress-Omega model
CTURBM | ‘RSM:TEF:BSL’ | Reynolds Stress-Omega model with BSL Omega equation
CHEATM | ‘ISOTHERMAL’ | Isothermal.
CHEATM | ‘THERMAL_H’ | Thermal Energy model
CHEATM | ‘TOTAL_H’ | Total Energy model
CBUOYM | ‘DEN*G’ | Buoyancy Force =
CBUOYM | ‘DENDIF*G’ | Buoyancy Force =
CBUOYM | ‘BOUSSINESQ’ | Boussinesq approximation

#### 18.5.2.7. USER_GET_TRANS_INFO

The USER_GET_TRANS_INFO routine provides access to time variables during transient simulations. It stores information in the ‘/USER/’//CDIR data area. It is available in user CEL and junction box routines.

             SUBROUTINE USER_GET_TRANS_INFO(WHO,ACTION,CDIR,CZ,DZ,IZ,LZ,RZ)
          C

The last five arguments are the stacks as usual. All the other arguments are character strings and are defined as follows:

          CI WHO          : Name of routine making original call.
          CI ACTION       : ‘GET’ & ‘RELEASE’
          CC
          CC
          CV CDIR         : Sub-directory name of /USER into which to put info.
          CC                If blank on entry, this is set equal to
          CC                TRANS_INFO
          CC                If non-blank on entry, it is unchanged, and treated
          CC                as a user supplied directory name.

Calling this routine with `ACTION = ‘GET’` creates and stores the transient information in `‘USER/’//CDIR` whereas `ACTION = ‘RELEASE’` deletes it. If `CDIR` is blank, the directory `‘TRANS_INFO’` will be used.

After calling `USER_GET_TRANS_INFO` the following variables will be available in `‘/USER/’//CDIR`:

Variable Names | Description
--- | ---
ATSTEP | Accumulated time step counter
CTSTEP | Current time step counter
ACLOOP | Accumulated coefficient loop counter
NCLOOP | Current coefficient loop counter
DT | Current time step size
ATIME_END | Accumulated simulation time at the end of time step
CTIME_END | Current simulation time at the end of time step
ATIME_MID | Accumulated simulation time at the middle of time step
CTIME_MID | Current simulation time at the middle of time step
ATIME | Accumulated simulation time
CTIME | Current simulation time

By default, `ATIME` is the same as `ATIME_END` and `CTIME` is the same as `CTIME_END`, but they can be changed to the ‘middle of timestep’ values using the expert parameter ‘time value `option=2’`.

For an example involving `USER_GET_TRANS_INFO`, see `Junction Box Example 3: Timestep Control`.

#### 18.5.2.8. USER_ASSEMBLE_INFO

This is a utility to obtain information about the equation being assembled when a call to a User Fortran routine is made during the computation of a boundary condition or a source. The call is made as follows:

          CALL USER_ASSEMBLE_INFO(ACTION,CGROUP,CEQN,CTERM,CPVAR,
         &                        CLVAR,CPATCH,CRESLT,
         &                        CZ,DZ,IZ,LZ,RZ)

The last five arguments are the stacks as usual. All the other arguments are character strings and are defined as follows:

    C --------------------
    C	Arguments
    C --------------------
    C
    CI	ACTION       : 'GET' or 'GET_USER'
    C
    CO	CRESLT       : Result of attempt to return information. See details.
    CO	CGROUP       : Equation group being assembled.
    CO	CEQN         : Equation being assembled.
    CO	CTERM        : Term or term type being assembled.
    CO	CPVAR        : Principal variable of equation being assembled.
    CO	CLVAR        : Linearization variable - see details.
    CO	CPATCH       : Patch name.
    C
    C --------------------
    C	Details
    C --------------------
    C
    C	ACTION:-
    C		= 'GET'       => Get all the field names that exists returned in
    C						internal solver form.
    C		= 'GET_USER'  => As for 'GET' except that user aliases are returned.
    C
    C	CRESLT:-
    C		If complete information can be provided then CRESLT = 'GOOD'
    C		If partial information is provided then CRESLT = 'SOME'
    C		Otherwise CRESLT = 'NONE' if no information can be found.
    C		CRESLT = 'BIG' if actual argument string lengths are too short to
    C		hold the data required. This argument should be declared to be *(4).
    C	Other output arguments:-
    C		These should be declared to be *(MXDNAM) for ACTION='GET' and they
    C		must be long enough to hold the user's names, a safe declaration is
    C		*(MXLEN_XALIAS).

`CTERM` is returned with the term `TYPE` if `ACTION = 'GET_USER'` rather than the term name. Possible term types are: `FTRANS.VOL`, `SOURCE.VOL` or `TRANS.VOL` for volumetric terms and `ADVECT.SUR`, `DIFFUS.SUR`, `FLUX.SUR`, `GRAD.SUR`, `LAPLACE.SUR`, `MSFLOW.SUR` and `STRESS.SUR`.

`CLVAR` is the variable on which the term operates, or for a source term, it is the one of the variables used to linearize the term. Generally this will be identical to `CPVAR` but for coupled systems of equations it might be the principal variable of any of the equations in the system. For a deferred term, for example, the term in the energy equation, it might be ANY variable.

An example of the use of USER_ASSEMBLE_INFO is available in User CEL Example 2: Using Gradients for an Additional Variable Source.

#### 18.5.2.9. GET_PARALLEL_INFO

The `GET_PARALLEL_INFO` routine provides access to information about the parallel run mode and partitioning details from within any user CEL function or from within junction box routines. It can be called in the following ways to look up the variables `RUNMOD`, `PARMOD`, `OWNPAR` and `NPARD`:

          CALL GET_PARALLEL_INFO ('RUNMOD',RUN_MODE,CNAME,CRESLT)
          CALL GET_PARALLEL_INFO ('PARMOD',PAR_MODE,CNAME,CRESLT)
          CALL GET_PARALLEL_INFO ('OWNPAR',OWN_PAR,CNAME,CRESLT)
          CALL GET_PARALLEL_INFO ('NPARD',NUM_PAR,CNAME,CRESLT)

- `RUNMOD` describes the run mode as either serial or parallel. It is an integer variable where `0` corresponds to serial and `1` to parallel.

- `PARMOD` describes the parallel mode and can be master or slave. It is an integer variable where `1` corresponds to the master process and `2` to a slave process.

- `OWNPAR` is an integer variable that gives the partition number on the current process.

- `NPARD` is an integer variable that gives the total number of partitions.

The variables `RUN_MODE`, `PAR_MODE`, `OWN_PAR` and `NUM_PAR` are used to store the values locally and should be declared as integer variables in your subroutine. They can be named differently to the names used here, but to avoid conflicts they should not be named `RUNMOD`, `PARMOD`, `OWNPAR` or `NPARD`. `CNAME` is a dummy character variable and should be declared as such.

#### 18.5.2.10. CAL_MESHMAP

This utility is used to generate and validate a mapping between an array of user-specified coordinates and the mesh coordinates within each domain.

          SUBROUTINE CAL_MESHMAP(CACTION,CZONE,UVX,IUVX_S,IUVX_F,
         &                       KUVXVX,NKUVXVX,CRESLT,
         &                       CZ,DZ,IZ,LZ,RZ)
    CC
    CC --------------------
    CC        Input
    CC --------------------
    CC
    CI  CACTION: ’CREATE’ to create the KUVXVX mapping
    CI           ’CHECK’ to perform basic validation of the map
    CI  CZONE:   Solver zone name for which mapping between mesh and UVX
    CI           coordinates is wanted
    CI  UVX:     User/new coordinates for which mapping to mesh coordinates
    CI           is wanted. Array dimensioning is UVX(3,IUVX_S:IUVX_F)
    CI  IUVX_S/F: Start/finish index of current block of user coordinates
    CC
    CC --------------------
    CC      Modified
    CC --------------------
    CC
    CM  KUVXVX: Mapping between current mesh nodes and those contained in
    CM          in the user array, UVX. Array dimensioning is KUVXVX(NKUVXVX)
    CM          where NKUVXVX is the number of nodes in the current zone.
    CC
    CC --------------------
    CC        Output
    CC --------------------
    CC
    CO  CRESLT: Status of work done

Release 18.2 - © ANSYS, Inc. All rights reserved.