EnergyPlus C API  0.1
This is the EnergyPlus C API, which allows linking to EnergyPlus and reading and manipluating data during a simulation.
/eplus/repos/7eplus/src/EnergyPlus/api/func.h File Reference

This "functional" API category provides access to things which do not require a simulation to be running. More...

Go to the source code of this file.

Typedefs

typedef void * Glycol
 This typedef is a convenient pointer to an internal glycol property class inside EnergyPlus. More...
 
typedef void * Refrigerant
 This typedef is a convenient pointer to an internal refrigerant property class inside EnergyPlus. More...
 

Functions

void initializeFunctionalAPI ()
 An initialization routine that sets up all functional API structures. More...
 
const char * apiVersionFromEPlus ()
 Returns the version of this API, in Major.Minor form. More...
 
void registerErrorCallback (void(*f)(const char *errorMessage))
 Allows a user to register an error callback function. More...
 
Glycol glycolNew (const char *glycolName)
 Returns a new reference to a Glycol class. More...
 
void glycolDelete (Glycol glycol)
 Deletes an instance of a Glycol class. More...
 
Real64 glycolSpecificHeat (Glycol glycol, Real64 temperature)
 Returns the fluid specific heat for the given Glycol instance at the specified temperature. More...
 
Real64 glycolDensity (Glycol glycol, Real64 temperature)
 Returns the fluid density for the given Glycol instance at the specified temperature. More...
 
Real64 glycolConductivity (Glycol glycol, Real64 temperature)
 Returns the fluid thermal conductivity for the given Glycol instance at the specified temperature. More...
 
Real64 glycolViscosity (Glycol glycol, Real64 temperature)
 Returns the fluid dynamic viscosity for the given Glycol instance at the specified temperature. More...
 
Refrigerant refrigerantNew (const char *refrigerantName)
 Returns a new reference to a Refrigerant class. More...
 
void refrigerantDelete (Refrigerant refrigerant)
 Deletes an instance of a Refrigerant class. More...
 
Real64 refrigerantSaturationPressure (Refrigerant refrigerant, Real64 temperature)
 Returns the refrigerant saturation pressure for the given Refrigerant instance at the specified temperature. More...
 
Real64 refrigerantSaturationTemperature (Refrigerant refrigerant, Real64 pressure)
 Returns the refrigerant saturation temperature for the given Refrigerant instance at the specified pressure. More...
 
Real64 refrigerantSaturatedEnthalpy (Refrigerant refrigerant, Real64 temperature, Real64 quality)
 Returns the refrigerant saturated enthalpy for the given Refrigerant instance at the specified temperature and quality. More...
 
Real64 refrigerantSaturatedDensity (Refrigerant refrigerant, Real64 temperature, Real64 quality)
 Returns the refrigerant saturated density for the given Refrigerant instance at the specified temperature and quality. More...
 
Real64 refrigerantSaturatedSpecificHeat (Refrigerant refrigerant, Real64 temperature, Real64 quality)
 Returns the refrigerant saturated specific heat for the given Refrigerant instance at the specified temperature and quality. More...
 
Real64 psyRhoFnPbTdbW (Real64 pb, Real64 tdb, Real64 dw)
 Returns the psychrometric density at given conditions. More...
 
Real64 psyHfgAirFnWTdb (Real64 T)
 Returns the psychrometric latent energy of air at given conditions. More...
 
Real64 psyHgAirFnWTdb (Real64 T)
 Returns the psychrometric latent energy of the moisture as a gas in the air at given conditions. More...
 
Real64 psyHFnTdbW (Real64 TDB, Real64 W)
 Returns the psychrometric enthalpy at given conditions. More...
 
Real64 psyCpAirFnW (Real64 W)
 Returns the psychrometric specific heat at given conditions. More...
 
Real64 psyTdbFnHW (Real64 H, Real64 W)
 Returns the psychrometric dry bulb temperature at given conditions. More...
 
