User Defined Element (UDE)
User Defined Element (UDE) General Description
User Defined Elements (UDE) allow users to create elements with custom formulations (Mass, Momentum & Energy equations). Users can use Python or Fortran programming language to create their own element formulations. UDE’s are integrated into GUI and once created UDE can be used like other Flow Simulator elements. Moreover, Flow Simulator allows users to share UDE’s among models.
User Defined Element (UDE) Creation in the GUI
Flow simulator allows users to create user defined element. Users can create different category of inputs like text fields, tabular inputs, combo box & checkbox using entity designer user interface. To Access the UDE go to Tools menu UDE as shown in the image. Moreover, you can see the predefined UDEs at the bottom section of the Element Library.
The Entity Designer windows allows you to create, save, open, delete UDE element. It also provides interface for object tree definition, create Input parameters & Provide interface to write a Python Script for a solver.
Object Tree Definition
Object tree Definition allow to Set the Element type, Element Name, Element Symbol, Icon path, Screen Label & Element Comment.
Property Editor Definition
Property Editor Definition allow to Set different input field for the element. It allows the user to set variable names for Databases as well as screen label. You can choose the type for input field which are Text box, Combo-box, Checkbox & Tabular. User also needs to set unit field for corresponding inputs. Below figure shows detailed layout of Property Editor Definition panel.
Solver
Solver panel interface allow users to write a Python Script or use Fortran Coding to create user defined solver.
- If the user selects Fortran option, there are set of instruction provided to use Fortran Myelib. User need to follow those instructions to create & compile user defined Fortran element.
- For Python User interface, it has two different panels, one for Flow Function which is the solver routine for user defined element, & the other panel is to setup the error traps for the solution routine.
A demo model to solve Hazen Williams Friction pressure drop in both Python & Fortran is placed under Resources-Demo_Models-UDE_Fortran_Example
Fortran API functions in the User-Defined Element
The following section outlines API functions that are available in Fortran User-Defined Elements.
| Function Name | Description |
| GET_UDE_TYPE | Returns the UDE element name for the UDE element number. It returns a character string 31 characters long. |
 |
|
| GET_UDE_SCALAR_PROPERTY | When users set up a property input in the UDE Property Editor Definition menu, the “DB Name” field allows users to choose a variable name for the property input. The chosen DB_NAME will help you to retrieve the variable’s value by using this Fortran functions. |
 |
|
| GET_UDE_ARRAY_PROPERTY | Function retrieves the value of a table input variable or the table size. It returns a double precision number. |
 |
|
| GET_UDE_BOUNDARY_CONDITION | This function returns flow element upstream and downstream boundary conditions such as PTS, PSEB, THETA_INLET, PHI_EXIT, etc. It returns a double precision number. These are usually used for the flow calculation. Typical BC_ID: UDE_PTS, UDE_TTS, UDE_PSEB, UDE_RELANGL, UDE_THETA_INLET, UDE_PHI_INLET, UDE_THETA_EXIT, UDE_PHI_EXIT |
 |
|
| GET_UDE_FLUID_PROPERTY | Function returns flow element fluid properties at the upstream, downstream and an average. It returns a double precision number. These may or may not be needed for the flow calculation. |
 |
|
| GET_UDE_FLOW_DIRECTION | Function returns the flow direction as determined by the solver. It returns an integer. Return values are -1, 0, 1. Parameters REVERSED_FLOW_DIRECTION=-1, FORWARD_FLOW_DIRECTION=1, UNDEFINED_FLOW_DIRECTION=0 are available for clearer code. |
 |
|
| SET_UDE_SOLVED_VALUE | Subroutine returns the results to the main solver. Valid SOL_ID: UDE_MDOT1, UDE_TT_EXIT, UDE_VEL_EXIT, UDE_D_MDOT1_D_PTS, UDE_D_MDOT1_D_PSEB UDE_MDOT1 is the only required solution, the others are optional. |
 |
