Customization Manager

Custom Correlations Description and Quick Guide

Flow Simulator has three customization methods to add capabilities and correlations that are not available in the software as distributed by Altair. These correlations may be based on company proprietary methods or may be in the public domain. If the correlations are in the public domain, contact Altair about the possibility of adding the correlations to the distributed version of the software.

The customization methods include:
  1. User Defined Elements (UDEs)

    UDE’s allow for an entire element to be added. In the user interface, the UDE Designer is used to create the UDE and define all required inputs. The UDE code (Python or Fortran) must include everything required to relate the inputs and boundary conditions to the thermo-fluid behavior of the element. This is a very flexible method but requires a higher level of expertise to implement. See User Defined Element (UDE) for more information.

  2. Controllers

    The controller manipulates a specific part of an element solution. For instance, the Feed-Forward controller can be used to calculate a Heat Transfer Coefficient (HTC) based on a set in the “gauge” variables. The HTC is then applied to an element as a “manipulated” variable. Controllers are very flexible and do not require as much expertise as a UDE to implement. The controller can be tedious to implement on numerous items in a model, however. See Controllers for more information.

  3. Custom Correlations

    The last customization option has a limited set of items that can be manipulated but is easy to implement on many elements. The items that can be manipulated by the custom correlation option include HTC’s, friction, and seal losses. If there is an item that you would like added to the custom correlations, Contact Altair if there is an item that you would like added to the custom correlations. The user interface customization manager defines the custom correlation.

Items That Use Custom Correlations

The following table shows the items that can have a custom correlation and the Flow Simulator modeling item (element, resistor, and so on) that can use the correlation.

Item (Subtype) Description Applies to These Elements
TURBULENT_FRICTION_FACTOR Friction coefficient used to calculate pressure loss along length of element. Re in turbulent flow range. CT, IT, AO, TP
LAMINAR_FRICTION_FACTOR Friction coefficient used to calculate pressure loss along the length of the element. Re in laminar flow range. CT, IT, AO
TURBULENT_DUCT_NU Heat Transfer Coefficient. Re in Turbulent. CT, IT, AO
LAMINAR_DUCT_NU Heat Transfer Coefficient. Re in Laminar. CT, IT, AO
NU_INLET_EFF HTC multiplier to account for boundary layer developing at the start of the element. CT, IT, AO
FREE_CONV_NU Heat Transfer Coefficient Convectors (Thermal Resistor)
FLAT_PLATE_NU Heat Transfer Coefficient Convectors (Thermal Resistor)
CYL_XFLOW_NU Heat Transfer Coefficient Convectors (Thermal Resistor)
ROTATING_CAVITY_NU Heat Transfer Coefficient. Convectors (Thermal Resistor)
INLET_K K loss = Ptotal Drop/Dynamic Pressure CT, IT, AO
HEAT_ADDITION Heat addition can be a heat flow (BTU/s or W), heat per unit mass (BTU/lbm or J/kg), delta T (deg R or K), and exit T (deg F or K) CT, IT, AO, and almost all orifice types.
HEAT_FLOW_TN Heat addition can be a heat flow (BTU/s or W) for a thermal network. Heat Flow (Thermal Resistor)
CHEM_REACTION Change the fluid species along the length of an element. Also includes a heat of reaction. IT
CAV_FRICTION_DISK_ROTOR Friction coefficient used to calculate torque and windage between fluid and cavity surface. Surface is vertical and rotating. Cavity Surface
CAV_FRICTION_DISK_STATOR Same as above, but surface is vertical and rotating. Cavity Surface
CAV_FRICTION_CYLINDER_ROTOR Same as above, but surface is horizontal and stationary. Cavity Surface
CAV_FRICTION_CYLINDER_STATOR Same as above, but surface is horizontal and stationary. Cavity Surface
LABSEAL_KEMULT A labyrinth seal loss factor. See Vermes Seal Element or Labyrinth Seal Tooth by Tooth Element for more information. Vermes or TbT Seal
LABSEAL_KFAC Vermes or TbT Seal
CDCOMP_CORNER_METHOD Discharge Coefficient (CD) adjustments. See FI CdComp Elements for more information. FI CdComp
  • CT=Standard Compressible Tube
  • IT=Incompressible Tube
  • AO=Advanced Orifice
  • TP=Turbulated Passage
  • Re=Reynolds Number
  • TbT=Tooth-by-Tooth

Custom Correlations in the Graphical User Interface (GUI)

There are two main steps to begin using a custom correlation.
  1. Create the custom item in the Customization Manager.
  2. Select the custom item from the element properties editor.

From the PreProcessing menu, select the customization manager.

Figure 1. PreProcessing Menu/Customization Manager option

Create a Custom Item

