Module: OSut

Extended by:
OSlg
Defined in:
lib/osut/version.rb,
lib/osut/utils.rb

Overview

BSD 3-Clause License

Copyright © 2022-2024, Denis Bourgeois All rights reserved.

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

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. 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.

  3. 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
INF =

see github.com/rd2/oslg

OSlg::INFO
WRN =

see github.com/rd2/oslg

OSlg::WARN
ERR =

see github.com/rd2/oslg

OSlg::ERROR
FTL =

see github.com/rd2/oslg

OSlg::FATAL
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 floros
    :top, # e.g. roof/ceiling
  :north, # NORTH
   :east, # EAST
  :south, # SOUTH
   :west  # WEST
].freeze
VERSION =

OSut version

"0.5.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

Instance Method Summary collapse

Class Method Details

.extended(base) ⇒ Object

Callback when other modules extend OSlg

Parameters:

  • base (Object)

    instance or class object



7319
7320
7321
# File 'lib/osut/utils.rb', line 7319

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-to-roof (SRR%) options (max 10%). If the user selects 0% (0.0) as the :srr while keeping :clear as true, the method simply purges all pre-existing roof subsurfaces (whether glazed or not) of selected spaces, and exits while returning 0 (without logging an error or warning). Pre-toplit spaces are otherwise ignored. Boolean options :attic, :plenum, :sloped and :sidelit, further restrict candidate roof surfaces. If applicable, options :attic and :plenum add skylight wells. Option :patterns restricts preset skylight allocation strategies 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.2m x 1.2m)

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):

  • :srr (#to_f)

    skylight-to-roof ratio (0.00, 0.10]

  • :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

  • :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 0 m2)



5920
5921
5922
5923
5924
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935
5936
5937
5938
5939
5940
5941
5942
5943
5944
5945
5946
5947
5948
5949
5950
5951
5952
5953
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
6119
6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218
6219
6220
6221
6222
6223
6224
6225
6226
6227
6228
6229
6230
6231
6232
6233
6234
6235
6236
6237
6238
6239
6240
6241
6242
6243
6244
6245
6246
6247
6248
6249
6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
6261
6262
6263
6264
6265
6266
6267
6268
6269
6270
6271
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
6291
6292
6293
6294
6295
6296
6297
6298
6299
6300
6301
6302
6303
6304
6305
6306
6307
6308
6309
6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
6357
6358
6359
6360
6361
6362
6363
6364
6365
6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
6429
6430
6431
6432
6433
6434
6435
6436
6437
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
6535
6536
6537
6538
6539
6540
6541
6542
6543
6544
6545
6546
6547
6548
6549
6550
6551
6552
6553
6554
6555
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
7001
7002
7003
7004
7005
7006
7007
7008
7009
7010
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021
7022
7023
7024
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
7035
7036
7037
7038
7039
7040
7041
7042
7043
7044
7045
7046
7047
7048
7049
7050
7051
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
7063
7064
7065
7066
7067
7068
7069
7070
7071
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
7083
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
7098
7099
7100
7101
7102
7103
7104
7105
7106
7107
7108
7109
7110
7111
7112
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124
7125
7126
7127
7128
7129
7130
7131
7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162
7163
7164
7165
7166
7167
7168
7169
7170
7171
7172
7173
7174
7175
7176
7177
7178
7179
7180
7181
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
7197
7198
7199
7200
7201
7202
7203
7204
7205
7206
7207
7208
7209
7210
7211
7212
7213
7214
7215
7216
7217
7218
7219
7220
7221
7222
7223
7224
7225
7226
7227
7228
7229
7230
7231
7232
7233
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243
7244
7245
7246
7247
7248
7249
7250
7251
7252
7253
7254
7255
7256
7257
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287
7288
7289
7290
7291
7292
7293
7294
7295
7296
7297
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
# File 'lib/osut/utils.rb', line 5920

