Humidity ADRIO (#167)

* Humidity ADRIO template and basic demo devlog. * Modified README. * Providing sources to equations. * Consistent constants among equations. * Added warning for relative humidity exceeding 100%
NAU-CCL · Sep 30, 2024 · 80090a2 · 80090a2
1 parent 53d762d
commit 80090a2
Show file tree

Hide file tree

Showing 3 changed files with 276 additions and 0 deletions.
diff --git a/doc/devlog/2024-09-25.ipynb b/doc/devlog/2024-09-25.ipynb
@@ -0,0 +1,197 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 2024/09/25 Humidity Demo\n",
+    "_Author: Meaghan Freund_\n",
+    "\n",
+    "Demonstrations for calculating relative and absolute humidity."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Relative Humidity (%)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from epymorph.geography.us_census import StateScope\n",
+    "from epymorph import *\n",
+    "from epymorph.adrio import acs5, us_tiger\n",
+    "from epymorph.simulator.data import evaluate_param\n",
+    "from datetime import date\n",
+    "from epymorph.adrio import prism, humidity\n",
+    "\n",
+    "\n",
+    "county_scope = StateScope.in_states_by_code([\"FL\", \"GA\", \"MD\", \"NC\", \"SC\", \"VA\"])\n",
+    "time_period = TimeFrame.range(date(2015, 9, 1), date(2015, 9, 15))\n",
+    "geoids = county_scope.get_node_ids()\n",
+    "\n",
+    "rume = SingleStrataRume.build(\n",
+    "    ipm_library[\"no\"](),\n",
+    "    mm_library[\"no\"](),\n",
+    "    init.NoInfection(),\n",
+    "    scope=county_scope,\n",
+    "    time_frame=time_period,\n",
+    "    params={\n",
+    "        \"population\": acs5.Population(),\n",
+    "        \"centroid\": us_tiger.GeometricCentroid(),\n",
+    "        \"temperature\": prism.Temperature(time_period, \"Mean\"),\n",
+    "        \"dewpoint\": prism.DewPoint(time_period),\n",
+    "        \"relativehumidity\": humidity.RelativeHumidity(),\n",
+    "    },\n",
+    ")\n",
+    "\n",
+    "relH = evaluate_param(rume, \"relativehumidity\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "States: ['12' '13' '24' '37' '45' '51']\n",
+      "\n",
+      "Relative Humidity %:\n",
+      " [[82.29247707 78.73673715 70.56217196 90.31227335 76.14893317 74.48283823]\n",
+      " [85.25185444 72.48473366 67.41792538 70.68458439 70.01324731 69.17132151]\n",
+      " [78.29976357 75.54821181 67.15069971 67.48447965 67.13281399 67.73227384]\n",
+      " [77.32186688 80.19254851 67.01082176 70.51711361 73.6904453  68.21675678]\n",
+      " [79.93455281 68.10161981 67.9206651  69.85678071 67.00621659 74.10909072]\n",
+      " [75.81833625 71.89186563 74.84465422 76.6365127  70.37072625 77.65832266]\n",
+      " [74.34317473 75.70718238 60.61078428 80.48693349 73.27456982 68.48137665]\n",
+      " [84.95526673 81.65340323 67.8126301  76.89748941 74.37605125 73.30764455]\n",
+      " [81.79063605 78.07472153 66.82747446 78.40718529 77.2757879  72.09381854]\n",
+      " [78.33560913 78.30970421 66.91818963 76.00375206 73.22660548 71.21517857]\n",
+      " [79.10596205 73.49101524 74.43710298 75.07644244 72.31160603 86.17382683]\n",
+      " [75.26973271 77.30220293 64.54166222 80.32495257 74.14833877 70.34289327]\n",
+      " [82.36947073 89.88308743 86.42973676 86.60547114 86.70889621 89.37982246]\n",
+      " [87.03743915 61.83458686 61.69276135 59.5260582  56.20604293 64.50581352]\n",
+      " [74.2548915  62.02495383 56.46315471 56.88246216 55.68443265 61.12441233]]\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(f\"States: {geoids}\\n\")\n",
+    "\n",
+    "print(f\"Relative Humidity %:\\n {relH}\\n\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Absolute Humidity (kg/m^3)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from epymorph.geography.us_census import StateScope\n",
+    "from epymorph import *\n",
+    "from epymorph.adrio import acs5, us_tiger\n",
+    "from epymorph.simulator.data import evaluate_param\n",
+    "from datetime import date\n",
+    "from epymorph.adrio import prism, humidity\n",
+    "\n",
+    "\n",
+    "county_scope = StateScope.in_states_by_code([\"FL\", \"GA\", \"MD\", \"NC\", \"SC\", \"VA\"])\n",
+    "time_period = TimeFrame.range(date(2015, 9, 1), date(2015, 9, 15))\n",
+    "geoids = county_scope.get_node_ids()\n",
+    "\n",
+    "rume = SingleStrataRume.build(\n",
+    "    ipm_library[\"no\"](),\n",
+    "    mm_library[\"no\"](),\n",
+    "    init.NoInfection(),\n",
+    "    scope=county_scope,\n",
+    "    time_frame=time_period,\n",
+    "    params={\n",
+    "        \"population\": acs5.Population(),\n",
+    "        \"centroid\": us_tiger.GeometricCentroid(),\n",
+    "        \"temperature\": prism.Temperature(time_period, \"Mean\"),\n",
+    "        \"dewpoint\": prism.DewPoint(time_period),\n",
+    "        \"absH\": humidity.AbsoluteHumidity(),\n",
+    "        \"relativehumidity\": humidity.RelativeHumidity(),\n",
+    "    },\n",
+    ")\n",
+    "\n",
+    "absH = evaluate_param(rume, \"absH\")\n",
+    "temperature = evaluate_param(rume, \"temperature\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "States: ['12' '13' '24' '37' '45' '51']\n",
+      "\n",
+      "Absolute Humidity in kilograms/m^3:\n",
+      " [[0.02157049 0.01756676 0.01619405 0.01713875 0.01772859 0.01615852]\n",
+      " [0.02196012 0.01795541 0.01697285 0.01679116 0.01778455 0.01695887]\n",
+      " [0.02144872 0.0191554  0.0165168  0.01696885 0.01825382 0.0159444 ]\n",
+      " [0.02165772 0.01945792 0.0170474  0.01703492 0.01899462 0.01663736]\n",
+      " [0.02040071 0.01781235 0.01724438 0.01715848 0.01777634 0.01714062]\n",
+      " [0.02036741 0.01728276 0.0145759  0.01683907 0.01703094 0.01598974]\n",
+      " [0.02004383 0.01709421 0.01193905 0.01717102 0.01756007 0.01442969]\n",
+      " [0.02104921 0.01831033 0.01569843 0.01734535 0.01813853 0.01624217]\n",
+      " [0.02111527 0.01925519 0.01722752 0.01858397 0.01926944 0.01734197]\n",
+      " [0.02167872 0.01893431 0.01819047 0.01919721 0.01936023 0.01833424]\n",
+      " [0.02153306 0.01797879 0.01564714 0.01801404 0.01788959 0.01784365]\n",
+      " [0.02060285 0.01778488 0.01247926 0.01763154 0.01783718 0.01448929]\n",
+      " [0.02064383 0.01444779 0.01458403 0.0154779  0.01575996 0.01438727]\n",
+      " [0.01796495 0.00944938 0.00850683 0.00863338 0.0092333  0.0085051 ]\n",
+      " [0.01828865 0.01049121 0.00855442 0.00852249 0.00897823 0.00858981]]\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(f\"States: {geoids}\\n\")\n",
+    "\n",
+    "print(f\"Absolute Humidity in kilograms/m^3:\\n {absH}\\n\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.0rc1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/doc/devlog/README.md b/doc/devlog/README.md
@@ -70,6 +70,7 @@ This folder is a handy place to put Jupyter notebooks or other documents which h
 | 2024-08-28.ipynb | Trevor | | Demo of numpy ADRIOs. |
 | 2024-08-30.ipynb | Tyler | | Testing non-returner movement support. |
 | 2024-09-24.ipynb | Tyler | | Demonstrating ADRIO with simulated download activity. |
+| 2024-09-25.ipynb | Meaghan | | Demo of humidity ADRIO. |
 
 ## Contributing
 

diff --git a/epymorph/adrio/humidity.py b/epymorph/adrio/humidity.py
@@ -0,0 +1,78 @@
+from warnings import warn
+
+import numpy as np
+from numpy.typing import NDArray
+from typing_extensions import override
+
+from epymorph.adrio.adrio import Adrio
+from epymorph.data_shape import Shapes
+from epymorph.simulation import AttributeDef
+
+
+class AbsoluteHumidity(Adrio[np.float64]):
+    """
+    Creates a TxN matrix of floats representing absolute humidity in kilograms per cubic
+    meter calculated from a relative humidity, which is calculated from a given
+    temperature and dew point temperature, both in degrees Celsius.
+    """
+
+    requirements = [
+        AttributeDef("temperature", type=float, shape=Shapes.TxN),
+        AttributeDef("dewpoint", type=float, shape=Shapes.TxN),
+    ]
+
+    @override
+    def evaluate_adrio(self) -> NDArray[np.float64]:
+        temperature = self.data("temperature")
+        relH = self.defer(RelativeHumidity())
+        npHumidity = []
+
+        # equation from relative humidity to absolute humidity provided by following url
+        # https://carnotcycle.wordpress.com/2012/08/04/how-to-convert-relative-humidity-to-absolute-humidity/
+        # values 17.67 and 243.5 are changed to 17.625 and 243.04 respectively to cover
+        # a larger range of temperature values with a smaller margin of error
+        # (Alduchov and Eskridge 1996)
+        constants = 6.112 * 2.16679
+        npHumidity = (
+            (
+                constants
+                * np.exp((17.625 * temperature) / (temperature + 243.04))
+                * (relH)
+            )
+            / (273.15 + temperature)
+            / 1000  # convert to kilograms
+        )
+
+        return npHumidity
+
+
+class RelativeHumidity(Adrio[np.float64]):
+    """
+    Creates a TxN matrix of floats representing relative humidity as a percentage
+    which is calculated from a given temperature and dew point temperature, both in
+    degrees Celsius.
+    """
+
+    requirements = [
+        AttributeDef("temperature", type=float, shape=Shapes.TxN),
+        AttributeDef("dewpoint", type=float, shape=Shapes.TxN),
+    ]
+
+    @override
+    def evaluate_adrio(self) -> NDArray[np.float64]:
+        temperature = self.data("temperature")
+        dewpoint = self.data("dewpoint")
+        npHumidity = []
+
+        # equation for calculating relative humidity provided by following url
+        # https://qed.epa.gov/hms/meteorology/humidity/algorithms/#:~:text=Relative%20humidity%20is%20calculated%20using,is%20air%20temperature%20(celsius).
+        npHumidity = 100 * (
+            np.exp((17.625 * dewpoint) / (243.04 + dewpoint))
+            / np.exp((17.625 * temperature) / (243.04 + temperature))
+        )
+
+        # if the humidity exceeds 100%, warn users
+        if (npHumidity > 100).any():
+            warn("At least one value of relative humidity exceeds 100%.")
+
+        return np.array(npHumidity, dtype=np.float64)