USER_EQUATION

Type

AcuTrace Command

Syntax

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

Qualifier

User-given name.

Parameters

user_function (string) [no default]

Name of the C function to use.

num_variables or num_vars (integer) >=1 [1]

Number of values returned by the equation, that is, the size of the output array of the equation.

user_values (array) [={}]

User-defined constant parameters supplied to the equation.

user_strings (list) [={}]

List of user-defined constant strings supplied to the equation.

type (enumerated) [=evolve]

Controls how the user equation is used in the particle trace. In both cases, u is the variable advanced and f is the user equation.

evolve: User equation is the right hand side of the evolution equation du/dt=f.
evaluate: User equation is the right hand side of u=f.

Description

The USER_EQUATION command defines an equation that can then be included in the particle trace simulation with the user_equations parameter of the EQUATION command. The full definition of a user equation consists a user-defined function written in the C programming language plus additional constants provided by the user_values and user_strings parameters. A single C function can therefore be used to define multiple user equations by using different values of these constants in multiple USER_EQUATION commands. See the AcuTrace User-Defined Function Manual for a detailed description of user-defined functions for AcuTrace.

In the following example, there are two user equations ener and temp. The first is used as the source term in an evolution equation for particle energy, and the second is used to compute the particle temperature from the particle energy. There are two constants provided by you: the product of the particle mass and the particle specific heat; and the thermal conductivity. The constants have values of two and three here. The two C functions are named usrEner and usrTemp. The input commands may then be given as:

EQUATION {
...
   user_equations = {ener, temp}
}
USER_EQUATION( "ener" ) {
   user_function  = "usrEner"
   num_variables  = 1
   user_strings   = {}
   user_values    = {3,2}
   type           = evolve
}
USER_EQUATION( "temp" ) {
   user_function  = "usrTemp"
   num_variables  = 1
   user_strings   = {}
   user_values    = {2}
   type           = evaluate
}

where the user-defined functions usrEner and usrTemp may be implemented as:

#include "acusim.h"
#include "ufp.h"
UFP_PROTOTYPE(usrEner);
Void usrEner (
      UfpHd        ufpHd,          /* Opaque handle for accessing data              */
      Integer      nItems,         /* Number of items in outVec                     */
      Integer      vecDim,         /* Vector dimension of outVec                    */
      Real*        outVec,         /* Output Vector                                 */
)
{ 
   Real*           usrVals ;       /* user values                                   */
   Real*           fluid ;         /* fluid temperature                             */
   Real*           particle ;      /* particle energy                               */
   Real            mpXcp ;         /* mass * c_p for particle                       */
   Real            cond ;          /* conductivity                                  */
   Real*           jac ;           /* source jacobian                               */
   cond                = usrVals[0] ;
   mpXcp               = usrVals[1] ;
   t_fluid             = ufpGetFlowData( ufpHd, UFP_FLOW_TEMPERATURE ) ;
   h_particle          = ufpGetUdfData( ufpHd, 0 ) ;
   outVec[0]           = -cond * ( h_particle[0] / mpXcp - t_fluid[0] ) ;
   jac                 = ufpGetJac( ufpHd, UFP_JAC_UDF_VARIABLES ) ;
   jac[0]              = -cond / mpXcp ;
}
UFP_PROTOTYPE(usrTemp);
Void usrTemp (
   UfpHd           ufpHd,          /* Opaque handle for accessing data              */
   Integer         nItems,         /* Number of items in outVec                     */
   Integer         vecDim,         /* Vector dimension of outVec                    */
   Real*           outVec,         /* Output Vector                                 */
)
{ 
   Real*           usrVals ;       /* user values                                   */
   Real*           h_particle ;    /* particle energy                               */
   Real            mpXcp ;         /* mass * c_p for particle                       */
   usrVals             = ufpGetUsrVals( ufpHd ) ;
   mpXcp               = usrVals[0] ;
   h_particle          = ufpGetUdfData( ufpHd, "ener" ) ;
   outVec[0]           = h_particle[0] / mpXcp ;
}

In order for AcuTrace to access these functions, the source file containing them must be compiled and linked into a shared library. The scripts AcuMakeLib, under Linux, and AcuMakeDll, under Windows, may be used for this purpose.

Assume the function implementations are in the file usrTemp.c. The functions are compiled and linked into a shared library libusr.so by issuing the command:

acuMakeLib -src usrTemp.c

The shared library libusr.so is automatically loaded by AcuTrace when it is run.