Package: pybps
PyBPS is a simulation manager that provides a framework for running parametric simulation jobs in an efficient way.
It includes modules to:Pre-process parametric simulation jobs(prepare simulation input files with a specific set of parameters)Run simulation jobs in parallel, making the most of available processors to run the parametric jobs fasterPost-process simulation jobs, by extracting results directly from simulation output filesStore simulation parameters and resultsin an SQlite database and a set of CSV files for subsequent analysisProduce a simulation run summary, including execution times of all simulated jobs, warnings and errors.The package usespandasDataFrames to handle data, which opens a lot of possibilities in terms of data analysis.
Users can therefore leverage all of the power of thepandaspackage to analyze simulation results.
Usingpandasalso makes it very straightforward to plot results using thematplotlibpackage.InstallationTo install PyBPS, use pip:$ pip install pybpsIf you have an earlier version of PyBPS already installed that you want to upgrade, just use:$ pip install pybps --upgradeThis will also upgrade PyBPS dependencies.Additionally, you will need to installjupyter notebookandmatplotlibto view and run the tutorial notebook:$ pip install jupyter matplotlibConfigurationPrior to using PyBPS, you first have to configure simulation tools options in theconfig.inifile located at the root of thepybpsdirectory (usuallyC:\Python27\Lib\site-packages\pybps).Alternatively, you can also include aconfig.inifile in your project directory with a project specific configuration. PyBPS will override default configuration settings whenever a customconfig.inifile is found in the project directory.Currently, PyBPS works on Windows with the following building performance simulation tools:TRNSYS v17DAYSIM v3.1bMost of the configuration options should be left to their default value. However, the user should revise the following options:Simulation tool installation directory[TRNSYS]
Install_Dir = C:\TRNSYS17  # Default installation directory for TRNSYS v17

[DAYSIM]
Install_Dir = C:\DAYSIM   # Default installation directory for DAYSIMIMPORTANT:If your DAYSIM install directory is different from the one above, you will also have to modify theDAYSIMPATHin the batch scriptpybps_daysim-exe.batfound inC:\Python27\ScriptsSimulation result file extensionsSimulation result files are files that might require post-processing and that will be exported to CSV and/or SQlite database.[TRNSYS]
ResultFile_Extensions = .out, .month  # Default extensions for TRNSYS output files

[DAYSIM]
ResultFile_Extensions = .el.htm, .DA  # Default extensions for DAYSIM output filesIn the current version of PyBPS, when working with TRNSYS, for the simulation results to be parsed automatically you must output monthly integrated results with aType46. All the results should go to a unique output file.
Future version of PyBPS will support additional TRNSYS output formats.Simulation log file extensionsLog files are files that are just kept for reference.[TRNSYS]
LogFile_Extensions = .log  # Default extensions for TRNSYS log files

