Contents

Glossary

Mean radiant temperature: is defined as the uniform temperature of an imaginary enclosure in which the radiant heat transfer from the human body is equal to the radiant heat transfer in the actual non-uniform enclosure
Mean radiant temperature: is defined as the uniform temperature of an imaginary enclosure in which the radiant heat transfer from the human body is equal to the radiant heat transfer in the actual non-uniform enclosure
The solar zenith angle is the angle between the zenith and the centre of the Sun's disc.
The zenith is an imaginary point directly "above" a particular location, on the

Tools

View3D

View3D is a command-line tool for evaluating radiation view factors for scenes with complex 2D and 3D geometry. It uses an adaptive integration method to calculate the view factors between faces where there is partial obstruction from inbetween faces.

Creating TRNSYS component c/c++ header file

TRNSYS has one more input / output distinction; that is DERIVATIVES. Components that solve differential equations numerically will often have DERIVATIVES as well as INPUTS, OUTPUTS and PARAMETERS. From the simulation user’s point of view, the DERIVATIVES for a given Type specify initial values, such as the initial temperatures of various nodes in a thermal storage tank or the initial zone temperatures in a multi zone building. At any given point in time, the DERIVATIVES of a Type hold the results of the solved differential equation. If these DERIVATIVES are set in a component as OUTPUTS, the simulation user can see, plot and output these values.

Rereading Parameters

If two or more instances of a given Type are to be used in a simulation, it is necessary to reread the parameter values so that the local variables within the Type’s code reflect the values associated with the current instance.

Fundamentals

Inputs: Parameters: Outputs: All outputs are assumed to be time dependent and are recomputed by a component Derivatives: Components that solve differential equations numerically will often have DERIVATIVES as well as INPUTS, OUTPUTS and PARAMETERS. From the simulation user’s point of view, the DERIVATIVES for a given Type specify initial values, such as the initial temperatures of various nodes in a thermal storage tank or the initial zone temperatures in a multi zone building. At any given point in time, the DERIVATIVES of a Type hold the results of the solved differential equation. If these DERIVATIVES are set in a component as OUTPUTS, the simulation user can see, plot and output these values.

Version Signing

Version signing is one of a series of special calls that is made to a Type when the Type is not intended to perform any manipulations of inputs or outputs. Once, at the very beginning of a simulation, a Type needs to log itself as having been written using a given TRNSYS coding standard.

"Last Call" Manipulations

The second special case call to Types occurs at the very END of each simulation. Whether the simulation ends correctly or ends in error, each Type is recalled by the TRNSYS kernel before the simulation shuts down. This call allows Types to perform any “last call” manipulations that may be necessary. These may include closing external data files that were opened by the Type during the course of a simulation, or calculating summary information that may have been collected during a simulation. If the type does not require any such last call manipulation, so it is advisable to simply return control directly to the Trnsys kernel.
You may want your component to actually do something at the end of the simulation. It could, for instance print a message to the list file or close logical units that were used during the simulation. Standard component Type 22 (Iterative Feedback controller) performs end of the simulation manipulations that you might use as an example.
The access function "getIsLastCallOfSimulation()" also returns a "true" result if the simulation terminates with a fatal error. In that case, the component that generates the error returns control to the TRNSYS kernel, which calls all components one last time in order to perform their "end of simulation" operations. You can check if the very last call occurs because of an error or as part of the normal simulation process by calling getNumberOfErrors

"End of Time Step" manipulations

At the end of each time step, each Type in a simulation is recalled. The Type should call the AccessFunction “getIsEndOfTimestep().” Note that the function will return “true” even if a converged solution was not found at the current time step.
the “end of time step” call allows a number of different manipulations to be performed such as resetting counters. For users familiar with the concept of manually updating storage variables, the concept of “dynamic” and “static” storage variables were introduced with TRNSYS 17. Refer to section 7.4.4.17

Reseting Counters

