GT-SUITE
Fortran User Routines Manual
VERSION 2016
by
Gamma Technologies
Copyright 2015 © Gamma Technologies LLC. All rights reserved.
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 LLC.GT Information
GT SUPPORT
© TELEPHONE: (630) 325-5848
+ FAX: (630) 325-5849
+ EMAIL:
[email protected]
© 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 —
dayTable of Contents
TABLE OF CONTENTS
CHAPTER 1: FORTRAN USER ROUTINES.
1.1 Introduction...
1.2 List of Available User and GT-supplied External Routines
1.3. Data Exchange To/From User Routine...
13.1 Input through GT-ISE...
132 Using APIs within User Routines.
13.3 Output through GT-!
134. Plots... .
1.4 Creating User Routines.
1.4.1 Structural Rules of User Routines
1.42 Generating Plots from User Routines 9
SUITE Model *.out File 10
iser Routines into G’
1.43 Writing Messages from
1.5. Compiling and Using User Routines
1.5.1 Compilation on Windows
1.5.2 Compilation on Linux
1.6 Running with User Routines.
1.6.1 Running with User Routines on Distributed,
1.7 Debugging User Routines. se
1.8. Calling a C/C++ Function from Fortran User Routines...
1.9 Compatibility with the Older Versions of GT-SUITE...
1.10 Running User Scripts Before and After a Simulation...CHAPTER 1
CHAPTER 1: FORTRAN USER ROUTINES
1.1 Introduction
GT-SUITE provides the users with the ability to incorporate their own programs into GT-SUITE. The
models developed by the user are called "User Models" or "User Routines". One or more user-defined
routines can be integrated into GT-SUITE in order to meet the user-specified requirements in modeling
certain physical processes (e.g, engine combustion, battery performance, catalyst modeling etc.) or any
«generic process. User models may be implemented by adding user-written code by replacing any of the
allowed sub-models (e.g. hi stion model, battery performance model) within GT-
SUITE. A flexible, general purpose option 'UserCodeFHamness' template also exists.
User routines are not actually used in the simulation unless they are specifically invoked from a template
in the GT-SUITE model, There are number of templates that let the users integrate their own routines and
‘maintain the communication between GT-SUITE and these routines without leaving GT-SUITE during
the simulation.
GT provides to the users the source files for the user subroutines, which are written in Fortran, The
source files are located in the directory %GTIHOME%w20 6\usercode\Fortran\sources (%GTIHOME%
is the GT-SUITE installation directory)
Each subroutine that performs a particular task in conjunction with its application area is provided to
allow the users to develop their own algorithms. The users have a flexibility to create any additional
external routines, which can be programmed in Fortran or another language that can be called from the
Fortran interface routine. This code is compiled into a DLL (or a Shared Object for Linux operating
system) using GI-supplied project file or make file. ‘This newly created DLL/Shared Library is called by
GT-SUITE at each computational time step.
Instructions on the implementation of user routines are given in the tutorial (UserCodeFortran-
tutorials pdf) located in ...\v2016\tutorials\Co-Simulation_And_UserCode\UserCodeFortran, Within this
tutorial, one will find the full list of sub-models that may be modified by a user routine, the templates
with which they are associated and the corresponding subroutines located in the source files.
‘Also — A new tool when using pure C (UserCodeC
UserCodeC is a family of templates which provides a powerful and flexible mechanism for extending
simulation capabilities of GT-SUITE. With this tool, the user can develop a custom algorithm purely
written in C language. The source code is compiled into a library that is loaded when the simulation starts.
Currently, only one member of this family has been released - 'UserCodeCControls.. As its name
suggests, it is a member of the Control library; and similar templates for other domains (i.e. Mechanical,
Flow, ete.) will be available in future versions. Sec ...\v2016\usercode\C\documentation for more details.
1.2. List of Available User and GT-supplied External Routines
Gamma Technologies © 2016CHAPTER 1
A list of provided source files containing user routines and the external routines to be called within these
user routines are given below. Each user routine is executed during the simulation as long as it is called
by a corresponding template in the GT-SUITE model (categorized by the application area). Note that the
‘UserCodeFHamess’ template in combination with the many sensors and actuators available in GT-SUITE,
offers a very flexible option for a user model of any kind, if @ built-in user model is not available for a
specific template. If you are interested in GT allowing a user-model directly in a specific template, please
contact GT support.
Gamma Technologies © 20169102 @ so/Bojouyoos ewes
WaSAUNOOONT
WASMULLVAHONT
ISUETT SE APNAD:
Wasit GONTTARIAL
TRTSHUTHOINGIAL SPURT
wasn aTaWNL
ASN RAMS
aun IsquoiKoug,
WaAShdaads HEIL
WASNGAAIS TINT
TORAMAUIOD 1S 105 PROT SUM,
‘qin IsqmontKoaug
Prag
OIROT,
WSANOLLINOMAT
1qHlOD [aL FHS WORT,
TenaaON OTT
avagdieygidogieoruo,
ssao7wasn
mesp4
uo aAIeA,
wagdieygudogyearo3
soda” wasn
auineapsi 20)
qiddy Snbuinang 10
2g yeaiuory # YO DAjeA [BaIUOL
rreaguozieddogiestu03
prewar 20 oxn2sps yf 3
suonean day
ste © SuN19pOK
eFsoumpoatpiande,
ne)
wasnaWwooo1 soueuiopeg dung 10 wey osseadiuos, ardumgouegsossaxduo
“ALIAISMAaTGAUVNIG
usnscpne “ALIAISAASIGAAALXIN apow ase see
PHENO WAZA [POW 840 ree
‘oT WSANGONLVO ASAGOWLYS.
PE, WAS AAVA HAA UISpOPN STBIOL TUL Tama
A ANAT WAST MLVE ATA Sata, AHP
Arneg, - pong
auad wasn Wve FTE SURO ATPL
= SrOMESTEAy SHPO,
eogdinggioddogiiea, ssdd"wasn ayeagdieygioddogtieg,
mpAH 10) Og dEUS P UO AIBA IPL
THasHO
Himeagauogieddogyred, HWSode-wasn Pasa eddo gto
40 aynespsy] 05 Wag [OO!UO.) B UO ATEA TEAL
ssauopiaddogites, sae wasn « dy apmunaud aveagauogeddogttea,
20 ayinespsi uO OAIRA {PEL
WV Tawa
AINVN ANILAOWAS:
NOILVolIddv
STAT SOARED AP TL, We SOOT SUMO | OT
ANWN TT
| MaLdVHO9102 @ so/Bojouyoos ewes
iODRSTZON NOMLNTOS WASAZZONINT WORDSTAT SAHDIPAT camowh
HOD SAZONT, TIGL WASAZZONINT TEIBUC SOTOHT TO FOGRON 107 Trumeouasyzz0N fa
ISNIPVUS EPH, IOOMOTIAD WTA TERISTSOD MOT MATRA POD THRNpVISeTPAH,
WISTEMOAASHNASTE aySpony AFoIERS TORO AAT ‘TIOMNGUNTCSMOAAIT
‘SOT WAS ON abso Bea BUTANE TEUODSSOTIBOH
aIxa Was Oa SADIOT, 19 SBI0 PO {Fonbie 3923104
INIVA WA TATA Tay TOMS OLGA PUP A PAPRAPSTDWPITT
Puasa on SueaLT
SRETA ASA OHA | soy uossujo09
Dh Wasa do SRT
say
was do
non a
HWATAS wasn SHNaaTeasoddoy
204 Suysnoyy SuAoyy quae oarea sadder
SDUPUINDL
‘wasn arpaqeqroddey
40 soyinesp sy
TAD
Oy, RiOToaay AURAL AATF
SINVYO WASN_ORTIONT.
"TKO WAST ORION 0 BPRS
rues pyugoustug
USMONTAVOS sABag PUTA TRUBONESS ap
WAGNITAQONAWASH PAD HIN, RUSE ph
NOLLVUOAVAS Ten pH TuopeIoden sp
WASMaXONONE
solaadg pauung parses ‘xONwoHsngulog a9
“TALE NONSOXON. ig poumg poreiag | ¢¥ON”wousnqui03y
GOWASAONN ‘worisnguio;) 1§ 49) ]APOW You | yOu uoNSNqwo:
‘Grwonsngu
apuysyaug, | GHISMENOOQNE 01 woyeambg) ronsnqu> sop. a
paso, SON Noon pmamen patel] ort
GLV1dWal GWYN ANILNOUANS: NOILVOMTddV GWYN FHA
| MaLdVHO9102 @ so/Bojouyoos ewes
7 ONTAZAX. TORR APTA TAK OUTIZRX |
TOHRU, WAS ONAGAX wopoung Rouapuadeq AX FUOTINIAK |
COTTA, ALATTASH ‘BET aIPA COATECHAIED, ODHOSTUEANTEA |
wud. 492 A987) WILE AZAANOS ADM | sa 0: [PalURYDa OM, UAaMIeq $9210; “UUOYD>AI95;/
auogyney2987, ‘Nooaewasriooaa | > yequyooyy om, aang so0304 raueousennn |
al THGOnaAN
srewwoqno[a305 : x Twewod] MoT ayp BPO BWOEIMOLE
wrewoemors3057, aaaoneun Nea 1 015 258 HOH apuognontsn |
sump gepenueep, ssaNuviwasn. sajfensog yea souseran |
m1, wasnminioL soueaiog2g aur9m seuamy
SOPH Soren TORT |
PL,
OW TOT
aig,
SHEISTD, apoROSOUAL,
Tao |
TaaTqo
‘dauauaj24 20u919}Y.J9P0D!980),
‘or Suurayax sorejduon ty
NOISaATIawas- Lao
A Aamsgy 987
aque
SuERSATEIED,
“gudsmord, 42d
SOWNOS-ADWANS 1aS"washn
wsodwo> pra
Foemos stow |
GLiVidwaL
WINN ANLnowaas:
NOILVOlIdd¥
WAVN aT
| MaLdVHO9102 @ so/Bojouyoos ewes
‘SoUNIMOL [eUIDIXa aSayp UE PoULyop sist] joUNe a4 40} (AzosauEp 298n 94 J9pUN pore>0}) A7-FANAKAL
ON INVILOdWI
1D ih pate WODIaS ayy OF SRRSOUT STI WAST LIA
Hq PING DATOS oH SAMOA | YSAINTN NOISWIA WAATOS LAO
D WIGrISINVUD
no" POW BLING:
TOATOS WORETES PORTA INVoaS
Dae Gan Saray SunyRIBdaIS Tay an
Toe 9 PUP a a Wy Toup aINNaTT aT STRAT aa Mow Gan
THFEWOP MOU] OYA.F0 SMTEIDUGIDY pu OMSTaIM OHS SOTOTAOTE CANAD WANASSVN
WORDEN SOU USAT w Hl SoLSadS JO GONTR SHUT SUIT, DV WASSWALAO,
7 300 START DVUTTON.
SORIDAOHT SEH SOTTAITED Ha WALLS
Todo SaRTRATED Oa dt UAL
SopIRAOTT Se STAITED W a
wopdoud see SO|MI|ED Og aw AULD
wander FH SaRTAATE DEALS
Tiep ToT sn saINIg TNOISTOTARMASA
ap 2aTeA SIMPY ANT INTVA 1a
rap sOTaTT SMD GANT YOLDaINI TaD
DPR © JROGE WOREUOYUT FuPHOGUIT SIS ‘GANT WAGNTIAD 199.
TESTE SPOT SAVMUY TEGOW Wasa GVOT
[ous yn SAM Tndino NAVA wasn IAD
‘IndLNO NUVH Was Las
ANT NUVA WAS
NWA WASH 1D
SaNWN NUVA Wash Lao
S75 STR OANT VA
TRUS eqOTS powsonar SUID DANI IVEOTD 19
NOILVorTddv WNWN ANILAOWaAS
ST
SUMON TTT ONT PIED SHUTTON PRINT PHTTATT TDS
| MaLdVHOCHAPTER 1
1.3 Data Exchange To/From User Routine
4.3.1. Input through GT-ISE
wer CodeFReference' Reference Object
During the execution, GT-SUITE passes certain variables to the user code via user routine interface, ie.
the argument list, This information can be complemented with the 'UserCodeFReference’ reference
template by setting additional inputs to be passed. The 'UserCodeFReference’ template contains five input
folders: Integers, Real Numbers, Strings, RLT Variables and Plots. By default, they are placeholders for
inputs to be used by the user model. With this template, one can create input integer variables (creating an
array whose elements are of type integer), real numbers and/or strings to the user code, GT-SUITE
provides its users the possibility to use GT-supplied RLTs as the additional input data, as well. RLTs can
be selected by use of the RLT Variables folder. Plot requests from the user code are made via the Plots
folder. Users can add their own comments into Descriptions attributes for the corresponding variables to
help themselves remember what each input is (see Figure 1).
TES =
Ey oF (astescomat]
[wie | es] kins | A ri | Ai]
Descoptens
Integer Vabes
pod
te 4
re spe daa
Figure | - Setting additional input data via 'UserCodeFReference’
Data defined in the Integer, Real Numbers, Strings, RLT Variables folders are transferred into user
subroutines through "LOAD_USER_MODEL_ARRAYS" external routine which is supplied by GT. The
"UserCodeFReference’ reference object can be refered by a variety of templates (cg.
"UserCodeFHamess}) related to the application (e.g. modeling laminar and turbulent flame speeds,
ignition delay, heat transfer)
Gamma Technologies © 2016CHAPTER 1
Sensors
Input data to user subroutines can also be supplied through sensors (‘SensorConn’ parts), which are
‘generally used to bring data from anywhere in the system during the simulation. This is done by passing
the signal into a 'UserCodeFHarness’ object. There are many variables that can be sensed (e.g. pressure,
temperature, ete.), and their number grows with each release of GT-SUITE.
1.3.2. Using APIs within User Routines
The user can access general simulation variables by calling other GT-supplied external routines that are
written for the user to point to and extract any needed information. GT-SUITE automatically loads a
broad range (hundreds) of frequently needed variables (c.g. bore, stroke, cylinder number, time, time-step
size, variety of flags etc.). Since these variables are very valuable to the code developers, GT constantly
adds to this growing list of variables on user request.
For instance, some important cylinder variables are made available with 2 call to a subroutine
GET_CYLINDER_INFO (called with one non-optional argument for the cylinder number, followed by
optional arguments for the desired variables). If the effective lambda at the end of combustion for
cylinder 1 is wanted, the following command line should be written:
call GEI_CYLINDER_INSO (1, BEFLAMBDA ~ efflambda
1.3.3. Output through GTASE
User model output signals are received by GT-SUITE by the means of several control templates such as
actuators and RLT creators via the 'UserCodeFHamess’ object
Actuators
Output fom the user subroutine can be used as system control parameters through actuators
(ActuatorConn' parts), which can collect output signals from user model and send anywhere in the system
during the execution. Actuators allow the user to choose many output signals to be collected.
RLT Creators
Output can also be stored as the RLT variables via RLT creators (RLTCreator’ objects), which can collect
‘output signals from user models and store them as new RLTs in addition to GT-supplied ones. Many
‘output signals can be stored as RLT variables in the standard format, For example, the output of a
"UserCodeFHamess' part, which couples GT-SUITE with a user model, can be connected to ‘RLTCreator’
to save the user model output as a new RLT.
13.4 Plots
Plots of any defined variables can be created within the user subroutine in conjunction with the
‘UserCodeFReference’ reference object. Please sce the section titled "Generating Plots from User
Subroutines” for detailed information,
Gamma Technologies © 2016CHAPTER 1
1.4 Creating User Routines
‘While creating a user routine, one should follow some fundamental programming rules.
1.4.1. Structural Rules of User Routines
Fach user subroutine is linked to other external procedures provided by GT with an explicit interface, and
the interface of these routines is placed in module GTIUSR_INTERFACE (which is a read-only module),
‘The "usc" statement for this module is added in the header section of cach user routine, and one must
keep this command line in order to employ all external procedures.
At the beginning of each user subroutine, there are specification statements declaring the types and intents
of all dummy arguments. These statements also include short in-line comments to describe the arguments
that are passed to/from the subroutine. Dummy argument names can be changed if desired; but, their
types and intents must not be changed. Besides, none of the values of variables with intent "in" attribute
‘can be modified since their values are set in GT-SUITE and passed into the routine. In contrast, all of the
values of variables defined with the intent of “out” must be set by the user. In general, these are required
variables that are needed by GT-SUITE and must be calculated by the user model
Declarations of local variables "intparm", “realparm", "charparm", “realparm’, “rltparm", "n_ints",
n reals", "n_chars" and "n_rlts” must not be changed in the routine since they correspond to the arrays
assigned by the values set in the 'UserCodeFReference' reference object and their sizes. As mentioned
before, these values are loaded through a call to the subroutine LOAD_USER_MODEL_ARRAYS.
Additional care should be taken not to exceed the bounds of arrays when employing them.
All other defined local variables should be declared before, and the user code must be inserted after the
call to LOAD_USER_MODEL_ARRAYS.
1.4.2 Generating Plots from User Routines
"UserCodeFReference' has a facility to store plots that can be displayed from the standard GT-POST
utility, These plots will be included in the *.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:
ody plot_number, "abel", ‘nane', "x label’, "y label",x vartable,y variable)
The GT-supplied external routine, subroutine USERPLOTSTORE only stores the given data points. In
this call, the input arguments are:
ref
imod: 'UserCodeF Reference’ reference object index which is passed into the user routine
plot_number: Number of the plot (1, 2, 3, ete.)
label: Text for the plot label (must be enclosed in single quotes)
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)
yd axis label (must be enclosed in single quotes)
x_variable: Name of the variable to be plotted on the x-axis
y_variable: Name of the variable to be plotted on the y-axis,
Gamma Technologies © 2016CHAPTER 1
Each call to USERPLOTSTORE creates a single plot for particular variables. This feature works for
multiple 'UserCodeFReference’ reference objects.
1.4.3. Writing Messages from User Routines into GT-SUITE Model *.out File
It is possible to write messages from a user routine into the GT-SUITE model *.out file. These messages
will also appear on monitor window or console output. This is done via calls to GT-supplied external
routine, subroutine WRT_USER within a user routine. One should implement the following syntax in
order to print messages into the * out file:
Within this call, the input arguments are:
© imod:
‘+ string: Text to be written into the *.out file (must be enclosed in single quotes)
JserCodeFReference’ reference object index which is available in the user routine
Note that each call to subroutine WRT_USER creates a new line, and maximum number of lines that can
be written into the *.out file (from each user routine per each time step) is 100. This feature works for
multiple 'UserCodeFReference’ reference objects. In addition, maximum number of characters that a
single line can hold is 130; otherwise, a string written into the * out file will be incomplete.
1.5 Compiling and Using User Routines
Intel Visual Fortran Composer XE (12 or higher) is required to compile the user routines.
All files required for compilation are located in the directory %GTIHOMEY%é\v20 I6\usereode\Fortran,
referred to here as the uscr directory. In order to prescrve the original files for future reference, it is
recommended to copy this directory to another location for editing
The following sub-sections provide the instructions for the compilation and usage of user subroutines on
different operating systems,
1.5.1 Compilation on Windows
For a Windows installation, the user directory contains the following files and directories:
+ README.txt - Contains general information
‘+ sources - A directory containing user source/header files written in Fortran and C/C++
‘© GTIusr2016.* - The project and solution files for Microsoft Visual Studio 2010
‘+ windows - A directory containing required object files provided by GT (do not modify)
© C-Project - Contains a project dedicated for C/C++ codes ("C-Project.vexproj" can be excluded
from "GTlust2016.vfproj” if not used)
The user must create a Dynamic-Link Library (DLL) and copy it to the appropriate location as described
in the section Running with User Routines. The DLL is named GTlust2016_64_dp.dll for the 64-bit
standard GY-SUITE serial solver. There can be other versions of this DLL to aecompany the other GT-
Gamma Technologies © 2016
10CHAPTER 1
SUITE solvers. The 32-bit solver would use 32 in place of 64 in the name, while parallel solver would use
mp in place of dp in the name,
Creating the DLL file within Microsoft Visual Studio
‘The *.ll file can be created in Microsoft Visual Studio with the following steps:
1. Copy the user directory to a location which can be edited,
2, Open the project solution GTlusr2016.sin within Microsoft Visual Studio 2010.
3. Edit the source files containing the user routines based on the application (see the list of user
files/routines). Each routine contains example code with @ comment indicating where the user should
begin editing.
4, Select “Release” (or "Release Parallel” when running GT-SUITE in parallel mode) from the
“Solution Configuration” pull-down menu. Note that "Debug" (or "Debug_ Parallel") may be selected
to facilitate debugging,
5. Select either "x64" or "Win32" from the "Solution Platform” pull-down menu to specify whether a
64-bit or 32-bit library should be compiled.
6. Select "Build Solution" from the Build menu. GTlusr2016_(64/32)_(dp/mp).dll will be created within
the "build" folder in the user directory according to the "Solution Configuration” and "Solution
Platform" chosen above.
7. Once the new DLL is created successfully without any etrors, copy GTlusr2016_*.4ll to the
appropriate location as described in the section Running with User Routines. If the DLL is being
copied to the installation directory, be sure to make a backup copy of the original
1.5.2 Compilation on Linux
For a Linux installation, the user directory contains the following files and directories:
+ README.txt - Contains general information
‘+ sources - A directory containing user source/header files written in Fortran and CICH++
‘+ Makefile - A makefile for building a shared object for Linux
‘+ linux - A directory containing required object files provided by GT (do not modify)
The user must create a shared object (SO) and copy it to the appropriate location as described in the
section Rumning with User Routines, The SO is named libgtiusr2016_64_dp.so for the standard GT-
SUITE serial solver, or libgtiusr2016_64_mp.so for the GT-SU
sob
solver. Note that the 32-bit
ITE parall
+ is no longer supported on Linux.
n Gamma Technologies © 2016CHAPTER 1
Creating the SO file
1. Copy the user directory to a common directory where you have full access permissions. This target
directory will be referred to here as the working directory.
2. Edit the source files containing the user routines based on the application (sce the list of user
files/routines). Each routine contains example code with a comment indicating where the user should
begin editing,
3. Modify the Makefile accordingly for the variables listed in its comment section,
4, From the command line, simple type "make", and the new shared object file will be created within the
build directory in the working directory.
5. Once the new SO has been created successfully without any errors, copy libgtiusr2016_*.so to the
appropriate location as described in the section Running with User Routines. If the *.so is being
copied to the installation directory, be sure to make a backup copy of the original.
1.6 Running with User Routines
Afier the DLL/SO is compiled as per details given above, it should then be copied to the appropriate
location described below. When running the model, please confirm that the correct file is loaded as per
the screen output as shown below:
Sample solver output:
INFO Shared object versions used:
/GT/bin/linux_x86_64/ libgtiust2016_64_dp.so 4.0000 € Verify the path to your file here
‘The first instance of the user routine which is found in the folders below will be loaded. Thus, in a shared
installation, a user or group can preferentially use their own user models by placing the dll/so in the
‘model folder (Windows only) or an appropriate location in the PATH or LD_LIBRARY_PATH.
Search hierarchy for the user dil/so
1, The local directory where the .gtm model file is located. See the exceptions below
i, If GT-SUITE is launched from a third-party CAE tool, the user dll/so might be loaded from the
application's launch directory, instead of the model directory.
ii, Linux: The local directory is generally not searched to load the user routines, as itis considered a
security risk. The model folder can be searched by adding the full path to the directory in the
LD_LIBRARY_PATH, ("can be added as well, but this is considered a security risk.)
2. The directories defined by the environment variable %PATH% on Windows or
LD_LIBRARY_PATH on Linux. Sce the section “Setting Environment Variables” in the Installation
notes for details on setting these values,
Dp Gamma Technologies © 2016CHAPTER 1
3. The bin\{PLATFORM} folder of the installation directory. For Windows, this is
%GTIHOMEA\bin\win64 or *\win32, depending on whether the 64-bit or 32-bit solver is used. For
Linux, SGTIHOME/bin/linux_x86_64 (32-bit Linux solver is no longer supported),
1.64
Running with User Routines on Distributed
Please see the section “Running a Simulation with User Models” in the “Distributed Computing and
Remote Run” manual,
4.7 Debugging User Routines
In this section, the brief instructions on debugging the user routines are given.
When using PC
‘Open GTIusr2016.sIn,
Set “Solution Configurations” as “Debug”.
Right-click “GTusr2016” project and choose “Set as Startup Project”.
Right-click “GTusr2016” project and choose “Properties” option.
Go to its “Debugging” menu; enter “%GTIHOME%\v2016\GTsuite\binwin64\gtsuite_dp.exe”
(64-bit) or “%GTIHOME%\v2016\GTsuite\bin\win32\gtsuite_dp.exe” (32-bit) in its “Command”
attribute (%GTIHOME% is the GT-SUITE installation directory, ic., CAGTD.
In its “Working Directory” attribute, enter the full path of directory where the*.gtm file is located,
In its “Command Arguments” attribute, add the GT-SUITE model file name without any
extension - do not include *.dat or *.gtm, Ensure that *dat file of the model is created (One
should re-create the *.dat file after each change to the model. To do this, within GT-ISE, select
Run > Run-Simulation Utilities > Create .dat file),
Init
invironment” attribute, define the PATH environment variable as,
"PATH="GTIHOMEY4\bin\win64;%GTIHOME%\v2016\GTsuite\biniwin64\external" (64-bit)
or "PATH=%GTIHOME®% bin\win32;%GTIHOME%\2016\GTsuite\bintwin32\extemal" (32-
bit)
Go to its “Linker” > “General” menu; enter “build\Debug\x64\GTIusr2016_64_dp.ll” (64-bit)
or “build\Debug\Win32\GTIusr2016_32_dp.dll* (32-bit) in its “Output File” attribute.
Click “Build Solution” to create “GTIusr2016_(64/32)_dp.dll” in “build\Debug\(x64/Win32)*.
Gamma Technologies © 2016CHAPTER 1
Copy this file into “%GTIHOME%\GTNbin\win64” or “%GTIHOME%\GTNbin\win32”. Note
that one can back up the original *dll file that comes with GT-SUITE installation before
implementing this step.
Add breakpoints into the code
Run the debugger.
No’
Before starting debugging, the following warming message might be issued by the compiler:
“Debugging information for ‘gtsuite_dp.exe' cannot be found or does not match. Binary was not
built with debug information. Do you want to continue debugging?”
‘This is just a warning message indicating that the executable does not contain debug information;
but the library does; which is expected for this implementation. Hence, the answer is "Yes".
Using Breakpoints in the Debugger
The content of this sub-section is obtained from the Intel compiler help pages to briefly describe
how to use the debugger environment to set file and data breakpoints. For detailed information,
user is encouraged to refer to Intel's documentation
> Viewing All Current Breakpoints
You can view all currently set breakpoints in the Breakpoints window.
To view all set breakpoints using the Breakpoints window:
1, Inthe Debug menu, sclect Windows > Breakpoints,
2. Scroll up or down in the Breakpoints list to view the breakpoints. Enabled
breakpoints have a check mark in the check box and disabled breakpoints have an
empty check box. The window displays all types of breakpoints.
v
Working with File Breakpoints
Use a file breakpoint to interrupt program execution when the program reaches a specified
location within a file. Several symbols are used to show the status of file breakpoints; these
appear in the left margin of the Source windo
© Enabled file breakpoints are identified as a red circle,
© Disabled file breakpoints are identified as a hollow circle in the left margin.
© During debugging, a currently active breakpoint appears as a red circle containing a
yellow arrow in the left margin of the Source window.
‘To set (enable) a file breakpois
1, Open the desired source file in the solution.
14 Gamma Technologies © 2016CHAPTER 1
2, Inthe Source window, click the line at which you want to enable a file breakpoint,
3. Do one of the following:
+ Click in the left margin of the line or press the F9 key. When you set a
breakpoint, itis enabled by default.
= Right click on the desired line and select Insert Breakpoint from the pop-up
ment.
isable a file breakpoint:
1, In the Source window, click the line containing the file breakpoint you want to
disable.
2. Do one of the following:
= Right click on that line, and select Disable Breakpoint from the pop-up
menu.
+ Inthe Debug menu, select Windows > Breakpoints, this opens the
Breakpoints window. Click the check box for that breakpoint so it is
unchecked (disabled).
To remove a file breakpoint:
1, Inthe Source window, click the line containing the file breakpoint you want to
remove.
2, Do one of the following:
= Click in the left margin of the line or press the F9 key. Ifthe breakpoint was
originally disabled, press F9 again to remove it.
= Right click om that line, and select Remove/Delete Breakpoint from the
pop-up menu,
= Inthe Debug menu, select Windows > Breakpoints, In the Breakpoints
window, select the breakpoi
button (which looks like an
To view the source code where a file breakpoint is set:
1, Inthe Debug menu, select Windows > Breakpoints,
2. Inthe Breakpoints window, click a file breakpoint.
3. Click the "Go To Source Code" button
This action takes you to the source code for a breakpoint set at a line number or function (or
subroutine) name. In the case of function (or subroutine) names, the debugger must be running
for this to work.
To remove all breakpoints (including data breakpoints):
In the Debug menu, select Clear/Delete All Breakpoints,
> Adding Conditions to File Breakpoints
When you associate a condition with a file breakpoint, the program executes until that
location is reached and the specified condition is met (such as when the value of an array
1s Gamma Technologies © 2016CHAPTER 1
element is greater than 1). To add a condition to a breakpoint, set a file breakpoint, then right-
click in the associated line and choose Breakpoint > Condition...
If the specified condition occurs at the chosen location when the program is run, a message
bbox appears.
To disable, enable, or remove a file breakpoint with a defined condition, follow the general
procedures for a file breakpoint.
> Working with Data Breakpoints
Use a data breakpoint to interrupt program execution when the value of a certain variable
changes. A data breakpoint displays a message box when the value of a variable changes, or,
if a condition has been defined, when a condition is met. Unlike a file breakpoint, data
breakpoints are not associated with a specific source location,
When using Linux
‘+ Ensure that a debug version of the Dynamic-Link Library (°-g" argument in compiler command)
is compiled.
+ Use any debugger utility that would normally be used.
‘© Ensure that *.dat file of the *.gtm file is created, and re-create the *.dat file after every change to
the *.gtm file. To do this, in GT-ISE, go to Run > Run-Simulation Utilities > Create .dat file,
1.8 Calling a C/C++ Function from Fortran User Routines
The "C-Project", which is included within the solution file GTlust2016.sin, is reserved to add functions
for algorithms written in C/C++ programming languages. Any function written in C/C1-+ must be called
from one of the Fortran subroutines listed under the "GTIust2016" project since GT-SUITE has direct
interfaces only with these Fortran subroutines.
In order to include a C/C++ function to be executed, please implement the following steps:
© Open the GT-supplied solution file GTIust2016.sIn.
+ Add the *.c/*.cpp file into the C project, "C-Project”
© On the "Solution Explorer" tree, right-click on "C-Project"
© Select "Add"
© Choose "New Item" or "Existing Item"
‘+ Add the function's prototype into the "UserRoutineAPLh" header file. While listing data types in the
function's argument list, please refer to “fortranc:h" for data type conversions from C/C++ to
Fortran,
16 Gamma Technologies © 2016CHAPTER 1
‘Asan example, see "EngCylinder_Combustion." and "EngCylinder_Combustion_C.cpp" files.
1.9 Compatibility with the Older Versions of GT-SUITE
‘When using a code developed for an old version of GT-SUITE, the user must compare the old code to the
new sample code, and manually make the required changes. The reason for this effort is that the
subroutines in the old version may not be compatible with the new version of GT-SUITE. Specifically,
the number of attributes passed into and out of a routine and the USE statements may be changed from
version to version,
1.10Running User Scripts Before and After a Simulation
Refer to %GTIHOME%\version\GTsuitelbin\UserSeripts.pm. The pre_simulation and post_simulation
functions will allow a user to define code using perl to run before and afier a simulation,
Gamma Technologies © 2016
7