-
Notifications
You must be signed in to change notification settings - Fork 65
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
JOSS review: update paper and readme + add Zenodo metadata (#11)
- Loading branch information
Showing
11 changed files
with
250 additions
and
97 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| { | ||
| "title": "PsychroLib: a library of psychrometric functions to calculate thermodynamic properties of air", | ||
| "description": "PsychroLib is a software library for estimating dry, moist, saturated properties of air, and standard atmosphere written in Python, C, Fortran, JavaScript, and Microsoft Excel Visual Basic for Applications (VBA). It is aimed at scientist and engineers developing software and working with psychrometric calculations.", | ||
| "keywords": ["python", "vba", "excel", "fortran", "c", "javascript", "engineering", "hvac", "ashrae", "temperature", "pressure", "meteorology"], | ||
| "upload_type": "software", | ||
| "access_right": "open", | ||
| "license": "MIT", | ||
| "creators": [ | ||
| { | ||
| "orcid": "0000-0002-7071-7547", | ||
| "name": "D. Meyer" | ||
| }, | ||
| { | ||
| "orcid": "0000-0002-0749-6841", | ||
| "name": "D. Thevenard" | ||
| } | ||
| ] | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| # How to contribute | ||
|
|
||
| Thank you for considering contributing to PsychroLib. In general, you can contribute by reporting an issue or by directly contributing to the source code. For the latter, fork our repository, clone the fork, make your changes, and create a pull request (PR) with a **clear description** of your changes -- if you are unfamiliar about forking/creating PR, please see [this guide](https://guides.github.com/activities/forking/) first. If/when your changes are merged, you will appear as one of our [Contributors](https://github.com/psychrometrics/psychrolib/graphs/contributors). For specific instructions on how to report a bug, test PsychroLib locally or to learn about our coding conventions please see the sections below. | ||
|
|
||
| - [Report a bug](#report-a-bug) | ||
| - [Testing](#testing) | ||
| - [Coding conventions](#coding-conventions) | ||
|
|
||
|
|
||
| ## Report a bug | ||
|
|
||
| Before creating bug reports, please check if similar issue have already been reported [here](https://github.com/psychrometrics/psychrolib/issues). If none exist please create a new issue and include as many details as possible using the required template. | ||
|
|
||
| ## Testing | ||
|
|
||
| PsychroLib is automatically tested at each commit using continuous integration. If are looking to run the tests locally, make sure you can satisfy the required prerequisites and dependencies. | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - A C and Fortran compiler | ||
| - Python version 3.6 or greater. | ||
| - Node.js 10.x or greater | ||
| - Microsoft Excel | ||
|
|
||
|
|
||
| ### Dependencies | ||
|
|
||
| There are a number of dependencies required to run the tests that need to be installed first. From you command prompt, navigate to the `psychrolib` folder and type the following (I assume that pip and python are for version 3.6 or greater): | ||
|
|
||
| ``` | ||
| pip install numpy m2r cffi pytest | ||
| cd tests/js && npm install | ||
| cd ../.. | ||
| ``` | ||
|
|
||
|
|
||
| ### Run | ||
|
|
||
| To run the tests, type the following in your command prompt: | ||
|
|
||
|
|
||
| #### Python, C, Fortran | ||
| ``` | ||
| python -m pytest -v -s | ||
| ``` | ||
|
|
||
|
|
||
| #### JavaScript | ||
| ``` | ||
| cd tests/js && npm test | ||
| ``` | ||
|
|
||
|
|
||
| #### VBA/Excel | ||
| For VBA/Excel, navigate to `tests/vba` and launch the `test_psychrolib_ip.xlsm` and `test_psychrolib_si.xlsm` files. In Microsoft Excel, after enabling macros, from Visual Basic Editor (VBE) (Alt+F11 on Windows), select `test_psychrolib_<unit_system>` and run (F5 on Windows). | ||
|
|
||
|
|
||
| ## Coding conventions | ||
|
|
||
| The followings are minimal guidelines for new contributors aiming to contribute to the source code. To become acquainted with the conventions it may be easier to first read some of the functions already implemented in the language you are interested to contribute to. | ||
|
|
||
| - Always use the language-specific syntax except when defining function names where camel case (e.g. `GetTRankineFromTFahrenheit`) is used irrespective of the language. | ||
| - Include a clear description of the function, its inputs, outputs and types. | ||
| - Include references. | ||
| - Write clear and comprehensive tests. | ||
|
|
||
| Thank you! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,98 +1,92 @@ | ||
| <p align="center"><img src="https://raw.githubusercontent.com/psychrometrics/psychrolib/master/assets/psychrolib-logo.svg?sanitize=true" alt="PsychroLib Logo" height="150" width="150"></p> | ||
| <p align="center"><img src="assets/psychrolib-logo.svg" alt="PsychroLib Logo" height="150" width="150"></p> | ||
|
|
||
| # PsychroLib - A Library of Psychrometric Functions in C, Fortran, VBA (Excel), JavaScript, and Python | ||
| [](https://travis-ci.com/psychrometrics/psychrolib) | ||
| # PsychroLib: a library of psychrometric functions for Python, C, Fortran, JavaScript and VBA/Excel [](https://travis-ci.com/psychrometrics/psychrolib) | ||
|
|
||
|
|
||
| ### Table of contents | ||
| - [Introduction](#introduction) | ||
| - [Documentation](#documentation) | ||
| - [Installing](#installing) | ||
| - [Example usage](#example-usage) | ||
| - [Contributing](#contributing) | ||
| - [Versioning](#versioning) | ||
| - [Copyright and license](#copyright-and-license) | ||
| - [Acknowledgements](#acknowledgements) | ||
|
|
||
|
|
||
| ## Introduction | ||
|
|
||
| Psychrometrics are the study of physical and thermodynamic properties of moist air. These properties include, for example, the air's dew point temperature, its wet bulb temperature, relative humidity, humidity ratio, enthalpy. | ||
|
|
||
| The estimation of these properties is critical in several engineering and scientific applications such as heating, ventilation, and air conditioning (HVAC) and meteorology. Although formulae to calculate the psychrometric properties of air are widely available in the literature ([@Stull2011]; [@Wexler1983]; [@Stoecker1982]; [@Dilley1968]; [@Humphreys1920]), their implementation in computer programs or spreadsheets can be challenging and time consuming. | ||
|
|
||
| PsychroLib is a library of functions to enable calculating psychrometric properties of moist and dry air. The library is available for Python, C, Fortran, JavaScript, and Microsoft Excel Visual Basic for Applications (VBA). The functions are based of formulae from the 2017 ASHRAE Handbook — Fundamentals, Chapter 1. Functions can be grouped into two categories: | ||
|
|
||
| 1. Functions for the calculation of dew point temperature, | ||
| wet-bulb temperature, partial vapour pressure of water, humidity | ||
| ratio or relative humidity, knowing any other of these and dry bulb | ||
| temperature and atmospheric pressure; | ||
| 1. Functions for the calculation of dew point temperature, wet-bulb temperature, partial vapour pressure of water, humidity ratio or relative humidity, knowing any other of these and dry bulb temperature and atmospheric pressure. | ||
|
|
||
| 2. Functions for the calculation of other moist air properties. All these use the | ||
| humidity ratio as input. | ||
| 2. Functions for the calculation of other moist air properties. All these use the humidity ratio as input. | ||
|
|
||
| Relationships between these various functions are illustrated in Figure 1. To compute a moist air property such as enthalpy, knowing a humidity parameter such as dew point temperature, one first has to compute the humidity ratio from the dew point temperature, then compute the enthalpy from the humidity ratio. The functions in point (1) above include primary relationships corresponding to formulae from the ASHRAE Handbook, and secondary relationships which use a combination of primary relationships to calculate the result. For example, to compute dew point temperature knowing the partial pressure of water vapor in moist air, the library uses a formula from the ASHRAE Handbook (primary relationship). On the other hand to compute dew point temperature from relative humidity, the library first computes the partial pressure of water vapor, then computes the dew point temperature (secondary relationship). Primary relationships are shown with bold double arrows in Figure 1. | ||
|
|
||
| <p align="center"><img src="https://raw.githubusercontent.com/psychrometrics/psychrolib/master/assets/psychrolib-relationships.svg?sanitize=true" alt="Psychrometric relationships"></p> | ||
| <p align="center"><img src="assets/psychrolib-relationships.svg" alt="Psychrometric relationships"></p> | ||
| <p align="center"><b>Figure 1</b> - Psychrometric relationships.</p> | ||
|
|
||
| ## Features | ||
| The following psychrometric functions are currently available in PsychroLib across all supported languages: | ||
|
|
||
| |Function Name|Description| | ||
| |-------------|-----------| | ||
| |`GetTRankineFromTFahrenheit`|Utility function to convert temperature to degree Rankine given temperature in degree Fahrenheit.| | ||
| |`GetTKelvinFromTCelsius`|Utility function to convert temperature to Kelvin given temperature in degree Celsius.| | ||
| |`GetTWetBulbFromTDewPoint`|Return wet-bulb temperature given dry-bulb temperature, dew-point temperature, and pressure.| | ||
| |`GetTWetBulbFromRelHum`|Return wet-bulb temperature given dry-bulb temperature, relative humidity, and pressure.| | ||
| |`GetRelHumFromTDewPoint`|Return relative humidity given dry-bulb temperature and dew-point temperature.| | ||
| |`GetRelHumFromTWetBulb`|Return relative humidity given dry-bulb temperature, wet bulb temperature and pressure.| | ||
| |`GetTDewPointFromRelHum`|Return dew-point temperature given dry-bulb temperature and relative humidity.| | ||
| |`GetTDewPointFromTWetBulb`|Return dew-point temperature given dry-bulb temperature, wet-bulb temperature, and pressure.| | ||
| |`GetVapPresFromRelHum`|Return partial pressure of water vapor as a function of relative humidity and temperature.| | ||
| |`GetRelHumFromVapPres`| Return relative humidity given dry-bulb temperature and vapor pressure.| | ||
| |`GetTWetBulbFromHumRatio`|Return wet-bulb temperature given dry-bulb temperature, humidity ratio, and pressure.| | ||
| |`GetHumRatioFromTWetBulb`|Return humidity ratio given dry-bulb temperature, wet-bulb temperature, and pressure.| | ||
| |`GetHumRatioFromRelHum`|Return humidity ratio given dry-bulb temperature, relative humidity, and pressure.| | ||
| |`GetRelHumFromHumRatio`|Return relative humidity given dry-bulb temperature, humidity ratio, and pressure.| | ||
| |`GetHumRatioFromTDewPoint`|Return humidity ratio given dew-point temperature and pressure.| | ||
| |`GetTDewPointFromHumRatio`|Return dew-point temperature given dry-bulb temperature, humidity ratio, and pressure.| | ||
| |`GetHumRatioFromVapPres`|Return humidity ratio given water vapor pressure and atmospheric pressure.| | ||
| |`GetVapPresFromHumRatio`|Return vapor pressure given humidity ratio and pressure.| | ||
| |`GetDryAirEnthalpy`|Return dry-air enthalpy given dry-bulb temperature.| | ||
| |`GetDryAirDensity`|Return dry-air density given dry-bulb temperature and pressure.| | ||
| |`GetDryAirVolume`|Return dry-air volume given dry-bulb temperature and pressure.| | ||
| |`GetSatVapPres`|Return saturation vapor pressure given dry-bulb temperature.| | ||
| |`GetSatHumRatio`|Return humidity ratio of saturated air given dry-bulb temperature and pressure.| | ||
| |`GetSatAirEnthalpy`|Return saturated air enthalpy given dry-bulb temperature and pressure.| | ||
| |`GetVaporPressureDeficit`|Return vapor pressure deficit given dry-bulb temperature, humidity ratio, and pressure.| | ||
| |`GetDegreeOfSaturation`|Return the degree of saturation (i.e humidity ratio of the air / humidity ratio of the air at saturation at the same temperature and pressure) given dry-bulb temperature, humidity ratio, and atmospheric pressure.| | ||
| |`GetMoistAirEnthalpy`|Return moist air enthalpy given dry-bulb temperature and humidity ratio.| | ||
| |`GetMoistAirVolume`|Return moist air specific volume given dry-bulb temperature, humidity ratio, and pressure.| | ||
| |`GetMoistAirDensity`|Return moist air density given humidity ratio, dry bulb temperature, and pressure.| | ||
| |`GetStandardAtmPressure`|Return standard atmosphere barometric pressure, given the elevation (altitude).| | ||
| |`GetStandardAtmTemperature`|Return standard atmosphere temperature, given the elevation (altitude).| | ||
| |`GetSeaLevelPressure`|Return sea level pressure given dry-bulb temperature, altitude above sea level and pressure.| | ||
| |`GetStationPressure`|Return station pressure from sea level pressure.| | ||
| |`CalcPsychrometricsFromTWetBulb`|Utility function to calculate humidity ratio, dew-point temperature, relative humidity, vapour pressure, moist air enthalpy, moist air volume, and degree of saturation of air given dry-bulb temperature, wet-bulb temperature, and pressure.| | ||
| |`CalcPsychrometricsFromTDewPoint`|Utility function to calculate humidity ratio, wet-bulb temperature, relative humidity, vapour pressure, moist air enthalpy, moist air volume, and degree of saturation of air given dry-bulb temperature, dew-point temperature, and pressure.| | ||
| |`CalcPsychrometricsFromRelHum`|Utility function to calculate humidity ratio, wet-bulb temperature, dew-point temperature, vapour pressure, moist air enthalpy, moist air volume, and degree of saturation of air given dry-bulb temperature, relative humidity and pressure.| | ||
|
|
||
| ## Getting started | ||
| PsychroLib is available for Python, C, Fortran, JavaScript, and Microsoft Excel Visual Basic for Applications (VBA). A list of functions available in the library can be found in the [PsychroLib application programming interface (API) documentation](https://psychrometrics.github.io/psychrolib/api-docs.html). The page provides a comprehensive description of all the functions available in PsychroLib. Although it describes the Python version of the library, PsychroLib uses a common API across all the supported language implementations. | ||
|
|
||
| ### Installation instructions | ||
| If you are using Python, PsychroLib is available though the Python Package Index (PyPI) at https://pypi.org/project/PsychroLib. Assuming you have PyPI installed on your system, type the following in your command prompt: | ||
| ``` | ||
| pip install psychrolib | ||
| ``` | ||
|
|
||
| For all other languages, clone the repository or download the file directly from the repository, and include PsychroLib to your code according to the language specifications. | ||
|
|
||
| ### Example usage | ||
| For examples on how to use PsychroLib in Python, C, Fortran, JavaScript, and Microsoft Excel Visual Basic for Applications (VBA) please see [this guide](https://github.com/psychrometrics/psychrolib/blob/master/docs/how-to-use-psychrolib.md). | ||
|
|
||
| ## Documentation | ||
|
|
||
| PsychroLib is available for Python, C, Fortran, JavaScript, and Microsoft Excel Visual Basic for Applications (VBA). For an overview of currently available functions, please see the [list of available functions page](docs/available-functions.md). To consult the application programming interface (API), documentation please see the [API documentation page](https://psychrometrics.github.io/psychrolib/api-docs.html) instead -- although the API describes the Python version of the library, the API is common across all the supported language implementations. | ||
|
|
||
|
|
||
| ## Installing | ||
|
|
||
| To install or bundle the library as part of your program see the language-specific instructions below -- there are no external dependencies required. | ||
|
|
||
| ### Python | ||
|
|
||
| PsychroLib is available though the Python Package Index (PyPI) and can be installed using `pip` with `pip install psychrolib`. | ||
|
|
||
|
|
||
| ### C, Fortran, JS and VBA | ||
|
|
||
| Clone the repository, or download the file directly from the repository, and include PsychroLib to your code according to the language specifications. | ||
|
|
||
|
|
||
| ## Example usage | ||
|
|
||
| For examples on how to use PsychroLib in Python, C, Fortran, JavaScript, and Microsoft Excel Visual Basic for Applications (VBA) please see [this guide](docs/how-to-use-psychrolib.md). | ||
|
|
||
|
|
||
| ## Contributing | ||
| If you would like to contribute to the PsychroLib project, clone this repository, make your changes, and create a pull request with a **clear description** of your changes. If your changes are merged, you will appear as one of our [Contributors](https://github.com/psychrometrics/psychrolib/graphs/contributors). | ||
|
|
||
| If you are looking to contribute, please read our [Contributors' guide](CONTRIBUTING.md) for details. | ||
|
|
||
|
|
||
| ## Versioning | ||
|
|
||
| This project uses [semantic versioning](https://semver.org/). | ||
|
|
||
| ## Copyright and licence | ||
| Copyright | ||
|
|
||
| - For the current library implementation | ||
| Copyright (c) 2018 D. Thevenard and D. Meyer. | ||
| - For equations and coefficients published ASHRAE Handbook — Fundamentals, Chapter 1 | ||
| Copyright (c) 2017 ASHRAE Handbook — Fundamentals (https://www.ashrae.org) | ||
| ## Copyright and license | ||
|
|
||
| Copyright (c) 2018 D. Thevenard and D. Meyer for the current library implementation. | ||
|
|
||
| Copyright (c) 2017 ASHRAE Handbook — Fundamentals (https://www.ashrae.org) for equations and coefficients published ASHRAE Handbook — Fundamentals Chapter 1. | ||
|
|
||
| Licence | ||
| Licensed under the [MIT License](LICENSE.txt). | ||
|
|
||
| - Licensed under the [MIT License](https://github.com/psychrometrics/psychrolib/blob/master/LICENSE.txt). | ||
|
|
||
| ## Acknowledgements | ||
| Many thanks to Tom Worster ([tom--](https://github.com/tom--)) for his suggestions with the original JavaScript library implementation. | ||
|
|
||
| Many thanks to Tom Worster ([@tom--](https://github.com/tom--)) for his suggestions with the original JavaScript library implementation. | ||
|
|
||
|
|
||
|
|
||
| [@Dilley1968]: https://dx.doi.org/10.1175/1520-0450(1968)007<0717:otccov>2.0.co;2 "Dilley, A. C. (1968). On the computer calculation of vapor pressure and specific humidity gradients from psychrometric data. Journal of Applied Meteorology, 7(4), 717–719. doi:10.1175/1520-0450(1968)007<0717:otccov>2.0.co;2" | ||
|
|
||
| [@Humphreys1920]: https://archive.org/details/physicsofair00hump/page/n9 "Humphreys, W. J. (1920). Physics of the air. Philadelphia, PA: Pub. for the Franklin Institute of the state of Pennsylvania by J.B. Lippincott Company." | ||
|
|
||
| [@Stoecker1982]: https://books.google.de/books?id=PrZTAAAAMAAJ&dq "Stoecker, W., & Jones, J. (1982). Refrigeration and air conditioning. McGraw-hill international editions. New York, NY: McGraw-Hill." | ||
|
|
||
| [@Stull2011]: https://doi.org/10.1175/JAMC-D-11-0143.1 "Stull, R. (2011). Wet-bulb temperature from relative humidity and air temperature. Journal of Applied Meteorology and Climatology, 50(11), 2267–2269. doi:10.1175/jamc-d11-0143.1" | ||
|
|
||
| [@Wexler1983]: https://books.google.de/books?id=MH8URAAACAAJ "Wexler, A., Hyland, R., Stewart, R., & American Society of Heating, Refrigerating and Air-Conditioning Engineers. (1983). Thermodynamic properties of dry air, moist air and water and si psychrometric charts. Atlanta, GA: ASHRAE." |
Oops, something went wrong.