Figure 2. Customization Manager dialog
  1. Click New to create a new custom item.
  2. Give the item a name; no spaces allowed in the name.
  3. Select the programming language: Python or Fortran.
  4. Select the subtype for the custom item.
  5. Select English or SI units to control the units of variables passed between the custom code and the Flow Simulator solver.
  6. Define the unique inputs for the custom items. These can be used to add inputs for each element that uses this custom item. These variables are added to the argument list for the Python and Fortran custom routines. No spaces are allowed in the names.

    Figure 3.
  7. If Language=Python, write the Python code. Use the Restore button to update the Python code template that is supplied.
  8. If Language=Fortran, a unique ID can be given so that multiple items of the same subtype can be programmed in the same Fortran subroutine. The other option is to use a unique subroutine name for each item.
  9. If Language=Fortran, a unique DLL and subroutine names can be given. “Default” means the solver uses customize.dll and the subroutine names are found in the fs_custom_lib.f example file.
From the Customization Manager, use the Import and Export buttons to write the custom items to a file and read into another model, respectively.
  • Use Export to write a file containing all custom items in the current model.
  • Use Import in another model to read all custom items into the model.

Custom Correlation in an Element

Once the custom correlation is created, it can be used in the element. Select the appropriate element type and property as shown in the table above. For instance, the “TURBULENT_FRICTION_FACTOR” subtype can be used in the Compressible Tube, Incompressible Tube, Advanced Orifice, and Turbulated Passage elements.

Figure 4.

Another row is displayed to add input for the custom correlation. Currently there are no units associated with these inputs. The values entered are the values passed to the custom correlation.

Figure 5.

Figure 6.

Units in the Custom Correlation

Flow Simulator uses English units (inch, lbm, BTU) by default. However, the custom correlation has the option to use SI units (m, kg, W). If the SI unit set is selected, the values of the input arguments are scaled by Flow Simulator to SI units before being passed to the custom correlation, and the correlation can return the output arguments in SI units. The user input is the exception to this and are not scaled.

Custom Correlations in Fortran

The custom correlations can be written in Fortran or Python. Creating a Fortran correlation is more complicated than Python but may run faster than Python. Use the method you are more comfortable with. Flow Simulator reads a dynamic linked library (DLL) for the Fortran correlation. The default name is customize.dll, but you can specify the name in the customization manager. Flow Simulator can read multiple DLL’s if needed. For example, all custom correlations can be put in the same DLL or each correclation can have a different DLL file.

A sample custom correlation Fortran source code file is distributed with Flow Simulator. The file can be found in <FlowSimulator_install_folder>\Resources\Customize\fs_custom_lib.f. This file contains a sample subroutine for each of the custom correlation subtypes. Your Fortran file does not have to have all 18 subroutines in this file; it only needs the subroutines for the correlations used in your model.

The comments in the file describe the subroutine arguments. The arguments are the typical values needed by the correlation. The arguments also include an array containing the user-defined inputs. The order of the inputs in the array are the same as the user defined inputs in the customization manager.

There are two subroutines available that can be used to retrieve more information about the model. These can be used if the argument list does not contain an input required by the correlation. The subroutines are:
The subroutine argument lists and some parameters can be found in the files:
  • <FlowSimulator_install_folder>\Resources\Customize\reference\custom_interface_mod.f90
  • custom_param_mod.f90

CUST_GET_SET_REFERENCE_CONDITION is based on the Flow Simulator controllers and can be used to retrieve (gauge or GET) and manipulate (SET) many items in the model.

Figure 7.
Example - Retrieve the static pressure at station IDX in the element ELEM:
Example - retrieve the area at station IDX in the element ELEM:

CUST_GET_FLUID_PROP retrieves fluid properties based on the pressure and temperature supplied.

Figure 8.
Example - Retrieve fluid conductivity based on a supplied P and T:
CUST_PRP_INP(2)              = CUST_PRP_T
CUST_PRP_VIN(1)              = PS
CUST_PRP_VIN(2)              = TS + 459.67
CUST_PRP_LOUT                = .FALSE.
K                            = CUST_PRP_VOUT(CUST_PRP_CON)

The subroutine CUST_FILL_OUTPUT_STRING writes custom correlation information to the element section in the .res file. The arguments are:

Figure 9.
Example - Write the first line of your text:
USER_OUTPUT=" STATION Re Friction_Factor"
This writes a table for each station of a tube:

The file custom_param_mod.f90 contains parameters such as ELEMENT_TYPE and CUST_PRP_P.

The INTEL Fortran compiler (v19.0.4.245) was used for development testing of this feature. Other compilers and versions may work but have not been tested. Compiling and linking should be done for 64-bit to be compatible with Flow Simulator. The fs_custom_lib.f uses the Fortran fixed format but with lines up to 132 columns, so use these compiler options. An example in Visual Studio:

Figure 10.

Custom Correlations in Python

