PsychroLib

PsychroLib is a library of functions for calculating the psychrometric properties of moist and dry air, such as dew point temperature, wet bulb temperature, relative humidity, humidity ratio, and enthalpy.

Key features:

• Multi-language support: Available in Python, C, C#, Fortran, JavaScript, and Excel VBA.
• Unit Systems: Supports both metric (SI) and imperial (IP) systems.
• Standard Compliance: Functions are based on formulae from the 2017 ASHRAE Handbook — Fundamentals (Chapter 1, SI and IP editions).

Functions are generally categorized into two groups:

1. Functions that calculate properties (like dew point or relative humidity) given other properties plus dry bulb temperature and atmospheric pressure.
2. Functions that calculate other moist air properties (like enthalpy or density) using the humidity ratio as an input.

While PsychroLib maintains a common API across all languages, note the following implementation differences:

Python

• Installing numba enables array support and faster runtime performance.

R

• Constants (e.g., ZERO_FAHRENHEIT_AS_RANKINE) are not exported and are not directly accessible to users.
• Functions accept vectors instead of scalars.
• Bulk calculation functions (e.g., CalcPsychrometricsFromRelHum) return a list.

PsychroLib uses two types of relationships to calculate properties:

1. Primary Relationships: Direct calculations based on formulae from the ASHRAE Handbook (e.g., computing dew point temperature from the partial pressure of water vapor).
2. Secondary Relationships: Calculations that combine multiple primary relationships to reach a result (e.g., computing dew point temperature from relative humidity by first calculating the partial pressure of water vapor, then the dew point).

Important Pattern: To compute a property like enthalpy when you only know a humidity parameter (like dew point), you must often perform a two-step calculation: first compute the humidity ratio from the known parameter, then compute the target property from that humidity ratio.

1. Add the psychrolib.bas module via the Visual Basic Editor (VBE).
2. Set the unit system by uncommenting the appropriate constant in the module: Const PSYCHROLIB_UNITS = UnitSystem.SI (or UnitSystem.IP).
3. Use the function directly in worksheet cells. Note that relative humidity must be entered as a ratio (e.g., 0.8 for 80%).

Example formula: =GetTDewPointFromRelHum(A2, B2)

=GetTDewPointFromRelHum(A2,B2)

To create and upload a new release for the Python implementation, navigate to the src/python directory and execute the following sequence of commands to build a source distribution, upgrade twine, and upload the package to PyPI.

python3 setup.py sdist --formats=zip
python3 -m pip install --user --upgrade twine
python3 -m twine upload dist/*

Installation methods vary by language:

• Python: Install via PyPI. You can optionally install Numba to enable array support and improved runtime performance.
• C# (.NET): Use the NuGet package manager or clone the repository and bundle it according to your requirements.
• C, Fortran, and JavaScript: Clone the repository and bundle it according to your requirements.
• R: Install from the Comprehensive R Archive Network (CRAN).
• VBA/Excel: Download ready-made spreadsheets from the GitHub releases tab.

PsychroLib provides test suites for multiple language implementations. Use the following commands based on the language you are testing:

Python, C, and Fortran

Run via pytest from the root directory:

python -m pytest -v -s

JavaScript

Run via npm from the JavaScript test directory:

cd tests/js && npm test

Microsoft .NET (C#, Visual Basic, and F#)

Run via dotnet test from the C# source directory:

cd src/c_sharp && dotnet test

VBA/Excel

1. Navigate to tests/vba.
2. Open test_psychrolib_ip.xlsm or test_psychrolib_si.xlsm.
3. Enable macros.
4. Open the Visual Basic Editor (Alt+F11).
5. Open the 'Immediate Window' (Alt+F11).
6. Select RunAllTests from the dropdown menu next to '(General)' and click 'Run'.

R

Navigate to src/r and run:

R CMD build .
R CMD check psychrolib*tar.gz

Before running tests, ensure you have the following prerequisites installed:

• A C and Fortran compiler
• Python 3.6+
• Node.js 10.x+
• Microsoft Excel
• Microsoft .NET Core SDK
• R 3.0.0+

Install Dependencies

Navigate to the psychrolib root folder and install the required Python and JavaScript dependencies:

pip install numpy m2r cffi pytest
cd tests/js && npm install
cd ../..

To install the R package locally, navigate to src/r, open an R session, and source the deployment script:

source("tools/deploy.R")

This script copies the LICENSE and README.md from the main repository into src/r, generates package documentation, and installs the package.

Advanced Deployment Options

If you are developing the package, you can use Rscript tools/deploy.R [OPTION] from your terminal. Ensure Rscript is in your system PATH.

Available options:

• --prepare or -p: Copy LICENSE.txt, README.md, and update links in README.md.
• --doc or -d: Create or update package documentation.
• --install or -i: Create/update package documentation and install the package.
• --help or -h: Show help messages.

1. Install the NuGet package: Install-Package PsychroLib.
2. Unlike other implementations, the unit system is specified via the Psychrometrics class constructor. This allows you to maintain independent instances for different unit systems (e.g., one for UnitSystem.IP and one for UnitSystem.SI) within the same application.

// Create instance of Psychrometrics class and specify the unit system.
var psyIP = new Psychrometrics(UnitSystem.IP);
var psySI = new Psychrometrics(UnitSystem.SI);
// Calculate the dew point temperature for a dry bulb temperature of 25 C and a relative humidity of 80%
var tDewPoint = psySI.GetTDewPointFromRelHum(25.0, 0.80);
Console.WriteLine($"TDewPoint: {tDewPoint} degree C");

PsychroLib supports vectorization for performance when the numba library is installed.

If numba is present, core functions (those starting with Get or dLnPws_) are automatically decorated with @vectorize and @njit. This allows you to pass NumPy arrays to these functions instead of single scalar values, enabling high-performance batch calculations.

If numba is not installed, the library functions as standard scalar functions.

PsychroLib provides utility functions to calculate a full suite of psychrometric properties from a single set of known parameters. These return a tuple of values.

Common Return Tuple Order:

1. Humidity ratio
2. Wet-bulb temperature (or Dew-point, depending on input)
3. Relative humidity
4. Partial pressure of water vapor
5. Moist air enthalpy
6. Specific volume of moist air
7. Degree of saturation

Available Utility Functions:

• CalcPsychrometricsFromTWetBulb(TDryBulb, TWetBulb, Pressure)
• CalcPsychrometricsFromTDewPoint(TDryBulb, TDewPoint, Pressure)
• CalcPsychrometricsFromRelHum(TDryBulb, RelHum, Pressure)

# Example: Calculate all properties from Dry Bulb, Wet Bulb, and Pressure
hum_ratio, t_dew, rel_hum, vap_pres, enthalpy, vol, deg_sat = CalcPsychrometricsFromTWetBulb(75.0, 60.0, 14.696)