It is sometimes advantageous to count the number of times that a particular event has occurred during a given time step. One example might be a controller that counts the number of times that it has calculated a different value of its control signal during a given time step. After a certain number of different decisions, the controller “sticks” and the calculated output state no longer changes. At the end of the time step after all components have converged, it is necessary to reset the iteration counter to zero. This could be done as one of the end of time step manipulations when the call to the getIsEndOfTimestep() Access Function returns “true.

Updating storage variables

With the addition of the concept of "dynamic" storage, this step is no longer needed

Updating Automatic reporting (SSR) variables

WWith the release of TRNSYS 18.0 the concept of automatic reports was introduced. If a component is to automatically report either integrated or min/max values, those values need to be updated at the end of each time step.

Initialization call (First call of simulation) manipulations

At the very start of each simulation, after all Types have version signed themselves each Type should initialize itself Types should call the “getIsFirstCallOfSimulation()” Access Function to determine when these initializations should take place. There is a very specific set of steps that each Type should take at this point in the simulation. With the release of TRNSYS version 16, the steps taken by a Type during the initialization step changed from what had been done previously. The most important thing to keep in mind concerning the initialization call is that a Type should NOT read its parameter list,nor should it perform ANY calculation of output values. It should perform the following operations:
Tell the kernel how many PARAMETERS are expected to be found in the input file by calling the setNumberOfParameters() AccessFunction as follows:
Call setNumberOfParameters(4) Tell the kernel how many INPUTS are expected to be found in the input file by calling the setNumberOfInputs() AccessFunction as follows: Call setNumberOfInputs(5) Tell the kernel how many DERIVATIVES are expected to be found in the input file by calling the setNumberOfDerivatives() AccessFunction as follows: Call setNumberOfDerivatives(0) Reserve the required amount of space in the global output array by calling the setNumberOfOutputs() AccessFunction as follows: Call setNumberOfOutputs(5) Set how the Type should be called using a call to setIterationMode(). Most Types will call this AccessFunction with a value of 1, indicating that the Type should be called every iteration whether or not its input values have changed. Types that are integrators or printers call the function with different values. Users programming this kind of Type should refer to section 7.4.3.5 for more information. The call to setIterationMode() is as follows: Call setIterationMode(1) Set the number of static and dynamic storage spots required using a call to the setNumberStoredVariables() AccessFunction. Refer to section 7.4.4.18 for fundamental information about static and dynamic data storage between time steps. It is again important to bear in mind that we are not setting initial values of the storage variables at this time, we are merely reserving space for later usage. For the water heater component, the following statement reserves the required space: Call setNumberStoredVariables(0,0) Return control to the TRNSYS kernel. Again, there are NO iterations performed during this time step. Therefore there should be NO calculations performed. To return control, add the following line: Return

Reserving space in the SSR

During the initialization step any Types that are to be reported in the Simulation Summary Report (*.SSR) must reserve the number of spots that they wish to later use.

Start time manipulation

Once the initialization steps were completed, control was returned to the TRNSYS kernel. The next time that each Type is called is when the simulation time is equal to the simulation start time. Throughout much of TRNSYS’s history (through version 15) there was no call to components at the simulation start time. After being called when getIsFirstCallOfSimulation() returned “true” for initialization (as described in section 7.3.11) Types were next called at the end of the first time step (TIME = InitialTime + TimeStep). With the release of TRNSYS 16.0, an important distinction was made by calling all Types once after they have been initialized but before time has advanced in the simulation. The point of this initial time call is to perform the following action

