User Routines Tutorials GT-SUITE

(1)

GT-SUITE

User Routines Tutorials

VERSION 7.4

by

Gamma Technologies

All information contained in this manual is confidential and cannot be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without

the express written permission of Gamma Technologies, Inc.

(2)

GTI SUPPORT

• TELEPHONE: (630) 325-5848

• FAX: (630) 325-5849

• E-MAIL: support@gtisoft.com

• Web Address: www.gtisoft.com

• Address: 601 Oakmont Lane, Suite 220 Westmont, IL 60559

USA

Telephone Support Hours

8:00 A.M. to 5:30 P.M. Central Time Monday – Friday

(3)

Integrated Modeling with User Routines

Overview

These tutorials are prepared to assist GT-SUITE users to perform integrated simulations with their own programs. In the following sections, step-by-step instructions to set up integrated simulations are provided.

It is assumed that the user is already familiar with GT-SUITE and technical details on the implementation of user routines which are given in the user manual. The user manual, UserRoutines.pdf which covers this subject is located under …\GTI\v7.4.0\documents\Co-Simulation_And_UserRoutines.

There is another document, README.txt which is located under the user directory, “usrfiles”. This document can be used as a quick reference while programming, and since it is a part of the user project, it can be visualized via Microsoft Visual Studio.

(5)

Tutorial 1: GT-SUITE Example Model (UserRoutine.gtm)

In this tutorial, we are going to show the basics of integration of a user routine with the GT-SUITE model by referring to the completed GT-POWER example model called UserRoutine.gtm which is located under %GTIHOME%\v7.4.0\examples\Engine_Performance\UserRoutine (where %GTIHOME% is the GT-SUITE installation directory such as C:\GTI).

Settings within GT-SUITE

Let us assume that we have already created a simple model having a single circuit inlet flow branching into two outlets (see Figure 1), and our objective is to control the diameter of the ‘OrificeConn’ object named valve. This simple model (UserRoutine_base.gtm) represents our system as the starting point, and it is located under %GTIHOME%\v7.4.0\tutorials\Co-Simulation_And_UserRoutines\UserRoutines Furthermore, we want to modify this model by creating control logic via the user routine while sensing flow static pressures from the intake and the right angle branch pipes.

Figure 1 - Simple branching flow model

(6)

Step 1: Adding Sensors

To start, launch GT-ISE. Open the base model for this tutorial,

UserRoutine_base.gtm

and save it as

UserRoutine.gtm

in your working directory.

Connect a ‘SensorConn’ object to the intake pipe and set its output name to “Pressure (Static)” in order to sense its static pressure Similarly, connect a sensor to the right angle branch pipe to sense its static pressure (see Figure 2).

Figure 2 - Sensors are connected to the pipe parts

Step 2: UserSubroutine

As the second step, create an object from the ‘UserSubroutine’ template. Name this object uservalve.

This object will let us exchange signals (to be sensed and generated) between the user routine and the GT-SUITE model. This is done by passing input signals to the ‘UserSubroutine’ template, manipulating these signals in the user routine, and sending output signals to the GT-SUITE model.

Set the object value of its attribute “User Model Name” to usv. By default, any string entered in this attribute will be a ‘UserModel’ reference object which has some pre-filled values. Let us assume that we need some extra inputs (in addition to the sensed static pressures) to the user routine to be processed in our control logic. For this reason, we need to modify this ‘UserModel’ reference object.

(7)

As seen in Figure 3, a single integer number is defined (ProtectionCode) in its “Integers” folder.

Likewise, four real numbers are defined (Time_Constant, Opening_DP_(bar), Max_Dia and Slope) in its

“Real Numbers” folder (see Figure 4). In its “Strings” folder, a character string in the first row is defined as ‘dum’. In its “RLT Variables” folder, attribute “RLT Variable Names” is set to “ign” not to pass any RLT variable into the user routine. Note that one can use the Value Selector (by right-clicking in the cell) to choose any available RLT variable to be passed into the user routine.

Figure 3 - Setting the integers argument list in ‘UserModel’

Figure 4 - Setting the real numbers argument list in ‘UserModel’

(8)

Check the box for attribute “Plot Flag” in its “Plots” folder to generate a single plot from the variables defined in the user routine (see Figure 5). Here, attribute “Plot Identifier” is set to “ign” since it is not used in the code (or does not show up on the plot in GT-POST), and it simply serves as a convenient method to identify the plot that will be generated.

Figure 5 - Activating “Plot Flag” to generate a plot in ‘UserModel’

After completing these settings, drag the uservalve object into the model map. Connect both sensor parts to the uservalve part to send static pressures as input data to the user routine (see Figure 6). Note that link numbers (i.e. 1 and 2) on the uservalve object indicate the order of input data.

Figure 6 - Sending input data to the user routine through sensors

(9)

Step 3: Adding Actuator

Add an ‘ActuatorConn’ connection object between uservalve part and valve object (part number 14).

Create a link from uservalve to actuator to receive the output from user routine (orifice diameter), and create another link from actuator to valve and select “Orifice Diameter” from the list of actuated quantities (see Figure 7). Note that “Orifice Diameter” input to valve object is defined in millimeters in GT-SUITE (see “Input Signal Editor” window for part 14). Thus, one should be careful with the units of all exchanged data from/to GT-SUITE. After the first simulation time step, control logic implemented in the user routine will start updating the orifice diameter by overriding its value via the actuator part. This update will continue at each time step until the simulation ends.

Figure 7 - Receiving user routine output data through an actuator

(10)

Modification of the User Routine: USERHARNESS