Real64 psyRhovFnTdbWPb (Real64 Tdb, Real64 W, Real64 PB)
 Returns the psychrometric vapor density at given conditions. More...
 
Real64 psyTwbFnTdbWPb (Real64 Tdb, Real64 W, Real64 PB)
 Returns the psychrometric wet bulb temperature at given conditions. More...
 
Real64 psyVFnTdbWPb (Real64 TDB, Real64 W, Real64 PB)
 Returns the psychrometric specific volume at given conditions. More...
 
Real64 psyWFnTdbH (Real64 TDB, Real64 H)
 Returns the psychrometric humidity ratio at given conditions. More...
 
Real64 psyPsatFnTemp (Real64 T)
 Returns the psychrometric saturation pressure at given conditions. More...
 
Real64 psyTsatFnHPb (Real64 H, Real64 PB)
 Returns the psychrometric saturation temperature at given conditions. More...
 
Real64 psyRhovFnTdbRh (Real64 Tdb, Real64 RH)
 Returns the psychrometric vapor density at given conditions. More...
 
Real64 psyRhFnTdbRhov (Real64 Tdb, Real64 Rhovapor)
 Returns the psychrometric relative humidity at given conditions. More...
 
Real64 psyRhFnTdbWPb (Real64 TDB, Real64 W, Real64 PB)
 Returns the psychrometric relative humidity at given conditions. More...
 
Real64 psyWFnTdpPb (Real64 TDP, Real64 PB)
 Returns the psychrometric humidity ratio at given conditions. More...
 
Real64 psyWFnTdbRhPb (Real64 TDB, Real64 RH, Real64 PB)
 Returns the psychrometric humidity ratio at given conditions. More...
 
Real64 psyWFnTdbTwbPb (Real64 TDB, Real64 TWB, Real64 PB)
 Returns the psychrometric humidity ratio at given conditions. More...
 
Real64 psyHFnTdbRhPb (Real64 TDB, Real64 RH, Real64 PB)
 Returns the psychrometric enthalpy at given conditions. More...
 
Real64 psyTdpFnWPb (Real64 W, Real64 PB)
 Returns the psychrometric dew point temperature at given conditions. More...
 
Real64 psyTdpFnTdbTwbPb (Real64 TDB, Real64 TWB, Real64 PB)
 Returns the psychrometric dew point temperature at given conditions. More...
 

Detailed Description

This "functional" API category provides access to things which do not require a simulation to be running.

Currently this includes accessing API version information, and looking up glycol, refrigerant, and psychrometric properties. Each category has some limitations as this is the first version of the API, but more functionality will be introduced throughout development cycles.

Remarks
Make sure to call initializeFunctionalAPI prior to calling any functional API methods to ensure the internal structures are in place in the code.
Glycol routines currently only operate on pure water; a future version will enable further property lookups.
Refrigerant routines currently only operate on steam; a future version will enable further property lookups.

Typedef Documentation

◆ Glycol

typedef void* Glycol

This typedef is a convenient pointer to an internal glycol property class inside EnergyPlus.

In a default EnergyPlus simulation, pure water properties are available directly. To access properties of ethylene glycol or propylene glycol, user-input is required. For the current time, the only glycol available through the API is pure water. Accessing the glycol API is initiated using the glycolNew function.

See also
glycolNew

◆ Refrigerant

typedef void* Refrigerant

This typedef is a convenient pointer to an internal refrigerant property class inside EnergyPlus.

In a default EnergyPlus simulation, refrigerant properties for steam are available directly. To access properties of other refrigerants, user-input is required. For the current time, the only refrigerant available through the API is pure steam. Accessing the refrigerant API is initiated using the refrigerantNew function.

See also
refrigerantNew

Function Documentation

◆ apiVersionFromEPlus()

const char* apiVersionFromEPlus ( )

Returns the version of this API, in Major.Minor form.

