In [1]:
import pybps
import os
import sys
import re
import sqlite3
import pandas as pd
from pandas.io import sql
import matplotlib.pyplot as plt
Once the pybps is imported into python, the first thing to do is to create an instance of the BPSProject class to get all the information required to run a particular simulation project from the project directory and hold it in a series of instance variables. This way, the project information will be easily retrieved when the different functions that manage simulation pre/post-processing and running are called.
The simplest and quickest way to get ready is to instanciate the BPSProject class with the path and batch arguments defined. path is the path (relative or absolute) to the directory holding the simulation files for a particular project. batch is a flag which sets whether the simulation project corresponds to a single run (batch = False, which is the default value) or to a batch run (batch = True).
In the present tutorial, we will use the very simple Begin example TRNSYS project that can be found in the Examples directory of any TRNSYS installation. We just made some modifications to the output (using Type46) and added parameters in an external parameters.txt file for the batch run. This example project can be found in the Examples/TRNSYS folder found in the PyBPS package. Note that as of today, PyBPS has only been tested with TRNSYS simulation projects, altought its functionnalities could easily be used with any other text-file-based simulation tool.
In [2]:
bps = pybps.BPSProject('Examples/TRNSYS/Begin', batch=True)
Another way to create an instance of the BPSProject class is to call it without any arguments and then use the path and batch methods to set both variables. In the case of the batch method, calling it sets batch to True (since by default it is set to False, which corresponds to a single simulation run).
In [3]:
bps = pybps.BPSProject()
bps.path('Examples/TRNSYS/Begin')
bps.batch()
Once we have got our bps object created, we can check the simulation project info obtained from the project folder and stored in the object's attributes. Behind the scenes, the BPSProject class uses two hidden methods to detect the simulation tool to be used (based on file extensions found in given directory) and to get the info required to run single or batch runs. The basic info needed to run any tool is contained in the config.ini file is the base folder of the pybps package.
If the project is of the "single run" type, the following instance variables hold the basic info needed to actually run the simulation:
In [3]:
# Path to the folder containing simulation files
bps.path
Out[3]:
In [4]:
# Simulation tool name
bps.sim_tool
Out[4]:
In [5]:
# Simulation input file path
bps.simfile_path
Out[5]:
In [6]:
# Basic config info needed to call the proper commands to run the simulation tool and identify the basic simulation files.
# This info is contained in the "config.ini" file.
bps.config
Out[6]:
In [7]:
# Particular configuration parameters can be acceded like in any python dictionnary
bps.config['executable']
Out[7]:
If the simulation project happens to be a batch run, an additional set of instance variables is created to hold information about the template and parameter files, as well as the list of jobs to be run. In pybps, template files are simulation files containing parameters to be replaced prior to running simulation. Parameters are identified as strings surrounded by % signs, like %PAR% for example. The user has to create the template files (replacing acordingly the simulation parameters with parameters search strings) prior to calling the pybps package and place a parameter file in csv format in the project folder. Template and parameter files should contain a specific search string in their filename to be recognized as such by pybps. By default, users should include _TMP in template filenames and _PAR in parameter filenames. These are just the default settings and can be modified in the config.ini file.
If the simulation project was identified by the user as corresponding to a batch run (batch = True) and pybps can't find any template or parameter file, it will give an error message and exit.
In [9]:
# Unique ID for the batch to be run. Allows for succesive batch runs with different sets of parameters to be run within a same directory without the risk to overwrite cases.
# Also helps for storing info in sql databases
bps.series_id
Out[9]:
In [10]:
# List of paths to the template files found in the project directory
bps.tmpfiles_pathlist
Out[10]:
In [11]:
# Path to parameter file
bps.paramfile_path
Out[11]:
In [12]:
# List of jobs to be run
# This is actually a list of dicts containing all the parameters for the current batch run
bps.job_list
Out[12]:
In [13]:
# Number of simulation jobs to be run
bps.njob
Out[13]:
In [16]:
job = pybps.BPSJob('Examples/TRNSYS/Begin_PARAM/SIM00001')
job.path
Out[16]:
In [ ]:
bpsbatch.job[1].run()
In [ ]:
bpsbatch.run()