Introduction
The Python API (application programming interface) was introduced in VE 2017. An API in its simplest terms is a mechanism for one software program to communicate with another software program. The VE Python API allows users create simple programs using the Python Programming Language, to interact with a VE Model and/or Vista Results File. This gives users the option to automate many of the repetitive tasks, which up to now would have been relatively tedious.
The VE Python API will allow users to create simple python programs, to automatically:
Extract specific information from a VE Model or Vista Results file,
Perform some calculations on the data if desired,
Arrange the data into a standard format,
Write the data to another program such as Microsoft Excel or Word.
Some simple examples of this would include:
Extracting air temperatures for a group of rooms from the Vista Results File, performing a range test to determine the percentage of annual occupied hours that each room is above 28oC and then writing this data to an excel sheet.
Extracting room data (internal gains, ventilation rates, etc.) for a group of rooms from the building template manager, collating this data into a table and then writing it to an excel sheet.
Extracting location and climate data from the weather file that is assigned to a model and writing it to a word file.
Introduction to Python
Python is a high level interpreted programming language used for general purpose programming and scripting. The main advantage of using Python over other programming languages is its readability and user friendliness. Python has a syntax that allows programs to be expressed in fewer lines of code than would be possible in many other languages. Python has a large library of open source modules that can be easily imported and used in any project. An experienced programmer in any other language can pick up Python very quickly, however it is also quite straightforward for beginners to learn and use. Note that the VE Python API uses Python 3 not Python 2.
Before attempting to use the VE Python API, it is strongly advised that the user becomes familiar with the basics of the Python Programming Language. Specifically the user must be competent in the following areas:
Variables and Types
How to declare variables
Types -> int, float, string, bool
Lists
Accessing values in a list using []
Append and Delete values from list
Get max min and length of list
Basic Operators
Arithmetic operators: ‘+’, ‘-’, ‘*’, ‘/’
Comparison operators: ‘==’, ‘!=’, ‘>’, ‘<’ , ‘>=’, ‘<=’
Assignment operators: ‘=’, ‘+=’, ‘-=’
Bool operators: ‘and’, ‘or’
Using operators with lists
String Formatting
String substitution
Basic String Operation
String slicing
‘.split()’, ‘.strip()’, ‘len(), ‘join()’
Concatenating strings using + operator
Conditionals
‘if’, ‘else’, ‘elif’ statements
Using with Bool operators
Loops
‘for’ loop
‘while’ loop
‘break’ and ‘continue’ statements
Functions
Defining a function
Calling a function
Arguments and Parameters
Dictionaries
Initialising a dictionary object
Adding and removing items from a dictionary
Accessing values in a dictionary using a key
Iterating over dictionaries using a ‘for’ loop
Modules and Packages
Importing built in modules
‘from’, ‘import’, ‘as’ statements
List Comprehensions
Creating a new list based on an existing list
Classes and Objects
Defining a class
The ‘__init__ ():’method
Defining attributes of a class
Defining methods of a class
Declaring an object
Additional Resources
Many free online learning resources including:
Basic Python Tutorials:
Numpy Tutorial for Beginners:
Xlsx Writer Tutorial:
Note that in addition to knowing the basics of Python, it is advisable that the user has experience in the VE before attempting to use the VE Python API.
3rd Party Libraries
Python version 3.12.3.
The following 3rd party python libraries are available in the VE Python environment:
- Numpy 1.26.4
- Scipy 1.14.1
- Pandas 2.2.3
- Matplotlib 3.10.0 (+ the Seaborn 0.13.2 formatting package)
- Dateutil 2.9.0.post0 (extensions to the standard python datetime module)
- Docx 1.1.2 (create Word documents)
- XlsxWriter 3.2.0 (create Excel spreadsheets)
- Xlrd 2.0.1 (read Excel spreadsheets)
- Lxml 6.0.2 (xml reader/writer)
- Pywin32 307 (Windows extensions, including COM interoperability)
- CoolProp 7.2.0 (thermodynamic and transport properties database)
- NumExpr 2.10.0 (fast numerical expression evaluator for NumPy)
- Jinja2 3.1.5 (templating language)
- MarkupSafe 2.1.5 (create XML/HTML/XHTML Markup safe string)
- Pillow 11.3.0 (Python imaging library)
- bokeh 3.4.1 (HTML based plotting library, output to file only)
- requests 2.33.1 (HTTP requests made easy)
- PyTables 3.11.1 (large dataset support, including HDF5 support for Pandas)
- Arrow 1.3.0 (better dates and times)
- ReportLab 4.2.0 (PDF creation library)
- Pint 0.25.2 (unit conversion)
- Six 1.16.0 (Python 2/3 compatibility library)
- Python-tabulate 0.9.0
- BeautifulSoup4 4.12.3
- Scikit-learn 1.7.2
- Statsmodel 0.14.2
- Openpyxl 3.1.2
- Plotly 5.24.1
- Psychrochart 0.11.1
- Folium 0.18.0
- Pvlib 0.11.1
PyGMO was available in previous versions of the VE Python environment. However this library is no longer included.