def addSkyLights(spaces = [], opts = {})
  mth   = "OSut::#{__callee__}"
  clear = true
  srr   = 0.0
  frame = nil   # FrameAndDivider object
  f     = 0.0   # FrameAndDivider frame width
  gap   = 0.1   # min 2" around well (2x), 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 ontoothers, 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 argument classes/keys.
  return mismatch("opts", opts, Hash, mth, DBG, 0) unless opts.is_a?(Hash)
  return  hashkey( "srr", opts, :srr, mth, ERR, 0) unless opts.key?(:srr)

  # Validate requested skylight-to-roof ratio.
  if opts[:srr].respond_to?(:to_f)
    srr = opts[:srr].to_f
    log(WRN, "Resetting srr to 0% (#{mth})")  if srr < 0
    log(WRN, "Resetting srr to 10% (#{mth})") if srr > 0.10
    srr = srr.clamp(0.00, 0.10)
  else
    return mismatch("srr", opts[:srr], Numeric, mth, DBG, 0)
  end

  # 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 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

  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 srr < TOL

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # 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/right + top/bottom (as illustrated below), once a roof
  # (or cast 3D overlap) is 'aligned' in 2D (possibly also 'realigned').
  #
  # 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 desired %SRR. If :patterns are left unaltered, the method will
  # select patterns that maximize the likelihood of attaining the requested
  # %SRR, to the detriment of spatial distribution of daylighting.
  #
  # The default skylight module size is 1.2m x 1.2m (4' x 4'), which be
  # overridden by the user, e.g. 2.4m x 2.4m (8' x 8').
  #
  # Preset skylight allocation patterns (in order of precedence):
  #    1. "array"
  #   _____________________
  #  |   _      _      _   |  - ?x columns ("cols") >= ?x rows (min 2x2)
  #  |  |_|    |_|    |_|  |  - SRR ~5% (1.2m x 1.2m), as illustrated
  #  |                     |  - SRR ~19% (2.4m x 2.4m)
  #  |   _      _      _   |  - +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.2m x ?1.2m), as illustrated
  #  |  | |    | |    | |  |  - SRR ~19% (2.4m x ?1.2m)
  #  |  |_|    |_|    |_|  |  - ~roof monitor layout
  #  |_____________________|  - fewer wells
  #
  #    3. "strip"
  #    ____________________
  #   |                    |  - 1x column, 1x row (min 1x)
  #   |   ______________   |  - SRR ~11% (1.2m x ?1.2m)
  #   |  | ............ |  |  - SRR ~22% (2.4m x ?1.2m), as illustrated
  #   |  |______________|  |  - +suitable for elongated bounded boxes
  #   |                    |  - 1x well
  #   |____________________|
  #
  #   TO-DO: 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)
  #   - not under plenums, nor attics (avoids wells)
  #
  # This ideal (albeit stringent) set of conditions is "combo a".
  #
  # If required %SRR has not yet been achieved, 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. Priority is always given to larger roof areas. If
  # unsuccessful in meeting the required %SRR target, a single criterion is
  # then dropped (e.g. b, then c, etc.), and the allocation process is
  # relaunched. An error message is logged if the %SRR isn't ultimately met.
  #
  # Through filters, users may 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 reduced (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)

  # Select candidate 'rooms' to toplit - excludes plenums/attics.
  spaces.each do |space|
    next if unconditioned?(space)          # e.g. attic
    next unless space.partofTotalFloorArea # occupied (not plenum)

    # Already toplit?
    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 local transformation.
    h  = 0
    t0 = transforms(space)
    next unless t0[:t]

    toitures = facets(space, "Outdoors", "RoofCeiling")
    plafonds = facets(space, "Surface", "RoofCeiling")

    toitures.each { |surf| h = [h, surf.vertices.max_by(&:z).z].max }
    plafonds.each { |surf| h = [h, surf.vertices.max_by(&:z).z].max }

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

    # Fetch and process room-specific outdoor-facing roof surfaces, the most
    # basic 'set' to track:
    #   - no skylight wells
    #   - 1x skylight array per roof surface
    #   - no need to preprocess space transformation
    rooms[space][:roofs].each do |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)

      # Track if bounded box is significantly smaller than roof.
      tight = bm2 < roof.grossArea / 2 ? true : false

      set           = {}
      set[:box    ] = box
      set[:bm2    ] = bm2
      set[:tight  ] = tight
      set[:roof   ] = roof
      set[:space  ] = space
      set[:sidelit] = rooms[space][:sidelit]
      set[:t      ] = rooms[space][:t      ]
      set[:sloped ] = slopedRoof?(roof)
      sets << set
    end
  end

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

    # Process room ceilings, as 1x or more are overlapping roofs above. Fetch
    # vertically-cast overlaps.
    rufs.each do |ruf|
      espace = ruf.space
      next if espace.empty?

      espace = espace.get
      next if espace.partofTotalFloorArea

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

      ti  = ti[:t]
      vtx = ruf.vertices

      # Ensure BLC vertex sequence.
      if facingUp?(vtx)
        vtx = ti * vtx

        if xyz?(vtx, :z)
          vtx = blc(vtx)
        else
          dZ  = vtx.first.z
          vtz = blc(flatten(vtx)).to_a
          vtx = []

          vtz.each { |v| vtx << OpenStudio::Point3d.new(v.x, v.y, v.z + dZ) }
        end

        ruf.setVertices(ti.inverse * vtx)
      else
        tr  = OpenStudio::Transformation.alignFace(vtx)
        vtx = blc(tr.inverse * vtx)
        ruf.setVertices(tr * vtx)
      end

      ri = ti * ruf.vertices

      facets(space, "Surface", "RoofCeiling").each do |tile|
        vtx = tile.vertices

        # Ensure BLC vertex sequence.
        if facingUp?(vtx)
          vtx = t0 * vtx

          if xyz?(vtx, :z)
            vtx = blc(vtx)
          else
            dZ  = vtx.first.z
            vtz = blc(flatten(vtx)).to_a
            vtx = []

            vtz.each { |v| vtx << OpenStudio::Point3d.new(v.x, v.y, v.z + dZ) }
          end

          vtx = t0.inverse * vtx
        else
          tr  = OpenStudio::Transformation.alignFace(vtx)
          vtx = blc(tr.inverse * vtx)
          vtx = tr * vtx
        end

        tile.setVertices(vtx)

        ci0 = cast(t0 * tile.vertices, ri, ray)
        next if ci0.empty?

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

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

        # Adding skylight wells (plenums/attics) is contingent to safely
        # linking new base roof 'inserts' through leader lines. Currently,
        # this requires an offset from main roof surface edges.
        #
        # TO DO: 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)
        box = poly(box, false, false, false, false, :blc)
        next if box.empty?

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

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

        # Vertically-cast box onto ceiling below.
        cbox = cast(box, t0 * tile.vertices, ray)
        next if cbox.empty?

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

        cm2 = cm2.get

        # Track if bounded boxes are significantly smaller than either roof
        # or ceiling.
        tight = bm2 < ruf.grossArea  / 2 ? true : false
        tight = cm2 < tile.grossArea / 2 ? true : tight

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

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

          floor = floor.get

          # Ensure BLC vertex sequence.
          vtx = t0 * vtx
          floor.setVertices(ti.inverse * vtx.reverse)

          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

        # More detailed skylight set entries with suspended ceilings.
        set           = {}
        set[:olap   ] = olap
        set[:box    ] = box
        set[:cbox   ] = cbox
        set[:bm2    ] = bm2
        set[:cm2    ] = cm2
        set[:tight  ] = tight
        set[:roof   ] = ruf
        set[:space  ] = space
        set[:clng   ] = tile
        set[:t      ] = t0
        set[:sidelit] = room[:sidelit]
        set[:sloped ] = slopedRoof?(ruf)

        if unconditioned?(espace) # e.g. attic
          unless attics.key?(espace)
            attics[espace] = {t: 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] = {t: 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, and set GROSS ROOF AREA.
  attics.values.each do |attic|
    attic[:roofs ].uniq!
    attic[:ridges] = getHorizontalRidges(attic[:roofs]) # TO-DO
  end

  plenums.values.each do |plenum|
    plenum[:roofs ].uniq!
    # plenum[:m2    ] = plenum[:roofs].sum(&:grossArea)
    plenum[:ridges] = getHorizontalRidges(plenum[:roofs]) # TO-DO
  end

  # Regardless of the selected skylight arrangement pattern, the current
  # solution may only consider attic/plenum sets that can be successfully
  # linked to leader line anchors, for both roof and ceiling surfaces.
  [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] }
        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?

    genAnchors(tile, stz, :cbox)
  end

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

  m2  = 0 # existing skylight rough opening area
  rm2 = grossRoofArea(spaces)

  # Tally existing skylight rough opening areas (%SRR calculations).
  rooms.values.each do |room|
    m = room[:m]

    room[:roofs].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 = rm2 * srr - m2

  # Skip if existing skylights exceed or ~roughly match requested %SRR.
  if sm2.round(2) < w02.round(2)
    log(INF, "Skipping: existing srr > requested srr (#{mth})")
    return 0
  end

  # Any sidelit/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 ] }

  # 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
  #
  # ... yet skylight areas are subsequently contracted to strictly meet SRR%.
  sets.each_with_index do |set, i|
    id     = "set #{i+1}"
    well   = set.key?(:clng)
    space  = set[:space]
    tight  = set[:tight]
    factor = tight ? 1.75 : 1.25
    room   = rooms[space]
    h      = room[:h]
    t      = OpenStudio::Transformation.alignFace(set[:box])
    abox   = poly(set[:box], false, false, false, t, :ulc)
    obox   = getRealignedFace(abox)
    next unless obox[:set]

    width = width(obox[:set])
    depth = height(obox[:set])
    area  = width * depth
    skym2 = srr * area

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

      if depth.round(2) < wl.round(2)
        log(ERR, "#{id}: Too shallow")
        set[:void] = true
        next
      end
    else
      if width.round(2) < w0.round(2)
        log(ERR, "#{id}: Too narrow")
        set[:void] = true
        next
      end

      if depth.round(2) < w0.round(2)
        log(ERR, "#{id}: Too shallow")
        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  = wl
      wyl  = wl
      dX   = nil
      dY   = nil

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

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

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

          next if cols < 2
          next if rows < 2

          dX = well ? 0.0 : bfr + f
          dY = well ? 0.0 : 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) / cols
          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) / cols
          dY = ly / 2
        end

        # Current skylight area. If undershooting, adjust skylight width/depth
        # as well as reduce spacing. For geometrical constrained cases,
        # undershooting means not reaching 1.75x the required SRR%. Otherwise,
        # undershooting means not reaching 1.25x the required SRR%. Any
        # consequent overshooting is later corrected.
        tm2       = wx * cols * wy * rows
        undershot = tm2.round(2) < factor * skym2.round(2) ? true : false

        # Inflate skylight width/depth (and reduce spacing) to reach SRR%.
        if undershot
          ratio2 = 1 + (factor * skym2 - tm2) / tm2
          ratio  = Math.sqrt(ratio2)

          sp  = w
          wx *= ratio
          wy *= ratio
          wxl = wx + gap
          wyl = wy + gap

          if tight
            if well
              lx = (width - cols * wxl) / (cols - 1)
              ly = (depth - rows * wyl) / (rows - 1)
            else
              lx = (width - cols * wx) / (cols - 1)
              ly = (depth - rows * wy) / (rows - 1)
            end

            lx = lx.round(2) < sp.round(2) ? sp : lx
            ly = ly.round(2) < sp.round(2) ? sp : ly

            if well
              wxl = (width - (cols - 1) * lx) / cols
              wyl = (depth - (rows - 1) * ly) / rows
              wx  = wxl - gap
              wy  = wyl - gap
            else
              wx  = (width - (cols - 1) * lx) / cols
              wy  = (depth - (rows - 1) * ly) / rows
              wxl = wx + gap
              wyl = wy + gap
            end
          else
            if well
              lx = (width - cols * wxl) / cols
              ly = (depth - rows * wyl) / rows
            else
              lx = (width - cols * wx) / cols
              ly = (depth - rows * wy) / rows
            end

            lx = lx.round(2) < sp.round(2) ? sp : lx
            ly = ly.round(2) < sp.round(2) ? sp : ly

            if well
              wxl = (width - cols * lx) / cols
              wyl = (depth - rows * ly) / rows
              wx  = wxl - gap
              wy  = wyl - gap
              lx  = (width - cols * wxl) / cols
              ly  = (depth - rows * wyl) / rows
            else
              wx  = (width - cols * lx) / cols
              wy  = (depth - rows * ly) / rows
              wxl = wx + gap
              wyl = wy + gap
              lx  = (width - cols * wx) / cols
              ly  = (depth - rows * wy) / rows
            end
          end

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

        if tight
          sp = h / 2
          lx = well ? width - cols * wxl : width - cols * wx
          ly = well ? depth - wyl : depth - wy
          next if lx.round(2) < sp.round(2)
          next if ly.round(2) < sp.round(2)

          if well
            cols = ((width - wxl) / (wxl + sp)).round(2).to_i + 1
          else
            cols = ((width - wx) / (wx + sp)).round(2).to_i + 1
          end

          next if cols < 2

          if well
            wyl = depth - ly
            wy  = wyl - gap
          else
            wy  = depth - ly
            wyl = wy + gap
          end

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

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

          next if cols < 2

          if well
            wyl = depth - ly
            wy  = wyl - gap
          else
            wy  = depth - ly
            wyl = wy + gap
          end

          dY = ly / 2
        end

        tm2       = wx * cols * wy
        undershot = tm2.round(2) < factor * skym2.round(2) ? true : false

        # Inflate skylight width (and reduce spacing) to reach SRR%.
        if undershot
          ratio2 = 1 + (factor * skym2 - tm2) / tm2

          sp  = w
          wx *= ratio2
          wxl = wx + gap

          if tight
            if well
              lx = (width - cols * wxl) / (cols - 1)
            else
              lx = (width - cols * wx) / (cols - 1)
            end

            lx = lx.round(2) < sp.round(2) ? sp : lx

            if well
              wxl = (width - (cols - 1) * lx) / cols
              wx  = wxl - gap
            else
              wx  = (width - (cols - 1) * lx) / cols
              wxl = wx + gap
            end
          else
            if well
              lx = (width - cols * wxl) / cols
            else
              lx = (width - cols * wx) / cols
            end

            lx  = lx.round(2) < sp.round(2) ? sp : lx

            if well
              wxl = (width - cols * lx) / cols
              wx  = wxl - gap
              lx  = (width - cols * wxl) / cols
            else
              wx  = (width - cols * lx) / cols
              wxl = wx + gap
              lx  = (width - cols * wx) / cols
            end
          end
        end
      else # "strip" 1 (long?) row x 1 column
        sp = w
        lx = well ? width - wxl : width - wx
        ly = well ? depth - wyl : depth - wy

        if tight
          next if lx.round(2) < sp.round(2)
          next if ly.round(2) < sp.round(2)

          if well
            wxl = width - lx
            wyl = depth - ly
            wx  = wxl - gap
            wy  = wyl - gap
          else
            wx  = width - lx
            wy  = depth - ly
            wxl = wx + gap
            wyl = wy + gap
          end

          dX = well ? 0.0 : bfr + f
          dY = ly / 2
        else
          next if lx.round(2) < sp.round(2)
          next if ly.round(2) < sp.round(2)

          if well
            wxl = width - lx
            wyl = depth - ly
            wx  = wxl - gap
            wy  = wyl - gap
          else
            wx  = width - lx
            wy  = depth - ly
            wxl = wx + gap
            wyl = wy + gap
          end

          dY = ly / 2
        end

        tm2       = wx * wy
        undershot = tm2.round(2) < factor * skym2.round(2) ? true : false

        # Inflate skylight depth to reach SRR%.
        if undershot
          ratio2 = 1 + (factor * skym2 - tm2) / tm2

          sp  = w
          wy *= ratio2
          wyl = wy + gap

          ly  = well ? depth - wy : depth - wyl
          ly  = ly.round(2) < sp.round(2) ? sp : lx

          if well
            wyl = depth - ly
            wy  = wyl - gap
          else
            wy  = depth - ly
            wyl = wy + gap
          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
  end

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

  # 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.
  skm2 = 0

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

    sts = sets
    sts = sts.sort_by { |st| st[:bm2] }.reverse!
    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   ] += wx * wy * cols * rows
        fpm2[pattern][:tight] = st[:tight] ? true : false
      end
    end

    pattern = nil
    next if fpm2.empty?

    fpm2 = fpm2.sort_by { |_, fm2| fm2[:m2] }.to_h

    # Select suitable pattern, often overshooting. Favour array unless
    # geometrically constrainted.
    if fpm2.keys.include?("array")
      if (fpm2["array"][:m2]).round(2) >= sm2.round(2)
        pattern = "array" unless fpm2[:tight]
      end
    end

    unless pattern
      if fpm2.values.first[:m2].round(2) >= sm2.round(2)
        pattern = fpm2.keys.first
      elsif fpm2.values.last[:m2].round(2) <= sm2.round(2)
        pattern = fpm2.keys.last
      else
        fpm2.keep_if { |_, fm2| fm2[:m2].round(2) >= sm2.round(2) }

        pattern = fpm2.keys.first
      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

  # Skylight size contraction if overshot (e.g. -13.2% if overshot by +13.2%).
  # This is applied on a surface/pattern basis; individual skylight sizes may
  # vary from one surface to the next, depending on respective patterns.
  if skm2.round(2) > sm2.round(2)
    ratio2 = 1 - (skm2 - sm2) / skm2
    ratio  = Math.sqrt(ratio2)
    skm2  *= ratio2

    sets.each do |set|
      next if set.key?(:void)
      next unless set.key?(:pattern)

      pattern = set[:pattern]
      next unless set.key?(pattern)

      case pattern
      when "array" # equally adjust both width and depth
        xr  = set[:w] * ratio
        yr  = set[:d] * ratio
        dyr = set[:d] - yr

        set[:w ]  = xr
        set[:d ]  = yr
        set[:w0]  = set[:w] + gap
        set[:d0]  = set[:d] + gap
        set[:dY] += dyr / 2
      when "strips" # adjust depth
        xr2 = set[:w] * ratio2

        set[:w ]  = xr2
        set[:w0]  = set[:w] + gap
      else # "strip", adjust width
        yr2 = set[:d] * ratio2
        dyr = set[:d] - yr2

        set[:d ]  = yr2
        set[:d0]  = set[:w] + gap
        set[:dY] += dyr / 2
      end
    end
  end

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

    greniers.each do |spce, grenier|
      ti = grenier[:t]

      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 final selection is
        # contingent to successfully inserting corresponding room ceiling
        # inserts (vis-à-vis attic/plenum floor below). The method also
        # generates new roof inserts. See key:value pair :vts.
        vz = genInserts(roof, sts)
        next if vz.empty? # TODO log error if empty

        roof.setVertices(ti.inverse * 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[:t]
    t0      = room[:t]
    stz     = []

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

      sts = sts.select { |st| st.key?(k) }
      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?

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

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

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

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

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

        # Generate well walls.
        v0 = roof.vertices
        vX = cast(roof, tile, ray)
        s0 = getSegments(v0)
        sX = getSegments(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

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

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

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

        # Add individual skylights.
        addSubs(roof, [sub])
      end
    end
  end

  # New direct roof loop. No overlaps, so no need for relative space
  # coordinate adjustments.
  rooms.each do |space, room|
    room[:roofs].each do |roof|
      sets.each_with_index do |set, i|
        next     if set.key?(:clng)
        next unless set.key?(:box)
        next unless set.key?(:roof)
        next unless set.key?(:cols)
        next unless set.key?(:rows)
        next unless set.key?(:d)
        next unless set.key?(:w)
        next unless set.key?(:tight)
        next unless set[:roof] == roof

        tight = set[:tight]

        d1 = set[:d] - f2
        w1 = set[:w] - f2

        # Y-axis 'height' of the roof, once re/aligned.
        # TODO: retrieve st[:out], +efficient
        y  = alignedHeight(set[:box])
        dY = set[:dY] if set[:dY]

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

  rm2
end

#addSubs(s = nil, subs = [], clear = 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

  • 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)



5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
5624
5625
5626
5627
5628
5629
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
5661
5662
5663
5664
5665
5666
5667
5668
5669
5670
5671
5672
5673
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
# File 'lib/osut/utils.rb', line 5135

def addSubs(s = nil, subs = [], clear = 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.
  return mismatch("surface",  s, cl2, mth, DBG, no) unless s.is_a?(cl1)
  return mismatch("subs",  subs, cl3, mth, DBG, no) unless subs.is_a?(cl2)
  return empty("surface points",      mth, DBG, no)     if poly(s).empty?

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # Clear existing sub surfaces if requested.
  nom = s.nameString
  mdl = s.model

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

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

  # --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- --- #
  # 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

  if facingUp?(s) || facingDown?(s) # TODO: redundant check?
    s00 = getRealignedFace(s0)
    return false unless s00[:set]

    s0 = s00[:set]
  end

  max_x = width(s0)
  max_y = 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

      ok = value.respond_to?(:to_f)
      return mismatch(key, value, Float, mth, DBG, no) unless ok
      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)
        sub[:height] = glass      if sub[:height] < glass
        sub[:height] = max_height if sub[:height] > max_height
        log(WRN, "Reset '#{id}' height to #{sub[:height]} 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)
        sub[:head] = max_head if sub[:head] > max_head
        sub[:head] = min_head if sub[:head] < min_head
        log(WRN, "Reset '#{id}' head height to #{sub[:head]} 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)
        sub[:sill] = max_sill if sub[:sill] > max_sill
        sub[:sill] = min_sill if sub[:sill] < min_sill
        log(WRN, "Reset '#{id}' sill height to #{sub[:sill]} 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
        sub[:sill] = sill
        log(WRN, "(Re)set '#{id}' sill height to #{sub[:sill]} 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 to #{height} 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
            sub[:sill  ] = sill
            sub[:height] = height
            log(WRN, "(Re)set '#{id}' height to #{sub[:height]} 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
            sub[:head  ] = head
            sub[:height] = height
            log(WRN, "(Re)set '#{id}' height to #{sub[:height]} 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)
        sub[:width] = glass     if sub[:width] < glass
        sub[:width] = max_width if sub[:width] > max_width
        log(WRN, "Reset '#{id}' width to #{sub[:width]} 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 #{sub[:count]} (#{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
        sub[:l_buffer] = min_ljamb
        log(WRN, "Reset '#{id}' left buffer to #{sub[:l_buffer]} 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
        sub[:r_buffer] = min_rjamb
        log(WRN, "Reset '#{id}' right buffer to #{sub[:r_buffer]} 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: '#{id}' ratio ~0 (#{mth})")
        next
      end

      # Log/reset if "ratio" beyond min/max?
      unless sub[:ratio].between?(min, max)
        sub[:ratio] = min if sub[:ratio] < min
        sub[:ratio] = max if sub[:ratio] > max
        log(WRN, "Reset ratio (min/max) to #{sub[:ratio]} (#{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: invalid (ratio) width/centreline (#{mth})")
        next
      end

      if sub.key?(:width) && (sub[:width] - width).abs > TOL
        sub[:width] = width
        log(WRN, "Reset width (ratio) to #{sub[:width]} (#{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 < bfr
      offset = gap + width

      if sub.key?(:offset) && (offset - sub[:offset]).abs > TOL
        sub[:offset] = offset
        log(WRN, "Reset sub offset to #{sub[:offset]} 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 < bfr - TOL2 || xf > max_x - bfr - 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
      ok = fits?(vc, s)

      log(ERR, "Skip '#{name}': won't fit in '#{nom}' (#{mth})") unless ok
      break                                                      unless ok

      # Log/skip if conflicts with existing subs (even if same array).
      s.subSurfaces.each do |sb|
        nome = sb.nameString
        fd   = sb.windowPropertyFrameAndDivider
        fr   = 0                     if fd.empty?
        fr   = fd.get.frameWidth unless fd.empty?
        vk   = sb.vertices
        vk   = offset(vk, fr, 300) if fr > 0
        oops = overlaps?(vc, vk)
        log(ERR, "Skip '#{name}': overlaps '#{nome}' (#{mth})") if oops
        ok = false                                              if oops
        break                                                   if oops
      end

      break unless ok

      sb = OpenStudio::Model::SubSurface.new(vec, mdl)
      sb.setName(name)
      sb.setSubSurfaceType(sub[:type])
      sb.setConstruction(sub[:assembly])               if sub[:assembly]
      ok = sb.allowWindowPropertyFrameAndDivider
      sb.setWindowPropertyFrameAndDivider(sub[:frame]) if sub[:frame] && ok
      sb.setMultiplier(sub[:multiplier])               if sub[:multiplier] > 1
      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)



1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
# 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) ⇒ 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

Returns:

  • (Float)

    height along Y-axis, once re/aligned

  • (0.0)

    if invalid inputs



4332
4333
4334
4335
4336
4337
4338
4339
4340
# File 'lib/osut/utils.rb', line 4332

def alignedHeight(pts = nil)
  pts   = pts = poly(pts, false, true, true, true)
  return 0 if pts.size < 2

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

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

#alignedWidth(pts = nil) ⇒ 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

Returns:

  • (Float)

    width along X-axis, once re/aligned

  • (0.0)

    if invalid inputs



4315
4316
4317
4318
4319
4320
4321
4322
4323
# File 'lib/osut/utils.rb', line 4315

def alignedWidth(pts = nil)
  pts = poly(pts, false, true, true, true)
  return 0 if pts.size < 2

  pts = getRealignedFace(pts)[: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)



2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
# File 'lib/osut/utils.rb', line 2101

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)



3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
# File 'lib/osut/utils.rb', line 3057

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)



4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
# File 'lib/osut/utils.rb', line 4025

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)

      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)

      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)

      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)

    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)

        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)



3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
# File 'lib/osut/utils.rb', line 3582

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(getNonCollinears(p2, 3))
  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

Determines if pre-‘aligned’ OpenStudio 3D points are listed clockwise.

Parameters:

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

    3D points

Returns:

  • (Bool)

    whether sequence is clockwise

  • (false)

    if invalid input (see logs)



3010
3011
3012
3013
3014
3015
3016
3017
3018
# File 'lib/osut/utils.rb', line 3010

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

  OpenStudio.pointInPolygon(pts.first, pts, TOL)
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)



1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
# 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)



5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
5102
5103
5104
5105
5106
5107
5108
# File 'lib/osut/utils.rb', line 5083

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)



