.. _function_syntax_section: Function Syntax =============== Most of the material and data fields of Tdyn CFD+HT may be defined by functions, through a "Function editor". Those data fields can be inserted by means of the function editor by pressing buttons shown in the following figure. Note that these buttons are only available in those pages where any function field exists. .. figure:: figures/function_editor_button.png :scale: 110% :align: center Function editor button. .. figure:: figures/matrix_editor.png :scale: 110% :align: center The "Functions editor" allows for comfortable definition of complex functions and matrices. Such an editor includes some tools to help the insertion of functions as for instance a list of available variables and operators. Next a brief explanation of the syntax of the functions used in Tdyn CFD+HT is given. .. _variables_section: * **Variables**: The variables that can be used for the definition of the functions are presented next. Global variables, available for any function: - *t* : Total (physical) time - *it* : Interval time. Time from the last restarting of the problem. - *dt* : Time increment. - *rand* : Random number. - *step* : Current step of the analysis. Geometrical variables, available for functions in domain scope (fluid or solid domain functions): - *x* : X cartesian coordinate of the point. - *y* : Y cartesian coordinate of the point. - *z* : Z cartesian coordinate of the point. - *rhoc* : ρ corresponding to cylindrical coordinates of the point. ρ is given by ρ=√(x2+y2) - *thetac* : θ corresponding to cylindrical coordinates of the point. θ is given by θ=atan(y/x). - *rhos* : ρ corresponding to spherical coordinates of the point. ρ is given by ρ=√(x2+y2+z2) - *thetas* : θ corresponding to spherical coordinates of the point. θ is given by θ=atan(y/x). - *phis* : φ corresponding to spherical coordinates of the point. φ is given by φ=atan(√(x2+y2)/x) - *nx* : X component of the point normal. - *ny* : Y component of the point normal. - *nz* : Z component of the point normal. Unknowns or physical properties that can be used in fluid domain scope: .. note:: **Remarks**: Unknowns variables or physical properties are evaluated by default within functions in general units. Furthermore it is possible to define the units to be used in the function. In these cases, the units must be inserted after the variable name between square brackets. Examples: .. code-block:: vx[m/s]/2 pr[bar]+1 sp1[%]+10 It is also possible to obtain the value of the physical properties in a particular node. Examples: .. code-block:: vx(#node) pr(#node) - vx : X velocity component at the point (Fluid Flow module). - vy : Y velocity component at the point (Fluid Flow module). - vz : Z velocity component at the point (Fluid Flow module). - pr : Pressure of the point (Fluid Flow module). - pt : Thermodynamic pressure (total pressure, including hydrostatic term plus operating pressure). Only available when solving fluid flow (Fluid Flow module). - vt : Eddy viscosity at the point (only available if turbulence model is selected) (Fluid Flow module). - ke : Eddy kinetic energy at the point (only available if turbulence model, based in the k equation is selected) (Fluid Flow module). - ep : Epsilon value at the point (only available if k-epsilon turbulence model is selected) (Fluid Flow module). - om : Omega value at the point (only available if k-omega turbulence model is selected) (Fluid Flow module). - kt : Ktau (k*tau) value at the point (only available if k-ktau turbulence model is selected) (Fluid Flow module). - bt : Beta (wave elevation) value at the point (Free SurfaceTranspiration module). - dn : Density of the point. - vs : Viscosity of the point (Fluid Flow module). - kvs : Kinematic viscosity of the point (Fluid Flow module). - cm : Compressibility factor at the point (Fluid Flow module). - tm : Temperature of the point (Fluid Flow module). - cp : Specific heat of the point (Fluid Flow module). - kis : Heat conductivity of the point for fluids (Fluid Flow module). - sp : Concentration of the corresponding species at the point (Species Advection module). Number of species must be indicated after sp (i.e. sp1, sp7) - ph : Value of the corresponding variable at the point (PDE's solver module). Number of variable must be indicated after ph (i.e. ph1, ph7) - ds : Distance of the point to the closest wall (Fluid Flow module). - mx : Accumulated mesh deformation of the point in the x direction (Mesh Deformation module). - my : Accumulated mesh deformation of the point in the y direction (Mesh Deformation module). - mz : Accumulated mesh deformation of the point in the z direction (Mesh Deformation module). - ols : Level set field defining free surface (Free Surface-Odd Level Set module) .. note:: **Remarks**: Variables are evaluated at the previous time step (t-dt). Variables are only available when corresponding module is active. Unknown or physical properties functions that can be used in solid domain scope: - vx : X velocity component at the point (Fluid Flow module). - vy : Y velocity component at the point (Fluid Flow module). - vz : Z velocity component at the point (Fluid Flow module). - pr : Pressure of the point (Fluid Flow module). - pt: Thermodynamic pressure (total pressure, including hydrostatic term plus operating pressure). Only available when solving fluid flow (Fluid Flow module). - dn : Fluid density of the point (Fluid Flow module). - vs : Fluid viscosity of the point (Fluid Flow module). - kvs : Fluid kinematic viscosity of the point (Fluid Flow module). - sdn : Solid density of the point. - tm : Temperature of the point (Heat Transfer module). - cp : Specific heat of the point (Heat Transfer module). - kxx : Heat conductivity (xx) of the point (Heat Transfer module). - kxy : Heat conductivity (xy) of the point (Heat Transfer module). - kxz : Heat conductivity (xz) of the point (Heat Transfer module). - kyy : Heat conductivity (yy) of the point (Heat Transfer module). - kyz : Heat conductivity (yz) of the point (Heat Transfer module). - kzz : Heat conductivity (zz) of the point (Heat Transfer module). - sp : Concentration of the corresponding species at the point (Species Advection module). Number of species must be indicated after sp (i.e. sp1, sp7) - ph : Value of the corresponding variable at the point (PDE's solver module). Number of variable must be indicated after ph (i.e. ph1, ph7) - ds : Distance of the point to the closest wall (Fluid Flow module). - mx : Accumulated mesh deformation of the point in the x direction (Mesh Deformation module). - my : Accumulated mesh deformation of the point in the y direction (Mesh Deformation module). - mz : Accumulated mesh deformation of the point in the z direction (Mesh Deformation module). .. note:: **Remarks**: Variables are evaluated at the previous time step (t-dt). Variables are only available when corresponding module is active. Examples: .. code-block:: x+y 0.1*vx*vx 120.0*(tm-25) 0.1*sp2 sin(x-t)*log(y^2) * **Constant**: The constants defined for functions internal compilation are: - *pi* : 3.1415926535897932385 - *exp(1)* : 2.7182818284590452354 - *dt* : Time increment of the current step. - *op* : Operating pressure. - *infinite* : Infinite. * **Function operators**: The function operators calculate the value of a standard function at the point defined by the given argument. The function operators that can be used for the definition of the Tdyn CFD+HT functions are: - sqrt : the sqrt function calculates the square root of the argument. Syntax: sqrt(.) - abs : the abs function calculates the absolute value of the argument. Syntax: abs(.) - ln : logarithm of the argument, e base. Syntax: ln(.) - log : logarithm of the argument, decimal base. Syntax: log(.) - fac : factorial of the argument. Syntax: fac(.) - sin : sine of the argument. Syntax: sin(.) (argument given in radians). - cos : cosine of the argument. Syntax: cos(.) (argument given in radians). - tan : tangent of the argument. Syntax: tan(.) (argument given in radians). - asin : The asin function returns the arcsine of the argument in the range -π/2 to π/2 radians. Syntax: asin(.). - acos : The acos function returns the arccosine of the argument in the range 0 to À radians. Syntax: acos(.). - atan : The atan function returns the arctangent of the argument in the range -π/2 to π/2 radians. Syntax: atan(.) (result given in radians). - sinh : hyperbolic sine of the argument. Syntax: sinh(.). - cosh : hyperbolic cosine of the argument. Syntax: cosh(.). - tanh : hyperbolic tangent of the argument. Syntax: tanh(.). - exp : the exp function calculates the exponential value of the argument. Syntax: exp(.). - heaviside : the heaviside function evaluates Hs defined as: .. math:: \begin{aligned} H_{\epsilon}({\Phi})=0{\Phi}<-{\epsilon} \end{aligned} :label: .. math:: \begin{aligned} H_{\varepsilon}({\Phi})=\frac{1}{2}(1+\frac{\Phi}{\epsilon}+\frac{1}{\pi}sin({\pi}*\frac{\Phi}{\varepsilon}))|{\Phi}|<{\varepsilon} \end{aligned} :label: .. math:: \begin{aligned} H_{\varepsilon}({\Phi})=1{\Phi}<{\varepsilon} \end{aligned} :label: The syntax of the function is heaviside(.,.), where the first argument is Φ and the second is ε. * *Interpolate* : performs a linear interpolation, based on the given data. Two arguments are required: a list of pairs (ξ,η), defining a polylineal curve, and a function (f) defining the point (ξ) where the evaluation is to be done. Syntax: interpolate(#ξ1,η1,ξ2,η2,ξ3,η3,...#f). * *InterpolateSpline* : performs a spline interpolation, based on the given data. Two arguments are required: a list of pairs (ξ,η), defining a the curve, and a function (f) defining the the point (ξ) where the evaluation is to be done. Syntax: interpolatespline(#ξ1,η1,ξ2,η2,ξ3,η3,...#f). * *InterpolateFile* : performs a spline interpolation, based on the data given in a file. Two arguments are required: a file name where a list of pairs (ξ,η), defining a the curve, is given, and a function defining the the point (ξ) where the evaluation is to be done. Syntax: Interpolatefile(filename, f), where the first argument in the filename, and the second a function (f) defining the value. - srand : The rand function returns a pseudorandom integer in the range 0 to 1, based on the argument given as seed. Syntax: srand(.). - int : Integer conversos. Syntax: int(.). `-` : change sign operator. Syntax: (-expression). - j0 : Calculates Bessel function of first kind and order 0, at the given point. Syntax: j0(.). - j1 : Calculates Bessel function of first kind and order 1, at the given point. Syntax: j1(.). - jn : Calculates Bessel function of first kind and order n, at the given point. Syntax: jn(.,.), where the first argument is the evaluation point and the second is the order of the Bessel function. - y0 : Calculates Bessel function of second kind and order 0, at the given point. Syntax: y0(.). - y1 : Calculates Bessel function of second kind and order 1, at the given point. Syntax: y1(.). - yn : Calculates Bessel function of second kind and order n, at the given point. Syntax: yn(.,.), where the first argument is the evaluation point and the second is the order of the Bessel function. - maxs : Maximum of the surrounding values. For a given point, maximum of the values of the argument for the connected nodes is returned. Syntax maxs(.), where the argument is any unknown or physical property (:ref:`see variables section for further information `). - mins : Minimum of the surrounding values. For a given point, minimum of the values of the argument for the connected nodes is returned. Syntax mins(.), where the argument is any unknown or physical property (:ref:`see variables section for further information `). - meds : Average of the maximum and minimum of the surrounding values. For a given point, average of the maximum and minimum values of the argument for the connected nodes is returned. Syntax meds(.), where the argument is any unknown or physical property (:ref:`see variables section for further information `). - aver : Average of the surrounding values. For a given point, average of the values of the argument for the connected nodes is returned. Syntax aver(.), where the argument is any unknown or physical property (:ref:`see variables section for further information `). Weighted average is calculated by using standard FEM integration on the connected elements. - maxvar : Maximum of the values of the unknown or physical property given as argument (:ref:`see variables section for further information `). Syntax maxvar(.). - minvar : Minimum of the values of the unknown or physical property given as argument (:ref:`see variables section for further information `). Syntax minvar(.). - imat or igroup: Returns 1 if the point belongs to the material given as argument. Note that the material name is actually the name of the group used to assign the material. This function is case insensitive. Syntax imat(.) where the argument is a material's name (if the point belongs to two contiguous materials, it returns 1 in both cases). - mat or group: Returns 1 if the material given as argument is being used. Note that the material name is actually the name of the group used to assign the material. Syntax mat(.) where the argument is a material's name. - curv : Curvature of the variable given as argument (:ref:`see variables section for further information `). Syntax curv(.). - pfx : X Component of the pressure force of the given Body. Syntax: pfx(.) where the argument is a body's name. - pfy : Y Component of the pressure force of the given Body. Syntax: pfy(.) where the argument is a body's name. - pfz : Z Component of the pressure force of the given Body. Syntax: pfz(.) where the argument is a body's name. - vfx : X Component of the viscous (stress) force of the given Body. Syntax: vfx(.) where the argument is a body's name. - vfy : Y Component of the viscous (stress) force of the given Body. Syntax: vfy(.) where the argument is a body's name. - vfz : Z Component of the viscous (stress) force of the given Body. Syntax: vfz(.) where the argument is a body's name. - pmx : X Component of the pressure moment of the given Body, evaluated at its center of gravity. Syntax: pmx(.) where the argument is a body's name. - pmy : Y Component of the pressure moment of the given Body, evaluated at its center of gravity. Syntax: pmy(.) where the argument is a body's name. - pmz : Z Component of the pressure moment of the given Body, evaluated at its center of gravity. Syntax: pmz(.) where the argument is a body's name. - vmx : X Component of the viscous (stress) moment of the given Body, evaluated at its center of gravity. Syntax: vmx(.) where the argument is a body's name. - vmy : Y Component of the viscous (stress) moment of the given Body, evaluated at its center of gravity. Syntax: vmy(.) where the argument is a body's name. - vmz : Z Component of the viscous (stress) moment of the given Body, evaluated at its center of gravity. Syntax: vmz(.) where the argument is a body's name. - dsx : X Component of the accumulated displacement vector of the given Body. Syntax: dsx(.) where the argument is a body's name. - dsy : Y Component of the accumulated displacement vector of the given Body. Syntax: dsy(.) where the argument is a body's name. - dsz : Z Component of the accumulated displacement vector of the given Body. Syntax: dsz(.) where the argument is a body's name. - rtx : X Component of the accumulated rotation vector of the given Body. Syntax: rtx(.) where the argument is a body's name. - rty : Y Component of the accumulated rotation vector of the given Body. Syntax: rty(.) where the argument is a body's name. - rtz : Z Component of the accumulated rotation vector of the given Body. Syntax: rtz(.) where the argument is a body's name. - vlx : X Component of the velocity vector of the given Body. Syntax: vlx(.) where the argument is a body's name. - vly : Y Component of the velocity vector of the given Body. Syntax: vly(.) where the argument is a body's name. - vlz : Z Component of the velocity vector of the given Body. Syntax: vlz(.) where the argument is a body's name. - vrx : X Component of the rotational velocity vector of the given Body. Syntax: vrx(.) where the argument is a body's name. - vry : Y Component of the rotational velocity vector of the given Body. Syntax: vry(.) where the argument is a body's name. - vrz : Z Component of the rotational velocity vector of the given Body. Syntax: vrz(.) where the argument is a body's name. - xcg : X Component of the center of gravity of the given Body. Syntax: xcg(.) where the argument is a body's name. - ycg : Y Component of the center of gravity of the given Body. Syntax: ycg(.) where the argument is a body's name. - zcg : Z Component of the center of gravity of the given Body. Syntax: zcg(.) where the argument is a body's name. - xrot : X displacement corresponding to de planar rotation of a point (center of rotation is the point 0,0,0). Note that if the geometry units and function units are different, the returning value must be multiplied by the units conversion factor. Syntax xrot(.) where the argument is the rotation angle. - yrot : Y displacement corresponding to de planar rotation of a point (center of rotation is the point 0,0,0). Note that if the geometry units and function units are different, the returning value must be multiplied by the units conversion factor. Syntax yrot(.) where the argument is the rotation angle. - Readfile : Execute the function in the text file defined by the argument. The file must include a first line defining the maximum time to use the function and a second line containing the function to be executed. If the current time is greater than the one defined in the file, Tdyn CFD+HT waits until the file is updated. Syntax readfile(.) where the argument is the path and name of the file. Example readfile(C:\Temp\velx.dat). Example of file format: .. code-block:: Time = 0.1; Function = "interpolate(#0.0,1.1,1.0,2.0#t);"; - Tcl : Executes a TCL script or procedure returning a double value. Syntax tcl(.) where the argument is the script to be executed. Example tcl(set var) return the value of tcl variable var. .. note:: **Note**: In order to use this function, TCL extension must be enabled by activating Tcl extension. - CloudOfDataFile : performs a local interpolation based on the cloud of points (x,y,z) and data (¸) given in a file. The argument is the path and name of the text file. Syntax: CloudOfDataFile(·), where the argument in the filename. Example CloudOfDataFile(C:\Temp\velx.dat). Example of file format: .. code-block:: 0.0 0.0 0.0 1.0 0.0 1.0 0.0 0.5 1.0 1.0 1.0 2.0 5.0 2.5 2.0 5.0 Examples: .. code-block:: 2*sqrt(y) x*fac(5) srand(0) log(abs(x)) exp(5) interpolate(#1.0,2.0,2.0,2.5,3.0,2.0#t^2) maxvar(vx) mat('Fluid') * **Operators**: Operators that can be used for Tdyn CFD+HT functions definitions are: - `+` : adding operator. Syntax: [adding_expression] + [adding_expression]. - `-` : substraction operator. Syntax: [substraction_expression] - [substraction_expression]. - `^` : exponent operator. Syntax: [exponent_expression] ^ [function_expression]. - `*` : multiplicative operator. Syntax: [multiplicative_expression] * [multiplicative_expression]. - `/` : division operator. Syntax: [multiplicative_expression] / [quotient_expression]. - div : integer division operator int(x/y+0.5). Syntax: ([multiplicative_expression]) div ([quotient_expression]). Example: (x)div(2+y). - idiv : integer division operator int(x/y+0.5). Similar to div operator but with different syntax. Syntax: idiv ([multiplicative_expression], [quotient_expression]). Example: idiv(x,2+y). - mod : integer division module operator int(x+0.5)%int(y+0.5). Syntax: ([multiplicative_expression]) mod ([quotient_expression]). Example: (t)mod(2). - imod : integer division module operator int(x+0.5)%int(y+0.5). Similar to mod operator but with different syntax. Syntax: imod ([multiplicative_expression],[quotient_expression]). Example: imod(t,2). - rdiv : real division operator int(x/y). Syntax: ([multiplicative_expression]) rdiv ([quotient_expression]). Example: (t)rdiv(5). - ddiv : real division operator int(x/y). Similar to rdiv operator but with different syntax. Syntax: ddiv ([multiplicative_expression], [quotient_expression]). Example: ddiv(t,5). - rmod : real division module operator x/y-int(x/y). Syntax: ([multiplicative_expression]) rmod ([quotient_expres-sion]). Example: (t)rmod(5). - dmod : real division module operator x/y-int(x/y). Similar to rmod operator but with different syntax. Syntax: dmod ([multiplicative_expression], [quotient_expres-sion]). Example: dmod(t,5). - max : maximum operator. Syntax: max ([expression], [expression]). Example: max(x,y). - min : minimum operator. Syntax: min ([expression], [expression]). Example: min(x,y). - not : not operator. Syntax: not([function_expression]). - ~ : not operator. Syntax: ~([function_expression]). Examples: .. code-block:: (2*y) (5*(y+1))/2 (z*y)mod(5) imod(z*y) (5) (5^4) * **Relational operators**: The relational (binary) operators compare their first operand with their second operand to test validity of the specified relationship. The result of the relational expression is 1 if the tested relationship is true and 0 if it is false. The binary operators that can be used for Tdyn CFD+HT functions definitions are: - `<` : less than operator. Syntax: [expression] < [expression]. - `<=` : less or equal than operator. Syntax: [expression] <= [expression]. - `>=` : greater or equal than operator. Syntax: [expression] >= [expression]. - `>` : greater than operator. Syntax: [expression] > [expression]. - `=` : equal operator. Syntax: [expression] = [expression]. - `~=` : not equal operator. Syntax: [expression] != [expression]. - `&` : and operator. Syntax: [expression] & [expression]. - `|` : and operator. Syntax: [expression] | [expression]. Examples: .. code-block:: (y>2) (x<=1) (x!=1) (y>2)&(x>2)&(x<3)&(y<3) * **cartesian derivatives**: It is also possible to use cartesian derivatives to evaluate functions in solid and fluid domains. The Cartesian derivative operators that can be used for Tdyn CFD+HT functions definitions are: - x : X Cartesian derivative. The argument must be a variable defined in the whole domain (not a function). - dy : Y Cartesian derivative. The argument must be a variable defined in the whole domain (not a function). - dz : Z Cartesian derivative. The argument must be a variable defined in the whole domain (not a function). - grad : Norm of the gradient of a variable. The argument must be a variable defined in the whole domain (not a function). Examples: .. code-block:: vx*dx(vx) nx*dx(vx)+ny*dy(vx) grad(vx) * **if-else statement**: The if statement controls conditional branching. The body of the if statement (elif_expression) is executed if the value of the expression is non zero. The syntax for the if statement is the following: .. code-block:: if(expression)then(elif_expression)else(next_expression)endif being elif_expression an additional expression that may include an elif clause with next form: .. code-block:: (expression2)elif(elif_expression2)then(next_expression2) Examples: .. code-block:: if(y>2)then(if(x<1)then(1)else(0)endif)else(0)endif if(y>2)then(1)elif(x<1)then(2)else(0)endif .. note:: **Remarks**: Dimensional variables used within the functions defined by the user are evaluated by default using general units. Nevertheless, it is also possible to define the units to be used for each variable within the function at hand. To this aim, the units must be inserted between square brackets after the variable name. The variables that can be defined with units are: t,it,dt,x,y,z and any other vector such as pr, vx, vy, tm, dn, ... It is also possible to define the units of any variable resulting from the application of a given operator over one of the variables described above. If this is the case, the units of the operation result must be indicate as well between brackets after the variable to which the operator under consideration operates. Examples: Units on variables: 2*t[s], dt[ms], x[cm]+y[m]^2, pr[bar], dn[Kg/m3] Units in operation results: dx(vx[1/s]), dxdy(tm[K/m2]) Every data field in Tdyn includes several standard units definition, but the user can also enter additional units based on the basic units definition shown in the following table. .. csv-table:: Units :file: ./figures/units_table.csv :widths: 20, 20, 70, 70 :header-rows: 1 Examples: W.m (watts per meter), N/m2 (newtons per square meter), m3 (cubic meter), g/cc (grams per cubic centimeter). New units can also be created by adding standard modifiers to the basic unit. These modifiers are shown next: .. csv-table:: Units :file: ./figures/units_prefix.csv :widths: 20, 20, 20 :header-rows: 1