tbd 3.0.0

data/tbd.schema.json

@@ -0,0 +1,571 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "id": "https://github.com/rd2/tbd/blob/master/tbd.schema.json",
+  "title": "TBD Schema",
+  "description": "Schema for Thermal Bridging and Derating",
+  "type": "object",
+  "properties": {
+    "description": {
+      "type": "string"
+    },
+    "schema": {
+      "type": "string"
+    },
+    "psis": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/PSI"
+      },
+      "uniqueItems": true
+    },
+    "khis": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/KHI"
+      },
+      "uniqueItems": true
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Edge"
+      },
+      "uniqueItems": true
+    },
+    "subsurfaces": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/SubSurface"
+      },
+      "uniqueItems": true
+    },
+    "surfaces": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Surface"
+      },
+      "uniqueItems": true
+    },
+    "spaces": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Space"
+      },
+      "uniqueItems": true
+    },
+    "spacetypes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/SpaceType"
+      },
+      "uniqueItems": true
+    },
+    "stories": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Story"
+      },
+      "uniqueItems": true
+    },
+    "building": {
+      "type": "object",
+      "$ref": "#/definitions/Building"
+    },
+    "log": {
+      "type": "object",
+      "$ref": "#/definitions/Log"
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "PSI": {
+      "description": "Set of PSI-values (in W/K per m) for thermal bridges",
+      "type": "object",
+      "properties": {
+        "id": {
+          "title": "Unique PSI set identifier",
+          "type": "string"
+        },
+        "rimjoist": {
+          "title": "Floor/wall edge PSI",
+          "type": "number"
+        },
+        "rimjoistconcave": {
+          "title": "Concave floor/wall edge PSI",
+          "type": "number"
+        },
+        "rimjoistconvex": {
+          "title": "Convex floor/wall edge PSI",
+          "type": "number"
+        },
+        "parapet": {
+          "title": "Roof/wall edge PSI",
+          "type": "number"
+        },
+        "parapetconcave": {
+          "title": "Concave roof/wall edge PSI",
+          "type": "number"
+        },
+        "parapetconvex": {
+          "title": "Convex roof/wall edge PSI",
+          "type": "number"
+        },
+        "fenestration": {
+          "title": "Window, door, skylight perimeter PSI",
+          "type": "number"
+        },
+        "head": {
+          "title": "Aperture head/lintel PSI",
+          "type": "number"
+        },
+        "headconcave": {
+          "title": "Concave aperture head/lintel PSI",
+          "type": "number"
+        },
+        "headconvex": {
+          "title": "Convex aperture head/lintel PSI",
+          "type": "number"
+        },
+        "sill": {
+          "title": "Aperture sill/base PSI",
+          "type": "number"
+        },
+        "sillconcave": {
+          "title": "Concave aperture sill/base PSI",
+          "type": "number"
+        },
+        "sillconvex": {
+          "title": "Convex aperture sill/base PSI",
+          "type": "number"
+        },
+        "jamb": {
+          "title": "Aperture jamb/side PSI",
+          "type": "number"
+        },
+        "jambconcave": {
+          "title": "Concave aperture jamb/side PSI",
+          "type": "number"
+        },
+        "jambconvex": {
+          "title": "Convex aperture jamb/side PSI",
+          "type": "number"
+        },
+        "corner": {
+          "title": "Any wall corner [0°,135°) or (225°,360°] PSI",
+          "type": "number"
+        },
+        "cornerconcave": {
+          "title": "Concave wall corner [0°,135°) PSI",
+          "type": "number"
+        },
+        "cornerconvex": {
+          "title": "Convex wall corner (225°,360°] PSI",
+          "type": "number"
+        },
+        "balcony": {
+          "title": "Floor/balcony edge PSI ",
+          "type": "number"
+        },
+        "balconyconcave": {
+          "title": "Concave floor/balcony edge PSI ",
+          "type": "number"
+        },
+        "balconyconvex": {
+          "title": "Convex floor/balcony edge PSI ",
+          "type": "number"
+        },
+        "party": {
+          "title": "Party wall edge PSI",
+          "type": "number"
+        },
+        "partyconcave": {
+          "title": "Concave party wall edge PSI",
+          "type": "number"
+        },
+        "partyconvex": {
+          "title": "Convex party wall edge PSI",
+          "type": "number"
+        },
+        "grade": {
+          "title": "Floor/foundation edge PSI",
+          "type": "number"
+        },
+        "gradeconcave": {
+          "title": "Concave floor/foundation edge PSI",
+          "type": "number"
+        },
+        "gradecovex": {
+          "title": "Convex floor/foundation edge PSI",
+          "type": "number"
+        },
+        "joint": {
+          "title": "Joints PSI",
+          "type": "number"
+        },
+        "transition": {
+          "title": "(Mild) transition PSI",
+          "type": "number"
+        }
+      },
+      "additionalProperties": false,
+      "minProperties": 2,
+      "required": [
+        "id"
+      ]
+    },
+    "KHI": {
+      "description": "KHI-value (in W/K) for a point thermal bridge",
+      "type": "object",
+      "properties": {
+        "id": {
+          "title": "Unique KHI identifier",
+          "type": "string"
+        },
+        "point": {
+          "title": "Point KHI-value",
+          "type": "number"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "point"
+      ]
+    },
+    "Edge": {
+      "description": "Surface(s) edge as thermal bridge",
+      "type": "object",
+      "properties": {
+        "psi": {
+          "title": "PSI-set identifier",
+          "type": "string"
+        },
+        "type": {
+          "title": "PSI-set type e.g., 'parapet'",
+          "type": "string",
+          "enum": [
+            "rimjoist",
+            "rimjoistconcave",
+            "rimjoisconvext",
+            "parapet",
+            "parapetconcave",
+            "parapetconvex",
+            "fenestration",
+            "head",
+            "headconcave",
+            "headconvex",
+            "sill",
+            "sillconcave",
+            "sillconvex",
+            "jamb",
+            "jambconcave",
+            "jambconvex",
+            "corner",
+            "cornerconcave",
+            "cornerconvex",
+            "balcony",
+            "balconyconcave",
+            "balconyconvex",
+            "party",
+            "partyconcave",
+            "partyconvex",
+            "grade",
+            "gradeconcave",
+            "gradeconvex",
+            "joint",
+            "transition"
+          ]
+        },
+        "length": {
+          "title": "Edge length (m), > 0 m",
+          "type": "number",
+          "minimum": 0,
+          "exclusiveMinimum": true
+        },
+        "v0x": {
+          "title": "Edge origin X vertex (m)",
+          "type": "number"
+        },
+        "v0y": {
+          "title": "Edge origin Y vertex (m)",
+          "type": "number"
+        },
+        "v0z": {
+          "title": "Edge origin Z vertex (m)",
+          "type": "number"
+        },
+        "v1x": {
+          "title": "Edge terminal X vertex (m)",
+          "type": "number"
+        },
+        "v1y": {
+          "title": "Edge terminal Y vertex (m)",
+          "type": "number"
+        },
+        "v1z": {
+          "title": "Edge terminal Z vertex (m)",
+          "type": "number"
+        },
+        "surfaces": {
+          "title": "Surface(s) connected to edge",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "type",
+        "surfaces"
+      ]
+    },
+    "SubSurface": {
+      "description": "Suburface(s) U-factors (optional)",
+      "type": "object",
+      "properties": {
+        "id": {
+          "title": "e.g. OS or E+ surface identifier",
+          "type": "string"
+        },
+        "usi": {
+          "title": "Overall U-factor",
+          "type": "number",
+          "minimum": 0.01,
+          "maximum": 10.0
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "usi"
+      ]
+    },
+    "Surface": {
+      "description": "Surface default PSI-set (optional)",
+      "type": "object",
+      "properties": {
+        "id": {
+          "title": "e.g. OS or E+ surface identifier",
+          "type": "string"
+        },
+        "psi": {
+          "title": "PSI-set identifier",
+          "type": "string"
+        },
+        "khis": {
+          "title": "Surface-hosted point thermal bridges",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "title": "Unique KHI-value identifier",
+                "type": "string"
+              },
+              "count": {
+                "title": "Number of KHI-matching point thermal bridges",
+                "type": "number",
+                "minimum": 1
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "count"
+            ]
+          },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false,
+      "minProperties": 2,
+      "required": [
+        "id"
+      ]
+    },
+    "Space": {
+      "description": "Space default PSI-set (optional for OS)",
+      "type": "object",
+      "properties": {
+        "id": {
+          "title": "e.g. OS space or E+ zone identifier",
+          "type": "string"
+        },
+        "psi": {
+          "title": "PSI-set identifier",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "psi"
+      ]
+    },
+    "SpaceType": {
+      "description": "SpaceType default PSI-set (optional for OS)",
+      "type": "object",
+      "properties": {
+        "id": {
+          "title": "e.g. OS spacetype identifier",
+          "type": "string"
+        },
+        "psi": {
+          "title": "PSI-set identifier",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "psi"
+      ]
+    },
+    "Story": {
+      "description": "Story default PSI-set (optional for OS)",
+      "type": "object",
+      "properties": {
+        "id": {
+          "title": "e.g. OS story identifier",
+          "type": "string"
+        },
+        "psi": {
+          "title": "PSI-set identifier",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "psi"
+      ]
+    },
+    "Building": {
+      "description": "Building default PSI-set (optional for OS)",
+      "type": "object",
+      "properties": {
+        "psi": {
+          "title": "PSI-set identifier",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "psi"
+      ]
+    },
+    "Log": {
+      "description": "TBD log",
+      "type": "object",
+      "properties": {
+        "date": {
+          "title": "Timestamp",
+          "type": "string"
+        },
+        "status": {
+          "title": "Global state",
+          "type": "string"
+        },
+        "ua": {
+          "title": "UA' assessment",
+          "type": "object",
+          "properties": {
+            "bloc1": {
+              "title": "heating setpoints >= 18°C",
+              "type": "object",
+              "$ref": "#/definitions/UaBlock"
+            },
+            "bloc2": {
+              "title": "heating setpoints < 18°C",
+              "type": "object",
+              "$ref": "#/definitions/UaBlock"
+            }
+          },
+          "additionalProperties": false,
+          "minProperties": 1
+        },
+        "results": {
+          "title": "Thermal derating results",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "messages": {
+          "title": "Logged messages",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/LogMessage"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "LogMessage": {
+      "description": "TBD log messages",
+      "type": "object",
+      "properties": {
+        "level": {
+          "title": "Severity of logged message (e.g. WARN)",
+          "type": "string"
+        },
+        "message": {
+          "title": "Logged message",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "UaBlock": {
+      "description": "UA summary",
+      "type": "object",
+      "properties": {
+        "summary": {
+          "type": "string"
+        },
+        "walls": {
+          "type": "string"
+        },
+        "roofs": {
+          "type": "string"
+        },
+        "floors": {
+          "type": "string"
+        },
+        "doors": {
+          "type": "string"
+        },
+        "windows": {
+          "type": "string"
+        },
+        "skylights": {
+          "type": "string"
+        },
+        "rimjoists": {
+          "type": "string"
+        },
+        "parapets": {
+          "type": "string"
+        },
+        "trim": {
+          "type": "string"
+        },
+        "corners": {
+          "type": "string"
+        },
+        "grade": {
+          "type": "string"
+        },
+        "other": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "minProperties": 2,
+      "required": ["summary"]
+    }
+  }
+}

data/v291_MacOS.md

@@ -0,0 +1,110 @@
+_We reiterate that building professionals and energy modellers can download the latest TBD version directly from the Guide itself, or under [releases](https://github.com/rd2/tbd/releases), or via NREL's [BCL](https://bcl.nrel.gov) (search for "bridging" or "rd2")._
+
+_Those instead interested in exploring/tweaking the source code (cloned or forked versions of TBD) can follow the Windows or MacOS Ruby setup described in TBD's [README](https://github.com/rd2/tbd#readme)._
+
+_The MacOS instructions below specifically target (older) Ruby v2.2.5 environments, needed for developing OpenStudio [v2.9.1](https://github.com/NREL/OpenStudio/releases/tag/v2.9.1) measures - the most up-to-date version that remains [compatible](https://github.com/NREL/OpenStudio/wiki/OpenStudio-SDK-Version-Compatibility-Matrix) with [SketchUp Make 2017](https://help.sketchup.com/en/downloading-older-versions). More recent OpenStudio versions (e.g. v3.4.0) can - to a large degree - safely translate older .osm files. Although TBD (and Topolys) are systematically tested against updated OpenStudio versions (v2.9.1 onwards), the following Ruby v2.2.5 setup is no longer tested or maintained. Nonetheless, it may be of some help for the more adventurous of you._
+
+
+## v2.9.1 MacOS Instructions
+_tested Catalina 10.15.4 up to Big Sur 11.4_
+
+OpenStudio v2.9.1 measures require Ruby v2.2.5, which is several iterations behind the default Ruby v2.6 version available on any recently-purchased Mac. Although it is common to develop/test using more than one Ruby version, some effort is nonetheless required for older vintages: v2.2.5 is no longer officially supported, it requires the deprecated OpenSSL-1.0 (not 1.1), etc. To help Mac users (and potentially Linux users as well), the following steps are recommended (although architecture-specific tweaks may be required).
+
+From a Terminal, install [Homebrew](https://brew.sh/index) - nice for package distribution and management. With a few tweaks, it will handle most package downloads, dependencies, etc. Using Homebrew, install OpenSSL-1.0, and then _rbenv_ (which allows users to manage multiple Ruby versions). One way of doing it:
+
+```
+brew install rbenv/tap/openssl@1.0
+```
+
+By _tapping_, Homebrew provides a way to access third-party repositories that are no longer officially supported by Homebrew, like Ruby v2.2.5 and OpenSSL-1.0. The above instruction tells Homebrew to install compatible versions of OpenSSL-1.0 with _rbenv_ (e.g. 1.0.2t, 1.0.2u).
+
+Next, ensure that Homebrew and _rbenv_ use OpenSSL-1.0 for future, local Ruby development. Edit (or create) a user’s local _~/.zshrc_ file (instructions here are provided for _zsh_, the default macOS Terminal shell interface - _bash_ users: adapt!), by pasting-in the following:
+
+```
+eval "$(rbenv init - zsh)"
+export PATH="/usr/local/opt/openssl@1.0/bin:$PATH"
+export LDFLAGS="-L/usr/local/opt/openssl@1.0/lib"
+export CPPFLAGS="-I/usr/local/opt/openssl@1.0/include"
+export PKG_CONFIG_PATH="/usr/local/opt/openssl@1.0/lib/pkgconfig"
+export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.0)"
+```
+
+There’s probably more there than necessary, but it should do the trick for the next few steps, and/or for future work. Quit the Terminal and start a new one, or simply _source_ the zshrc file:
+
+```
+source ~/.zshrc
+```
+
+Make sure the right OpenSSL version is recognized, and then instruct Homebrew to switch over to it:
+
+```
+openssl version
+brew switch openssl 1.0.2t
+```
+
+… or whatever Openssl 1.0 version was installed, e.g. 1.0.2u. Then install _ruby-build_, _rbenv_ and finally Ruby v2.2.5:
+
+```
+brew install ruby-build
+brew install rbenv
+rbenv install 2.2.5
+```
+
+Install a compatible version of [bundler](https://bundler.io), great for managing Ruby gems and dependencies:
+
+```
+gem install bundler -v 1.17.3
+```
+In some cases, (temporarily) switching over to an insecure ```http``` connection to rubygems.org (instead of the default ```https```) may be required:
+```
+gem source -r https://rubygems.org/
+gem source -a http://rubygems.org/
+gem install bundler -v 1.17.3
+gem source -r http://rubygems.org/
+gem source -a https://rubygems.org/
+```
+
+In the Terminal, check the Ruby version:
+
+```
+ruby -v
+```
+
+... should still report the current Ruby version used by macOS (e.g. ```system``` or ```2.6```). To ensure Ruby v2.2.5 is used for developing OpenStudio v2.9.1-compatible measures, instruct _rbenv_ to use Ruby v2.2.5 _locally_ within a user’s chosen directory (e.g. "sandbox291"):
+
+```
+mkdir ~/Documents/sandbox291
+cd ~/Documents/sandbox291
+rbenv local 2.2.5
+ruby -v
+```
+
+… should now report ```2.2.5``` as the local Ruby version, to be used by default for anything under the "sandbox291" directory tree. To ensure both Ruby versions are operational and safe, run the following checkup twice - once from a user’s _home_ (or ~/), then from within e.g., "sandbox291":
+
+```
+cd ~/
+ruby -ropen-uri -e 'eval open("https://git.io/vQhWq").read'
+cd ~/Documents/sandbox291
+ruby -ropen-uri -e 'eval open("https://git.io/vQhWq").read'
+```
+
+If successful, one should get a ```Hooray!``` from both Ruby versions confirming valid communication with [Rubygems](https://rubygems.org/), yet with their specific RubyGems and OpenSSL versions, as well as their own SSL certificates.
+
+Install OpenStudio [v2.9.1](https://github.com/NREL/OpenStudio/releases/tag/v2.9.1).
+
+Then create the file _~/.rbenv/versions/2.2.5/lib/ruby/site_ruby/openstudio.rb_, and edit it so it _points_ to your new OpenStudio installation:
+
+```
+require '/Applications/OpenStudio-2.9.1/Ruby/openstudio.rb'
+```
+
+Verify your local OpenStudio and Ruby configuration:
+
+```
+cd ~/Documents/sandbox291
+ruby -e "require 'openstudio'" -e "puts OpenStudio::Model::Model.new"
+```
+
+Install the latest version of _git_ (e.g. through Homebrew), and ```git clone``` the TBD measure under e.g., "sandbox291".
+
+Run the basic [tests](https://github.com/rd2/tbd#complete-list-of-test-commands) to ensure the measure operates as expected.