Tidied up documentation. This is more or less ready for others to play with.

This commit is contained in:
Simon Brooke 2026-08-11 19:21:08 +01:00
parent 91343b9c10
commit 507a365682
15 changed files with 337 additions and 40 deletions

View file

@ -11,12 +11,12 @@ partial data.
The 'packet', in the terminology of this library, is a map which has bindings
for some of the following keywords:
1. `:actual-humidity`
2. `:actual-vapour-pressure
1. `:absolute-humidity`
2. `:actual-vapour-pressure` *not yet implemented*
1. `:dew-point`
2. `:pressure-pascals`
3. `:pressure-millibars`
4. `:saturation-pressure`
4. `:saturation--vapour-pressure`
5. `:relative-humidity`
6. `:temperature`
7. `:temperature-celsius`

View file

@ -1,7 +1,18 @@
(defproject humidity "0.1.0-SNAPSHOT"
:description "FIXME: write description"
:url "http://example.com/FIXME"
:license {:name "EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0"
:url "https://www.eclipse.org/legal/epl-2.0/"}
:dependencies [[org.clojure/clojure "1.11.1"]]
:repl-options {:init-ns humidity.core})
:cloverage {:output "docs/cloverage"
:ns-exclude-regex [#"beowulf\.gendoc" #"beowulf\.scratch"]}
:codox {:metadata {:doc "**TODO**: write docs"
:doc/format :markdown}
:output-path "docs/codox"
:source-uri "https://github.com/simon-brooke/humidity/blob/master/{filepath}#L{line}"}
:dependencies [[org.clojure/clojure "1.12.5"]]
:description "Functions to compute relative humidity, absolute humidity, wet bulb
temperature, and other values related to humidity of air, given
partial data."
:license {:name "GPL-2.0-or-later"
:url "https://www.gnu.org/licenses/old-licenses/gpl-2.0.html"}
:repl-options {:init-ns humidity.core}
:plugins [[lein-ancient "1.0.0"]
[lein-cloverage "1.2.2"]
[lein-codox "0.10.8"]]
:url "https://git.journeyman.cc/simon/humidity")

View file

@ -1,10 +1,32 @@
(ns ^{:doc "Function to calculate wet bulb temperature (in ° C) given temperature in
° C and relative-humidity percentage (0...100).
See [authority](https://carnotcycle.wordpress.com/2012/08/04/how-to-convert-relative-humidity-to-absolute-humidity/)"}
(ns ^{:doc "Function to calculate absolute humidity in grammes per
metre<sup>3</sup> given temperature in &deg; K, saturation vapour pressure
in Pascals, and relative humidity as a percentage (0...100)."
:authority "https://carnotcycle.wordpress.com/2012/08/04/how-to-convert-relative-humidity-to-absolute-humidity/"
:author "simon"}
humidity.absolute
(:require
[humidity.constants :refer [Rw]]))
[humidity.constants :refer [Rw]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Absolute Humidity (grams/m3) = 6.112 × e^[(17.67 × T)/(T+243.5)] × rh × 2.1674
;; -----
@ -18,20 +40,14 @@
(def C magic-numbers)
;; (defn abs-humidity
;; "Returns absolute humidity in grammes per cubic metre given this
;; `temperature` in &deg; C and `relative-hunidity` percentage (0...100).
;; ![function for absolute humidity given temperature and relative humidity](https://carnotcycle.wordpress.com/wp-content/uploads/2014/09/ah3.gif)"
;; [temperature relative-humidity]
;; (when (empty? (filter false? (map number? [temperature relative-humidity])))
;; (let [T temperature
;; RHP relative-humidity]
;; (/ (* (C 1) (pow (* (/ (C 2) T) (+ T (C 3))) e) RHP (C 4))
;; (+ celsius-offset temperature)))))
;; AH=(RH × Ps)/(Rw × T × 100)
(defn abs-humidity [& {:keys [relative-humidity saturation-vapour-pressure temperature-kelvin]}]
(defn abs-humidity
"calculate and return absolute humidity in grammes per metre<sup>3</sup>
given temperature in &deg; K, saturation vapour pressure in Pascals, and
relative humidity as a percentage (0...100)."
[& {:keys [relative-humidity saturation-vapour-pressure temperature-kelvin]}]
(when (and relative-humidity saturation-vapour-pressure temperature-kelvin)
;; I don't know why I'm having to multiply by a thousand here...
(* (/ (* relative-humidity saturation-vapour-pressure) Rw temperature-kelvin) 1000)))
(*
(/
(* relative-humidity saturation-vapour-pressure) Rw temperature-kelvin)
1000)))

View file

@ -1 +1,23 @@
(ns humidity.actual-vp)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

View file

@ -1,5 +1,26 @@
(ns humidity.constants)
(ns ^{:doc "Constants used in humidity calculations."
:author "simon"} humidity.constants)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(def ^:const celsius-offset
"Value of 0&deg; Celsius in &deg; Kelvin"

View file

@ -1,4 +1,6 @@
(ns humidity.core
(ns ^{:doc "Central resolver function for humidity calculations"
:author "simon"}
humidity.core
(:require [humidity.absolute :refer [abs-humidity]]
[humidity.constants :refer [celsius-offset Pa]]
[humidity.relative :refer [rel-humidity]]
@ -6,6 +8,27 @@
[humidity.utils :refer [?assoc]]
[humidity.wet-bulb :as wb]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defn resolve-humidity
"Resolve humidity equations given the data in this packet."
[& {:keys [absolute-humidity pressure-pascals pressure-millibars
@ -37,7 +60,7 @@
(not temperature-kelvin))
(+ temperature-celsius celsius-offset))
:wet-bulb-temperature (when-not wet-bulb-temperature
(wb/wet-bulb-temperature packet)))))
(wb/wet-bulb-temperature packet)))))
(defn resolution
"Repeatedly run `resolve-humidity`, q.v., until we can infer no further

View file

@ -4,6 +4,27 @@
(:require [humidity.constants :refer [e Rw]]
[humidity.utils :refer [expt]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(def ^:const magic-numbers
"The magic numbers (empirical constants) from the derived expression. It
bothers me that all these formulae depend on 'empirical constants', *and*

View file

@ -5,6 +5,27 @@
(:require [clojure.math :refer [pow]]
[humidity.constants :refer [celsius-offset e]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defn saturation-vp-tetens
"Calculate and return saturation vapour pressure in Pa using Tetens'
formula, given temerature in &deg; Celsius."

View file

@ -1,6 +1,27 @@
(ns ^{:doc "Utility functions for humidity calculation"} humidity.utils
(ns ^{:doc "Utility functions for humidity calculation"
:author "simon"} humidity.utils
(:require [clojure.math :refer [pow]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(defmacro expt
"Clojure.math `pow` function does not allow ratios as exponents;
@ -16,4 +37,4 @@
(partition 2)
(filter second)
(map vec)
(into m)))
(into m)))

View file

@ -5,6 +5,27 @@
(:require [clojure.math :refer [atan]]
[humidity.utils :refer [expt]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(def ^:const magic-numbers
"The magic numbers (empirical constants) from the derived expression. It
bothers me that all these formulae depend on 'empirical constants', *and*

View file

@ -2,6 +2,26 @@
(:require [clojure.test :refer [deftest is testing]]
[humidity.constants :refer [celsius-offset]]
[humidity.absolute :refer [abs-humidity]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(deftest absolute-humidity-test
(testing "definitional"

View file

@ -0,0 +1,38 @@
(ns humidity.core-test
(:require
[clojure.test :refer [deftest is testing]]
[humidity.core :refer [resolution]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(deftest resolution-test
(testing "resolution")
(let [expected {:relative-humidity 100,
:temperature-celsius 35,
:pressure-pascals 101325,
:pressure-millibars 4053/4,
:saturation-vapour-pressure 5622.488734516426,
:temperature-kelvin 308.15,
:absolute-humidity 3953.618101887827}
packet {:relative-humidity 100 :temperature-celsius 35}
actual (resolution packet)]
(is (= actual expected))))

View file

@ -3,6 +3,27 @@
[humidity.constants :refer [celsius-offset]]
[humidity.relative :refer [rel-humidity rel-humidity]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(deftest relative-humidity-test
(testing "definitional"
(let [min-expected 99

View file

@ -1,10 +1,31 @@
(ns humidity.saturation-vp-test(:require [clojure.test :refer [deftest is testing]]
[humidity.constants :refer [celsius-offset]]
[humidity.saturation-vp :refer [saturation-vp saturation-vp-tetens]]))
(ns humidity.saturation-vp-test
(:require [clojure.test :refer [deftest is testing]]
[humidity.saturation-vp :refer [saturation-vp]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(deftest saturation-vp-test
(testing "from online sources"
(let [min-expected 5622
max-expected 5629
actual (saturation-vp {:temperature-celsius 35})]
(is (< min-expected actual max-expected)))))
max-expected 5629
actual (saturation-vp {:temperature-celsius 35})]
(is (< min-expected actual max-expected)))))

View file

@ -2,6 +2,26 @@
(:require [clojure.test :refer [deftest is testing]]
[humidity.wet-bulb :refer [wet-bulb-temperature]]))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; Copyright (C) 2026 Simon Brooke
;;;
;;; This program is free software; you can redistribute it and/or
;;; modify it under the terms of the GNU General Public License
;;; as published by the Free Software Foundation; either version 2
;;; of the License, or (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
;;; USA.
;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
(deftest wet-bulb-test
(testing "Example from paper"