Module: BuildingSync::Helper

Included in:
AllResourceTotal, AuditDate, BuildingSection, BuildingSystem, Contact, Facility, Generator, HVACSystem, LightingSystemType, LoadsSystem, Measure, Report, ResourceUse, Scenario, SpatialElement, TimeSeries, Translator, Utility
Defined in:
lib/buildingsync/helpers/helper.rb

Overview

helper class for helper methods in BuildingSync

Instance Method Summary collapse

Instance Method Details

#help_calculate_hours(optional_schedule, cut_off_value = 0.5) ⇒ OpenStudio::Model::ScheduleRuleSet

calculate schedule hours that are at or above the cut off value @ return [Float]

Parameters:

  • optional_schedule (OpenStudio::Model::OptionalSchedule)

Returns:

  • (OpenStudio::Model::ScheduleRuleSet) 


427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
 
# File 'lib/buildingsync/helpers/helper.rb', line 427

def help_calculate_hours(optional_schedule, cut_off_value = 0.5)
  calculated_hours_per_week = 0.0
  schedule_rule_set = help_get_schedule_rule_set_from_schedule(optional_schedule)
  return 0.0 if schedule_rule_set.nil?
  defaultProfile = schedule_rule_set.defaultDaySchedule
  default_profile_duration = help_get_duration(defaultProfile, cut_off_value)
  default_number_of_days = 7
  schedule_rule_set.scheduleRules.each do |rule|
    profile_duration = help_get_duration(rule.daySchedule, cut_off_value)
    number_of_days = help_count_number_of_days(rule)
    default_number_of_days -= number_of_days
    calculated_hours_per_week += profile_duration * number_of_days
  end
  calculated_hours_per_week += default_profile_duration * default_number_of_days
  return calculated_hours_per_week
end

#help_convert(val, from_unit, to_unit) ⇒ Float?

convert between supported units

Parameters:

  • val (Numeric) —

    value to convert, i.e. 1

  • from_unit (String) —

    starting units

  • to_unit (String) —

    desired end units

Returns:

  • (Float) —

    if successful, converted value

  • (nil) —

    if unsuccessful



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/buildingsync/helpers/helper.rb', line 89

def help_convert(val, from_unit, to_unit)
  if from_unit == to_unit
    return val
  end

  btu_multiples = [
    {
      'from' => 'Btu',
      'kBtu' => 0.001,
      'MMBtu' => 0.000001
    },
    {
      'from' => 'kBtu',
      'Btu' => 1000,
      'MMBtu' => 0.001
    },
    {
      'from' => 'MMBtu',
      'Btu' => 1000000,
      'kBtu' => 1000
    }
  ]
  map = btu_multiples.find { |from| from['from'] == from_unit }
  if !map.nil? && !map.empty?
    mult = map[to_unit]
    if !mult.nil?
      return val * mult
    else
      OpenStudio.logFree(OpenStudio::Error, 'BuildingSync.Helper.help_convert', "Unable to convert from: #{from_unit} to #{to_unit}")
    end
  else
    OpenStudio.logFree(OpenStudio::Error, 'BuildingSync.Helper.help_convert', "Unable to convert from: #{from_unit} to #{to_unit}")
    return nil
  end
end

#help_count_number_of_days(rule) ⇒ Object

count number of days return [Integer]

Parameters:

  • rule (OpenStudio::Model::ScheduleRule) 


447
448
449
450
451
452
453
454
455
456
457
 
# File 'lib/buildingsync/helpers/helper.rb', line 447

def help_count_number_of_days(rule)
  count = 0
  count += 1 if rule.applyFriday
  count += 1 if rule.applyMonday
  count += 1 if rule.applySaturday
  count += 1 if rule.applySunday
  count += 1 if rule.applyThursday
  count += 1 if rule.applyTuesday
  count += 1 if rule.applyWednesday
  return count
end

#help_element_class_type_check(xml_element, expected_type) ⇒ Object 



42
43
44
45
46
47
 
# File 'lib/buildingsync/helpers/helper.rb', line 42