[DAYSIM]
LogFile_Extensions = _active.intgain.csv  # Default extensions for DAYSIM log filesActually, DAYSIM does not produce log files, but since this field can’t be left empty, just put here the extensions of files that won’t need post-processing.Template files search stringUsed to identify which files are templates, that is, files containing parameter search strings to be replaced by real values.
Template filenames should contain the specified string.TemplateFile_SearchString = _Template   # Example: Model_Template.dckParameter sample files search stringUsed to identify which file contains the parameter sample, that is, file containing real values for all parameters found in template files.
Sample filenames should contain the specified string.SampleFile_SearchString = _Samples   # Example: Model_Sample.csvPrerequisitesIn addition to the necessary configuration options commented above, there is a set of prerequisites to ensure PyBPS can work properly with your building simulation project.Template FilesTemplate files have to be properly identified by putting the search string specified inconfig.iniin their filename.
For example, the template file for the3Dbuilding.dckproject would be3Dbuilding_Template.dck.To properly work as a template file, it should contain parameter search strings in place of actual parameters that should be replaced by PyBPS in each simulation job.It is a requirement of PyBPS that all parameter search strings should be strings of characters with a leading $ sign.Valid parameter search strings would look like:$ORIENTATION  # Valid search string for ORIENTATION parameter
$HEAT_SETPOINT # Valid search string for HEAT_SETPOINT parameterSample FileFor every single parameter search string defined in the template files, there should be a corresponding column with values in the sample file.Sample files should always be CSV files and be properly identified by putting the search string specified inconfig.iniin their filename.
For example, the sample file for the3Dbuilding.dckproject would be3Dbuilding_Sample.csvand would contain the following information:ORIENTATION,HEAT_SETPOINT
0,20
0,21
180,20
180,21
...UsageShell ScriptThe simplest way to start using PyBPS is by way of the shell script.Just open a command line window and callrun-pybps.pyfollowed by the path to the BPS project directory. It should look like this:$ run-pybps.py C:\My_BPS_Project\The script accepts optional arguments to control the number of local threads/processors to be used in simulation run and to calculate to total execution time.
For example, calling the script with the following arguments will limit to 2 threads/processors and returns the batch execution run time:$ run-pybps.py --ncore 2 --stopwatch C:\My_BPS_Project\PackageIf you are already proficient with Python programming, you can get more control over the simulation workflow by directly using the methods of thePyBPSpackage in your own script.
The best way to start is probably by having a look at therun-pybps.pyscript mentioned above.
Anyway, here is a quick guide to the main methods and functions contained in thePyBPSpackage.To get started, it is necessary to import theBPSProjectclass definition:From pybps import BPSProjectAn instance of theBPSProjectclass should then be created, giving the path to the simulation project directory as an argument:path_to_bps_project = 'C:\BPS_PROJECT'
bpsproj = BPSProject(path_to_bps_project)During the instance creation process, the given directory is analyzed and all of the information necessary to run the simulation jobs is stored in the new instance: paths to simulation input files, details about simulation tool to be used, parameter sample, etc…
Once the new instance has been created, class methods can be used to manage the parametric simulation jobs.
For example, simulation jobs identified from the parameter sample can (and should) be added using the following method:bpsproj.add_jobs()This step creates instances of aBPSJobclass for each one of the identified simulation jobs.
Additional functions can be written by the user to modify the parameter sample prior to adding jobs to the simulation project.
For example, it is possible to have several simulation input files listed in the project directory and select a different input file in each job based on specific parameter values.A particular job can be manage using the following methods:bpsproj.jobs[0].prepare()    # Copy all simulation files to a temp directory where the first job will be run
bpsproj.jobs[0].preprocess() # Create simulation input files with set of parameters for first job
bpsproj.jobs[0].run()        # Run the first job
bpsproj.jobs[0].close()      # Copy result and log files to results dir, get job run summary and delete temp dirThe decision of which result and log files should be copied to theResultsdirectory depends on the files extensions specified in theResultFile_ExtensionsandLogFile_Extensionskeywords of theconfig.inifile.In general, it is more common to run all simulation jobs at once.
Calling therunmethod without arguments launches simulation jobs in parallel using all available processors:bpsproj.run()You can also limit the number of threads/processors used to prevent PyBPS from eating up all of the available computing resources:bpsproj.run(ncore=2)   # limits the current run to 2 threads/processorsWhen all simulation jobs have been run, all of the information related to the current simulation project (job parameters, results and run summaries) can be stored inpandasDataFrames:bpsproj.jobs2df()
bpsproj.results2df()
bpsproj.runsum2df()Once our simulation project data is in DataFrames, it can be stored in an SQlite database and/or CSV files:bpsproj.save2db()
bpsproj.save2csv()LicenseThis software is licensed under the3-clauseBSD license. See theLICENSEfile in the top distribution directory for the full license text.ContributorsPyBPS is open to contributions! Feel free to forkthe repositoryon github to start making your changes.