symian 0.1.0

data/lib/symian/operator.rb

@@ -0,0 +1,97 @@
+require 'symian/work_shift'
+
+
+module Symian
+  class Activity < Struct.new(:iid, :start_time, :end_time)
+  end
+
+
+  class Operator
+
+    extend Forwardable
+
+    REQUIRED_ATTRIBUTES = [
+      :oid,
+      :support_group_id,
+    ]
+
+    OTHER_ATTRIBUTES = [
+      :workshift,
+      :specialization,
+      :work_record,
+      :support_group_id,
+    ]
+
+    attr_reader *(REQUIRED_ATTRIBUTES + OTHER_ATTRIBUTES)
+
+    def_delegators :@workshift, :active_at?, :secs_to_begin_of_shift, :secs_to_end_of_shift
+    def_delegator :@workshift, :duration, :workshift_duration
+
+
+    def initialize(oid, support_group_id, opts={})
+      @oid = oid
+      @support_group_id = support_group_id
+
+      # set correspondent instance variables for optional arguments
+      opts.each do |k, v|
+        # ignore invalid attributes
+        instance_variable_set("@#{k}", v) if OTHER_ATTRIBUTES.include?(k)
+      end
+
+      # support :workshift => :all_day_long shortcut
+      if @workshift == :all_day_long
+        @workshift = WorkShift::WORKSHIFT_24x7
+      end
+
+      # default workshift is 24x7
+      @workshift ||= WorkShift::WORKSHIFT_24x7
+
+      @specialization ||= {}
+      @work_record ||= []
+    end
+
+
+    def assign(incident, incident_info, time)
+
+      # initialize incident start work time if needed
+      incident.start_work_time ||= time
+
+      # calculate time to end of shift
+      tteos = @workshift.secs_to_end_of_shift(time)
+      raise "tteos: #{tteos}" if tteos < 0.0
+
+      # specialization
+      specialization = @specialization[incident.category] || 1.0
+
+      # calculate time to incident escalation
+      ttie = incident_info[:needed_work_time] / specialization.to_f
+      raise "ttie: #{ttie}" if ttie < 0.0
+
+      # handle incident
+      if tteos < ttie # end of shift first
+        work_time = tteos
+        reason = :operator_off_duty
+      else # escalation first
+        work_time = ttie
+        reason = :incident_escalation
+      end
+
+      # update needed (effective) incident work time
+      incident_info[:needed_work_time] -= work_time * specialization
+
+      # update incident tracking
+      incident.add_tracking_information(:type => :work,
+                                        :at => time,
+                                        :duration => work_time,
+                                        :sg => @support_group_id,
+                                        :operator => @oid)
+
+      # update operator work record
+      @work_record << Activity.new(incident.iid, time, time + work_time)
+
+      # return [ reason, time_when_operator_stops_working ]
+      [ reason, time + work_time ]
+    end
+
+  end
+end

data/lib/symian/performance_analyzer.rb

@@ -0,0 +1,60 @@
+require 'symian/event'
+require 'symian/generator'
+require 'symian/incident'
+require 'symian/operator'
+require 'symian/support_group'
+
+
+module Symian
+  class PerformanceAnalyzer
+    def initialize(config)
+      @warmup_threshold = config.start_time + config.warmup_duration
+    end
+
+    def calculate_kpis(trace)
+      raise ArgumentError, 'Argument must be a TraceCollector' unless TraceCollector === trace
+
+      kpis = {}
+
+      # these metrics are considered as kpis
+      kpis[:all_incidents]        = trace.incidents
+      kpis[:incidents_considered] = 0
+      kpis[:closed_incidents]     = 0
+      kpis[:mean_ttr]             = 0
+      kpis[:max_ttr]              = 0
+      kpis[:mean_waiting_time]    = 0
+
+      max_ttr = 0
+      ttr_sum = 0
+      wt_sum  = 0
+      trace.with_incidents do |i|
+
+        next if @warmup_threshold and i.arrival_time < @warmup_threshold
+
+        kpis[:incidents_considered] += 1
+
+        if i.closed?
+          kpis[:closed_incidents] += 1
+          ttr = i.total_work_time
+          ttr_sum += ttr
+          wt_sum  += i.total_queue_time
+          max_ttr = ttr if ttr > max_ttr
+        end
+
+      end
+
+      kpis[:max_ttr] = max_ttr
+      if kpis[:closed_incidents] == 0
+        kpis[:mean_ttr]          = Float::MAX
+        kpis[:mean_waiting_time] = Float::MAX
+      else
+        kpis[:mean_ttr]          = ttr_sum / kpis[:closed_incidents]
+        kpis[:mean_waiting_time] = wt_sum / kpis[:closed_incidents]
+      end
+
+      # return kpis
+      kpis
+    end
+
+  end
+end