def help_element_class_type_check(xml_element, expected_type)
  if xml_element.name != expected_type
    OpenStudio.logFree(OpenStudio::Error, "BuildingSync.#{expected_type}.initialize", "Attempted to initialize #{expected_type} object with Element name of: #{xml_element.name}")
    raise StandardError, "Attempted to initialize #{expected_type} object with Element name of: #{xml_element.name}"
  end
end

#help_get_attribute_value(xml_element, attribute_name) ⇒ String?

get attribute value from xml element

Parameters:

  • xml_element (REXML::Element)
  • attribute_name (String) —

    name of attribute to get the value for

Returns:

  • (String) —

    if attribute

  • (nil) —

    if attribute doesnt exist



130
131
132
133
134
135
 
# File 'lib/buildingsync/helpers/helper.rb', line 130

def help_get_attribute_value(xml_element, attribute_name)
  if xml_element && !xml_element.attribute(attribute_name).nil?
    return xml_element.attribute(attribute_name).value
  end
  return nil
end

#help_get_default_schedule_set(model) ⇒ Object

get default schedule set return [OpenStudio::Model::DefaultScheduleSet]

Parameters:

  • model (OpenStudio::Model) 


483
484
485
486
487
488
489
490
491
492
 
# File 'lib/buildingsync/helpers/helper.rb', line 483

def help_get_default_schedule_set(model)
  if model.getBuilding.defaultScheduleSet.is_initialized
    return model.getBuilding.defaultScheduleSet.get
  else
    space_types = model.getSpaceTypes
    space_types.each do |space_type|
      return space_type.defaultScheduleSet.get
    end
  end
end

#help_get_duration(profile, cut_off_value) ⇒ Object

get duration return [Float]

Parameters:

  • profile (OpenStudio::Model::ScheduleDay)
  • cut_off_value (Float) 


463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
 
# File 'lib/buildingsync/helpers/helper.rb', line 463

def help_get_duration(profile, cut_off_value)
  last_time = nil
  duration_above_cut_off = 0.0
  profile.times.each do |time|
    if profile.getValue(time) >= cut_off_value
      if last_time.nil?
        duration_above_cut_off += time.totalHours
      else
        duration_above_cut_off += time.totalHours - last_time.totalHours
      end
    end
    last_time = time
  end

  return duration_above_cut_off
end

#help_get_end_time(profile, cut_off_value) ⇒ Object

get end time

Parameters:

  • profile (OpenStudio::Model::ScheduleDay)
  • cut_off_value (Float) 


395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/buildingsync/helpers/helper.rb', line 395

def help_get_end_time(profile, cut_off_value)
  last_time = nil
  profile.times.each do |time|
    if profile.getValue(time) >= cut_off_value
      last_time = time
    elsif profile.getValue(time) < cut_off_value && !last_time.nil?
      return last_time
    end
  end
  return OpenStudio::Time.new
end

#help_get_end_time_sat(schedule_rule_set, cut_off_value = 0.5) ⇒ Object

get end time Saturday

Parameters:

  • schedule_rule_set (OpenStudio::Model::ScheduleRuleSet)
  • cut_off_value (Float) (defaults to: 0.5) 


339
340
341
342
343
344
345
346
347
348
 
# File 'lib/buildingsync/helpers/helper.rb', line 339

def help_get_end_time_sat(schedule_rule_set, cut_off_value = 0.5)
  profile = schedule_rule_set.defaultDaySchedule
  schedule_rule_set.scheduleRules.each do |rule|
    if rule.applySaturday
      profile = rule.daySchedule
    end
  end

  return help_get_end_time(profile, cut_off_value)
end

#help_get_end_time_sun(schedule_rule_set, cut_off_value = 0.5) ⇒ Object

get end time Sunday

Parameters:

  • schedule_rule_set (OpenStudio::Model::ScheduleRuleSet)
  • cut_off_value (Float) (defaults to: 0.5) 


367
368
369
370
371
372
373
374
375
376
 
# File 'lib/buildingsync/helpers/helper.rb', line 367

def help_get_end_time_sun(schedule_rule_set, cut_off_value = 0.5)
  profile = schedule_rule_set.defaultDaySchedule
  schedule_rule_set.scheduleRules.each do |rule|
    if rule.applySunday
      profile = rule.daySchedule
    end
  end

  return help_get_end_time(profile, cut_off_value)
