Running simulations

pytrnsys runs TRNSYS simulations based on configuration files with the extension .config. The general idea behind this is to provide a fast and easily accessible way to define, run and analyse both single simulations as well as parametric studies.

Note

The configuration file does not require a header. It should contain different keyword commands on single lines. Comments start with # characters. End of line comments are possbile.

The existing commands are listed per topic in the following.

Simulation control

outputLevel

Output message level according to the logging package. (Options: “DEBUG”, “INFO” (default), “WARNING”, “ERROR”, and “CRITICAL”):

string outputLevel "INFO"

ignoreOnlinePlotter

If set to True, the TRNSYS online plotters are commented out in all the dck-files. No online plotters are shown during the simulation run. The TRNSYS progress bar window is still displayed (default: False):

bool ignoreOnlinePlotter False

autoCloseOnlinePlotter

If set to False, the TRNSYS online plotters will be left open until they are closed manually. This requires ignoreOnlinePlotter to be set to False at the same time (default: False):

bool autoCloseOnlinePlotter True

removePopUpWindow

Online plotters as well as the progress bar window are suppressed during the simulations, which corresponds to the TRNSYS hidden mode (default: False):

bool removePopUpWindow False

reduceCpu

When running simulations in parallel on different logical cores of your CPU, you can specify how many cores will be left unoccupied (default: 0):

int reduceCpu 0

checkDeck

If set to True, during merging the ddck-files, the specified and given amount of Equations and Parameters in each block are checked for inconsistencies (default: True):

bool checkDeck True

parseFileCreated

Saves the parsed dck-file that can be used to locate the line where checkDeck found errors (default: True):

bool parseFileCreated True

runCases

If set to False, the dck-files are created and saved in the normal structure but not executed (default: True):

bool runCases True

doAutoUnitNumbering

If set to True, the units of the merged dck-file are renumbered to avoid duplicates. This parameter should usually be set to the default True:

bool doAutoUnitNumbering True

generateUnitTypesUsed

If set to True, a file called UnitType.info containing the TRNSYS-Type numbers used is saved in the main run-folder (default True):

bool generateUnitTypesUsed True

addAutomaticEnergyBalance

If set to True, an automatic energy balance printer is created in the dck file. For more information see Default plotting for TRNSYS results (default: True):

bool addAutomaticEnergyBalance True

nameRef

Base name of the dck-file(s) created. Default base name is “pytrnsysRun”:

string nameRef "pytrnsysRun"

rerunCases

TBD:

bool rerunCases False

runFromCases

TBD:

bool runFromCases False

copyBuildingData

TBD:

bool copyBuildingData False

runType

TBD (Options: “runFromConfig” (default), “runFromCases”, “runFromFolder”):

string runType "runFromConfig"

pathToConnectionInfo

Specify the path to the DdckPlaceHolderValues.json, which you would like to use to replace the placeholders in the ddck-files. It overrules the behaviour of replacing the placeholders with the defaults:

string pathToConnectionInfo "path-to-your-project-folder\DdckPlaceHolderValues.json"

Tracking

trackingFile

When running multiple simulations the status of each simulation can be tracked with the help of a json-file. When a simulation is started, this is entered with a timestamp into this file. Once the simulation is finished this entry will be overwritten accordingly. Like this one can keep track of which simulations were aborted (for whatever reason) after having been launched. To activate this functionality you need to specify the full path of the json-file to be created:

string trackingFile "...\[name].json"

masterFile

If several simulations are run from different instances, the tracking can be taken one step further by employing a “master-file” in the form of a csv-file. It also tracks the status of different simulations based on the tracking json-files. One important feature is that, when it is used, simulations (identified by the name of the dck-file) that are already entered as a “success” won’t be run again. This is useful for redoing parametric studies where single simulations failed. If this is the case one can do the needed corrections and then simply launch the same parametric study again and the “master-file” will ensure that no unnecessary repetitions of simualtions are executed. To activate this functionality you need to specify the full path of the csv-file to be created:

string masterFile "...\[name].csv"

Paths

trnsysExePath

Specify the path to the exe-file of TRNSYS, which you would like to use to run the simulations:

string trnsysExePath "C:\TRNSYS18\Exe\TrnEXE.exe"

pathBaseSimulations

If specified, the location of where the simulation is run is changed to the given path. It overrules the normal behavior of executing the simulations in the current working directory:

string pathBaseSimulations "path-to-your-simulation-folder"

addResultsFolder

Specify the path to which you would like to save your simulation results:

string addResultsFolder "path-to-your-results-folder"

Definition of path alias

You can define an alias for a path to be used in a different place. If, e.g., you want to load many ddck-files from “C:\GIT\pytrnsys\data\ddcks” you can give this path an alias such as “PYTRNSYS$”. The “$” at the end of the alias needs to be included always to mark it as such:

string PYTRNSYS$ "C:\GIT\pytrnsys\data\ddcks"

Scaling

scaling

If this is set to “toDemand” the scaling functionality is activated for the parameter variation. (Options: “False” (default), “toDemand”):

string scaling "False"

scaleHP

Specify the size of the heat pump of the system in kW through some numerical value x and some variable that is defined in the scalingReference file (see below):

string scaleHP "x*variable"

scalingVariable

This defines a variable from the scalingReference file (see below) that is used for scaling the parameter variations:

string scalingVariable "name-of-your-scaling variable"

scalingReference

Full path to a json-file containing the variables used for scaling (see above):

string scalingReference "...\[name].json"

Parameter variation

A core feature of pytrnsys is the parameter variation. pytrnsys allows either to modify TRNSYS simulation parameters in the configuration file statically or with variations that result in parametric runs.

deck

A certain trnsysVariable defined in the dck-file can be set to a certain value by overwriting the previous one through:

deck trnsysVariable value

This feature can for example be used to change the starting time of the simulation(s):

deck START 4344

variation

A parametric study, i.e. several TRNSYS simulations with different values for a certain trnsysVariable, can be launched with the following command:

variation variationName trnsysVariable value1 value2 value3 ...

Here, variationName defines how the variation will be noted in the names of the dck-files to be generated. In general the values are absolute values of the respective trnsysVariable. If scaling is set to “toDemand”, however, then the values are the factors by which the scalingVariable is mulitplied to receive the actual numerical value of the trnsysVariable. If, e.g., the scalingVariable is the yearly heat demand of a system in MWh and the trnsysVariable to be varied is the area of the solar collector field called AcollAp in m2, then this area can be varied as multiples of the yearly heat demand (in m2/MWh) like this:

variation Ac AcollAp 1.0 1.5 2.0 2.5 3.0

combineAllCases

If several variations are defined, this parameter controls their combination. If it is set to the default True, all combinations are created. So if n values are given for variation 1 and m values are in variation 2 the total amount of simulations executed will be (m x n). If it is set to False, the amount of values of all variations has to be equal and they are combined according to their order:

bool combineAllCases True

changeDdckFile

Instead of only varying one or more variable, due to its modular nature, pytrnsys also allows to vary through different ddck-files:

changeDDckFile originalDdck ddckVariation1 ddckVariation2 ddckVariation3 ...

This can be used, e.g., to change the weather location for a simulation very swiftly. Assuming the weather data is specified through a file of the type City..._dryK and the locations BAS, CDF and LUG should be simulated, this can be done with the command:

changeDDckFile CityBAS_dryK CityBAS_dryK CityCDF_dryK CityLUG_dryK

random variations

If the influence of many different parameters is of interest, random variations might be needed. Random variations can be done with the keywords randvar, randvarddck, nrandvar and randseed. If using random variations, do not include any regular variations and be aware, that only one ddck can be changed with randvarddck.

randvar

Random variations of trnsys constants can be executed by adding one or multiple lines like the following:

randvar variationName trnsysVariable minValue maxValue stepSize

Here, variationName defines how the variation will be noted in the names of the dck-files to be generated. The minValue and maxValue are the minimum and maximum Value that the trnsysVariable will take, respectively. stepSize describes the step size of the values that can be taken between minValue and maxValue. Make sure that maxValue = minValue + n * stepSize. Where n is an integer. In the following example, the storage size will be taken between 0.5 m3 and 1 m3 in steps of 0.1, so it will have the options 0.5, 0.6, 0.7, 0.8, 0.9, 1:

randvar Vtes storageSize 0.5 1 0.1

randvarddck

Random variations of ddcks can be included with the following command:

randvarddck originalDdck ddckVariation1 ddckVariation2 ddckVariation3 ... ddckVariationn

For every iteration pytrnsys then takes randomly one of the n ddckVariation instead of the originalDdck, that is specified in the used ddcks section. Currently, only one ddck can be randomly varied.

nrandvar

This keyword describes the total number of random variations to be simulated, if e.g. 1000 variations should be simulated, the following line has to be added:

nrandvar 1000

Default value of nrandvar is 100.

randseed

This keyword describes an integer, that is used as a seed. If a seed is set, then rerunning a simulation will yield the same variations. A different integer will yield different random variations.

Example:

randseed 1

If randseed is not defined or of it is set to None, then the variations will be different every time.

ddck files

The core of the run configuration file is the ddck section. In this part of the configuration file, the different modular ddck files that should be used in the simulation are specified:

PATH_ALIAS_1$ head
PATH_ALIAS_2$ ddck_1
PATH_ALIAS_2$ ddck_2
...
PATH_ALIAS_m$ ddck_n
PATH_ALIAS_1$ end

An example can be found in the example section below. The path to the repository root can be either absolute or relative. If a relative path is detected, pytrnsys will interpret it as relative to the configuration file location.

Example

Here is an example of a run configuration file. It is taken from the example project solar_dhw (run_solar_dhw.config):

######### Generic ########################
bool ignoreOnlinePlotter  True
int reduceCpu  4
bool parseFileCreated True
bool runCases True
bool checkDeck True

############# AUTOMATIC WORK BOOL##############################

bool doAutoUnitNumbering True
bool generateUnitTypesUsed True
bool addAutomaticEnergyBalance True

#############PATHS################################

string trnsysExePath "C:\Trnsys17\Exe\TRNExe.exe"
string addResultsFolder "solar_dhw"
string PYTRNSYS$ "..\..\pytrnsys_ddck\"
string LOCAL$ ".\"

################SCALING#########################

string scaling "False" #"toDemand"
string nameRef "SFH_DHW"
string runType "runFromConfig"

#############PARAMETRIC VARIATIONS##################

bool combineAllCases True
variation Ac AcollAp 2 3 4 6 8 10
variation VTes volPerM2Col 75 100

#############FIXED CHANGED IN DDCK##################

deck START 0    # 0 is midnight new year
deck STOP  8760 #
deck sizeAux 3

#############USED DDCKs##################

PYTRNSYS$ generic\head
PYTRNSYS$ demands\dhw\dhw_sfh_task44
PYTRNSYS$ weather\weather_data_base
PYTRNSYS$ weather\SIA\normal\CitySMA_dryN
PYTRNSYS$ solar_collector\type1\database\type1_constants_CobraAK2_8V
PYTRNSYS$ solar_collector\type1\type1
LOCAL$ solar_dhw_control
LOCAL$ solar_dhw_storage1
LOCAL$ solar_dhw_hydraulic
LOCAL$ solar_dhw_control_plotter
PYTRNSYS$ generic\end