828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
# 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

#facets(spaces = [], boundary = "Outdoors", type = "Wall", sides = []) ⇒ Array<OpenStudio::Model::Surface>

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 absolute model 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].

Parameters:

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

    target spaces

  • boundary (#to_s) (defaults to: "Outdoors")

    OpenStudio outside boundary condition

  • type (#to_s) (defaults to: "Wall")

    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)



4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
# File 'lib/osut/utils.rb', line 4848

def facets(spaces = [], boundary = "Outdoors", type = "Wall", 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|
      next unless s.outsideBoundaryCondition.downcase == boundary
      next unless s.surfaceType.downcase == type

      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|
    break unless faces.empty?

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

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

        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.

Parameters:

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

    OpenStudio 3D points

Returns:

  • (Bool)

    if facing downwards

  • (false)

    if invalid input (see logs)



3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
# File 'lib/osut/utils.rb', line 3378

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

  pts = getNonCollinears(pts, 3)
  return false if pts.empty?

  OpenStudio::Plane.new(pts).outwardNormal.dot(lo) > 0.99
end

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

Validates whether a polygon faces upwards.

Parameters:

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

    OpenStudio 3D points

Returns:

  • (Bool)

    if facing upwards

  • (false)

    if invalid input (see logs)



3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
# File 'lib/osut/utils.rb', line 3360

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

  pts = getNonCollinears(pts, 3)
  return false if pts.empty?

  OpenStudio::Plane.new(pts).outwardNormal.dot(up) > 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)



2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
# File 'lib/osut/utils.rb', line 2509

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)