In this GT-SUITE example model, the user routine named subroutine USERHARNESS, which is located in UserSubroutine.F, is called by GT-SUITE and executed at every time step because the model contains an object derived from the ‘UserSubroutine’ template. Before going further, the user should be aware of the fact that the algorithm in this subroutine is designed to demonstrate the utilization of user routines for this particular example. Hence, one should modify only the allowed sections of this subroutine to develop their own algorithm. The following sub-sections present the structure of this subroutine to let the users realize how it should be modified.

Modules

Remember that the module named GTIUSR_INTERFACE must be declared in this subroutine since an explicit interface is applied. This module is supplied by GTI. Any other module defined by the user and/or supplied by GTI can be added before the declarations of variables since the module declaration statements with the USE associations must occur before any other statements in a routine.

Note:

GT-SUITE uses FORTRAN 90, and module procedures may contain data, subroutine(s) and/or functions.

Arguments

Declarations of dummy subroutine arguments associated with an INTENT attribute must be kept in the subroutine since they pass input data from GT-SUITE or return the results from the subroutine to GT- SUITE when the subroutine is called by GT-SUITE during the simulation. The arguments passing input data and their descriptions are:

• istep: Current time step count

• imod: Index of the ‘UserModel’ reference object (Here, imod = 1)

Note: User may create multiple ‘UserModel’ objects in GT-SUITE. In this case, user can set flags using their input folders, and allow the execution of specified calculations for the desired

‘UserModel’ object(s) by adding “IF” statements into the code.

• idharn: ID of the ‘UserSubroutine’ part that is being executed (Here, idharn = 1)

Note: User may create multiple ‘UserSubroutine’ parts. In this case, user can identify each

‘UserSubroutine’ part by calling GTI-provided external routines, GET_USER_HARN_NAMES and GET_USER_HARN_ID to obtain its name and part ID. With these information, user can allow the execution of specified calculations for the ‘UserSubroutine’ part(s) by adding “IF”

statements into the code.

• uharn: Sensor variable array which contains the ‘UserSubroutine’ inputs (flow static pressures sensed from pipe parts – uharn(1): static pressure of the intake pipe, uharn(2): static pressure of the angle branch pipe )

Note: User should coordinate the array indices by referring to the ‘UserSubroutine’ input signals and its input port numbers.

• nuharn: Size of sensor variable array

(11)

(Here, nuharn = 2 since there are two input ports to the ‘UserSubroutine’ part)

• nyharn: Size of actuator variable array

(Here, nyharn = 1 since there is only one output port from the ‘UserSubroutine’ part)

• dt: Current time step size

The argument passing the output data and its description is:

• yharn: Actuator variable array which is the ‘UserSubroutine’ output (yharn(1): orifice diameter of the angle branch pipe)

Note: User should coordinate the array indices by referring to the ‘UserSubroutine’ output signals and its output port numbers.

Local Variables

Local variables are grouped under two categories: variables whose declarations (and executions) must stay in the subroutine and remains unchanged; and the ones whose declarations (and executions) depend on the design of the user’s algorithm.

Indeed, local variables, whose declarations cannot be changed, are later assigned by the arrays (which are set in the ‘UserModel’ reference object) with a call to subroutine ‘LOAD_USER_MODEL_ARRAYS’.

These variables are:

• intparm: An array holding integers provided by the user (Integer Values)

• realparm: An array holding real numbers provided by the user (Real Numbers)

• charparm: An array holding strings of characters provided (Character Strings)

• rltparm: An array holding values of the RLT variables defined by the user

• n_ints: Size of an integer numbers array

• n_reals: Size of a real numbers array

• n_rlts: Size of an array storing RLT variables

• n_chars: Size of a string array

Note that, indices of these arrays match the order of data entry in the ‘UserModel’ folders.

In this tutorial;

n_ints = 1, intparm (1) = 999, n_reals = 4, realparm (3) = 22 etc.

Essentially, ‘LOAD_USER_MODEL_ARRAYS’ returns the arrays and their sizes for each ‘UserModel’

object from GT-SUITE. The call to this routine should not be changed since it is part of the GTI-supplied code. Program executable statements to be written by the user must be placed after this call.

(12)

Existing Algorithm and Its Modification

There are some important points to make clear in the current algorithm of USERHARNESS. The most crucial one, which should always be remembered, is that the current algorithm that updates the output is just a demonstration.

Currently, there is a call to subroutine GET_GLOBAL_INFO to obtain the current simulation time (‘time’). At this point, this call is necessary since we want to generate a plot of orifice diameter versus simulation time. Generally, GET_GLOBAL_INFO, which uses optional arguments for global variables, is one of the external routines that can be called within all user files to access global variables in order to employ them locally in the user routines.

The current algorithm has some error-checking. It stops running the program and gives an error message if ‘n_ints’ is equal to 0, or intparm(1) is equal to 999 and ‘n_reals’ is less than 4 (by use of STOP statements in the IF control blocks). Keep in mind that this algorithm is designated for this specific example model (UserRoutine.gtm), and it functions well as it is written as long as these conditions are ensured. Nevertheless, the user can change all these control statements if desired.

After obtaining the updated value of orifice diameter ‘yharn (1)’, the plot storage subroutine USERPLOTSTORE is called to create a plot of orifice diameter versus simulation time ‘time’. The user can make appropriate changes to get the plot(s) of preferred variable sets or just ignore calling this subroutine. Notice that, the plot flag must also be set to “on” in the ‘UserModel’ reference object for each requested plot.

Once coding is finished, all user files must be compiled into a single .dll (on Windows) or a shared object library (on Linux). For the compilation instructions on different platforms, please refer to the manual, UserRoutines.pdf located under …\GTI\v7.4.0\documents\Co-Simulation_And_UserRoutines.

(13)

Tutorial 2: External Cylinder Model

Time integration for a model utilizing GT-SUITE’s external cylinder facility involves two distinct phases. At specified crank angles between IVC (intake valve closure) and EVO (exhaust valve opening), the external code is used for in-cylinder modeling.

