ResultsReader

class iesve.ResultsReader

Bases: object

Support for reading simulation result files (APS files).

Basic usage:

1with iesve.ResultsReader.open(filename) as f:
2    x = f.get_results('Total electricity', 'Total electricity', 'e')
3    # f.closed() is called automatically when using with.

Notes on Reading APS files

The ResultsReader API has many references to variables and variable levels. This section will explain Variables and their details a bit further.

Variables have 2 names:

• An internal name which is used in the APS file. Pass this name to the various reading APIs that are part of the ResultsReader class

• A display name, which is shown in Vista / VistaPro. Attempting to read this from an APS will normally result in an error; there are certain exceptions to this however see iesve.ResultsReader.get_room_results() for more details.

The variable level (also known as model level flag) is represented by a single character as shown in the table below, together with the corresponding API for reading the data.

Surface level results are available only for those rooms that have detailed output switched on for a surface-level result (Apache Simulation output options: Surface temperatures, External / internal incident solar flux)

Opening level results are available only if Macroflo was included in simulation.

For more information on reading APS data, and information on how to map a Vista / VistaPro display string to a variable, see the sample on reading APS data.

Valid Model Level flags (character)	API for reading data at this level
w = weather	get_weather_results
z = room level (zone)	get_room_results
v = apache systems misc	get_apache_system_results
j = apache systems energy	get_apache_system_results
r = apache systems carbon	get_apache_system_results
l = building loads	get_results
e = building energy	get_results
c = building carbon	get_results
s = surface level	get_surface_results
o = opening level	get_opening_results
n = HVAC node level	get_hvac_node_results
h = HVAC component level	get_hvac_component_results

static open(filename: str) → ResultsReader

Open an APS file and return a ResultsReader instance. Throws exception on error.

close() → None

Close the results file, and releases all resources associated with the file. It is recommended to close files as soon as possible to save resources.

Recommend using with iesve.ResultsReader.open(filename) as f as close will be called automatically

get_all_apache_system_results(system_id: str, aps_var: str, var_level: str, start_day: int = -1, end_day: int = -1) → dict

Dictionary of numpy array of floats, keyed by variable display name

Get the results for specified system + variable. See units spreadsheet for available variables and matching level.

See iesve.ResultsReader.get_results() for start_day and end_day details.

get_all_component_process_results(room_id: str, index_in_room: int, aps_var: str, var_level: str, start_day: int = -1, end_day: int = -1) → dict

Dictionary of numpy array of floats, keyed by variable display name

Read the results for specified process variable.

See iesve.ResultsReader.get_results() for start_day and end_day details.

get_all_opening_results(room_id: str, surface_index: int, opening_index: int, aps_var: str, start_day: int = -1, end_day: int = -1) → dict

Dictionary of numpy array of floats, keyed by variable display name

Get the results for specified opening + variable. Obtain: - room_ID from iesve.VEBody.get_index() - surface_index from iesve.VESurface.index - opening_index from iesve.VEGeometry.get_properties() - See units spreadsheet for available variables for aps_var - See iesve.ResultsReader.get_results() for start_day and end_day details

get_all_process_results(process_name: str, aps_var: str, start_day: int = -1, end_day: int = -1) → dict

Dictionary of numpy array of floats, keyed by variable display name Read the results for specified process variable.

See iesve.ResultsReader.get_results() for start_day and end_day details.

get_all_results(aps_var: str, var_level: str, start_day: int = -1, end_day: int = -1) → dict

Dictionary of numpy array of floats, keyed by variable display name

Get the model-level results for specified variable.

See units spreadsheet for information on variable + level

If start_day and/or end_day are omitted, all available results will be returned. start_day = 1 means January 1, end_day = 365 is December 31st.

Check APS file firstday and lastday properties for valid range for file.

Note: results are always returned in metric units

get_all_room_results(room_id: str, aps_var: str, var_level: str, start_day: int = -1, end_day: int = -1) → dict

Dictionary of numpy array of floats, keyed by variable display name

Get the results for specified room + variable. See units spreadsheet for available variables and matching level. See iesve.ResultsReader.get_results() for start_day and end_day details.