1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
# 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)



3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
# File 'lib/osut/utils.rb', line 3448

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) }

  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)



2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
# File 'lib/osut/utils.rb', line 2561

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 = :vtx) ⇒ Integer

Generates leader line anchors, linking polygon vertices to one or more sets (Hashes) of sequenced vertices. By default, the method seeks to link set :vtx (key) vertices (users can select another collection of vertices, e.g. tag == :box). The method minimally validates individual sets of vertices (e.g. coplanarity, non-self-intersecting, no inter-set conflicts). Potential leader lines cannot intersect each other, other ‘tagged’ set vertices or original polygon edges. For highly-articulated cases (e.g. a narrow polygon with multiple concavities, holding multiple sets), such leader line conflicts will surely occur. The method relies on a ‘first-come-first-served’ approach: sets without leader lines are ignored (check for set :void keys, see error logs). It is recommended to sort sets prior to calling the method.

Parameters:

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

    a larger (parent) set of points

  • set (Array<Hash>) (defaults to: [])

    a collection of sequenced vertices

  • [Symbol] (Hash)

    a customizable set of options

Returns:

  • (Integer)

    number of successfully-generated anchors (check logs)



4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
# File 'lib/osut/utils.rb', line 4360

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

  set = set.to_a

  # Validate individual sets. Purge surface-specific leader line anchors.
  set.each_with_index do |st, i|
    str1 = id + "set ##{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?

    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

  if facingUp?(pts)
    if xyz?(pts, :z)
      dZ = 0
    else
      dZ = pts.first.z
      pts = flatten(pts).to_a
    end
  else
    t  = OpenStudio::Transformation.alignFace(pts)
    pts = t.inverse * pts
  end

  # Set leader lines anchors. Gather candidate leader line anchors; select
  # anchor with shortest distance to first vertex of 'tagged' set.
  set.each_with_index do |st, i|
    candidates = []
    break if st[:ld].key?(s)

    stt = dZ ? flatten(st[tag]).to_a : t.inverse * st[tag]
    p1  = stt.first

    pts.each_with_index do |pt, k|
      ld  = [pt, p1]
      nb  = 0

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

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

      next unless nb.zero?

      # Check for intersections between candidate leader line and other sets.
      set.each_with_index do |other, j|
        break unless nb.zero?
        next if i == j

        ost = dZ ? flatten(other[tag]).to_a : t.inverse * other[tag]
        sgj = getSegments(ost)

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

      next unless nb.zero?

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

        ost = other[tag]
        pj  = ost.first
        old = other[:ld][s]
        ldj = dZ ? flatten([ old, pj ]) : t.inverse * [ old, pj ]

        unless same?(old, pt)
          nb += 1 if lineIntersects?(ld, ldj)
        end
      end

      next unless nb.zero?

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

        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(ERR, "#{str}: unable to anchor #{tag} leader line (#{mth})")
      st[:void] = true
    else
      p0 = candidates.sort_by! { |pt| (pt - p1).length }.first

      if dZ
        st[:ld][s] = OpenStudio::Point3d.new(p0.x, p0.y, p0.z + dZ)
      else
        st[:ld][s] = t * p0
      end

      n += 1
    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)



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
# 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

