Module: OSut

Extended by:: OSlg

Defined in:: lib/osut/version.rb,
lib/osut/utils.rb

Overview

BSD 3-Clause License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Constant Summary collapse

TOL = default distance tolerance (m)

0.01

TOL2 = default area tolerance (m2)

TOL * TOL

DBG = see github.com/rd2/oslg

OSlg::DEBUG.dup

INF = see github.com/rd2/oslg

OSlg::INFO.dup

WRN = see github.com/rd2/oslg

OSlg::WARN.dup

ERR = see github.com/rd2/oslg

OSlg::ERROR.dup

FTL = see github.com/rd2/oslg

OSlg::FATAL.dup

NS = OpenStudio object identifier method

"nameString"

HEAD = standard 80“ door

2.032

SILL = standard 30“ window sill

0.762

SIDZ = General surface orientations (see facets method)

[:bottom, # e.g. ground-facing, exposed floors
    :top, # e.g. roof/ceiling
  :north, # NORTH
   :east, # EAST
  :south, # SOUTH
   :west  # WEST
].freeze

VERSION = OSut version

"0.6.0".freeze

@@mass = Thermal mass categories (e.g. exterior cladding, interior finish, framing).

[
    :none, # token for 'no user selection', resort to defaults
   :light, # e.g. 16mm drywall interior
  :medium, # e.g. 100mm brick cladding
   :heavy  # e.g. 200mm poured concrete
].freeze

@@mats = Basic materials (StandardOpaqueMaterials only).

{
  material: {}, # generic, e.g. lightweight cladding over furring, fibreboard
      sand: {},
  concrete: {},
     brick: {},
   drywall: {}, # e.g. finished drywall, intermediate sheating
   mineral: {}, # e.g. light, semi-rigid rock wool insulation
   polyiso: {}, # e.g. polyisocyanurate panel (or similar)
 cellulose: {}, # e.g. blown, dry/stabilized fibre
      door: {}  # single composite material (45mm insulated steel door)
}.freeze

@@film = default inside + outside air film resistances (m2.K/W)

{
    shading: 0.000, # NA
  partition: 0.150, # uninsulated wood- or steel-framed wall
       wall: 0.150, # un/insulated wall
       roof: 0.140, # un/insulated roof
      floor: 0.190, # un/insulated (exposed) floor
   basement: 0.120, # un/insulated basement wall
       slab: 0.160, # un/insulated basement slab or slab-on-grade
       door: 0.150, # standard, 45mm insulated steel (opaque) door
     window: 0.150, # vertical fenestration, e.g. glazed doors, windows
   skylight: 0.140  # e.g. domed 4' x 4' skylight
}.freeze

@@uo = default (~1980s) envelope Uo (W/m2•K), based on surface type

{
    shading: nil,   # N/A
  partition: nil,   # N/A
       wall: 0.384, # rated R14.8 hr•ft2F/Btu
       roof: 0.327, # rated R17.6 hr•ft2F/Btu
      floor: 0.317, # rated R17.9 hr•ft2F/Btu (exposed floor)
   basement: nil,
       slab: nil,
       door: 1.800, # insulated, unglazed steel door (single layer)
     window: 2.800, # e.g. patio doors (simple glazing)
   skylight: 3.500  # all skylight technologies
}.freeze

Class Method Summary collapse

.extended(base) ⇒ Object

Callback when other modules extend OSlg.

Instance Method Summary collapse

#addSkyLights(spaces = [], opts = {}) ⇒ Float

Adds skylights to toplight selected OpenStudio (occupied, conditioned) spaces, based on requested skylight area, or a skylight-to-roof ratio (SRR%).
#addSubs(s = nil, subs = [], clear = false, bound = false, realign = false, bfr = 0.005) ⇒ Bool, false

Adds sub surfaces (e.g. windows, doors, skylights) to surface.
#airLoopsHVAC?(model = nil) ⇒ Bool, false

Validates if model has zones with HVAC air loops.
#alignedHeight(pts = nil, force = false) ⇒ Float, 0.0

Returns ‘height’ of a set of OpenStudio 3D points, once re/aligned.
#alignedWidth(pts = nil, force = false) ⇒ Float, 0.0

Returns ‘width’ of a set of OpenStudio 3D points, once re/aligned.
#availabilitySchedule(model = nil, avl = "") ⇒ OpenStudio::Model::Schedule^?

Generates an HVAC availability schedule.
#blc(pts = nil) ⇒ OpenStudio::Point3dVector

Returns OpenStudio 3D points (min 3x) conforming to an BottomLeftCorner (BLC) convention.
#boundedBox(pts = nil) ⇒ OpenStudio::Point3dVector

Generates a BLC bounded box within a polygon.
#cast(p1 = nil, p2 = nil, ray = nil) ⇒ OpenStudio::Point3dVector

Casts an OpenStudio polygon onto the 3D plane of a 2nd polygon, relying on an independent 3D ray vector.
#clockwise?(pts = nil) ⇒ Bool, false

Validates whether OpenStudio 3D points are listed clockwise, assuming points have been pre-‘aligned’ - not just flattened along XY (i.e. Z = 0).
#coolingTemperatureSetpoints?(model = nil) ⇒ Bool, false

Validates if model has zones with valid cooling temperature setpoints.
#daylit?(space = nil, sidelit = true, toplit = true, baselit = true) ⇒ Bool, false

Validates whether space has outdoor-facing surfaces with fenestration.
#defaultConstructionSet(s = nil) ⇒ OpenStudio::Model::DefaultConstructionSet^?

Returns a surface’s default construction set.
#facets(spaces = [], boundary = "all", type = "all", sides = []) ⇒ Array<OpenStudio::Model::Surface>

Returns an array of OpenStudio space surfaces or subsurfaces that match criteria, e.g.
#facingDown?(pts = nil) ⇒ Bool, false

Validates whether a polygon faces downwards, harmonized with OpenStudio Utilities’ “alignZPrime” function.
#facingUp?(pts = nil) ⇒ Bool, false

Validates whether a polygon faces upwards, harmonized with OpenStudio Utilities’ “alignZPrime” function.
#farthest(pts = nil, p01 = nil) ⇒ Integer^?

Returns OpenStudio 3D point (in a set) farthest from a point of reference, e.g.
#fenestration?(s = nil) ⇒ Bool, false

Validates whether a sub surface is fenestrated.
#fits?(p1 = nil, p2 = nil, entirely = false) ⇒ Bool, false

Determines whether a 1st OpenStudio polygon fits in a 2nd polygon.
#flatten(pts = nil, axs = :z, val = 0) ⇒ OpenStudio::Point3dVector

Flattens OpenStudio 3D points vs X, Y or Z axes.
#genAnchors(s = nil, set = [], tag = :box) ⇒ Integer

Identifies ‘leader line anchors’, i.e.
#genConstruction(model = nil, specs = {}) ⇒ OpenStudio::Model::Construction^?

Generates an OpenStudio multilayered construction, + materials if needed.
#genExtendedVertices(s = nil, set = [], tag = :vtx) ⇒ OpenStudio::Point3dVector

Extends (larger) polygon vertices to circumscribe one or more (smaller) subsets of vertices, based on previously-generated ‘leader line’ anchors.
#genInserts(s = nil, set = []) ⇒ OpenStudio::Point3dVector

Generates (1D or 2D) arrays of (smaller) rectangular collection of points, (e.g. arrays of polygon inserts) from subset parameters, within a (larger) set (e.g. parent polygon).
#genMass(sps = OpenStudio::Model::SpaceVector.new, ratio = 2.0) ⇒ Bool, false

Generates an internal mass definition and instances for target spaces.
#genShade(subs = OpenStudio::Model::SubSurfaceVector.new) ⇒ Bool, false

Generates a solar shade (e.g. roller, textile) for glazed OpenStudio SubSurfaces (v351+), controlled to minimize overheating in cooling months (May to October in Northern Hemisphere), when outdoor dry bulb temperature is above 18°C and impinging solar radiation is above 100 W/m2.
#genSlab(pltz = [], z = 0) ⇒ OpenStudio::Point3dVector

Generates an OpenStudio 3D point vector of a composite floor “slab”, a ‘union’ of multiple rectangular, horizontal floor “plates”.
#getCollinears(pts = nil, n = 0) ⇒ OpenStudio::Point3dVector

Returns sequential collinear points in an OpenStudio 3D point vector.
#getHorizontalRidges(roofs = []) ⇒ Array

Identifies horizontal ridges along 2x sloped (roof?) surfaces (same space).
#getLineIntersection(s1 = [], s2 = []) ⇒ OpenStudio::Point3d^?

Returns point of intersection of 2x 3D line segments.
#getNonCollinears(pts = nil, n = 0) ⇒ OpenStudio::Point3dVector

Returns sequential non-collinear points in an OpenStudio 3D point vector.
#getRealignedFace(pts = nil, force = false) ⇒ Hash

Generates re-‘aligned’ polygon vertices wrt main axis of symmetry of its largest bounded box.
#getRoofs(spaces = []) ⇒ Array<OpenStudio::Model::Surface>

Returns outdoor-facing, space-related roof surfaces.
#getSegments(pts = nil) ⇒ OpenStudio::Point3dVectorVector

Returns paired sequential points as (non-zero length) line segments.
#getTriads(pts = nil, co = false) ⇒ OpenStudio::Point3dVectorVector

Returns points as (non-zero length) ‘triads’, i.e.
#getUniques(pts = nil, n = 0) ⇒ OpenStudio::Point3dVector

Returns unique OpenStudio 3D points from an OpenStudio 3D point vector.
#glazingAirFilmRSi(usi = 5.85) ⇒ Float, 0.1216

Returns total air film resistance of a fenestrated construction (m2•K/W).
#grossRoofArea(spaces = []) ⇒ Object

Returns the “gross roof area” above selected conditioned, occupied spaces.
#heatingTemperatureSetpoints?(model = nil) ⇒ Bool, false

Validates if model has zones with valid heating temperature setpoints.
#height(pts = nil) ⇒ Float, 0.0

Returns ‘height’ of a set of OpenStudio 3D points.
#holds?(pts = nil, p1 = nil) ⇒ Bool, false

Returns true if an OpenStudio 3D point is part of a set of 3D points.
#holdsConstruction?(set = nil, bse = nil, gr = false, ex = false, tp = "") ⇒ Bool, false

Validates if a default construction set holds a base construction.
#insulatingLayer(lc = nil) ⇒ Hash

Identifies a layered construction’s (opaque) insulating layer.
#lineIntersects?(l = [], s = []) ⇒ Bool, false

Validates whether 3D line segment intersects 3D segments (e.g. polygon).
#maxHeatScheduledSetpoint(zone = nil) ⇒ Hash

Returns MAX zone heating temperature schedule setpoint [°C] and whether zone has an active dual setpoint thermostat.
#medialBox(pts = nil) ⇒ OpenStudio::Point3dVector

Generates a BLC box bounded within a triangle (midpoint theorem).
#midpoint(p1 = nil, p2 = nil) ⇒ OpenStudio::Point3d^?

Returns midpoint coordinates of line segment.
#minCoolScheduledSetpoint(zone = nil) ⇒ Hash

Returns MIN zone cooling temperature schedule setpoint [°C] and whether zone has an active dual setpoint thermostat.
#nearest(pts = nil, p01 = nil) ⇒ Integer^?

Returns OpenStudio 3D point (in a set) nearest to a point of reference, e.g.
#nextUp(pts = nil, pt = nil) ⇒ OpenStudio::Point3d^?

Returns next sequential point in an OpenStudio 3D point vector.
#offset(p1 = nil, w = 0, v = 0) ⇒ OpenStudio::Point3dVector

Generates offset vertices (by width) for a 3- or 4-sided, convex polygon.
#outline(a = [], bfr = 0, flat = true) ⇒ OpenStudio::Point3dVector

Generates a ULC OpenStudio 3D point vector (a bounding box) that surrounds multiple (smaller) OpenStudio 3D point vectors.
#overlap(p1 = nil, p2 = nil, flat = false) ⇒ OpenStudio::Point3dVector

Returns intersection of overlapping polygons, empty if non intersecting.
#overlaps?(p1 = nil, p2 = nil, flat = false) ⇒ Bool, false

Determines whether OpenStudio polygons overlap.
#parallel?(p1 = nil, p2 = nil) ⇒ Bool, false

Validates whether 2 polygons are parallel, regardless of their direction.
#plenum?(space = nil) ⇒ Bool, false

Validates whether a space is an indirectly-conditioned plenum.
#pointAlongSegment?(p0 = nil, sg = []) ⇒ Bool, false

Validates whether a 3D point lies ~along a 3D point segment, i.e.
#pointAlongSegments?(p0 = nil, sgs = []) ⇒ Bool, false

Validates whether a 3D point lies anywhere ~along a set of 3D point segments, i.e.
#pointWithinPolygon?(p0 = nil, s = [], entirely = false) ⇒ Bool, false

Validates whether 3D point is within a 3D polygon.
#poly(pts = nil, vx = false, uq = false, co = false, tt = false, sq = :no) ⇒ OpenStudio::Point3dVector

Returns an OpenStudio 3D point vector as basis for a valid OpenStudio 3D polygon.
#rectangular?(pts = nil) ⇒ Bool, false

Validates whether an OpenStudio polygon is a rectangle (4x sides + 2x diagonals of equal length, meeting at midpoints).
#refrigerated?(space = nil) ⇒ Bool, false

Validates whether a space can be considered as REFRIGERATED.
#roof?(pts = nil) ⇒ Bool, false

Validates whether a polygon can be considered a valid ‘roof’ surface, as per ASHRAE 90.1 & Canadian NECBs, i.e.
#rsi(lc = nil, film = 0.0, t = 0.0) ⇒ Float, 0.0

Returns a construction’s ‘standard calc’ thermal resistance (m2•K/W), which includes air film resistances.
#same?(s1 = nil, s2 = nil, indexed = true) ⇒ Bool, false

Returns true if 2 sets of OpenStudio 3D points are nearly equal.
#scalar(v = OpenStudio::Vector3d.new, m = 0) ⇒ OpenStudio::Vector3d

Returns a scalar product of an OpenStudio Vector3d.
#scheduleCompactMinMax(sched = nil) ⇒ Hash

Returns MIN/MAX values of a schedule (compact).
#scheduleConstantMinMax(sched = nil) ⇒ Hash

Returns MIN/MAX values of a schedule (constant).
#scheduleIntervalMinMax(sched = nil) ⇒ Hash

Returns MIN/MAX values for schedule (interval).
#scheduleRulesetMinMax(sched = nil) ⇒ Hash

Returns MIN/MAX values of a schedule (ruleset).
#segment?(pts = nil) ⇒ Bool, false

Determines if a set of 3D points if a valid segment.
#semiheated?(space = nil) ⇒ Bool, false

Validates whether a space can be considered as SEMIHEATED as per NECB 2020 1.2.1.2.
#setpoints(space = nil) ⇒ Hash

Retrieves a space’s (implicit or explicit) heating/cooling setpoints.
#sloped?(pts = nil) ⇒ Bool, false

Validates whether surface can be considered ‘sloped’ (i.e. not ~flat, as per OpenStudio Utilities’ “alignZPrime”).
#spandrel?(s = nil) ⇒ Bool, false

Validates whether opaque surface can be considered as a curtain wall (or similar technology) spandrel, regardless of construction layers, by looking up AdditionalProperties or its identifier.
#square?(pts = nil) ⇒ Bool, false

Validates whether an OpenStudio polygon is a square (rectangular, 4x ~equal sides).
#standardOpaqueLayers?(lc = nil) ⇒ Bool, false

Validates if every material in a layered construction is standard & opaque.
#thickness(lc = nil) ⇒ Float, 0.0

Returns total (standard opaque) layered construction thickness (m).
#to_p3Dv(pts = nil) ⇒ OpenStudio::Point3dVector

Returns OpenStudio 3D points as an OpenStudio point vector, validating points in the process (if Array).
#toToplit(spaces = [], opts = {}) ⇒ Array<OpenStudio::Model::Space>

Preselects ideal spaces to toplight, based on ‘addSkylights’ options and key building model geometry attributes.
#transforms(group = nil) ⇒ Hash

Returns OpenStudio site/space transformation & rotation angle [0,2PI) rads.
#triad?(pts = nil) ⇒ Bool, false

Determines if a set of 3D points if a valid triad.
#triadBox(pts = nil) ⇒ Set<OpenStudio::Point3D>

Generates a BLC box from a triad (3D points).
#trueNormal(s = nil, r = 0) ⇒ OpenStudio::Vector3d^?

Returns the site/true outward normal vector of a surface.
#ulc(pts = nil) ⇒ OpenStudio::Point3dVector

Returns OpenStudio 3D points (min 3x) conforming to an UpperLeftCorner (ULC) convention.
#unconditioned?(space = nil) ⇒ Bool, false

Validates if a space is UNCONDITIONED.
#verticalPlane(p1 = nil, p2 = nil) ⇒ OpenStudio::Plane^?

Returns a vertical 3D plane from 2x 3D points, right-hand rule.
#vestibule?(space = nil) ⇒ Bool, false

Validates whether space is a vestibule.
#width(pts = nil) ⇒ Float, 0.0

Returns ‘width’ of a set of OpenStudio 3D points.
#xyz?(pts = nil, axs = :z, val = 0) ⇒ Bool, false

Validates whether 3D points share X, Y or Z coordinates.

Class Method Details

.extended(base) ⇒ `Object`

Callback when other modules extend OSlg

Parameters:

base (Object) —

instance or class object



7778
7779
7780

# File 'lib/osut/utils.rb', line 7778

def self.extended(base)
  base.send(:include, self)
end

Instance Method Details

#addSkyLights(spaces = [], opts = {}) ⇒ `Float`

Adds skylights to toplight selected OpenStudio (occupied, conditioned) spaces, based on requested skylight area, or a skylight-to-roof ratio (SRR%). If the user selects 0m2 as the requested :area (or 0 as the requested :srr), while setting the option :clear as true, the method simply purges all pre-existing roof fenestrated subsurfaces of selected spaces, and exits while returning 0 (without logging an error or warning). Pre-existing skylight wells are not cleared however. Pre-toplit spaces are otherwise ignored. Boolean options :attic, :plenum, :sloped and :sidelit further restrict candidate spaces to toplight. If applicable, options :attic and :plenum add skylight wells. Option :patterns restricts preset skylight allocation layouts in order of preference; if left empty, all preset patterns are considered, also in order of preference (see examples).

Examples:

(a) consider 2D array of individual skylights, e.g. n(1.22m x 1.22m)

opts[:patterns] = ["array"]

(b) consider ‘a’, then array of 1x(size) x n(size) skylight strips

opts[:patterns] = ["array", "strips"]

Parameters:

spaces (Array<OpenStudio::Model::Space>) (defaults to: []) —

space(s) to toplight
opts (Hash) (defaults to: {}) —

requested skylight attributes

Options Hash (opts):

