ladybug.sql module

Module for parsing EnergyPlus SQLite result files into Ladybug DataCollections

class ladybug.sql.ComponentSize(sql_table_rows)[source]

Bases: object

Object for holding the sizing results of an individual HVAC components.

Parameters:

sql_table_rows – A list of list where each sub-list represents a row of the SQLite ComponentSizes table. These rows are all expected to have the same component name.

Properties:

  • component_type

  • component_name

  • descriptions

  • properties

  • values

  • units

  • properties_dict

ToString()[source]

Overwrite .NET ToString.

classmethod from_dict(data)[source]

Create a ComponentSize from a dictionary.

Parameters:

data – ComponentSize dictionary following the format below.

{
"type": "ComponentSize",
"component_type": str,
"component_name": str,
"properties": [],
"values": [],
"units": []
}
to_dict()[source]

Get ComponentSize as a dictionary.

property component_name

Get text for the name of component that this object represents.

property component_type

Get text for the type of component that this object represents.

property descriptions

Get a tuple with text descriptions for all component properties.

Descriptions are formatted as component_name-property-unit. They are aligned with the values on this object.

property properties

Get a tuple with text for all component properties.

They are aligned with the values on this object.

property properties_dict

Get a dictionary with the properties as keys and values as the values.

property units

Get a tuple with text for all component property units.

They are aligned with the values on this object.

property values

Get a tuple with numbers for all component property values.

They are aligned with the properties on this object.

class ladybug.sql.SQLiteResult(file_path)[source]

Bases: object

Object for parsing EnergyPlus SQLite result files into Ladybug DataCollections.

Parameters:

file_path – Full path to an SQLite file that was generated by EnergyPlus.

Properties:

  • file_path

  • location

  • reporting_frequency

  • run_periods

  • run_period_names

  • run_period_indices

  • available_outputs

  • available_outputs_info

  • zone_cooling_sizes

  • zone_heating_sizes

  • component_sizes

  • component_types

ToString()[source]

Overwrite .NET ToString.

component_sizes_by_type(component_type)[source]

Get a list of ComponentSize objects for a specific type of HVAC component.

This can be much faster than using the component_sizes property when there are a lot of components in the model and only one type of component is needed.

Parameters:

component_type – Text for the type of component to be retrieved. (eg. ‘ZoneHVAC:IdealLoadsAirSystem’)

data_collections_by_output_name(output_name)[source]

Get an array of Ladybug DataCollections for a specified output.

Parameters:

output_name – The name of an EnergyPlus output to be retrieved from the SQLite result file. This can also be an array of output names for which all data collections should be retrieved.

Returns:

An array of data collections of the requested output type. This will be an empty list if no output of the requested name was found in the file.

data_collections_by_output_name_run_period(output_name, run_period_index)[source]

Get an array of Ladybug DataCollections for an output and a run period index.

Parameters:

  • output_name – The name of an EnergyPlus output to be retrieved from the SQLite result file as a string.

  • run_period_index – An integer taken from the run_period_indices property of this object, which will be used to select out data collections for just one run period in the SQL file.

Returns:

An array of data collections of the requested output type. This will be an empty list if no output of the requested name was found in the file.

tabular_column_names(table_name, report_name=None)[source]

Get the names of the columns for a table of a Summary Report.

Parameters:

  • table_name – Text string for the name of a table within a summary report. (eg. ‘General’).

  • report_name – An optional text string to indicate the report name from which the table should be pulled. This is useful in cases where tables have the same name in different reports. If None, data from all available tables will be returned. (Default: None).

Returns:

A list of the column names of the table

tabular_data_by_name(table_name, j_to_kwh=True, report_name=None)[source]

Get all the data within a table of a Summary Report using the table name.

Parameters:

  • table_name – Text string for the name of a table within a summary report. (eg. ‘General’).

  • j_to_kwh – Boolean to note if any data in MJ or GJ should be converted to kWh upon import of the table. This will also mean that any area-normalized values will also be converted to kWh/m2.

  • report_name – An optional text string to indicate the report name from which the table should be pulled. This is useful in cases where tables have the same name in different reports. If None, data from all available tables will be returned. (Default: None).

Returns:

An ordered dictionary representing a matrix (list of lists), where the keys of the dictionary represent the row names and each value is a row of the table. The output should mirror how the table appears in the HTML output.

values_by_output_name(output_name)[source]

Get a list of values for a specified output.

This list will be flat and will not be organized into different run periods or different zones.