end

#help_get_end_time_weekday(schedule_rule_set, cut_off_value = 0.5) ⇒ Object

get end time weekday

Parameters:

  • schedule_rule_set (OpenStudio::Model::ScheduleRuleSet)
  • cut_off_value (Float) (defaults to: 0.5) 


311
312
313
314
315
316
317
318
319
320
 
# File 'lib/buildingsync/helpers/helper.rb', line 311

def help_get_end_time_weekday(schedule_rule_set, cut_off_value = 0.5)
  profile = schedule_rule_set.defaultDaySchedule
  schedule_rule_set.scheduleRules.each do |rule|
    if rule.applyMonday
      profile = rule.daySchedule
    end
  end

  return help_get_end_time(profile, cut_off_value)
end

#help_get_or_create(parent, new_element_type) ⇒ Object 



49
50
51
52
53
54
55
 
# File 'lib/buildingsync/helpers/helper.rb', line 49

def help_get_or_create(parent, new_element_type)
  new_element = parent.elements[new_element_type]
  if new_element.nil?
    new_element = REXML::Element.new(new_element_type, parent)
  end
  return new_element
end

#help_get_schedule_rule_set_from_schedule(optional_schedule) ⇒ OpenStudio::Model::ScheduleRuleSet

get schedule rule set from schedule

Parameters:

  • optional_schedule (OpenStudio::Model::OptionalSchedule)

Returns:

  • (OpenStudio::Model::ScheduleRuleSet) 


410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/buildingsync/helpers/helper.rb', line 410

def help_get_schedule_rule_set_from_schedule(optional_schedule)
  if optional_schedule.is_a?(OpenStudio::Model::OptionalSchedule)
    if optional_schedule.is_initialized
      schedule = optional_schedule.get
    else
      return nil
    end
  else
    schedule = optional_schedule
  end
  return schedule.to_ScheduleRuleset.get
end

#help_get_start_time(profile, cut_off_value) ⇒ Object

get start time

Parameters:

  • profile (OpenStudio::Model::ScheduleDay)
  • cut_off_value (Float) 


381
382
383
384
385
386
387
388
389
390
 
# File 'lib/buildingsync/helpers/helper.rb', line 381

def help_get_start_time(profile, cut_off_value)
  last_time = OpenStudio::Time.new
  profile.times.each do |time|
    if profile.getValue(time) >= cut_off_value
      return last_time
    end
    last_time = time
  end
  return OpenStudio::Time.new
end

#help_get_start_time_sat(schedule_rule_set, cut_off_value = 0.5) ⇒ Object

get start time Saturday

Parameters:

  • schedule_rule_set (OpenStudio::Model::ScheduleRuleSet)
  • cut_off_value (Float) (defaults to: 0.5) 


325
326
327
328
329
330
331
332
333
334
 
# File 'lib/buildingsync/helpers/helper.rb', line 325

def help_get_start_time_sat(schedule_rule_set, cut_off_value = 0.5)
  profile = schedule_rule_set.defaultDaySchedule
  schedule_rule_set.scheduleRules.each do |rule|
    if rule.applySaturday
      profile = rule.daySchedule
    end
  end

  return help_get_start_time(profile, cut_off_value)
end

#help_get_start_time_sun(schedule_rule_set, cut_off_value = 0.5) ⇒ Object

get start time Sunday

Parameters:

  • schedule_rule_set (OpenStudio::Model::ScheduleRuleSet)
  • cut_off_value (Float) (defaults to: 0.5) 


353
354
355
356
357
358
359
360
361
362
 
# File 'lib/buildingsync/helpers/helper.rb', line 353

def help_get_start_time_sun(schedule_rule_set, cut_off_value = 0.5)
  profile = schedule_rule_set.defaultDaySchedule
  schedule_rule_set.scheduleRules.each do |rule|
    if rule.applySunday
      profile = rule.daySchedule
    end
  end

  return help_get_start_time(profile, cut_off_value)
end

#help_get_start_time_weekday(schedule_rule_set, cut_off_value = 0.5) ⇒ Object

get start time weekday