data/lib/symian/simulation.rb

@@ -0,0 +1,171 @@
+require 'symian/event'
+require 'symian/generator'
+require 'symian/operator'
+require 'symian/performance_analyzer'
+require 'symian/sorted_array'
+require 'symian/support_group'
+require 'symian/transition_matrix'
+require 'symian/trace_collector'
+
+
+module Symian
+  class Simulation
+
+    ATTRIBUTES = [ :start_time ]
+
+    attr_reader *ATTRIBUTES
+
+
+    def initialize(configuration, performance_analyzer, trace=TraceCollector.new(:memory))
+      @configuration = configuration
+
+      # setup performance analyzer and simulation trace
+      @performance_analyzer = performance_analyzer
+      @trace = trace
+
+      # setup simulation start and current time
+      @current_time = @start_time = @configuration.start_time
+
+      # create support groups
+      @support_groups = {}
+      @configuration.support_groups.each do |name,conf|
+        @support_groups[name] = SupportGroup.new(name, self, conf[:work_time], conf[:operators])
+      end
+
+      # create transition matrix
+      @transition_matrix = TransitionMatrix.new(@configuration.transition_matrix)
+
+      # create event queue
+      @event_queue = SortedArray.new
+    end
+
+
+    def new_event(type, data, time, destination)
+      @event_queue << Event.new(type, data, time, destination)
+    end
+
+
+    def now
+      @current_time
+    end
+
+
+    def run
+
+      # initialize support groups
+      @support_groups.values.each do |sg|
+        sg.initialize_at(@configuration.start_time)
+      end
+
+      # generate first incident
+      ig = IncidentGenerator.new(self, @configuration.incident_generation)
+      ig.generate
+
+      # schedule end of simulation
+      unless @configuration.end_time.nil?
+        # puts "Simulation ends at: #{@configuration.end_time}"
+        new_event(Event::ET_END_OF_SIMULATION, nil, @configuration.end_time, nil)
+      end
+
+      # calculate warmup threshold
+      warmup_threshold = @configuration.start_time + @configuration.warmup_duration
+
+      @incidents_being_worked_on ||= []
+
+      # launch simulation
+      until @event_queue.empty?
+        e = @event_queue.shift
+
+        # sanity check on simulation time flow
+        if @current_time > e.time
+          raise 'Error: simulation time inconsistency for event ' +
+                "e.type=#{e.type} @current_time=#{@current_time}, e.time=#{e.time}"
+        end
+
+        @current_time = e.time
+
+        #Trace.new_event e
+        case e.type
+          when Event::ET_INCIDENT_ARRIVAL
+
+            sg_name = @transition_matrix.escalation('In')
+
+            sg = @support_groups[sg_name]
+            sg.new_incident(e.data, e.time)
+
+            @incidents_being_worked_on << e.data
+
+            # generate next incident
+            ig.generate
+
+            # TODO: pinpoint instant for calculation of time spent in enqueued state
+
+
+          when Event::ET_INCIDENT_ASSIGNMENT
+
+            # TODO: implement calculation of time spent in suspended state
+
+
+          when Event::ET_OPERATOR_ACTIVITY_STARTS
+
+
+          when Event::ET_OPERATOR_ACTIVITY_FINISHES
+
+            sg = @support_groups[e.destination]
+            sg.operator_finished_working(e.data[0], e.time)
+
+
+          when Event::ET_INCIDENT_RESCHEDULING
+
+            sg = @support_groups[e.destination]
+            sg.schedule_incident_for_reassignment(e.data[0], e.data[1], e.time)
+
+            # TODO: pinpoint instant for calculation of time spent in suspended state
+
+
+          when Event::ET_INCIDENT_ESCALATION
+            inc = e.data
+
+            sg_name = @transition_matrix.escalation(e.destination)
+            if sg_name == "Out"
+              inc.closure_time = e.time
+
+              # remove incident from list of incidents being worked on and add it to trace
+              @incidents_being_worked_on.delete(inc)
+              @trace.record_incidents(inc)
+            else
+              sg = @support_groups[sg_name]
+              sg.new_incident(inc, e.time)
+            end
+
+
+          when Event::ET_OPERATOR_LEAVING
+
+            sg = @support_groups[e.destination]
+            sg.operator_going_home(e.data, e.time)
+
+
+          when Event::ET_OPERATOR_RETURNING
+
+            sg = @support_groups[e.destination]
+            sg.operator_arrived_at_work(e.data, e.time)
+
+
+          when Event::ET_SUPPORT_GROUP_QUEUE_SIZE_CHANGE
+
+
+          when Event::ET_END_OF_SIMULATION
+            break
+
+        end
+      end
+
+      # save trace file
+      @trace.save_and_close
+      kpis = @performance_analyzer.calculate_kpis(@trace)
+      kpis.merge(incidents_being_worked_on: @incidents_being_worked_on.size)
+
+    end
+
+  end
+end

