2008 International
ANSYS Conference
Training Manual
Customizing CFX
Introduction to User Fortran:
User CEL Functions
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-1
August 26, 2008
Inventory #002568
Introduction to User Fortran
User Fortran - Introduction
Training Manual
Used for advanced CFX Solver customization beyond
what may be achieved using:
CFX Command Language (CCL)
CFX Expression Language (CEL)
CCL with embedded Perl
The limitations of these methods is that they are
specified using state files
CCL and CEL are interpreted at the start of the run
Can also be re-read during the run to provide a limited
amount of interaction
Relationships between variables may be defined (CEL)
External data may be utilized, particularly with the aid of
embedded Perl
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-2
August 26, 2008
Inventory #002568
Introduction to User Fortran
User Fortran Examples of use
Training Manual
Examples where User Fortran may be used include:
Input of external data
Specification of boundary conditions
Specification of source terms
Specification of the initial guess
Advanced solver control
Custom terms for particle tracking calculations
Communication with other software
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-3
August 26, 2008
Inventory #002568
Introduction to User Fortran
General Details
Training Manual
Currently two types of User Fortran
User CEL (write your own CEL functions)
Junction Box (routines called at specific points in the
solver execution cycle)
Both are Fortran subroutines
Both have access to all solver data structures
User subroutines may, in turn call:
Your own subroutines
Any CFX solver subroutine or function, including some
useful utilities
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-4
August 26, 2008
Inventory #002568
Introduction to User Fortran
Runtime link
Training Manual
User Fortran source is compiled and linked into a platform
specific shared library
Shared library is dynamically loaded at runtime
Re-linking of the solver is not required
Library files can be distributed for use on other systems
running the same platform
SHARED
LIBRARY
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
RUNTIME LINK
4-5
CFX-5
SOLVER
August 26, 2008
Inventory #002568
Introduction to User Fortran
Steps for using user Fortran
Training Manual
Write your Fortran
Compile/link to create a shared library
This is done using a special utility called cfx5mkext
Tell the Solver to use the library. This can be done:
From CFX-Pre
By editing the CFX Command Language (CCL)
Run the Solver (dynamic link automatically established)
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-6
August 26, 2008
Inventory #002568
Introduction to User Fortran
Creating a shared library
Training Manual
The utility cfx5mkext creates a single shared library from the
user Fortran source code
How to use cfx5mkext
cfx5mkext -name test file1.F file2.F ...
file1.o
file1.F
COMPILER
LINKER
file2.F
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
COMPILER
test.so
file2.o
4-7
August 26, 2008
Inventory #002568
Introduction to User Fortran
Creating a shared library
Training Manual
The shared library file is created in a platform specific
subdirectory
For example on an SGI machine, cfx5mkext
creates a subdirectory called irix containing the
shared library
Double precision shared libraries may be created:
cfx5mkext double -name test file1.F file2.F
The solver automatically selects the correct subdirectory:
SGI
irix/test.so
SGI double precision
irix/double/test.so
SUN
solaris/test.so
Windows
winnt\test.dll
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-8
August 26, 2008
Inventory #002568
Introduction to User Fortran
User CEL
Training Manual
User CEL is a user defined CEL function
Used in CEL expressions just like any other CEL function
Invokes a Fortran subroutine, written by the user
Uses include:
Specifying boundary conditions
Specifying source terms
Specifying initial guess for variables
Specifying material (including fluid) properties
anywhere CEL can be used
Operates over a set of points in space e.g.
Cell vertices for specifying variable initial guess
Cell face centres for boundary condition specification
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-9
August 26, 2008
Inventory #002568
Introduction to User Fortran
What can User CEL do that CEL cant?
Training Manual
Write special CEL functions not yet available e.g.
Calculate values depending on old time step data
Modulo function mod(x,y)
Random function rand()
Writing special interpolation functions for data tables
Logic which is too complicated for CEL
User CEL functions can access the solver data structures
May be used to access stored data in files, etc. (in
conjunction with Junction Box routines)
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-10
August 26, 2008
Inventory #002568
Introduction to User Fortran
User CEL vs. Built-in CEL Functions
Training Manual
User CEL functions have many similarities to built-in CEL
functions
Built-in CEL functions:
Have a single return value
Have varying numbers of arguments including none
Examples:
max function: a = max(b,c)
area function: area1 = area()@inlet1
User CEL functions
Have a single return value
Must have at least 1 argument
Example:function1 function: a = function1(b,c)
Return and argument units must be specified
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-11
August 26, 2008
Inventory #002568
Introduction to User Fortran
Application of User CEL functions
Training Manual
User CEL functions are used in CEL expressions in a
similar way to built-in CEL functions. For example:
In simple expressions
uvelocity = function1(a,b)
As operands of CEL operators
uvelocity = function1(a,b) + wvelocity
As arguments of built-in CEL functions or other user CEL functions
uvelocity = max(0.5,function1(a,b))
There is virtually no limit to what can be achieved, as
long as the syntax is obeyed and the expressions are
dimensionally consistent
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-12
August 26, 2008
Inventory #002568
Introduction to User Fortran
User CEL Subroutine Arguments
Training Manual
A user CEL function invokes a Fortran subroutine
This has a standard argument list
SUBROUTINE USRCEL(NLOC,NRET,NARG,RET,ARGS,CRESLT,
&
CZ,DZ,IZ,LZ,RZ)
Argument
Data type
I/O
Description
NLOC
INTEGER
IN
Number of locations in space.
Depends on Locale type
NRET
INTEGER
IN
Number of return variables (usually 1)
NARG
INTEGER
IN
Number of CEL arguments
RET(NLOC,NRET)
REAL array
OUT
Return data field
ARGS(NLOC,NARG)
REAL array
IN
Argument data field
CRESLT
CHARACTER*4
OUT
Result of call
CZ, DZ, IZ, LZ, RZ
Various
MOD
Solver Workspace Stacks.
Used to access solver data structures.
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-13
August 26, 2008
Inventory #002568
Introduction to User Fortran
Mesh Entities
Training Manual
User CEL operates over a set of points in
space
These will differ depending on where the
user CEL function is used
For initialisations, the calculation is
performed over cell vertices
At boundaries, the calculation is performed
over face centres or integration points
Other mesh entities exist, such as
integration points, for internal assembly
User CEL functions assume that the
arguments are located at the same
locations as the returned field
This suffices for most simple applications
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-14
Nodes
Face
Centres
August 26, 2008
Inventory #002568
Introduction to User Fortran
Mesh Locales
Training Manual
Internally, the Solver may split regions (such as faces of
a boundary) into manageable groups called locales
Example Locales:
VERTICES = set of cell vertices on a domain, or zone
IELGn = nth interior element group
BELGn = nth boundary element group
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-15
August 26, 2008
Inventory #002568
Introduction to User Fortran
Locales and User CEL
Training Manual
User CEL routines are called for variables defined on
specific entities on specific locales in the appropriate
domain
The user does not control the locales or entities for which a
User CEL function is called
The user does not control when a User CEL function is
called
User CEL functions assume that the arguments are located
at the same locations as the returned field
This suffices for most simple applications
Advanced applications may require:
Knowledge of current locale type
Access to different entity types on the current locale
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-16
August 26, 2008
Inventory #002568
Introduction to User Fortran
User CEL function Set-up (CFX-Pre)
Training Manual
Step 1: define a user routine
Following data required
Calling name (Fortran name)
Shared library name
Shared library path
NOTE: Forward slashes (/) or backslashes (\) may
be used as path separators. However do not put a
backslash at the end of a line, as this is interpreted
as a continuation character.
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-17
August 26, 2008
Inventory #002568
Introduction to User Fortran
User CEL function Set-up (CFX-Pre)
Training Manual
Step 2: Define the function
Following data required
Function name (CEL name)
Input argument units list
Return argument units (automatically
converted to units used by solver).
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-18
August 26, 2008
Inventory #002568
Introduction to User Fortran
User CEL function Set-up (CFX-Pre)
LIBRARY:
USER ROUTINE DEFINITIONS:
USER ROUTINE: velfunc
Calling Name = usr_velfnc
Library Name = backstep
Library Path = ..
Training Manual
This section relates
the user function to the Fortran subroutine.
The Fortran calling name is specified, also
the shared library name and path.
Option = User CEL Function
END
END
CEL:
FUNCTION: velfunc
Argument Units = m
Option = User Function
This section relates
the user function to the CEL function.
The CEL function name is specified,
as well as argument and result units.
Result Units = m/s
User Routine Name = velfunc
END
END
END
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-19
August 26, 2008
Inventory #002568
Introduction to User Fortran
USER_GETVAR utility
Training Manual
A user friendly wrapper for the more general solver
GETVAR utility
Allows solution fields to be accessed for calculations
Automatically returns data for the current locale
Gradients may be calculated
Only callable from User CEL functions
Obtains or computes its own copy of the data, on
the current locale / entities
Cannot be used to change the solution data
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-20
August 26, 2008
Inventory #002568
Introduction to User Fortran
USER_GETVAR Argument List
Training Manual
Standard calling sequence
CALL USER_GETVAR (VARIABLE_DESCRIPTION,CRESLT,pVAR,
&
CZ,DZ,IZ,LZ,RZ)
CHARACTER*(*) VARIABLE_DESCRIPTION (Input) =
Long alias name of variable
<Fluid Name>.<Component Name>.<Variable
Name>.<Operation>
E.g. Air.Nitrogen.Mass Fraction, Water at RTP.Gradient
<Operation> = Curl, Gradient, Time Derivative, Trnmin,
Trnmax, Trnrms, Trnsdv, Trnavg, Boundcon or null string
CHARACTER*4 CRESLT (Output) = Result of call
CRESLT = GOOD if call is successful
__stack_point__ pVAR (Output) = stack pointer to
variable
Currently equivalent to INTEGER, but allows future extension
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-21
August 26, 2008
Inventory #002568
Introduction to User Fortran
USER_GETVAR Example
Training Manual
#include stack_point.h
__stack_point__ pVEL, pVGRAD
CALL USER_GETVAR (R134a.Velocity,
&
CRESLT,pVEL,CZ,DZ,IZ,LZ,RZ)
CALL USER_GETVAR (R134a.Velocity.Gradient,
&
CRESLT,pVGRAD,CZ,DZ,IZ,LZ,RZ)
CALL USR_ROUTINE1 (RET,RZ(pVEL),RZ(pVGRAD), etc., etc. ..
Obtains a pointer pVEL to the velocity field on the current
locale/entities, for the fluid called R134a.
Obtains a pointer pVGRAD to the velocity gradient field on
the current locale/entities for the fluid called R134a.
Calls user defined calculation routine to compute returned
field as a function of velocity and velocity gradient.
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-22
August 26, 2008
Inventory #002568
Introduction to User Fortran
USER_GETVAR Variable Shapes
Training Manual
Standard Variables (Non-Gradients):
VAR (NCOMPT, NLOC)
NLOC = Locale dimensions
NCOMPT = no. of tensor components
NCOMPT = 1 for scalar, 3 for vector
Gradients:
VAR (NGRAD, NLOC, NCOMPT)
NGRAD = No. of gradient components = 3
NLOC, NCOMPT as above
ANSYS, Inc. Proprietary
2008 ANSYS, Inc. All rights reserved.
4-23
August 26, 2008
Inventory #002568
