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