In general, the external code should begin at IVC and end its computation at EVO. The external cylinder interface, however, is not constrained to align precisely with these events, and the user may specify desired starting and ending crank angles for external cylinder model use as long as the cylinder is closed (i.e., entirely between IVC and EVO). Note that for cases when IVC and EVO are not used for starting and ending angles respectively (generally not recommended), standard GT-SUITE in-cylinder models will be used for portions of the closed cylinder processes not modeled by the external cylinder.

Initial conditions for the engine cylinder solution are provided by GT-SUITE to the external code at a user specified starting angle that must be at or after IVC. In principle, no further communication is required until a user specified ending angle that precedes EVO. However, in some instances, one may desire to provide additional information to the cylinder model (e.g., injection rate) during the period when external code is active. Conversely, one may desire to obtain some information from the external code to be sent back to GT-SUITE, so that they can be stored or manipulated for reporting purposes (e.g., plotting) or passed as inputs to the mechanical components (e.g., crank-slider mechanism).

At a user specified ending angle, the communication between GT-SUITE and the external code is discontinued until it is reestablished at a user specified starting angle of the next cycle.

Time diagram of external cylinder coupling

(14)

Settings within GT-SUITE

Let us assume that we have already created a model of a single cylinder DI engine, and our objective is to control all the aspects of cylinder modeling between IVC and EVO. This model which is called UserEngCylinder_base.gtm represents our system as the starting point of this tutorial (see Figure 8), and it is located under %GTIHOME%\v7.4.0\tutorials\Co-Simulation_And_UserRoutines\UserRoutines (%GTIHOME% is the GT-SUITE installation directory such as C:\GTI).

Figure 8 – Single cylinder DI engine

(15)

Step 1: Modification of the “EngCylinder’ Object

To start, launch GT-ISE. Open the base model for this tutorial,

UserEngCylinder_base.gtm

and save it with

a different name (e.g. UserEngCylinder.gtm)

in your working directory.

Within GT-ISE, the user cylinder routine is called by the ‘EngCylinder’ object as long as its

“External Cylinder Model Object” attribute in its “Advanced” folder points to an

‘EngCylExtMod’ reference object. By default, all values of the ‘EngCylinder’ object attributes in its “Advanced” folder are set to “ign” (see Figure 9).

In order to refer to the ‘EngCylExtMod’ object:

• Double click on the ‘EngCylinder’ part (cylinder) on the map

• Click on the “Edit Object” button (part override may be used as well)

• Type name of the external cylinder model (external_cyl) in the object value field of its

“External Cylinder Model Object” attribute

• Double click on external_cyl and select ‘EngCylExtMod’ as the reference template (see Figures 10 and 11).

Figure 9 – Default values for the “Advanced” folder of ‘EngCylinder’

(16)

Figure 10 – Defining the external cylinder model object

Figure 11 – Selection of the reference template as’ EngCylExtMod’

(17)

Step 2: ‘EngCylExtMod’

Once the ‘EngCylExtMod’ object is created, enter the following values in its fields (see Figure 12).

The “User Model Name” attribute must point to the ‘UserModel’ object (user), which passes integers, real numbers, character strings, RLT variables and plot request flags into the user model. Set the

“Starting Cycle Number” value to “def”, so that the user routine will be called at the first cycle. Choose the “imposed” option from dropdown list of the “Calculation Window Specification” in order to let the user routine be executed between the angles entered in the following angles (starting and ending angles).

Note that, these angles (i.e. -80^O and 80^O) will be used throughout the entire simulation since the

“imposed” calculation window is selected. Then, save all changes within the model.

Please refer to the GT-SUITE manuals for detailed information on the usage of templates.

Figure 12 – Settings for the ‘EngCylExtMod’ object

(18)

Modification of the User Routine: USERENGCYLINDER

For this tutorial, the user routine of interest is named subroutine USERENGCYLINDER, which is located at …\v7.4.0\usrfiles in a FORTRAN source file named EngCylinder_External.F. This subroutine is called by GT-SUITE and executed at every time step because the GT-SUITE model whenever an object derived from the ‘EngCylExtMod’ template is referenced in the GT-SUITE model. Note that when first opened, the subroutine contains code designed to demonstrate the implementation of user external cylinder model within GT-SUITE. An external cylinder model developer should modify this subroutine according to develop his or her custom model algorithm.

The interface and a complete list of arguments of this routine are given below:

subroutine USERENGCYLINDER (nc,imod,ivcflag,icombe,ifrac,rpm,

& thetanext,dthet,volnext,volold,totmas,totnrg,gpres,gtemp,

& dw1,wiebeo,mspec,fm,fmairu,fmfuv,fmful,fmairb,fmfb,mxoxy,

& moxy,mxnitr,mnitr,mxfvap,mfvap,mxfliq,mfliq,gtke,gtlen,

& gswrt,gturt,ghtran,tpist,thead,tlinr) Arguments

integer, intent (IN)



nc – Cylinder number



imod – 'UserModel' object index



ivcflag - Flag to capture IVC condition (2 = at IVC)



^ifrac ^–A flag to keep tracking mass fractions of species



mspec – Total number of species



mxoxy – Number of unburned Oxygen species



moxy(mxoxy) – Array indices for unburned Oxygen species



mxnitr – Number of unburned Nitrogen species



mnitr(mxnitr) – Array indices for unburned Nitrogen species



^mxfvap ^–Number of unburned vaporized fuel species



mfvap(mxfvap) – Array indices for unburned vaporized fuel species



mxfliq – Number of unburned liquid fuel species



mfliq(mxfliq) – Array indices for unburned liquid fuel species real, intent (IN)



rpm – Engine speed [rev/min]



thetanext - Crank angle of the cylinder at the current time step in [degrees]



dthet – Current timestep size [CA - degrees]