Parameters:

output_name – The name of an EnergyPlus output to be retrieved from the SQLite result file. This can also be an array of output names for which all data collections should be retrieved.

Returns:

An array of values for the requested output type. This will be an empty list if no output of the requested name was found in the file.

property available_outputs

Get a list of strings for available timeseries outputs that can be requested.

Any of these outputs when input to data_collections_by_output_name will yield a result with data collections.

property available_outputs_info

Get a list of dictionaries with outputs within the SQL and their metadata.

Each dictionary is formatted with the keys below.

{
"output_name": "Zone Ideal Loads Supply Air Total Cooling Energy",
"object_type": "Zone",
"units": "kWh",
"data_type ": Energy  # this is a ladybug DataType object
}
property component_sizes

Get a list of ComponentSize objects for all HVAC components in the results.

Each ComponentSize object contains several properties regarding the outcome of the sizing calculation.

property component_types

Get a list of text for all component types contained in the results.

property file_path

Get the path to the .sql file.

property location

Get a Ladybug Location object derived from the SQL data.

This will be None if there was no AllSummary report in the SQL file.

property reporting_frequency

Get text for the output reporting frequency. Will be one of the following.

  • Annual

  • Monthly

  • Daily

  • Hourly

  • An integer for the number of steps per hour

property run_period_indices

Get an array integers used to identify the run periods in the time table.

These will align with the run_periods property.

property run_period_names

Get an array of text for the names of the run periods.

These will align with the run_periods property. This will be None if there was no AllSummary report in the SQL file.

property run_periods

Get an array of Ladybug AnalysisPeriod objects for the simulation run periods.

This will be None if there was no AllSummary report in the SQL file.

property zone_cooling_sizes

Get a list of ZoneSize objects for all conditioned zones in the model.

Each ZoneSize object contains several properties regarding the outcome of the cooling sizing calculation.

property zone_heating_sizes

Get a list of ZoneSize objects for all conditioned zones in the model.

Each ZoneSize object contains several properties regarding the outcome of the heating sizing calculation.

class ladybug.sql.ZoneSize(sql_table_row)[source]

Bases: object

Object for holding the sizing results of an individual zone.

Parameters:

sql_table_row – A list that represents a row of the SQLite ZoneSizes table. This row contains all of the sizing information for a single conditioned zone (either heating or cooling).

Properties:

  • zone_name

  • load_type

  • calculated_design_load

  • final_design_load

  • calculated_design_flow

  • final_design_flow

  • design_day_name

  • peak_date_time

  • peak_temperature

  • peak_humidity_ratio

  • peak_outdoor_air_flow

ToString()[source]

Overwrite .NET ToString.

classmethod from_dict(data)[source]

Create a ZoneSize from a dictionary.

Parameters:

data – ZoneSize dictionary following the format below.

{
"type": "ZoneSize",
"zone_name": str,
"load_type": str,
"calculated_design_load": float,
"final_design_load": float,
"calculated_design_flow": float,
"final_design_flow": float,
"design_day_name": str,
"peak_date_time": str,
"peak_temperature": float,
"peak_humidity_ratio": float,
"peak_outdoor_air_flow": float
}
to_dict()[source]

Get ZoneSize as a dictionary.

property calculated_design_flow

Get the peak flow of the Zone computed by the EnergyPlus sizing calculation.

Values are always in m3/s.

property calculated_design_load

Get the peak load of the Zone computed by the EnergyPlus sizing calculation.

Values are always in Watts.

property design_day_name

Get the name of the design day on which the peak load occurred.

property final_design_flow

Get the peak flor of the Zone that is ultimately used to size the equipment.

Values are always in m3/s. This accounts for the heating_factor and cooling_factor of the specified in the SizingParameter of the SimulationParameter object.

property final_design_load

Get the peak load of the Zone that is ultimately used to size the equipment.

Values are always in Watts. This accounts for the heating_factor and cooling_factor of the specified in the SizingParameter of the SimulationParameter object.

property load_type

Get a text string that is either “Cooling” or “Heating”.

property peak_date_time

Get a DateTime for the time at which the peak occurred.

property peak_humidity_ratio

Get the outdoor humidity ratio at the time of the peak load (fractional).

property peak_outdoor_air_flow

Get the outdoor air flow into the zone at the time of the peak load (m3/s).

property peak_temperature

Get the outdoor air temperature at the time of the peak load (C).

property zone_name

Get the name of the zone to which this sizing information corresponds.