:area (#to_f) —

overall skylight area
:srr (#to_f) —

skylight-to-roof ratio (0.00, 0.90]
:size (#to_f) — default: 1.22 —

template skylight width/depth (min 0.4m)
:frame (#frameWidth) — default: nil —

OpenStudio Frame & Divider (optional)
:clear (Bool) — default: true —

whether to first purge existing skylights
:ration (Bool) — default: true —

finer selection of candidates to toplight
:sidelit (Bool) — default: true —

whether to consider sidelit spaces
:sloped (Bool) — default: true —

whether to consider sloped roof surfaces
:plenum (Bool) — default: true —

whether to consider plenum wells
:attic (Bool) — default: true —

whether to consider attic wells
:patterns (Array<#to_s>) —

requested skylight allocation (3x)

Returns:

(Float) —

returns gross roof area if successful (see logs if 0m2)

# File 'lib/osut/utils.rb', line 6234

def addSkyLights(spaces = [], opts = {})
  mth   = "OSut::#{__callee__}"
  clear = true
  srr   = nil
  area  = nil
  frame = nil   # FrameAndDivider object
  f     = 0.0   # FrameAndDivider frame width
  gap   = 0.1   # min 2" around well (2x == 4"), as well as max frame width
  gap2  = 0.2   # 2x gap
  gap4  = 0.4   # minimum skylight 16" width/depth (excluding frame width)
  bfr   = 0.005 # minimum array perimeter buffer (no wells)
  w     = 1.22  # default 48" x 48" skylight base
  w2    = w * w # m2

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Excerpts of ASHRAE 90.1 2022 definitions:
  #
  # "ROOF":
  #
  #   "the upper portion of the building envelope, including opaque areas and
  #   fenestration, that is horizontal or tilted at an angle of less than 60
  #   degrees from horizontal. For the purposes of determining building
  #   envelope requirements, the classifications are defined as follows
  #   (inter alia):
  #
  #     - attic and other roofs: all other roofs, including roofs with
  #       insulation ENTIRELY BELOW (inside of) the roof structure (i.e.,
  #       attics, cathedral ceilings, and single-rafter ceilings), roofs with
  #       insulation both above and BELOW the roof structure, and roofs
  #       without insulation but excluding metal building roofs. [...]"
  #
  # "ROOF AREA, GROSS":
  #
  #   "the area of the roof measured from the EXTERIOR faces of walls or from
  #   the centerline of party walls."
  #
  #
  # For the simple case below (steep 4-sided hip roof, UNENCLOSED ventilated
  # attic), 90.1 users typically choose between either:
  #   1. modelling the ventilated attic explicitly, or
  #   2. ignoring the ventilated attic altogether.
  #
  # If skylights were added to the model, option (1) would require one or more
  # skylight wells (light shafts leading to occupied spaces below), with
  # insulated well walls separating CONDITIONED spaces from an UNENCLOSED,
  # UNCONDITIONED space (i.e. attic).
  #
  # Determining which roof surfaces (or which portion of roof surfaces) need
  # to be considered when calculating "GROSS ROOF AREA" may be subject to some
  # interpretation. From the above definitions:
  #
  #   - the uninsulated, tilted hip-roof attic surfaces are considered "ROOF"
  #     surfaces, provided they 'shelter' insulation below (i.e. insulated
  #     attic floor).
  #   - however, only the 'projected' portion of such "ROOF" surfaces, i.e.
  #     areas between axes AA` and BB` (along exterior walls)) would be
  #     considered.
  #   - the portions above uninsulated soffits (illustrated on the right)
  #     would be excluded from the "GROSS ROOF AREA" as they are beyond the
  #     exterior wall projections.
  #
  #     A         B
  #     |         |
  #      _________
  #     /          \                  /|        |\
  #    /            \                / |        | \
  #   /_  ________  _\    = >       /_ |        | _\   ... excluded portions
  #     |          |
  #     |__________|
  #     .          .
  #     A`         B`
  #
  # If the unoccupied space (directly under the hip roof) were instead an
  # INDIRECTLY-CONDITIONED plenum (not an attic), then there would be no need
  # to exclude portions of any roof surface: all plenum roof surfaces (in
  # addition to soffit surfaces) would need to be insulated). The method takes
  # such circumstances into account, which requires vertically casting of
  # surfaces onto others, as well as overlap calculations. If successful, the
  # method returns the "GROSS ROOF AREA" (in m2), based on the above rationale.
  #
  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Excerpts of similar NECB requirements (unchanged from 2011 through 2020):
  #
  #   3.2.1.4. 2). "The total skylight area shall be less than 2% of the GROSS
  #   ROOF AREA as determined in Article 3.1.1.6." (5% in earlier versions)
  #
  #   3.1.1.6. 5). "In the calculation of allowable skylight area, the GROSS
  #   ROOF AREA shall be calculated as the sum of the areas of insulated
  #   roof including skylights."
  #
  # There are NO additional details or NECB appendix notes on the matter. It
  # is unclear if the NECB's looser definition of GROSS ROOF AREA includes
  # (uninsulated) sloped roof surfaces above (insulated) flat ceilings (e.g.
  # attics), as with 90.1. It would be definitely odd if it didn't. For
  # instance, if the GROSS ROOF AREA were based on insulated ceiling surfaces,
  # there would be a topological disconnect between flat ceiling and sloped
  # skylights above. Should NECB users first 'project' (sloped) skylight rough
  # openings onto flat ceilings when calculating SRR%? Without much needed
  # clarification, the (clearer) 90.1 rules equally apply here to NECB cases.

  # If skylight wells are indeed required, well wall edges are always vertical
  # (i.e. never splayed), requiring a vertical ray.
  origin = OpenStudio::Point3d.new(0,0,0)
  zenith = OpenStudio::Point3d.new(0,0,1)
  ray    = zenith - origin

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Accept a single 'OpenStudio::Model::Space' (vs an array of spaces).
  if spaces.respond_to?(:spaceType) || spaces.respond_to?(:to_a)
    spaces = spaces.respond_to?(:to_a) ? spaces.to_a : [spaces]
    spaces = spaces.select { |space| space.respond_to?(:spaceType) }
    spaces = spaces.select { |space| space.partofTotalFloorArea }
    spaces = spaces.reject { |space| unconditioned?(space) }
    return empty("spaces", mth, DBG, 0) if spaces.empty?
  else
    return mismatch("spaces", spaces, Array, mth, DBG, 0)
  end

  mdl = spaces.first.model

  # Exit if mismatched or invalid options.
  return mismatch("opts", opts, Hash, mth, DBG, 0) unless opts.is_a?(Hash)

  # Validate Frame & Divider object, if provided.
  if opts.key?(:frame)
    frame = opts[:frame]

    if frame.respond_to?(:frameWidth)
      frame = nil if v < 321
      frame = nil if f.frameWidth.round(2) < 0
      frame = nil if f.frameWidth.round(2) > gap

      f = f.frameWidth                            if frame
      log(WRN, "Skip Frame&Divider (#{mth})") unless frame
    else
      frame = nil
      log(ERR, "Skip invalid Frame&Divider object (#{mth})")
    end
  end

  # Validate skylight size, if provided.
  if opts.key?(:size)
    if opts[:size].respond_to?(:to_f)
      w  = opts[:size].to_f
      w2 = w * w
      return invalid(size, mth, 0, ERR, 0) if w.round(2) < gap4
    else
      return mismatch("size", opts[:size], Numeric, mth, DBG, 0)
    end
  end

  f2  = 2 * f
  w0  = w + f2
  w02 = w0 * w0
  wl  = w0 + gap
  wl2 = wl * wl

  # Validate requested skylight-to-roof ratio (or overall area).
  if opts.key?(:area)
    if opts[:area].respond_to?(:to_f)
      area = opts[:area].to_f
      log(WRN, "Area reset to 0.0m2 (#{mth})") if area < 0
    else
      return mismatch("area", opts[:area], Numeric, mth, DBG, 0)
    end
  elsif opts.key?(:srr)
    if opts[:srr].respond_to?(:to_f)
      srr = opts[:srr].to_f
      log(WRN, "SRR (#{srr.round(2)}) reset to 0% (#{mth})")  if srr < 0
      log(WRN, "SRR (#{srr.round(2)}) reset to 90% (#{mth})") if srr > 0.90
      srr = srr.clamp(0.00, 0.10)
    else
      return mismatch("srr", opts[:srr], Numeric, mth, DBG, 0)
    end
  else
    return hashkey("area", opts, :area, mth, ERR, 0)
  end

  # Validate purge request, if provided.
  if opts.key?(:clear)
    clear = opts[:clear]

    unless [true, false].include?(clear)
      log(WRN, "Purging existing skylights by default (#{mth})")
      clear = true
    end
  end

  # Purge if requested.
  getRoofs(spaces).each { |s| s.subSurfaces.map(&:remove) } if clear

  # Safely exit, e.g. if strictly called to purge existing roof subsurfaces.
  return 0 if area && area.round(2) == 0
  return 0 if srr  &&  srr.round(2) == 0

  m2  = 0 # total existing skylight rough opening area
  rm2 = grossRoofArea(spaces) # excludes e.g. overhangs

  # Tally existing skylight rough opening areas.
  spaces.each do |space|
    m = space.multiplier

    facets(space, "Outdoors", "RoofCeiling").each do |roof|
      roof.subSurfaces.each do |sub|
        next unless fenestration?(sub)

        id  = sub.nameString
        xm2 = sub.grossArea

        if sub.allowWindowPropertyFrameAndDivider
          unless sub.windowPropertyFrameAndDivider.empty?
            fw   = sub.windowPropertyFrameAndDivider.get.frameWidth
            vec  = offset(sub.vertices, fw, 300)
            aire = OpenStudio.getArea(vec)

            if aire.empty?
              log(ERR, "Skipping '#{id}': invalid Frame&Divider (#{mth})")
            else
              xm2 = aire.get
            end
          end
        end

        m2 += xm2 * sub.multiplier * m
      end
    end
  end

  # Required skylight area to add.
  sm2 = area ? area : rm2 * srr - m2

  # Warn/skip if existing skylights exceed or ~roughly match targets.
  if sm2.round(2) < w02.round(2)
    if m2 > 0
      log(INF, "Skipping: existing skylight area > request (#{mth})")
      return rm2
    else
      log(INF, "Requested skylight area < min size (#{mth})")
    end
  elsif 0.9 * rm2.round(2) < sm2.round(2)
    log(INF, "Skipping: requested skylight area > 90% of GRA (#{mth})")
    return rm2
  end

  opts[:ration] = true unless opts.key?(:ration)

  # By default, seek ideal candidate spaces/roofs. Bail out if unsuccessful.
  unless opts[:ration] == false
    spaces = toToplit(spaces, opts)
    return rm2 if spaces.empty?
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # The method seeks to insert a skylight array within the largest rectangular
  # 'bounded box' that neatly 'fits' within a given roof surface. This equally
  # applies to any vertically-cast overlap between roof and plenum (or attic)
  # floor, which in turn generates skylight wells. Skylight arrays are
  # inserted from left-to-right & top-to-bottom (as illustrated below), once a
  # roof (or cast 3D overlap) is 'aligned' in 2D.
  #
  # Depending on geometric complexity (e.g. building/roof concavity,
  # triangulation), the total area of bounded boxes may be significantly less
  # than the calculated "GROSS ROOF AREA", which can make it challenging to
  # attain the requested skylight area. If :patterns are left unaltered, the
  # method will select those that maximize the likelihood of attaining the
  # requested target, to the detriment of spatial daylighting distribution.
  #
  # The default skylight module size is 1.22m x 1.22m (4' x 4'), which can be
  # overridden by the user, e.g. 2.44m x 2.44m (8' x 8'). However, skylight
  # sizes usually end up either contracted or inflated to exactly meet a
  # request skylight area or SRR%,
  #
  # Preset skylight allocation patterns (in order of precedence):
  #
  #    1. "array"
  #   _____________________
  #  |   _      _      _   |  - ?x columns ("cols") >= ?x rows (min 2x2)
  #  |  |_|    |_|    |_|  |  - SRR ~5% (1.22m x 1.22m), as illustrated
  #  |                     |  - SRR ~19% (2.44m x 2.44m)
  #  |   _      _      _   |  - +suitable for wide spaces (storage, retail)
  #  |  |_|    |_|    |_|  |  - ~1.4x height + skylight width 'ideal' rule
  #  |_____________________|  - better daylight distribution, many wells
  #
  #    2. "strips"
  #   _____________________
  #  |   _      _      _   |  - ?x columns (min 2), 1x row
  #  |  | |    | |    | |  |  - ~doubles %SRR ...
  #  |  | |    | |    | |  |  - SRR ~10% (1.22m x ?1.22m), as illustrated
  #  |  | |    | |    | |  |  - SRR ~19% (2.44m x ?1.22m)
  #  |  |_|    |_|    |_|  |  - ~roof monitor layout
  #  |_____________________|  - fewer wells
  #
  #    3. "strip"
  #    ____________________
  #   |                    |  - 1x column, 1x row (min 1x)
  #   |   ______________   |  - SRR ~11% (1.22m x ?1.22m)
  #   |  | ............ |  |  - SRR ~22% (2.44m x ?1.22m), as illustrated
  #   |  |______________|  |  - +suitable for elongated bounded boxes
  #   |                    |  - 1x well
  #   |____________________|
  #
  # @todo: Support strips/strip patterns along ridge of paired roof surfaces.
  layouts  = ["array", "strips", "strip"]
  patterns = []

  # Validate skylight placement patterns, if provided.
  if opts.key?(:patterns)
    if opts[:patterns].is_a?(Array)
      opts[:patterns].each_with_index do |pattern, i|
        pattern = trim(pattern).downcase

        if pattern.empty?
          invalid("pattern #{i+1}", mth, 0, ERR)
          next
        end

        patterns << pattern if layouts.include?(pattern)
      end
    else
      mismatch("patterns", opts[:patterns], Array, mth, DBG)
    end
  end

  patterns = layouts if patterns.empty?

  # The method first attempts to add skylights in ideal candidate spaces:
  #   - large roof surface areas (e.g. retail, classrooms ... not corridors)
  #   - not sidelit (favours core spaces)
  #   - having flat roofs (avoids sloped roofs)
  #   - neither under plenums, nor attics (avoids wells)
  #
  # This ideal (albeit stringent) set of conditions is "combo a".
  #
  # If the requested skylight area has not yet been achieved (after initially
  # applying "combo a"), the method decrementally drops selection criteria and
  # starts over, e.g.:
  #   - then considers sidelit spaces
  #   - then considers sloped roofs
  #   - then considers skylight wells
  #
  # A maximum number of skylights are allocated to roof surfaces matching a
  # given combo, all the while giving priority to larger roof areas. An error
  # message is logged if the target isn't ultimately achieved.
  #
  # Through filters, users may in advance restrict candidate roof surfaces:
  #   b. above occupied sidelit spaces ('false' restricts to core spaces)
  #   c. that are sloped ('false' restricts to flat roofs)
  #   d. above INDIRECTLY CONDITIONED spaces (e.g. plenums, uninsulated wells)
  #   e. above UNCONDITIONED spaces (e.g. attics, insulated wells)
  filters = ["a", "b", "bc", "bcd", "bcde"]

  # Prune filters, based on user-selected options.
  [:sidelit, :sloped, :plenum, :attic].each do |opt|
    next unless opts.key?(opt)
    next unless opts[opt] == false

    case opt
    when :sidelit then filters.map! { |f| f.include?("b") ? f.delete("b") : f }
    when :sloped  then filters.map! { |f| f.include?("c") ? f.delete("c") : f }
    when :plenum  then filters.map! { |f| f.include?("d") ? f.delete("d") : f }
    when :attic   then filters.map! { |f| f.include?("e") ? f.delete("e") : f }
    end
  end

  filters.reject! { |f| f.empty? }
  filters.uniq!

  # Remaining filters may be further pruned automatically after space/roof
  # processing, depending on geometry, e.g.:
  #  - if there are no sidelit spaces: filter "b" will be pruned away
  #  - if there are no sloped roofs  : filter "c" will be pruned away
  #  - if no plenums are identified  : filter "d" will be pruned away
  #  - if no attics are identified   : filter "e" will be pruned away

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Break down spaces (and connected spaces) into groups.
  sets     = [] # collection of skylight arrays to deploy
  rooms    = {} # occupied CONDITIONED spaces to toplight
  plenums  = {} # unoccupied (INDIRECTLY-) CONDITIONED spaces above rooms
  attics   = {} # unoccupied UNCONDITIONED spaces above rooms
  ceilings = {} # of occupied CONDITIONED space (if plenums/attics)

  # Candidate 'rooms' to toplit - excludes plenums/attics.
  spaces.each do |space|
    id = space.nameString

    if daylit?(space, false, true, false)
      log(WRN, "#{id} is already toplit, skipping (#{mth})")
      next
    end

    # When unoccupied spaces are involved (e.g. plenums, attics), the occupied
    # space (to toplight) may not share the same local transformation as its
    # unoccupied space(s) above. Fetching site transformation.
    t0 = transforms(space)
    next unless t0[:t]

    # Calculate space height.
    hMIN  = 10000
    hMAX  = 0
    surfs = facets(space)

    surfs.each { |surf| hMAX = [hMAX, surf.vertices.max_by(&:z).z].max }
    surfs.each { |surf| hMIN = [hMIN, surf.vertices.min_by(&:z).z].min }

    h = hMAX - hMIN

    unless h > 0
      log(ERR, "#{id} height? #{hMIN.round(2)} vs #{hMAX.round(2)} (#{mth})")
      next
    end

    rooms[space]           = {}
    rooms[space][:t0     ] = t0[:t]
    rooms[space][:m      ] = space.multiplier
    rooms[space][:h      ] = h
    rooms[space][:roofs  ] = facets(space, "Outdoors", "RoofCeiling")
    rooms[space][:sidelit] = daylit?(space, true, false, false)

    # Fetch and process room-specific outdoor-facing roof surfaces, the most
    # basic 'set' to track, e.g.:
    #   - no skylight wells (i.e. no leader lines)
    #   - 1x skylight array per roof surface
    #   - no need to consider site transformation
    rooms[space][:roofs].each do |roof|
      next unless roof?(roof)

      box = boundedBox(roof)
      next if box.empty?

      bm2 = OpenStudio.getArea(box)
      next if bm2.empty?

      bm2 = bm2.get
      next if bm2.round(2) < w02.round(2)

      width = alignedWidth(box, true)
      depth = alignedHeight(box, true)
      next if width < wl * 3
      next if depth < wl

      # A set is 'tight' if the area of its bounded box is significantly
      # smaller than that of its roof. A set is 'thin' if the depth of its
      # bounded box is (too) narrow. If either is true, some geometry rules
      # may be relaxed to maximize allocated skylight area. Neither apply to
      # cases with skylight wells.
      tight = bm2 < roof.grossArea / 2 ? true : false
      thin  = depth.round(2) < (1.5 * wl).round(2) ? true : false

      set           = {}
      set[:box    ] = box
      set[:bm2    ] = bm2
      set[:tight  ] = tight
      set[:thin   ] = thin
      set[:roof   ] = roof
      set[:space  ] = space
      set[:m      ] = space.multiplier
      set[:sidelit] = rooms[space][:sidelit]
      set[:t0     ] = rooms[space][:t0]
      set[:t      ] = OpenStudio::Transformation.alignFace(roof.vertices)
      sets << set
    end
  end

  # Process outdoor-facing roof surfaces of plenums and attics above.
  rooms.each do |space, room|
    t0   = room[:t0]
    rufs = getRoofs(space) - room[:roofs]

    rufs.each do |ruf|
      next unless roof?(ruf)

      espace = ruf.space
      next if espace.empty?

      espace = espace.get
      next if espace.partofTotalFloorArea

      m = espace.multiplier

      if m != space.multiplier
        log(ERR, "Skipping #{ruf.nameString} (multiplier mismatch) (#{mth})")
        next
      end

      ti = transforms(espace)
      next unless ti[:t]

      ti   = ti[:t]
      rpts = ti * ruf.vertices

      # Process occupied room ceilings, as 1x or more are overlapping roof
      # surfaces above. Vertically cast, then fetch overlap.
      facets(space, "Surface", "RoofCeiling").each do |tile|
        tpts = t0 * tile.vertices
        ci0  = cast(tpts, rpts, ray)
        next if ci0.empty?

        olap = overlap(rpts, ci0)
        next if olap.empty?

        om2 = OpenStudio.getArea(olap)
        next if om2.empty?

        om2 = om2.get
        next if om2.round(2) < w02.round(2)

        box = boundedBox(olap)
        next if box.empty?

        # Adding skylight wells (plenums/attics) is contingent to safely
        # linking new base roof 'inserts' (as well as new ceiling ones)
        # through 'leader lines'. This requires an offset to ensure no
        # conflicts with roof or (ceiling) tile edges.
        #
        # @todo: Expand the method to factor in cases where simple 'side'
        #        cutouts can be supported (no need for leader lines), e.g.
        #        skylight strips along roof ridges.
        box = offset(box, -gap, 300)
        next if box.empty?

        bm2 = OpenStudio.getArea(box)
        next if bm2.empty?

        bm2 = bm2.get
        next if bm2.round(2) < wl2.round(2)

        width = alignedWidth(box, true)
        depth = alignedHeight(box, true)
        next if width < wl * 3
        next if depth < wl * 2

        # Vertically cast box onto tile below.
        cbox = cast(box, tpts, ray)
        next if cbox.empty?

        cm2 = OpenStudio.getArea(cbox)
        next if cm2.empty?

        cm2  = cm2.get
        box  = ti.inverse * box
        cbox = t0.inverse * cbox

        unless ceilings.key?(tile)
          floor = tile.adjacentSurface

          if floor.empty?
            log(ERR, "#{tile.nameString} adjacent floor? (#{mth})")
            next
          end

          floor = floor.get

          if floor.space.empty?
            log(ERR, "#{floor.nameString} space? (#{mth})")
            next
          end

          espce = floor.space.get

          unless espce == espace
            log(ERR, "#{espce.nameString} != #{espace.nameString}? (#{mth})")
            next
          end

          ceilings[tile]          = {}
          ceilings[tile][:roofs ] = []
          ceilings[tile][:space ] = space
          ceilings[tile][:floor ] = floor
        end

        ceilings[tile][:roofs] << ruf

        # Skylight set key:values are more detailed with suspended ceilings.
        # The overlap (:olap) remains in 'transformed' site coordinates (with
        # regards to the roof). The :box polygon reverts to attic/plenum space
        # coordinates, while the :cbox polygon is reset with regards to the
        # occupied space coordinates.
        set           = {}
        set[:olap   ] = olap
        set[:box    ] = box
        set[:cbox   ] = cbox
        set[:om2    ] = om2
        set[:bm2    ] = bm2
        set[:cm2    ] = cm2
        set[:tight  ] = false
        set[:thin   ] = false
        set[:roof   ] = ruf
        set[:space  ] = space
        set[:m      ] = space.multiplier
        set[:clng   ] = tile
        set[:t0     ] = t0
        set[:ti     ] = ti
        set[:t      ] = OpenStudio::Transformation.alignFace(ruf.vertices)
        set[:sidelit] = room[:sidelit]

        if unconditioned?(espace) # e.g. attic
          unless attics.key?(espace)
            attics[espace] = {ti: ti, m: m, bm2: 0, roofs: []}
          end

          attics[espace][:bm2  ] += bm2
          attics[espace][:roofs] << ruf

          set[:attic] = espace

          ceilings[tile][:attic] = espace
        else # e.g. plenum
          unless plenums.key?(espace)
            plenums[espace] = {ti: ti, m: m, bm2: 0, roofs: []}
          end

          plenums[espace][:bm2  ] += bm2
          plenums[espace][:roofs] << ruf

          set[:plenum] = espace

          ceilings[tile][:plenum] = espace
        end

        sets << set
        break # only 1x unique ruf/ceiling pair.
      end
    end
  end

  # Ensure uniqueness of plenum roofs.
  attics.values.each do |attic|
    attic[:roofs ].uniq!
    attic[:ridges] = getHorizontalRidges(attic[:roofs]) # @todo
  end

  plenums.values.each do |plenum|
    plenum[:roofs ].uniq!
    plenum[:ridges] = getHorizontalRidges(plenum[:roofs]) # @todo
  end

  # Regardless of the selected skylight arrangement pattern, the solution only
  # considers attic/plenum sets that can be successfully linked to leader line
  # anchors, for both roof and ceiling surfaces. First, attic/plenum roofs.
  [attics, plenums].each do |greniers|
    k = greniers == attics ? :attic : :plenum

    greniers.each do |spce, grenier|
      grenier[:roofs].each do |roof|
        sts = sets

        sts = sts.select { |st| st.key?(k) }
        sts = sts.select { |st| st.key?(:box) }
        sts = sts.select { |st| st.key?(:bm2) }
        sts = sts.select { |st| st.key?(:roof) }
        sts = sts.select { |st| st.key?(:space) }
        sts = sts.select { |st| st[k    ] == spce }
        sts = sts.select { |st| st[:roof] == roof }
        next if sts.empty?

        sts = sts.sort_by { |st| st[:bm2] }.reverse

        genAnchors(roof, sts, :box)
      end
    end
  end

  # Delete voided sets.
  sets.reject! { |set| set.key?(:void) }

  # Repeat leader line loop for ceilings.
  ceilings.each do |tile, ceiling|
    k = ceiling.key?(:attic) ? :attic : :plenum
    next unless ceiling.key?(k)

    space = ceiling[:space]
    spce  = ceiling[k]
    next unless ceiling.key?(:roofs)
    next unless rooms.key?(space)

    stz = []

    ceiling[:roofs].each do |roof|
      sts = sets

      sts = sts.select { |st| st.key?(k) }
      sts = sts.select { |st| st.key?(:cbox) }
      stz = stz.select { |st| st.key?(:cm2) }
      sts = sts.select { |st| st.key?(:roof) }
      sts = sts.select { |st| st.key?(:clng) }
      sts = sts.select { |st| st.key?(:space) }
      sts = sts.select { |st| st[k     ] == spce }
      sts = sts.select { |st| st[:roof ] == roof }
      sts = sts.select { |st| st[:clng ] == tile }
      sts = sts.select { |st| st[:space] == space }
      next unless sts.size == 1

      stz << sts.first
    end

    next if stz.empty?

    stz = stz.sort_by { |st| st[:cm2] }.reverse
    genAnchors(tile, stz, :cbox)
  end

  # Delete voided sets.
  sets.reject! { |set| set.key?(:void) }

  return empty("sets", mth, WRN, rm2) if sets.empty?

  # Sort sets, from largest to smallest bounded box area.
  sets = sets.sort_by { |st| st[:bm2] * st[:m] }.reverse

  # Any sidelit and/or sloped roofs being targeted?
  # @todo: enable double-ridged, sloped roofs have double-sloped
  #        skylights/wells (patterns "strip"/"strips").
  sidelit = sets.any? { |set| set[:sidelit] }
  sloped  = sets.any? { |set| set[:sloped ] }

  # Average sandbox area + revised 'working' SRR%.
  sbm2 = sets.map { |set| set[:bm2] }.reduce(:+)
  avm2 = sbm2 / sets.size
  srr2 = sm2 / sets.size / avm2

  # Precalculate skylight rows + cols, for each selected pattern. In the case
  # of 'cols x rows' arrays of skylights, the method initially overshoots
  # with regards to 'ideal' skylight placement, e.g.:
  #
  #   aceee.org/files/proceedings/2004/data/papers/SS04_Panel3_Paper18.pdf
  #
  # Skylight areas are subsequently contracted to strictly meet the target.
  sets.each_with_index do |set, i|
    thin   = set[:thin ]
    tight  = set[:tight]
    factor = tight ? 1.75 : 1.25
    well   = set.key?(:clng)
    space  = set[:space]
    room   = rooms[space]
    h      = room[:h]
    width  = alignedWidth( set[:box], true)
    depth  = alignedHeight(set[:box], true)
    barea  = set.key?(:om2) ? set[:om2] : set[:bm2]
    rtio   = barea / avm2
    skym2  = srr2 * barea * rtio

    # Flag set if too narrow/shallow to hold a single skylight.
    if well
      if width.round(2) < wl.round(2)
        log(WRN, "set #{i+1} well: Too narrow (#{mth})")
        set[:void] = true
        next
      end

      if depth.round(2) < wl.round(2)
        log(WRN, "set #{i+1} well: Too shallow (#{mth})")
        set[:void] = true
        next
      end
    else
      if width.round(2) < w0.round(2)
        log(WRN, "set #{i+1}: Too narrow (#{mth})")
        set[:void] = true
        next
      end

      if depth.round(2) < w0.round(2)
        log(WRN, "set #{i+1}: Too shallow (#{mth})")
        set[:void] = true
        next
      end
    end

    # Estimate number of skylight modules per 'pattern'. Default spacing
    # varies based on bounded box size (i.e. larger vs smaller rooms).
    patterns.each do |pattern|
      cols = 1
      rows = 1
      wx   = w0
      wy   = w0
      wxl  = well ? wl : nil
      wyl  = well ? wl : nil
      dX   = nil
      dY   = nil

      case pattern
      when "array" # min 2x cols x min 2x rows
        cols = 2
        rows = 2
        next if thin

        if tight
          sp = 1.4 * h / 2
          lx = width - cols * wx
          ly = depth - rows * wy
          next if lx.round(2) < sp.round(2)
          next if ly.round(2) < sp.round(2)

          cols = ((width - wx) / (wx + sp)).round(2).to_i + 1
          rows = ((depth - wy) / (wy + sp)).round(2).to_i + 1
          next if cols < 2
          next if rows < 2

          dX = bfr + f
          dY = bfr + f
        else
          sp = 1.4 * h
          lx = well ? (width - cols * wxl) / cols : (width - cols * wx) / cols
          ly = well ? (depth - rows * wyl) / rows : (depth - rows * wy) / rows
          next if lx.round(2) < sp.round(2)
          next if ly.round(2) < sp.round(2)

          if well
            cols = (width / (wxl + sp)).round(2).to_i
            rows = (depth / (wyl + sp)).round(2).to_i
          else
            cols = (width / (wx + sp)).round(2).to_i
            rows = (depth / (wy + sp)).round(2).to_i
          end

          next if cols < 2
          next if rows < 2

          ly = well ? (depth - rows * wyl) / rows : (depth - rows * wy) / rows
          dY = ly / 2
        end

        # Default allocated skylight area. If undershooting, inflate skylight
        # width/depth (with reduced spacing). For geometrically-constrained
        # cases, undershooting means not reaching 1.75x the required target.
        # Otherwise, undershooting means not reaching 1.25x the required
        # target. Any consequent overshooting is later corrected.
        tm2 = wx * cols * wy * rows

        # Inflate skylight width/depth (and reduce spacing) to reach target.
        if tm2.round(2) < factor * skym2.round(2)
          ratio2 = 1 + (factor * skym2 - tm2) / tm2
          ratio  = Math.sqrt(ratio2)

          sp  = wl
          wx *= ratio
          wy *= ratio
          wxl = wx + gap if well
          wyl = wy + gap if well

          if tight
            lx = (width - 2 * (bfr + f) - cols * wx) / (cols - 1)
            ly = (depth - 2 * (bfr + f) - rows * wy) / (rows - 1)
            lx = lx.round(2) < sp.round(2) ? sp : lx
            ly = ly.round(2) < sp.round(2) ? sp : ly
            wx = (width - 2 * (bfr + f) - (cols - 1) * lx) / cols
            wy = (depth - 2 * (bfr + f) - (rows - 1) * ly) / rows
          else
            if well
              lx  = (width - cols * wxl) / cols
              ly  = (depth - rows * wyl) / rows
              lx  = lx.round(2) < sp.round(2) ? sp : lx
              ly  = ly.round(2) < sp.round(2) ? sp : ly
              wxl = (width - cols * lx) / cols
              wyl = (depth - rows * ly) / rows
              wx  = wxl - gap
              wy  = wyl - gap
              ly  = (depth - rows * wyl) / rows
            else
              lx  = (width - cols * wx) / cols
              ly  = (depth - rows * wy) / rows
              lx  = lx.round(2) < sp.round(2) ? sp : lx
              ly  = ly.round(2) < sp.round(2) ? sp : ly
              wx  = (width - cols * lx) / cols
              wy  = (depth - rows * ly) / rows
              ly  = (depth - rows * wy) / rows
            end

            dY = ly / 2
          end
        end
      when "strips" # min 2x cols x 1x row
        cols = 2

        if tight
          sp = h / 2
          dX = bfr + f
          lx = width - cols * wx
          next if lx.round(2) < sp.round(2)

          cols = ((width - wx) / (wx + sp)).round(2).to_i + 1
          next if cols < 2

          if thin
            dY = bfr + f
            wy = depth - 2 * dY
            next if wy.round(2) < gap4
          else
            ly = depth - wy
            next if ly.round(2) < wl.round(2)

            dY = ly / 2
          end
        else
          sp = h

          if well
            lx = (width - cols * wxl) / cols
            next if lx.round(2) < sp.round(2)

            cols = (width / (wxl + sp)).round(2).to_i
            next if cols < 2

            ly = depth - wyl
            dY = ly / 2
            next if ly.round(2) < wl.round(2)
          else
            lx = (width - cols * wx) / cols
            next if lx.round(2) < sp.round(2)

            cols = (width / (wx + sp)).round(2).to_i
            next if cols < 2

            if thin
              dY = bfr + f
              wy = depth - 2 * dY
              next if wy.round(2) < gap4
            else
              ly = depth - wy
              next if ly.round(2) < wl.round(2)

              dY = ly / 2
            end
          end
        end

        tm2 = wx * cols * wy

        # Inflate skylight depth to reach target.
        if tm2.round(2) < factor * skym2.round(2)
          sp = wl

          # Skip if already thin.
          unless thin
            ratio2 = 1 + (factor * skym2 - tm2) / tm2

            wy *= ratio2

            if well
              wyl = wy + gap
              ly  = depth - wyl
              ly  = ly.round(2) < sp.round(2) ? sp : ly
              wyl = depth - ly
              wy  = wyl - gap
            else
              ly = depth - wy
              ly = ly.round(2) < sp.round(2) ? sp : ly
              wy = depth - ly
            end

            dY = ly / 2
          end
        end

        tm2 = wx * cols * wy

        # Inflate skylight width (and reduce spacing) to reach target.
        if tm2.round(2) < factor * skym2.round(2)
          ratio2 = 1 + (factor * skym2 - tm2) / tm2

          wx *= ratio2
          wxl = wx + gap if well

          if tight
            lx = (width - 2 * (bfr + f) - cols * wx) / (cols - 1)
            lx = lx.round(2) < sp.round(2) ? sp : lx
            wx = (width - 2 * (bfr + f) - (cols - 1) * lx) / cols
          else
            if well
              lx  = (width - cols * wxl) / cols
              lx  = lx.round(2) < sp.round(2) ? sp : lx
              wxl = (width - cols * lx) / cols
              wx  = wxl - gap
            else
              lx  = (width - cols * wx) / cols
              lx  = lx.round(2) < sp.round(2) ? sp : lx
              wx  = (width - cols * lx) / cols
            end
          end
        end
      else # "strip" 1 (long?) row x 1 column
        if tight
          sp = gap4
          dX = bfr + f
          wx = width - 2 * dX
          next if wx.round(2) < sp.round(2)

          if thin
            dY = bfr + f
            wy = depth - 2 * dY
            next if wy.round(2) < sp.round(2)
          else
            ly = depth - wy
            dY = ly / 2
            next if ly.round(2) < sp.round(2)
          end
        else
          sp = wl
          lx = well ? width - wxl : width - wx
          ly = well ? depth - wyl : depth - wy
          dY = ly / 2
          next if lx.round(2) < sp.round(2)
          next if ly.round(2) < sp.round(2)
        end

        tm2 = wx * wy

        # Inflate skylight width (and reduce spacing) to reach target.
        if tm2.round(2) < factor * skym2.round(2)
          unless tight
            ratio2 = 1 + (factor * skym2 - tm2) / tm2

            wx *= ratio2

            if well
              wxl = wx + gap
              lx  = width - wxl
              lx  = lx.round(2) < sp.round(2) ? sp : lx
              wxl = width - lx
              wx  = wxl - gap
            else
              lx  = width - wx
              lx  = lx.round(2) < sp.round(2) ? sp : lx
              wx  = width - lx
            end
          end
        end

        tm2 = wx * wy

        # Inflate skylight depth to reach target. Skip if already tight thin.
        if tm2.round(2) < factor * skym2.round(2)
          unless thin
            ratio2 = 1 + (factor * skym2 - tm2) / tm2

            wy *= ratio2

            if well
              wyl = wy + gap
              ly  = depth - wyl
              ly  = ly.round(2) < sp.round(2) ? sp : ly
              wyl = depth - ly
              wy  = wyl - gap
            else
              ly = depth - wy
              ly = ly.round(2) < sp.round(2) ? sp : ly
              wy = depth - ly
            end

            dY = ly / 2
          end
        end
      end

      st         = {}
      st[:tight] = tight
      st[:cols ] = cols
      st[:rows ] = rows
      st[:wx   ] = wx
      st[:wy   ] = wy
      st[:wxl  ] = wxl
      st[:wyl  ] = wyl
      st[:dX   ] = dX if dX
      st[:dY   ] = dY if dY

      set[pattern] = st
    end

    set[:void] = true unless patterns.any? { |k| set.key?(k) }
  end

  # Delete voided sets.
  sets.reject! { |set| set.key?(:void) }
  return empty("sets (2)", mth, WRN, rm2) if sets.empty?

  # Final reset of filters.
  filters.map! { |f| f.include?("b") ? f.delete("b") : f } unless sidelit
  filters.map! { |f| f.include?("c") ? f.delete("c") : f } unless sloped
  filters.map! { |f| f.include?("d") ? f.delete("d") : f } if plenums.empty?
  filters.map! { |f| f.include?("e") ? f.delete("e") : f } if attics.empty?

  filters.reject! { |f| f.empty? }
  filters.uniq!

  # Initialize skylight area tally (to increment).
  skm2 = 0

  # Assign skylight pattern.
  filters.each do |filter|
    next if skm2.round(2) >= sm2.round(2)

    dm2 = sm2 - skm2 # differential (remaining skylight area to meet).
    sts = sets
    sts = sts.reject  { |st| st.key?(:pattern) }

    if filter.include?("a")
      # Start with the default (ideal) allocation selection:
        # - large roof surface areas (e.g. retail, classrooms not corridors)
        # - not sidelit (favours core spaces)
        # - having flat roofs (avoids sloped roofs)
        # - not under plenums, nor attics (avoids wells)
      sts = sts.reject { |st| st[:sidelit]   }
      sts = sts.reject { |st| st[:sloped ]   }
      sts = sts.reject { |st| st.key?(:clng) }
    else
      sts = sts.reject { |st| st[:sidelit]     } unless filter.include?("b")
      sts = sts.reject { |st| st[:sloped]      } unless filter.include?("c")
      sts = sts.reject { |st| st.key?(:plenum) } unless filter.include?("d")
      sts = sts.reject { |st| st.key?(:attic)  } unless filter.include?("e")
    end

    next if sts.empty?

    # Tally precalculated skylights per pattern (once filtered).
    fpm2 = {}

    patterns.each do |pattern|
      sts.each do |st|
        next unless st.key?(pattern)

        cols = st[pattern][:cols]
        rows = st[pattern][:rows]
        wx   = st[pattern][:wx  ]
        wy   = st[pattern][:wy  ]

        fpm2[pattern] = {m2: 0, tight: false} unless fpm2.key?(pattern)

        fpm2[pattern][:m2   ] += st[:m] * wx * wy * cols * rows
        fpm2[pattern][:tight] = true if st[:tight]
      end
    end

    pattern = nil
    next if fpm2.empty?

    # Favour (large) arrays if meeting residual target, unless constrained.
    if fpm2.keys.include?("array")
      if fpm2["array"][:m2].round(2) >= dm2.round(2)
        pattern = "array" unless fpm2[:tight]
      end
    end

    unless pattern
      fpm2   = fpm2.sort_by { |_, fm2| fm2[:m2] }.to_h
      min_m2 = fpm2.values.first[:m2]
      max_m2 = fpm2.values.last[:m2]

      if min_m2.round(2) >= dm2.round(2)
        # If not large array, then retain pattern generating smallest skylight
        # area if ALL patterns >= residual target (deterministic sorting).
        fpm2.keep_if { |_, fm2| fm2[:m2].round(2) == min_m2.round(2) }

        if fpm2.keys.include?("array")
          pattern = "array"
        elsif fpm2.keys.include?("strips")
          pattern = "strips"
        else fpm2.keys.include?("strip")
          pattern = "strip"
        end
      else
        # Pick pattern offering greatest skylight area (deterministic sorting).
        fpm2.keep_if { |_, fm2| fm2[:m2].round(2) == max_m2.round(2) }

        if fpm2.keys.include?("strip")
          pattern = "strip"
        elsif fpm2.keys.include?("strips")
          pattern = "strips"
        else fpm2.keys.include?("array")
          pattern = "array"
        end
      end
    end

    skm2 += fpm2[pattern][:m2]

    # Update matching sets.
    sts.each do |st|
      sets.each do |set|
        next unless set.key?(pattern)
        next unless st[:roof] == set[:roof]
        next unless same?(st[:box], set[:box])

        if st.key?(:clng)
          next unless set.key?(:clng)
          next unless st[:clng] == set[:clng]
        end

        set[:pattern] = pattern
        set[:cols   ] = set[pattern][:cols]
        set[:rows   ] = set[pattern][:rows]
        set[:w      ] = set[pattern][:wx  ]
        set[:d      ] = set[pattern][:wy  ]
        set[:w0     ] = set[pattern][:wxl ]
        set[:d0     ] = set[pattern][:wyl ]
        set[:dX     ] = set[pattern][:dX  ] if set[pattern][:dX]
        set[:dY     ] = set[pattern][:dY  ] if set[pattern][:dY]
      end
    end
  end

  # Delete incomplete sets (same as rejected if 'voided').
  sets.reject! { |set| set.key?(:void) }
  sets.select! { |set| set.key?(:pattern) }
  return empty("sets (3)", mth, WRN, rm2) if sets.empty?

  # Skylight size contraction if overshot (e.g. scale down by -13% if > +13%).
  # Applied on a surface/pattern basis: individual skylight sizes may vary
  # from one surface to the next, depending on respective patterns.

  # First, skip whole sets altogether if their total m2 < (skm2 - sm2). Only
  # considered if significant discrepancies vs average set skylight m2.
  sbm2 = 0

  sets.each do |set|
    sbm2 += set[:cols] * set[:w] * set[:rows] * set[:d] * set[:m]
  end

  avm2 = sbm2 / sets.size

  if skm2.round(2) > sm2.round(2)
    sets.reverse.each do |set|
      break unless skm2.round(2) > sm2.round(2)

      stm2 = set[:cols] * set[:w] * set[:rows] * set[:d] * set[:m]
      next unless stm2 < 0.75 * avm2
      next unless stm2.round(2) < (skm2 - sm2).round(2)

      skm2 -= stm2
      set[:void] = true
    end
  end

  sets.reject! { |set| set.key?(:void) }
  return empty("sets (4)", mth, WRN, rm2) if sets.empty?

  # Size contraction: round 1: low-hanging fruit.
  if skm2.round(2) > sm2.round(2)
    ratio2 = 1 - (skm2 - sm2) / skm2
    ratio  = Math.sqrt(ratio2)

    sets.each do |set|
      am2 = set[:cols] * set[:w] * set[:rows] * set[:d] * set[:m]
      xr  = set[:w]
      yr  = set[:d]

      if xr > w0
        xr = xr * ratio < w0 ? w0 : xr * ratio
      end

      if yr > w0
        yr = yr * ratio < w0 ? w0 : yr * ratio
      end

      xm2 = set[:cols] * xr * set[:rows] * yr * set[:m]
      next if xm2.round(2) == am2.round(2)

      set[:dY] += (set[:d] - yr) / 2
      set[:dX] += (set[:w] - xr) / 2 if set.key?(:dX)
      set[:w ]  = xr
      set[:d ]  = yr
      set[:w0]  = set[:w] + gap
      set[:d0]  = set[:d] + gap

      skm2 -= (am2 - xm2)
    end
  end

  # Size contraction: round 2: prioritize larger sets.
  adm2 = 0

  sets.each_with_index do |set, i|
    next if set[:w].round(2) <= w0
    next if set[:d].round(2) <= w0

    adm2 += set[:cols] * set[:w] * set[:rows] * set[:d] * set[:m]
  end

  if skm2.round(2) > sm2.round(2) && adm2.round(2) > sm2.round(2)
    ratio2 = 1 - (adm2 - sm2) / adm2
    ratio  = Math.sqrt(ratio2)

    sets.each do |set|
      next if set[:w].round(2) <= w0
      next if set[:d].round(2) <= w0

      am2 = set[:cols] * set[:w] * set[:rows] * set[:d] * set[:m]
      xr  = set[:w]
      yr  = set[:d]

      if xr > w0
        xr = xr * ratio < w0 ? w0 : xr * ratio
      end

      if yr > w0
        yr = yr * ratio < w0 ? w0 : yr * ratio
      end

      xm2 = set[:cols] * xr * set[:rows] * yr * set[:m]
      next if xm2.round(2) == am2.round(2)

      set[:dY] += (set[:d] - yr) / 2
      set[:dX] += (set[:w] - xr) / 2 if set.key?(:dX)
      set[:w ]  = xr
      set[:d ]  = yr
      set[:w0]  = set[:w] + gap
      set[:d0]  = set[:d] + gap

      skm2 -= (am2 - xm2)
      adm2 -= (am2 - xm2)
    end
  end

  # Size contraction: round 3: Resort to sizes < requested w0.
  if skm2.round(2) > sm2.round(2)
    ratio2 = 1 - (skm2 - sm2) / skm2
    ratio  = Math.sqrt(ratio2)

    sets.each do |set|
      break unless skm2.round(2) > sm2.round(2)

      am2 = set[:cols] * set[:w] * set[:rows] * set[:d] * set[:m]
      xr  = set[:w]
      yr  = set[:d]

      if xr > gap4
        xr = xr * ratio < gap4 ? gap4 : xr * ratio
      end

      if yr > gap4
        yr = yr * ratio < gap4 ? gap4 : yr * ratio
      end

      xm2 = set[:cols] * xr * set[:rows] * yr * set[:m]
      next if xm2.round(2) == am2.round(2)

      set[:dY] += (set[:d] - yr) / 2
      set[:dX] += (set[:w] - xr) / 2 if set.key?(:dX)
      set[:w ]  = xr
      set[:d ]  = yr
      set[:w0]  = set[:w] + gap
      set[:d0]  = set[:d] + gap

      skm2 -= (am2 - xm2)
    end
  end

  # Log warning if unable to entirely contract skylight dimensions.
  if skm2.round(2) > sm2.round(2)
    log(WRN, "Skylights slightly oversized (#{mth})")
  end

  # Generate skylight well vertices for roofs, attics & plenums.
  [attics, plenums].each do |greniers|
    k = greniers == attics ? :attic : :plenum

    greniers.each do |spce, grenier|
      grenier[:roofs].each do |roof|
        sts = sets
        sts = sts.select { |st| st.key?(k) }
        sts = sts.select { |st| st.key?(:pattern) }
        sts = sts.select { |st| st.key?(:clng) }
        sts = sts.select { |st| st.key?(:roof) }
        sts = sts.select { |st| st.key?(:space) }
        sts = sts.select { |st| st[:roof] == roof }
        sts = sts.select { |st| st[k    ] == spce }
        sts = sts.select { |st| st.key?(st[:pattern]) }
        sts = sts.select { |st| rooms.key?(st[:space]) }
        sts = sts.select { |st| st.key?(:ld) }
        sts = sts.select { |st| st[:ld].key?(roof) }
        next if sts.empty?

        # If successful, 'genInserts' returns extended ROOF surface vertices,
        # including leader lines to support cutouts. The method also generates
        # new roof inserts. See key:value pair :vts. The FINAL go/no-go is
        # contingent to successfully inserting corresponding room ceiling
        # inserts (vis-à-vis attic/plenum floor below).
        vz = genInserts(roof, sts)
        next if vz.empty?

        roof.setVertices(vz)
      end
    end
  end

  # Repeat for ceilings below attic/plenum floors.
  ceilings.each do |tile, ceiling|
    k = ceiling.key?(:attic) ? :attic : :plenum
    next unless ceiling.key?(k)
    next unless ceiling.key?(:roofs)

    greniers = ceiling.key?(:attic) ? attics : plenums
    space    = ceiling[:space]
    spce     = ceiling[k     ]
    floor    = ceiling[:floor]
    next unless rooms.key?(space)
    next unless greniers.key?(spce)

    room    = rooms[space]
    grenier = greniers[spce]
    ti      = grenier[:ti]
    t0      = room[:t0]
    stz     = []

    ceiling[:roofs].each do |roof|
      sts = sets

      sts = sts.select { |st| st.key?(k) }
      sts = sts.select { |st| st.key?(:pattern) }
      sts = sts.select { |st| st.key?(:clng) }
      sts = sts.select { |st| st.key?(:cm2) }
      sts = sts.select { |st| st.key?(:roof) }
      sts = sts.select { |st| st.key?(:space) }
      sts = sts.select { |st| st[:clng] == tile }
      sts = sts.select { |st| st[:roof] == roof }
      sts = sts.select { |st| st[k    ] == spce }
      sts = sts.select { |st| rooms.key?(st[:space]) }
      sts = sts.select { |st| st.key?(:ld) }
      sts = sts.select { |st| st.key?(:vtx) }
      sts = sts.select { |st| st.key?(:vts) }
      sts = sts.select { |st| st[:ld].key?(roof) }
      sts = sts.select { |st| st[:ld].key?(tile) }
      next unless sts.size == 1

      stz << sts.first
    end

    next if stz.empty?

    # Add new roof inserts & skylights for the (now) toplit space.
    stz.each_with_index do |st, i|
      sub         = {}
      sub[:type ] = "Skylight"
      sub[:frame] = frame if frame
      sub[:sill ] = gap / 2

      st[:vts].each do |id, vt|
        roof = OpenStudio::Model::Surface.new(t0.inverse * (ti * vt), mdl)
        roof.setSpace(space)
        roof.setName("#{id}:#{space.nameString}")

        # Generate well walls.
        vX = cast(roof, tile, ray)
        s0 = getSegments(t0 * roof.vertices)
        sX = getSegments(t0 * vX)

        s0.each_with_index do |sg, j|
          sg0 = sg.to_a
          sgX = sX[j].to_a
          vec = OpenStudio::Point3dVector.new
          vec << sg0.first
          vec << sg0.last
          vec << sgX.last
          vec << sgX.first

          v_grenier = ti.inverse * vec
          v_room    = (t0.inverse * vec).to_a.reverse

          grenier_wall = OpenStudio::Model::Surface.new(v_grenier, mdl)
          grenier_wall.setSpace(spce)
          grenier_wall.setName("#{id}:#{i}:#{j}:#{spce.nameString}")

          room_wall = OpenStudio::Model::Surface.new(v_room, mdl)
          room_wall.setSpace(space)
          room_wall.setName("#{id}:#{i}:#{j}:#{space.nameString}")

          grenier_wall.setAdjacentSurface(room_wall)
          room_wall.setAdjacentSurface(grenier_wall)
        end

        # Add individual skylights. Independently of the set layout (rows x
        # cols), individual roof inserts may be deeper than wider (or
        # vice-versa). Adapt skylight width vs depth accordingly.
        if st[:d].round(2) > st[:w].round(2)
          sub[:width ] = st[:d] - f2
          sub[:height] = st[:w] - f2
        else
          sub[:width ] = st[:w] - f2
          sub[:height] = st[:d] - f2
        end

        sub[:id] = roof.nameString
        addSubs(roof, sub, false, true, true)
      end
    end

    # Vertically-cast set roof :vtx onto ceiling.
    stz.each do |st|
      st[:cvtx] = t0.inverse * cast(ti * st[:vtx], t0 * tile.vertices, ray)
    end

    # Extended ceiling vertices.
    vertices = genExtendedVertices(tile, stz, :cvtx)
    next if vertices.empty?

    # Reset ceiling and adjacent floor vertices.
    tile.setVertices(vertices)
    floor.setVertices(ti.inverse * (t0 * vertices).to_a.reverse)
  end

  # Loop through 'direct' roof surfaces of rooms to toplit (no attics or
  # plenums). No overlaps, so no relative space coordinate adjustments.
  rooms.each do |space, room|
    room[:roofs].each do |roof|
      sets.each_with_index do |st, i|
        next unless st.key?(:roof)
        next unless st[:roof] == roof
        next     if st.key?(:clng)
        next unless st.key?(:box)
        next unless st.key?(:cols)
        next unless st.key?(:rows)
        next unless st.key?(:d)
        next unless st.key?(:w)
        next unless st.key?(:dY)

        w1 = st[:w ] - f2
        d1 = st[:d ] - f2
        dY = st[:dY]

        st[:rows].times.each do |j|
          sub            = {}
          sub[:type    ] = "Skylight"
          sub[:count   ] = st[:cols]
          sub[:width   ] = w1
          sub[:height  ] = d1
          sub[:frame   ] = frame if frame
          sub[:id      ] = "#{roof.nameString}:#{i}:#{j}"
          sub[:sill    ] = dY + j * (2 * dY + d1)
          sub[:r_buffer] = st[:dX] if st[:dX]
          sub[:l_buffer] = st[:dX] if st[:dX]

          addSubs(roof, sub, false, true, true)
        end
      end
    end
  end

  rm2
end

#addSubs(s = nil, subs = [], clear = false, bound = false, realign = false, bfr = 0.005) ⇒ `Bool`, `false`

Adds sub surfaces (e.g. windows, doors, skylights) to surface.

Parameters:

s (OpenStudio::Model::Surface) (defaults to: nil) —

a model surface
subs (Array<Hash>) (defaults to: []) —

requested attributes
clear (Bool) (defaults to: false) —

whether to remove current sub surfaces
bound (Bool) (defaults to: false) —

whether to add subs wrt surface’s bounded box
realign (Bool) (defaults to: false) —

whether to first realign bounded box
bfr (#to_f) (defaults to: 0.005) —

safety buffer, to maintain near other edges

Options Hash (subs):

:id (#to_s) —

identifier e.g. “Window 007”
:type (#to_s) — default: "FixedWindow" —

OpenStudio subsurface type
:count (#to_i) — default: 1 —

number of individual subs per array
:multiplier (#to_i) — default: 1 —

OpenStudio subsurface multiplier
:frame (#frameWidth) — default: nil —

OpenStudio frame & divider object
:assembly (#isFenestration) — default: nil —

OpenStudio construction
:ratio (#to_f) —

e.g. %FWR [0.0, 1.0]
:head (#to_f) — default: OSut::HEAD —

e.g. door height (incl frame)
:sill (#to_f) — default: OSut::SILL —

e.g. window sill (incl frame)
:height (#to_f) —

sill-to-head height
:width (#to_f) —

e.g. door width
:offset (#to_f) —

left-right centreline dX e.g. between doors
:centreline (#to_f) —

left-right dX (sub/array vs base)
:r_buffer (#to_f) —

gap between sub/array and right corner
:l_buffer (#to_f) —

gap between sub/array and left corner

Returns:

(Bool) —

whether addition is successful
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 5284

def addSubs(s = nil, subs = [], clear = false, bound = false, realign = false, bfr = 0.005)
  mth = "OSut::#{__callee__}"
  v   = OpenStudio.openStudioVersion.split(".").join.to_i
  cl1 = OpenStudio::Model::Surface
  cl2 = Array
  cl3 = Hash
  min = 0.050 # minimum ratio value ( 5%)
  max = 0.950 # maximum ratio value (95%)
  no  = false

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Exit if mismatched or invalid argument classes.
  sbs = subs.is_a?(cl3) ? [subs] : subs
  sbs = sbs.respond_to?(:to_a) ? sbs.to_a : []
  return mismatch("surface",  s, cl1, mth, DBG, no) unless s.is_a?(cl1)
  return mismatch("subs",  subs, cl2, mth, DBG, no)     if sbs.empty?
  return empty("surface points",      mth, DBG, no)     if poly(s).empty?

  subs = sbs
  nom  = s.nameString
  mdl  = s.model

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Purge existing sub surfaces?
  unless [true, false].include?(clear)
    log(WRN, "#{nom}: Keeping existing sub surfaces (#{mth})")
    clear = false
  end

  s.subSurfaces.map(&:remove) if clear

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Add sub surfaces with respect to base surface's bounded box? This is
  # often useful (in some cases necessary) with irregular or concave surfaces.
  # If true, sub surface parameters (e.g. height, offset, centreline) no
  # longer apply to the original surface 'bounding' box, but instead to its
  # largest 'bounded' box. This can be combined with the 'realign' parameter.
  unless [true, false].include?(bound)
    log(WRN, "#{nom}: Ignoring bounded box (#{mth})")
    bound = false
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Force re-alignment of base surface (or its 'bounded' box)? False by
  # default (ideal for vertical/tilted walls & sloped roofs). If set to true
  # for a narrow wall for instance, an array of sub surfaces will be added
  # from bottom to top (rather from left to right).
  unless [true, false].include?(realign)
    log(WRN, "#{nom}: Ignoring realignment (#{mth})")
    realign = false
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Ensure minimum safety buffer.
  if bfr.respond_to?(:to_f)
    bfr = bfr.to_f
    return negative("safety buffer", mth, ERR, no) if bfr.round(2) < 0

    msg = "Safety buffer < 5mm may generate invalid geometry (#{mth})"
    log(WRN, msg) if bfr.round(2) < 0.005
  else
    log(ERR, "Setting safety buffer to 5mm (#{mth})")
    bfr = 0.005
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Allowable sub surface types ... & Frame&Divider enabled
  #   - "FixedWindow"             | true
  #   - "OperableWindow"          | true
  #   - "Door"                    | false
  #   - "GlassDoor"               | true
  #   - "OverheadDoor"            | false
  #   - "Skylight"                | false if v < 321
  #   - "TubularDaylightDome"     | false
  #   - "TubularDaylightDiffuser" | false
  type  = "FixedWindow"
  types = OpenStudio::Model::SubSurface.validSubSurfaceTypeValues
  stype = s.surfaceType # Wall, RoofCeiling or Floor

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  t   = OpenStudio::Transformation.alignFace(s.vertices)
  s0  = poly(s, false, false, false, t, :ulc)
  s00 = nil

  # Adapt sandbox if user selects to 'bound' and/or 'realign'.
  if bound
    box = boundedBox(s0)

    if realign
      s00 = getRealignedFace(box, true)
      return invalid("bound realignment", mth, 0, DBG, false) unless s00[:set]
    end
  elsif realign
    s00 = getRealignedFace(s0, false)
    return invalid("unbound realignment", mth, 0, DBG, false) unless s00[:set]
  end

  max_x = s00 ? width( s00[:set]) :  width(s0)
  max_y = s00 ? height(s00[:set]) : height(s0)
  mid_x = max_x / 2
  mid_y = max_y / 2

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Assign default values to certain sub keys (if missing), +more validation.
  subs.each_with_index do |sub, index|
    return mismatch("sub", sub, cl4, mth, DBG, no) unless sub.is_a?(cl3)

    # Required key:value pairs (either set by the user or defaulted).
    sub[:frame     ] = nil  unless sub.key?(:frame     )
    sub[:assembly  ] = nil  unless sub.key?(:assembly  )
    sub[:count     ] = 1    unless sub.key?(:count     )
    sub[:multiplier] = 1    unless sub.key?(:multiplier)
    sub[:id        ] = ""   unless sub.key?(:id        )
    sub[:type      ] = type unless sub.key?(:type      )
    sub[:type      ] = trim(sub[:type])
    sub[:id        ] = trim(sub[:id])
    sub[:type      ] = type                   if sub[:type].empty?
    sub[:id        ] = "OSut:#{nom}:#{index}" if sub[:id  ].empty?
    sub[:count     ] = 1 unless sub[:count     ].respond_to?(:to_i)
    sub[:multiplier] = 1 unless sub[:multiplier].respond_to?(:to_i)
    sub[:count     ] = sub[:count     ].to_i
    sub[:multiplier] = sub[:multiplier].to_i
    sub[:count     ] = 1 if sub[:count     ] < 1
    sub[:multiplier] = 1 if sub[:multiplier] < 1

    id = sub[:id]

    # If sub surface type is invalid, log/reset. Additional corrections may
    # be enabled once a sub surface is actually instantiated.
    unless types.include?(sub[:type])
      log(WRN, "Reset invalid '#{id}' type to '#{type}' (#{mth})")
      sub[:type] = type
    end

    # Log/ignore (optional) frame & divider object.
    unless sub[:frame].nil?
      if sub[:frame].respond_to?(:frameWidth)
        sub[:frame] = nil if sub[:type] == "Skylight" && v < 321
        sub[:frame] = nil if sub[:type] == "Door"
        sub[:frame] = nil if sub[:type] == "OverheadDoor"
        sub[:frame] = nil if sub[:type] == "TubularDaylightDome"
        sub[:frame] = nil if sub[:type] == "TubularDaylightDiffuser"
        log(WRN, "Skip '#{id}' FrameDivider (#{mth})") if sub[:frame].nil?
      else
        sub[:frame] = nil
        log(WRN, "Skip '#{id}' invalid FrameDivider object (#{mth})")
      end
    end

    # The (optional) "assembly" must reference a valid OpenStudio
    # construction base, to explicitly assign to each instantiated sub
    # surface. If invalid, log/reset/ignore. Additional checks are later
    # activated once a sub surface is actually instantiated.
    unless sub[:assembly].nil?
      unless sub[:assembly].respond_to?(:isFenestration)
        log(WRN, "Skip invalid '#{id}' construction (#{mth})")
        sub[:assembly] = nil
      end
    end

    # Log/reset negative float values. Set ~0.0 values to 0.0.
    sub.each do |key, value|
      next if key == :count
      next if key == :multiplier
      next if key == :type
      next if key == :id
      next if key == :frame
      next if key == :assembly

      unless value.respond_to?(:to_f)
        return mismatch(key, value, Float, mth, DBG, no)
      end

      next if key == :centreline

      negative(key, mth, WRN) if value < 0
      value = 0.0             if value.abs < TOL
    end
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Log/reset (or abandon) conflicting user-set geometry key:value pairs:
  #   :head       e.g. std 80" door + frame/buffers (+ m)
  #   :sill       e.g. std 30" sill + frame/buffers (+ m)
  #   :height     any sub surface height, below "head" (+ m)
  #   :width      e.g. 1.200 m
  #   :offset     if array (+ m)
  #   :centreline left or right of base surface centreline (+/- m)
  #   :r_buffer   buffer between sub/array and right-side corner (+ m)
  #   :l_buffer   buffer between sub/array and left-side corner (+ m)
  #
  # If successful, this will generate sub surfaces and add them to the model.
  subs.each do |sub|
    # Set-up unique sub parameters:
    #   - Frame & Divider "width"
    #   - minimum "clear glazing" limits
    #   - buffers, etc.
    id         = sub[:id]
    frame      = sub[:frame] ? sub[:frame].frameWidth : 0
    frames     = 2 * frame
    buffer     = frame + bfr
    buffers    = 2 * buffer
    dim        = 3 * frame > 0.200 ? 3 * frame : 0.200
    glass      = dim - frames
    min_sill   = buffer
    min_head   = buffers + glass
    max_head   = max_y - buffer
    max_sill   = max_head - (buffers + glass)
    min_ljamb  = buffer
    max_ljamb  = max_x - (buffers + glass)
    min_rjamb  = buffers + glass
    max_rjamb  = max_x - buffer
    max_height = max_y - buffers
    max_width  = max_x - buffers

    # Default sub surface "head" & "sill" height, unless user-specified.
    typ_head = HEAD
    typ_sill = SILL

    if sub.key?(:ratio)
      typ_head = mid_y * (1 + sub[:ratio])     if sub[:ratio] > 0.75
      typ_head = mid_y * (1 + sub[:ratio]) unless stype.downcase == "wall"
      typ_sill = mid_y * (1 - sub[:ratio])     if sub[:ratio] > 0.75
      typ_sill = mid_y * (1 - sub[:ratio]) unless stype.downcase == "wall"
    end

    # Log/reset "height" if beyond min/max.
    if sub.key?(:height)
      unless sub[:height].between?(glass - TOL2, max_height + TOL2)
        log(WRN, "Reset '#{id}' height #{sub[:height].round(3)}m (#{mth})")
        sub[:height] = sub[:height].clamp(glass, max_height)
        log(WRN, "Height '#{id}' reset to #{sub[:height].round(3)}m (#{mth})")
      end
    end

    # Log/reset "head" height if beyond min/max.
    if sub.key?(:head)
      unless sub[:head].between?(min_head - TOL2, max_head + TOL2)
        log(WRN, "Reset '#{id}' head #{sub[:head].round(3)}m (#{mth})")
        sub[:head] = sub[:head].clamp(min_head, max_head)
        log(WRN, "Head '#{id}' reset to #{sub[:head].round(3)}m (#{mth})")
      end
    end

    # Log/reset "sill" height if beyond min/max.
    if sub.key?(:sill)
      unless sub[:sill].between?(min_sill - TOL2, max_sill + TOL2)
        log(WRN, "Reset '#{id}' sill #{sub[:sill].round(3)}m (#{mth})")
        sub[:sill] = sub[:sill].clamp(min_sill, max_sill)
        log(WRN, "Sill '#{id}' reset to #{sub[:sill].round(3)}m (#{mth})")
      end
    end

    # At this point, "head", "sill" and/or "height" have been tentatively
    # validated (and/or have been corrected) independently from one another.
    # Log/reset "head" & "sill" heights if conflicting.
    if sub.key?(:head) && sub.key?(:sill) && sub[:head] < sub[:sill] + glass
      sill = sub[:head] - glass

      if sill < min_sill - TOL2
        sub[:ratio     ] = 0 if sub.key?(:ratio)
        sub[:count     ] = 0
        sub[:multiplier] = 0
        sub[:height    ] = 0 if sub.key?(:height)
        sub[:width     ] = 0 if sub.key?(:width)
        log(ERR, "Skip: invalid '#{id}' head/sill combo (#{mth})")
        next
      else
        log(WRN, "(Re)set '#{id}' sill #{sub[:sill].round(3)}m (#{mth})")
        sub[:sill] = sill
        log(WRN, "Sill '#{id}' (re)set to #{sub[:sill].round(3)}m (#{mth})")
      end
    end

    # Attempt to reconcile "head", "sill" and/or "height". If successful,
    # all 3x parameters are set (if missing), or reset if invalid.
    if sub.key?(:head) && sub.key?(:sill)
      height = sub[:head] - sub[:sill]

      if sub.key?(:height) && (sub[:height] - height).abs > TOL2
        log(WRN, "(Re)set '#{id}' height #{sub[:height].round(3)}m (#{mth})")
        log(WRN, "Height '#{id}' (re)set to #{height.round(3)}m (#{mth})")
      end

      sub[:height] = height
    elsif sub.key?(:head) # no "sill"
      if sub.key?(:height)
        sill = sub[:head] - sub[:height]

        if sill < min_sill - TOL2
          sill   = min_sill
          height = sub[:head] - sill

          if height < glass
            sub[:ratio     ] = 0 if sub.key?(:ratio)
            sub[:count     ] = 0
            sub[:multiplier] = 0
            sub[:height    ] = 0 if sub.key?(:height)
            sub[:width     ] = 0 if sub.key?(:width)
            log(ERR, "Skip: invalid '#{id}' head/height combo (#{mth})")
            next
          else
            log(WRN, "(Re)set '#{id}' height #{sub[:height].round(3)}m (#{mth})")
            sub[:sill  ] = sill
            sub[:height] = height
            log(WRN, "Height '#{id}' re(set) #{sub[:height].round(3)}m (#{mth})")
          end
        else
          sub[:sill] = sill
        end
      else
        sub[:sill  ] = typ_sill
        sub[:height] = sub[:head] - sub[:sill]
      end
    elsif sub.key?(:sill) # no "head"
      if sub.key?(:height)
        head = sub[:sill] + sub[:height]

        if head > max_head - TOL2
          head   = max_head
          height = head - sub[:sill]

          if height < glass
            sub[:ratio     ] = 0 if sub.key?(:ratio)
            sub[:count     ] = 0
            sub[:multiplier] = 0
            sub[:height    ] = 0 if sub.key?(:height)
            sub[:width     ] = 0 if sub.key?(:width)
            log(ERR, "Skip: invalid '#{id}' sill/height combo (#{mth})")
            next
          else
            log(WRN, "(Re)set '#{id}' height #{sub[:height].round(3)}m (#{mth})")
            sub[:head  ] = head
            sub[:height] = height
            log(WRN, "Height '#{id}' reset to #{sub[:height].round(3)}m (#{mth})")
          end
        else
          sub[:head] = head
        end
      else
        sub[:head  ] = typ_head
        sub[:height] = sub[:head] - sub[:sill]
      end
    elsif sub.key?(:height) # neither "head" nor "sill"
      head = s00 ? mid_y + sub[:height]/2 : typ_head
      sill = head - sub[:height]

      if sill < min_sill
        sill = min_sill
        head = sill + sub[:height]
      end

      sub[:head] = head
      sub[:sill] = sill
    else
      sub[:head  ] = typ_head
      sub[:sill  ] = typ_sill
      sub[:height] = sub[:head] - sub[:sill]
    end

    # Log/reset "width" if beyond min/max.
    if sub.key?(:width)
      unless sub[:width].between?(glass - TOL2, max_width + TOL2)
        log(WRN, "Reset '#{id}' width #{sub[:width].round(3)}m (#{mth})")
        sub[:width] = sub[:width].clamp(glass, max_width)
        log(WRN, "Width '#{id}' reset to #{sub[:width].round(3)}m (#{mth})")
      end
    end

    # Log/reset "count" if < 1 (or not an Integer)
    if sub[:count].respond_to?(:to_i)
      sub[:count] = sub[:count].to_i

      if sub[:count] < 1
        sub[:count] = 1
        log(WRN, "Reset '#{id}' count to min 1 (#{mth})")
      end
    else
      sub[:count] = 1
    end

    sub[:count] = 1 unless sub.key?(:count)

    # Log/reset if left-sided buffer under min jamb position.
    if sub.key?(:l_buffer)
      if sub[:l_buffer] < min_ljamb - TOL
        log(WRN, "Reset '#{id}' left buffer #{sub[:l_buffer].round(3)}m (#{mth})")
        sub[:l_buffer] = min_ljamb
        log(WRN, "Left buffer '#{id}' reset to #{sub[:l_buffer].round(3)}m (#{mth})")
      end
    end

    # Log/reset if right-sided buffer beyond max jamb position.
    if sub.key?(:r_buffer)
      if sub[:r_buffer] > max_rjamb - TOL
        log(WRN, "Reset '#{id}' right buffer #{sub[:r_buffer].round(3)}m (#{mth})")
        sub[:r_buffer] = min_rjamb
        log(WRN, "Right buffer '#{id}' reset to #{sub[:r_buffer].round(3)}m (#{mth})")
      end
    end

    centre  = mid_x
    centre += sub[:centreline] if sub.key?(:centreline)
    n       = sub[:count     ]
    h       = sub[:height    ] + frames
    w       = 0 # overall width of sub(s) bounding box (to calculate)
    x0      = 0 # left-side X-axis coordinate of sub(s) bounding box
    xf      = 0 # right-side X-axis coordinate of sub(s) bounding box

    # Log/reset "offset", if conflicting vs "width".
    if sub.key?(:ratio)
      if sub[:ratio] < TOL
        sub[:ratio     ] = 0
        sub[:count     ] = 0
        sub[:multiplier] = 0
        sub[:height    ] = 0 if sub.key?(:height)
        sub[:width     ] = 0 if sub.key?(:width)
        log(ERR, "Skip: ratio ~0 (#{mth})")
        next
      end

      # Log/reset if "ratio" beyond min/max?
      unless sub[:ratio].between?(min, max)
        log(WRN, "Reset ratio #{sub[:ratio].round(3)} (#{mth})")
        sub[:ratio] = sub[:ratio].clamp(min, max)
        log(WRN, "Ratio reset to #{sub[:ratio].round(3)} (#{mth})")
      end

      # Log/reset "count" unless 1.
      unless sub[:count] == 1
        sub[:count] = 1
        log(WRN, "Reset count (ratio) to 1 (#{mth})")
      end

      area  = s.grossArea * sub[:ratio] # sub m2, including (optional) frames
      w     = area / h
      width = w - frames
      x0    = centre - w/2
      xf    = centre + w/2

      if sub.key?(:l_buffer)
        if sub.key?(:centreline)
          log(WRN, "Skip '#{id}' left buffer (vs centreline) (#{mth})")
        else
          x0     = sub[:l_buffer] - frame
          xf     = x0 + w
          centre = x0 + w/2
        end
      elsif sub.key?(:r_buffer)
        if sub.key?(:centreline)
          log(WRN, "Skip '#{id}' right buffer (vs centreline) (#{mth})")
        else
          xf     = max_x - sub[:r_buffer] + frame
          x0     = xf - w
          centre = x0 + w/2
        end
      end

      # Too wide?
      if x0 < min_ljamb - TOL2 || xf > max_rjamb - TOL2
        sub[:ratio     ] = 0 if sub.key?(:ratio)
        sub[:count     ] = 0
        sub[:multiplier] = 0
        sub[:height    ] = 0 if sub.key?(:height)
        sub[:width     ] = 0 if sub.key?(:width)
        log(ERR, "Skip '#{id}': invalid (ratio) width/centreline (#{mth})")
        next
      end

      if sub.key?(:width) && (sub[:width] - width).abs > TOL
        log(WRN, "Reset '#{id}' width (ratio) #{sub[:width].round(2)}m (#{mth})")
        sub[:width] = width
        log(WRN, "Width (ratio) '#{id}' reset to #{sub[:width].round(2)}m (#{mth})")
      end

      sub[:width] = width unless sub.key?(:width)
    else
      unless sub.key?(:width)
        sub[:ratio     ] = 0 if sub.key?(:ratio)
        sub[:count     ] = 0
        sub[:multiplier] = 0
        sub[:height    ] = 0 if sub.key?(:height)
        sub[:width     ] = 0 if sub.key?(:width)
        log(ERR, "Skip: missing '#{id}' width (#{mth})")
        next
      end

      width  = sub[:width] + frames
      gap    = (max_x - n * width) / (n + 1)
      gap    = sub[:offset] - width if sub.key?(:offset)
      gap    = 0                    if gap < buffer
      offset = gap + width

      if sub.key?(:offset) && (offset - sub[:offset]).abs > TOL
        log(WRN, "Reset '#{id}' sub offset #{sub[:offset].round(2)}m (#{mth})")
        sub[:offset] = offset
        log(WRN, "Sub offset (#{id}) reset to #{sub[:offset].round(2)}m (#{mth})")
      end

      sub[:offset] = offset unless sub.key?(:offset)

      # Overall width (including frames) of bounding box around array.
      w  = n * width + (n - 1) * gap
      x0 = centre - w/2
      xf = centre + w/2

      if sub.key?(:l_buffer)
        if sub.key?(:centreline)
          log(WRN, "Skip '#{id}' left buffer (vs centreline) (#{mth})")
        else
          x0     = sub[:l_buffer] - frame
          xf     = x0 + w
          centre = x0 + w/2
        end
      elsif sub.key?(:r_buffer)
        if sub.key?(:centreline)
          log(WRN, "Skip '#{id}' right buffer (vs centreline) (#{mth})")
        else
          xf     = max_x - sub[:r_buffer] + frame
          x0     = xf - w
          centre = x0 + w/2
        end
      end

      # Too wide?
      if x0 < buffer - TOL2 || xf > max_x - buffer - TOL2
        sub[:ratio     ] = 0 if sub.key?(:ratio)
        sub[:count     ] = 0
        sub[:multiplier] = 0
        sub[:height    ] = 0 if sub.key?(:height)
        sub[:width     ] = 0 if sub.key?(:width)
        log(ERR, "Skip: invalid array width/centreline (#{mth})")
        next
      end
    end

    # Initialize left-side X-axis coordinate of only/first sub.
    pos = x0 + frame

    # Generate sub(s).
    sub[:count].times do |i|
      name = "#{id}:#{i}"
      fr   = 0
      fr   = sub[:frame].frameWidth if sub[:frame]
      vec  = OpenStudio::Point3dVector.new
      vec << OpenStudio::Point3d.new(pos,               sub[:head], 0)
      vec << OpenStudio::Point3d.new(pos,               sub[:sill], 0)
      vec << OpenStudio::Point3d.new(pos + sub[:width], sub[:sill], 0)
      vec << OpenStudio::Point3d.new(pos + sub[:width], sub[:head], 0)
      vec = s00 ? t * (s00[:r] * (s00[:t] * vec)) : t * vec

      # Log/skip if conflict between individual sub and base surface.
      vc = vec
      vc = offset(vc, fr, 300) if fr > 0

      unless fits?(vc, s)
        log(ERR, "Skip '#{name}': won't fit in '#{nom}' (#{mth})")
        break
      end

      # Log/skip if conflicts with existing subs (even if same array).
      conflict = false

      s.subSurfaces.each do |sb|
        nome = sb.nameString
        fd   = sb.windowPropertyFrameAndDivider
        fr   = fd.empty? ? 0 : fd.get.frameWidth
        vk   = sb.vertices
        vk   = offset(vk, fr, 300) if fr > 0

        if overlaps?(vc, vk)
          log(ERR, "Skip '#{name}': overlaps '#{nome}' (#{mth})")
          conflict = true
          break
        end
      end

      break if conflict

      sb = OpenStudio::Model::SubSurface.new(vec, mdl)
      sb.setName(name)
      sb.setSubSurfaceType(sub[:type])
      sb.setConstruction(sub[:assembly]) if sub[:assembly]
      sb.setMultiplier(sub[:multiplier]) if sub[:multiplier] > 1

      if sub[:frame] && sb.allowWindowPropertyFrameAndDivider
        sb.setWindowPropertyFrameAndDivider(sub[:frame])
      end

      sb.setSurface(s)

      # Reset "pos" if array.
      pos += sub[:offset] if sub.key?(:offset)
    end
  end

  true
end

#airLoopsHVAC?(model = nil) ⇒ `Bool`, `false`

Validates if model has zones with HVAC air loops.

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model

Returns:

(Bool) —

whether model has HVAC air loops
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1291

def airLoopsHVAC?(model = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Model
  return mismatch("model", model, cl, mth, DBG, false) unless model.is_a?(cl)

  model.getThermalZones.each do |zone|
    next            if zone.canBePlenum
    return true unless zone.airLoopHVACs.empty?
    return true     if zone.isPlenum
  end

  false
end

#alignedHeight(pts = nil, force = false) ⇒ `Float`, `0.0`

Returns ‘height’ of a set of OpenStudio 3D points, once re/aligned.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points, once re/aligned
force (Bool) (defaults to: false) —

whether to force rotation of (narrow) bounded box

Returns:

(Float) —

height along Y-axis, once re/aligned
(0.0) —

if invalid inputs

# File 'lib/osut/utils.rb', line 4470

def alignedHeight(pts = nil, force = false)
  mth = "OSut::#{__callee__}"
  pts = poly(pts, false, true, true, true)
  return 0 if pts.size < 2

  unless [true, false].include?(force)
    log(DBG, "Ignoring force input (#{mth})")
    force = false
  end

  pts = getRealignedFace(pts, force)[:set]
  return 0 if pts.size < 2

  pts.max_by(&:y).y - pts.min_by(&:y).y
end

#alignedWidth(pts = nil, force = false) ⇒ `Float`, `0.0`

Returns ‘width’ of a set of OpenStudio 3D points, once re/aligned.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points, once re/aligned
force (Bool) (defaults to: false) —

whether to force rotation of (narrow) bounded box

Returns:

(Float) —

width al©ong X-axis, once re/aligned
(0.0) —

if invalid inputs

# File 'lib/osut/utils.rb', line 4446

def alignedWidth(pts = nil, force = false)
  mth = "OSut::#{__callee__}"
  pts = poly(pts, false, true, true, true)
  return 0 if pts.size < 2

  unless [true, false].include?(force)
    log(DBG, "Ignoring force input (#{mth})")
    force = false
  end

  pts = getRealignedFace(pts, force)[:set]
  return 0 if pts.size < 2

  pts.max_by(&:x).x - pts.min_by(&:x).x
end

#availabilitySchedule(model = nil, avl = "") ⇒ `OpenStudio::Model::Schedule`^?

Generates an HVAC availability schedule.

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model
avl (String) (defaults to: "") —

seasonal availability choice (optional, default “ON”)

Returns:

(OpenStudio::Model::Schedule) —

HVAC availability sched
(nil) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2155

def availabilitySchedule(model = nil, avl = "")
  mth    = "OSut::#{__callee__}"
  cl     = OpenStudio::Model::Model
  limits = nil
  return mismatch("model",     model, cl, mth) unless model.is_a?(cl)
  return invalid("availability", avl,  2, mth) unless avl.respond_to?(:to_s)

  # Either fetch availability ScheduleTypeLimits object, or create one.
  model.getScheduleTypeLimitss.each do |l|
    break    if limits
    next     if l.lowerLimitValue.empty?
    next     if l.upperLimitValue.empty?
    next     if l.numericType.empty?
    next unless l.lowerLimitValue.get.to_i == 0
    next unless l.upperLimitValue.get.to_i == 1
    next unless l.numericType.get.downcase == "discrete"
    next unless l.unitType.downcase == "availability"
    next unless l.nameString.downcase == "hvac operation scheduletypelimits"

    limits = l
  end

  unless limits
    limits = OpenStudio::Model::ScheduleTypeLimits.new(model)
    limits.setName("HVAC Operation ScheduleTypeLimits")
    limits.setLowerLimitValue(0)
    limits.setUpperLimitValue(1)
    limits.setNumericType("Discrete")
    limits.setUnitType("Availability")
  end

  time = OpenStudio::Time.new(0,24)
  secs = time.totalSeconds
  on   = OpenStudio::Model::ScheduleDay.new(model, 1)
  off  = OpenStudio::Model::ScheduleDay.new(model, 0)

  # Seasonal availability start/end dates.
  year  = model.yearDescription
  return empty("yearDescription", mth, ERR) if year.empty?

  year  = year.get
  may01 = year.makeDate(OpenStudio::MonthOfYear.new("May"),  1)
  oct31 = year.makeDate(OpenStudio::MonthOfYear.new("Oct"), 31)

  case trim(avl).downcase
  when "winter" # available from November 1 to April 30 (6 months)
    val = 1
    sch = off
    nom = "WINTER Availability SchedRuleset"
    dft = "WINTER Availability dftDaySched"
    tag = "May-Oct WINTER Availability SchedRule"
    day = "May-Oct WINTER SchedRule Day"
  when "summer" # available from May 1 to October 31 (6 months)
    val = 0
    sch = on
    nom = "SUMMER Availability SchedRuleset"
    dft = "SUMMER Availability dftDaySched"
    tag = "May-Oct SUMMER Availability SchedRule"
    day = "May-Oct SUMMER SchedRule Day"
  when "off" # never available
    val = 0
    sch = on
    nom = "OFF Availability SchedRuleset"
    dft = "OFF Availability dftDaySched"
    tag = ""
    day = ""
  else # always available
    val = 1
    sch = on
    nom = "ON Availability SchedRuleset"
    dft = "ON Availability dftDaySched"
    tag = ""
    day = ""
  end

  # Fetch existing schedule.
  ok = true
  schedule = model.getScheduleByName(nom)

  unless schedule.empty?
    schedule = schedule.get.to_ScheduleRuleset

    unless schedule.empty?
      schedule = schedule.get
      default  = schedule.defaultDaySchedule
      ok = ok && default.nameString           == dft
      ok = ok && default.times.size           == 1
      ok = ok && default.values.size          == 1
      ok = ok && default.times.first          == time
      ok = ok && default.values.first         == val
      rules = schedule.scheduleRules
      ok = ok && rules.size < 2

      if rules.size == 1
        rule = rules.first
        ok = ok && rule.nameString            == tag
        ok = ok && !rule.startDate.empty?
        ok = ok && !rule.endDate.empty?
        ok = ok && rule.startDate.get         == may01
        ok = ok && rule.endDate.get           == oct31
        ok = ok && rule.applyAllDays

        d = rule.daySchedule
        ok = ok && d.nameString               == day
        ok = ok && d.times.size               == 1
        ok = ok && d.values.size              == 1
        ok = ok && d.times.first.totalSeconds == secs
        ok = ok && d.values.first.to_i        != val
      end

      return schedule if ok
    end
  end

  schedule = OpenStudio::Model::ScheduleRuleset.new(model)
  schedule.setName(nom)

  unless schedule.setScheduleTypeLimits(limits)
    log(ERR, "'#{nom}': Can't set schedule type limits (#{mth})")
    return nil
  end

  unless schedule.defaultDaySchedule.addValue(time, val)
    log(ERR, "'#{nom}': Can't set default day schedule (#{mth})")
    return nil
  end

  schedule.defaultDaySchedule.setName(dft)

  unless tag.empty?
    rule = OpenStudio::Model::ScheduleRule.new(schedule, sch)
    rule.setName(tag)

    unless rule.setStartDate(may01)
      log(ERR, "'#{tag}': Can't set start date (#{mth})")
      return nil
    end

    unless rule.setEndDate(oct31)
      log(ERR, "'#{tag}': Can't set end date (#{mth})")
      return nil
    end

    unless rule.setApplyAllDays(true)
      log(ERR, "'#{tag}': Can't apply to all days (#{mth})")
      return nil
    end

    rule.daySchedule.setName(day)
  end

  schedule
end

#blc(pts = nil) ⇒ `OpenStudio::Point3dVector`

Returns OpenStudio 3D points (min 3x) conforming to an BottomLeftCorner (BLC) convention. Points Z-axis values must be ~= 0. Points are returned counterclockwise.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(OpenStudio::Point3dVector) —

BLC points (see logs if empty)

# File 'lib/osut/utils.rb', line 3121

def blc(pts = nil)
  mth = "OSut::#{__callee__}"
  v   = OpenStudio::Point3dVector.new
  pts = to_p3Dv(pts).to_a
  return invalid("points (3+)",      mth, 1, DBG, v)     if pts.size < 3
  return invalid("points (aligned)", mth, 1, DBG, v) unless xyz?(pts, :z)

  # Ensure counterclockwise sequence.
  pts  = pts.reverse if clockwise?(pts)
  minX = pts.min_by(&:x).x
  i0   = nearest(pts)
  p0   = pts[i0]

  pts_x = pts.select { |pt| pt.x.round(2) == minX.round(2) }.reverse

  return to_p3Dv(pts.rotate(i0)) if pts_x.include?(p0)

  p1 = pts_x.min_by { |pt| (pt - p0).length }
  i1 = pts.index(p1)

  to_p3Dv(pts.rotate(i1))
end

#boundedBox(pts = nil) ⇒ `OpenStudio::Point3dVector`

Generates a BLC bounded box within a polygon.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points

Returns:

(OpenStudio::Point3dVector) —

bounded box (see logs if empty)

# File 'lib/osut/utils.rb', line 4133

def boundedBox(pts = nil)
  str = ".*(?<!utilities.geometry.join)$"
  OpenStudio::Logger.instance.standardOutLogger.setChannelRegex(str)

  mth = "OSut::#{__callee__}"
  bkp = OpenStudio::Point3dVector.new
  box = []
  pts = poly(pts, false, true, true)
  return bkp if pts.empty?

  t   = xyz?(pts, :z) ? nil : OpenStudio::Transformation.alignFace(pts)
  pts = t.inverse * pts if t
  return bkp if pts.empty?

  pts = to_p3Dv(pts.to_a.reverse) if clockwise?(pts)

  # PATH A : Return medial bounded box if polygon is a triangle.
  if pts.size == 3
    box = medialBox(pts)

    unless box.empty?
      box = to_p3Dv(t * box) if t
      return box
    end
  end

  # PATH B : Return polygon itself if already rectangular.
  if rectangular?(pts)
    box = t ? to_p3Dv(t * pts) : pts
    return box
  end

  aire = 0

  # PATH C : Right-angle, midpoint triad approach.
  getSegments(pts).each do |sg|
    m0 = midpoint(sg.first, sg.last)

    getSegments(pts).each do |seg|
      p1 = seg.first
      p2 = seg.last
      next if same?(p1, sg.first)
      next if same?(p1, sg.last)
      next if same?(p2, sg.first)
      next if same?(p2, sg.first)

      out = triadBox(OpenStudio::Point3dVector.new([m0, p1, p2]))
      next if out.empty?
      next unless fits?(out, pts)
      next if fits?(pts, out)

      area = OpenStudio.getArea(out)
      next if area.empty?

      area = area.get
      next if area < TOL
      next if area < aire

      aire = area
      box  = out
    end
  end

  # PATH D : Right-angle triad approach, may override PATH C boxes.
  getSegments(pts).each do |sg|
    p0 = sg.first
    p1 = sg.last

    pts.each do |p2|
      next if same?(p2, p0)
      next if same?(p2, p1)

      out = triadBox(OpenStudio::Point3dVector.new([p0, p1, p2]))
      next if out.empty?
      next unless fits?(out, pts)
      next if fits?(pts, out)

      area = OpenStudio.getArea(out)
      next if area.empty?

      area = area.get
      next if area < TOL
      next if area < aire

      aire = area
      box  = out
    end
  end

  unless aire < TOL
    box = to_p3Dv(t * box) if t
    return box
  end

  # PATH E : Medial box, segment approach.
  aire = 0

  getSegments(pts).each do |sg|
    p0 = sg.first
    p1 = sg.last

    pts.each do |p2|
      next if same?(p2, p0)
      next if same?(p2, p1)

      out = medialBox(OpenStudio::Point3dVector.new([p0, p1, p2]))
      next if out.empty?
      next unless fits?(out, pts)
      next if fits?(pts, out)

      area = OpenStudio.getArea(box)
      next if area.empty?

      area = area.get
      next if area < TOL
      next if area < aire

      aire = area
      box  = out
    end
  end

  unless aire < TOL
    box = to_p3Dv(t * box) if t
    return box
  end

  # PATH F : Medial box, triad approach.
  aire = 0

  getTriads(pts).each do |sg|
    p0 = sg[0]
    p1 = sg[1]
    p2 = sg[2]

    out = medialBox(OpenStudio::Point3dVector.new([p0, p1, p2]))
    next if out.empty?
    next unless fits?(out, pts)
    next if fits?(pts, out)

    area = OpenStudio.getArea(box)
    next if area.empty?

    area = area.get
    next if area < TOL
    next if area < aire

    aire = area
    box  = out
  end

  unless aire < TOL
    box = to_p3Dv(t * box) if t
    return box
  end

  # PATH G : Medial box, triangulated approach.
  aire  = 0
  outer = to_p3Dv(pts.to_a.reverse)
  holes = OpenStudio::Point3dVectorVector.new

  OpenStudio.computeTriangulation(outer, holes).each do |triangle|
    getSegments(triangle).each do |sg|
      p0 = sg.first
      p1 = sg.last

      pts.each do |p2|
        next if same?(p2, p0)
        next if same?(p2, p1)

        out = medialBox(OpenStudio::Point3dVector.new([p0, p1, p2]))
        next if out.empty?
        next unless fits?(out, pts)
        next if fits?(pts, out)

        area = OpenStudio.getArea(out)
        next if area.empty?

        area = area.get
        next if area < TOL
        next if area < aire

        aire = area
        box  = out
      end
    end
  end

  return bkp if aire < TOL

  box = to_p3Dv(t * box) if t

  box
end

#cast(p1 = nil, p2 = nil, ray = nil) ⇒ `OpenStudio::Point3dVector`

Casts an OpenStudio polygon onto the 3D plane of a 2nd polygon, relying on an independent 3D ray vector.

Parameters:

p1 (Set<OpenStudio::Point3d>) (defaults to: nil) —

1st set of 3D points
p2 (Set<OpenStudio::Point3d>) (defaults to: nil) —

2nd set of 3D points
ray (OpenStudio::Vector3d) (defaults to: nil) —

a vector

Returns:

(OpenStudio::Point3dVector) —

cast of p1 onto p2 (see logs if empty)

# File 'lib/osut/utils.rb', line 3685

def cast(p1 = nil, p2 = nil, ray = nil)
  mth  = "OSut::#{__callee__}"
  cl   = OpenStudio::Vector3d
  face = OpenStudio::Point3dVector.new
  p1   = poly(p1)
  p2   = poly(p2)
  return face if p1.empty?
  return face if p2.empty?
  return mismatch("ray", ray, cl, mth) unless ray.is_a?(cl)

  # From OpenStudio SDK v3.7.0 onwards, one could/should rely on:
  #
  # s3.amazonaws.com/openstudio-sdk-documentation/cpp/OpenStudio-3.7.0-doc/
  # utilities/html/classopenstudio_1_1_plane.html
  # #abc4747b1b041a7f09a6887bc0e5abce1
  #
  #   e.g. p1.each { |pt| face << pl.rayIntersection(pt, ray) }
  #
  # The following +/- replicates the same solution, based on:
  #   https://stackoverflow.com/a/65832417
  p0 = p2.first
  pl = OpenStudio::Plane.new(p2)
  n  = pl.outwardNormal
  return face if n.dot(ray).abs < TOL

  p1.each do |pt|
    length = n.dot(pt - p0) / n.dot(ray.reverseVector)
    face << pt + scalar(ray, length)
  end

  face
end

#clockwise?(pts = nil) ⇒ `Bool`, `false`

Validates whether OpenStudio 3D points are listed clockwise, assuming points have been pre-‘aligned’ - not just flattened along XY (i.e. Z = 0).

Parameters:

pts (OpenStudio::Point3dVector) (defaults to: nil) —

pre-aligned 3D points

Returns:

(Bool) —

whether sequence is clockwise
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3072

def clockwise?(pts = nil)
  mth = "OSut::#{__callee__}"
  pts = to_p3Dv(pts)
  return invalid("3+ points"  , mth, 1, DBG, false)     if pts.size < 3
  return invalid("flat points", mth, 1, DBG, false) unless xyz?(pts, :z)

  n = OpenStudio.getOutwardNormal(pts)
  return invalid("polygon", mth, 1, DBG, false) if n.empty?

  n.get.z > 0 ? false : true
end

#coolingTemperatureSetpoints?(model = nil) ⇒ `Bool`, `false`

Validates if model has zones with valid cooling temperature setpoints.

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model

Returns:

(Bool) —

whether model holds valid cooling temperature setpoints
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1793

def coolingTemperatureSetpoints?(model = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Model
  return mismatch("model", model, cl, mth, DBG, false) unless model.is_a?(cl)

  model.getThermalZones.each do |zone|
    return true if minCoolScheduledSetpoint(zone)[:spt]
  end

  false
end

#daylit?(space = nil, sidelit = true, toplit = true, baselit = true) ⇒ `Bool`, `false`

Validates whether space has outdoor-facing surfaces with fenestration.

Parameters:

space (OpenStudio::Model::Space) (defaults to: nil) —

a space
sidelit (Bool) (defaults to: true) —

whether to check for sidelighting, e.g. windows
toplit (Bool) (defaults to: true) —

whether to check for toplighting, e.g. skylights
baselit (Bool) (defaults to: true) —

whether to check for baselighting, e.g. glazed floors

Returns:

(Bool) —

whether space is daylit
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 5230

def daylit?(space = nil, sidelit = true, toplit = true, baselit = true)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Space
  ck1 = space.is_a?(cl)
  ck2 = [true, false].include?(sidelit)
  ck3 = [true, false].include?(toplit)
  ck4 = [true, false].include?(baselit)
  return mismatch("space", space, cl, mth,    DBG, false) unless ck1
  return invalid("sidelit"          , mth, 2, DBG, false) unless ck2
  return invalid("toplit"           , mth, 3, DBG, false) unless ck3
  return invalid("baselit"          , mth, 4, DBG, false) unless ck4

  walls  = sidelit ? facets(space, "Outdoors", "Wall")        : []
  roofs  =  toplit ? facets(space, "Outdoors", "RoofCeiling") : []
  floors = baselit ? facets(space, "Outdoors", "Floor")       : []

  (walls + roofs + floors).each do |surface|
    surface.subSurfaces.each do |sub|
      # All fenestrated subsurface types are considered, as user can set these
      # explicitly (e.g. skylight in a wall) in OpenStudio.
      return true if fenestration?(sub)
    end
  end

  false
end

#defaultConstructionSet(s = nil) ⇒ `OpenStudio::Model::DefaultConstructionSet`^?

Returns a surface’s default construction set.

Parameters:

s (OpenStudio::Model::Surface) (defaults to: nil) —

a surface

Returns:

(OpenStudio::Model::DefaultConstructionSet) —

default set
(nil) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 828

def defaultConstructionSet(s = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Surface
  return invalid("surface", mth, 1) unless s.respond_to?(NS)

  id = s.nameString
  ok = s.isConstructionDefaulted
  m1 = "#{id} construction not defaulted (#{mth})"
  m2 = "#{id} construction"
  m3 = "#{id} space"
  return mismatch(id, s, cl, mth) unless s.is_a?(cl)

  log(ERR, m1)           unless ok
  return nil             unless ok
  return empty(m2, mth, ERR) if s.construction.empty?
  return empty(m3, mth, ERR) if s.space.empty?

  mdl      = s.model
  base     = s.construction.get
  space    = s.space.get
  type     = s.surfaceType
  ground   = false
  exterior = false

  if s.isGroundSurface
    ground = true
  elsif s.outsideBoundaryCondition.downcase == "outdoors"
    exterior = true
  end

  unless space.defaultConstructionSet.empty?
    set = space.defaultConstructionSet.get
    return set if holdsConstruction?(set, base, ground, exterior, type)
  end

  unless space.spaceType.empty?
    spacetype = space.spaceType.get

    unless spacetype.defaultConstructionSet.empty?
      set = spacetype.defaultConstructionSet.get
      return set if holdsConstruction?(set, base, ground, exterior, type)
    end
  end

  unless space.buildingStory.empty?
    story = space.buildingStory.get

    unless story.defaultConstructionSet.empty?
      set = story.defaultConstructionSet.get
      return set if holdsConstruction?(set, base, ground, exterior, type)
    end
  end

  building = mdl.getBuilding

  unless building.defaultConstructionSet.empty?
    set = building.defaultConstructionSet.get
    return set if holdsConstruction?(set, base, ground, exterior, type)
  end

  nil
end

Returns an array of OpenStudio space surfaces or subsurfaces that match criteria, e.g. exterior, north-east facing walls in hotel “lobby”. Note that ‘sides’ rely on space coordinates (not building or site coordinates). Also, ‘sides’ are exclusive (not inclusive), e.g. walls strictly north-facing or strictly east-facing would not be returned if ‘sides’ holds [:north, :east]. No outside boundary condition filters if ‘boundary’ argument == “all”. No surface type filters if ‘type’ argument == “all”.

Parameters:

spaces (Set<OpenStudio::Model::Space>) (defaults to: []) —

target spaces
boundary (#to_s) (defaults to: "all") —

OpenStudio outside boundary condition
type (#to_s) (defaults to: "all") —

OpenStudio surface (or subsurface) type
sides (Set<Symbols>) (defaults to: []) —

direction keys, e.g. :north (see OSut::SIDZ)

Returns:

(Array<OpenStudio::Model::Surface>) —

surfaces (may be empty, no logs)

# File 'lib/osut/utils.rb', line 4984

def facets(spaces = [], boundary = "all", type = "all", sides = [])
  spaces = spaces.is_a?(OpenStudio::Model::Space) ? [spaces] : spaces
  spaces = spaces.respond_to?(:to_a) ? spaces.to_a : []
  return [] if spaces.empty?

  sides = sides.respond_to?(:to_sym) ? [sides] : sides
  sides = sides.respond_to?(:to_a) ? sides.to_a : []

  faces    = []
  boundary = trim(boundary).downcase
  type     = trim(type).downcase
  return [] if boundary.empty?
  return [] if type.empty?

  # Filter sides. If 'sides' is initially empty, return all surfaces of
  # matching type and outside boundary condition.
  unless sides.empty?
    sides = sides.select { |side| SIDZ.include?(side) }
    return [] if sides.empty?
  end

  spaces.each do |space|
    return [] unless space.respond_to?(:setSpaceType)

    space.surfaces.each do |s|
      unless boundary == "all"
        next unless s.outsideBoundaryCondition.downcase == boundary
      end

      unless type == "all"
        next unless s.surfaceType.downcase == type
      end

      if sides.empty?
        faces << s
      else
        orientations = []
        orientations << :top    if s.outwardNormal.z >  TOL
        orientations << :bottom if s.outwardNormal.z < -TOL
        orientations << :north  if s.outwardNormal.y >  TOL
        orientations << :east   if s.outwardNormal.x >  TOL
        orientations << :south  if s.outwardNormal.y < -TOL
        orientations << :west   if s.outwardNormal.x < -TOL

        faces << s if sides.all? { |o| orientations.include?(o) }
      end
    end
  end

  # SubSurfaces?
  spaces.each do |space|
    space.surfaces.each do |s|
      unless boundary == "all"
        next unless s.outsideBoundaryCondition.downcase == boundary
      end

      s.subSurfaces.each do |sub|
        unless type == "all"
          next unless sub.subSurfaceType.downcase == type
        end

        if sides.empty?
          faces << sub
        else
          orientations = []
          orientations << :top    if sub.outwardNormal.z >  TOL
          orientations << :bottom if sub.outwardNormal.z < -TOL
          orientations << :north  if sub.outwardNormal.y >  TOL
          orientations << :east   if sub.outwardNormal.x >  TOL
          orientations << :south  if sub.outwardNormal.y < -TOL
          orientations << :west   if sub.outwardNormal.x < -TOL

          faces << sub if sides.all? { |o| orientations.include?(o) }
        end
      end
    end
  end

  faces
end

#facingDown?(pts = nil) ⇒ `Bool`, `false`

Validates whether a polygon faces downwards, harmonized with OpenStudio Utilities’ “alignZPrime” function.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points

Returns:

(Bool) —

if facing downwards
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3457

def facingDown?(pts = nil)
  ray = OpenStudio::Point3d.new(0,0,-1) - OpenStudio::Point3d.new(0,0,0)
  pts = poly(pts, false, true, true)
  return false if pts.empty?

  OpenStudio.getOutwardNormal(pts).get.dot(ray) > 0.99
end

#facingUp?(pts = nil) ⇒ `Bool`, `false`

Validates whether a polygon faces upwards, harmonized with OpenStudio Utilities’ “alignZPrime” function.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points

Returns:

(Bool) —

if facing upwards
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3441

def facingUp?(pts = nil)
  ray = OpenStudio::Point3d.new(0,0,1) - OpenStudio::Point3d.new(0,0,0)
  pts = poly(pts, false, true, true)
  return false if pts.empty?

  OpenStudio.getOutwardNormal(pts).get.dot(ray) > 0.99
end

#farthest(pts = nil, p01 = nil) ⇒ `Integer`^?

Returns OpenStudio 3D point (in a set) farthest from a point of reference, e.g. grid origin. If left unspecified, the method systematically returns the top-right corner (TRC) of any horizontal set. If more than one point fits the initial criteria, the method relies on deterministic sorting through triangulation.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points
p01 (OpenStudio::Point3d) (defaults to: nil) —

point of reference

Returns:

(Integer) —

set index of farthest point from point of reference
(nil) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2563

def farthest(pts = nil, p01 = nil)
  mth = "OSut::#{__callee__}"
  l   = 100
  d01 = 0
  d02 = 10000
  d03 = 10000
  idx = nil
  pts = to_p3Dv(pts)
  return idx if pts.empty?

  p03 = OpenStudio::Point3d.new( l,-l,-l)
  p02 = OpenStudio::Point3d.new( l, l, l)
  p01 = OpenStudio::Point3d.new(-l,-l,-l) unless p01
  return mismatch("point", p01, cl, mth) unless p01.is_a?(OpenStudio::Point3d)

  pts.each_with_index do |pt, i|
    next if same?(pt, p01)

    length01 = (pt - p01).length
    length02 = (pt - p02).length
    length03 = (pt - p03).length

    if length01.round(2) == d01.round(2)
      if length02.round(2) == d02.round(2)
        if length03.round(2) < d03.round(2)
          idx = i
          d03 = length03
        end
      elsif length02.round(2) < d02.round(2)
        idx = i
        d03 = length03
        d02 = length02
      end
    elsif length01.round(2) > d01.round(2)
      idx = i
      d01 = length01
      d02 = length02
      d03 = length03
    end
  end

  idx
end

#fenestration?(s = nil) ⇒ `Bool`, `false`

Validates whether a sub surface is fenestrated.

Parameters:

s (OpenStudio::Model::SubSurface) (defaults to: nil) —

a sub surface

Returns:

(Bool) —

whether subsurface can be considered ‘fenestrated’
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1126

def fenestration?(s = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::SubSurface
  return invalid("subsurface", mth, 1, DBG, false) unless s.respond_to?(NS)

  id = s.nameString
  return mismatch(id, s, cl, mth, false) unless s.is_a?(cl)

  # OpenStudio::Model::SubSurface.validSubSurfaceTypeValues
  # "FixedWindow"              : fenestration
  # "OperableWindow"           : fenestration
  # "Door"
  # "GlassDoor"                : fenestration
  # "OverheadDoor"
  # "Skylight"                 : fenestration
  # "TubularDaylightDome"      : fenestration
  # "TubularDaylightDiffuser"  : fenestration
  return false if s.subSurfaceType.downcase == "door"
  return false if s.subSurfaceType.downcase == "overheaddoor"

  true
end

#fits?(p1 = nil, p2 = nil, entirely = false) ⇒ `Bool`, `false`

Determines whether a 1st OpenStudio polygon fits in a 2nd polygon. Vertex sequencing of both polygons must be counterclockwise. If option ‘entirely’ is set to true, then the method returns false if point lies along any of the polygon edges, or is very near any of its vertices.

Parameters:

p1 (Set<OpenStudio::Point3d>) (defaults to: nil) —

1st set of 3D points
p2 (Set<OpenStudio::Point3d>) (defaults to: nil) —

2nd set of 3D points
entirely (Bool) (defaults to: false) —

whether point should be neatly within polygon limits

Returns:

(Bool) —

whether 1st polygon fits within the 2nd polygon
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3542

def fits?(p1 = nil, p2 = nil, entirely = false)
  pts = []
  p1  = poly(p1)
  p2  = poly(p2)
  return false if p1.empty?
  return false if p2.empty?

  p1.each { |p0| return false unless pointWithinPolygon?(p0, p2) }

  # Although p2 points may lie ALONG p1, none may lie entirely WITHIN p1.
  p2.each { |p0| return false if pointWithinPolygon?(p0, p1, true) }

  # p1 segment mid-points must not lie OUTSIDE of p2.
  getSegments(p1).each do |sg|
    mp = midpoint(sg.first, sg.last)
    return false unless pointWithinPolygon?(mp, p2)
  end

  entirely = false unless [true, false].include?(entirely)
  return true unless entirely

  p1.each { |p0| return false unless pointWithinPolygon?(p0, p2, entirely) }

  true
end

#flatten(pts = nil, axs = :z, val = 0) ⇒ `OpenStudio::Point3dVector`

Flattens OpenStudio 3D points vs X, Y or Z axes.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points
axs (Symbol) (defaults to: :z) —

:x, :y or :z axis
val (#to_f) (defaults to: 0) —

axis value

Returns:

(OpenStudio::Point3dVector) —

flattened points (see logs if empty)

# File 'lib/osut/utils.rb', line 2615

def flatten(pts = nil, axs = :z, val = 0)
  mth = "OSut::#{__callee__}"
  pts = to_p3Dv(pts)
  v   = OpenStudio::Point3dVector.new
  ok1 = val.respond_to?(:to_f)
  ok2 = [:x, :y, :z].include?(axs)
  return mismatch("val", val, Numeric, mth,    DBG, v) unless ok1
  return invalid("axis (XYZ?)",        mth, 2, DBG, v) unless ok2

  val = val.to_f

  case axs
  when :x
    pts.each { |pt| v << OpenStudio::Point3d.new(val, pt.y, pt.z) }
  when :y
    pts.each { |pt| v << OpenStudio::Point3d.new(pt.x, val, pt.z) }
  else
    pts.each { |pt| v << OpenStudio::Point3d.new(pt.x, pt.y, val) }
  end

  v
end

#genAnchors(s = nil, set = [], tag = :box) ⇒ `Integer`

Identifies ‘leader line anchors’, i.e. specific 3D points of a (larger) set (e.g. delineating a larger, parent polygon), each anchor linking the BLC corner of one or more (smaller) subsets (free-floating within the parent)

see follow-up ‘genInserts’. Subsets may hold several ‘tagged’ vertices

(e.g. :box, :cbox). By default, the solution seeks to anchor subset :box vertices. Users can select other tags, e.g. tag == :cbox. The solution minimally validates individual subsets (e.g. no self-intersecting polygons, coplanarity, no inter-subset conflicts, must fit within larger set). Potential leader lines cannot intersect each other, similarly tagged subsets or (parent) polygon edges. For highly-articulated cases (e.g. a narrow parent polygon with multiple concavities, holding multiple subsets), such leader line conflicts are likely unavoidable. It is recommended to first sort subsets (e.g. areas), given the solution’s ‘first-come-first-served’ policy. Subsets without valid leader lines are ultimately ignored (check for new set :void keys, see error logs). The larger set of points is expected to be in space coordinates - not building or site coordinates, while subset points are expected to ‘fit?’ in the larger set.

Parameters:

s (Set<OpenStudio::Point3d>) (defaults to: nil) —

a (larger) parent set of points
set (Array<Hash>) (defaults to: []) —

a collection of (smaller) sequenced points
[Symbol] (Hash) —

a customizable set of options

Returns:

(Integer) —

number of successfully anchored subsets (see logs)

# File 'lib/osut/utils.rb', line 4510

def genAnchors(s = nil, set = [], tag = :box)
  mth = "OSut::#{__callee__}"
  n   = 0
  id  = s.respond_to?(:nameString) ? "#{s.nameString}: " : ""
  pts = poly(s)
  return invalid("#{id} polygon", mth, 1, DBG, n) if pts.empty?
  return mismatch("set", set, Array, mth, DBG, n) unless set.respond_to?(:to_a)

  origin = OpenStudio::Point3d.new(0,0,0)
  zenith = OpenStudio::Point3d.new(0,0,1)
  ray    = zenith - origin
  set    = set.to_a

  # Validate individual subsets. Purge surface-specific leader line anchors.
  set.each_with_index do |st, i|
    str1 = id + "subset ##{i+1}"
    str2 = str1 + " #{tag.to_s}"
    return mismatch(str1, st, Hash,  mth, DBG, n) unless st.respond_to?(:key?)
    return hashkey( str1, st,  tag,  mth, DBG, n) unless st.key?(tag)
    return empty("#{str2} vertices", mth, DBG, n) if st[tag].empty?

    if st.key?(:out)
      return hashkey( str1, st,   :t,  mth, DBG, n) unless st.key?(:t)
      return hashkey( str1, st,  :ti,  mth, DBG, n) unless st.key?(:ti)
      return hashkey( str1, st,  :t0,  mth, DBG, n) unless st.key?(:t0)
    end

    stt = poly(st[tag])
    return invalid("#{str2} polygon", mth, 0, DBG, n) if stt.empty?
    return invalid("#{str2} gap", mth, 0, DBG, n) unless fits?(stt, pts, true)

    if st.key?(:ld)
      ld = st[:ld]
      return invalid("#{str1} leaders", mth, 0, DBG, n) unless ld.is_a?(Hash)

      ld.reject! { |k, _| k == s }
    else
      st[:ld] = {}
    end
  end

  set.each_with_index do |st, i|
    # When a subset already holds a leader line anchor (from an initial call
    # to 'genAnchors'), it inherits key :out - a Hash holding (among others) a
    # 'realigned' set of points (by default a 'realigned' :box). The latter is
    # typically generated from an outdoor-facing roof (e.g. when called from
    # 'lights'). Subsequent calls to 'genAnchors' may send (as first
    # argument) a corresponding ceiling tile below (also from 'addSkylights').
    # Roof vs ceiling may neither share alignment transformation nor space
    # site transformation identities. All subsequent calls to 'genAnchors'
    # shall recover the :out points, apply a succession of de/alignments and
    # transformations in sync , and overwrite tagged points.
    #
    # Although 'genAnchors' and 'genInserts' have both been developed to
    # support anchor insertions in other cases (e.g. bay window in a wall),
    # variables and terminology here continue pertain to roofs, ceilings,
    # skylights and wells - less abstract, simpler to follow.
    if st.key?(:out)
      ti   = st[:ti ] # unoccupied attic/plenum space site transformation
      t0   = st[:t0 ] # occupied space site transformation
      t    = st[:t  ] # initial alignment transformation of roof surface
      o    = st[:out]
      tpts = t0.inverse * (ti * (t * (o[:r] * (o[:t] * o[:set]))))
      tpts = cast(tpts, pts, ray)

      st[tag] = tpts
    else
      st[:t] = OpenStudio::Transformation.alignFace(pts) unless st.key?(:t)
      tpts   = st[:t].inverse * st[tag]
      o      = getRealignedFace(tpts, true)
      tpts   = st[:t] * (o[:r] * (o[:t] * o[:set]))

      st[:out] = o
      st[tag ] = tpts
    end
  end

  # Identify candidate leader line anchors for each subset.
  set.each_with_index do |st, i|
    candidates = []
    tpts = st[tag]

    pts.each do |pt|
      ld = [pt, tpts.first]
      nb = 0

      # Check for intersections between leader line and larger polygon edges.
      getSegments(pts).each do |sg|
        break unless nb.zero?
        next if holds?(sg, pt)

        nb += 1 if lineIntersects?(sg, ld)
      end

      # Check for intersections between candidate leader line vs other subsets.
      set.each do |other|
        break unless nb.zero?
        next if st == other

        ost = other[tag]

        getSegments(ost).each { |sg| nb += 1 if lineIntersects?(ld, sg) }
      end

      # ... and previous leader lines (first come, first serve basis).
      set.each do |other|
        break unless nb.zero?
        next if st == other
        next unless other.key?(:ld)
        next unless other[:ld].key?(s)

        ost = other[tag]
        pld = other[:ld][s]
        next if same?(pld, pt)

        nb += 1 if lineIntersects?(ld, [pld, ost.first])
      end

      # Finally, check for self-intersections.
      getSegments(tpts).each do |sg|
        break unless nb.zero?
        next if holds?(sg, tpts.first)

        nb += 1 if lineIntersects?(sg, ld)
        nb += 1 if (sg.first - sg.last).cross(ld.first - ld.last).length < TOL
      end

      candidates << pt if nb.zero?
    end

    if candidates.empty?
      str = id + "set ##{i+1}"
      log(WRN, "#{str}: unable to anchor #{tag} leader line (#{mth})")
      st[:void] = true
    else
      p0 = candidates.sort_by { |pt| (pt - tpts.first).length }.first
      n += 1

      st[:ld][s] = p0
    end
  end

  n
end

#genConstruction(model = nil, specs = {}) ⇒ `OpenStudio::Model::Construction`^?

Generates an OpenStudio multilayered construction, + materials if needed.

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model
specs (Hash) (defaults to: {}) —

OpenStudio construction specifications

Options Hash (specs):

:id (#to_s) — default: "" —

construction identifier
:type (Symbol) — default: :wall —

, see @@uo
:uo (Numeric) —

assembly clear-field Uo, in W/m2•K, see @@uo
:clad (Symbol) — default: :light —

exterior cladding, see @@mass
:frame (Symbol) — default: :light —

assembly framing, see @@mass
:finish (Symbol) — default: :light —

interior finishing, see @@mass

Returns:

(OpenStudio::Model::Construction) —

generated construction
(nil) —

if invalid inputs (see logs)

# File 'lib/osut/utils.rb', line 208

def genConstruction(model = nil, specs = {})
  mth = "OSut::#{__callee__}"
  cl1 = OpenStudio::Model::Model
  cl2 = Hash
  return mismatch("model", model, cl1, mth) unless model.is_a?(cl1)
  return mismatch("specs", specs, cl2, mth) unless specs.is_a?(cl2)

  specs[:id] = "" unless specs.key?(:id)
  id = trim(specs[:id])
  id = "OSut|CON|#{specs[:type]}" if id.empty?

  specs[:type] = :wall unless specs.key?(:type)
  chk = @@uo.keys.include?(specs[:type])
  return invalid("surface type", mth, 2, ERR) unless chk

  specs[:uo] = @@uo[ specs[:type] ] unless specs.key?(:uo)
  u = specs[:uo]

  if u
    return mismatch("#{id} Uo", u, Numeric, mth)  unless u.is_a?(Numeric)
    return invalid("#{id} Uo (> 5.678)", mth, 2, ERR) if u > 5.678
    return negative("#{id} Uo"         , mth,    ERR) if u < 0
  end

  # Optional specs. Log/reset if invalid.
  specs[:clad  ] = :light             unless specs.key?(:clad  ) # exterior
  specs[:frame ] = :light             unless specs.key?(:frame )
  specs[:finish] = :light             unless specs.key?(:finish) # interior
  log(WRN, "Reset to light cladding") unless @@mass.include?(specs[:clad  ])
  log(WRN, "Reset to light framing" ) unless @@mass.include?(specs[:frame ])
  log(WRN, "Reset to light finish"  ) unless @@mass.include?(specs[:finish])
  specs[:clad  ] = :light             unless @@mass.include?(specs[:clad  ])
  specs[:frame ] = :light             unless @@mass.include?(specs[:frame ])
  specs[:finish] = :light             unless @@mass.include?(specs[:finish])

  film = @@film[ specs[:type] ]

  # Layered assembly (max 4 layers):
  #   - cladding
  #   - intermediate sheathing
  #   - composite insulating/framing
  #   - interior finish
  a = {clad: {}, sheath: {}, compo: {}, finish: {}, glazing: {}}

  case specs[:type]
  when :shading
    mt = :material
    d  = 0.015
    a[:compo][:mat] = @@mats[mt]
    a[:compo][:d  ] = d
    a[:compo][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
  when :partition
    unless specs[:clad] == :none
      d  = 0.015
      mt = :drywall
      a[:clad][:mat] = @@mats[mt]
      a[:clad][:d  ] = d
      a[:clad][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end

    d  = 0.015
    d  = 0.100      if specs[:frame] == :medium
    d  = 0.200      if specs[:frame] == :heavy
    d  = 0.100      if u
    mt = :concrete
    mt = :material  if specs[:frame] == :light
    mt = :mineral   if u
    a[:compo][:mat] = @@mats[mt]
    a[:compo][:d  ] = d
    a[:compo][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

    unless specs[:finish] == :none
      d  = 0.015
      mt = :drywall
      a[:finish][:mat] = @@mats[mt]
      a[:finish][:d  ] = d
      a[:finish][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end
  when :wall
    unless specs[:clad] == :none
      mt = :material
      mt = :brick    if specs[:clad] == :medium
      mt = :concrete if specs[:clad] == :heavy
      d  = 0.100
      d  = 0.015     if specs[:clad] == :light
      a[:clad][:mat] = @@mats[mt]
      a[:clad][:d  ] = d
      a[:clad][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end

    mt = :drywall
    mt = :mineral    if specs[:frame] == :medium
    mt = :polyiso    if specs[:frame] == :heavy
    d  = 0.100
    d  = 0.015       if specs[:frame] == :light
    a[:sheath][:mat] = @@mats[mt]
    a[:sheath][:d  ] = d
    a[:sheath][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

    mt = :mineral
    mt = :cellulose if specs[:frame] == :medium
    mt = :concrete  if specs[:frame] == :heavy
    mt = :material  unless u
    d  = 0.100
    d  = 0.200      if specs[:frame] == :heavy
    d  = 0.015      unless u

    a[:compo][:mat] = @@mats[mt]
    a[:compo][:d  ] = d
    a[:compo][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

    unless specs[:finish] == :none
      mt = :concrete
      mt = :drywall   if specs[:finish] == :light
      d  = 0.015
      d  = 0.100      if specs[:finish] == :medium
      d  = 0.200      if specs[:finish] == :heavy
      a[:finish][:mat] = @@mats[mt]
      a[:finish][:d  ] = d
      a[:finish][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end
  when :roof
    unless specs[:clad] == :none
      mt = :concrete
      mt = :material if specs[:clad] == :light
      d  = 0.015
      d  = 0.100     if specs[:clad] == :medium # e.g. terrace
      d  = 0.200     if specs[:clad] == :heavy  # e.g. parking garage
      a[:clad][:mat] = @@mats[mt]
      a[:clad][:d  ] = d
      a[:clad][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end

    mt = :mineral
    mt = :polyiso   if specs[:frame] == :medium
    mt = :cellulose if specs[:frame] == :heavy
    mt = :material  unless u
    d  = 0.100
    d  = 0.015      unless u
    a[:compo][:mat] = @@mats[mt]
    a[:compo][:d  ] = d
    a[:compo][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

    unless specs[:finish] == :none
      mt = :concrete
      mt = :drywall   if specs[:finish] == :light
      d  = 0.015
      d  = 0.100      if specs[:finish] == :medium # proxy for steel decking
      d  = 0.200      if specs[:finish] == :heavy
      a[:finish][:mat] = @@mats[mt]
      a[:finish][:d  ] = d
      a[:finish][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end
  when :floor
    unless specs[:clad] == :none
      mt = :material
      d  = 0.015
      a[:clad][:mat] = @@mats[mt]
      a[:clad][:d  ] = d
      a[:clad][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end

    mt = :mineral
    mt = :polyiso   if specs[:frame] == :medium
    mt = :cellulose if specs[:frame] == :heavy
    mt = :material  unless u
    d  = 0.100
    d  = 0.015      unless u
    a[:compo][:mat] = @@mats[mt]
    a[:compo][:d  ] = d
    a[:compo][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

    unless specs[:finish] == :none
      mt = :concrete
      mt = :material  if specs[:finish] == :light
      d  = 0.015
      d  = 0.100      if specs[:finish] == :medium
      d  = 0.200      if specs[:finish] == :heavy
      a[:finish][:mat] = @@mats[mt]
      a[:finish][:d  ] = d
      a[:finish][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end
  when :slab
    mt = :sand
    d  = 0.100
    a[:clad][:mat] = @@mats[mt]
    a[:clad][:d  ] = d
    a[:clad][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

    unless specs[:frame] == :none
      mt = :polyiso
      d  = 0.025
      a[:sheath][:mat] = @@mats[mt]
      a[:sheath][:d  ] = d
      a[:sheath][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end

    mt = :concrete
    d  = 0.100
    d  = 0.200      if specs[:frame] == :heavy
    a[:compo][:mat] = @@mats[mt]
    a[:compo][:d  ] = d
    a[:compo][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

    unless specs[:finish] == :none
      mt = :material
      d  = 0.015
      a[:finish][:mat] = @@mats[mt]
      a[:finish][:d  ] = d
      a[:finish][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    end
  when :basement
    unless specs[:clad] == :none
      mt = :concrete
      mt = :material if specs[:clad] == :light
      d  = 0.100
      d  = 0.015     if specs[:clad] == :light
      a[:clad][:mat] = @@mats[mt]
      a[:clad][:d  ] = d
      a[:clad][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

      mt = :polyiso
      d  = 0.025
      a[:sheath][:mat] = @@mats[mt]
      a[:sheath][:d  ] = d
      a[:sheath][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

      mt = :concrete
      d  = 0.200
      a[:compo][:mat] = @@mats[mt]
      a[:compo][:d  ] = d
      a[:compo][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
    else
      mt = :concrete
      d  = 0.200
      a[:sheath][:mat] = @@mats[mt]
      a[:sheath][:d  ] = d
      a[:sheath][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

      unless specs[:finish] == :none
        mt = :mineral
        d  = 0.075
        a[:compo][:mat] = @@mats[mt]
        a[:compo][:d  ] = d
        a[:compo][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"

        mt = :drywall
        d  = 0.015
        a[:finish][:mat] = @@mats[mt]
        a[:finish][:d  ] = d
        a[:finish][:id ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
      end
    end
  when :door
    mt = :door
    d  = 0.045

    a[:compo  ][:mat ] = @@mats[mt]
    a[:compo  ][:d   ] = d
    a[:compo  ][:id  ] = "OSut|#{mt}|#{format('%03d', d*1000)[-3..-1]}"
  when :window
    a[:glazing][:u   ]  = specs[:uo  ]
    a[:glazing][:shgc]  = 0.450
    a[:glazing][:shgc]  = specs[:shgc] if specs.key?(:shgc)
    a[:glazing][:id  ]  = "OSut|window"
    a[:glazing][:id  ] += "|U#{format('%.1f', a[:glazing][:u])}"
    a[:glazing][:id  ] += "|SHGC#{format('%d', a[:glazing][:shgc]*100)}"
  when :skylight
    a[:glazing][:u   ] = specs[:uo  ]
    a[:glazing][:shgc] = 0.450
    a[:glazing][:shgc] = specs[:shgc] if specs.key?(:shgc)
    a[:glazing][:id  ]  = "OSut|skylight"
    a[:glazing][:id  ] += "|U#{format('%.1f', a[:glazing][:u])}"
    a[:glazing][:id  ] += "|SHGC#{format('%d', a[:glazing][:shgc]*100)}"
  end

  # Initiate layers.
  glazed = true
  glazed = false if a[:glazing].empty?
  layers = OpenStudio::Model::OpaqueMaterialVector.new   unless glazed
  layers = OpenStudio::Model::FenestrationMaterialVector.new if glazed

  if glazed
    u    = a[:glazing][:u   ]
    shgc = a[:glazing][:shgc]
    lyr  = model.getSimpleGlazingByName(a[:glazing][:id])

    if lyr.empty?
      lyr = OpenStudio::Model::SimpleGlazing.new(model, u, shgc)
      lyr.setName(a[:glazing][:id])
    else
      lyr = lyr.get
    end

    layers << lyr
  else
    # Loop through each layer spec, and generate construction.
    a.each do |i, l|
      next if l.empty?

      lyr = model.getStandardOpaqueMaterialByName(l[:id])

      if lyr.empty?
        lyr = OpenStudio::Model::StandardOpaqueMaterial.new(model)
        lyr.setName(l[:id])
        lyr.setThickness(l[:d])
        lyr.setRoughness(         l[:mat][:rgh]) if l[:mat].key?(:rgh)
        lyr.setConductivity(      l[:mat][:k  ]) if l[:mat].key?(:k  )
        lyr.setDensity(           l[:mat][:rho]) if l[:mat].key?(:rho)
        lyr.setSpecificHeat(      l[:mat][:cp ]) if l[:mat].key?(:cp )
        lyr.setThermalAbsorptance(l[:mat][:thm]) if l[:mat].key?(:thm)
        lyr.setSolarAbsorptance(  l[:mat][:sol]) if l[:mat].key?(:sol)
        lyr.setVisibleAbsorptance(l[:mat][:vis]) if l[:mat].key?(:vis)
      else
        lyr = lyr.get
      end

      layers << lyr
    end
  end

  c  = OpenStudio::Model::Construction.new(layers)
  c.setName(id)

  # Adjust insulating layer thickness or conductivity to match requested Uo.
  unless glazed
    ro = 0
    ro = 1 / specs[:uo] - @@film[ specs[:type] ] if specs[:uo]

    if specs[:type] == :door # 1x layer, adjust conductivity
      layer = c.getLayer(0).to_StandardOpaqueMaterial
      return invalid("#{id} standard material?", mth, 0) if layer.empty?

      layer = layer.get
      k     = layer.thickness / ro
      layer.setConductivity(k)
    elsif ro > 0 # multiple layers, adjust insulating layer thickness
      lyr = insulatingLayer(c)
      return invalid("#{id} construction", mth, 0) if lyr[:index].nil?
      return invalid("#{id} construction", mth, 0) if lyr[:type ].nil?
      return invalid("#{id} construction", mth, 0) if lyr[:r    ].zero?

      index = lyr[:index]
      layer = c.getLayer(index).to_StandardOpaqueMaterial
      return invalid("#{id} material @#{index}", mth, 0) if layer.empty?

      layer = layer.get
      k     = layer.conductivity
      d     = (ro - rsi(c) + lyr[:r]) * k
      return invalid("#{id} adjusted m", mth, 0) if d < 0.03

      nom   = "OSut|"
      nom  += layer.nameString.gsub(/[^a-z]/i, "").gsub("OSut", "")
      nom  += "|"
      nom  += format("%03d", d*1000)[-3..-1]
      layer.setName(nom) if model.getStandardOpaqueMaterialByName(nom).empty?
      layer.setThickness(d)
    end
  end

  c
end

#genExtendedVertices(s = nil, set = [], tag = :vtx) ⇒ `OpenStudio::Point3dVector`

Extends (larger) polygon vertices to circumscribe one or more (smaller) subsets of vertices, based on previously-generated ‘leader line’ anchors. The solution minimally validates individual subsets (e.g. no self-intersecting polygons, coplanarity, no inter-subset conflicts, must fit within larger set). Valid leader line anchors (set key :ld) need to be generated prior to calling the method - see ‘genAnchors’. Subsets may hold several ‘tag’ged vertices (e.g. :box, :vtx). By default, the solution seeks to anchor subset :vtx vertices. Users can select other tags, e.g. tag == :box).

Parameters:

s (Set<OpenStudio::Point3d>) (defaults to: nil) —

a larger (parent) set of points
set (Array<Hash>) (defaults to: []) —

a collection of (smaller) sequenced vertices
[Symbol] (Hash) —

a customizable set of options

Options Hash (set):

:ld (Hash) —

a polygon-specific leader line anchors

Returns:

(OpenStudio::Point3dVector) —

extended vertices (see logs if empty)

# File 'lib/osut/utils.rb', line 4672

def genExtendedVertices(s = nil, set = [], tag = :vtx)
  mth = "OSut::#{__callee__}"
  id  = s.respond_to?(:nameString) ? "#{s.nameString}: " : ""
  f   = false
  pts = poly(s)
  cl  = OpenStudio::Point3d
  a   = OpenStudio::Point3dVector.new
  v   = []
  return a if pts.empty?
  return mismatch("set", set, Array, mth, DBG, a) unless set.respond_to?(:to_a)

  set = set.to_a

  # Validate individual sets.
  set.each_with_index do |st, i|
    str1 = id + "subset ##{i+1}"
    str2 = str1 + " #{tag.to_s}"
    next if st.key?(:void) && st[:void]
    return mismatch(str1, st,  Hash, mth, DBG, a) unless st.respond_to?(:key?)
    return hashkey( str1, st,   tag, mth, DBG, a) unless st.key?(tag)
    return empty("#{str2} vertices", mth, DBG, a) if st[tag].empty?
    return hashkey( str1, st,   :ld, mth, DBG, a) unless st.key?(:ld)

    stt = poly(st[tag])
    return invalid("#{str2} polygon", mth, 0, DBG, a) if stt.empty?

    ld = st[:ld]
    return mismatch(str, ld,  Hash, mth, DBG, a) unless ld.is_a?(Hash)
    return hashkey( str, ld,     s, mth, DBG, a) unless ld.key?(s)
    return mismatch(str, ld[s], cl, mth, DBG, a) unless ld[s].is_a?(cl)
  end

  # Re-sequence polygon vertices.
  pts.each do |pt|
    v << pt

    # Loop through each valid set; concatenate circumscribing vertices.
    set.each do |st|
      next if st.key?(:void) && st[:void]
      next unless same?(st[:ld][s], pt)
      next unless st.key?(tag)

      v += st[tag].to_a
      v << pt
    end
  end

  to_p3Dv(v)
end

#genInserts(s = nil, set = []) ⇒ `OpenStudio::Point3dVector`

Generates (1D or 2D) arrays of (smaller) rectangular collection of points, (e.g. arrays of polygon inserts) from subset parameters, within a (larger) set (e.g. parent polygon). If successful, each subset inherits additional key:value pairs: namely :vtx (collection of circumscribing vertices), and :vts (collection of individual insert vertices). Valid leader line anchors (set key :ld) need to be generated prior to calling the solution

see ‘genAnchors’.

Parameters:

s (Set<OpenStudio::Point3d>) (defaults to: nil) —

a larger (parent) set of points
set (Array<Hash>) (defaults to: []) —

a collection of (smaller) sequenced vertices

Options Hash (set):

:box (Set<OpenStudio::Point3d>) —

bounding box of each subset
:ld (Hash) —

a collection of leader line anchors
:rows (Integer) — default: 1 —

number of rows of inserts
:cols (Integer) — default: 1 —

number of columns of inserts
:w0 (Numeric) —

width of individual inserts (wrt cols) min 0.4
:d0 (Numeric) —

depth of individual inserts (wrt rows) min 0.4
:dX (Numeric) — default: 0 —

optional left/right X-axis buffer
:dY (Numeric) — default: 0 —

optional top/bottom Y-axis buffer

Returns:

(OpenStudio::Point3dVector) —

new polygon vertices (see logs if empty)

# File 'lib/osut/utils.rb', line 4743

def genInserts(s = nil, set = [])
  mth = "OSut::#{__callee__}"
  id  = s.respond_to?(:nameString) ? "#{s.nameString}:" : ""
  pts = poly(s)
  cl  = OpenStudio::Point3d
  a   = OpenStudio::Point3dVector.new
  return a if pts.empty?
  return mismatch("set", set, Array, mth, DBG, a) unless set.respond_to?(:to_a)

  set  = set.to_a
  gap  = 0.1
  gap4 = 0.4 # minimum insert width/depth

  # Validate/reset individual set collections.
  set.each_with_index do |st, i|
    str1 = id + "subset ##{i+1}"
    next if st.key?(:void) && st[:void]
    return mismatch(str1, st, Hash, mth, DBG, a) unless st.respond_to?(:key?)
    return hashkey( str1, st, :box, mth, DBG, a) unless st.key?(:box)
    return hashkey( str1, st,  :ld, mth, DBG, a) unless st.key?(:ld)
    return hashkey( str1, st, :out, mth, DBG, a) unless st.key?(:out)

    str2 = str1 + " anchor"
    ld = st[:ld]
    return mismatch(str2, ld,  Hash, mth, DBG, a) unless ld.respond_to?(:key?)
    return hashkey( str2, ld,     s, mth, DBG, a) unless ld.key?(s)
    return mismatch(str2, ld[s], cl, mth, DBG, a) unless ld[s].is_a?(cl)

    # Ensure each set bounding box is safely within larger polygon boundaries.
    # @todo: In line with related addSkylights' @todo, expand solution to
    #        safely handle 'side' cutouts (i.e. no need for leader lines). In
    #        so doing, boxes could eventually align along surface edges.
    str3 = str1 + " box"
    bx = poly(st[:box])
    return invalid(str3, mth, 0, DBG, a) if bx.empty?
    return invalid("#{str3} rectangle", mth, 0, DBG, a) unless rectangular?(bx)
    return invalid("#{str3} box", mth, 0, DBG, a) unless fits?(bx, pts, true)

    if st.key?(:rows)
      rws = st[:rows]
      return invalid("#{id} rows", mth, 0, DBG, a) unless rws.is_a?(Integer)
      return zero(   "#{id} rows", mth,    DBG, a)     if rws < 1
    else
      st[:rows] = 1
    end

    if st.key?(:cols)
      cls = st[:cols]
      return invalid("#{id} cols", mth, 0, DBG, a) unless cls.is_a?(Integer)
      return zero(   "#{id} cols", mth,    DBG, a)     if cls < 1
    else
      st[:cols] = 1
    end

    if st.key?(:w0)
      w0 = st[:w0]
      return invalid("#{id} width", mth, 0, DBG, a) unless w0.is_a?(Numeric)

      w0 = w0.to_f
      return zero("#{id} width", mth, DBG, a) if w0.round(2) < gap4
    else
      st[:w0] = 1.4
    end

    if st.key?(:d0)
      d0 = st[:d0]
      return invalid("#{id} depth", mth, 0, DBG, a) unless d0.is_a?(Numeric)

      d0 = d0.to_f
      return zero("#{id} depth", mth, DBG, a) if d0.round(2) < gap4
    else
      st[:d0] = 1.4
    end

    if st.key?(:dX)
      dX = st[:dX]
      return invalid( "#{id} dX", mth, 0, DBG, a) unless dX.is_a?(Numeric)
    else
      st[:dX] = nil
    end

    if st.key?(:dY)
      dY = st[:dY]
      return invalid( "#{id} dY", mth, 0, DBG, a) unless dY.is_a?(Numeric)
    else
      st[:dY] = nil
    end
  end

  # Flag conflicts between set bounding boxes. @todo: ease up for ridges.
  set.each_with_index do |st, i|
    bx = st[:box]
    next if st.key?(:void) && st[:void]

    set.each_with_index do |other, j|
      next if i == j

      bx2  = other[:box]
      str4 = id + "set boxes ##{i+1}:##{j+1}"
      next unless overlaps?(bx, bx2)
      return invalid("#{str4} (overlapping)", mth, 0, DBG, a)
    end
  end

  t    = OpenStudio::Transformation.alignFace(pts)
  rpts = t.inverse * pts

  # Loop through each 'valid' subset (i.e. linking a valid leader line anchor),
  # generate subset vertex array based on user-provided specs.
  set.each_with_index do |st, i|
    str = id + "subset ##{i+1}"
    next if st.key?(:void) && st[:void]

    o    = st[:out]
    vts  = {} # collection of individual (named) polygon insert vertices
    vtx  = [] # sequence of circumscribing polygon vertices
    bx   = o[:set]
    w    = width(bx)  # overall sandbox width
    d    = height(bx) # overall sandbox depth
    dX   = st[:dX  ]  # left/right buffer (array vs bx)
    dY   = st[:dY  ]  # top/bottom buffer (array vs bx)
    cols = st[:cols]  # number of array columns
    rows = st[:rows]  # number of array rows
    x    = st[:w0  ]  # width of individual insert
    y    = st[:d0  ]  # depth of individual insert
    gX   = 0          # gap between insert columns
    gY   = 0          # gap between insert rows

    # Gap between insert columns.
    if cols > 1
      dX = ( (w - cols * x) / cols) / 2 unless dX
      gX = (w - 2 * dX - cols * x) / (cols - 1)
      gX = gap if gX.round(2) < gap
      dX = (w - cols * x - (cols - 1) * gX) / 2
    else
      dX = (w - x) / 2
    end

    if dX.round(2) < 0
      log(ERR, "Skipping #{str}: Negative dX {#{mth}}")
      next
    end

    # Gap between insert rows.
    if rows > 1
      dY = ( (d - rows * y) / rows) / 2 unless dY
      gY = (d - 2 * dY - rows * y) / (rows - 1)
      gY = gap if gY.round(2) < gap
      dY = (d - rows * y - (rows - 1) * gY) / 2
    else
      dY = (d - y) / 2
    end

    if dY.round(2) < 0
      log(ERR, "Skipping #{str}: Negative dY {#{mth}}")
      next
    end

    st[:dX] = dX
    st[:gX] = gX
    st[:dY] = dY
    st[:gY] = gY

    x0 = bx.min_by(&:x).x + dX # X-axis starting point
    y0 = bx.min_by(&:y).y + dY # X-axis starting point
    xC = x0                    # current X-axis position
    yC = y0                    # current Y-axis position

    # BLC of array.
    vtx << OpenStudio::Point3d.new(xC, yC, 0)

    # Move up incrementally along left side of sandbox.
    rows.times.each do |iY|
      unless iY.zero?
        yC += gY
        vtx << OpenStudio::Point3d.new(xC, yC, 0)
      end

      yC += y
      vtx << OpenStudio::Point3d.new(xC, yC, 0)
    end

    # Loop through each row: left-to-right, then right-to-left.
    rows.times.each do |iY|
      (cols - 1).times.each do |iX|
        xC += x
        vtx << OpenStudio::Point3d.new(xC, yC, 0)

        xC += gX
        vtx << OpenStudio::Point3d.new(xC, yC, 0)
      end

      # Generate individual polygon inserts, left-to-right.
      cols.times.each do |iX|
        nom  = "#{i}:#{iX}:#{iY}"
        vec  = []
        vec << OpenStudio::Point3d.new(xC    , yC    , 0)
        vec << OpenStudio::Point3d.new(xC    , yC - y, 0)
        vec << OpenStudio::Point3d.new(xC + x, yC - y, 0)
        vec << OpenStudio::Point3d.new(xC + x, yC    , 0)

        # Store.
        vts[nom] = to_p3Dv(t * ulc(o[:r] * (o[:t] * vec)))

        # Add reverse vertices, circumscribing each insert.
        vec.reverse!
        vec.pop if iX == cols - 1
        vtx += vec

        xC -= gX + x unless iX == cols - 1
      end

      unless iY == rows - 1
        yC -= gY + y
        vtx << OpenStudio::Point3d.new(xC, yC, 0)
      end
    end

    st[:vts] = vts
    st[:vtx] = to_p3Dv(t * (o[:r] * (o[:t] * vtx)))
  end

  # Extended vertex sequence of the larger polygon.
  genExtendedVertices(s, set)
end

#genMass(sps = OpenStudio::Model::SpaceVector.new, ratio = 2.0) ⇒ `Bool`, `false`

Generates an internal mass definition and instances for target spaces.

Parameters:

sps (OpenStudio::Model::SpaceVector) (defaults to: OpenStudio::Model::SpaceVector.new) —

target spaces
ratio (Numeric) (defaults to: 2.0) —

internal mass surface / floor areas

Returns:

(Bool) —

whether successfully generated
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 675

def genMass(sps = OpenStudio::Model::SpaceVector.new, ratio = 2.0)
  # This is largely adapted from OpenStudio-Standards:
  #
  #   https://github.com/NREL/openstudio-standards/blob/
  #   d332605c2f7a35039bf658bf55cad40a7bcac317/lib/openstudio-standards/
  #   prototypes/common/objects/Prototype.Model.rb#L786
  mth = "OSut::#{__callee__}"
  cl1 = OpenStudio::Model::SpaceVector
  cl2 = Numeric
  no  = false
  return mismatch("spaces",   sps, cl1, mth, DBG, no) unless sps.is_a?(cl1)
  return mismatch( "ratio", ratio, cl2, mth, DBG, no) unless ratio.is_a?(cl2)
  return empty(   "spaces",             mth, WRN, no)     if sps.empty?
  return negative( "ratio",             mth, ERR, no)     if ratio < 0

  # A single material.
  mdl = sps.first.model
  id  = "OSut|MASS|Material"
  mat = mdl.getOpaqueMaterialByName(id)

  if mat.empty?
    mat = OpenStudio::Model::StandardOpaqueMaterial.new(mdl)
    mat.setName(id)
    mat.setRoughness("MediumRough")
    mat.setThickness(0.15)
    mat.setConductivity(1.12)
    mat.setDensity(540)
    mat.setSpecificHeat(1210)
    mat.setThermalAbsorptance(0.9)
    mat.setSolarAbsorptance(0.7)
    mat.setVisibleAbsorptance(0.17)
  else
    mat = mat.get
  end

  # A single, 1x layered construction.
  id  = "OSut|MASS|Construction"
  con = mdl.getConstructionByName(id)

  if con.empty?
    con = OpenStudio::Model::Construction.new(mdl)
    con.setName(id)
    layers = OpenStudio::Model::MaterialVector.new
    layers << mat
    con.setLayers(layers)
  else
    con = con.get
  end

  id = "OSut|InternalMassDefinition|" + (format "%.2f", ratio)
  df = mdl.getInternalMassDefinitionByName(id)

  if df.empty?
    df = OpenStudio::Model::InternalMassDefinition.new(mdl)
    df.setName(id)
    df.setConstruction(con)
    df.setSurfaceAreaperSpaceFloorArea(ratio)
  else
    df = df.get
  end

  sps.each do |sp|
    mass = OpenStudio::Model::InternalMass.new(df)
    mass.setName("OSut|InternalMass|#{sp.nameString}")
    mass.setSpace(sp)
  end

  true
end

#genShade(subs = OpenStudio::Model::SubSurfaceVector.new) ⇒ `Bool`, `false`

Generates a solar shade (e.g. roller, textile) for glazed OpenStudio SubSurfaces (v351+), controlled to minimize overheating in cooling months (May to October in Northern Hemisphere), when outdoor dry bulb temperature is above 18°C and impinging solar radiation is above 100 W/m2.

Parameters:

subs (OpenStudio::Model::SubSurfaceVector) (defaults to: OpenStudio::Model::SubSurfaceVector.new) —

sub surfaces

Returns:

(Bool) —

whether successfully generated
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 581

def genShade(subs = OpenStudio::Model::SubSurfaceVector.new)
  # Filter OpenStudio warnings for ShadingControl:
  #   ref: https://github.com/NREL/OpenStudio/issues/4911
  str = ".*(?<!ShadingControl)$"
  OpenStudio::Logger.instance.standardOutLogger.setChannelRegex(str)

  mth = "OSut::#{__callee__}"
  v   = OpenStudio.openStudioVersion.split(".").join.to_i
  cl  = OpenStudio::Model::SubSurfaceVector
  return mismatch("subs ", subs,  cl2, mth, DBG, false) unless subs.is_a?(cl)
  return empty(   "subs",              mth, WRN, false)     if subs.empty?
  return false                                              if v < 321

  # Shading availability period.
  mdl   = subs.first.model
  id    = "onoff"
  onoff = mdl.getScheduleTypeLimitsByName(id)

  if onoff.empty?
    onoff = OpenStudio::Model::ScheduleTypeLimits.new(mdl)
    onoff.setName(id)
    onoff.setLowerLimitValue(0)
    onoff.setUpperLimitValue(1)
    onoff.setNumericType("Discrete")
    onoff.setUnitType("Availability")
  else
    onoff = onoff.get
  end

  # Shading schedule.
  id  = "OSut|SHADE|Ruleset"
  sch = mdl.getScheduleRulesetByName(id)

  if sch.empty?
    sch = OpenStudio::Model::ScheduleRuleset.new(mdl, 0)
    sch.setName(id)
    sch.setScheduleTypeLimits(onoff)
    sch.defaultDaySchedule.setName("OSut|Shade|Ruleset|Default")
  else
    sch = sch.get
  end

  # Summer cooling rule.
  id   = "OSut|SHADE|ScheduleRule"
  rule = mdl.getScheduleRuleByName(id)

  if rule.empty?
    may     = OpenStudio::MonthOfYear.new("May")
    october = OpenStudio::MonthOfYear.new("Oct")
    start   = OpenStudio::Date.new(may, 1)
    finish  = OpenStudio::Date.new(october, 31)

    rule = OpenStudio::Model::ScheduleRule.new(sch)
    rule.setName(id)
    rule.setStartDate(start)
    rule.setEndDate(finish)
    rule.setApplyAllDays(true)
    rule.daySchedule.setName("OSut|Shade|Rule|Default")
    rule.daySchedule.addValue(OpenStudio::Time.new(0,24,0,0), 1)
  else
    rule = rule.get
  end

  # Shade object.
  id  = "OSut|Shade"
  shd = mdl.getShadeByName(id)

  if shd.empty?
    shd = OpenStudio::Model::Shade.new(mdl)
    shd.setName(id)
  else
    shd = shd.get
  end

  # Shading control (unique to each call).
  id  = "OSut|ShadingControl"
  ctl = OpenStudio::Model::ShadingControl.new(shd)
  ctl.setName(id)
  ctl.setSchedule(sch)
  ctl.setShadingControlType("OnIfHighOutdoorAirTempAndHighSolarOnWindow")
  ctl.setSetpoint(18)   # °C
  ctl.setSetpoint2(100) # W/m2
  ctl.setMultipleSurfaceControlType("Group")
  ctl.setSubSurfaces(subs)
end

#genSlab(pltz = [], z = 0) ⇒ `OpenStudio::Point3dVector`

Generates an OpenStudio 3D point vector of a composite floor “slab”, a ‘union’ of multiple rectangular, horizontal floor “plates”. Each plate must either share an edge with (or encompass or overlap) any of the preceding plates in the array. The generated slab may not be convex.

Parameters:

pltz (Array<Hash>) (defaults to: []) —

individual floor plates, each holding:
z (Numeric) (defaults to: 0) —

Z-axis coordinate

Options Hash (pltz):

:x (Numeric) —

left corner of plate origin (bird’s eye view)
:y (Numeric) —

bottom corner of plate origin (bird’s eye view)
:dx (Numeric) —

plate width (bird’s eye view)
:dy (Numeric) —

plate depth (bird’s eye view)

Returns:

(OpenStudio::Point3dVector) —

slab vertices (see logs if empty)

# File 'lib/osut/utils.rb', line 5079

def genSlab(pltz = [], z = 0)
  mth = "OSut::#{__callee__}"
  slb = OpenStudio::Point3dVector.new
  bkp = OpenStudio::Point3dVector.new
  cl1 = Array
  cl2 = Hash
  cl3 = Numeric

  # Input validation.
  return mismatch("plates", pltz, cl1, mth, DBG, slb) unless pltz.is_a?(cl1)
  return mismatch(     "Z",    z, cl3, mth, DBG, slb) unless z.is_a?(cl3)

  pltz.each_with_index do |plt, i|
    id = "plate # #{i+1} (index #{i})"

    return mismatch(id, plt, cl1, mth, DBG, slb) unless plt.is_a?(cl2)
    return hashkey( id, plt,  :x, mth, DBG, slb) unless plt.key?(:x )
    return hashkey( id, plt,  :y, mth, DBG, slb) unless plt.key?(:y )
    return hashkey( id, plt, :dx, mth, DBG, slb) unless plt.key?(:dx)
    return hashkey( id, plt, :dy, mth, DBG, slb) unless plt.key?(:dy)

    x  = plt[:x ]
    y  = plt[:y ]
    dx = plt[:dx]
    dy = plt[:dy]

    return mismatch("#{id} X",   x, cl3, mth, DBG, slb) unless  x.is_a?(cl3)
    return mismatch("#{id} Y",   y, cl3, mth, DBG, slb) unless  y.is_a?(cl3)
    return mismatch("#{id} dX", dx, cl3, mth, DBG, slb) unless dx.is_a?(cl3)
    return mismatch("#{id} dY", dy, cl3, mth, DBG, slb) unless dy.is_a?(cl3)
    return zero(    "#{id} dX",          mth, ERR, slb)     if dx.abs < TOL
    return zero(    "#{id} dY",          mth, ERR, slb)     if dy.abs < TOL
  end

  # Join plates.
  pltz.each_with_index do |plt, i|
    id = "plate # #{i+1} (index #{i})"
    x  = plt[:x ]
    y  = plt[:y ]
    dx = plt[:dx]
    dy = plt[:dy]

    # Adjust X if dX < 0.
    x -= -dx if dx < 0
    dx = -dx if dx < 0

    # Adjust Y if dY < 0.
    y -= -dy if dy < 0
    dy = -dy if dy < 0

    vtx  = []
    vtx << OpenStudio::Point3d.new(x + dx, y + dy, 0)
    vtx << OpenStudio::Point3d.new(x + dx, y,      0)
    vtx << OpenStudio::Point3d.new(x,      y,      0)
    vtx << OpenStudio::Point3d.new(x,      y + dy, 0)

    if slb.empty?
      slb = vtx
    else
      slab = OpenStudio.join(slb, vtx, TOL2)
      slb  = slab.get                  unless slab.empty?
      return invalid(id, mth, 0, ERR, bkp) if slab.empty?
    end
  end

  # Once joined, re-adjust Z-axis coordinates.
  unless z.zero?
    vtx = OpenStudio::Point3dVector.new
    slb.each { |pt| vtx << OpenStudio::Point3d.new(pt.x, pt.y, z) }
    slb = vtx
  end

  slb
end

#getCollinears(pts = nil, n = 0) ⇒ `OpenStudio::Point3dVector`

Returns sequential collinear points in an OpenStudio 3D point vector.

Parameters:

pts (Set<OpenStudio::Point3d] 3D points) (defaults to: nil) —

ts [Set<OpenStudio::Point3d] 3D points
n (#to_i) (defaults to: 0) —

requested number of collinears (0 returns all)

Returns:

(OpenStudio::Point3dVector) —

collinears (see logs if empty)

# File 'lib/osut/utils.rb', line 3192

def getCollinears(pts = nil, n = 0)
  mth = "OSut::#{__callee__}"
  pts = getUniques(pts)
  ok  = n.respond_to?(:to_i)
  v   = OpenStudio::Point3dVector.new
  return pts if pts.size < 3
  return mismatch("n collinears", n, Integer, mth, DBG, v) unless ok

  ncolls = getNonCollinears(pts)
  return pts if ncolls.empty?

  to_p3Dv( pts.delete_if { |pt| holds?(ncolls, pt) } )
end

#getHorizontalRidges(roofs = []) ⇒ `Array`

Identifies horizontal ridges along 2x sloped (roof?) surfaces (same space). The concept of ‘sloped’ is harmonized with OpenStudio’s “alignZPrime”. If successful, the returned Array holds ‘ridge’ Hashes. Each Hash holds: an :edge (OpenStudio::Point3dVector), the edge :length (Numeric), and :roofs (Array of 2x linked surfaces). Each surface may be linked to more than one horizontal ridge.

Parameters:

roofs (Array<OpenStudio::Model::Surface>) (defaults to: []) —

target surfaces

Returns:

(Array) —

horizontal ridges (see logs if empty)

# File 'lib/osut/utils.rb', line 6019

def getHorizontalRidges(roofs = [])
  mth    = "OSut::#{__callee__}"
  ridges = []
  return ridges unless roofs.is_a?(Array)

  roofs = roofs.select { |s| s.is_a?(OpenStudio::Model::Surface) }
  roofs = roofs.select { |s| sloped?(s) }

  roofs.each do |roof|
    maxZ = roof.vertices.max_by(&:z).z
    next if roof.space.empty?

    space = roof.space.get

    getSegments(roof).each do |edge|
      next unless xyz?(edge, :z, maxZ)

      # Skip if already tracked.
      match = false

      ridges.each do |ridge|
        break if match

        edg   = ridge[:edge]
        match = same?(edge, edg) || same?(edge, edg.reverse)
      end

      next if match

      ridge = { edge: edge, length: (edge[1] - edge[0]).length, roofs: [roof] }

      # Links another roof (same space)?
      match = false

      roofs.each do |ruf|
        break if match
        next  if ruf == roof
        next  if ruf.space.empty?
        next  unless ruf.space.get == space

        getSegments(ruf).each do |edg|
          break    if match
          next unless same?(edge, edg) || same?(edge, edg.reverse)

          ridge[:roofs] << ruf
          ridges << ridge
          match = true
        end
      end
    end
  end

  ridges
end

#getLineIntersection(s1 = [], s2 = []) ⇒ `OpenStudio::Point3d`^?

Returns point of intersection of 2x 3D line segments.

Parameters:

s1 (Set<OpenStudio::Point3d] 1st 3D line segment) (defaults to: []) —

1 [Set<OpenStudio::Point3d] 1st 3D line segment
s2 (Set<OpenStudio::Point3d] 2nd 3D line segment) (defaults to: []) —

2 [Set<OpenStudio::Point3d] 2nd 3D line segment

Returns:

(OpenStudio::Point3d) —

point of intersection of both lines
(nil) —

if no intersection, equal, or invalid input (see logs)

# File 'lib/osut/utils.rb', line 2961

def getLineIntersection(s1 = [], s2 = [])
  s1  = getSegments(s1)
  s2  = getSegments(s2)
  return nil if s1.empty?
  return nil if s2.empty?

  s1 = s1.first
  s2 = s2.first

  # Matching segments?
  return nil if same?(s1, s2)
  return nil if same?(s1, s2.to_a.reverse)

  a1 = s1[0]
  a2 = s1[1]
  b1 = s2[0]
  b2 = s2[1]

  # Matching segment endpoints?
  return a1 if same?(a1, b1)
  return a2 if same?(a2, b1)
  return a1 if same?(a1, b2)
  return a2 if same?(a2, b2)

  # Segment endpoint along opposite segment?
  return a1 if pointAlongSegments?(a1, s2)
  return a2 if pointAlongSegments?(a2, s2)
  return b1 if pointAlongSegments?(b1, s1)
  return b2 if pointAlongSegments?(b2, s1)

  # Line segments as vectors. Skip if colinear.
  a   = a2 - a1
  b   = b2 - b1
  xab = a.cross(b)
  return nil if xab.length.round(4) < TOL2

  # Link 1st point to other segment endpoints as vectors. Must be coplanar.
  a1b1  = b1 - a1
  a1b2  = b2 - a1
  xa1b1 = a.cross(a1b1)
  xa1b2 = a.cross(a1b2)
  xa1b1.normalize
  xa1b2.normalize
  xab.normalize
  return nil unless xab.cross(xa1b1).length.round(4) < TOL2
  return nil unless xab.cross(xa1b2).length.round(4) < TOL2

  # Reset.
  xa1b1 = a.cross(a1b1)
  xa1b2 = a.cross(a1b2)

  # Both segment endpoints can't be 'behind' point.
  return nil if a.dot(a1b1) < 0 && a.dot(a1b2) < 0

  # Both in 'front' of point? Pick farthest from 'a'.
  if a.dot(a1b1) > 0 && a.dot(a1b2) > 0
    lxa1b1 = xa1b1.length
    lxa1b2 = xa1b2.length

    c1 = lxa1b1.round(4) < lxa1b2.round(4) ? b1 : b2
  else
    c1 = a.dot(a1b1) > 0 ? b1 : b2
  end

  c1a1  = a1 - c1
  xc1a1 = a.cross(c1a1)
  d1    = a1 + xc1a1
  n     = a.cross(xc1a1)
  dot   = b.dot(n)
  n     = n.reverseVector if dot < 0
  f     = c1a1.dot(n) / b.dot(n)
  p0    = c1 + scalar(b, f)

  # Intersection can't be 'behind' point.
  return nil if a.dot(p0 - a1) < 0

  # Ensure intersection is sandwiched between endpoints.
  return nil unless pointAlongSegments?(p0, s2) && pointAlongSegments?(p0, s1)

  p0
end

#getNonCollinears(pts = nil, n = 0) ⇒ `OpenStudio::Point3dVector`

Returns sequential non-collinear points in an OpenStudio 3D point vector.

Parameters:

pts (Set<OpenStudio::Point3d] 3D points) (defaults to: nil) —

ts [Set<OpenStudio::Point3d] 3D points
n (#to_i) (defaults to: 0) —

requested number of non-collinears (0 returns all)

Returns:

(OpenStudio::Point3dVector) —

non-collinears (see logs if empty)

# File 'lib/osut/utils.rb', line 3151

def getNonCollinears(pts = nil, n = 0)
  mth = "OSut::#{__callee__}"
  pts = getUniques(pts)
  ok  = n.respond_to?(:to_i)
  v   = OpenStudio::Point3dVector.new
  a   = []
  return pts if pts.size < 3
  return mismatch("n non-collinears", n, Integer, mth, DBG, v) unless ok

  # Evaluate cross product of vectors of 3x sequential points.
  pts.each_with_index do |p2, i2|
    i1  = i2 - 1
    i3  = i2 + 1
    i3  = 0 if i3 == pts.size
    p1  = pts[i1]
    p3  = pts[i3]
    v13 = p3 - p1
    v12 = p2 - p1
    next if v12.cross(v13).length < TOL2

    a << p2
  end

  if holds?(a, pts[0])
    a = a.rotate(-1) unless same?(a[0], pts[0])
  end

  n = n.to_i
  a = a[0..n-1]  if n > 0
  a = a[n-1..-1] if n < 0

  to_p3Dv(a)
end

#getRealignedFace(pts = nil, force = false) ⇒ `Hash`

Generates re-‘aligned’ polygon vertices wrt main axis of symmetry of its largest bounded box. Input polygon vertex Z-axis values must equal 0, and be counterclockwise. A Hash is returned with 6x key:value pairs … set: realigned (cloned) polygon vertices, box: its bounded box (wrt to :set), bbox: its bounding box, t: its translation transformation, r: its rotation transformation, and o: the origin coordinates of its axis of rotation. First, cloned polygon vertices are rotated so the longest axis of symmetry of its bounded box lies parallel to the X-axis; :o being the midpoint of the narrow side (of the bounded box) nearest to grid origin (0,0,0). If the axis of symmetry of the bounded box is already parallel to the X-axis, then the rotation step is skipped (unless force == true). Whether rotated or not, polygon vertices are then translated as to ensure one or more vertices are aligned along the X-axis and one or more vertices are aligned along the Y-axis (no vertices with negative X or Y coordinate values). To unalign the returned set of vertices (or its bounded box, or its bounding box), first inverse the translation transformation, then inverse the rotation transformation.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points
force (Bool) (defaults to: false) —

whether to force rotation for aligned yet narrow boxes

Returns:

(Hash) —

:set, :box, :bbox, :t, :r & :o
(Hash) —

:set, :box, :bbox, :t, :r & :o (nil) if invalid (see logs)

# File 'lib/osut/utils.rb', line 4352

def getRealignedFace(pts = nil, force = false)
  mth = "OSut::#{__callee__}"
  out = { set: nil, box: nil, bbox: nil, t: nil, r: nil, o: nil }
  pts = poly(pts, false, true)
  return out if pts.empty?
  return invalid("aligned plane", mth, 1, DBG, out) unless xyz?(pts, :z)
  return invalid("clockwise pts", mth, 1, DBG, out)     if clockwise?(pts)

  # Optionally force rotation so bounded box ends up wider than taller.
  # Strongly suggested for flat surfaces like roofs (see 'sloped?').
  unless [true, false].include?(force)
    log(DBG, "Ignoring force input (#{mth})")
    force = false
  end

  o   = OpenStudio::Point3d.new(0, 0, 0)
  w   = width(pts)
  h   = height(pts)
  d   = h > w ? h : w
  sgs = {}
  box = boundedBox(pts)
  return invalid("bounded box", mth, 0, DBG, out) if box.empty?

  segments = getSegments(box)
  return invalid("bounded box segments", mth, 0, DBG, out) if segments.empty?

  # Deterministic ID of box rotation/translation 'origin'.
  segments.each_with_index do |sg, idx|
    sgs[sg]       = {}
    sgs[sg][:idx] = idx
    sgs[sg][:mid] = midpoint(sg[0], sg[1])
    sgs[sg][:l  ] = (sg[1] - sg[0]).length
    sgs[sg][:mo ] = (sgs[sg][:mid] - o).length
  end

  sgs = sgs.sort_by { |sg, s| s[:mo] }.first(2).to_h     if square?(box)
  sgs = sgs.sort_by { |sg, s| s[:l ] }.first(2).to_h unless square?(box)
  sgs = sgs.sort_by { |sg, s| s[:mo] }.first(2).to_h unless square?(box)
  sg0 = sgs.values[0]
  sg1 = sgs.values[1]

  if (sg0[:mo]).round(2) == (sg1[:mo]).round(2)
    i = sg1[:mid].y.round(2) < sg0[:mid].y.round(2) ? sg1[:idx] : sg0[:idx]
  else
    i = sg0[:idx]
  end

  k = i + 2 < segments.size ? i + 2 : i - 2

  origin   = midpoint(segments[i][0], segments[i][1])
  terminal = midpoint(segments[k][0], segments[k][1])
  seg      = terminal - origin
  right    = OpenStudio::Point3d.new(origin.x + d, origin.y    , 0) - origin
  north    = OpenStudio::Point3d.new(origin.x,     origin.y + d, 0) - origin
  axis     = OpenStudio::Point3d.new(origin.x,     origin.y    , d) - origin
  angle    = OpenStudio::getAngle(right, seg)
  angle    = -angle if north.dot(seg) < 0

  # Skip rotation if bounded box is already aligned along XY grid (albeit
  # 'narrow'), i.e. if the angle is 90°.
  if angle.round(3) == (Math::PI/2).round(3)
    angle = 0 unless force
  end

  r        = OpenStudio.createRotation(origin, axis, angle)
  pts      = to_p3Dv(r.inverse * pts)
  box      = to_p3Dv(r.inverse * box)
  dX       = pts.min_by(&:x).x
  dY       = pts.min_by(&:y).y
  xy       = OpenStudio::Point3d.new(origin.x + dX, origin.y + dY, 0)
  origin2  = xy - origin
  t        = OpenStudio.createTranslation(origin2)
  set      = to_p3Dv(t.inverse * pts)
  box      = to_p3Dv(t.inverse * box)
  bbox     = outline([set])

  out[:set ] = blc(set)
  out[:box ] = blc(box)
  out[:bbox] = blc(bbox)
  out[:t   ] = t
  out[:r   ] = r
  out[:o   ] = origin

  out
end

#getRoofs(spaces = []) ⇒ `Array<OpenStudio::Model::Surface>`

Returns outdoor-facing, space-related roof surfaces. These include outdoor-facing roofs of each space per se, as well as any outdoor-facing roof surface of unoccupied spaces immediately above (e.g. plenums, attics) overlapping any of the ceiling surfaces of each space. It does not include surfaces labelled as ‘RoofCeiling’, which do not comply with ASHRAE 90.1 or NECB tilt criteria - see ‘roof?’.

Parameters:

spaces (Set<OpenStudio::Model::Space>) (defaults to: []) —

target spaces

Returns:

(Array<OpenStudio::Model::Surface>) —

roofs (may be empty)

# File 'lib/osut/utils.rb', line 5165

def getRoofs(spaces = [])
  mth    = "OSut::#{__callee__}"
  up     = OpenStudio::Point3d.new(0,0,1) - OpenStudio::Point3d.new(0,0,0)
  roofs  = []
  spaces = spaces.is_a?(OpenStudio::Model::Space) ? [spaces] : spaces
  spaces = spaces.respond_to?(:to_a) ? spaces.to_a : []

  spaces = spaces.select { |space| space.is_a?(OpenStudio::Model::Space) }

  # Space-specific outdoor-facing roof surfaces.
  roofs = facets(spaces, "Outdoors", "RoofCeiling")
  roofs = roofs.select { |roof| roof?(roof) }

  spaces.each do |space|
    # When unoccupied spaces are involved (e.g. plenums, attics), the target
    # space may not share the same local transformation as the space(s) above.
    # Fetching site transformation.
    t0 = transforms(space)
    next unless t0[:t]

    t0 = t0[:t]

    facets(space, "Surface", "RoofCeiling").each do |ceiling|
      cv0 = t0 * ceiling.vertices

      floor = ceiling.adjacentSurface
      next if floor.empty?

      other = floor.get.space
      next if other.empty?

      other = other.get
      next if other.partofTotalFloorArea

      ti = transforms(other)
      next unless ti[:t]

      ti = ti[:t]

      # @todo: recursive call for stacked spaces as atria (via AirBoundaries).
      facets(other, "Outdoors", "RoofCeiling").each do |ruf|
        next unless roof?(ruf)

        rvi = ti * ruf.vertices
        cst = cast(cv0, rvi, up)
        next unless overlaps?(cst, rvi, false)

        roofs << ruf unless roofs.include?(ruf)
      end
    end
  end

  roofs
end

#getSegments(pts = nil) ⇒ `OpenStudio::Point3dVectorVector`

Returns paired sequential points as (non-zero length) line segments. If the set strictly holds 2x unique points, a single segment is returned. Otherwise, the returned number of segments equals the number of unique points.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(OpenStudio::Point3dVectorVector) —

line segments (see logs if empty)

# File 'lib/osut/utils.rb', line 2806

def getSegments(pts = nil)
  mth = "OSut::#{__callee__}"
  vv  = OpenStudio::Point3dVectorVector.new
  pts = getUniques(pts)
  return vv if pts.size < 2

  pts.each_with_index do |p1, i1|
    i2 = i1 + 1
    i2 = 0 if i2 == pts.size
    p2 = pts[i2]

    line = OpenStudio::Point3dVector.new
    line << p1
    line << p2
    vv   << line
    break if pts.size == 2
  end

  vv
end

#getTriads(pts = nil, co = false) ⇒ `OpenStudio::Point3dVectorVector`

Returns points as (non-zero length) ‘triads’, i.e. 3x sequential points. If the set holds less than 3x unique points, an empty triad is returned. Otherwise, the returned number of triads equals the number of unique points. If non-collinearity is requested, then the number of returned triads equals the number of non-collinear points.

Parameters:

pts (OpenStudio::Point3dVector) (defaults to: nil) —

3D points

Returns:

(OpenStudio::Point3dVectorVector) —

triads (see logs if empty)

# File 'lib/osut/utils.rb', line 2853

def getTriads(pts = nil, co = false)
  mth = "OSut::#{__callee__}"
  vv  = OpenStudio::Point3dVectorVector.new
  pts = getUniques(pts)
  return vv if pts.size < 2

  pts.each_with_index do |p1, i1|
    i2 = i1 + 1
    i2 = 0 if i2 == pts.size
    i3 = i2 + 1
    i3 = 0 if i3 == pts.size
    p2 = pts[i2]
    p3 = pts[i3]

    tri = OpenStudio::Point3dVector.new
    tri << p1
    tri << p2
    tri << p3
    vv  << tri
  end

  vv
end

#getUniques(pts = nil, n = 0) ⇒ `OpenStudio::Point3dVector`

Returns unique OpenStudio 3D points from an OpenStudio 3D point vector.

Parameters:

pts (Set<OpenStudio::Point3d] 3D points) (defaults to: nil) —

ts [Set<OpenStudio::Point3d] 3D points
n (#to_i) (defaults to: 0) —

requested number of unique points (0 returns all)

Returns:

(OpenStudio::Point3dVector) —

unique points (see logs if empty)

# File 'lib/osut/utils.rb', line 2779

def getUniques(pts = nil, n = 0)
  mth = "OSut::#{__callee__}"
  pts = to_p3Dv(pts)
  ok  = n.respond_to?(:to_i)
  v   = OpenStudio::Point3dVector.new
  return v if pts.empty?
  return mismatch("n unique points", n, Integer, mth, DBG, v) unless ok

  pts.each { |pt| v << pt unless holds?(v, pt) }

  n = n.to_i
  n = 0    unless n.abs < v.size
  v = v[0..n]  if n > 0
  v = v[n..-1] if n < 0

  v
end

#glazingAirFilmRSi(usi = 5.85) ⇒ `Float`, `0.1216`

Returns total air film resistance of a fenestrated construction (m2•K/W)

Parameters:

usi (Numeric) (defaults to: 5.85) —

a fenestrated construction’s U-factor (W/m2•K)

Returns:

(Float) —

total air film resistances
(0.1216) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 941

def glazingAirFilmRSi(usi = 5.85)
  # The sum of thermal resistances of calculated exterior and interior film
  # coefficients under standard winter conditions are taken from:
  #
  #   https://bigladdersoftware.com/epx/docs/9-6/engineering-reference/
  #   window-calculation-module.html#simple-window-model
  #
  # These remain acceptable approximations for flat windows, yet likely
  # unsuitable for subsurfaces with curved or projecting shapes like domed
  # skylights. The solution here is considered an adequate fix for reporting,
  # awaiting eventual OpenStudio (and EnergyPlus) upgrades to report NFRC 100
  # (or ISO) air film resistances under standard winter conditions.
  #
  # For U-factors above 8.0 W/m2•K (or invalid input), the function returns
  # 0.1216 m2•K/W, which corresponds to a construction with a single glass
  # layer thickness of 2mm & k = ~0.6 W/m.K.
  #
  # The EnergyPlus Engineering calculations were designed for vertical
  # windows - not horizontal, slanted or domed surfaces - use with caution.
  mth = "OSut::#{__callee__}"
  cl  = Numeric
  return mismatch("usi", usi, cl, mth,    DBG, 0.1216)  unless usi.is_a?(cl)
  return invalid("usi",           mth, 1, WRN, 0.1216)      if usi > 8.0
  return negative("usi",          mth,    WRN, 0.1216)      if usi < 0
  return zero("usi",              mth,    WRN, 0.1216)      if usi.abs < TOL

  rsi = 1 / (0.025342 * usi + 29.163853) # exterior film, next interior film
  return rsi + 1 / (0.359073 * Math.log(usi) + 6.949915) if usi < 5.85
  return rsi + 1 / (1.788041 * usi - 2.886625)
end

#grossRoofArea(spaces = []) ⇒ `Object`

Returns the “gross roof area” above selected conditioned, occupied spaces. This includes all roof surfaces of indirectly-conditioned, unoccupied spaces like plenums (if located above any of the selected spaces). This also includes roof surfaces of unconditioned or unenclosed spaces like attics, if vertically-overlapping any ceiling of occupied spaces below; attic roof sections above uninsulated soffits are excluded, for instance. It does not include surfaces labelled as ‘RoofCeiling’, which do not comply with ASHRAE 90.1 or NECB tilt criteria - see ‘roof?’.

# File 'lib/osut/utils.rb', line 5892

def grossRoofArea(spaces = [])
  mth = "OSut::#{__callee__}"
  up  = OpenStudio::Point3d.new(0,0,1) - OpenStudio::Point3d.new(0,0,0)
  rm2 = 0
  rfs = {}

  spaces = spaces.is_a?(OpenStudio::Model::Space) ? [spaces] : spaces
  spaces = spaces.respond_to?(:to_a) ? spaces.to_a : []
  spaces = spaces.select { |space| space.is_a?(OpenStudio::Model::Space) }
  spaces = spaces.select { |space| space.partofTotalFloorArea }
  spaces = spaces.reject { |space| unconditioned?(space) }
  return invalid("spaces", mth, 1, DBG, 0) if spaces.empty?

  # The method is very similar to OpenStudio-Standards' :
  #   find_exposed_conditioned_roof_surfaces(model)
  #
  # github.com/NREL/openstudio-standards/blob/
  # be81bd88dc55a44d8cce3ee6daf29c768032df6a/lib/openstudio-standards/
  # standards/Standards.Surface.rb#L99
  #
  # ... yet differs with regards to attics with overhangs/soffits.

  # Start with roof surfaces of occupied, conditioned spaces.
  spaces.each do |space|
    facets(space, "Outdoors", "RoofCeiling").each do |roof|
      next if rfs.key?(roof)
      next unless roof?(roof)

      rfs[roof] = {m2: roof.grossArea, m: space.multiplier}
    end
  end

  # Roof surfaces of unoccupied, conditioned spaces above (e.g. plenums)?
  # @todo: recursive call for stacked spaces as atria (via AirBoundaries).
  spaces.each do |space|
    facets(space, "Surface", "RoofCeiling").each do |ceiling|
      floor = ceiling.adjacentSurface
      next if floor.empty?

      other = floor.get.space
      next if other.empty?

      other = other.get
      next if other.partofTotalFloorArea
      next if unconditioned?(other)

      facets(other, "Outdoors", "RoofCeiling").each do |roof|
        next if rfs.key?(roof)
        next unless roof?(roof)

        rfs[roof] = {m2: roof.grossArea, m: other.multiplier}
      end
    end
  end

  # Roof surfaces of unoccupied, unconditioned spaces above (e.g. attics)?
  # @todo: recursive call for stacked spaces as atria (via AirBoundaries).
  spaces.each do |space|
    # When taking overlaps into account, the target space may not share the
    # same local transformation as the space(s) above.
    t0 = transforms(space)
    next unless t0[:t]

    t0 = t0[:t]

    facets(space, "Surface", "RoofCeiling").each do |ceiling|
      cv0 = t0 * ceiling.vertices

      floor = ceiling.adjacentSurface
      next if floor.empty?

      other = floor.get.space
      next if other.empty?

      other = other.get
      next if other.partofTotalFloorArea
      next unless unconditioned?(other)

      ti = transforms(other)
      next unless ti[:t]

      ti = ti[:t]

      facets(other, "Outdoors", "RoofCeiling").each do |roof|
        next unless roof?(roof)

        rvi  = ti * roof.vertices
        cst  = cast(cv0, rvi, up)
        next if cst.empty?

        # The overlap calculation fails for roof and ceiling surfaces with
        # previously-added leader lines.
        #
        # @todo: revise approach for attics ONCE skylight wells have been added.
        olap = nil
        olap = overlap(cst, rvi, false)
        next if olap.empty?

        m2 = OpenStudio.getArea(olap)
        next if m2.empty?

        m2 = m2.get
        next unless m2.round(2) > 0

        rfs[roof] = {m2: 0, m: other.multiplier} unless rfs.key?(roof)

        rfs[roof][:m2] += m2
      end
    end
  end

  rfs.values.each { |rf| rm2 += rf[:m2] * rf[:m] }

  rm2
end

#heatingTemperatureSetpoints?(model = nil) ⇒ `Bool`, `false`

Validates if model has zones with valid heating temperature setpoints.

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model

Returns:

(Bool) —

whether model holds valid heating temperature setpoints
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1615

def heatingTemperatureSetpoints?(model = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Model
  return mismatch("model", model, cl, mth, DBG, false) unless model.is_a?(cl)

  model.getThermalZones.each do |zone|
    return true if maxHeatScheduledSetpoint(zone)[:spt]
  end

  false
end

#height(pts = nil) ⇒ `Float`, `0.0`

Returns ‘height’ of a set of OpenStudio 3D points.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(Float) —

height along Z-axis, or Y-axis if flat
(0.0) —

if invalid inputs

# File 'lib/osut/utils.rb', line 2711

def height(pts = nil)
  pts = to_p3Dv(pts)
  return 0 if pts.size < 2

  min = pts.min_by(&:z).z
  max = pts.max_by(&:z).z
  return max - min if (max - min).abs > TOL

  pts.max_by(&:y).y - pts.min_by(&:y).y
end

#holds?(pts = nil, p1 = nil) ⇒ `Bool`, `false`

Returns true if an OpenStudio 3D point is part of a set of 3D points.

Parameters:

pts (Set<OpenStudio::Point3dVector>) (defaults to: nil) —

3d points
p1 (OpenStudio::Point3d) (defaults to: nil) —

a 3D point

Returns:

(Bool) —

whether part of a set of 3D points
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2484

def holds?(pts = nil, p1 = nil)
  mth = "OSut::#{__callee__}"
  pts = to_p3Dv(pts)
  cl  = OpenStudio::Point3d
  return mismatch("point", p1, cl, mth, DBG, false) unless p1.is_a?(cl)

  pts.each { |pt| return true if same?(p1, pt) }

  false
end

#holdsConstruction?(set = nil, bse = nil, gr = false, ex = false, tp = "") ⇒ `Bool`, `false`

Validates if a default construction set holds a base construction.

Parameters:

set (OpenStudio::Model::DefaultConstructionSet) (defaults to: nil) —

a default set
bse (OpensStudio::Model::ConstructionBase) (defaults to: nil) —

a construction base
gr (Bool) (defaults to: false) —

if ground-facing surface
ex (Bool) (defaults to: false) —

if exterior-facing surface
tp (#to_s) (defaults to: "") —

a surface type

Returns:

(Bool) —

whether default set holds construction
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 756

def holdsConstruction?(set = nil, bse = nil, gr = false, ex = false, tp = "")
  mth = "OSut::#{__callee__}"
  cl1 = OpenStudio::Model::DefaultConstructionSet
  cl2 = OpenStudio::Model::ConstructionBase
  ck1 = set.respond_to?(NS)
  ck2 = bse.respond_to?(NS)
  return invalid("set" , mth, 1, DBG, false) unless ck1
  return invalid("base", mth, 2, DBG, false) unless ck2

  id1 = set.nameString
  id2 = bse.nameString
  ck1 = set.is_a?(cl1)
  ck2 = bse.is_a?(cl2)
  ck3 = [true, false].include?(gr)
  ck4 = [true, false].include?(ex)
  ck5 = tp.respond_to?(:to_s)
  return mismatch(id1, set, cl1, mth,    DBG, false) unless ck1
  return mismatch(id2, bse, cl2, mth,    DBG, false) unless ck2
  return invalid("ground"      , mth, 3, DBG, false) unless ck3
  return invalid("exterior"    , mth, 4, DBG, false) unless ck4
  return invalid("surface type", mth, 5, DBG, false) unless ck5

  type = trim(tp).downcase
  ck1  = ["floor", "wall", "roofceiling"].include?(type)
  return invalid("surface type", mth, 5, DBG, false) unless ck1

  constructions = nil

  if gr
    unless set.defaultGroundContactSurfaceConstructions.empty?
      constructions = set.defaultGroundContactSurfaceConstructions.get
    end
  elsif ex
    unless set.defaultExteriorSurfaceConstructions.empty?
      constructions = set.defaultExteriorSurfaceConstructions.get
    end
  else
    unless set.defaultInteriorSurfaceConstructions.empty?
      constructions = set.defaultInteriorSurfaceConstructions.get
    end
  end

  return false unless constructions

  case type
  when "roofceiling"
    unless constructions.roofCeilingConstruction.empty?
      construction = constructions.roofCeilingConstruction.get
      return true if construction == bse
    end
  when "floor"
    unless constructions.floorConstruction.empty?
      construction = constructions.floorConstruction.get
      return true if construction == bse
    end
  else
    unless constructions.wallConstruction.empty?
      construction = constructions.wallConstruction.get
      return true if construction == bse
    end
  end

  false
end

#insulatingLayer(lc = nil) ⇒ `Hash`

Identifies a layered construction’s (opaque) insulating layer. The method returns a 3-keyed hash :index, the insulating layer index [0, n layers) within the layered construction; :type, either :standard or :massless; and :r, material thermal resistance in m2•K/W.

Parameters:

lc (OpenStudio::Model::LayeredConstruction) (defaults to: nil) —

a layered construction

Returns:

(Hash) —

index: (Integer), type: (Symbol), r: (Float)
(Hash) —

index: nil, type: nil, r: 0 if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1043

def insulatingLayer(lc = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::LayeredConstruction
  res = { index: nil, type: nil, r: 0.0 }
  i   = 0  # iterator
  return invalid("lc", mth, 1, DBG, res) unless lc.respond_to?(NS)

  id   = lc.nameString
  return mismatch(id, lc, cl1, mth, DBG, res) unless lc.is_a?(cl)

  lc.layers.each do |m|
    unless m.to_MasslessOpaqueMaterial.empty?
      m             = m.to_MasslessOpaqueMaterial.get

      if m.thermalResistance < 0.001 || m.thermalResistance < res[:r]
        i += 1
        next
      else
        res[:r    ] = m.thermalResistance
        res[:index] = i
        res[:type ] = :massless
      end
    end

    unless m.to_StandardOpaqueMaterial.empty?
      m             = m.to_StandardOpaqueMaterial.get
      k             = m.thermalConductivity
      d             = m.thickness

      if d < 0.003 || k > 3.0 || d / k < res[:r]
        i += 1
        next
      else
        res[:r    ] = d / k
        res[:index] = i
        res[:type ] = :standard
      end
    end

    i += 1
  end

  res
end

#lineIntersects?(l = [], s = []) ⇒ `Bool`, `false`

Validates whether 3D line segment intersects 3D segments (e.g. polygon).

Parameters:

l (Set<OpenStudio::Point3d] 3D line segment) (defaults to: []) —
Set<OpenStudio::Point3d

3D line segment
s (Set<OpenStudio::Point3d] 3D segments) (defaults to: []) —
Set<OpenStudio::Point3d

3D segments

Returns:

(Bool) —

whether 3D line intersects 3D segments
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3051

def lineIntersects?(l = [], s = [])
  l   = getSegments(l)
  s   = getSegments(s)
  return nil if l.empty?
  return nil if s.empty?

  l = l.first

  s.each { |segment| return true if getLineIntersection(l, segment) }

  false
end

#maxHeatScheduledSetpoint(zone = nil) ⇒ `Hash`

Returns MAX zone heating temperature schedule setpoint [°C] and whether zone has an active dual setpoint thermostat.

Parameters:

zone (OpenStudio::Model::ThermalZone) (defaults to: nil) —

a thermal zone

Returns:

(Hash) —

spt: (Float), dual: (Bool)
(Hash) —

spt: nil, dual: false if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1441

def maxHeatScheduledSetpoint(zone = nil)
  # Largely inspired from Parker & Marrec's "thermal_zone_heated?" procedure.
  # The solution here is a tad more relaxed to encompass SEMIHEATED zones as
  # per Canadian NECB criteria (basically any space with at least 10 W/m2 of
  # installed heating equipement, i.e. below freezing in Canada).
  #
  # github.com/NREL/openstudio-standards/blob/
  # 58964222d25783e9da4ae292e375fb0d5c902aa5/lib/openstudio-standards/
  # standards/Standards.ThermalZone.rb#L910
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::ThermalZone
  res = { spt: nil, dual: false }
  return invalid("zone", mth, 1, DBG, res) unless zone.respond_to?(NS)

  id = zone.nameString
  return mismatch(id, zone, cl, mth, DBG, res) unless zone.is_a?(cl)

  # Zone radiant heating? Get schedule from radiant system.
  zone.equipment.each do |equip|
    sched = nil

    unless equip.to_ZoneHVACHighTemperatureRadiant.empty?
      equip = equip.to_ZoneHVACHighTemperatureRadiant.get

      unless equip.heatingSetpointTemperatureSchedule.empty?
        sched = equip.heatingSetpointTemperatureSchedule.get
      end
    end

    unless equip.to_ZoneHVACLowTemperatureRadiantElectric.empty?
      equip = equip.to_ZoneHVACLowTemperatureRadiantElectric.get
      sched = equip.heatingSetpointTemperatureSchedule
    end

    unless equip.to_ZoneHVACLowTempRadiantConstFlow.empty?
      equip = equip.to_ZoneHVACLowTempRadiantConstFlow.get
      coil = equip.heatingCoil

      unless coil.to_CoilHeatingLowTempRadiantConstFlow.empty?
        coil = coil.to_CoilHeatingLowTempRadiantConstFlow.get

        unless coil.heatingHighControlTemperatureSchedule.empty?
          sched = c.heatingHighControlTemperatureSchedule.get
        end
      end
    end

    unless equip.to_ZoneHVACLowTempRadiantVarFlow.empty?
      equip = equip.to_ZoneHVACLowTempRadiantVarFlow.get
      coil = equip.heatingCoil

      unless coil.to_CoilHeatingLowTempRadiantVarFlow.empty?
        coil = coil.to_CoilHeatingLowTempRadiantVarFlow.get

        unless coil.heatingControlTemperatureSchedule.empty?
          sched = coil.heatingControlTemperatureSchedule.get
        end
      end
    end

    next unless sched

    unless sched.to_ScheduleRuleset.empty?
      sched = sched.to_ScheduleRuleset.get
      max = scheduleRulesetMinMax(sched)[:max]

      if max
        res[:spt] = max unless res[:spt]
        res[:spt] = max     if res[:spt] < max
      end
    end

    unless sched.to_ScheduleConstant.empty?
      sched = sched.to_ScheduleConstant.get
      max = scheduleConstantMinMax(sched)[:max]

      if max
        res[:spt] = max unless res[:spt]
        res[:spt] = max     if res[:spt] < max
      end
    end

    unless sched.to_ScheduleCompact.empty?
      sched = sched.to_ScheduleCompact.get
      max = scheduleCompactMinMax(sched)[:max]

      if max
        res[:spt] = max unless res[:spt]
        res[:spt] = max     if res[:spt] < max
      end
    end
  end

  return res if zone.thermostat.empty?

  tstat = zone.thermostat.get
  res[:spt] = nil

  unless tstat.to_ThermostatSetpointDualSetpoint.empty? &&
         tstat.to_ZoneControlThermostatStagedDualSetpoint.empty?

    unless tstat.to_ThermostatSetpointDualSetpoint.empty?
      tstat = tstat.to_ThermostatSetpointDualSetpoint.get
    else
      tstat = tstat.to_ZoneControlThermostatStagedDualSetpoint.get
    end

    unless tstat.heatingSetpointTemperatureSchedule.empty?
      res[:dual] = true
      sched = tstat.heatingSetpointTemperatureSchedule.get

      unless sched.to_ScheduleRuleset.empty?
        sched = sched.to_ScheduleRuleset.get
        max = scheduleRulesetMinMax(sched)[:max]

        if max
          res[:spt] = max unless res[:spt]
          res[:spt] = max     if res[:spt] < max
        end

        dd = sched.winterDesignDaySchedule

        unless dd.values.empty?
          res[:spt] = dd.values.max unless res[:spt]
          res[:spt] = dd.values.max     if res[:spt] < dd.values.max
        end
      end

      unless sched.to_ScheduleConstant.empty?
        sched = sched.to_ScheduleConstant.get
        max = scheduleConstantMinMax(sched)[:max]

        if max
          res[:spt] = max unless res[:spt]
          res[:spt] = max     if res[:spt] < max
        end
      end

      unless sched.to_ScheduleCompact.empty?
        sched = sched.to_ScheduleCompact.get
        max = scheduleCompactMinMax(sched)[:max]

        if max
          res[:spt] = max unless res[:spt]
          res[:spt] = max     if res[:spt] < max
        end
      end

      unless sched.to_ScheduleYear.empty?
        sched = sched.to_ScheduleYear.get

        sched.getScheduleWeeks.each do |week|
          next if week.winterDesignDaySchedule.empty?

          dd = week.winterDesignDaySchedule.get
          next unless dd.values.empty?

          res[:spt] = dd.values.max unless res[:spt]
          res[:spt] = dd.values.max     if res[:spt] < dd.values.max
        end
      end
    end
  end

  res
end

#medialBox(pts = nil) ⇒ `OpenStudio::Point3dVector`

Generates a BLC box bounded within a triangle (midpoint theorem).

pts [Set<OpenStudio::Point3d>] triangular polygon

Returns:

(OpenStudio::Point3dVector) —

medial bounded box (see logs if empty)

# File 'lib/osut/utils.rb', line 4085

def medialBox(pts = nil)
  mth = "OSut::#{__callee__}"
  bkp = OpenStudio::Point3dVector.new
  box = []
  pts = poly(pts, true, true, true)
  return bkp if pts.empty?
  return invalid("triangle", mth, 1, ERR, bkp) unless pts.size == 3

  t   = xyz?(pts, :z) ? nil : OpenStudio::Transformation.alignFace(pts)
  pts = poly(pts, false, false, false, t) if t
  return bkp if pts.empty?

  pts = to_p3Dv(pts.to_a.reverse) if clockwise?(pts)

  # Generate vertical plane along longest segment.
  mpoints = []
  sgs     = getSegments(pts)
  longest = sgs.max_by { |s| OpenStudio.getDistanceSquared(s.first, s.last) }
  plane   = verticalPlane(longest.first, longest.last)

  # Fetch midpoints of other 2 segments.
  sgs.each { |s| mpoints << midpoint(s.first, s.last) unless s == longest }

  return bkp unless mpoints.size == 2

  # Generate medial bounded box.
  box << plane.project(mpoints.first)
  box << mpoints.first
  box << mpoints.last
  box << plane.project(mpoints.last)
  box = getNonCollinears(box).to_a
  return bkp unless box.size == 4

  box = clockwise?(box) ? blc(box.reverse) : blc(box)
  return bkp unless rectangular?(box)
  return bkp unless fits?(box, pts)

  box = to_p3Dv(t * box) if t

  box
end

#midpoint(p1 = nil, p2 = nil) ⇒ `OpenStudio::Point3d`^?

Returns midpoint coordinates of line segment.

Parameters:

p1 (OpenStudio::Point3d) (defaults to: nil) —

1st 3D point of a line segment
p2 (OpenStudio::Point3d) (defaults to: nil) —

2nd 3D point of a line segment

Returns:

(OpenStudio::Point3d) —

midpoint
(nil) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2730

def midpoint(p1 = nil, p2 = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Point3d
  return mismatch("point 1", p1, cl, mth) unless p1.is_a?(cl)
  return mismatch("point 2", p2, cl, mth) unless p2.is_a?(cl)
  return invalid("same points", mth, 0)       if same?(p1, p2)

  midX = p1.x + (p2.x - p1.x)/2
  midY = p1.y + (p2.y - p1.y)/2
  midZ = p1.z + (p2.z - p1.z)/2

  OpenStudio::Point3d.new(midX, midY, midZ)
end

#minCoolScheduledSetpoint(zone = nil) ⇒ `Hash`

Returns MIN zone cooling temperature schedule setpoint [°C] and whether zone has an active dual setpoint thermostat.

Parameters:

zone (OpenStudio::Model::ThermalZone) (defaults to: nil) —

a thermal zone

Returns:

(Hash) —

spt: (Float), dual: (Bool)
(Hash) —

spt: nil, dual: false if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1635

def minCoolScheduledSetpoint(zone = nil)
  # Largely inspired from Parker & Marrec's "thermal_zone_cooled?" procedure.
  #
  # github.com/NREL/openstudio-standards/blob/
  # 99cf713750661fe7d2082739f251269c2dfd9140/lib/openstudio-standards/
  # standards/Standards.ThermalZone.rb#L1058
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::ThermalZone
  res = { spt: nil, dual: false }
  return invalid("zone", mth, 1, DBG, res) unless zone.respond_to?(NS)

  id = zone.nameString
  return mismatch(id, zone, cl, mth, DBG, res) unless zone.is_a?(cl)

  # Zone radiant cooling? Get schedule from radiant system.
  zone.equipment.each do |equip|
    sched = nil

    unless equip.to_ZoneHVACLowTempRadiantConstFlow.empty?
      equip = equip.to_ZoneHVACLowTempRadiantConstFlow.get
      coil = equip.coolingCoil

      unless coil.to_CoilCoolingLowTempRadiantConstFlow.empty?
        coil = coil.to_CoilCoolingLowTempRadiantConstFlow.get

        unless coil.coolingLowControlTemperatureSchedule.empty?
          sched = coil.coolingLowControlTemperatureSchedule.get
        end
      end
    end

    unless equip.to_ZoneHVACLowTempRadiantVarFlow.empty?
      equip = equip.to_ZoneHVACLowTempRadiantVarFlow.get
      coil = equip.coolingCoil

      unless coil.to_CoilCoolingLowTempRadiantVarFlow.empty?
        coil = coil.to_CoilCoolingLowTempRadiantVarFlow.get

        unless coil.coolingControlTemperatureSchedule.empty?
          sched = coil.coolingControlTemperatureSchedule.get
        end
      end
    end

    next unless sched

    unless sched.to_ScheduleRuleset.empty?
      sched = sched.to_ScheduleRuleset.get
      min = scheduleRulesetMinMax(sched)[:min]

      if min
        res[:spt] = min unless res[:spt]
        res[:spt] = min     if res[:spt] > min
      end
    end

    unless sched.to_ScheduleConstant.empty?
      sched = sched.to_ScheduleConstant.get
      min = scheduleConstantMinMax(sched)[:min]

      if min
        res[:spt] = min unless res[:spt]
        res[:spt] = min     if res[:spt] > min
      end
    end

    unless sched.to_ScheduleCompact.empty?
      sched = sched.to_ScheduleCompact.get
      min = scheduleCompactMinMax(sched)[:min]

      if min
        res[:spt] = min unless res[:spt]
        res[:spt] = min     if res[:spt] > min
      end
    end
  end

  return res if zone.thermostat.empty?

  tstat     = zone.thermostat.get
  res[:spt] = nil

  unless tstat.to_ThermostatSetpointDualSetpoint.empty? &&
         tstat.to_ZoneControlThermostatStagedDualSetpoint.empty?

    unless tstat.to_ThermostatSetpointDualSetpoint.empty?
      tstat = tstat.to_ThermostatSetpointDualSetpoint.get
    else
      tstat = tstat.to_ZoneControlThermostatStagedDualSetpoint.get
    end

    unless tstat.coolingSetpointTemperatureSchedule.empty?
      res[:dual] = true
      sched = tstat.coolingSetpointTemperatureSchedule.get

      unless sched.to_ScheduleRuleset.empty?
        sched = sched.to_ScheduleRuleset.get
        min = scheduleRulesetMinMax(sched)[:min]

        if min
          res[:spt] = min unless res[:spt]
          res[:spt] = min     if res[:spt] > min
        end

        dd = sched.summerDesignDaySchedule

        unless dd.values.empty?
          res[:spt] = dd.values.min unless res[:spt]
          res[:spt] = dd.values.min     if res[:spt] > dd.values.min
        end
      end

      unless sched.to_ScheduleConstant.empty?
        sched = sched.to_ScheduleConstant.get
        min = scheduleConstantMinMax(sched)[:min]

        if min
          res[:spt] = min unless res[:spt]
          res[:spt] = min     if res[:spt] > min
        end
      end

      unless sched.to_ScheduleCompact.empty?
        sched = sched.to_ScheduleCompact.get
        min = scheduleCompactMinMax(sched)[:min]

        if min
          res[:spt] = min unless res[:spt]
          res[:spt] = min     if res[:spt] > min
        end
      end

      unless sched.to_ScheduleYear.empty?
        sched = sched.to_ScheduleYear.get

        sched.getScheduleWeeks.each do |week|
          next if week.summerDesignDaySchedule.empty?

          dd = week.summerDesignDaySchedule.get
          next unless dd.values.empty?

          res[:spt] = dd.values.min unless res[:spt]
          res[:spt] = dd.values.min     if res[:spt] > dd.values.min
        end
      end
    end
  end

  res
end

#nearest(pts = nil, p01 = nil) ⇒ `Integer`^?

Returns OpenStudio 3D point (in a set) nearest to a point of reference, e.g. grid origin. If left unspecified, the method systematically returns the bottom-left corner (BLC) of any horizontal set. If more than one point fits the initial criteria, the method relies on deterministic sorting through triangulation.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points
p01 (OpenStudio::Point3d) (defaults to: nil) —

point of reference

Returns:

(Integer) —

set index of nearest point to point of reference
(nil) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2507

def nearest(pts = nil, p01 = nil)
  mth = "OSut::#{__callee__}"
  l   = 100
  d01 = 10000
  d02 = 0
  d03 = 0
  idx = nil
  pts = to_p3Dv(pts)
  return idx if pts.empty?

  p03 = OpenStudio::Point3d.new( l,-l,-l)
  p02 = OpenStudio::Point3d.new( l, l, l)
  p01 = OpenStudio::Point3d.new(-l,-l,-l) unless p01
  return mismatch("point", p01, cl, mth) unless p01.is_a?(OpenStudio::Point3d)

  pts.each_with_index { |pt, i| return i if same?(pt, p01) }

  pts.each_with_index do |pt, i|
    length01 = (pt - p01).length
    length02 = (pt - p02).length
    length03 = (pt - p03).length

    if length01.round(2) == d01.round(2)
      if length02.round(2) == d02.round(2)
        if length03.round(2) > d03.round(2)
          idx = i
          d03 = length03
        end
      elsif length02.round(2) > d02.round(2)
        idx = i
        d03 = length03
        d02 = length02
      end
    elsif length01.round(2) < d01.round(2)
      idx = i
      d01 = length01
      d02 = length02
      d03 = length03
    end
  end

  idx
end

#nextUp(pts = nil, pt = nil) ⇒ `OpenStudio::Point3d`^?

Returns next sequential point in an OpenStudio 3D point vector.

Parameters:

pts (OpenStudio::Point3dVector) (defaults to: nil) —

3D points
pt (OpenStudio::Point3d) (defaults to: nil) —

a given 3D point

Returns:

(OpenStudio::Point3d) —

the next sequential point
(nil) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2678

def nextUp(pts = nil, pt = nil)
  mth = "OSut::#{__callee__}"
  pts = to_p3Dv(pts)
  cl  = OpenStudio::Point3d
  return mismatch("point", pt, cl, mth)  unless pt.is_a?(cl)
  return invalid("points (2+)", mth, 1, WRN) if pts.size < 2

  pair = pts.each_cons(2).find { |p1, _| same?(p1, pt) }

  pair.nil? ? pts.first : pair.last
end

#offset(p1 = nil, w = 0, v = 0) ⇒ `OpenStudio::Point3dVector`

Generates offset vertices (by width) for a 3- or 4-sided, convex polygon. If width is negative, the vertices are contracted inwards.

Parameters:

p1 (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points
w (#to_f) (defaults to: 0) —

offset width (absolute min: 0.0254m)
v (#to_i) (defaults to: 0) —

OpenStudio SDK version, eg ‘321’ for “v3.2.1” (optional)

Returns:

(OpenStudio::Point3dVector) —

offset points (see logs if unaltered)

# File 'lib/osut/utils.rb', line 3727

def offset(p1 = nil, w = 0, v = 0)
  mth = "OSut::#{__callee__}"
  pts = poly(p1, true, true, false, true, :cw)
  return invalid("points", mth, 1, DBG, p1) unless [3, 4].include?(pts.size)

  mismatch("width",   w, Numeric, mth) unless w.respond_to?(:to_f)
  mismatch("version", v, Integer, mth) unless v.respond_to?(:to_i)

  iv = pts.size == 4 ? true : false
  vs = OpenStudio.openStudioVersion.split(".").join.to_i
  v  = v.respond_to?(:to_i) ? v.to_i : vs
  w  = w.respond_to?(:to_f) ? w.to_f : 0
  return p1 if w.abs < 0.0254

  unless v < 340
    t      = OpenStudio::Transformation.alignFace(p1)
    offset = OpenStudio.buffer(pts, w, TOL)
    return p1 if offset.empty?

    return to_p3Dv(t * offset.get.reverse)
  else # brute force approach
    pz     = {}
    pz[:A] = {}
    pz[:B] = {}
    pz[:C] = {}
    pz[:D] = {}                                                          if iv

    pz[:A][:p] = OpenStudio::Point3d.new(p1[0].x, p1[0].y, p1[0].z)
    pz[:B][:p] = OpenStudio::Point3d.new(p1[1].x, p1[1].y, p1[1].z)
    pz[:C][:p] = OpenStudio::Point3d.new(p1[2].x, p1[2].y, p1[2].z)
    pz[:D][:p] = OpenStudio::Point3d.new(p1[3].x, p1[3].y, p1[3].z)      if iv

    pzAp = pz[:A][:p]
    pzBp = pz[:B][:p]
    pzCp = pz[:C][:p]
    pzDp = pz[:D][:p]                                                    if iv

    # Generate vector pairs, from next point & from previous point.
    # :f_n : "from next"
    # :f_p : "from previous"
    #
    #
    #
    #
    #
    #
    #             A <---------- B
    #              ^
    #               \
    #                \
    #                 C (or D)
    #
    pz[:A][:f_n] = pzAp - pzBp
    pz[:A][:f_p] = pzAp - pzCp                                       unless iv
    pz[:A][:f_p] = pzAp - pzDp                                           if iv

    pz[:B][:f_n] = pzBp - pzCp
    pz[:B][:f_p] = pzBp - pzAp

    pz[:C][:f_n] = pzCp - pzAp                                       unless iv
    pz[:C][:f_n] = pzCp - pzDp                                           if iv
    pz[:C][:f_p] = pzCp - pzBp

    pz[:D][:f_n] = pzDp - pzAp                                           if iv
    pz[:D][:f_p] = pzDp - pzCp                                           if iv

    # Generate 3D plane from vectors.
    #
    #
    #             |  <<< 3D plane ... from point A, with normal B>A
    #             |
    #             |
    #             |
    # <---------- A <---------- B
    #             |\
    #             | \
    #             |  \
    #             |   C (or D)
    #
    pz[:A][:pl_f_n] = OpenStudio::Plane.new(pzAp, pz[:A][:f_n])
    pz[:A][:pl_f_p] = OpenStudio::Plane.new(pzAp, pz[:A][:f_p])

    pz[:B][:pl_f_n] = OpenStudio::Plane.new(pzBp, pz[:B][:f_n])
    pz[:B][:pl_f_p] = OpenStudio::Plane.new(pzBp, pz[:B][:f_p])

    pz[:C][:pl_f_n] = OpenStudio::Plane.new(pzCp, pz[:C][:f_n])
    pz[:C][:pl_f_p] = OpenStudio::Plane.new(pzCp, pz[:C][:f_p])

    pz[:D][:pl_f_n] = OpenStudio::Plane.new(pzDp, pz[:D][:f_n])          if iv
    pz[:D][:pl_f_p] = OpenStudio::Plane.new(pzDp, pz[:D][:f_p])          if iv

    # Project an extended point (pC) unto 3D plane.
    #
    #             pC   <<< projected unto extended B>A 3D plane
    #        eC   |
    #          \  |
    #           \ |
    #            \|
    # <---------- A <---------- B
    #             |\
    #             | \
    #             |  \
    #             |   C (or D)
    #
    pz[:A][:p_n_pl] = pz[:A][:pl_f_n].project(pz[:A][:p] + pz[:A][:f_p])
    pz[:A][:n_p_pl] = pz[:A][:pl_f_p].project(pz[:A][:p] + pz[:A][:f_n])

    pz[:B][:p_n_pl] = pz[:B][:pl_f_n].project(pz[:B][:p] + pz[:B][:f_p])
    pz[:B][:n_p_pl] = pz[:B][:pl_f_p].project(pz[:B][:p] + pz[:B][:f_n])

    pz[:C][:p_n_pl] = pz[:C][:pl_f_n].project(pz[:C][:p] + pz[:C][:f_p])
    pz[:C][:n_p_pl] = pz[:C][:pl_f_p].project(pz[:C][:p] + pz[:C][:f_n])

    pz[:D][:p_n_pl] = pz[:D][:pl_f_n].project(pz[:D][:p] + pz[:D][:f_p]) if iv
    pz[:D][:n_p_pl] = pz[:D][:pl_f_p].project(pz[:D][:p] + pz[:D][:f_n]) if iv

    # Generate vector from point (e.g. A) to projected extended point (pC).
    #
    #             pC
    #        eC   ^
    #          \  |
    #           \ |
    #            \|
    # <---------- A <---------- B
    #             |\
    #             | \
    #             |  \
    #             |   C (or D)
    #
    pz[:A][:n_p_n_pl] = pz[:A][:p_n_pl] - pzAp
    pz[:A][:n_n_p_pl] = pz[:A][:n_p_pl] - pzAp

    pz[:B][:n_p_n_pl] = pz[:B][:p_n_pl] - pzBp
    pz[:B][:n_n_p_pl] = pz[:B][:n_p_pl] - pzBp

    pz[:C][:n_p_n_pl] = pz[:C][:p_n_pl] - pzCp
    pz[:C][:n_n_p_pl] = pz[:C][:n_p_pl] - pzCp

    pz[:D][:n_p_n_pl] = pz[:D][:p_n_pl] - pzDp                           if iv
    pz[:D][:n_n_p_pl] = pz[:D][:n_p_pl] - pzDp                           if iv

    # Fetch angle between both extended vectors (A>pC & A>pB),
    # ... then normalize (Cn).
    #
    #             pC
    #        eC   ^
    #          \  |
    #           \ Cn
    #            \|
    # <---------- A <---------- B
    #             |\
    #             | \
    #             |  \
    #             |   C (or D)
    #
    a1 = OpenStudio.getAngle(pz[:A][:n_p_n_pl], pz[:A][:n_n_p_pl])
    a2 = OpenStudio.getAngle(pz[:B][:n_p_n_pl], pz[:B][:n_n_p_pl])
    a3 = OpenStudio.getAngle(pz[:C][:n_p_n_pl], pz[:C][:n_n_p_pl])
    a4 = OpenStudio.getAngle(pz[:D][:n_p_n_pl], pz[:D][:n_n_p_pl])       if iv

    # Generate new 3D points A', B', C' (and D') ... zigzag.
    #
    #
    #
    #
    #     A' ---------------------- B'
    #      \
    #       \      A <---------- B
    #        \      \
    #         \      \
    #          \      \
    #           C'      C
    pz[:A][:f_n].normalize
    pz[:A][:n_p_n_pl].normalize
    pzAp = pzAp + scalar(pz[:A][:n_p_n_pl], w)
    pzAp = pzAp + scalar(pz[:A][:f_n], w * Math.tan(a1/2))

    pz[:B][:f_n].normalize
    pz[:B][:n_p_n_pl].normalize
    pzBp = pzBp + scalar(pz[:B][:n_p_n_pl], w)
    pzBp = pzBp + scalar(pz[:B][:f_n], w * Math.tan(a2/2))

    pz[:C][:f_n].normalize
    pz[:C][:n_p_n_pl].normalize
    pzCp = pzCp + scalar(pz[:C][:n_p_n_pl], w)
    pzCp = pzCp + scalar(pz[:C][:f_n], w * Math.tan(a3/2))

    pz[:D][:f_n].normalize                                               if iv
    pz[:D][:n_p_n_pl].normalize                                          if iv
    pzDp = pzDp + scalar(pz[:D][:n_p_n_pl], w)                           if iv
    pzDp = pzDp + scalar(pz[:D][:f_n], w * Math.tan(a4/2))               if iv

    # Re-convert to OpenStudio 3D points.
    vec  = OpenStudio::Point3dVector.new
    vec << OpenStudio::Point3d.new(pzAp.x, pzAp.y, pzAp.z)
    vec << OpenStudio::Point3d.new(pzBp.x, pzBp.y, pzBp.z)
    vec << OpenStudio::Point3d.new(pzCp.x, pzCp.y, pzCp.z)
    vec << OpenStudio::Point3d.new(pzDp.x, pzDp.y, pzDp.z)               if iv

    return vec
  end
end

#outline(a = [], bfr = 0, flat = true) ⇒ `OpenStudio::Point3dVector`

Generates a ULC OpenStudio 3D point vector (a bounding box) that surrounds multiple (smaller) OpenStudio 3D point vectors. The generated, 4-point outline is optionally buffered (or offset). Frame and Divider frame widths are taken into account.

Parameters:

a (Array) (defaults to: []) —

sets of OpenStudio 3D points
bfr (Numeric) (defaults to: 0) —

an optional buffer size (min: 0.0254m)
flat (Bool) (defaults to: true) —

if points are to be pre-flattened (Z=0)

Returns:

(OpenStudio::Point3dVector) —

ULC outline (see logs if empty)

# File 'lib/osut/utils.rb', line 3941

def outline(a = [], bfr = 0, flat = true)
  mth  = "OSut::#{__callee__}"
  flat = true unless [true, false].include?(flat)
  xMIN = nil
  xMAX = nil
  yMIN = nil
  yMAX = nil
  a2   = []
  out  = OpenStudio::Point3dVector.new
  cl   = Array
  return mismatch("array", a, cl, mth, DBG, out) unless a.is_a?(cl)
  return empty("array",           mth, DBG, out)     if a.empty?

  mismatch("buffer", bfr, Numeric, mth) unless bfr.respond_to?(:to_f)

  bfr = bfr.to_f if bfr.respond_to?(:to_f)
  bfr = 0    unless bfr.respond_to?(:to_f)
  bfr = 0        if bfr < 0.0254
  vtx = poly(a.first)
  return out if vtx.empty?

  t = OpenStudio::Transformation.alignFace(vtx)

  a.each do |pts|
    points = poly(pts, false, true, false, t)
    points = flatten(points) if flat
    next if points.empty?

    a2 << points
  end

  a2.each do |pts|
    minX = pts.min_by(&:x).x
    maxX = pts.max_by(&:x).x
    minY = pts.min_by(&:y).y
    maxY = pts.max_by(&:y).y

    # Consider frame width, if frame-and-divider-enabled sub surface.
    if pts.respond_to?(:allowWindowPropertyFrameAndDivider)
      fd = pts.windowPropertyFrameAndDivider
      w  = 0
      w  = fd.get.frameWidth unless fd.empty?

      if w > TOL
        minX -= w
        maxX += w
        minY -= w
        maxY += w
      end
    end

    xMIN = minX if xMIN.nil?
    xMAX = maxX if xMAX.nil?
    yMIN = minY if yMIN.nil?
    yMAX = maxY if yMAX.nil?

    xMIN = [xMIN, minX].min
    xMAX = [xMAX, maxX].max
    yMIN = [yMIN, minY].min
    yMAX = [yMAX, maxY].max
  end

  return negative("outline width",  mth, DBG, out) if xMAX < xMIN
  return negative("outline height", mth, DBG, out) if yMAX < yMIN
  return zero("outline width",      mth, DBG, out) if (xMIN - xMAX).abs < TOL
  return zero("outline height",     mth, DBG, out) if (yMIN - yMAX).abs < TOL

  # Generate ULC point 3D vector.
  out << OpenStudio::Point3d.new(xMIN, yMAX, 0)
  out << OpenStudio::Point3d.new(xMIN, yMIN, 0)
  out << OpenStudio::Point3d.new(xMAX, yMIN, 0)
  out << OpenStudio::Point3d.new(xMAX, yMAX, 0)

  # Apply buffer, apply ULC (options).
  out = offset(out, bfr, 300) if bfr > 0.0254

  to_p3Dv(t * out)
end

#overlap(p1 = nil, p2 = nil, flat = false) ⇒ `OpenStudio::Point3dVector`

Returns intersection of overlapping polygons, empty if non intersecting. If the optional 3rd argument is left as false, the 2nd polygon may only overlap if it shares the 3D plane equation of the 1st one. If the 3rd argument is instead set to true, then the 2nd polygon is first cast onto the 3D plane of the 1st one; the method therefore returns (as overlap) the intersection of a projection of the 2nd polygon onto the 1st one. The method returns the smallest of the 2 polygons if either fits within the larger one.

Parameters:

p1 (Set<OpenStudio::Point3d>) (defaults to: nil) —

1st set of 3D points
p2 (Set<OpenStudio::Point3d>) (defaults to: nil) —

2nd set of 3D points
flat (Bool) (defaults to: false) —

whether to first align the 2nd set onto the 1st set plane

Returns:

(OpenStudio::Point3dVector) —

largest intersection (see logs if empty)

# File 'lib/osut/utils.rb', line 3582

def overlap(p1 = nil, p2 = nil, flat = false)
  mth  = "OSut::#{__callee__}"
  flat = false unless [true, false].include?(flat)
  face = OpenStudio::Point3dVector.new
  p01  = poly(p1)
  p02  = poly(p2)
  return empty("points 1", mth, DBG, face) if p01.empty?
  return empty("points 2", mth, DBG, face) if p02.empty?
  return p01 if fits?(p01, p02)
  return p02 if fits?(p02, p01)

  if xyz?(p01, :z)
    t   = nil
    cw1 = clockwise?(p01)
    a1  = cw1 ? p01.to_a.reverse : p01.to_a
    a2  = p02.to_a
    a2  = flatten(a2).to_a if flat
    return invalid("points 2", mth, 2, DBG, face) unless xyz?(a2, :z)

    cw2 = clockwise?(a2)
    a2  = a2.reverse if cw2
  else
    t   = OpenStudio::Transformation.alignFace(p01)
    a1  = t.inverse * p01
    a2  = t.inverse * p02
    a2  = flatten(a2).to_a if flat
    return invalid("points 2", mth, 2, DBG, face) unless xyz?(a2, :z)

    cw2 = clockwise?(a2)
    a2  = a2.reverse if cw2
  end

  # Return either (transformed) polygon if one fits into the other.
  p1t = p01

  if t
    p2t = to_p3Dv(cw2 ? t * a2 : t * a2.reverse)
  else
    if cw1
      p2t = to_p3Dv(cw2 ? a2.reverse : a2)
    else
      p2t = to_p3Dv(cw2 ? a2 : a2.reverse)
    end
  end

  return p1t if fits?(a1, a2)
  return p2t if fits?(a2, a1)

  area1 = OpenStudio.getArea(a1)
  area2 = OpenStudio.getArea(a2)
  return empty("points 1 area", mth, ERR, face) if area1.empty?
  return empty("points 2 area", mth, ERR, face) if area2.empty?

  area1 = area1.get
  area2 = area2.get
  union = OpenStudio.join(a1.reverse, a2.reverse, TOL2)
  return face if union.empty?

  union = union.get
  area  = OpenStudio.getArea(union)
  return face if area.empty?

  area  = area.get
  delta = area1 + area2 - area

  if area > TOL
    return face if  area.round(2) == area1.round(2)
    return face if  area.round(2) == area2.round(2)
    return face if delta.round(2) == 0
  end

  res = OpenStudio.intersect(a1.reverse, a2.reverse, TOL)
  return face if res.empty?

  res  = res.get
  res1 = res.polygon1
  return face if res1.empty?

  to_p3Dv(t ? t * res1.reverse : res1.reverse)
end

#overlaps?(p1 = nil, p2 = nil, flat = false) ⇒ `Bool`, `false`

Determines whether OpenStudio polygons overlap.

Parameters:

p1 (Set<OpenStudio::Point3d>) (defaults to: nil) —

1st set of 3D points
p2 (Set<OpenStudio::Point3d>) (defaults to: nil) —

2nd set of 3D points
flat (Bool) (defaults to: false) —

whether points are to be pre-flattened (Z=0)

Returns:

(Bool) —

whether polygons overlap (or fit)
(false) —

if invalid input (see logs)



3672
3673
3674

# File 'lib/osut/utils.rb', line 3672

def overlaps?(p1 = nil, p2 = nil, flat = false)
  overlap(p1, p2, flat).empty? ? false : true
end

#parallel?(p1 = nil, p2 = nil) ⇒ `Bool`, `false`

Validates whether 2 polygons are parallel, regardless of their direction.

Parameters:

p1 (Set<OpenStudio::Point3d>) (defaults to: nil) —

1st set of 3D points
p2 (Set<OpenStudio::Point3d>) (defaults to: nil) —

2nd set of 3D points

Returns:

(Bool) —

whether 2 polygons are parallel
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3398

def parallel?(p1 = nil, p2 = nil)
  p1 = poly(p1, false, true)
  p2 = poly(p2, false, true)
  return false if p1.empty?
  return false if p2.empty?

  n1 = OpenStudio.getOutwardNormal(p1)
  n2 = OpenStudio.getOutwardNormal(p2)
  return false if n1.empty?
  return false if n2.empty?

  n1.get.dot(n2.get).abs > 0.99
end

#plenum?(space = nil) ⇒ `Bool`, `false`

Validates whether a space is an indirectly-conditioned plenum.

Parameters:

space (OpenStudio::Model::Space) (defaults to: nil) —

a space

Returns:

(Bool) —

whether space is considered a plenum
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1884

def plenum?(space = nil)
  # Largely inspired from NREL's "space_plenum?":
  #
  #   github.com/NREL/openstudio-standards/blob/
  #   58964222d25783e9da4ae292e375fb0d5c902aa5/lib/openstudio-standards/
  #   standards/Standards.Space.rb#L1384
  #
  # Ideally, "plenum?" should be in sync with OpenStudio SDK's "isPlenum"
  # method, which solely looks for either HVAC air mixer objects:
  #  - AirLoopHVACReturnPlenum
  #  - AirLoopHVACSupplyPlenum
  #
  # Of the OpenStudio-Standards Prototype models, only the LargeOffice
  # holds AirLoopHVACReturnPlenum objects. OpenStudio-Standards' method
  # "space_plenum?" indeed catches them by checking if the space is
  # "partofTotalFloorArea" (which internally has an "isPlenum" check). So
  # "isPlenum" closely follows ASHRAE 90.1 2016's definition of "plenum":
  #
  #   "plenum": a compartment or chamber ...
  #             - to which one or more ducts are connected
  #             - that forms a part of the air distribution system, and
  #             - that is NOT USED for occupancy or storage.
  #
  # Canadian NECB 2020 has the following (not as well) defined term:
  #   "plenum": a chamber forming part of an air duct system.
  #             ... we'll assume that a space shall also be considered
  #             UNOCCUPIED if it's "part of an air duct system".
  #
  # As intended, "isPlenum" would NOT identify as a "plenum" any vented
  # UNCONDITIONED or UNENCLOSED attic or crawlspace - good. Yet "isPlenum"
  # would also ignore dead air spaces integrating ducted return air. The
  # SDK's "partofTotalFloorArea" would be more suitable in such cases, as
  # long as modellers have, a priori, set this parameter to FALSE.
  #
  # By initially relying on the SDK's "partofTotalFloorArea", "space_plenum?"
  # ends up catching a MUCH WIDER range of spaces, which aren't caught by
  # "isPlenum". This includes attics, crawlspaces, non-plenum air spaces above
  # ceiling tiles, and any other UNOCCUPIED space in a model. The term
  # "plenum" in this context is more of a catch-all shorthand - to be used
  # with caution. For instance, "space_plenum?" shouldn't be used (in
  # isolation) to determine whether an UNOCCUPIED space should have its
  # envelope insulated ("plenum") or not ("attic").
  #
  # In contrast to OpenStudio-Standards' "space_plenum?", the method below
  # strictly returns FALSE if a space is indeed "partofTotalFloorArea". It
  # also returns FALSE if the space is a vestibule. Otherwise, it needs more
  # information to determine if such an UNOCCUPIED space is indeed a
  # plenum. Beyond these 2x criteria, a space is considered a plenum if:
  #
  # CASE A: it includes the substring "plenum" (case insensitive) in its
  #         spaceType's name, or in the latter's standardsSpaceType string;
  #
  # CASE B: "isPlenum" == TRUE in an OpenStudio model WITH HVAC airloops; OR
  #
  # CASE C: its zone holds an 'inactive' thermostat (i.e. can't extract valid
  #         setpoints) in an OpenStudio model with setpoint temperatures.
  #
  # If a modeller is instead simply interested in identifying UNOCCUPIED
  # spaces that are INDIRECTLYCONDITIONED (not necessarily plenums), then the
  # following combination is likely more reliable and less confusing:
  #   - SDK's partofTotalFloorArea == FALSE
  #   - OSut's unconditioned? == FALSE
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Space
  return mismatch("space", space, cl, mth, DBG, false) unless space.is_a?(cl)
  return false if space.partofTotalFloorArea
  return false if vestibule?(space)

  # CASE A: "plenum" spaceType.
  unless space.spaceType.empty?
    type = space.spaceType.get
    return true if type.nameString.downcase.include?("plenum")

    unless type.standardsSpaceType.empty?
      type = type.standardsSpaceType.get.downcase
      return true if type.include?("plenum")
    end
  end

  # CASE B: "isPlenum" == TRUE if airloops.
  return space.isPlenum if airLoopsHVAC?(space.model)

  # CASE C: zone holds an 'inactive' thermostat.
  zone   = space.thermalZone
  heated = heatingTemperatureSetpoints?(space.model)
  cooled = coolingTemperatureSetpoints?(space.model)

  if heated || cooled
    return false if zone.empty?

    zone = zone.get
    heat = maxHeatScheduledSetpoint(zone)
    cool = minCoolScheduledSetpoint(zone)
    return false if heat[:spt] || cool[:spt] # directly CONDITIONED
    return heat[:dual] || cool[:dual]        # FALSE if both are nilled
  end

  false
end

#pointAlongSegment?(p0 = nil, sg = []) ⇒ `Bool`, `false`

Validates whether a 3D point lies ~along a 3D point segment, i.e. less than 10mm from any segment.

Parameters:

p0 (OpenStudio::Point3d) (defaults to: nil) —

a 3D point
sg (Set<OpenStudio::Point3d] a 3D point segment) (defaults to: []) —

g [Set<OpenStudio::Point3d] a 3D point segment

Returns:

(Bool) —

whether a 3D point lies ~along a 3D point segment
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2904

def pointAlongSegment?(p0 = nil, sg = [])
  mth = "OSut::#{__callee__}"
  cl1 = OpenStudio::Point3d
  cl2 = OpenStudio::Point3dVector
  return mismatch(  "point", p0, cl1, mth, DBG, false) unless p0.is_a?(cl1)
  return mismatch("segment", sg, cl2, mth, DBG, false) unless segment?(sg)

  return true if holds?(sg, p0)

  a   = sg.first
  b   = sg.last
  ab  = b - a
  abn = b - a
  abn.normalize
  ap  = p0 - a
  sp = ap.dot(abn)
  return false if sp < 0

  apd = scalar(abn, sp)
  return false if apd.length > ab.length + TOL

  ap0 = a + apd
  return true if (p0 - ap0).length.round(2) <= TOL

  false
end

#pointAlongSegments?(p0 = nil, sgs = []) ⇒ `Bool`, `false`

Validates whether a 3D point lies anywhere ~along a set of 3D point segments, i.e. less than 10mm from any segment.

Parameters:

p0 (OpenStudio::Point3d) (defaults to: nil) —

a 3D point
sgs (Set<OpenStudio::Point3d] 3D point segments) (defaults to: []) —

gs [Set<OpenStudio::Point3d] 3D point segments

Returns:

(Bool) —

whether a 3D point lies ~along a set of 3D point segments
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2940

def pointAlongSegments?(p0 = nil, sgs = [])
  mth = "OSut::#{__callee__}"
  cl1 = OpenStudio::Point3d
  cl2 = OpenStudio::Point3dVectorVector
  sgs = sgs.is_a?(cl2) ? sgs : getSegments(sgs)
  return empty("segments",         mth, DBG, false)     if sgs.empty?
  return mismatch("point", p0, cl, mth, DBG, false) unless p0.is_a?(cl1)

  sgs.each { |sg| return true if pointAlongSegment?(p0, sg) }

  false
end

#pointWithinPolygon?(p0 = nil, s = [], entirely = false) ⇒ `Bool`, `false`

Validates whether 3D point is within a 3D polygon. If option ‘entirely’ is set to true, then the method returns false if point lies along any of the polygon edges, or is very near any of its vertices.

Parameters:

p0 (OpenStudio::Point3d) (defaults to: nil) —

a 3D point
s (Set<OpenStudio::Point3d] a 3D polygon) (defaults to: []) —
Set<OpenStudio::Point3d

a 3D polygon
entirely (Bool) (defaults to: false) —

whether point should be neatly within polygon limits

Returns:

(Bool) —

whether a 3D point lies within a 3D polygon
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3332

def pointWithinPolygon?(p0 = nil, s = [], entirely = false)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Point3d
  s   = poly(s, false, true, true)
  return empty("polygon",          mth, DBG, false)     if s.empty?
  return mismatch("point", p0, cl, mth, DBG, false) unless p0.is_a?(cl)

  n = OpenStudio.getOutwardNormal(s)
  return invalid("plane/normal", mth, 2, DBG, false) if n.empty?

  n  = n.get
  pl = OpenStudio::Plane.new(s.first, n)
  return false unless pl.pointOnPlane(p0)

  entirely = false unless [true, false].include?(entirely)
  segments = getSegments(s)

  # Along polygon edges, or near vertices?
  if pointAlongSegments?(p0, segments)
    return false    if entirely
    return true unless entirely
  end

  segments.each do |segment|
    #   - draw vector from segment midpoint to point
    #   - scale 1000x (assuming no building surface would be 1km wide)
    #   - convert vector to an independent line segment
    #   - loop through polygon segments, tally the number of intersections
    #   - avoid double-counting polygon vertices as intersections
    #   - return false if number of intersections is even
    mid = midpoint(segment.first, segment.last)
    mpV = scalar(mid - p0, 1000)
    p1  = p0 + mpV
    ctr = 0

    # Skip if ~collinear.
    next if mpV.cross(segment.last - segment.first).length.round(4) < TOL2

    segments.each do |sg|
      intersect = getLineIntersection([p0, p1], sg)
      next unless intersect

      # Skip test altogether if one of the polygon vertices.
      if holds?(s, intersect)
        ctr = 0
        break
      else
        ctr += 1
      end
    end

    next         if ctr.zero?
    return false if ctr.even?
  end

  true
end

#poly(pts = nil, vx = false, uq = false, co = false, tt = false, sq = :no) ⇒ `OpenStudio::Point3dVector`

Returns an OpenStudio 3D point vector as basis for a valid OpenStudio 3D polygon. In addition to basic OpenStudio polygon tests (e.g. all points sharing the same 3D plane, non-self-intersecting), the method can optionally check for convexity, or ensure uniqueness and/or non-collinearity. Returned vector can also be ‘aligned’, as well as in UpperLeftCorner (ULC), BottomLeftCorner (BLC), in clockwise (or counterclockwise) sequence.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points
vx (Bool) (defaults to: false) —

whether to check for convexity
uq (Bool) (defaults to: false) —

whether to ensure uniqueness
co (Bool) (defaults to: false) —

whether to ensure non-collinearity
tt (Bool, OpenStudio::Transformation) (defaults to: false) —

whether to ‘align’
sq (:no, :ulc, :blc, :cw) (defaults to: :no) —

unaltered, ULC, BLC or clockwise sequence

Returns:

(OpenStudio::Point3dVector) —

3D points (see logs if empty)

# File 'lib/osut/utils.rb', line 3222

def poly(pts = nil, vx = false, uq = false, co = false, tt = false, sq = :no)
  mth = "OSut::#{__callee__}"
  pts = to_p3Dv(pts)
  cl  = OpenStudio::Transformation
  v   = OpenStudio::Point3dVector.new
  vx  = false unless [true, false].include?(vx)
  uq  = false unless [true, false].include?(uq)
  co  = false unless [true, false].include?(co)

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Exit if mismatched/invalid arguments.
  ok1 = tt == true || tt == false || tt.is_a?(cl)
  ok2 = sq == :no  || sq == :ulc  || sq == :blc || sq == :cw
  return invalid("transformation", mth, 5, DBG, v) unless ok1
  return invalid("sequence",       mth, 6, DBG, v) unless ok2

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Minimum 3 points?
  p3 = getNonCollinears(pts, 3)
  return empty("polygon (non-collinears < 3)", mth, ERR, v) if p3.size < 3

  # Coplanar?
  pln = OpenStudio::Plane.new(p3)

  pts.each do |pt|
    return empty("plane", mth, ERR, v) unless pln.pointOnPlane(pt)
  end

  t  = OpenStudio::Transformation.alignFace(pts)
  at = (t.inverse * pts).reverse

  if tt.is_a?(cl)
    att = (tt.inverse * pts).reverse

    if same?(at, att)
      a = att
      a = ulc(a).to_a if clockwise?(a)
      t = nil
    else
      t = xyz?(att, :z) ? nil : OpenStudio::Transformation.alignFace(att)
      a = t ? (t.inverse * att).reverse : att
    end
  else
    a = at
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Ensure uniqueness and/or non-collinearity. Preserve original sequence.
  p0 = a.first
  a  = getUniques(a).to_a       if uq
  a  = getNonCollinears(a).to_a if co
  i0 = a.index { |pt| same?(pt, p0) }
  a  = a.rotate(i0)             unless i0.nil?

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Check for convexity (optional).
  if vx && a.size > 3
    zen = OpenStudio::Point3d.new(0, 0, 1000)

    getTriads(a).each do |trio|
      p1  = trio[0]
      p2  = trio[1]
      p3  = trio[2]
      v12 = p2 - p1
      v13 = p3 - p1
      x   = (zen - p1).cross(v12)
      return v if x.dot(v13).round(4) > 0
    end
  end

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Alter sequence (optional).
  if tt.is_a?(cl)
    case sq
    when :ulc
      a = t ? to_p3Dv(t * ulc(a.reverse)) : to_p3Dv(ulc(a.reverse))
    when :blc
      a = t ? to_p3Dv(t * blc(a.reverse)) : to_p3Dv(blc(a.reverse))
    when :cw
      a = t ? to_p3Dv(t * a) : to_p3Dv(a)
    else
      a = t ? to_p3Dv(t * a.reverse) : to_p3Dv(a.reverse)
    end
  else
    case sq
    when :ulc
      a = tt ? to_p3Dv(ulc(a.reverse)) : to_p3Dv(t * ulc(a.reverse))
    when :blc
      a = tt ? to_p3Dv(blc(a.reverse)) : to_p3Dv(t * blc(a.reverse))
    when :cw
      a = tt ? to_p3Dv(a) : to_p3Dv(t * a)
    else
      a = tt ? to_p3Dv(a.reverse) : to_p3Dv(t * a.reverse)
    end
  end

  a
end

#rectangular?(pts = nil) ⇒ `Bool`, `false`

Validates whether an OpenStudio polygon is a rectangle (4x sides + 2x diagonals of equal length, meeting at midpoints).

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(Bool) —

whether polygon is rectangular
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3491

def rectangular?(pts = nil)
  pts = poly(pts, false, false, false)
  return false     if pts.empty?
  return false unless pts.size == 4

  m1 = midpoint(pts[0], pts[2])
  m2 = midpoint(pts[1], pts[3])
  return false unless same?(m1, m2)

  diag1 = pts[2] - pts[0]
  diag2 = pts[3] - pts[1]
  return true if (diag1.length - diag2.length).abs < TOL

  false
end

#refrigerated?(space = nil) ⇒ `Bool`, `false`

Validates whether a space can be considered as REFRIGERATED.

Parameters:

space (OpenStudio::Model::Space) (defaults to: nil) —

a space

Returns:

(Bool) —

whether space is considered REFRIGERATED
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2100

def refrigerated?(space = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Space
  tg0 = "refrigerated"
  return mismatch("space", space, cl, mth, DBG, false) unless space.is_a?(cl)

  # 1. First check OSut's REFRIGERATED status.
  status = space.additionalProperties.getFeatureAsString(tg0)

  unless status.empty?
    status = status.get
    return status if [true, false].include?(status)

    log(ERR, "Unknown #{space.nameString} REFRIGERATED #{status} (#{mth})")
  end

  # 2. Else, compare design heating/cooling setpoints.
  stps = setpoints(space)
  return false unless stps[:heating].nil?
  return false     if stps[:cooling].nil?
  return true      if stps[:cooling] < 15

  false
end

#roof?(pts = nil) ⇒ `Bool`, `false`

Validates whether a polygon can be considered a valid ‘roof’ surface, as per ASHRAE 90.1 & Canadian NECBs, i.e. outward normal within 60° from vertical

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points

Returns:

(Bool) —

if considered a roof surface
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3420

def roof?(pts = nil)
  ray = OpenStudio::Point3d.new(0,0,1) - OpenStudio::Point3d.new(0,0,0)
  dut = Math.cos(60 * Math::PI / 180)
  pts = poly(pts, false, true, true)
  return false if pts.empty?

  dot = ray.dot(OpenStudio.getOutwardNormal(pts).get)
  return false if dot.round(2) <= 0
  return true  if dot.round(2) == 1

  dot.round(4) >= dut.round(4)
end

#rsi(lc = nil, film = 0.0, t = 0.0) ⇒ `Float`, `0.0`

Returns a construction’s ‘standard calc’ thermal resistance (m2•K/W), which includes air film resistances. It excludes insulating effects of shades, screens, etc. in the case of fenestrated constructions.

Parameters:

lc (OpenStudio::Model::LayeredConstruction) (defaults to: nil) —

a layered construction
film (Numeric) (defaults to: 0.0) —

thermal resistance of surface air films (m2•K/W)
t (Numeric) (defaults to: 0.0) —

gas temperature (°C) (optional)

Returns:

(Float) —

layered construction’s thermal resistance
(0.0) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 983

def rsi(lc = nil, film = 0.0, t = 0.0)
  # This is adapted from BTAP's Material Module "get_conductance" (P. Lopez)
  #
  #   https://github.com/NREL/OpenStudio-Prototype-Buildings/blob/
  #   c3d5021d8b7aef43e560544699fb5c559e6b721d/lib/btap/measures/
  #   btap_equest_converter/envelope.rb#L122
  mth = "OSut::#{__callee__}"
  cl1 = OpenStudio::Model::LayeredConstruction
  cl2 = Numeric
  return invalid("lc", mth, 1, DBG, 0.0) unless lc.respond_to?(NS)

  id = lc.nameString
  return mismatch(id,       lc, cl1, mth, DBG, 0.0) unless lc.is_a?(cl1)
  return mismatch("film", film, cl2, mth, DBG, 0.0) unless film.is_a?(cl2)
  return mismatch("temp K",  t, cl2, mth, DBG, 0.0) unless t.is_a?(cl2)

  t += 273.0 # °C to K
  return negative("temp K", mth, ERR, 0.0) if t < 0
  return negative("film",   mth, ERR, 0.0) if film < 0

  rsi = film

  lc.layers.each do |m|
    # Fenestration materials first.
    empty = m.to_SimpleGlazing.empty?
    return 1 / m.to_SimpleGlazing.get.uFactor                     unless empty

    empty = m.to_StandardGlazing.empty?
    rsi += m.to_StandardGlazing.get.thermalResistance             unless empty
    empty = m.to_RefractionExtinctionGlazing.empty?
    rsi += m.to_RefractionExtinctionGlazing.get.thermalResistance unless empty
    empty = m.to_Gas.empty?
    rsi += m.to_Gas.get.getThermalResistance(t)                   unless empty
    empty = m.to_GasMixture.empty?
    rsi += m.to_GasMixture.get.getThermalResistance(t)            unless empty

    # Opaque materials next.
    empty = m.to_StandardOpaqueMaterial.empty?
    rsi += m.to_StandardOpaqueMaterial.get.thermalResistance      unless empty
    empty = m.to_MasslessOpaqueMaterial.empty?
    rsi += m.to_MasslessOpaqueMaterial.get.thermalResistance      unless empty
    empty = m.to_RoofVegetation.empty?
    rsi += m.to_RoofVegetation.get.thermalResistance              unless empty
    empty = m.to_AirGap.empty?
    rsi += m.to_AirGap.get.thermalResistance                      unless empty
  end

  rsi
end

#same?(s1 = nil, s2 = nil, indexed = true) ⇒ `Bool`, `false`

Returns true if 2 sets of OpenStudio 3D points are nearly equal.

Parameters:

s1 (Set<OpenStudio::Point3d>) (defaults to: nil) —

1st set of 3D point(s)
s2 (Set<OpenStudio::Point3d>) (defaults to: nil) —

2nd set of 3D point(s)
indexed (Bool) (defaults to: true) —

whether to attempt to harmonize vertex sequence

Returns:

(Bool) —

whether sets are nearly equal (within TOL)
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2428

def same?(s1 = nil, s2 = nil, indexed = true)
  mth = "OSut::#{__callee__}"
  s1  = to_p3Dv(s1).to_a
  s2  = to_p3Dv(s2).to_a
  return false if s1.empty?
  return false if s2.empty?
  return false unless s1.size == s2.size

  indexed = true unless [true, false].include?(indexed)

  if indexed
    xOK = (s1[0].x - s2[0].x).abs < TOL
    yOK = (s1[0].y - s2[0].y).abs < TOL
    zOK = (s1[0].z - s2[0].z).abs < TOL

    if xOK && yOK && zOK && s1.size == 1
      return true
    else
      indx = nil

      s2.each_with_index do |pt, i|
        break if indx

        xOK = (s1[0].x - s2[i].x).abs < TOL
        yOK = (s1[0].y - s2[i].y).abs < TOL
        zOK = (s1[0].z - s2[i].z).abs < TOL

        indx = i if xOK && yOK && zOK
      end

      return false unless indx

      s2 = to_p3Dv(s2).to_a
      s2.rotate!(indx)
    end
  end

  # OpenStudio.isAlmostEqual3dPt(p1, p2, TOL) # ... from v350 onwards.
  s1.size.times.each do |i|
    xOK = (s1[i].x - s2[i].x).abs < TOL
    yOK = (s1[i].y - s2[i].y).abs < TOL
    zOK = (s1[i].z - s2[i].z).abs < TOL
    return false unless xOK && yOK && zOK
  end

  true
end

#scalar(v = OpenStudio::Vector3d.new, m = 0) ⇒ `OpenStudio::Vector3d`

Returns a scalar product of an OpenStudio Vector3d.

Parameters:

v (OpenStudio::Vector3d) (defaults to: OpenStudio::Vector3d.new) —

a vector
m (#to_f) (defaults to: 0) —

a scalar

Returns:

(OpenStudio::Vector3d) —

scaled points (see logs if empty)

# File 'lib/osut/utils.rb', line 2374

def scalar(v = OpenStudio::Vector3d.new, m = 0)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Vector3d
  ok  = m.respond_to?(:to_f)
  return mismatch("vector", v, cl,      mth, DBG, v) unless v.is_a?(cl)
  return mismatch("m",      m, Numeric, mth, DBG, v) unless ok

  m = m.to_f
  OpenStudio::Vector3d.new(m * v.x, m * v.y, m * v.z)
end

#scheduleCompactMinMax(sched = nil) ⇒ `Hash`

Returns MIN/MAX values of a schedule (compact).

Parameters:

sched (OpenStudio::Model::ScheduleCompact) (defaults to: nil) —

schedule

Returns:

(Hash) —

min: (Float), max: (Float)
(Hash) —

min: nil, max: nil if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1374

def scheduleCompactMinMax(sched = nil)
  # Largely inspired from Andrew Parker's
  # "schedule_compact_annual_min_max_value":
  #
  # github.com/NREL/openstudio-standards/blob/
  # 99cf713750661fe7d2082739f251269c2dfd9140/lib/openstudio-standards/
  # standards/Standards.ScheduleCompact.rb#L8
  mth  = "OSut::#{__callee__}"
  cl   = OpenStudio::Model::ScheduleCompact
  vals = []
  prev = ""
  res  = { min: nil, max: nil }
  return invalid("sched", mth, 1, DBG, res) unless sched.respond_to?(NS)

  id = sched.nameString
  return mismatch(id, sched, cl, mth, DBG, res) unless sched.is_a?(cl)

  sched.extensibleGroups.each do |eg|
    if prev.include?("until")
      vals << eg.getDouble(0).get unless eg.getDouble(0).empty?
    end

    str  = eg.getString(0)
    prev = str.get.downcase unless str.empty?
  end

  return empty("#{id} values", mth, ERR, res) if vals.empty?

  res[:min] = vals.min.is_a?(Numeric) ? vals.min : nil
  res[:max] = vals.min.is_a?(Numeric) ? vals.max : nil

  res
end

#scheduleConstantMinMax(sched = nil) ⇒ `Hash`

Returns MIN/MAX values of a schedule (constant).

Parameters:

sched (OpenStudio::Model::ScheduleConstant) (defaults to: nil) —

a schedule

Returns:

(Hash) —

min: (Float), max: (Float)
(Hash) —

min: nil, max: nil if invalid inputs (see logs)

# File 'lib/osut/utils.rb', line 1344

def scheduleConstantMinMax(sched = nil)
  # Largely inspired from David Goldwasser's
  # "schedule_constant_annual_min_max_value":
  #
  # github.com/NREL/openstudio-standards/blob/
  # 99cf713750661fe7d2082739f251269c2dfd9140/lib/openstudio-standards/
  # standards/Standards.ScheduleConstant.rb#L21
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::ScheduleConstant
  res = { min: nil, max: nil }
  return invalid("sched", mth, 1, DBG, res) unless sched.respond_to?(NS)

  id = sched.nameString
  return mismatch(id, sched, cl, mth, DBG, res) unless sched.is_a?(cl)

  ok = sched.value.is_a?(Numeric)
  mismatch("#{id} value", sched.value, Numeric, mth, ERR, res) unless ok
  res[:min] = sched.value
  res[:max] = sched.value

  res
end

#scheduleIntervalMinMax(sched = nil) ⇒ `Hash`

Returns MIN/MAX values for schedule (interval).

Parameters:

sched (OpenStudio::Model::ScheduleInterval) (defaults to: nil) —

schedule

Returns:

(Hash) —

min: (Float), max: (Float)
(Hash) —

min: nil, max: nil if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1415

def scheduleIntervalMinMax(sched = nil)
  mth  = "OSut::#{__callee__}"
  cl   = OpenStudio::Model::ScheduleInterval
  vals = []
  res  = { min: nil, max: nil }
  return invalid("sched", mth, 1, DBG, res) unless sched.respond_to?(NS)

  id = sched.nameString
  return mismatch(id, sched, cl, mth, DBG, res) unless sched.is_a?(cl)

  vals = sched.timeSeries.values

  res[:min] = vals.min.is_a?(Numeric) ? vals.min : nil
  res[:max] = vals.max.is_a?(Numeric) ? vals.min : nil

  res
end

#scheduleRulesetMinMax(sched = nil) ⇒ `Hash`

Returns MIN/MAX values of a schedule (ruleset).

Parameters:

sched (OpenStudio::Model::ScheduleRuleset) (defaults to: nil) —

a schedule

Returns:

(Hash) —

min: (Float), max: (Float)
(Hash) —

min: nil, max: nil if invalid inputs (see logs)

# File 'lib/osut/utils.rb', line 1312

def scheduleRulesetMinMax(sched = nil)
  # Largely inspired from David Goldwasser's
  # "schedule_ruleset_annual_min_max_value":
  #
  # github.com/NREL/openstudio-standards/blob/
  # 99cf713750661fe7d2082739f251269c2dfd9140/lib/openstudio-standards/
  # standards/Standards.ScheduleRuleset.rb#L124
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::ScheduleRuleset
  res = { min: nil, max: nil }
  return invalid("sched", mth, 1, DBG, res) unless sched.respond_to?(NS)

  id = sched.nameString
  return mismatch(id, sched, cl, mth, DBG, res) unless sched.is_a?(cl)

  values = sched.defaultDaySchedule.values.to_a

  sched.scheduleRules.each { |rule| values += rule.daySchedule.values }

  res[:min] = values.min.is_a?(Numeric) ? values.min : nil
  res[:max] = values.max.is_a?(Numeric) ? values.max : nil

  res
end

#segment?(pts = nil) ⇒ `Bool`, `false`

Determines if a set of 3D points if a valid segment.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(Bool) —

whether set is a valid segment
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2834

def segment?(pts = nil)
  pts = to_p3Dv(pts)
  return false     if pts.empty?
  return false unless pts.size == 2
  return false     if same?(pts[0], pts[1])

  true
end

#semiheated?(space = nil) ⇒ `Bool`, `false`

Validates whether a space can be considered as SEMIHEATED as per NECB 2020 1.2.1.2. 2): design heating setpoint < 15°C (and non-REFRIGERATED).

Parameters:

space (OpenStudio::Model::Space) (defaults to: nil) —

a space

Returns:

(Bool) —

whether space is considered SEMIHEATED
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2133

def semiheated?(space = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Space
  return mismatch("space", space, cl, mth, DBG, false) unless space.is_a?(cl)
  return false if refrigerated?(space)

  stps = setpoints(space)
  return false unless stps[:cooling].nil?
  return false     if stps[:heating].nil?
  return true      if stps[:heating] < 15

  false
end

#setpoints(space = nil) ⇒ `Hash`

Retrieves a space’s (implicit or explicit) heating/cooling setpoints.

Parameters:

space (OpenStudio::Model::Space) (defaults to: nil) —

a space

Returns:

(Hash) —

heating: (Float), cooling: (Float)
(Hash) —

heating: nil, cooling: nil if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1991

def setpoints(space = nil)
  mth = "OSut::#{__callee__}"
  cl1 = OpenStudio::Model::Space
  cl2 = String
  res = {heating: nil, cooling: nil}
  tg1 = "space_conditioning_category"
  tg2 = "indirectlyconditioned"
  cts = ["nonresconditioned", "resconditioned", "semiheated", "unconditioned"]
  cnd = nil
  return mismatch("space", space, cl1, mth, DBG, res) unless space.is_a?(cl1)

  # 1. Check for OpenStudio-Standards' space conditioning categories.
  if space.additionalProperties.hasFeature(tg1)
    cnd = space.additionalProperties.getFeatureAsString(tg1)

    if cnd.empty?
      cnd = nil
    else
      cnd = cnd.get

      if cts.include?(cnd.downcase)
        return res if cnd.downcase == "unconditioned"
      else
        invalid("#{tg1}:#{cnd}", mth, 0, ERR)
        cnd = nil
      end
    end
  end

  # 2. Check instead OSut's INDIRECTLYCONDITIONED (parent space) link.
  if cnd.nil?
    id = space.additionalProperties.getFeatureAsString(tg2)

    unless id.empty?
      id  = id.get
      dad = space.model.getSpaceByName(id)

      if dad.empty?
        log(ERR, "Unknown space #{id} (#{mth})")
      else
        # Now focus on 'parent' space linked to INDIRECTLYCONDITIONED space.
        space = dad.get
        cnd   = tg2
      end
    end
  end

  # 3. Fetch space setpoints (if model indeed holds valid setpoints).
  heated = heatingTemperatureSetpoints?(space.model)
  cooled = coolingTemperatureSetpoints?(space.model)
  zone   = space.thermalZone

  if heated || cooled
    return res if zone.empty? # UNCONDITIONED

    zone = zone.get
    res[:heating] = maxHeatScheduledSetpoint(zone)[:spt]
    res[:cooling] = minCoolScheduledSetpoint(zone)[:spt]
  end

  # 4. Reset if AdditionalProperties were found & valid.
  unless cnd.nil?
    if cnd.downcase == "unconditioned"
      res[:heating] = nil
      res[:cooling] = nil
    elsif cnd.downcase == "semiheated"
      res[:heating] = 14.0 if res[:heating].nil?
      res[:cooling] = nil
    elsif cnd.downcase.include?("conditioned")
      # "nonresconditioned", "resconditioned" or "indirectlyconditioned"
      res[:heating] = 21.0 if res[:heating].nil? # default
      res[:cooling] = 24.0 if res[:cooling].nil? # default
    end
  end

  # 5. Reset if plenum?
  if plenum?(space)
    res[:heating] = 21.0 if res[:heating].nil? # default
    res[:cooling] = 24.0 if res[:cooling].nil? # default
  end

  res
end

#sloped?(pts = nil) ⇒ `Bool`, `false`

Validates whether surface can be considered ‘sloped’ (i.e. not ~flat, as per OpenStudio Utilities’ “alignZPrime”). A vertical polygon returns true.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points

Returns:

(Bool) —

whether surface is sloped
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3473

def sloped?(pts = nil)
  mth = "OSut::#{__callee__}"
  pts = poly(pts, false, true, true)
  return false if pts.empty?
  return false if facingUp?(pts)
  return false if facingDown?(pts)

  true
end

#spandrel?(s = nil) ⇒ `Bool`, `false`

Validates whether opaque surface can be considered as a curtain wall (or similar technology) spandrel, regardless of construction layers, by looking up AdditionalProperties or its identifier.

Parameters:

s (OpenStudio::Model::Surface) (defaults to: nil) —

an opaque surface

Returns:

(Bool) —

whether surface can be considered ‘spandrel’
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1097

def spandrel?(s = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Surface
  return invalid("surface", mth, 1, DBG, false) unless s.respond_to?(NS)

  id = s.nameString
  m1  = "#{id}:spandrel"
  m2  = "#{id}:spandrel:boolean"
  return mismatch(id, s, cl, mth) unless s.is_a?(cl)

  if s.additionalProperties.hasFeature("spandrel")
    val = s.additionalProperties.getFeatureAsBoolean("spandrel")
    return invalid(m1, mth, 1, ERR, false) if val.empty?

    val = val.get
    return invalid(m2, mth, 1, ERR, false) unless [true, false].include?(val)
    return val
  end

  id.downcase.include?("spandrel")
end

#square?(pts = nil) ⇒ `Bool`, `false`

Validates whether an OpenStudio polygon is a square (rectangular, 4x ~equal sides).

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(Bool) —

whether polygon is a square
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 3515

def square?(pts = nil)
  d   = nil
  pts = poly(pts, false, false, false)
  return false if pts.empty?
  return false unless rectangular?(pts)

  getSegments(pts).each do |pt|
    l = (pt[1] - pt[0]).length
    d = l unless d
    return false unless l.round(2) == d.round(2)
  end

  true
end

#standardOpaqueLayers?(lc = nil) ⇒ `Bool`, `false`

Validates if every material in a layered construction is standard & opaque.

Parameters:

lc (OpenStudio::LayeredConstruction) (defaults to: nil) —

a layered construction

Returns:

(Bool) —

whether all layers are valid
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 898

def standardOpaqueLayers?(lc = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::LayeredConstruction
  return invalid("lc", mth, 1, DBG, false) unless lc.respond_to?(NS)
  return mismatch(lc.nameString, lc, cl, mth, DBG, false) unless lc.is_a?(cl)

  lc.layers.each { |m| return false if m.to_StandardOpaqueMaterial.empty? }

  true
end

#thickness(lc = nil) ⇒ `Float`, `0.0`

Returns total (standard opaque) layered construction thickness (m).

Parameters:

lc (OpenStudio::LayeredConstruction) (defaults to: nil) —

a layered construction

Returns:

(Float) —

construction thickness
(0.0) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 916

def thickness(lc = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::LayeredConstruction
  return invalid("lc", mth, 1, DBG, 0.0) unless lc.respond_to?(NS)

  id = lc.nameString
  return mismatch(id, lc, cl, mth, DBG, 0.0) unless lc.is_a?(cl)

  ok = standardOpaqueLayers?(lc)
  log(ERR, "'#{id}' holds non-StandardOpaqueMaterial(s) (#{mth})")  unless ok
  return 0.0                                                        unless ok

  thickness = 0.0
  lc.layers.each { |m| thickness += m.thickness }

  thickness
end

#to_p3Dv(pts = nil) ⇒ `OpenStudio::Point3dVector`

Returns OpenStudio 3D points as an OpenStudio point vector, validating points in the process (if Array).

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points

Returns:

(OpenStudio::Point3dVector) —

3D vector (see logs if empty)

# File 'lib/osut/utils.rb', line 2392

def to_p3Dv(pts = nil)
  mth = "OSut::#{__callee__}"
  cl1 = OpenStudio::Point3d
  cl2 = OpenStudio::Point3dVector
  cl3 = OpenStudio::Model::PlanarSurface
  cl4 = Array
  v   = OpenStudio::Point3dVector.new

  if pts.is_a?(cl1)
    v << pts
    return v
  end

  return pts if pts.is_a?(cl2)
  return pts.vertices if pts.is_a?(cl3)

  return mismatch("points", pts, cl1, mth, DBG, v) unless pts.is_a?(cl4)

  pts.each do |pt|
    return mismatch("point", pt, cl4, mth, DBG, v) unless pt.is_a?(cl1)
  end

  pts.each { |pt| v << OpenStudio::Point3d.new(pt.x, pt.y, pt.z) }

  v
end

#toToplit(spaces = [], opts = {}) ⇒ `Array<OpenStudio::Model::Space>`

Preselects ideal spaces to toplight, based on ‘addSkylights’ options and key building model geometry attributes. Can be called from within ‘addSkylights’ by setting :ration (opts key:value argument) to ‘true’ (‘false’ by default). Alternatively, the method can be called prior to ‘addSkylights’. The set of filters stems from previous rounds of ‘addSkylights’ stress testing. It is intended as an option to prune away less ideal candidate spaces (irregular, smaller) in favour of (larger) candidates (notably with more suitable roof geometries). This is key when dealing with attic and plenums, where ‘addSkylights’ seeks to add skylight wells (relying on roof cut-outs and leader lines). Another check/outcome is whether to prioritize skylight allocation in already sidelit spaces - opts may be reset to ‘true’.

Parameters:

spaces (Array<OpenStudio::Model::Space>) (defaults to: []) —

candidate(s) to toplight
opts (Hash) (defaults to: {}) —

requested skylight attributes (same as ‘addSkylights’)

Options Hash (opts):

:size (#to_f) — default: 1.22m —

template skylight width/depth (min 0.4m)

Returns:

(Array<OpenStudio::Model::Space>) —

candidates (see logs if empty)

# File 'lib/osut/utils.rb', line 6092

def toToplit(spaces = [], opts = {})
  mth  = "OSut::#{__callee__}"
  gap4 = 0.4  # minimum skylight 16" width/depth (excluding frame width)
  w    = 1.22 # default 48" x 48" skylight base
  w2   = w * w

  # Validate skylight size, if provided.
  if opts.key?(:size)
    if opts[:size].respond_to?(:to_f)
      w  = opts[:size].to_f
      w2 = w * w
      return invalid(size, mth, 0, ERR, []) if w.round(2) < gap4
    else
      return mismatch("size", opts[:size], Numeric, mth, DBG, [])
    end
  end

  # Accept single 'OpenStudio::Model::Space' (vs an array of spaces). Filter.
  #
  # Whether individual spaces are UNCONDITIONED (e.g. attics, unheated areas)
  # or flagged as NOT being part of the total floor area (e.g. unoccupied
  # plenums), should of course reflect actual design intentions. It's up to
  # modellers to correctly flag such cases - can't safely guess in lieu of
  # design/modelling team.
  #
  # A friendly reminder: 'addSkylights' should be called separately for
  # strictly SEMIHEATED spaces vs REGRIGERATED spaces vs all other CONDITIONED
  # spaces, as per 90.1 and NECB requirements.
  if spaces.respond_to?(:spaceType) || spaces.respond_to?(:to_a)
    spaces = spaces.respond_to?(:to_a) ? spaces.to_a : [spaces]
    spaces = spaces.select { |sp| sp.respond_to?(:spaceType) }
    spaces = spaces.select { |sp| sp.partofTotalFloorArea }
    spaces = spaces.reject { |sp| unconditioned?(sp) }
    spaces = spaces.reject { |sp| vestibule?(sp) }
    spaces = spaces.reject { |sp| getRoofs(sp).empty? }
    spaces = spaces.reject { |sp| sp.floorArea < 4 * w2 }
    spaces = spaces.sort_by(&:floorArea).reverse
    return empty("spaces", mth, WRN, 0) if spaces.empty?
  else
    return mismatch("spaces", spaces, Array, mth, DBG, 0)
  end

  # Unfenestrated spaces have no windows, glazed doors or skylights. By
  # default, 'addSkylights' will prioritize unfenestrated spaces (over all
  # existing sidelit ones) and maximize skylight sizes towards achieving the
  # required skylight area target. This concentrates skylights for instance in
  # typical (large) core spaces, vs (narrower) perimeter spaces. However, for
  # less conventional spatial layouts, this default approach can produce less
  # optimal skylight distributions. A balance is needed to prioritize large
  # unfenestrated spaces when appropriate on one hand, while excluding smaller
  # unfenestrated ones on the other. Here, exclusion is based on the average
  # floor area of spaces to toplight.
  fm2  = spaces.sum(&:floorArea)
  afm2 = fm2 / spaces.size

  unfen = spaces.reject { |sp| daylit?(sp) }.sort_by(&:floorArea).reverse

  # Target larger unfenestrated spaces, if sufficient in area.
  if unfen.empty?
    opts[:sidelit] = true
  else
    if spaces.size > unfen.size
      ufm2  = unfen.sum(&:floorArea)
      u0fm2 = unfen.first.floorArea

      if ufm2 > 0.33 * fm2 && u0fm2 > 3 * afm2
        unfen  = unfen.reject { |sp| sp.floorArea > 0.25 * afm2 }
        spaces = spaces.reject { |sp| unfen.include?(sp) }
      else
        opts[:sidelit] = true
      end
    end
  end

  espaces = {}
  rooms   = []
  toits   = []

  # Gather roof surfaces - possibly those of attics or plenums above.
  spaces.each do |sp|
    getRoofs(sp).each do |rf|
      espaces[sp] = {roofs: []} unless espaces.key?(sp)
      espaces[sp][:roofs] << rf unless espaces[sp][:roofs].include?(rf)
    end
  end

  # Priortize larger spaces.
  espaces = espaces.sort_by { |espace, _| espace.floorArea }.reverse

  # Prioritize larger roof surfaces.
  espaces.each do |_, datum|
    datum[:roofs] = datum[:roofs].sort_by(&:grossArea).reverse
  end

  # Single out largest roof in largest space, key when dealing with shared
  # attics or plenum roofs.
  espaces.each do |espace, datum|
    rfs = datum[:roofs].reject { |ruf| toits.include?(ruf) }
    next if rfs.empty?

    toits << rfs.sort { |ruf| ruf.grossArea }.reverse.first
    rooms << espace
  end

  log(INF, "No ideal toplit candidates (#{mth})") if rooms.empty?

  rooms
end

#transforms(group = nil) ⇒ `Hash`

Returns OpenStudio site/space transformation & rotation angle [0,2PI) rads.

Parameters:

group (OpenStudio::Model::PlanarSurfaceGroup) (defaults to: nil) —

a site or space object

Returns:

(Hash) —

t: (OpenStudio::Transformation), r: (Float)
(Hash) —

t: nil, r: nil if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2329

def transforms(group = nil)
  mth = "OSut::#{__callee__}"
  cl2 = OpenStudio::Model::PlanarSurfaceGroup
  res = { t: nil, r: nil }
  return invalid("group", mth, 2, DBG, res) unless group.respond_to?(NS)

  id  = group.nameString
  mdl = group.model
  return mismatch(id, group, cl2, mth, DBG, res) unless group.is_a?(cl2)

  res[:t] = group.siteTransformation
  res[:r] = group.directionofRelativeNorth + mdl.getBuilding.northAxis

  res
end

#triad?(pts = nil) ⇒ `Bool`, `false`

Determines if a set of 3D points if a valid triad.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(Bool) —

whether set is a valid triad (i.e. a trio of 3D points)
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2884

def triad?(pts = nil)
  pts = to_p3Dv(pts)
  return false     if pts.empty?
  return false unless pts.size == 3
  return false     if same?(pts[0], pts[1])
  return false     if same?(pts[0], pts[2])
  return false     if same?(pts[1], pts[2])

  true
end

#triadBox(pts = nil) ⇒ `Set<OpenStudio::Point3D>`

Generates a BLC box from a triad (3D points). Points must be unique and non-collinear.

Parameters:

a (Set<OpenStudio::Point3d>) —

triad (3D points)

Returns:

(Set<OpenStudio::Point3D>) —

a rectangular ULC box (see logs if empty)

# File 'lib/osut/utils.rb', line 4027

def triadBox(pts = nil)
  mth = "OSut::#{__callee__}"
  bkp = OpenStudio::Point3dVector.new
  box = []
  pts = getNonCollinears(pts)
  return bkp if pts.empty?

  t   = xyz?(pts, :z) ? nil : OpenStudio::Transformation.alignFace(pts)
  pts = poly(pts, false, true, true, t) if t
  return bkp if pts.empty?
  return invalid("triad", mth, 1, ERR, bkp) unless pts.size == 3

  pts = to_p3Dv(pts.to_a.reverse) if clockwise?(pts)
  p0  = pts[0]
  p1  = pts[1]
  p2  = pts[2]

  # Cast p0 unto vertical plane defined by p1/p2.
  pp0 = verticalPlane(p1, p2).project(p0)
  v00 = p0  - pp0
  v11 = pp0 - p1
  v10 = p0  - p1
  v12 = p2  - p1

  # Reset p0 and/or p1 if obtuse or acute.
  if v12.dot(v10) < 0
    p0 = p1 + v00
  elsif v12.dot(v10) > 0
    if v11.length < v12.length
      p1 = pp0
    else
      p0 = p1 + v00
    end
  end

  p3 = p2 + v00

  box << OpenStudio::Point3d.new(p0.x, p0.y, p0.z)
  box << OpenStudio::Point3d.new(p1.x, p1.y, p1.z)
  box << OpenStudio::Point3d.new(p2.x, p2.y, p2.z)
  box << OpenStudio::Point3d.new(p3.x, p3.y, p3.z)
  box = getNonCollinears(box, 4)
  return bkp unless box.size == 4

  box = blc(box)
  return bkp unless rectangular?(box)

  box = to_p3Dv(t * box) if t

  box
end

#trueNormal(s = nil, r = 0) ⇒ `OpenStudio::Vector3d`^?

Returns the site/true outward normal vector of a surface.

Parameters:

s (OpenStudio::Model::PlanarSurface) (defaults to: nil) —

a surface
r (#to_f) (defaults to: 0) —

a group/site rotation angle [0,2PI) radians

Returns:

(OpenStudio::Vector3d) —

true normal vector
(nil) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2353

def trueNormal(s = nil, r = 0)
  mth = "TBD::#{__callee__}"
  cl  = OpenStudio::Model::PlanarSurface
  return mismatch("surface", s, cl, mth)   unless s.is_a?(cl)
  return invalid("rotation angle", mth, 2) unless r.respond_to?(:to_f)

  r = -r.to_f * Math::PI / 180.0
  vx = s.outwardNormal.x * Math.cos(r) - s.outwardNormal.y * Math.sin(r)
  vy = s.outwardNormal.x * Math.sin(r) + s.outwardNormal.y * Math.cos(r)
  vz = s.outwardNormal.z

  OpenStudio::Point3d.new(vx, vy, vz) - OpenStudio::Point3d.new(0, 0, 0)
end

#ulc(pts = nil) ⇒ `OpenStudio::Point3dVector`

Returns OpenStudio 3D points (min 3x) conforming to an UpperLeftCorner (ULC) convention. Points Z-axis values must be ~= 0. Points are returned counterclockwise.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(OpenStudio::Point3dVector) —

ULC points (see logs if empty)

# File 'lib/osut/utils.rb', line 3092

def ulc(pts = nil)
  mth = "OSut::#{__callee__}"
  v   = OpenStudio::Point3dVector.new
  pts = to_p3Dv(pts).to_a
  return invalid("points (3+)",      mth, 1, DBG, v)     if pts.size < 3
  return invalid("points (aligned)", mth, 1, DBG, v) unless xyz?(pts, :z)

  # Ensure counterclockwise sequence.
  pts  = pts.reverse if clockwise?(pts)
  minX = pts.min_by(&:x).x
  i0   = nearest(pts)
  p0   = pts[i0]

  pts_x = pts.select { |pt| pt.x.round(2) == minX.round(2) }.reverse

  p1 = pts_x.max_by { |pt| (pt - p0).length }
  i1 = pts.index(p1)

  to_p3Dv(pts.rotate(i1))
end

#unconditioned?(space = nil) ⇒ `Bool`, `false`

Validates if a space is UNCONDITIONED.

Parameters:

space (OpenStudio::Model::Space) (defaults to: nil) —

a space

Returns:

(Bool) —

whether space is considered UNCONDITIONED
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2082

def unconditioned?(space = nil)
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Space
  return mismatch("space", space, cl, mth, DBG, false) unless space.is_a?(cl)

  ok = false
  ok = setpoints(space)[:heating].nil? && setpoints(space)[:cooling].nil?

  ok
end

#verticalPlane(p1 = nil, p2 = nil) ⇒ `OpenStudio::Plane`^?

Returns a vertical 3D plane from 2x 3D points, right-hand rule. Input points are considered last 2 (of 3) points forming the plane; the first point is assumed zenithal. Input points cannot align vertically.

Parameters:

p1 (OpenStudio::Point3d) (defaults to: nil) —

1st 3D point of a line segment
p2 (OpenStudio::Point3d) (defaults to: nil) —

2nd 3D point of a line segment

Returns:

(OpenStudio::Plane) —

3D plane
(nil) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2754

def verticalPlane(p1 = nil, p2 = nil)
  mth = "OSut::#{__callee__}"
  return mismatch("point 1", p1, cl, mth) unless p1.is_a?(OpenStudio::Point3d)
  return mismatch("point 2", p2, cl, mth) unless p2.is_a?(OpenStudio::Point3d)

  if (p1.x - p2.x).abs < TOL && (p1.y - p2.y).abs < TOL
    return invalid("vertically aligned points", mth)
  end

  zenith = OpenStudio::Point3d.new(p1.x, p1.y, (p2 - p1).length)
  points = OpenStudio::Point3dVector.new
  points << zenith
  points << p1
  points << p2

  OpenStudio::Plane.new(points)
end

#vestibule?(space = nil) ⇒ `Bool`, `false`

Validates whether space is a vestibule.

Parameters:

space (OpenStudio::Model::Space) (defaults to: nil) —

a space

Returns:

(Bool) —

whether space is considered a vestibule
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 1812

def vestibule?(space = nil)
  # INFO: OpenStudio-Standards' "thermal_zone_vestibule" criteria:
  #   - zones less than 200ft2; AND
  #   - having infiltration using Design Flow Rate
  #
  #   github.com/NREL/openstudio-standards/blob/
  #   86bcd026a20001d903cc613bed6d63e94b14b142/lib/openstudio-standards/
  #   standards/Standards.ThermalZone.rb#L1264
  #
  # This (unused) OpenStudio-Standards method likely needs revision; it would
  # return "false" if the thermal zone area were less than 200ft2. Not sure
  # which edition of 90.1 relies on a 200ft2 threshold (2010?); 90.1 2016
  # doesn't. Yet even fixed, the method would nonetheless misidentify as
  # "vestibule" a small space along an exterior wall, such as a semiheated
  # storage space.
  #
  # The code below is intended as a simple short-term solution, basically
  # relying on AdditionalProperties, or (if missing) a "vestibule" substring
  # within a space's spaceType name (or the latter's standardsSpaceType).
  #
  # Alternatively, some future method could infer its status as a vestibule
  # based on a few basic features (common to all vintages):
  #   - 1x+ outdoor-facing wall(s) holding 1x+ door(s)
  #   - adjacent to 1x+ 'occupied' conditioned space(s)
  #   - ideally, 1x+ door(s) between vestibule and 1x+ such adjacent space(s)
  #
  # An additional method parameter (i.e. std = :necb) could be added to
  # ensure supplementary Standard-specific checks, e.g. maximum floor area,
  # minimum distance between doors.
  #
  # Finally, an entirely separate method could be developed to first identify
  # whether "building entrances" (a defined term in 90.1) actually require
  # vestibules as per specific code requirements. Food for thought.
  mth = "OSut::#{__callee__}"
  cl  = OpenStudio::Model::Space
  return mismatch("space", space, cl, mth, DBG, false) unless space.is_a?(cl)

  id  = space.nameString
  m1  = "#{id}:vestibule"
  m2  = "#{id}:vestibule:boolean"

  if space.additionalProperties.hasFeature("vestibule")
    val = space.additionalProperties.getFeatureAsBoolean("vestibule")
    return invalid(m1, mth, 1, ERR, false) if val.empty?

    val = val.get
    return invalid(m2, mth, 1, ERR, false) unless [true, false].include?(val)
    return val
  end

  unless space.spaceType.empty?
    type = space.spaceType.get
    return false if type.nameString.downcase.include?("plenum")
    return true  if type.nameString.downcase.include?("vestibule")

    unless type.standardsSpaceType.empty?
      type = type.standardsSpaceType.get.downcase
      return false if type.include?("plenum")
      return true  if type.include?("vestibule")
    end
  end

  false
end

#width(pts = nil) ⇒ `Float`, `0.0`

Returns ‘width’ of a set of OpenStudio 3D points.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

3D points

Returns:

(Float) —

width along X-axis, once re/aligned
(0.0) —

if invalid inputs

# File 'lib/osut/utils.rb', line 2697

def width(pts = nil)
  pts = to_p3Dv(pts)
  return 0 if pts.size < 2

  pts.max_by(&:x).x - pts.min_by(&:x).x
end

#xyz?(pts = nil, axs = :z, val = 0) ⇒ `Bool`, `false`

Validates whether 3D points share X, Y or Z coordinates.

Parameters:

pts (Set<OpenStudio::Point3d>) (defaults to: nil) —

OpenStudio 3D points
axs (Symbol) (defaults to: :z) —

if potentially along :x, :y or :z axis
val (Numeric) (defaults to: 0) —

axis value

Returns:

(Bool) —

if points share X, Y or Z coordinates
(false) —

if invalid input (see logs)

# File 'lib/osut/utils.rb', line 2647

def xyz?(pts = nil, axs = :z, val = 0)
  mth = "OSut::#{__callee__}"
  pts = to_p3Dv(pts)
  ok1 = val.respond_to?(:to_f)
  ok2 = [:x, :y, :z].include?(axs)
  return false if pts.empty?
  return mismatch("val", val, Numeric, mth,    DBG, false) unless ok1
  return invalid("axis",               mth, 2, DBG, false) unless ok2

  val = val.to_f

  case axs
  when :x
    pts.each { |pt| return false if (pt.x - val).abs > TOL }
  when :y
    pts.each { |pt| return false if (pt.y - val).abs > TOL }
  else
    pts.each { |pt| return false if (pt.z - val).abs > TOL }
  end

  true
end

Module: OSut

Overview

Constant Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extended(base) ⇒ Object

Instance Method Details

#addSkyLights(spaces = [], opts = {}) ⇒ Float

Examples:

(a) consider 2D array of individual skylights, e.g. n(1.22m x 1.22m)

(b) consider ‘a’, then array of 1x(size) x n(size) skylight strips

#addSubs(s = nil, subs = [], clear = false, bound = false, realign = false, bfr = 0.005) ⇒ Bool, false

#airLoopsHVAC?(model = nil) ⇒ Bool, false

#alignedHeight(pts = nil, force = false) ⇒ Float, 0.0

#alignedWidth(pts = nil, force = false) ⇒ Float, 0.0

#availabilitySchedule(model = nil, avl = "") ⇒ OpenStudio::Model::Schedule?

#blc(pts = nil) ⇒ OpenStudio::Point3dVector

#boundedBox(pts = nil) ⇒ OpenStudio::Point3dVector

#cast(p1 = nil, p2 = nil, ray = nil) ⇒ OpenStudio::Point3dVector

#clockwise?(pts = nil) ⇒ Bool, false

#coolingTemperatureSetpoints?(model = nil) ⇒ Bool, false

#daylit?(space = nil, sidelit = true, toplit = true, baselit = true) ⇒ Bool, false

#defaultConstructionSet(s = nil) ⇒ OpenStudio::Model::DefaultConstructionSet?

#facets(spaces = [], boundary = "all", type = "all", sides = []) ⇒ Array<OpenStudio::Model::Surface>

#facingDown?(pts = nil) ⇒ Bool, false

#facingUp?(pts = nil) ⇒ Bool, false

#farthest(pts = nil, p01 = nil) ⇒ Integer?

#fenestration?(s = nil) ⇒ Bool, false

#fits?(p1 = nil, p2 = nil, entirely = false) ⇒ Bool, false

#flatten(pts = nil, axs = :z, val = 0) ⇒ OpenStudio::Point3dVector

#genAnchors(s = nil, set = [], tag = :box) ⇒ Integer

#genConstruction(model = nil, specs = {}) ⇒ OpenStudio::Model::Construction?

#genExtendedVertices(s = nil, set = [], tag = :vtx) ⇒ OpenStudio::Point3dVector

#genInserts(s = nil, set = []) ⇒ OpenStudio::Point3dVector

#genMass(sps = OpenStudio::Model::SpaceVector.new, ratio = 2.0) ⇒ Bool, false

#genShade(subs = OpenStudio::Model::SubSurfaceVector.new) ⇒ Bool, false

#genSlab(pltz = [], z = 0) ⇒ OpenStudio::Point3dVector

#getCollinears(pts = nil, n = 0) ⇒ OpenStudio::Point3dVector

#getHorizontalRidges(roofs = []) ⇒ Array

#getLineIntersection(s1 = [], s2 = []) ⇒ OpenStudio::Point3d?

#getNonCollinears(pts = nil, n = 0) ⇒ OpenStudio::Point3dVector

#getRealignedFace(pts = nil, force = false) ⇒ Hash

#getRoofs(spaces = []) ⇒ Array<OpenStudio::Model::Surface>

#getSegments(pts = nil) ⇒ OpenStudio::Point3dVectorVector

#getTriads(pts = nil, co = false) ⇒ OpenStudio::Point3dVectorVector

#getUniques(pts = nil, n = 0) ⇒ OpenStudio::Point3dVector

#glazingAirFilmRSi(usi = 5.85) ⇒ Float, 0.1216

#grossRoofArea(spaces = []) ⇒ Object

#heatingTemperatureSetpoints?(model = nil) ⇒ Bool, false

#height(pts = nil) ⇒ Float, 0.0

#holds?(pts = nil, p1 = nil) ⇒ Bool, false

#holdsConstruction?(set = nil, bse = nil, gr = false, ex = false, tp = "") ⇒ Bool, false

#insulatingLayer(lc = nil) ⇒ Hash

#lineIntersects?(l = [], s = []) ⇒ Bool, false

#maxHeatScheduledSetpoint(zone = nil) ⇒ Hash

#medialBox(pts = nil) ⇒ OpenStudio::Point3dVector

#midpoint(p1 = nil, p2 = nil) ⇒ OpenStudio::Point3d?

#minCoolScheduledSetpoint(zone = nil) ⇒ Hash

#nearest(pts = nil, p01 = nil) ⇒ Integer?

#nextUp(pts = nil, pt = nil) ⇒ OpenStudio::Point3d?

#offset(p1 = nil, w = 0, v = 0) ⇒ OpenStudio::Point3dVector

#outline(a = [], bfr = 0, flat = true) ⇒ OpenStudio::Point3dVector

#overlap(p1 = nil, p2 = nil, flat = false) ⇒ OpenStudio::Point3dVector

#overlaps?(p1 = nil, p2 = nil, flat = false) ⇒ Bool, false

#parallel?(p1 = nil, p2 = nil) ⇒ Bool, false

#plenum?(space = nil) ⇒ Bool, false

#pointAlongSegment?(p0 = nil, sg = []) ⇒ Bool, false

#pointAlongSegments?(p0 = nil, sgs = []) ⇒ Bool, false

#pointWithinPolygon?(p0 = nil, s = [], entirely = false) ⇒ Bool, false

#poly(pts = nil, vx = false, uq = false, co = false, tt = false, sq = :no) ⇒ OpenStudio::Point3dVector

#rectangular?(pts = nil) ⇒ Bool, false

#refrigerated?(space = nil) ⇒ Bool, false

#roof?(pts = nil) ⇒ Bool, false

#rsi(lc = nil, film = 0.0, t = 0.0) ⇒ Float, 0.0

#same?(s1 = nil, s2 = nil, indexed = true) ⇒ Bool, false

#scalar(v = OpenStudio::Vector3d.new, m = 0) ⇒ OpenStudio::Vector3d

#scheduleCompactMinMax(sched = nil) ⇒ Hash

#scheduleConstantMinMax(sched = nil) ⇒ Hash

#scheduleIntervalMinMax(sched = nil) ⇒ Hash

.extended(base) ⇒ `Object`

#addSkyLights(spaces = [], opts = {}) ⇒ `Float`

#addSubs(s = nil, subs = [], clear = false, bound = false, realign = false, bfr = 0.005) ⇒ `Bool`, `false`

#airLoopsHVAC?(model = nil) ⇒ `Bool`, `false`

#alignedHeight(pts = nil, force = false) ⇒ `Float`, `0.0`

#alignedWidth(pts = nil, force = false) ⇒ `Float`, `0.0`

#availabilitySchedule(model = nil, avl = "") ⇒ `OpenStudio::Model::Schedule`^?

#blc(pts = nil) ⇒ `OpenStudio::Point3dVector`

#boundedBox(pts = nil) ⇒ `OpenStudio::Point3dVector`

#cast(p1 = nil, p2 = nil, ray = nil) ⇒ `OpenStudio::Point3dVector`

#clockwise?(pts = nil) ⇒ `Bool`, `false`

#coolingTemperatureSetpoints?(model = nil) ⇒ `Bool`, `false`

#daylit?(space = nil, sidelit = true, toplit = true, baselit = true) ⇒ `Bool`, `false`

#defaultConstructionSet(s = nil) ⇒ `OpenStudio::Model::DefaultConstructionSet`^?

#facets(spaces = [], boundary = "all", type = "all", sides = []) ⇒ `Array<OpenStudio::Model::Surface>`

#facingDown?(pts = nil) ⇒ `Bool`, `false`

#facingUp?(pts = nil) ⇒ `Bool`, `false`

#farthest(pts = nil, p01 = nil) ⇒ `Integer`^?

#fenestration?(s = nil) ⇒ `Bool`, `false`

#fits?(p1 = nil, p2 = nil, entirely = false) ⇒ `Bool`, `false`

#flatten(pts = nil, axs = :z, val = 0) ⇒ `OpenStudio::Point3dVector`

#genAnchors(s = nil, set = [], tag = :box) ⇒ `Integer`

#genConstruction(model = nil, specs = {}) ⇒ `OpenStudio::Model::Construction`^?

#genExtendedVertices(s = nil, set = [], tag = :vtx) ⇒ `OpenStudio::Point3dVector`

#genInserts(s = nil, set = []) ⇒ `OpenStudio::Point3dVector`

#genMass(sps = OpenStudio::Model::SpaceVector.new, ratio = 2.0) ⇒ `Bool`, `false`

#genShade(subs = OpenStudio::Model::SubSurfaceVector.new) ⇒ `Bool`, `false`

#genSlab(pltz = [], z = 0) ⇒ `OpenStudio::Point3dVector`

#getCollinears(pts = nil, n = 0) ⇒ `OpenStudio::Point3dVector`

#getHorizontalRidges(roofs = []) ⇒ `Array`

#getLineIntersection(s1 = [], s2 = []) ⇒ `OpenStudio::Point3d`^?

#getNonCollinears(pts = nil, n = 0) ⇒ `OpenStudio::Point3dVector`

#getRealignedFace(pts = nil, force = false) ⇒ `Hash`

#getRoofs(spaces = []) ⇒ `Array<OpenStudio::Model::Surface>`

#getSegments(pts = nil) ⇒ `OpenStudio::Point3dVectorVector`

#getTriads(pts = nil, co = false) ⇒ `OpenStudio::Point3dVectorVector`

#getUniques(pts = nil, n = 0) ⇒ `OpenStudio::Point3dVector`

#glazingAirFilmRSi(usi = 5.85) ⇒ `Float`, `0.1216`

#grossRoofArea(spaces = []) ⇒ `Object`

#heatingTemperatureSetpoints?(model = nil) ⇒ `Bool`, `false`

#height(pts = nil) ⇒ `Float`, `0.0`

#holds?(pts = nil, p1 = nil) ⇒ `Bool`, `false`

#holdsConstruction?(set = nil, bse = nil, gr = false, ex = false, tp = "") ⇒ `Bool`, `false`

#insulatingLayer(lc = nil) ⇒ `Hash`

#lineIntersects?(l = [], s = []) ⇒ `Bool`, `false`

#maxHeatScheduledSetpoint(zone = nil) ⇒ `Hash`

#medialBox(pts = nil) ⇒ `OpenStudio::Point3dVector`

#midpoint(p1 = nil, p2 = nil) ⇒ `OpenStudio::Point3d`^?

#minCoolScheduledSetpoint(zone = nil) ⇒ `Hash`

#nearest(pts = nil, p01 = nil) ⇒ `Integer`^?

#nextUp(pts = nil, pt = nil) ⇒ `OpenStudio::Point3d`^?

#offset(p1 = nil, w = 0, v = 0) ⇒ `OpenStudio::Point3dVector`

#outline(a = [], bfr = 0, flat = true) ⇒ `OpenStudio::Point3dVector`

#overlap(p1 = nil, p2 = nil, flat = false) ⇒ `OpenStudio::Point3dVector`

#overlaps?(p1 = nil, p2 = nil, flat = false) ⇒ `Bool`, `false`

#parallel?(p1 = nil, p2 = nil) ⇒ `Bool`, `false`

#plenum?(space = nil) ⇒ `Bool`, `false`

#pointAlongSegment?(p0 = nil, sg = []) ⇒ `Bool`, `false`

#pointAlongSegments?(p0 = nil, sgs = []) ⇒ `Bool`, `false`

#pointWithinPolygon?(p0 = nil, s = [], entirely = false) ⇒ `Bool`, `false`

#poly(pts = nil, vx = false, uq = false, co = false, tt = false, sq = :no) ⇒ `OpenStudio::Point3dVector`

#rectangular?(pts = nil) ⇒ `Bool`, `false`

#refrigerated?(space = nil) ⇒ `Bool`, `false`

#roof?(pts = nil) ⇒ `Bool`, `false`

#rsi(lc = nil, film = 0.0, t = 0.0) ⇒ `Float`, `0.0`

#same?(s1 = nil, s2 = nil, indexed = true) ⇒ `Bool`, `false`

#scalar(v = OpenStudio::Vector3d.new, m = 0) ⇒ `OpenStudio::Vector3d`

#scheduleCompactMinMax(sched = nil) ⇒ `Hash`

#scheduleConstantMinMax(sched = nil) ⇒ `Hash`

#scheduleIntervalMinMax(sched = nil) ⇒ `Hash`

#scheduleRulesetMinMax(sched = nil) ⇒ `Hash`

#segment?(pts = nil) ⇒ `Bool`, `false`

#semiheated?(space = nil) ⇒ `Bool`, `false`

#setpoints(space = nil) ⇒ `Hash`

#sloped?(pts = nil) ⇒ `Bool`, `false`

#spandrel?(s = nil) ⇒ `Bool`, `false`

#square?(pts = nil) ⇒ `Bool`, `false`

#standardOpaqueLayers?(lc = nil) ⇒ `Bool`, `false`

#thickness(lc = nil) ⇒ `Float`, `0.0`

#to_p3Dv(pts = nil) ⇒ `OpenStudio::Point3dVector`