Over time, the API will evolve. In most cases, there won't be breaking changes, just additional functionality. When improvements are made, but they don't break functionality, the minor number will be incremented. If a breaking change ever occurs, the major number will be incremented. This function can be used by users as a way to target a specific major version of the API and avoid problems if the API ever changes.

◆ glycolConductivity()

Real64 glycolConductivity ( Glycol  glycol,
Real64  temperature 
)

Returns the fluid thermal conductivity for the given Glycol instance at the specified temperature.

Parameters
[in]glycolAn instance of a Glycol class, which can be created by calling glycolNew.
[in]temperatureThe fluid temperature for property evaluation, in degrees Celsius.
Returns
Fluid thermal conductivity, in W/mK
See also
Glycol
glycolNew

◆ glycolDelete()

void glycolDelete ( Glycol  glycol)

Deletes an instance of a Glycol class.

When an instance of a Glycol class is created using glycolNew, it should be cleaned up when totally done with it.

Parameters
[in]glycolAn instance of a Glycol class to be deleted. The Glycol class is initially created by calling glycolNew.
See also
Glycol
glycolNew

◆ glycolDensity()

Real64 glycolDensity ( Glycol  glycol,
Real64  temperature 
)

Returns the fluid density for the given Glycol instance at the specified temperature.

Parameters
[in]glycolAn instance of a Glycol class, which can be created by calling glycolNew.
[in]temperatureThe fluid temperature for property evaluation, in degrees Celsius.
Returns
Fluid density, in kg/m3
See also
Glycol
glycolNew

◆ glycolNew()

Glycol glycolNew ( const char *  glycolName)

Returns a new reference to a Glycol class.

The glycol class allows access to fluid properties. Eventually ethylene and propylene glycol properties will be made available but for now the only fluid is pure water.

Parameters
[in]glycolNameThe name of the glycol. Currently the only valid option is "water". In future versions of the API, the function will accept other fluid types and glycol mixtures.
Returns
This functions allocates a new glycol class and returns a Glycol, which is a pointer to that new instance.
Remarks
In API applications, when the calling script is done with the glycol instance, call glycolDelete to clean up the instance.
See also
Glycol
glycolDelete

◆ glycolSpecificHeat()

Real64 glycolSpecificHeat ( Glycol  glycol,
Real64  temperature 
)

Returns the fluid specific heat for the given Glycol instance at the specified temperature.

Parameters
[in]glycolAn instance of a Glycol class, which can be created by calling glycolNew.
[in]temperatureThe fluid temperature for property evaluation, in degrees Celsius.
Returns
Fluid specific heat, in J/kgK
See also
Glycol
glycolNew

◆ glycolViscosity()

Real64 glycolViscosity ( Glycol  glycol,
Real64  temperature 
)

Returns the fluid dynamic viscosity for the given Glycol instance at the specified temperature.

Parameters
[in]glycolAn instance of a Glycol class, which can be created by calling glycolNew.
[in]temperatureThe fluid temperature for property evaluation, in degrees Celsius.
Returns
Fluid dynamic viscosity, in Pa-s (or kg/m-s)
See also
Glycol
glycolNew

◆ initializeFunctionalAPI()

void initializeFunctionalAPI ( )

An initialization routine that sets up all functional API structures.

The functional API exposes classes and methods that can be used for outside calculations. Some of these calculations rely on internal structures being allocated and set up. Whenever any script is going to use a method from this functional API, this method must be called.

Remarks
When using the functional API from a Python Plugin workflow, this function should not be called.

◆ psyCpAirFnW()

Real64 psyCpAirFnW ( Real64  W)

Returns the psychrometric specific heat at given conditions.

Parameters
[in]WHumidity ratio, in kgWater/kgDryAir
Returns
Psychrometric specific heat, in J/kg-K

◆ psyHfgAirFnWTdb()

Real64 psyHfgAirFnWTdb ( Real64  T)

Returns the psychrometric latent energy of air at given conditions.