^volnext ^–Cylinder volume at the current time step in [m³]



^volold ^–Cylinder volume at the previous time step in [m³]



gtke – Turbulence intensity in [m²/sec²]



gtlen – Turbulence length scale in [m]



tpist – Piston temperature in [K]



thead – Head temperature in [K]



tlinr – Liner temperature in [K]



^totnrg ^–Total internal energy of cylinder content [J]

(19)

real, intent (INOUT)



totmas – Mass of the cylinder content in [kg]



^gpres ^–In-cylinder pressure at the current time step in [Pa]



gtemp - In-cylinder temperature at the current time step in [K]



wiebeo – Fraction of cumulative fuel burned



fmairu – Mass fraction of unburned air



fmfuv – Mass fraction of unburned vapor fuel



fmful – Mass fraction of unburned liquid fuel



^fmairb ^–Mass fraction of burned air



fmfb – Mass fraction of burned fuel



gswrt – Swirl ratio



gturt – Tumble ratio



fm – Mass fractions of mixture composition integer, intent (OUT)



icombe – A flag to control the combustion event (0 = before; 1 = during/after)

real, intent (OUT)



ghtran – In-cylinder heat transfer in [Watts] (positive if into the wall)



^dw1 ^-Fraction of fuel burned during the current time step NOTES:

o A user may create multiple ‘UserModel’ and ‘EngCylExtMod’ objects in GT-SUITE. If multiple objects are used, the user can set flags using the input folders of these ‘UserModel’ objects, and allow the execution of specified calculations for the desired ‘EngCylExtMod’ object(s) by adding

“IF” statements into the code.

o Fluid composition is tracked in very different ways depending on the ifrac flag value (which is passed into the user code). When ifrac equals to 1 (i.e., ‘EngCylExtMod’ > Species Description for Exchange > “detailed”), the fm array should read as the species mass fraction array and can be updated according in-cylinder processes that are being modeled. For this case, the symbols fmairu, fmfuv, fmful, fmairb, and fmfb are ignored by GT-SUITE. In contrast, if ifrac equals to 2 (i.e.,

‘EngCylExtMod’ > Species Description for Exchange > “lumped”) the fm array should not read or updated and instead scalars corresponding to broader mixture definitions should read and be reassigned. These scalars are fmairu – representing unburned air mass fraction, fmfuv – representing unburned vapor fuel, fmful – representing unburned liquid fuel, fmairb – representing burned air and fmfb – representing burned fuel.

o When ifrac equals 1 (i.e., ‘EngCylExtMod’ > Species Description for Exchange > “detailed”), the array fm(1:mspec) consists of fractions of user-defined species, followed by an additional "burned"

species. The order of the species in the array fm(1:mspec) and other species arrays follows a particular set of order rules. The first rule is that all user-defined species precede all “burned”

species. For the user-defined species whole groups of fluid species will be first be ordered according to the GT-SUITE fluid template the species it is derived from. The species group order is always

‘FluidGas’ first, followed by ‘FluidLiqCompressible’, ‘FluidLiqIncompress’, and ending in

‘FluidNASA-LiqGas’ objects. Within these groups the species order is alphabetical. For models that include any ‘EngCyl*’ part, it is always true that after all of these user-defined species, “burned”

(20)

species that are not defined in GT-ISE are appended to the end of the species list in the following relative order:

1) CO2 2) H2O 3) N2 4) O2 5) CO 6) H2 7) H 8) O 9) OH 10) NO 11) N 12) Ar 13) SO2

NOTE: Ar and SO2 will be present only if they exist in the GT-SUITE model

Although this order is consistent, it is good practice for a particular model to always check that the species order has been interpreted in the user code correctly. This can be done by referencing the namfl character array in the scope of the USERENGCYLINDER subroutine, which lists the names of the different species in the same order as the fm species mass fraction array and other species- length arrays.

Prototype Algorithm for USER ENGCYLINDER Subroutine

The user routine is responsible for the calculation of in-cylinder fuel injection, combustion, heat transfer, mass, species, and energy conservation and emissions. A skeletal algorithm is provided and explained below. Note that this provided code does not represent an acceptable modeling standard and is just presented here for demonstration purposes; the code segments shown below are simply placeholders that should be replaced by realistic models.

• Access GTI provided routines and the variables declared in the property module use GTIUSR_INTERFACE

use user_prop_module, only : mspecbasic, ifuel, iproptyp, fm1, namfl o mspecbasic

-

Number of basic species defined by the user

o

ifuel

-

An integer type of flag to see species characteristic (2 = fuel)

o

iproptyp

-

An integer type of flag to see species property type

1 = gas; 2 = incompressible liquid; 3 = compressible liquid o fm1

-

Work array (whose size equals to total number of species) o namfl

-

A character array to get the names of species

• Call GTI provided routine GET_GLOBAL_INFO to get the time step

call GET_GLOBAL_INFO(ISTEP=istep)

• Print mass fractions of unburned liquid fuel species and their names at the first time step if (istep .eq. 1) then ! for the first time step

do m=1, mxfliq ! loop over all unburned liquid fuel species write(*,*) mfliq(m), namfl(mfliq(m))

enddo endif

(21)

• Store IVC values

if (ivcflag .eq. 2) then ! Capture IVC

pivc(nc) = gpres ! Pressure tivc(nc) = gtemp ! Temperature volivc(nc) = volold ! Volume

! Get mass fractions of species

if (ifrac .eq. 2)then ! if species are “lumped”

airuivc(nc) = fmairu ! mass fraction of unburned air

fuvivc(nc) = fmfuv ! mass fraction of unburned vapor fuel fulivc(nc) = fmful ! mass fraction unburned liquid fuel airbivc(nc) = fmairb ! mass fraction burned air

fbivc(nc) = fmfb ! mass fraction burned fuel else ! if the “detailed” option is selected

