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:

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:

VAR(NCOMPT,NLOC)

VAR(NGRAD,NLOC,NCOMPT)

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).

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:

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:

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

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

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:

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

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:

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:

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.

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.

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:

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:

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.

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:

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.

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.

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)

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 placeholder character variable and should be declared as such.

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