data/lib/symian/sorted_array.rb

@@ -0,0 +1,57 @@
+module Symian
+  # the SortedArray class was taken from the ruby cookbook
+  class SortedArray < Array
+    def initialize(*args, &sort_by)
+      @sort_by = sort_by || Proc.new { |x,y| x <=> y }
+      super(*args)
+      sort! &sort_by
+    end
+
+    def insert(i, v)
+      if size == 0 or v < self[0]
+        super(0, v) 
+      elsif v > self[-1]
+        super(-1, v) 
+      else
+        left = 0
+        right = size - 1
+        middle = (left + right)/2
+        while left < right
+          if v >= self[middle]
+            left = middle + 1
+          else
+            right = middle
+          end
+          middle = (left + right)/2
+        end
+        super(middle, v)
+      end
+    end
+
+    def <<(el)
+      insert(0, el)
+    end
+
+    alias push <<
+    alias unshift <<
+
+    # some methods, like collect!, can modify the items in an array, 
+    # taking them out of sort order. we need to redefine those
+    # methods.
+    # we can't use define_method to define these methods because in 
+    # Ruby 1.8 you can't use define_method to create a method that 
+    # takes a block argument.
+    [ "collect!", "flatten!", "[]=" ].each do |method_name|
+      class_eval %{
+        def #{method_name}(*args)
+          super
+          sort! &@sort_by
+        end
+      }
+    end
+
+    def reverse!
+      # do nothing: reversing the array would disorder it.
+    end
+  end
+end

data/lib/symian/support/dsl_helper.rb

@@ -0,0 +1,18 @@
+# taken from Jim Freeze's excellent article "Creating DSLs with Ruby"
+# http://www.artima.com/rubycs/articles/ruby_as_dsl.html
+
+class Module
+  def dsl_accessor(*symbols)
+    symbols.each { |sym|
+      class_eval %{
+        def #{sym}(*val)
+          if val.empty?
+            @#{sym}
+          else
+            @#{sym} = val.size == 1 ? val[0] : val
+          end
+        end
+      }
+    }
+  end
+end

data/lib/symian/support/yaml_io.rb

@@ -0,0 +1,9 @@
+require 'yaml'
+
+module Symian
+  module YAMLSerializable
+    def to_yaml_properties
+      self.class.const_get('TRACED_ATTRIBUTES').map{|attr| "@#{attr.to_s}"}
+    end
+  end
+end

data/lib/symian/support_group.rb