get_all_surface_results(room_id: str, aps_handle: int, aps_var: str, start_day: int = -1, end_day: int = -1) → dict

Dictionary of numpy array of floats, keyed by variable display name

Get the results for specified surface + variable.

See units spreadsheet for available variables for aps_var.

• room_id from iesve.VEBody

• aps_handle from iesve.VESurface.get_properties().

• See get_results() for start_day and end_day details.

get_all_weather_results(aps_var: str, start_day: int = -1, end_day: int = -1) → dict

Dictionary of numpy array of floats, keyed by variable display name Get the results for a weather variable. See units spreadsheet for available variables. See iesve.ResultsReader.get_results() for start_day and end_day details.

get_apache_system_results(system_id: str, aps_var: str, vista_var: str, var_level: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Get the results for specified system + variable. See variables list for available variables and matching level. See iesve.ResultsReader.get_results() for start_day and end_day details.

get_apache_systems() → list[tuple]

Get list of Apache Systems in the results file. Each list entry holds a tuple of (system name, system ID).

get_component_objects() → list[tuple[str, int, str, list[tuple[str, str, str]]]]

Return the list of process component objects for this results file. Structure:

[(room ID, index in room, component name, [(var name, var unit, var level)])]

The variable unit can be used as an index into the units list returned from iesve.ResultsReader.get_units().

get_component_process_results(room_id: str, index_in_room: int, aps_var: str, vista_var: str, var_level: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Read the results for specified process variable. See iesve.ResultsReader.get_results() for start_day and end_day details.

get_conditioned_sizes() → tuple[float, float, int]

Returns a tuple containing the conditioned area, volume and number of rooms as recorded in the results file.

get_data_file_details(filename: str, date_time_format: str = '%H:%M %d/%b/%y') → dict

Get a dictionary of file details.

Key	Description
name	Filename (str)
calculated	File date/time (str)
profile_month_start	Name of start month (str)
profile_month_end	Name of end month (str)

get_energy_meters(used_only: bool = True) → dict

Returns a dictionary of all (or only the used) energy meters in the file by id.

Each item is a dictionary containing information about a specific energy meter. Dictionary fields include:

Key	Description
has_subs	whether or not the meter has any child (sub) meters (bool)
id	the meter id (iesve.EnergyMeter)
name	the meter name (string)
parent_id	the id of the parent meter this meter belongs to, if any (iesve.EnergyMeter)
source_id	the id of the source the meter is assigned to (iesve.EnergySource)
used	whether or not the meter has any aps results (bool)

get_energy_results(use_id: EnergyUse = EnergyUse.unspecified, source_id: EnergySource = EnergySource.unspecified, meter_id: EnergyMeter = EnergyMeter.unspecified, type: str = 'e', add_subs: int = -1, start_day: int = -1, end_day: int = 1) → ndarray[Any, dtype[float32]] | None

Returns the specified energy results given the use id, source id, meter id and type. Setting type to ‘e’ or ‘c’ determines whether or not energy (W) or carbon (kgC) results are returned. Setting add_subs to 1 or 0 determines whether or not parent meter results include or do not include child (sub) meter results. When add_subs is -1 the option is ignored and the default behaviour will be applied.

See iesve.ResultsReader.get_results() for start_day and end_day details.

Example usage:

• get_energy_results() -> ‘Total Energy’

• get_energy_results(source_id=elec) -> ‘Electricity’

• get_energy_results(source_id=elec, meter_id=1 ) -> ‘Electricity: Meter 1’

• get_energy_results(use_id=prm_pumps) -> ‘Pumps’

• get_energy_results(use_id=prm_pumps, source_id=elec) -> ‘Pumps - Electricity’

• get_energy_results(use_id=prm_pumps, source_id=elec, meter_id=1) -> ‘Pumps - Electricity: Meter 1’

In the case of advanced comfort variables, the Vista variable should be used for both the vista_var and aps_var parameters. These are:

• PPD (ASHRAE 55 Analytical)

• PMV (ASHRAE 55 Analytical)

• CLO (ASHRAE 55 Analytical)

• PMV (ASHRAE 55 Adaptive)

• PPD (ASHRAE 55 Adaptive)

• CLO (ASHRAE 55 Adaptive)

• PMV (ASHRAE 55 Analytical direct-solar)

• PPD (ASHRAE 55 Analytical direct-solar)

• CLO (ASHRAE 55 Analytical direct-solar)

• MRT (ASHRAE 55 Analytical direct-solar)

• Top (ASHRAE 55 Analytical direct-solar)

• PMV (ASHRAE 55 Adaptive direct-solar)

• PPD (ASHRAE 55 Adaptive direct-solar)

• CLO (ASHRAE 55 Adaptive direct-solar)

• MRT (ASHRAE 55 Adaptive direct-solar)

• Top (ASHRAE 55 Adaptive direct-solar)

• PMV(ISO 7730 nominal air speed)

• PPD(ISO 7730 nominal air speed)

• PMV(ISO 7730 elevated air speed)

• PPD(ISO 7730 elevated air speed)

• PMV(ISO 7730 nom & elev air speed cat A)

• PPD(ISO 7730 nom & elev air speed cat A)

• PMV(ISO 7730 nom & elev air speed cat B)

• PPD(ISO 7730 nom & elev air speed cat B)

• PMV(ISO 7730 nom & elev air speed cat C)

• PPD(ISO 7730 nom & elev air speed cat C)

• Operative temperature (ASHRAE)

• Operative temperature (TM 52/CIBSE)

Note that when calculating results for these variables, an elevated air speed is applied between May-September.

get_energy_results_ex(use_ids: list[EnergyUse] | None = None, source_ids: list[EnergySource] | None = None, type: str = 'e', start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Returns the aggregated energy results for the specified use(s) and/or source(s). The use_ids argument can be None, a single use id, or a list of use ids.

The source_ids argument can be None, a single source id, or a list of source ids.

At least one use or one source must be specified.

Setting type to ‘e’ or ‘c’ determines whether or not energy (W) or carbon (kgC) results are returned.

See iesve.ResultsReader.get_results() for start_day and end_day details

get_energy_sources(used_only: bool = True) → dict

Returns a dictionary of all (or only the used) energy sources in the file by id. Each item is a dictionary containing information about a specific energy source. Dictionary fields include:

Key	Description
cef	the carbon emission factor of the source, used to convert kgC to kgCO2 (float)
id	the source id (iesve.EnergySource)
name	the source name (string)
used	whether or not the source has any aps results (bool)

get_energy_uses(used_only: bool = True) → dict

Returns a dictionary of all (or only the used) energy uses in the file by id. Each item is a dictionary containing information about a specific energy use. Dictionary fields include:

Key	Description
id	the use id (iesve.EnergyUse)
name	the use name (string)
tied_source_id	the id of the source the use is fixed to, if any (iesve.EnergySource)
used	whether or not the use has any aps results (bool)

get_hvac_component_results(component_id: str, component_type: int, var_name: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Get the results for HVAC Component ID + variable.

See variables list for available variables and matching level.

See iesve.ResultsReader.get_results() for start_day and end_day details.

See iesve.HVACComponentTypes for available types.

get_hvac_node_results(node_nr: int, layer_nr: int, var_name: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Get the results for HVAC Node. Use layer_nr to specify multiplex layer, or -1 for plant-side node (outside of multiplex).

See variables list for available variables and matching level.

See iesve.ResultsReader.get_results() for start_day and end_day details.

get_opening_results(room_id: str, surface_index: int, opening_index: int, aps_var: str, vista_var: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Get the results for specified opening + variable. - room_ID from iesve.VEBody.get_index() - surface_index from iesve.VESurface.index - opening_index from iesve.VEGeometry.get_properties() - See units spreadsheet for available variables for aps_var and vista_var. - See iesve.ResultsReader.get_results() for start_day and end_day details.

get_peak_results(room_id: str, variables: list) → dict

Get the peak results of a series of variables at room-level, for the specified room. Variables are specified by APS variable name (string). Returns the peak value for each variable, using the variable name as dictionary key.

get_process_list() → list

Return the list of process categories (strings) for this results file.

get_process_results(process_name: str, aps_var: str, vista_var: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Read the results for specified process variable.

See iesve.ResultsReader.get_results() for start_day and end_day details.

get_process_variables(process: str) → list[tuple]

For the process specified (one of the return values from GetProcessList), return the available process variables. The returned list contains tuples of: (name, units). The units can be used as an index into the units dictionary returned by get_units().

get_results(aps_var: str, vista_var: str, var_level: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Get the model-level results for specified variable.

See variables list for information on variable + level details, as well as footnotes at the end of this section.

If start_day and/or end_day are omitted, all available results will be returned. start_day = 1 means January 1, end_day = 365 is December 31st. start_day and end_day value of -1 means first and last available day respectively.

Check first_day and last_day properties for valid range for file.

Note: results are always returned in metric units

get_room_geometry_details(room_id: list | str) → list[dict] | dict

Returns a list of dictionaries for all requested room IDs. You can also pass a single room ID string, in which case a single dictionary is returned. All units are in m². Dictionary entries are:

opaque, glazed, internal_wall, external_wall, internal_glazed, num_open, num_surf, external_glazed, rooflight, door, floor, ground_floor, ceiling, roof.

Note: glazing areas have construction frame dimensions applied (net glazed area, not gross opening area).

get_room_ids() → list[str]

Returns a list of room IDs for all rooms in the results file.

get_room_list() → list[tuple]

Returns a list of (room name, room ID, room area, room volume) tuples for all rooms in the results file.

get_room_results(room_id: str, aps_var: str, vista_var: str, var_level: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Get the results for specified room + variable.

See variables list for available variables and matching level.

See iesve.ResultsReader.get_results() for start_day and end_day details.

get_surface_results(room_id: str, aps_handle: int, aps_var: str, vista_var: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

See units spreadsheet for available variables for aps_var and vista_var.

Obtain room_id from VEBody.get_index() and aps_handle from VESurface.get_properties().

See get_results() for start_day and end_day details.

get_units() → dict

Get the list of results file units that are applicable to the loaded file. The return value is a dictionary, keyed by unit type (string). This unit type corresponds to the units_type field for APS variables, as well as the units for process variables.

Each units data field consists of another dictionary with 2 fields: ‘units_IP’ and ‘units_metric’. These provide the conversion from APS raw data to both IP and metric display values.

The available unit data fields are:

• divisor

• offset

• display_name

To achieve conversion of the raw APS results to display_name, divide the variable by divisor, and for temperatures also add offset (to convert degrees C to Fahrenheit).

For example, to display a ‘Power’ units variable in IP units:

1aps_data = resultsfile.get_results(var_aps_name, var_model_level)
2peak = np.max(aps_data)
3aps_units = resultsfile.get_units()
4power_units = aps_units['Power']
5pu_ip = power_units['units_IP']
6peak_IP = (peak / pu_ip['divisor']) + pu_ip['offset']
7print('{} {}'.format(peak_IP, pu_ip['display_name'])

get_unmet_hours(excluded_room_ids: list[str] = []) → dict

Get unmet load hours data. Keys are: ‘cooling’ and ‘heating’

get_variables() → list[dict]

Get the list of results file variables that are applicable to the loaded file. The return value is a list of dictionaries, with each dictionary entry containing the various information fields for a variable.

Available data fields are:

Key	Description
aps_varname	APS result name. Use this string for all ResultReader functions
display_name	the Vista / VistaPro name for this variable
model_level	variable level for ResultsReader function parameters
units_type	results unit for this variable. Use this as index to unit dictionary

get_weather_results(aps_var: str, vista_var: str, start_day: int = -1, end_day: int = -1) → ndarray[Any, dtype[float32]] | None

Get the results for specified weather variable.

See variable list for available variables, matching level, and units.

See iesve.ResultsReader.get_results() for start_day and end_day details.

open_aps_data(filename: str) → int

Open an APS file, returns 1 on success, throws exception on file not found

first_day: int

The first simulation day that has results

first_weekday_plot_year: int

The day-of-week (Sun = 1..) of Jan 1 in plot year

hvac_file: str

The HVAC network used for simulation

last_day: int

The last simulation day that has results

plot_data_offset_secs: int

The plot data offset in seconds

plot_year: int

The plot year

results_per_day: int

The number of results per 24 hour period

simulation_year: int

The simulation year

weather_file: str

The weatherfile used for simulation