Parameters:

  • schedule_rule_set (OpenStudio::Model::ScheduleRuleSet)
  • cut_off_value (Float) (defaults to: 0.5) 


297
298
299
300
301
302
303
304
305
306
 
# File 'lib/buildingsync/helpers/helper.rb', line 297

def help_get_start_time_weekday(schedule_rule_set, cut_off_value = 0.5)
  profile = schedule_rule_set.defaultDaySchedule
  schedule_rule_set.scheduleRules.each do |rule|
    if rule.applyMonday
      profile = rule.daySchedule
    end
  end

  return help_get_start_time(profile, cut_off_value)
end

#help_get_text_value(xml_element) ⇒ String?

get text value from xml element

Parameters:

  • xml_element (REXML::Element)

Returns:

  • (String) —

    if text value exists

  • (nil) —

    if text value doesnt exist or element is complex (has children)



61
62
63
64
65
66
 
# File 'lib/buildingsync/helpers/helper.rb', line 61

def help_get_text_value(xml_element)
  if xml_element && !xml_element.text.nil?
    return xml_element.text
  end
  return nil
end

#help_get_text_value_as_bool(xml_element) ⇒ Object 



78
79
80
81
 
# File 'lib/buildingsync/helpers/helper.rb', line 78

def help_get_text_value_as_bool(xml_element)
  v = help_get_text_value(xml_element)
  return v.to_bool
end

#help_get_text_value_as_date(xml_element) ⇒ Date?

get date value from xml element

Parameters:

  • xml_element (REXML::Element)

Returns:

  • (Date) —

    if the text can be parsed as a date

  • (nil) —

    if the text cant be parsed as a date



141
142
143
144
145
146
147
148
149
150
 
# File 'lib/buildingsync/helpers/helper.rb', line 141

def help_get_text_value_as_date(xml_element)
  if xml_element && !xml_element.text.nil?
    begin
      return Date.parse(xml_element.text)
    rescue ArgumentError
      return nil
    end
  end
  return nil
end

#help_get_text_value_as_datetime(xml_element) ⇒ DateTime?

get date datetime from xml element

Parameters:

  • xml_element (REXML::Element)

Returns:

  • (DateTime) —

    if the text can be parsed as a date

  • (nil) —

    if the text cant be parsed as a date



156
157
158
159
160
161
162
163
164
165
 
# File 'lib/buildingsync/helpers/helper.rb', line 156

def help_get_text_value_as_datetime(xml_element)
  if xml_element && !xml_element.text.nil?
    begin
      return DateTime.parse(xml_element.text)
    rescue ArgumentError
      return nil
    end
  end
  return nil
end

#help_get_text_value_as_float(xml_element) ⇒ Object 



68
69
70
71
 
# File 'lib/buildingsync/helpers/helper.rb', line 68

def help_get_text_value_as_float(xml_element)
  v = help_get_text_value(xml_element)
  return v.to_f
end

#help_get_text_value_as_integer(xml_element) ⇒ Object 



73
74
75
76
 
# File 'lib/buildingsync/helpers/helper.rb', line 73

def help_get_text_value_as_integer(xml_element)
  v = help_get_text_value(xml_element)
  return v.to_i
end

#help_get_zone_name_list(zones) ⇒ Object

get zone name list

Parameters:

  • zones (array<OpenStudio::Model::ThermalZone>)

Returns:

  • array



170
171
172
173
174
175
176
 
# File 'lib/buildingsync/helpers/helper.rb', line 170

def help_get_zone_name_list(zones)
  names = []
  zones.each do |zone|
    names << zone.name.get
  end
  return names
end

#help_load_doc(xml_file_path) ⇒ Object

read xml file document

Parameters:

  • xml_file_path (String)

Returns:

  • REXML::Document



181
182
183
184
185
186
187
 
# File 'lib/buildingsync/helpers/helper.rb', line 181

def help_load_doc(xml_file_path)
  doc = nil
  File.open(xml_file_path, 'r') do |file_content|
    doc = REXML::Document.new(file_content, ignore_whitespace_nodes: :all)
  end
  return doc
end

#help_print_all_schedules(file_name, default_schedule_set) ⇒ Object

print all schedules to a file