@@ -0,0 +1,182 @@
+require 'erv'
+
+require 'symian/event'
+require 'symian/operator'
+require 'symian/work_shift'
+
+require 'symian/support/yaml_io'
+
+
+module Symian
+
+  class SupportGroup
+
+    # setup readable/accessible attributes
+    ATTRIBUTES = [ :sgid, :operators ]
+
+    attr_reader *ATTRIBUTES
+
+
+    # setup attributes saved in traces
+    include YAMLSerializable
+
+    TRACED_ATTRIBUTES = ATTRIBUTES + [ :incident_queue_info ]
+
+
+    def initialize(support_group_id, simulation, work_time_characterization, operator_characterizations)
+      @sgid = support_group_id
+      @simulation = simulation
+
+      # initialize needed_work_time_rng
+      @needed_work_time_rv = ERV::RandomVariable.new(work_time_characterization)
+
+      # create operators
+      @operators = []
+
+      if operator_characterizations.kind_of?(Hash)
+        operator_characterizations = [ operator_characterizations ]
+      end
+
+      next_op_id = 1
+      operator_characterizations.each do |x|
+        x[:number].times do |y|
+          op = Operator.new("OP#{next_op_id}_#{@sgid}", @sgid, x.reject { |k, v| k == :number })
+          @operators << op
+          next_op_id = next_op_id + 1
+        end
+      end
+
+      # initialize incident queue and related tracking information
+      @incident_queue = []
+      @incident_queue_info = []
+    end
+
+
+    def initialize_at(time)
+      # find out which operators are off duty and schedule their comeback
+      @operators_off_work = @operators.select do |x|
+        !x.workshift.active_at?(time)
+      end
+      @operators_off_work.each do |op|
+        t = op.workshift.secs_to_begin_of_shift(time)
+        @simulation.new_event(Event::ET_OPERATOR_RETURNING, op.oid,
+                              time + t, @sgid)
+      end
+
+      # find out which operators are on duty and schedule their leaving
+      @available_operators = @operators - @operators_off_work
+      @available_operators.each do |op|
+        t = op.workshift.secs_to_end_of_shift(time)
+        @simulation.new_event(Event::ET_OPERATOR_LEAVING, op.oid,
+                              time + t, @sgid) unless t == WorkShift::Infinity
+      end
+    end
+
+
+    def new_incident(incident, time)
+      # increase number of visited SGs
+      incident.visited_support_groups += 1
+
+      incident_info = {
+        # set up incident needed work time
+        :needed_work_time => @needed_work_time_rv.next,
+        # # reset queue_time_at_last_sg attribute
+        # :queue_time => 0
+      }
+
+      # put incident at the end of the queue
+      @incident_queue << [ incident, incident_info, time ]
+
+      # update queue size tracking information
+      @incident_queue_info << { :size => @incident_queue.size, :time => time }
+      @simulation.new_event(Event::ET_SUPPORT_GROUP_QUEUE_SIZE_CHANGE, @incident_queue.size,
+                            time, @sgid)
+
+      # try to allocate operator
+      try_to_allocate_operator(time)
+    end
+
+
+    def schedule_incident_for_reassignment(incident, incident_info, time)
+      @incident_queue.unshift [ incident, incident_info, time ]
+      # update queue size tracking information
+      @incident_queue_info << { :size => @incident_queue.size, :time => time }
+      try_to_allocate_operator(time)
+    end
+
+
+    def operator_going_home(operator_id, time)
+      op = @operators.find{|x| x.oid == operator_id }
+      @available_operators.delete_if{|x| x.oid == operator_id }
+      @operators_off_work << op
+      @simulation.new_event(Event::ET_OPERATOR_RETURNING, op.oid,
+                            time + 86400 - op.workshift.duration, @sgid)
+    end
+
+
+    def operator_arrived_at_work(operator_id, time)
+      op = @operators.find{|x| x.oid == operator_id }
+      @operators_off_work.delete(op)
+      @available_operators << op
+      try_to_allocate_operator(time)
+      @simulation.new_event(Event::ET_OPERATOR_LEAVING, op.oid,
+                            time + op.workshift.duration, @sgid)
+    end
+
+
+    def operator_finished_working(operator_id, time)
+      op = @operators.find{|x| x.oid == operator_id }
+      if op.workshift.secs_to_end_of_shift(time) > 0
+        @available_operators << op
+      end
+      try_to_allocate_operator(time)
+    end
+
+
+    private
+
+      def try_to_allocate_operator(time)
+        if !@available_operators.empty? and !@incident_queue.empty?
+          op = @available_operators.shift
+          i, inc_info, t = @incident_queue.shift
+
+          # update incident tracking information
+          queue_time = time.to_i - t.to_i
+          i.add_tracking_information(:type => :queue,
+                                     :at => t,
+                                     :duration => queue_time,
+                                     :sg => @support_group_id)
+
+
+          @simulation.new_event(Event::ET_SUPPORT_GROUP_QUEUE_SIZE_CHANGE,
+                                @incident_queue.size, time, @sgid)
+          @simulation.new_event(Event::ET_INCIDENT_ASSIGNMENT,
+                                [ i.iid, op.oid ], time, @sgid)
+          @simulation.new_event(Event::ET_OPERATOR_ACTIVITY_STARTS,
+                                [ op.oid, i.iid ], time, @sgid)
+
+          # assign updates inc_info
+          report = op.assign(i, inc_info, time)
+          finish_time = report[1]
+
+          puts "finish_time: #{finish_time}, time: #{time}" if time > finish_time
+          @simulation.new_event(Event::ET_OPERATOR_ACTIVITY_FINISHES,
+                                [ op.oid, i.iid ], finish_time, @sgid)
+
+          case report[0]
+            when :incident_escalation
+              @simulation.new_event(Event::ET_INCIDENT_ESCALATION,
+                                    i, finish_time, @sgid)
+            when :operator_off_duty
+              # TODO: implement configurable rescheduling policy
+              @incident_queue << [ i, inc_info, finish_time ]
+              @simulation.new_event(Event::ET_INCIDENT_RESCHEDULING,
+                                    [ i, inc_info, op.oid ], finish_time, @sgid)
+          end
+        end
+      end
+
+  end
+
+end
+