! initialization combcumo(nc) = 0 airuivc(nc) = 0.0 fuvivc(nc) = 0.0`

fulivc(nc) = 0.0 airbivc(nc) = 0.0 fbivc(nc) = 0.0

do 10 m = 1, mspec ! loop over all species

if(m .le. mspecbasic)then ! only user-defined species

! if species is liquid fuel

if (ifuel(m) .eq. 2 .and. iproptyp(m) .gt. 1)then

! get mass fraction unburned liquid fuel fulivc(nc) = fulivc(nc) + fm(m)

! if species is vapor fuel

elseif (ifuel(m) .eq. 2 .and. iproptyp(m) .le. 1)then

! get mass fraction of unburned vapor fuel fuvivc(nc) = fuvivc(nc) + fm(m)

! for the rest of user-defined species else

! get mass fraction of unburned air airuivc(nc) = airuivc(nc) + fm(m) endif

! for the burned species else

! get mass fraction burned air airbivc(nc) = airbivc(nc) + fm(m) endif

10 enddo ! end of loop

! update the values based on unburned fuel-air ratio

fbivc(nc) = airbivc(nc)* (fuvivc(nc)+fulivc(nc))/airuivc(nc) airbivc(nc) = airbivc(nc) - fbivc(nc)

endif endif

• Report heat transfer values (Direction: positive if into wall) httran = 0.0

do 20 i = 1,3 ! loop over its components (1=piston,2=head,3=liner) ghtran(i) = 0. ! heat transfer is not considered here

httran = httran + ghtran(i) 20 enddo

(22)

Combustion progress

combcum = 0. ! fraction of cumulative fuel burned (new) icombe = 0 ! set the combustion flag (before combustion)

! Check the current crank angle if(thetanext .lt. 180.)then thcomb1 = -5. !

thcomb2 = 45. ! regular combustion else

thcomb1 = 340. !

thcomb2 = 370. ! negative overlap combustion if(thetanext .lt. thcomb1) then

combcumo(nc) = 0.0 endif

endif

if(thetanext .lt. 180. .and. thetanext .gt. thcomb1) then icombe = 1 ! combustion occurs

endif

if (thetanext .gt. thcomb1 .and. thetanext .lt. thcomb2) then xx = (thetanext-thcomb1)/(thcomb2-thcomb1)

combcum = xx - sin(xx*2.*pi)/(2.*pi) endif

if (thetanext .ge. thcomb2) combcum = 1.

if(combcum .lt. combcumo(nc))then

combcumo(nc) = combcum ! fraction of cumulative fuel burned (old)

• Energy solution, update mixture composition and flow field variables If (ifrac .eq. 2) then ! “lumped” species

! dummy energy solution call GET_GLOBAL_INFO(DT=dt)

faratio = (fuvivc(nc)+fulivc(nc)) / airuivc(nc) phi = max(faratio * 14.5, 0.00001)

useable = min(phi,1.) / phi

unbrndfuel = fuvivc(nc)+fulivc(nc)

delh = combcum*44.2e6*useable*unbrndfuel-(sum(ghtran(1 :3))*dt dcombt = delh / 1200.

gamc = 1.35

gtemp = tivc(nc) * (volivc(nc)/volnext)**(gamc-1.) + dcombt gpres = pivc(nc) * (gtemp/tivc(nc)) * (volivc(nc)/volnext)

! composition recalculation

fmairu = airuivc(nc) * (1.-combcum) fmfuv = fuvivc(nc) * (1.-combcum) fmful = fulivc(nc) * (1.-combcum)

fmairb = airbivc(nc) + airuivc(nc) * combcum

fmfb = fbivc(nc) + fuvivc(nc) * combcum + fulivc(nc) * combcum else ! “detailed” species

! calculate the burned gas composition

dw1 = combcum - combcumo(nc) ! fraction of fuel burned (this time step) combcumo(nc) = combcum ! update the old value

wiebeo = combcum ! fraction of cumulative fuel burned

sumu = 0. ! sum of mass fractions of unburned species (initialization) sumb = 0. ! sum of mass fractions of burned species (initialization) do 30 m=1,mspec ! loop over all species

! burned mass composion before combustion of the current parcel

(23)

if(m .le. mspecbasic) then ! for user-defined species fm1(m) = fm(m) * dw1 ! pass to species work array fm(m) = fm(m) * (1.0 - dw1) ! update

else ! update burned species mass fractions fm1(m) = fm(m) * combcum

fm(m) = fm(m) * (1.0 - combcum) endif

sumb = sumb + fm1(m) sumu = sumu + fm(m) 30 enddo

! restore fm and just account for compression/expansion if(sumb .lt. 1.e-6)then

do 35 m=1,mspec

fm(m) = fm(m) + fm1(m)

35 enddo

dw1 = 0.

wiebeo = 0.

goto 70 endif

do 40 m=1,mspec

if(sumb .gt. 0.0)fm1(m) = fm1(m) / sumb if(sumu .gt. 0.0)fm(m) = fm(m) / sumu 40 enddo

! burn the current fuel

call GTITHRM_TP_EQ (gtemp,gpres,fm1,rhodum,enerdum,enthdum,cpdum,cvdum)

! new mixture composition sum2 = 0.

do 50 m=1,mspec

fm(m) = fm(m) * sumu

if (m .gt. mspecbasic) fm(m) = fm(m) + fm1(m) * sumb sum2 = sum2 + fm(m)

50 enddo

do 60 m=1,mspec

fm(m) = fm(m) / sum2 60 enddo

! calculate new pressure and temperature etc.

70 continue pold = gpres

source = 0.0; vel2 = 0.0 rhos = totmas/volnext dvol = volnext-volold do 80 jj=1,2

pdv = 0.5*(gpres+pold) * dvol

ener = (totnrg - pdv -httran + source) / totmas - vel2 call GTITHRM_RE (rhos,ener,fm,gtemp,gpres,enth,cp,cv) 80 enddo

endif

Pre-compiled Inquiry Procedures

User routines (i.e., subroutines with open source code like USERENGCYLINDER) pass information to and from the external code and GT-SUITE via its argument list. In addition to information passed through this argument list, there is an interface for the external code developer to optionally retrieve

(24)

many different additional GT-SUITE model parameters by programming calls to pre-compiled inquiry procedures (i.e. procedures built by GTI without viewable source code).

Pre-compiled inquiry procedures provide useful information pertaining to many areas such as species thermo-physical properties, cylinder geometry, valves, injectors, flow field characterizations etc. When coupling with external cylinder models, it is highly recommended to utilize GT-SUITE’s thermo-physical property routines from within the external code so that species properties are consistent throughout the simulation. This information can be accessed by external code by using a FORTRAN module named user_prop_module and thermo-property routines such as GTITHRM_TP. In a similar fashion, cylinder data can be accessed using the GTI-supplied subroutine GET_CYLINDER_INFO, injector data from GET_INJECTOR_INFO, and valve data from GET_VALVE_INFO.

The module GTIUSR_INTERFACE must be used in the external code to access any pre-compiled inquiry procedures. A USE GTIUSR_INTERFACE statement must be added into external code before the declaration of any variables in that procedure. In the next sub-sections, these routines the purpose as well as interface specifications are described.

Module USER_PROP_MODULE

Mixture composition data used in the GT-SUITE model are available with the module user_prop_module. A USE statement containing this module name along with its data objects (declared in the module) must be added into the routine before the declaration of any variables.

For example, to obtain the array having the names of species defined in the model, the use statement should read:

use user_prop_module, only : namfl

This introduces the namfl character array into the scope of the external code, where it might be useful to verify species array indices.

Variables accessible from the "user_prop_module"

mspecbasic

-

An integer indicates the number of basic species defined by the user mspec

-

An integer indicates the total number of species

mspec

=

mspecbasic

+

11 (or 13), 11 (or 13) is for the burned species

Burned Species

1) CO₂ 2) H₂O 3) N₂ 4) O₂ 5) CO 6) H₂ 7) H 8) O 9) OH 10) NO 11) N 12) Ar 13) SO₂

NOTE: Ar and SO₂ will be present only if they exist in the GT-SUITE model pmwt(mspec)

-

A real number indicating species molecular weight [g/mole]

ifuel(mspec)

-

An integer flag indicating fuel species (ifuel=2 → fuel) namfl(mspec)

-

A character array containing ordered names of species iproptyp(mspec)

-

An integer type of flag to see species property type

1 = gas; 2 = incompressible liquid; 3 = compressible liquid patom(i,mspec)

-

An integer array giving atomic information for species (i = 1,4)

patom(1,mspec) - Number of Carbon atoms

patom(2,mspec) - Number of Hydrogen atoms

patom(3,mspec) - Number of Oxygen atoms

patom(4,mspec) - Number of Nitrogen atoms

(25)

fm1

-

Work array (mspec number of elements) fm2

-

Work array (mspec number of elements) Subroutine LOAD_USER_MODEL_ARRAYS

This routine returns data defined in the ‘UserModel’ object referred by ‘EngCylExtMod’.

The interface and a complete list of arguments of this routine are given below.

subroutine LOAD_USER_MODEL_ARRAYS (imod,n_ints,n_reals,n_chars,n_rlts,

& intparm, realparm,charparm rltparm)

integer, intent (IN)



^{imod -}‘UserModel’ index integer, intent (OUT)



^n_ints ^-Size of an integer numbers array



n_reals - Size of a real numbers array



n_chars - Size of a string array



n_rlts - Size of an array storing RLT variables



n_rlts - Size of an array storing RLT variables



intparm - An array holding integers provided by the user

real, intent (OUT)



realparm - An array holding real numbers provided by the user



rltparm - An array holding values of the RLT variables defined by the user character (LEN = *), intent (OUT)



charparm - An array holding strings of characters provided by the user

Subroutine GET_GLOBAL_INFO

Some global simulation variables are accessible using the GET_GLOBAL_INFO subroutine. The subroutine is programmed with FORTRAN 95 optional arguments, allowing the only desired arguments to be programmed in any order as long as the appropriate keywords are used.

For example, to get just the time step counter, time, and time step size, the call could be call GET_GLOBAL_INFO(ISTEP = istep, TIME = time, DT = dt)

subroutine GET_GLOBAL_INFO (mperiod, idrvopt, ifinalper, icase, istep,

& istepp, icycle, time, dt, theta, modelname) integer, optional, intent (OUT)



mperiod - Time control flag

(26)

0 = for continuous

1 = for periodic



idrvopt - Optimization type

0 = if off, or during final post-iteration run

1 = while running iterations for "target" optimization

3 = while running iterations for "OptimumMax" optimization

4 = while running iterations for "OptimumMin" optimization



^ifinalper ^-Final cycle flag 0 = if not final cycle

1 = if final cycle



^icase ^-Case number



istep - Time step counter



istepp - Time step counter in current cycle ( = 0 on the last step of cycle)



icycle - Cycle number for periodic runs real, optional, intent (OUT)

 time - Current simulation time [sec]

 dt - Current time step size [sec]



theta - Current crank driver angle (for periodic simulations) [degrees]

character (LEN = *), optional, intent (OUT)

 modelname - Model name (without file extension)

Subroutine GET_CYLINDER_INFO

Some cylinder variables are accessible using the GET_CYLINDER_INFO subroutine, which is called with one non-optional argument for the cylinder number, followed by FORTRAN 95 optional arguments.

For example, to obtain cylinder bore and stroke for cylinder 1, the call can be call GET_CYLINDER_INFO(1, BORE = bore, STROKE = stroke)

subroutine GET_CYLINDER_INFO (nc, bore, stroke, pinoffset, compratio,

& conrodlength, trpdlambda, efflambda, airtrpd, fueltrpd,

& vapfuelfrac, volefref, volefman, clrheight, portno) integer, intent (IN)



^nc ^–Cylinder number

real, optional, intent (OUT)



^bore ^–Cylinder bore [m]



^stroke ^-Cylinder stroke [m]



pinoffset - Wrist pin to crank offset [m]



compratio - Compression ratio



conrodlength - Connecting rod length [m]



trpdlambda - Trapped lambda at cycle start



efflambda - Effective lambda (at the end of combustion)

(27)



airtrpd - Trapped air [kg]



fueltrpd - Trapped fuel [kg]



vapfuelfrac - Fuel vapor fraction



volefref - Reference volumetric efficiency



volefman - Manifold volumetric efficiency



^clrheight ^-Clearance height [m]

integer, optional, intent (OUT)

portno - port number with which connected to the cranktrain Subroutine GET_INJECTOR_INFO

Injector data are available using the GET_INJECTOR_INFO subroutine, which is called with one non- optional argument for the injector index, followed by FORTRAN 95 optional arguments for the desired data. For example, to obtain the name and mass flow rate of the injected fluid for the injector whose index is 2, the call can be

call GET_INJECTOR_INFO(2, NAME = name, MASSFLOWRATE = massflowrate)

subroutine GET_INJECTOR_INFO (inj,name,typ,numholes,holediameter,

& dischargecoef,temperature,pressure,massflowrate,

& velocity,enthalpyrate,mliquid,mvapor,fvapor) integer, intent (IN)



inj – Injector index



name – Name of the injector integer, optional, intent (OUT)



typ - Type of the injector

1 = ‘InjProfileConn’

3 = ‘InjAF-RatioConn’ (proportional to remote flow, instant) 4 = ‘InjAF-RatioConn’ (proportional to local flow)

5 = ‘InjRateConn’

6 = ‘InjMeanValueConn’

7 = ‘InjAF-RatioConn’ (proportional to remote flow, averaged) 8 = ‘InjPulseConn’ or ‘InjAFSeqConn’

9 = ‘InjNozzConn’

10 = ‘EjectorConn’

12 = ‘InjMultiProfileConn’



numholes - Number of holes per nozzle



mliquid - Species index of injected liquid



mvapor - Species index of corresponding vapor

(28)



holediameter – Nozzle nole diameter [m]



dischargecoef – Nozzle discharge coefficient



temperature – Fluid temperature [K]



pressure – Fluid pressure [bar]



massflowrate – Fluid mass flow rate [kg/s]



velocity – Fluid velocity [m/s]



enthalpyrate – Enthalpy flow rate [J/s]



^fvapor ^–Mass fraction of the vaporized liquid immediately after injection NOTES:

• For ‘InjMeanValueConn’ (typ = 6) or ‘InjNozzConn’ (typ = 9) type injectors, all arguments except name and type have no meaning and will just be returned as zero.

• For ‘InjAF-RatioConn’ (typ = 3 and typ = 4), ‘InjRateConn’ (typ = 5), ‘InjAF-RatioConn’

(typ = 7), and ‘EjectorConn’ (typ = 10) type injectors, the following arguments have no meaning will be just returned as zero: numholes, holediameter, dischargecoef, pressure, velocity

Subroutine GET_VALVE_INFO

Valve data are accessible using the GET_VALVE_INFO subroutine, which is called with one non- optional argument for the valve index, followed by FORTRAN 95 optional arguments for the desired data.

subroutine GET_VALVE_INFO (nv,name,typ,lift,velocity,massflowrate,

& enthalpyrate,fm,massflowratepuddle,enthalpyratepuddle,fmpuddle) integer, intent (IN)



nv – Valve index



name – Name of the valve integer, optional, intent (OUT)



typ - Valve type (1 = exhaust; 2 = intake)



lift – Lift [m]



^velocity ^–Velocity [m/s]



massflowrate – Mass flow rate (excluding puddle) [kg/s]



enthalpyrate – Enthalpy flow rate (excluding puddle) [J/s]



fm(mspec) – Mass fractions of species (excluding puddle)



massflowratepuddle – Puddle mass flow rate [kg/s]



enthalpyratepuddle – Puddle enthalpy flow rate [J/s]



fmpuddle(mspec) - Puddle mass fractions

(29)

NOTES:

• When the valve is connected to 'FlowSplitPort' or 'PipePort' parts, the fuel puddle can flow through the valve. The following quantities refer to the transport of this fuel puddle:

massflowratepuddle, enthalpyflowratepuddle, fmpuddle

• The following quantities refer to the total flow through the valve, excluding any fuel puddle flow: massflowrate, enthalpyflowrate, fm

• The array fm(:) consists of the user-defined species, followed by the 11 (or 13) "burned" species:

1) CO2 2) H2O 3) N2 4) O2 5) CO 6) H2 7) H 8) O 9) OH 10) NO 11) N 12) Ar 13) SO2

NOTE: Ar and SO2 will be present only if they exist in the GT-SUITE model

• The order of the user-defined species in the array fm(:) is the same as in the array namfl(:) which contains the names of the different species. This allows verifying the order of the user- defined species in fm(:). namfl(:) is in the module USER_PROP_MODULE.

Subroutine GETMOLFRAC

This routine returns mole fractions of species for given mass fractions.

subroutine GETMOLFRAC (fm,ym)

real, intent (IN)



^{fm(*) –}Mass fraction array real, intent (OUT)



^{ym(*) –}Mole fraction array NOTES:

1) CO2 2) H2O 3) N2 4) O2 5) CO 6) H2 7) H 8) O 9) OH 10) NO 11) N 12) Ar 13) SO2 NOTE: Ar and SO2 will be present only if they exist in the GT-SUITE model

Subroutine GETMASSFRAC

This routine returns mass fractions of species for given mole fractions.

subroutine GETMASSFRAC (ym,fm)

real, intent (IN)



ym(*) – Mole fraction array

real, intent (OUT)



fm(*) – Massfraction array NOTES:

(30)

1) CO2 2) H2O 3) N2 4) O2 5) CO 6) H2 7) H 8) O 9) OH 10) NO 11) N 12) Ar 13) SO2 NOTE: Ar and SO2 will be present only if they exist in the GT-SUITEmodel

Subroutine GTITHRM_RE

This routine returns temperature, pressure, static enthalpy, and specific heats for an input density, specific energy, composition and initial pressure and temperature according to the GT-SUITE property model.

subroutine GTITHRM_RE (rho, ener, fm, temp, pres, enth, cp, cv) real, intent (IN)



rho – Density [kg/m³]



ener – Specific energy [J/kg]



fm(*) – Mass fraction array of species real, intent (INOUT)



temp – Temperature [K]



^{pres –}Pressure [Pa]

real, intent (OUT)



enth – Specific enthalpy [J/kg]



cp – Heat capacity at constant pressure [J/kg/K]



cv – Heat capacity at constant volume [J/kg/K]

NOTES:

Subroutine GTITHRM_RE_EQ

This routine returns temperature, pressure, static enthalpy, specific heats, and new composition at equilibrium for a given density, specific energy, and initial composition and initial pressure and temperature. Density and specific energy are held constant.

(31)

subroutine GTITHRM_RE_EQ (rho, ener, fm, temp, pres, enth, cp, cv) real, intent (IN)



fm(*) – Mass fraction array of species



^{temp –}Temperature [K]



pres – Pressure [Pa]

real, intent (OUT)



NOTES:

Subroutine GTITHRM_TP

In a call to this routine, the user passes in temperature, presssure and an array that consists of the mass fractions of all species. The routine will return the density, the specific energy, the static enthalpy and the specific heats. The composition array normally remains unchanged for this call except for a cavitating fluid. For the cavitation event, fractions of vapor and liquid phases are recalculated within the subroutine.

subroutine GTITHRM_TP (temp, pres, fm, rhos, ener, enth, cp, cv) real, intent (IN)



fm(*) – Mass fraction array of species (changed ONLY for cavitating fluids) real, intent (OUT)



rhos – Density [kg/m³]

(32)



NOTES:

Subroutine GTITHRM_TP_EQ

This routine is nearly identical to subroutine GTITHRM_TP except that the call to this routine will take the species passed within the species mass fractions array and return the equilibrium condition at the user entered temperature and pressure. The new mass fractions will be passed back to the user as well as density, specific energy, specific enthalpy and heat capacities.

subroutine GTITHRM_TP_EQ (temp, pres, fm, rho, ener, enth, cp, cv) real, intent (IN)



fm(*) – Mass fraction array of species real, intent (OUT)



^{enth –}Specific enthalpy [J/kg]



^cp ^–Heat capacity at constant pressure [J/kg/K]



NOTES:

Subroutine GTITHRM_PH

(33)

This subroutine iterates to find the correct temperature and density to satisfy the inputs of pressure, specific enthalpy, and mass fractions of species. It returns the new temperature, density, specific energy and heat capacities.

subroutine GTITHRM_PH (pres, enth, fm, temp, rho, ener, cp, cv) real, intent (IN)



fm(*) – Mass fraction array of species real, intent (INOUT)



temp –

Temperature [K]

real, intent (OUT)



^cp ^–Heat capacity at constant pressure [J/kg/K]



^cv ^–Heat capacity at constant volume [J/kg/K]

NOTES:

Subroutine USERPLOTSTORE

‘UserModel’ has a facility to store plots that can be displayed from the standard GT-POST utility.

These plots are viewable when GT-POST opens a *.gdx file along with the all other plots requested at the part level in GT-SUITE. In order to plot a variable from a user subroutine, the following command line must be added:

call USERPLOTSTORE (imod, plot_number,’label’,’name’,’x_label’,

& ’y_label’,x_variable,y_variable)

The GTI-supplied subroutine USERPLOTSTORE only stores the given data points. In this call, the input arguments are:

• imod

-

‘UserModel’ reference object index (passed into user routine)

• plot_number - Index for user plot (1-10, just needs to be unique for particular user plot)

• label

-

Text for the plot label (must be enclosed in single quotes)

(34)

• name

-

Text for the plot name (must be enclosed in single quotes)

• x_label

-

Text for the x-axis label (must be enclosed in single quotes)

• y_label

-

Text for the y-axis label (must be enclosed in single quotes)

• x_variable

-

X-axis quantity to be added to plot

• y_variable

-

Y-axis quantity to be added to plot

Each call to USERPLOTSTORE creates a single plot for particular variables. This feature works for more than one ‘UserModel’ reference objects. A maximum of 10 plots can be stored for each

‘UserModel’ object in a simulation.

Data Exchange through ‘UserSubroutine’

It is possible to exchange data via signals in the GT-SUITE model using a part derived from the

‘UserSubroutine’ template. Adding a ‘UserSubroutine’ part as part of a GT-SUITE controls model and adding code to the user routine, subroutine USERHARNESS allows the user to model some parts of a GT-SUITE model externally.

Figure 13 – Example of sending user harness output data through an actuator part

subroutine USERHARNESS(istep,imod,dt,uharn,nuharn,yharn,nyharn,idharn) real, intent (IN)



istep – Time step counter



^imod ^–'UserModel' object index

User Routines Tutorials GT-SUITE

GT-SUITE