Functional API

class func.EnergyPlusVersion

Bases: object

This is the EnergyPlus version. Could also call into the DLL but it’s the same effect.

class func.Functional(api: <ctypes.LibraryLoader object at 0x7f7529afe110>, running_as_python_plugin: bool = False)

Bases: object

This API class enables accessing structures and functionality inside EnergyPlus from an outside client. This functional API will be extended over time, but initial targeted functionality includes fluid and refrigerant property methods, and surface and geometry classes and methods.

The Functional API class itself is really just an organizational class that provides access to nested functional classes through member functions. The functional API class is instantiated by the higher level EnergyPlusAPI class, and clients should never attempt to create an instance manually. Instead, create an EnergyPlusAPI instance, and use the functional member variable to access a Functional class instance. For Python Plugin workflows, the EnergyPlusPlugin base class also provides an instance of the Functional base class through the self.api.functional member variable. Clients should use that directly when needing to make functional calls into the library.

callback_error(state, f: function) → None

This function allows a client to register a function to be called back by EnergyPlus when an error message is added to the error file. The user can then detect specific error messages or whatever.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• f – A python function which takes an integer severity and a string (bytes) argument and returns nothing

Returns:

Nothing

static clear_callbacks() → None

This function is only used if you are running this script continually making many calls into the E+ library in one thread, each with many new and different error handler callbacks, and you need to clean up.

Note this will affect all current instances in this thread, so use carefully!

Returns:

Nothing

static ep_version() → EnergyPlusVersion

glycol(state: c_void_p, glycol_name: str) → Glycol

Returns a Glycol instance, which allows calculation of glycol properties.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• glycol_name – Name of the Glycol, for now only water is allowed

Returns:

An instantiated Glycol structure

initialize(state: c_void_p) → None

psychrometrics(state: c_void_p) → Psychrometrics

Returns a Psychrometric instance, which allows calculation of psychrometric properties.

Parameters:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

Returns:

An instantiated Psychrometric structure

refrigerant(state: c_void_p, refrigerant_name: str) → Refrigerant

Returns a Refrigerant instance, which allows calculation of refrigerant properties.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• refrigerant_name – Name of the Refrigerant, for now only steam is allowed

Returns:

An instantiated Refrigerant structure

class func.Glycol(state: ~ctypes.c_void_p, api: <ctypes.LibraryLoader object at 0x7f7529afe110>, glycol_name: bytes)

Bases: object

This class provides access to the glycol property calculations inside EnergyPlus. For now, the only glycol name allowed is plain water. This is because other fluids are only initialized when they are declared in the input file. When calling through the API, there is no input file, so no other fluids are declared. This is ripe for a refactor to enable additional fluids, but water will suffice for now.

conductivity(state: c_void_p, temperature: float) → float

Returns the conductivity of the fluid at the specified temperature.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state()

• temperature – Fluid temperature, in degrees Celsius

Returns:

The conductivity of the fluid, in W/m-K

delete(state: c_void_p) → None

Frees the memory of the associated Glycol instance inside the EnergyPlus (C++) state.

Parameters:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

Returns:

Nothing

density(state: c_void_p, temperature: float) → float

Returns the density of the fluid at the specified temperature.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state()

• temperature – Fluid temperature, in degrees Celsius

Returns:

The density of the fluid, in kg/m3

specific_heat(state: c_void_p, temperature: float) → float

Returns the specific heat of the fluid at the specified temperature.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state()

• temperature – Fluid temperature, in degrees Celsius

Returns:

The specific heat of the fluid, in J/kg-K

viscosity(state: c_void_p, temperature: float) → float

Returns the dynamic viscosity of the fluid at the specified temperature.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state()

• temperature – Fluid temperature, in degrees Celsius

Returns:

The dynamic viscosity of the fluid, in Pa-s (or kg/m-s)

class func.Psychrometrics(api: <ctypes.LibraryLoader object at 0x7f7529afe110>)

Bases: object

This class provides access to the psychrometric functions within EnergyPlus. Some property calculations are available as functions of different independent variable combinations, leading to suffixed function names, such as vapor_density_b and relative_humidity_c.

density(state: c_void_p, barometric_pressure: float, dry_bulb_temp: float, humidity_ratio: float) → float

Returns the psychrometric density at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• barometric_pressure – Barometric pressure, in Pa

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

Returns:

dew_point(state: c_void_p, humidity_ratio: float, barometric_pressure: float) → float

Returns the psychrometric dew point temperature at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

• barometric_pressure – Barometric pressure, in Pa

Returns:

dew_point_b(state: c_void_p, dry_bulb_temp: float, wet_bulb_temp: float, barometric_pressure: float) → float

Returns the psychrometric dew point temperature at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• wet_bulb_temp – Psychrometric wet bulb temperature, in C

• barometric_pressure – Barometric pressure, in Pa

Returns:

dry_bulb(state: c_void_p, enthalpy: float, humidity_ratio: float) → float

Returns the psychrometric dry bulb temperature at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• enthalpy – Psychrometric enthalpy, in J/kg

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

Returns:

enthalpy(state: c_void_p, dry_bulb_temp: float, humidity_ratio: float) → float

Returns the psychrometric enthalpy at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

Returns:

enthalpy_b(state: c_void_p, dry_bulb_temp: float, relative_humidity_fraction: float, barometric_pressure: float) → float

Returns the psychrometric enthalpy at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• relative_humidity_fraction – Psychrometric relative humidity, as a fraction from 0.0 to 1.0.

• barometric_pressure – Barometric pressure, in Pa

Returns:

humidity_ratio(state: c_void_p, dry_bulb_temp: float, enthalpy: float) → float