Parameters
[in]TDry bulb temperature, in Celsius
Returns
Psychrometric latent energy of air, in J/kg

◆ psyHFnTdbRhPb()

Real64 psyHFnTdbRhPb ( Real64  TDB,
Real64  RH,
Real64  PB 
)

Returns the psychrometric enthalpy at given conditions.

Parameters
[in]TDBDry bulb temperature, in Celsius
[in]RHRelative humidity ratio, as a fraction from 0.0 to 1.0
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric enthalpy, in J/kg

◆ psyHFnTdbW()

Real64 psyHFnTdbW ( Real64  TDB,
Real64  W 
)

Returns the psychrometric enthalpy at given conditions.

Parameters
[in]TDBDry bulb temperature, in Celsius
[in]WHumidity ratio, in kgWater/kgDryAir
Returns
Psychrometric enthalpy, in J/kg

◆ psyHgAirFnWTdb()

Real64 psyHgAirFnWTdb ( Real64  T)

Returns the psychrometric latent energy of the moisture as a gas in the air at given conditions.

Parameters
[in]TDry bulb temperature, in Celsius
Returns
Psychrometric latent energy of the moisture as a gas in the air, in J/kg

◆ psyPsatFnTemp()

Real64 psyPsatFnTemp ( Real64  T)

Returns the psychrometric saturation pressure at given conditions.

Parameters
[in]TDry bulb temperature, in Celsius
Returns
Psychrometric saturation pressure, in Pascals

◆ psyRhFnTdbRhov()

Real64 psyRhFnTdbRhov ( Real64  Tdb,
Real64  Rhovapor 
)

Returns the psychrometric relative humidity at given conditions.

Parameters
[in]TdbDry bulb temperature, in Celsius
[in]RhovaporVapor density, in kg/m3
Returns
Psychrometric relative humidity, as a fraction from 0.0 to 1.0

◆ psyRhFnTdbWPb()

Real64 psyRhFnTdbWPb ( Real64  TDB,
Real64  W,
Real64  PB 
)

Returns the psychrometric relative humidity at given conditions.

Parameters
[in]TDBDry bulb temperature, in Celsius
[in]WHumidity ratio, in kgWater/kgDryAir
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric relative humidity, as a fraction from 0.0 to 1.0

◆ psyRhoFnPbTdbW()

Real64 psyRhoFnPbTdbW ( Real64  pb,
Real64  tdb,
Real64  dw 
)

Returns the psychrometric density at given conditions.

Parameters
[in]pbBarometric pressure, in Pa
[in]tdbDry bulb temperature, in Celsius
[in]dwHumidity ratio, in kgWater/kgDryAir
Returns
Psychrometric density, in kg/m3

◆ psyRhovFnTdbRh()

Real64 psyRhovFnTdbRh ( Real64  Tdb,
Real64  RH 
)

Returns the psychrometric vapor density at given conditions.

Parameters
[in]TdbDry bulb temperature, in Celsius
[in]RHRelative humidity, as a fraction from 0.0 to 1.0
Returns
Psychrometric vapor density, in kg/m3

◆ psyRhovFnTdbWPb()

Real64 psyRhovFnTdbWPb ( Real64  Tdb,
Real64  W,
Real64  PB 
)

Returns the psychrometric vapor density at given conditions.

Parameters
[in]TdbDry bulb temperature, in Celsius
[in]WHumidity ratio, in kgWater/kgDryAir
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric vapor density, in kg/m3

◆ psyTdbFnHW()

Real64 psyTdbFnHW ( Real64  H,
Real64  W 
)

Returns the psychrometric dry bulb temperature at given conditions.

Parameters
[in]HEnthalpy, in J/kg
[in]WHumidity ratio, in kgWater/kgDryAir
Returns
Psychrometric dry bulb temperature, in Celsius

◆ psyTdpFnTdbTwbPb()