Generates extended polygon vertices to circumscribe one or more sets (Hashes) of sequenced vertices. The method minimally validates individual sets of vertices (e.g. coplanarity, non-self-intersecting, no inter-set conflicts). Valid leader line anchors (set key :ld) need to be generated prior to calling the method (see genAnchors). By default, the method seeks to link leader line anchors to set :vtx (key) vertices (users can select another collection of vertices, 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 sequenced vertices

  • [Symbol] (Hash)

    a customizable set of options

Options Hash (set):

  • :ld (Hash)

    a collection of polygon-specific leader line anchors

Returns:

  • (OpenStudio::Point3dVector)

    extended vertices (see logs if empty)



4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
# File 'lib/osut/utils.rb', line 4507

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 + "set ##{i+1}"
    str2 = str1 + " #{tag.to_s}"
    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_with_index do |st, i|
      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 arrays of rectangular polygon inserts within a larger polygon. If successful, each set inherits additional key:value pairs: namely :vtx (subset of polygon circumscribing vertices), and :vts (collection of indivudual polygon insert vertices). Valid leader line anchors (set key :ld) need to be generated prior to calling the method (see genAnchors, and genExtendedvertices).

Parameters:

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

    a larger polygon

  • set (Array<Hash>) (defaults to: [])

    a collection of polygon insert instructions

Options Hash (set):

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

    bounding box of each collection

  • :ld (Hash)

    a collection of polygon-specific leader line anchors

  • :rows (Integer) — default: 1

    number of rows of inserts

  • :cols (Integer) — default: 1

    number of columns of inserts

  • :w0 (Numeric) — default: 1.4

    width of individual inserts (wrt cols) min 0.4

  • :d0 (Numeric) — default: 1.4

    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)