Returns the psychrometric humidity ratio at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• enthalpy – Psychrometric enthalpy, in J/kg

Returns:

humidity_ratio_b(state: c_void_p, dew_point_temp: float, barometric_pressure: float) → float

Returns the psychrometric humidity ratio at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dew_point_temp – Psychrometric dew point temperature, in Celsius

• barometric_pressure – Barometric pressure, in Pa

Returns:

humidity_ratio_c(state: c_void_p, dry_bulb_temp: float, relative_humidity_fraction: float, barometric_pressure: float) → float

Returns the psychrometric humidity ratio at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• relative_humidity_fraction – Psychrometric relative humidity, as a fraction from 0.0 to 1.0.

• barometric_pressure – Barometric pressure, in Pa

Returns:

humidity_ratio_d(state: c_void_p, dry_bulb_temp: float, wet_bulb_temp: float, barometric_pressure: float) → float

Returns the psychrometric humidity ratio at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• wet_bulb_temp – Psychrometric wet bulb temperature, in C

• barometric_pressure – Barometric pressure, in Pa

Returns:

latent_energy_of_air(state: c_void_p, dry_bulb_temp: float) → float

Returns the psychrometric latent energy of air at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

Returns:

latent_energy_of_moisture_in_air(state: c_void_p, dry_bulb_temp: float) → float

Returns the psychrometric latent energy of the moisture in air at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

Returns:

relative_humidity(state: c_void_p, dry_bulb_temp: float, vapor_density: float) → float

Returns the psychrometric relative humidity at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• vapor_density – Psychrometric vapor density, in kg/m3

Returns:

relative_humidity_b(state: c_void_p, dry_bulb_temp: float, humidity_ratio: float, barometric_pressure: float) → float

Returns the psychrometric relative humidity at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

• barometric_pressure – Barometric pressure, in Pa

Returns:

saturation_pressure(state: c_void_p, dry_bulb_temp: float) → float

Returns the psychrometric saturation pressure at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

Returns:

saturation_temperature(state: c_void_p, enthalpy: float, barometric_pressure: float) → float

Returns the psychrometric saturation temperature at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• enthalpy – Psychrometric enthalpy, in J/kg

• barometric_pressure – Barometric pressure, in Pa

Returns:

specific_heat(state: c_void_p, humidity_ratio: float) → float

Returns the psychrometric specific heat at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

Returns:

specific_volume(state: c_void_p, dry_bulb_temp: float, humidity_ratio: float, barometric_pressure: float) → float

Returns the psychrometric specific volume at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

• barometric_pressure – Barometric pressure, in Pa

Returns:

vapor_density(state: c_void_p, dry_bulb_temp: float, humidity_ratio: float, barometric_pressure: float) → float

Returns the psychrometric vapor density at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

• barometric_pressure – Barometric pressure, in Pa

Returns:

vapor_density_b(state: c_void_p, dry_bulb_temp: float, relative_humidity_fraction: float) → float

Returns the psychrometric vapor density at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• relative_humidity_fraction – Psychrometric relative humidity, as a fraction from 0.0 to 1.0.

Returns:

wet_bulb(state: c_void_p, dry_bulb_temp: float, humidity_ratio: float, barometric_pressure: float) → float

Returns the psychrometric wet bulb temperature at the specified conditions.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• dry_bulb_temp – Psychrometric dry bulb temperature, in C

• humidity_ratio – Humidity ratio, in kgWater/kgDryAir

• barometric_pressure – Barometric pressure, in Pa

Returns:

class func.Refrigerant(state: ~ctypes.c_void_p, api: <ctypes.LibraryLoader object at 0x7f7529afe110>, refrigerant_name: bytes)

Bases: object

This class provides access to the refrigerant property calculations inside EnergyPlus. For now, the only refrigerant name allowed is steam. This is because other refrigerants are only initialized when they are declared in the input file. When calling through the API, there is no input file, so no other refrigerants are declared. This should be improved through later enhancements, but steam will provide a suitable use case for now.

delete(state: c_void_p)

Frees the memory of the associated Refrigerant instance inside the EnergyPlus (C++) state.

Parameters:

state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

Returns:

Nothing

saturated_density(state: c_void_p, temperature: float, quality: float) → float

Returns the refrigerant density at the specified temperature and quality.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• temperature – Refrigerant temperature, in Celsius

• quality – Refrigerant quality, in fractional form from 0.0 to 1.0

Returns:

Refrigerant saturated density, in kg/m3

saturated_enthalpy(state: c_void_p, temperature: float, quality: float) → float

Returns the refrigerant saturated enthalpy at the specified temperature and quality.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• temperature – Refrigerant temperature, in Celsius

• quality – Refrigerant quality, in fractional form from 0.0 to 1.0

Returns:

Refrigerant saturated enthalpy, in J/kg

saturated_specific_heat(state: c_void_p, temperature: float, quality: float) → float

Returns the refrigerant specific heat at the specified temperature and quality.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• temperature – Refrigerant temperature, in Celsius

• quality – Refrigerant quality, in fractional form from 0.0 to 1.0

Returns:

Refrigerant saturated specific heat, in J/kg-K

saturation_pressure(state: c_void_p, temperature: float) → float

Returns the saturation pressure of the refrigerant at the specified temperature.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• temperature – Refrigerant temperature, in Celsius.

Returns:

Refrigerant saturation pressure, in Pa

saturation_temperature(state: c_void_p, pressure: float) → float

Returns the saturation temperature of the refrigerant at the specified pressure.

Parameters:

• state – An active EnergyPlus “state” that is returned from a call to api.state_manager.new_state().

• pressure – Refrigerant pressure, in Pa

Returns:

Refrigerant saturation temperature, in Celsius