Python: Add support for handling numpy vectors and JIT compilation with Numba (Closes #34) (#57)

Add support for handling numpy vectors as inputs/outputs and greater run time performance using Numba: when Numba is found, all functions are compiled using the Numba just in time (JIT) compiler.

Author: dmey

.travis.yml

@@ -1,46 +1,86 @@
 dist: xenial
-sudo: required
 
-# TODO: blend Python and R together.
-
-matrix:
+jobs:
   include:
     - language: python
-      python: 3.6
-      before_install:
-        - pip freeze
-        - pip uninstall numpy -y && pip install numpy==1.15.4 # FIXME: Temporary fix as f2py is buggy on numpy 1.16.0
-        - sudo apt-get install gfortran
-        - pip install Sphinx==2.4.* sphinx_bootstrap_theme sphinx-autodoc-typehints m2r cffi
-        - sudo apt install snapd
-        - sudo snap install dotnet-sdk --classic
-      install:
-        - sphinx-build docs/sphinx build/html
-        - touch build/html/.nojekyll # https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/
-        - cd tests/js && npm install
-        - cd $TRAVIS_BUILD_DIR
-      script:
-        # See https://stackoverflow.com/a/34140498 for why "python -m" is needed.
-        - python3 -m pytest -v -s
-        - cd tests/js && npm test
-        - cd $TRAVIS_BUILD_DIR
-        - cd src/c_sharp && dotnet-sdk.dotnet test
-        - cd $TRAVIS_BUILD_DIR
+      python: 3.8
+      env:
+        - USE_NUMBA=no
+      addons:
+        apt:
+          packages:
+            - gfortran
+
+    - language: python
+      python: 3.8
+      env:
+        - USE_NUMBA=yes
+      addons:
+        apt:
+          packages:
+            - gfortran
+
+    - language: minimal
+      addons:
+          snaps:
+            - name: dotnet-sdk
+      env:
+        - C_SHARP=yes
+
     - language: r
-      r: release
-      before_install:
-        - Rscript -e 'install.packages("devtools")'
-        - cd $TRAVIS_BUILD_DIR/src/r
-        - Rscript tools/deploy.R
-      script:
-        - R CMD build .
-        - R CMD check --as-cran psychrolib*tar.gz
+
+before_install:
+  - | 
+    set -x
+    if [[ "$TRAVIS_PYTHON_VERSION" ]]; then
+      pip install cffi # Common to both
+      if [[ "$USE_NUMBA" == "no" ]]; then
+        pip install Sphinx==2.4.* sphinx_bootstrap_theme sphinx-autodoc-typehints m2r
+      fi
+      if [[ "$USE_NUMBA" == "yes" ]]; then
+        pip install numba
+      fi
+    fi
+    if [[ "$TRAVIS_R_VERSION" ]]; then
+      Rscript -e 'install.packages("devtools")'
+      cd "$TRAVIS_BUILD_DIR/src/r" || exit
+      Rscript tools/deploy.R
+    fi
+
+install:
+  - | 
+    set -x
+    if [[ "$TRAVIS_PYTHON_VERSION" ]]; then
+      sphinx-build docs/sphinx build/html
+      touch build/html/.nojekyll # https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/
+      cd tests/js && npm install
+      cd $TRAVIS_BUILD_DIR
+    fi
+
+script:
+  - | 
+    set -x
+    if [[ "$TRAVIS_PYTHON_VERSION" ]]; then
+      cd $TRAVIS_BUILD_DIR
+      # See https://stackoverflow.com/a/34140498 for why "python -m" is needed.
+      python3 -m pytest -v -s
+      # Javascript tests
+      cd tests/js && npm test
+    fi
+    if [[ "$TRAVIS_R_VERSION" ]]; then
+      R CMD build .
+      R CMD check --as-cran psychrolib*tar.gz
+    fi
+    if [[ "$C_SHARP" ]]; then
+      cd $TRAVIS_BUILD_DIR
+      cd src/c_sharp && dotnet-sdk.dotnet test
+    fi
 
 deploy:
- provider: pages
- skip_cleanup: true
- github_token: $GITHUB_TOKEN
- local_dir: build/html
- on:
-   branch: master
-   condition: $TRAVIS_PYTHON_VERSION == 3.6
+  provider: pages
+  skip_cleanup: true
+  github_token: $GITHUB_TOKEN
+  local_dir: build/html
+  on:
+    branch: master
+    condition: $USE_NUMBA == "no"

README.md

@@ -1,32 +1,46 @@
-# <img src="assets/psychrolib_logo.svg" alt="PsychroLib Logo" height="40" width="40"> PsychroLib [![PyPI](https://img.shields.io/pypi/v/psychrolib)](https://pypi.org/project/PsychroLib) [![NuGet](https://img.shields.io/nuget/v/PsychroLib.svg?maxAge=600)](https://www.nuget.org/packages/PsychroLib) [![CRAN](http://www.r-pkg.org/badges/version/psychrolib)](https://cran.r-project.org/package=psychrolib)
+<div align="center">
+<img src="assets/psychrolib_logo.svg" alt="PsychroLib Logo" height="80" width="80"> 
 
+<!-- omit in toc -->
+# PsychroLib
 
-|CI and Tests | Paper DOI | Software DOI |
-|---|---|------|
-[![Build Status](https://travis-ci.com/psychrometrics/psychrolib.svg?branch=master)](https://travis-ci.com/psychrometrics/psychrolib) | [![DOI](https://joss.theoj.org/papers/10.21105/joss.01137/status.svg)](https://doi.org/10.21105/joss.01137) | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2537945.svg)](https://doi.org/10.5281/zenodo.2537945)|
+[![PyPI](https://img.shields.io/pypi/v/psychrolib)](https://pypi.org/project/PsychroLib) [![NuGet](https://img.shields.io/nuget/v/PsychroLib.svg?maxAge=600)](https://www.nuget.org/packages/PsychroLib) [![CRAN](https://www.r-pkg.org/badges/version/psychrolib)](https://cran.r-project.org/package=psychrolib) [![Build Status](https://travis-ci.com/psychrometrics/psychrolib.svg?branch=master)](https://travis-ci.com/psychrometrics/psychrolib) [![DOI](https://joss.theoj.org/papers/10.21105/joss.01137/status.svg)](https://doi.org/10.21105/joss.01137) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2537945.svg)](https://doi.org/10.5281/zenodo.2537945)
 
-PsychroLib is a library of functions to enable the calculation of psychrometric properties of moist and dry air. Versions of PsychroLib are available for Python, C, C#, Fortran, R, JavaScript, Microsoft Excel Visual Basic for Applications (VBA). The library works in both metric (SI) and imperial (IP) systems of units. For a general overview and a list of currently available functions, please see the [overview page](docs/overview.md).
+[Overview](#overview) | [Documentation](#documentation) | [Installation](#installation) | [How to cite](#how-to-cite) | [Contributing](#contributing) | [Development](#development) | [Copyright and license](#copyright-and-license) | [Acknowledgements](#acknowledgements)
+
+</div>
+
+
+## Overview
+
+PsychroLib is a software library to enable the calculation of psychrometric properties of moist and dry air. Versions of PsychroLib are available for Python, C, C#, Fortran, R, JavaScript, Microsoft Excel Visual Basic for Applications (VBA). PsychroLib works in both metric (SI) and imperial (IP) systems of units. For a general overview and a list of currently available functions, please see the [overview page](docs/overview.md).
 
 
 ## Documentation
 
-The API documentation is available [here](https://psychrometrics.github.io/psychrolib/api_docs.html). Please note that although the API describes the Python version of the library, the API is common across all the supported language implementations. In R please note that (1) constants, like `ZERO_FAHRENHEIT_AS_RANKINE` are not exported (i.e. not directly accessible to users), (2) functions accept a vector, not a scalar (3) bulk calculations, like `CalcPsychrometricsFromRelHum` return a list.
+Please see the [Python API documentation](https://psychrometrics.github.io/psychrolib/api_docs.html) for the common API across all the supported language implementations. In Python, array support and improved runtime performance can be optionally enabled by installing [Numba](https://numba.pydata.org/). In R (1) constants, like `ZERO_FAHRENHEIT_AS_RANKINE` are not exported (i.e. not directly accessible to users), (2) functions accept a vector, not a scalar (3) bulk calculations, like `CalcPsychrometricsFromRelHum` return a list.
 
 Examples on how to use PsychroLib in all the supported languages are described in [this guide](docs/examples.md).
 
 
-## Installing
+## Installation
 
-- Python: from the [Python Package Index (PyPI)](https://pypi.org/project/PsychroLib/).
+- Python: from the [Python Package Index (PyPI)](https://pypi.org/project/PsychroLib/). [Numba](https://numba.pydata.org/) can be optionally installed to enable array support and faster runtime performance.
 - C# (.NET): from the [NuGet package](https://www.nuget.org/packages/PsychroLib/) manager or clone the repository, and bundle according to your requirements.
 - C, Fortran and JavaScript: clone the repository, and bundle according to your requirements.
 - VBA/Excel: download the ready-made spreadsheets from the [release tab](https://github.com/psychrometrics/psychrolib/releases).
 - R: from the [Comprehensive R Archive Network (CRAN)](https://cran.r-project.org/package=psychrolib).
 
 
-## Citing
+## How to cite
+
+When using PsychroLib, please cite the software summary paper and software version using the following Digital Object Identifiers (DOIs) to [generate citations in your preferred style](https://citation.crosscite.org/):
+
+| Software summary paper                                                                                                  | Software version*                                                                                                  |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| [![DOI](https://joss.theoj.org/papers/10.21105/joss.01137/status.svg)](https://doi.org/10.21105/joss.01137) | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2537945.svg)](https://doi.org/10.5281/zenodo.2537945) |
 
-If you are using PsychroLib, please cite the the summary paper (https://doi.org/10.21105/joss.01137) *together* with the specific version of PsychroLib you are using (see [list on Zenodo](https://doi.org/10.5281/zenodo.2537945) for all available versions).
+*please make sure to cite the same version you are using with the correct DOI. For a list of all available versions see see [more on Zenodo]((https://doi.org/10.5281/zenodo.2537945)).
 
 
 ## Contributing

src/python/psychrolib.py

@@ -172,6 +172,13 @@ def SetUnitSystem(Units: UnitSystem) -> None:
     else:
         PSYCHROLIB_TOLERANCE = 0.001
 
+    if has_numba:
+        # Need to recompile functions when the system of units is changed as Numba considers these global variables compile-time constants.
+        # See https://numba.pydata.org/numba-doc/dev/user/faq.html#numba-doesn-t-seem-to-care-when-i-modify-a-global-variable
+        globals()['isIP'] = njit(isIP.py_func)
+        for func in func_list:
+            globals()[func[0]] = vectorize(func[1])
+
 def GetUnitSystem() -> Optional[UnitSystem]:
     """
     Return system of units in use.
@@ -1459,3 +1466,23 @@ def CalcPsychrometricsFromRelHum(TDryBulb: float, RelHum: float, Pressure: float
     MoistAirVolume = GetMoistAirVolume(TDryBulb, HumRatio, Pressure)
     DegreeOfSaturation = GetDegreeOfSaturation(TDryBulb, HumRatio, Pressure)
     return HumRatio, TWetBulb, TDewPoint, VapPres, MoistAirEnthalpy, MoistAirVolume, DegreeOfSaturation
+
+
+# This section provides support for vectorization through the use of the Numba library (http://numba.pydata.org/)
+# If Numba is not installed, the library just works with scalars and vectorization is simply not supported 
+try:
+    from inspect import isfunction
+    from numba import vectorize, njit
+
+    has_numba = True
+    # Needs to compile as used in vectorized functions below.
+    isIP = njit(isIP)
+    # Vectorise all 'core' functions. 
+    # Utility function are excluded as they are just wrappers.
+    func_list = []
+    for func in list(globals().items()):
+        if isfunction(func[1]) and func[0].startswith(('Get', 'dLnPws_')) and func != 'GetUnitSystem':
+            globals()[func[0]] = vectorize(func[1])
+            func_list.append(func)
+except ImportError:
+    has_numba = False