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
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 somevariable
that is defined in thescalingReference
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 certainvalue
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 certaintrnsysVariable
, 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 thevalues
are absolute values of the respectivetrnsysVariable
. If scaling is set to “toDemand”, however, then thevalues
are the factors by which thescalingVariable
is mulitplied to receive the actual numerical value of thetrnsysVariable
. If, e.g., thescalingVariable
is the yearly heat demand of a system in MWh and thetrnsysVariable
to be varied is the area of the solar collector field calledAcollAp
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 locationsBAS
,CDF
andLUG
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. TheminValue
andmaxValue
are the minimum and maximum Value that thetrnsysVariable
will take, respectively.stepSize
describes the step size of the values that can be taken betweenminValue
andmaxValue
. Make sure thatmaxValue
=minValue
+n
*stepSize
. Wheren
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 theoriginalDdck
, 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