First, read the local parameter list and set each parameter to a local variable. Parameter values can (and should) be read only at two places in a Type. The first is during this "Start time" call before time has progressed. the other is during the "multiple unit manipulations" section. Only reading parameters at these two stages of the simulation saves a great deal of comutational time (for c++ it seems that we have to read parameters all the times) because in this manner, parameters (which do not change with time) are read only when they must be. In each of these two sections, each parameter value is set equal to a local variable name that has been declared as a double precision variable
the second step performed durign the "start time" manipulations section is to check each of the parameter values for validity parameters whose values cannot be negative, or whose values must be between 0 and 1, can be flagged as an error using a call to the foundBadParamter() AccessFunction
Next, it is necessary to set the initial values of any static or dynamic storage variables that are used by the Type. This is accomplished simply by assigning local variable values to each of the spots in the array that is used to transfer information to and from the storage structure, then calling the setStaticArrayValue() and setDynamicArrayValueThisIteration() subroutines. The code used to set four initial storage values might look like the following
The final step performed during the “Start Time” manipulations section is to set the initial values of the outputs. It is essential that you set initial values here. Your Type should not perform any of its calculations at this point in time. If it does, then it will likely get one time step ahead of where it is supposed to be at this point in the simulation. Because of this restriction on performing calculations, it is often difficult to know what value to choose for an output initial value. A good default value is zero since that usually indicates to the user that the output has not yet been calculated. In the case of devices that have fluid flow through them, the outlet temperature and outlet flow rate of the fluid can often be set to the inlet temperature and inlet flow rate respectively.

Initializing the SSR

During the initialization step any Types that are to be reported in the Simulation Summary Report (*.SSR) should initialize (set up) the specifics of the values that they wish to report.

multiple unit manipulation

Every time step manipulations

Retrieve Stored Values

At each iteration, a call should be made to the getDynamicArrayValueLastTimestep() and getStaticArrayValue() functions to retrieve stored values that are needed in calculations.

Retrieve input values

Retrieving input values follows much the same pattern as that of retrieving parameter values. The inputs are available to each Type by means of the getInputValue() AccessFunction. The values are typically read to local variable names for convenience and then can be checked for validity in much the same way as parameters.

Perform Calculations

Once all of the input values have been retrieved, the heater performance calculations and control logic can be performed.

Set storage values

Before exiting the Type at each iteration, it is good practice to update all appropriate storage variables. Obviously, if one or more of the storage variables is an initial value to be used for all iterative calculations at a given time step until convergence has been reached then it is not appropriate to update this value until the “End of Timestep” call

Set outputs

Return control

The very last requirement is that a Type return control to the TRNSYS kernel after its computations are complete.

Storage of Data between Time Steps

With the release of TRNSYS v.17, the concept of data storage between time steps was further simplified into two main usages: “static” and “dynamic.” If the user has a component that was written using an earlier coding standard, both the “s array” and the set/getStorageVars() functions are retained in the kernel so that the component does not need to be modified. However, if the user is writing a component using the TRNSYS v.17 coding standard, the user should not make use of these earlier features as they are incompatible with the more recent standard.

Static storage

Dynamic storage

Programming a Type in C++

It is also possible to program a TRNSYS type using C++ as long as the DLL created by the compiler correctly exports the Type. This section will highlight a number of the specific changes needed to use C++.

Header file (TRNSYS.h)

The TRNSYS.h header file provides the interface for the TRNSYS functions and subroutines. The most commonly used functions and subroutines have been included in the header file. Some of the more advanced functions and subroutines that should only be used by expert users have not been included. If these routines a needed, the programmer should have the knowledge to add these routines in the header file when needed

Type declaration

In C++ the Type declaration and the DLL export is complete in the same linearity extern "C" __declspec(dllexport) void TYPEnn(void){}

Calling TRNSYS function

Calling a TRNSYS Boolean Function

if (getIsFirstCallOfSimulation()){}

Calling a function that passes a number to TRNSYS

Calling a function that passes a string to TRNSYS

Calling a function that receives a string from TRNSYS


Creating a Dynamic-Link Library using MS Visual Studio

Opent MS Visual Studio
File\New\Project
Installed\Visual C++\ Dynamic-Link Library (DLL)
Name: Name of dll project
Location: The location of source code
Solution: Create new solution
Solution name:

