How to run a SAP 10 calculation in Python

This post shows how to use the sap10calcs Python package to run a Standard Assessment Procedure 10.2 (SAP10) calculation.

What is sap10calcs?

sap10calcs is a Python package I have written. It does two things:

• It runs SAP 10.2 calculations, by acting as a wrapper for this API service.
• It provides tools to create and edit SAP 10 input data XML files.

The documentation for the package is available on the main GitHub page, which also contains a suite of examples of how to use the package to work with SAP 10 calculations.

What is SAP 10?

The Standard Assessment Procedure is a method to calculate the energy consumption of UK dwellings. SAP version 10 is published by the Building Research Establishment (see here). SAP 10.2 is the latest version and is used by the UK government in the building regulations for the design of new dwellings. SAP is also the calculation engine for domestic energy performance certificates.

Installing sap10calcs

sap10calcs can be installed by running the following command in the Command Prompt:

pip install sap10calcs

Running the SAP10 calculation

Here is the Python code to run the calculation:

import sap10calcs
result = sap10calcs.calculate(
    input_file = 'Example - creating a complete SAP XML file.xml'
)
print(result['sap_calculation_success'])
# >>> True

This makes use of the calculate function. This function:

• takes a SAP XML input data file as an argument (input_file). The input file used in this example is this one, which is created here. The input data is a detached house with gas central heating.
• sends this input data to the remote API service
• returns the results (in this case placing them in the variable result)

The complete set of results returned in this example is available here.

What are the results?

The result variable returned by the calculate function is a dictionary.

It contains information about the API call itself, and the results of the SAP 10 calculation.

API results

The API results can be viewed using the Python code below. This removes the SAP 10 calculation results and places them in a separate variable output_dict.

output_dict = result.pop('sap_calculation_output_dict')
print(result)

{
 'api_call_datetime': '2024-10-28 05:47:37.552160',
 'api_call_url': 'https://netzeroapis.com/calc/sap10?calculation_method=Energy%20rating',
 'api_call_filename': 'Example - creating a complete SAP XML file.xml',
 'api_call_server_time_seconds': 0.027029944001697004,
 'licenses': ['https://netzeroapis.com/redoc#section/Terms-and-Conditions',
  'https://creativecommons.org/publicdomain/zero/1.0/'],
 'sap_calculation_success': True,
 'sap_calculation_error_type': None,
 'sap_calculation_error_message': None,
 'sap_calculation_error_traceback': None
 }

The sap_calculation_success variable is True which tells us the SAP 10 calculation made it to the end. If there was an error in the calcuation process then sap_calculation_success would be False and the returned calculation outputs would be incomplete.

If an error occurs during the calculation process, then the details are shown in the three sap_calculation_error_... variables.

Information about the API call is given in the api_call_... variables. Here the API was called on 28th October 2024 and took 0.027 seconds to run the calculation.

SAP 10 calculation results

The SAP 10.2 calculation results can be seen using:

print('number of output variables:', len(output_dict))
print('---')
for k, v in output_dict.items():
    print(f'{k}: {v}')

number of output variables: 2342
---
calculation_type: Energy rating
region_code: 0
postcode: None
postcode_area: None
postcode_district: None
latitude: 53.5
pcdb_fuel_price_table_name: None
main_heating_1_fghrs_index_number: None
value_1_building_part_1_level_0: 100.0
value_2_building_part_1_level_0: 3.0
value_3_level_0: 300.0
value_4: 100.0
value_5: 300.0
...
electricity_sold_to_grid_pv_unit_price: 5.59
electricity_sold_to_grid_other_unit_price: 5.59
value_252: 0.0
value_253: None
value_254: None
value_255: 628.527382156558
value_256: 0.36
value_257: 1.5604817763886958
sap_value: 74.70459040473924
value_258: 75
sap_band: C

For this example, the SAP calculation results comprise of 2,342 key/value pairs, stored in a Python dictionary.

Variables starting with value... match the values as seen in the SAP Worksheet in the SAP 10.2 PDF document. For example value_5 is the "Dwelling volume" in m³.

The remaining variables are other SAP calculations which are not associated with a specfic variable in the SAP Worksheet. These are often intermediate calculation steps. These variables are named to match the calculation step and their meaining can be discerned from the calculation descriptions in the SAP 10.2 PDF document.

In this example:

• There are some pre-calculation steps including the calculation_type ("Energy rating"), the region_code ("0" - representing UK average - see SAP10.2 Table U1) and the latitude (53.5^o).
• The SAP Worksheet calculations start with value_1_building_part_1_level_0. This is the area in m² of the ground floor of the first part of the building.
• The SAP Worksheet calcuations end with value_258 (the SAP rating) and the sap_band (a letter between A to G - see SAP10.2 Table 14).

Summary

This post has shown how to use the sap10calcs Python package to run a SAP 10.2 calculation.

This is done using the calculate function, which takes this input file and returns this output dictionary.

A Jupyter Notebook with this example is available here.