Real64 psyTdpFnTdbTwbPb ( Real64  TDB,
Real64  TWB,
Real64  PB 
)

Returns the psychrometric dew point temperature at given conditions.

Parameters
[in]TDBDry bulb temperature, in Celsius
[in]TWBWet bulb temperature, in Celsius
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric dew point temperature, in Celsius

◆ psyTdpFnWPb()

Real64 psyTdpFnWPb ( Real64  W,
Real64  PB 
)

Returns the psychrometric dew point temperature at given conditions.

Parameters
[in]WHumidity ratio, in kgWater/kgDryAir
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric dew point temperature, in Celsius

◆ psyTsatFnHPb()

Real64 psyTsatFnHPb ( Real64  H,
Real64  PB 
)

Returns the psychrometric saturation temperature at given conditions.

Parameters
[in]HEnthalpy, in J/kg
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric saturation temperature, in Celsius

◆ psyTwbFnTdbWPb()

Real64 psyTwbFnTdbWPb ( Real64  Tdb,
Real64  W,
Real64  PB 
)

Returns the psychrometric wet bulb temperature at given conditions.

Parameters
[in]TdbDry bulb temperature, in Celsius
[in]WHumidity ratio, in kgWater/kgDryAir
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric wet bulb temperature, in Celsius

◆ psyVFnTdbWPb()

Real64 psyVFnTdbWPb ( Real64  TDB,
Real64  W,
Real64  PB 
)

Returns the psychrometric specific volume at given conditions.

Parameters
[in]TDBDry bulb temperature, in Celsius
[in]WHumidity ratio, in kgWater/kgDryAir
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric specific volume, in m3/kg

◆ psyWFnTdbH()

Real64 psyWFnTdbH ( Real64  TDB,
Real64  H 
)

Returns the psychrometric humidity ratio at given conditions.

Parameters
[in]TDBDry bulb temperature, in Celsius
[in]HEnthalpy, in J/kg
Returns
Psychrometric humidity ratio, in kgWater/kgDryAir

◆ psyWFnTdbRhPb()

Real64 psyWFnTdbRhPb ( Real64  TDB,
Real64  RH,
Real64  PB 
)

Returns the psychrometric humidity ratio at given conditions.

Parameters
[in]TDBDry bulb temperature, in Celsius
[in]RHRelative humidity ratio, as a fraction from 0.0 to 1.0
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric humidity ratio, in kgWater/kgDryAir

◆ psyWFnTdbTwbPb()

Real64 psyWFnTdbTwbPb ( Real64  TDB,
Real64  TWB,
Real64  PB 
)

Returns the psychrometric humidity ratio at given conditions.

Parameters
[in]TDBDry bulb temperature, in Celsius
[in]TWBWet bulb temperature, in Celsius
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric humidity ratio, in kgWater/kgDryAir

◆ psyWFnTdpPb()

Real64 psyWFnTdpPb ( Real64  TDP,
Real64  PB 
)

Returns the psychrometric humidity ratio at given conditions.

Parameters
[in]TDPDew point temperature, in Celsius
[in]PBBarometric pressure, in Pascals
Returns
Psychrometric humidity ratio, in kgWater/kgDryAir

◆ refrigerantDelete()

void refrigerantDelete ( Refrigerant  refrigerant)

Deletes an instance of a Refrigerant class.

When an instance of a Refrigerant class is created using refrigerantNew, it should be cleaned up when totally done with it.

Parameters
[in]refrigerantAn instance of a Refrigerant class to be deleted. The Refrigerant class is initially created by calling refrigerantNew.
See also
Refrigerant
refrigerantNew

◆ refrigerantNew()

Refrigerant refrigerantNew ( const char *  refrigerantName)

Returns a new reference to a Refrigerant class.

The refrigerant class allows access to refrigerant properties. Eventually more refrigerant properties will be made available but for now the only refrigerant is pure steam.