Step 2: Configuration properties
Configuration: Active (Debug) Platform x64
General: let it as default
- Target Platform: Windows 10
- Windows SDK Version: 10.0.16299.0
- Output Directory: $(SolutionDir)
Debugging: let it as default
VC++ Directories: let it as default
C/C++
general:
- Additional Include Directories: adding trnsys.h location
- Optimization: do nothing
- Preprocessor: Verify if all is in majuscule
- Code generation:
- All Options: adding trnsys.h location to Additional Include Directories
/Yu"stdafx.h" /GS /W3 /Zc:wchar_t /ZI /Gm /Od /sdl /Fd"x64\Debug\vc141.pdb" /Zc:inline /fp:precise /D "_DEBUG" /D "TRNSYSCOMPONENTSLIBX64_EXPORTS" /D "_WINDOWS" /D "_USRDLL" /D "_WINDLL" /D "_UNICODE" /D "UNICODE" /errorReport:prompt /WX- /Zc:forScope /RTC1 /Gd /MDd /Fa"x64\Debug\" /EHsc /nologo /Fo"x64\Debug\" /Fp"x64\Debug\TRNSYSComponentsLib_x64.pch" /diagnostics:classic
Linker
General
- Additional Library directories:
Input
- Additional Dependencies
What is the difference betwwen Release and Debug
Visual Studio fatal error C1041/FS
fatal error C1041: cannot open program database 'c:\users\username\desktop\projectName\projectName\x64\debug\vc120.pdb'; if multiple CL.EXE write to the same .PDB file, please use /FS
The problem is because different projects in a solution hat the same intermediate directory
changing
$(Platform)\$(Configuration)\ to $(Platform)\$(Configuration)\$(ProjectName)\
in
configuration properties->general->Intermediate directory
Use "View > Other Windows > Property Manager" to bring up the Property Manager. It will show your projects and configurations.
Right click a configuration, and select "Add New Project Property Sheet...". You can name it, and select a location that works for all your projects.
Once created, you can edit its properties just as you would a build configuration.
To use that property sheet as the basis for other projects, just right click the configuration or project, and select "Add Existing Property Sheet...". Browse to where you saved the original sheet, and it will be inherited. Any changes to the original sheet will be applied to any project that inherits it, unless they are overridden. If you go into properties higher up the chain, properties that override will have bold type for their values. To get them to always use the value in the base sheet, there will be a "inherit from parent or project defaults" option where applicable. Programming a Type in C++

How to debug your program

As it is, debugging is an incredibly important part of programming. If you run upon errors, you need to know how to find the issue, and resolve it. If you’re missing a semi-colon, you shouldn’t have to make a post to figure that out.
Anyway, we’ll start basic, from acknowledging and understanding a compiler error, to single-stepping through a program with your IDE’s debugger
Ref: C++ for Dummies 5th Edition by Stephen Randy Davis, pages 139-155

Identifying an error

To get the name of the function of TRNSYS
source: exp
Get the name of the function of TRNSYS that is published. Function of TRNSYS is TRNDLL.DLL (C: TRNSYS17 \ Exe \ TRNDLL.DLL) to, but contains all the functions that have been published under a different name and when using in FORTRAN There are multiple. To call from the C / C ++, to get the name of the function directly from TRNDLL.DLL. Taken out of the function name is done with the development tools included in Visual Studio. Run the following batch file from the command prompt, and prepares the use environment of development tools. Below is a working example of the PC that Visual Studio 2013 has been installed. "C: \ Program Files (X86) \ Microsoft Visual Studio 12.0 \ Common7 \ Tools \ Vsvars32.Bat" First, and prepares for using the development tools. Start the command prompt, type [Win] + in the dialog displayed by clicking the [R] "cmd" from the keyboard. Then, using the dumpbin.exe
Example:
dumpbin /exports Trndll64.dll > Trndll64.txt

System of differential equations

Solving differential equations in a TRNSYS Type is an easy task
Note: TRNSYS uses AVERAGED values on the time step, NOT INSTANTANEOUS values. So if you compare results from TRNSYS to other programs or hand calculations, you often have to convert "end-of-time-step" values to averaged values.

The wind blows from the north