ID #1077

The first User Subroutine is the hardest

Many users are interested in using user subroutines to set special boundary conditions, do problem-specific post-processing, or try things that are not supported either by the GUI or the solver itself. We have developed many user subroutines over the past few years to help users get started. Usually it only takes a couple days and does not cost very much.

Although the process of developing and using a user subroutine is straightforward, it is not easy at first. Many users have trouble getting started. If you fall into this category, this tip is for you.

This tip will take you through a specific example of creating and using a UCOND user subroutine. This example is a simple heat conduction problem in a square, where the conductivity is higher in a circular region inside the square. UCOND is similar to UVISC or UDENS --- one of many user subroutines that let you change specific material properties inside a given volume.

In order to compile user subroutines, you must have a FORTRAN compiler. For a list of the valid compilers compatible with the latest software release, please refer to the Knowledge Base section of our portal website. You may also use our online compiler for guaranteed compatibility. We do not guarantee or recommend other compilers, but they may work too.

Step 1 – Model Creation.  Using CFD-GEOM, create the 2D square grid shown in the figure (21 x 21), and save a clean DTF file.

Step 2 – Model Setup.  Set up the model in CFD-ACE-GUI. Pay special attention to steps (3) and (5) below:
  1. On the PT panel, turn on Heat
  2. On the BC panel, pick the left wall and set it to ‘Heat Flux’ and specify q = 100 W/m2. Similarly, pick the right wall and set it to ‘Isothermal’ and specify T = 300K.
  3. On the VC panel, pick the volume and change its conductivity to ‘User Sub(ucond)’
  4. On the SC panel, set the number of iterations to 1000. On the Relax tab, set the enthalpy relaxation to 5E-06.
  5. On the Run panel, indicate the name of the file containing the user subroutine you will be writing. Let's call the user subroutine "my_UCOND" .



Step 3 – User Subroutine Development.  Follow these steps to create the user subroutine:
  1. Copy the template file libUserAce.f over to your working directory, and rename it to my_UCOND.f. The template file libUserAce.f is located in the bin directory of your CFD-ACE-SOLVER installation folder.
  2. Edit the file my_UCOND.f with a non-formatting text editor or programming editor. On Windows, Notepad will work fine, but don’t use Microsoft Word or Wordpad, because these add extra hidden formatting character into the file. You could also use the editor that came with your FORTRAN compiler.
  3. Find the UCOND user subroutine. The template file starts by defining a MODULE named cfdrc_user at the top, containing some general parameters. Then, the file contains approximately 70 empty templates for user subroutines. UCOND is the 6th one. In version 2009.2, UCOND starts on line 570 and ends on line 617. You are free to delete all of the other user sub templates that are not being used.
  4. Type in the coding shown below inside the UCOND user subroutine template:


In order to understand what each line is doing, you can refer to the User Subroutine chapter in the CFD-ACE+ User Manual.  Below is short description.

The purpose of lines 15 through 17 is to get identifiers for each of the variables you need to 'get' or 'set'.

Line 19 gets the ‘active cell index’. Each iteration, the solver will call your UCOND for every grid cell in the volume, one cell at a time. Thus, there is a concept of the ‘current’ or ‘active’ cell. Some other routines work the same, but others work differently. For example, a UBOUND is called for a given boundary one face at a time, but a UINIT or USOURCE is called for an entire volume at a time. These things are well-documented both in the user manual and in comments inside the user subroutine template file.

Lines 21 through 29 determine what conductivity value to use, depending on the location of the current cell.

Finally, line 31 sets the conductivity for the current cell.

Step 4 – Compile the User Sub.  Now open up a DOS or Unix shell, change directories to your working directory, and type the following command at the shell prompt:
build-userlib my_UCOND

Note the absence of the “.f” on the filename. You must use the build-userlib script to compile the user subroutine, because it links the appropriate libraries for the solver.

You can also use the online compiler.

Step 5 – Run the Simulation.  Go back to the Run panel of CFD-ACE-GUI and press Run. Wait a few seconds for the simulation to complete, and then launch CFD-VIEW to look at the results.  You should get the results shown below. Because of the higher conductivity region, the overall resistance to heat flow is decreased, resulting in a lower temperature on the left wall.  Also, the temperature contours are no longer vertical.


So what would you do with this user subroutine? In some situations, it can be a coarse but easy alternative to creating a mesh with two distinct volumes, especially if the position of the high conductivity region changes with time or is a function of other variables.

The files used for this example can be  found by clicking here.


Note: tested with V2009.2

Tags: -

Related entries:

Last update: 2009-11-18 16:00
Author: ESI-CFD Support Team
Revision: 1.1

Digg it! Print this record Send to a friend Show this as PDF file
Propose a translation for Propose a translation for
Please rate this entry:

Average rating: 1 out of 5 (7 Votes )

completely useless 1 2 3 4 5 most valuable

You cannot comment on this entry