Parameters
[in]refrigerantNameThe name of the refrigerant. Currently the only valid option is "steam". In future versions of the API, the function will accept other refrigerant types.
Returns
This functions allocates a new refrigerant class and returns a Refrigerant, which is a pointer to that new instance.
Remarks
In API applications, when the calling script is done with the refrigerant instance, call refrigerantDelete to clean up the instance.
See also
Refrigerant
refrigerantDelete

◆ refrigerantSaturatedDensity()

Real64 refrigerantSaturatedDensity ( Refrigerant  refrigerant,
Real64  temperature,
Real64  quality 
)

Returns the refrigerant saturated density for the given Refrigerant instance at the specified temperature and quality.

Parameters
[in]refrigerantAn instance of a Refrigerant class, which can be created by calling refrigerantNew.
[in]temperatureThe refrigerant temperature for property evaluation, in C.
[in]qualityThe refrigerant quality for property evaluation, in fractional form from 0.0 to 1.0.
Returns
Refrigerant saturated density in kg/m3
See also
Refrigerant
refrigerantNew

◆ refrigerantSaturatedEnthalpy()

Real64 refrigerantSaturatedEnthalpy ( Refrigerant  refrigerant,
Real64  temperature,
Real64  quality 
)

Returns the refrigerant saturated enthalpy for the given Refrigerant instance at the specified temperature and quality.

Parameters
[in]refrigerantAn instance of a Refrigerant class, which can be created by calling refrigerantNew.
[in]temperatureThe refrigerant temperature for property evaluation, in C.
[in]qualityThe refrigerant quality for property evaluation, in fractional form from 0.0 to 1.0.
Returns
Refrigerant saturated enthalpy in J/kg
See also
Refrigerant
refrigerantNew

◆ refrigerantSaturatedSpecificHeat()

Real64 refrigerantSaturatedSpecificHeat ( Refrigerant  refrigerant,
Real64  temperature,
Real64  quality 
)

Returns the refrigerant saturated specific heat for the given Refrigerant instance at the specified temperature and quality.

Parameters
[in]refrigerantAn instance of a Refrigerant class, which can be created by calling refrigerantNew.
[in]temperatureThe refrigerant temperature for property evaluation, in C.
[in]qualityThe refrigerant quality for property evaluation, in fractional form from 0.0 to 1.0.
Returns
Refrigerant saturated enthalpy in J/kg-K
See also
Refrigerant
refrigerantNew

◆ refrigerantSaturationPressure()

Real64 refrigerantSaturationPressure ( Refrigerant  refrigerant,
Real64  temperature 
)

Returns the refrigerant saturation pressure for the given Refrigerant instance at the specified temperature.

Parameters
[in]refrigerantAn instance of a Refrigerant class, which can be created by calling refrigerantNew.
[in]temperatureThe refrigerant temperature for property evaluation, in degrees Celsius.
Returns
Refrigerant saturation pressure, in Pa
See also
Refrigerant
refrigerantNew

◆ refrigerantSaturationTemperature()

Real64 refrigerantSaturationTemperature ( Refrigerant  refrigerant,
Real64  pressure 
)

Returns the refrigerant saturation temperature for the given Refrigerant instance at the specified pressure.

Parameters
[in]refrigerantAn instance of a Refrigerant class, which can be created by calling refrigerantNew.
[in]pressureThe refrigerant pressure for property evaluation, in Pa.
Returns
Refrigerant saturation temperature, in C
See also
Refrigerant
refrigerantNew

◆ registerErrorCallback()

void registerErrorCallback ( void(*)(const char *errorMessage)  f)

Allows a user to register an error callback function.

If a user script registers a callback function here, then when EnergyPlus is sending an error message to the error file, it will also send it here. The user function will then have the ability to act on the error message if needed.

Remarks
A future version of this method will enable additional functionality including an argument indicating the error type, and allowing the return value from this callback to determine how EnergyPlus should behave.