The Python code for a custom correlation is entered in the user interface Customization Manager. Each custom correlation subtype has a Python code template that shows the arguments passed to the correlation and the expected variables the code must fill and pass back to Flow Simulator. Any user-defined inputs are appended to the end of the argument list. The arguments in the “def” line do not need to be used in the custom correlation; only use what is required by your equations. The variables in the “return” line must be set to a value in your code.

The Python language uses the line indentation to recognize programming units so it's very important that the line indentation of the added code is consistent. The template uses a tab at the beginning of each line so each new line must begin with at least one tab.

Like Fortran, Python has functions that can retrieve additional model data. The functions are:
  • cust.get_set_reference_condition
  • cust.get_fluid_prop

The arguments are like the Fortran code except that the returned values are not in the argument list.

cust.get_set_reference_condition is based on the Flow Simulator controllers and can be used to retrieve (gauge or GET) and manipulate (SET) many items in the model. Command format:
propval = cust.get_set_reference_condition (mode, itemtype, itemnum, prop, locat1, locat1_str, locat2, locat3)

mode       = GET (1) or SET (2)
itemnum    = Number from the .flo file of the item (chamber, element, etc..)
prop       = A property name recognized by the controller (like "PT", "PS", "TT", "MDOT_TOTAL" etc..)
locat1     = First additional index. Ex: 5 for tube station 5, 0 if not needed
locat1_str = Only needed if itemtype=7 (Thermal).  Then use "TNODE", "CDUCR", "CVECR", "RADTR", "HEAT_FLOW". "NONE" if not needed.
locat2     = Second additional index. Ex 2 for tube wall side 2, or 4 for TNODE 4, 0 if not needed
locat3     = Third additional index. Ex "2" for ?, 0 if not needed, etc..
propval    = value returned from controller for "GET" and sent to controller for "SET"
Example - Retrieve the static pressure at station IDX in the element ELEM:
pstatic = cust.get_set_reference_condition (cust.GET_MODE, cust.ELEMENT_TYPE, int(elem), "PS", int(idx), "NONE", 0, 0)
Example - Retrieve the area at station IDX in the element ELEM:
area = cust.get_set_reference_condition (cust.GET_MODE, cust.ELEMENT_TYPE, int(elem), "AREA", int(idx), "NONE", 0, 0)
CUST_GET_FLUID_PROP retrieves fluid properties based on the pressure and temperature supplied. Command format:
propval = cust.get_fluid_prop (inp_type_1, inp_val_1, inp_type_2, inp_val_2, out_type, itemnum, ec_flag)

inp_type_1   =   first independent variable type (typically pressure so use cust.PRP_P parameter)
inp_val_1    =   value of the first independent variable
inp_type_2   =   second independent variable type (typically temperature so use cust.PRP_T parameter)
inp_val_2    =   value of the second independent variable
out_type     =   the fluid property to output
itemnum      =   Number from the .flo file of the element
ec_flag      =   identifies itemnum as an element or chamber (cust.FLOW_ELM)
The parameters that can be used for inp_type_1, inp_type_2, and out_type are:
cust.PRP_P 1 pressure used to get properties (psi)
cust.PRP_T 2 temperature used to get properties (deg R)
cust.PRP_QUAL 3 quality
cust.PRP_RHO 4 density, (LBM/FT^3)
cust.PRP_CP 5 specific heat at constant pressure, BTU/(LBM R)
cust.PRP_CV 6 specific heat at constant volume, BTU/(LBM R)
cust.PRP_GAM 7 gamma
cust.PRP_CON 8 conductivity, BTU/(HR FT R)
cust.PRP_VIS 9 dynamic viscosity, LBM/(HR FT)
cust.PRP_PR 10 Prandtl number
cust.PRP_MW 11 Molecular Weight, (lbm/lbmole)
cust.PRP_R 12 Gas constant, (FT LBF)/(LBM R)
cust.PRP_H 13 Specific Enthalpy (BTU/lbm)
cust.PRP_S 14 Specific Entropy (BTU/lbm/R)
cust.PRP_TSAT 15 Saturation Temperature (deg R) at the Pressure provided
cust.PRP_HVAP 16 Heat of vaporization (BTU/lbm) (Specific Enthalpy Vapor - Specific Enthalpy Liquid)
cust.PRP_PCRT 17 Critical pressure (psia)
Example - Retrieve fluid conductivity based on a supplied P and T:
k = cust.get_fluid_prop (cust.PRP_P, pstatic, cust.PRP_T, tstatic, cust.PRP_CON, int(elem), cust.FLOW_ELM)

Use cust.fill_output_string write custom correlation information to the element section in the .res file.

Command format:
cust.fill_output_string (line_number, text_string)
The line that this text string is written to. Start with 1 and add more if needed.
The text string to write to the .res file
Example - Write the calcuted inlet k as the first custom output line:
cust.fill_output_string(1, "inlet_k="+str(inlet_k))