|
| SET_UDE_EXTRA_RESULT | Subroutine writes some extra results to the .res file. It does not affect the analysis. |
 |
|
| UDE_GET_REFERENCE_CONDITION | Function will retrieve general values from the solution. It is based on the controller so it’s valid inputs are the same as the controllers valid inputs. |
 |
|
| UDE_GET_FLUID_PROP | Subroutine will get fluid properties based on 2 supplied input properties (like pressure and temperature). The fluid type is always based on the fluid type entering the element. |
 |
|
Python API functions in the User-Defined Element
API functions that are available in Python-scripted User-Defined Elements:
Note 1: When you set up a property input in the UDE Property Editor Definition menu, the “DB Name” field allows you to choose a variable name for the property input. Your chosen DB_NAME will help you to retrieve the variable’s value by using the python functions detailed below.
Note 2: Python is a dynamic-typed language. Usually pure Python code does not document function argument and return value types. However, since the Python-scripted UDE is communicating with Fortran code, the argument and return value types are important and are documented below. Currently, string, real, and int are supported. In addition, you will see string?, real?, and int?. The question mark indicates the function argument is optional.
| Function Name | Description |
| ude.get_scalar_property (string DB_NAME) → real | This function returns the value of TEXTBOX (real number) inputs. |
| ude.is_checkbox_set (string DB_NAME) → int | This function returns the value of CHECKBOX inputs. Please remember that drop-down menu choices are indexed starting from 1. |
| ude.get_combobox_setting (string DB_NAME) → int | This function returns the value of COMBOBOX inputs. Please remember that unticked (Off) has value 0 and ticked (On) has value 1. |
| ude.get_array_size (string DB_NAME) → int | This function returns the number of entries in a TABULAR (real array) input. |
| ude.get_array_property (string DB_NAME, int INDEX) → real | This function returns the value of TABULAR (real array) input at index. |
| ude.get_flow_direction ()→ int ID_CODE | This function returns the flow direction ID_CODE. See below. |
| ude.FORWARD_FLOW_DIRECTION | Flow is usually in the “user-defined” forward direction, determined when you drag-and-drop the element from the Element Library and then choose “upstream” and “downstream” connected chambers. For Pump-like elements, flow is almost always in the forward direction. |
| ude.REVERSED_FLOW_DIRECTION |
If the “user-defined” downstream pressure becomes higher than the “user-defined” upstream pressure, then restrictive elements will reverse their flow direction. You are expected to provide MDOT1, VEL_EXIT, and TT_TEXIT in this case. Note: MDOT1 and VEL_EXIT are always positive values even for reversed flow. If reversed flow is expected, then it should be physically accurate. If reversed flow is never expected, then the values only need to be sufficiently accurate to help the Flow Simulator main solver to reach a converged solution. |
| ude.UNDEFINED_FLOW_DIRECTION | This is uncommon and means a valid flow direction could not be established on the current iteration. It generally happens only for elements with gravitational or rotational pumping coupled with a temperature gradient. |
| ude.get_boundary_condition (int ID_CODE) → real |
This function returns element boundary condition values. Note: “Inlet” and “Exit” are based on actual run-time flow direction. Valid ID_CODE are as follows. ude.PTS – Total pressure at inlet (psia) ude.TTS – Total temperature at inlet (degR) ude.FS – Secondary fluid fraction at inlet (unitless) ude.PSEB – Static back pressure at exit (psia) ude.THETA_INLET – Fluid tangential angle in at inlet (degrees) ude.PHI_INLET – Fluid radial angle in at inlet (degrees) ude.THETA_EXIT – Fluid tangential angle in at exit (degrees) ude.PHI_EXIT – Fluid radial angle in at exit (degrees) ude.RELANGL – Angle between upstream chamber and inlet flow (degrees) |
| ude.get_fluid_property (int ID_CODE) → real |
This function returns fluid properties at inlet and exit of the element. It also returns an average of the inlet and exit. ude.RHO_INLET – Fluid Density at inlet (lbm/ft^3) ude.RHO_AVG – Fluid Density averaged (lbm/ft^3) ude.RHO_EXIT – Fluid Density at exit (lbm/ft^3) ude.RGAS_INLET – Gas Constant at inlet (lbf*ft/lbm/degR) ude.RGAS_AVG – Gas Constant averaged (lbf*ft/lbm/degR) ude.RGAS_EXIT – Gas Constant exit (lbf*ft/lbm/degR) ude.CP_INLET – Specific Heat at inlet (Btu/lbm/degF) ude.CP_AVG – Specific Heat averaged (Btu/lbm/degF) ude.CP_EXIT – Specific Heat at exit (Btu/lbm/degF) ude.GAMMA_INLET – Specific Heat Ratio at inlet (unitless) ude.GAMMA_AVG – Specific Heat Ratio averaged (unitless) ude.GAMMA_EXIT – Specific Heat Ratio at exit (unitless) ude.MU_INLET – Dynamic Viscosity at inlet (lbm/hr/ft) ude.MU_AVG – Dynamic Viscosity averaged (lbm/hr/ft) ude.MU_EXIT – Dynamic Viscosity at exit (lbm/hr/ft) ude.KOND_INLET – Thermal Conductivity at inlet (Btu/hr/ft/degF) ude.KOND_AVG – Thermal Conductivity average (Btu/hr/ft/degF) ude.KOND_EXIT – Thermal Conductivity at exit (Btu/hr/ft/degF) ude.PRANDTL_INLET – Prandtl Number at inlet (unitless) ude.PRANDTL_AVG – Prandtl Number averaged (unitless) ude.PRANDTL_EXIT – Prandtl Number at exit (unitless) |
| ude.set_solved_value (int ID_CODE) |
This function returns your solved values (e.g. flow rate, fluid velocity, and exit temperature) to the Flow Simulator main solver. ude.MDOT1 – Mass Flow Rate per Stream, always positive (lbm/s) ude.VEL_EXIT – Fluid Velocity at exit (ft/s) ude.TT_EXIT – Total Temperature at exit (degR) ude.D_MDOT1_WRT_PTS, ude.D_MDOT1_WRT_PSEB Note: Derivative of MDOT1 with respect to inlet pressure and exit pressure. If not provided, then Flow Simulator uses a simple incompressible orifice flow function to estimate it. (lbm/s/psi) |
| ude.set_extra_result (string ANY_NAME, real VALUE, string UNITS) | This function allows you to create an extra result that will be printed to the results file. You can assign any name and any units. It will print as “ANY_NAME= VALUE (UNITS)” |
| ude.get_reference_condition (string ITEM_TYPE, int ITEM_ID, string PROP_NAME, string? INDEX1, string? INDEX2, string? INDEX3) → real |
This function is seldom needed. If your element flow function depends on non-local quantities (e.g. far away chamber swirl or another element flow rate), then this function will help. Any quantity that is available in the controller gauge selection is supported by ude.get_reference_condition too. The two most popular ITEM_TYPEs are “CHAMBER” and “ELEMENT”. The ITEM_ID is the reference Chamber ID number or reference Element ID number. Here is a list of the most popular PROP_NAME options. PT – Total Pressure at Chamber (psia) PS – Static Pressure at Chamber (psia) TT – Total Temperature at Chamber (degF) VEL – Velocity at Chamber or Element Exit (ft/s) RHOVEL – Rho*V at Chamber or Element Exit (lbm/ft^2/s) MACH – Mach Number at Chamber or Element Exit (unitless) XK – Swirl Factor at Chamber (unitless) REYF – Reynolds Number (for Friction calc.) in Duct-like elements (unitless) REYN – Reynolds Number (for HTC calc.) in Duct-like element (unitless) MDOT_SINGLE – Mass Flow Rate per Stream in Element (lbm/s) MDOT_TOTAL – Mass Flow Rate all Streams in Element (lbm/s) VDOT_SINGLE – Volumetric Flow Rate per Stream in Element (USgal/min) VDOT_TOTAL – Volumetric Flow Rate all Streams in Element (USgal/min) STREAMS – Number of Streams in Element VALVEPOS – Valve Opening (%) FANNING_FRIC – Fanning Friction Coefficient (unitless) DARCY_FRIC – Darcy Friction Coefficient (unitless) HTC – Heat Transfer Coefficient in elements with convection (Btu/hr/ft^2/DegF) NUSSELT – Nusselt Number in elements with convection (unitless) TWALL – Twall temperature of elements with convection (degF) RHO – Density of fluid in Chamber (lbm/ft^3) CP – Specific Heat of fluid in Chamber (Btu/lbm/degF) GAMMA – Specific Heats Ratio of gas in Chamber (unitless) RGAS – Gas Constant of gas in Chamber (lbf*ft/lbm/degR) COND – Thermal Conductivity of fluid in Chamber (Btu/hr/ft/degF) MU – Dynamic Viscosity of fluid in Chamber (lbm/hr/ft) PRANDTL – Prandtl Number of fluid in Chamber (unitless) INDEX1, INDEX2, and INDEX3 are optional arguments that help to supply addition information. For pipe elements that have stations, INDEX1=”5” would signify Station 5. INDEX1=”INLET”, “EXIT”, and “VENAC” (vena contracta) are available for elements such are expansions, contractions, and orifices. |
| ude.get_fluid_prop (int INPUT_TYPE_1, real INPUT_VALUE_1, int INPUT_TYPE_2, real INPUT_VALUE_2, int OUTPUT_TYPE) -> real |
Function will get 1 fluid property based on 2 supplied input variables (like pressure and temperature). The fluid type is always based on the fluid type entering the element.
Example:
INPUT and OUTPUT TYPEs |
| ude.write_message (string MESSAGE, string? PROPNAME, real? VALUE1, real? VALUE2) | This function writes an error message to the screen and to the errors/warnings output file. The MESSAGE input allows you to write any message. Typically, errors start with “ERROR: …” and warnings start with “WARNING: …”. The final three inputs are optional. If your message contains %PROPNAME, %VALUE1, or %VALUE2, they will be replaced with the arguments you supply. Please see the demo cases for additional information. In addition, if your message contains %ELNUM, it will be replaced with the UDE’s ID number. Note: You do not need to supply the UDE’s ID number as an input because it can be inferred. |
| ude.terminate_run () | This function sets the stop condition so the Flow Simulator main solver will terminate after error traps are done. It should be used when a critical error is detected. |
| ude.error_if_property_is_out_of_domain (string DB_NAME, string LEFT_BRACE, real LOWER_BOUND, real UPPER_BOUND, string RIGHT_BRACE) | This function is an easy-to-use wrapper that checks if the input is between the lower bound and upper bound. If the input is out-of-bounds, it issues ude.terminate_run(). The brace inputs can be ‘(‘ or ‘)’ to exclude the bound from the valid domain. Or they can be ‘[‘ or ‘]’ to include the bound in the valid domain. If DB_NAME corresponds to TABULAR (real array) input, then each entry will be checked to make sure it is valid. |
| ude.warn_if_property_is_out_of_domain (string DB_NAME, string LEFT_BRACE, real LOWER_BOUND, real UPPER_BOUND, string RIGHT_BRACE) | This function is the as ude.error_if_property_is_out_of_domain with a few exceptions. First, it writes “WARNING: …” instead of “ERROR: …”. Second, it does not terminate the run. It is useful for detecting and warning users about suspicious inputs that are not necessarily incorrect. |
Using a UDE
UDE elements are listed at the bottom of the element library. Users should drag the UDE and connect to chambers the same as other elements. Then, Provide inputs to the new element.