4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
4828
4829
4830
4831
4832
4833
# File 'lib/osut/utils.rb', line 4575

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 + "set ##{i+1}"
    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)

    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.
    # TO DO: In line with related addSkylights "TO DO", expand method 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. TO DO: ease up for ridges.
  set.each_with_index do |st, i|
    bx = st[:box]

    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

  # Loop through each 'valid' set (i.e. linking a valid leader line anchor),
  # generate set vertex array based on user-provided specs. Reset BLC vertex
  # coordinates once completed.
  set.each_with_index do |st, i|
    str = id + "set ##{i+1}"
    dZ  = nil
    t   = nil
    bx  = st[:box]

    if facingUp?(bx)
      if xyz?(bx, :z)
        dZ = 0
      else
        dZ = bx.first.z
        bx = flatten(bx).to_a
      end
    else
      t  = OpenStudio::Transformation.alignFace(bx)
      bx = t.inverse * bx
    end

    o = getRealignedFace(bx)
    next unless o[:set]

    st[:out] = o
    st[:bx ] = blc(o[:r] * (o[:t] * o[:set]))


    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 indivual 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.
        vtz = ulc(o[:r] * (o[:t] * vec))

        if dZ
          vz = OpenStudio::Point3dVector.new
          vtz.each { |v| vz << OpenStudio::Point3d.new(v.x, v.y, v.z + dZ) }
          vts[nom] = vz
        else
          vts[nom] = to_p3Dv(t * vtz)
        end

        # 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

    vtx = o[:r] * (o[:t] * vtx)

    if dZ
      vz = OpenStudio::Point3dVector.new
      vtx.each { |v| vz << OpenStudio::Point3d.new(v.x, v.y, v.z + dZ) }
      vtx = vz
    else
      vtx = to_p3Dv(t * vtx)
    end

    st[:vts] = vts
    st[:vtx] = 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)



675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
# 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)



581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
# 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)



4936
4937
4938
4939
4940
4941
4942
4943
4944
4945
4946
4947
4948
4949
4950
4951
4952
4953
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
5002
5003
5004
5005
5006
5007
5008
5009
# File 'lib/osut/utils.rb', line 4936

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)