Parameters:

  • file_name (String)
  • default_schedule_set (OpenStudio::Model::DefaultScheduleSet) 


192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/buildingsync/helpers/helper.rb', line 192

def help_print_all_schedules(file_name, default_schedule_set)
  f = File.open(file_name, 'w')
  help_print_schedule(f, default_schedule_set.numberofPeopleSchedule)
  help_print_schedule(f, default_schedule_set.hoursofOperationSchedule)
  help_print_schedule(f, default_schedule_set.peopleActivityLevelSchedule)
  help_print_schedule(f, default_schedule_set.lightingSchedule)
  help_print_schedule(f, default_schedule_set.electricEquipmentSchedule)
  help_print_schedule(f, default_schedule_set.gasEquipmentSchedule)
  help_print_schedule(f, default_schedule_set.hotWaterEquipmentSchedule)
  help_print_schedule(f, default_schedule_set.infiltrationSchedule)
  help_print_schedule(f, default_schedule_set.steamEquipmentSchedule)
  help_print_schedule(f, default_schedule_set.otherEquipmentSchedule)
  f.close
end

#help_print_schedule(f, optional_schedule, cut_off_value = 0.5) ⇒ Object

print schedule

Parameters:

  • f (File)
  • optional_schedule (OpenStudio::Model::OptionalSchedule)
  • cut_off_value (Float) (defaults to: 0.5) 


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
 
# File 'lib/buildingsync/helpers/helper.rb', line 268

def help_print_schedule(f, optional_schedule, cut_off_value = 0.5)
  if optional_schedule.is_a?(OpenStudio::Model::OptionalSchedule) && optional_schedule.is_initialized
    schedule = optional_schedule.get
    if schedule.is_a?(OpenStudio::Model::OptionalSchedule) && schedule.is_initialized
      schedule = schedule.get
    end
  else
    schedule = optional_schedule
  end
  if schedule.is_a?(OpenStudio::Model::Schedule)
    schedule_rule_set = schedule.to_ScheduleRuleset.get
    f.puts "schedule_rule_set name: ,#{schedule_rule_set.name}, duration:, #{help_calculate_hours(optional_schedule, cut_off_value)}"
    defaultProfile = schedule_rule_set.defaultDaySchedule

    f.puts 'Name, Su, Mo, Tu, We, Th, Fr, Sa, Duration, TimeValue1, TV2, ...'
    help_write_profile(f, defaultProfile, nil, cut_off_value)

    schedule_rule_set.scheduleRules.each do |rule|
      help_write_profile(f, rule.daySchedule, rule, cut_off_value)
    end
    f.puts
  else
    puts "schedule: #{schedule}"
  end
end

#help_write_profile(f, profile, rule, cut_off_value = 0.5) ⇒ Object

write a schedule profile

Parameters:

  • f (File)
  • profile (OpenStudio::Model::ScheduleDay)
  • rule (OpenStudio::Model::ScheduleRule)
  • cut_off_value (Float) (defaults to: 0.5) 


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
 
# File 'lib/buildingsync/helpers/helper.rb', line 212

def help_write_profile(f, profile, rule, cut_off_value = 0.5)
  time_row = "#{profile.name},"
  if rule.nil?
    time_row += ',,,,,,,'
  else
    if rule.applySunday
      time_row += 'X,'
    else
      time_row += ','
    end
    if rule.applyMonday
      time_row += 'X,'
    else
      time_row += ','
    end
    if rule.applyTuesday
      time_row += 'X,'
    else
      time_row += ','
    end
    if rule.applyWednesday
      time_row += 'X,'
    else
      time_row += ','
    end
    if rule.applyThursday
      time_row += 'X,'
    else
      time_row += ','
    end
    if rule.applyFriday
      time_row += 'X,'
    else
      time_row += ','
    end
    if rule.applySaturday
      time_row += 'X,'
    else
      time_row += ','
    end
  end
  time_row += ','
  value_row = ",,,,,,,,#{help_get_duration(profile, cut_off_value)},"

  profile.times.each do |time|
    time_row += "#{time},"
    value_row += "#{profile.getValue(time)},"
  end
  f.write time_row + "\n"
  f.write value_row + "\n"
end