symian 0.1.0

data/lib/symian/trace_collector.rb

@@ -0,0 +1,107 @@
+require 'yaml'
+
+module Symian
+  class TraceCollector
+    extend Forwardable
+
+    # attributes to store
+    ATTRIBUTES = [ :incidents, :events, :support_groups ]
+
+    def initialize(backend, opts={})
+      @backend = case backend
+      when :memory
+        MemoryBackend.new
+      when :yaml
+        raise ArgumentError, 'File not specified' unless opts[:file]
+        YAMLBackend.new(opts[:file])
+      # when :marshal
+      #   MarshalBackend.new
+      # when :json
+      #   JsonBackend.new
+      else
+        raise ArgumentError, 'Unsupported backend!'
+      end
+    end
+
+    # methods to dynamically generate
+    METHODS = [ :save_and_close, ATTRIBUTES.collect{ |attr| [ "#{attr}", "record_#{attr}", "with_#{attr}" ] } ].flatten!
+
+    # delegate methods to @backend
+    def_delegators :@backend, *METHODS
+
+  end
+
+
+  class MemoryBackend
+
+    def initialize
+      TraceCollector::ATTRIBUTES.each do |attr|
+        instance_variable_set("@#{attr}_storage", [])
+      end
+    end
+
+    TraceCollector::ATTRIBUTES.each do |attr|
+      class_eval <<-EOS
+        def record_#{attr}(elem)
+          if Array === elem
+            @#{attr}_storage += elem
+          else
+            @#{attr}_storage << elem
+          end
+          self
+        end
+
+        def #{attr}
+          @#{attr}_storage.size
+        end
+
+        def with_#{attr}
+          if block_given?
+            @#{attr}_storage.each do |el|
+              yield el
+            end
+          else
+            Enumerator.new(@#{attr}_storage)
+          end
+        end
+      EOS
+    end
+
+    def save_and_close
+      # raise NotImplementedError, 'A trace with memory backend cannot be saved!'
+    end
+
+  end
+
+
+  class YAMLBackend < MemoryBackend
+
+    def initialize(filename)
+      @filename = filename
+      # if file exists and is non-empty, try to read its contents
+      size = File.size?(@filename)
+      if !size.nil? and size > 0
+        hash = File.open(@filename) do |file|
+          YAML.load(file)
+        end
+        TraceCollector::ATTRIBUTES.map(&:to_s).each do |attr|
+          instance_variable_set("@#{attr}_storage", hash[attr])
+        end
+      else
+        super()
+      end
+    end
+
+    def save_and_close
+      hash = {}
+      TraceCollector::ATTRIBUTES.map(&:to_s).each do |attr|
+        hash[attr] = instance_variable_get("@#{attr}_storage")
+      end
+      File.open(@filename, 'w') do |file|
+        YAML.dump(hash, file)
+      end
+    end
+
+  end
+
+end

data/lib/symian/transition_matrix.rb

@@ -0,0 +1,168 @@
+require 'csv'
+require 'stringio'
+
+require 'erv'
+
+
+module Symian
+  class TransitionMatrix
+
+    # this is mostly for testing purposes
+    attr_reader :transition_probabilities
+
+    def initialize(input)
+      # allow filename, string, and IO objects as input
+      if input.kind_of?(String)
+        if File.exists?(input)
+          input = File.new(input, 'r')
+        else
+          input = StringIO.new(input.strip.split("\n").collect{|l| l.strip }.join("\n"))
+        end
+      else
+        raise RuntimeError unless input.respond_to?(:read)
+      end
+
+      @transition_probabilities = {}
+
+      # process escalation matrix
+      headers = nil
+      CSV.parse(input.read, :headers => :first_row) do |row|
+        headers ||= row.headers
+        @sg_names ||= headers[1..-2]
+
+        # make sure that support groups do not include the "In" virtual support group
+        raise RuntimeError if @sg_names.include?("In")
+
+        # make sure that last support group is the "Out" virtual support group
+        raise RuntimeError unless headers[-1] == "Out"
+
+        sg_name = row[0]  # the first row element is the support group name
+
+        # make sure support group name is valid
+        raise RuntimeError unless sg_name == "In" or @sg_names.include?(sg_name)
+
+        # make sure we are not overwriting existing data
+        raise RuntimeError if @transition_probabilities[sg_name]
+        @transition_probabilities[sg_name] = []
+
+        # prepare corresponding row in transition matrix
+        2.upto(row.length) do |i|
+          escalations = Integer(row[i-1]) # raises ArgumentError in case of errors
+          if escalations > 0
+            @transition_probabilities[sg_name] << { :sg_name => headers[i-1],
+                                                    :escalations => escalations }
+          end
+        end
+
+        # calculate normalized probabilities
+        normalize_probabilities(@transition_probabilities[sg_name])
+      end
+
+      # check that we have transition probabilities for each support group
+      [ "In", *@sg_names].each do |name|
+        raise RuntimeError unless @transition_probabilities.has_key?(name)
+      end
+
+      # TODO: make seeding of this thing configurable...
+      @rng = ERV::RandomVariable.new(:distribution => :uniform, :min_value => 0.0, :max_value => 1.0)
+    end
+
+
+    def escalation(from)
+      # raise error if source support group does not exist
+      raise ArgumentError unless tps = @transition_probabilities[from]
+
+      # get random value
+      x = @rng.next
+
+      # return name of first support group whose (cumulative)
+      # transition probability is larger than x
+      tps.each do |el|
+        return el[:sg_name] if el[:probability] > x
+      end
+
+      # the destination support group was not found
+      raise RuntimeError
+    end
+
+
+    def merge(sg1_name, sg2_name, new_name=nil)
+      # raise error if support groups do not exist
+      raise RuntimeError unless sg1_probs = @transition_probabilities.delete(sg1_name) and
+                                sg2_probs = @transition_probabilities.delete(sg2_name)
+
+      new_sg_name = new_name || "Merge_of_%s_and_%s" % [ sg1_name, sg2_name ]
+
+      # recalculate escalations to new sg
+      @transition_probabilities.each do |k,v|
+
+        # add escalation information for new group
+        escalations = 0
+        v.each do |el|
+          if el[:sg_name] == sg1_name or el[:sg_name] == sg2_name
+            escalations += el[:escalations]
+          end
+        end
+
+        v << { :sg_name => new_sg_name,
+               :escalations => escalations }
+
+        # remove old escalation information
+        v.delete_if {|el| el[:sg_name] == sg1_name or el[:sg_name] == sg2_name }
+
+        # recalculate normalized probabilities
+        normalize_probabilities(v)
+      end
+
+      # update @sg_names
+      @sg_names[@sg_names.index(sg1_name)] = new_name
+      @sg_names.delete(sg2_name)
+
+      # recalculate escalations from new sg
+      total_escalation_info = sg1_probs + sg2_probs
+      @transition_probabilities[new_sg_name] = []
+      [ @sg_names, "Out" ].flatten!.each do |name|
+        escalations = total_escalation_info.inject(0) do |sum,el|
+          sum + (el[:sg_name] == name ? el[:escalations] : 0)
+        end
+
+        if escalations > 0
+          @transition_probabilities[new_sg_name] << { :sg_name => name,
+                                                      :escalations => escalations }
+        end
+      end
+
+      # recalculate normalized probabilities
+      normalize_probabilities(@transition_probabilities[new_sg_name])
+    end
+
+
+    def to_s
+      lines = [ "From/To,#{@sg_names.join(',')},Out" ]
+      [ "In", *@sg_names ].each do |input_sg|
+        escalations = [ @sg_names, "Out" ].flatten!.map do |output_sg|
+          @transition_probabilities[input_sg].map{|x| x[:sg_name] == output_sg ? x[:escalations] : nil }.compact.first || 0
+        end
+        lines << "#{input_sg},#{escalations.join(',')}"
+      end
+      lines.join("\n")
+    end
+
+
+    private
+      def normalize_probabilities(probability_vector)
+        # calculate total escalations
+        total_escalations = probability_vector.inject(0) { |sum,el| sum += el[:escalations] }
+
+        # probability values are cumulative
+        cumulative_escalations = 0
+        probability_vector.each do |el|
+          cumulative_escalations += el[:escalations]
+          el[:probability] = cumulative_escalations.to_f / total_escalations.to_f
+        end
+
+        # just in case...
+        probability_vector[-1][:probability] = 1.0
+      end
+  end
+end

data/lib/symian/version.rb

@@ -0,0 +1,3 @@
+module Symian
+  VERSION = '0.1.0'
+end

data/lib/symian/work_shift.rb

@@ -0,0 +1,158 @@
+module Symian
+  class WorkShift
+
+    def initialize(type, params={})
+      case type
+        when :predefined
+          # get workshift id
+          raise ArgumentError unless params[:id]
+          wsid = params[:id]
+
+          # retrieve predefined workshift
+          predefined_workshift = WORKSHIFT_TABLE[wsid]
+          raise ArgumentError unless predefined_workshift
+
+          # load start_time and end_time from predefined workshift
+          @start_time = predefined_workshift[:start_time]
+          @end_time   = predefined_workshift[:end_time]
+        when :custom
+          # load start_time and end_time from parameters
+          raise ArgumentError unless params[:start_time] and params[:end_time]
+          @start_time = params[:start_time]
+          @end_time   = params[:end_time]
+        when :all_day_long
+          # nothing to do
+        else
+          raise ArgumentError
+      end
+
+      # save work shift type
+      @type = type
+
+      unless @type == :all_day_long
+        # normalize start_time and end_time by transforming them from
+        # instances of (Date)Time class to integers representing the
+        # number of seconds elapsed from last midnight UTC
+        @start_time = @start_time.utc.seconds_since_midnight.round
+        @end_time   = @end_time.utc.seconds_since_midnight.round
+      end
+
+      # check if it is an overnight work shift
+      @overnight = (@type == :all_day_long ? false : @end_time < @start_time)
+    end
+
+
+    def active_at?(time)
+      return true if @type == :all_day_long
+
+      t = time.utc.seconds_since_midnight.round
+      if @overnight
+        t <= @end_time or t >= @start_time
+      else
+        @start_time <= t and t <= @end_time
+      end
+    end
+
+
+    def secs_to_end_of_shift(time)
+      raise 'secs_to_end_of_shift called for unavailable operator' unless active_at?(time)
+      return Infinity if @type == :all_day_long
+
+      t = time.utc.seconds_since_midnight.round
+      res = if @overnight
+        if t <= @end_time
+          @end_time - t
+        elsif t >= @start_time
+          @end_time + 1.day - t
+        else
+          # TODO: else raise error
+          raise 'Weird error in secs_to_end_of_shift!'
+        end
+      else
+        # TODO: raise error if t < @start_time or t > @end_time
+        raise 'Weirder error in secs_to_end_of_shift!' if t < @start_time or t > @end_time
+        @end_time - t
+      end
+
+      # need to convert to integer
+      res.round
+    end
+
+
+    def secs_to_begin_of_shift(time)
+      raise 'secs_to_begin_of_shift called for available operator' if active_at?(time)
+
+      t = time.utc.seconds_since_midnight.round
+      res = if @overnight
+        # TODO: raise error if t < @end_time or t > @start_time
+        raise 'Weirder error in secs_to_begin_of_shift!' if t < @end_time or t > @start_time
+        @start_time - t
+      else
+        if t <= @start_time
+          @start_time - t
+        elsif t >= @end_time
+          @start_time + 1.day - t
+        else
+          # TODO: else raise error
+          raise 'Weird error in secs_to_begin_of_shift!'
+        end
+      end
+
+      # need to convert to integer
+      res.round
+    end
+
+
+    def duration
+      return Infinity if @type == :all_day_long
+
+      res = if @overnight
+        1.day.to_i - @start_time + @end_time
+      else
+        @end_time - @start_time
+      end
+
+      # need to convert to integer
+      res.round
+    end
+
+
+    # 24x7 work shift
+    WORKSHIFT_24x7 = WorkShift.new(:all_day_long)
+
+    # an infinitely large value
+    Infinity = 1.0/0.0
+
+    # the predefined work shift table
+    WORKSHIFT_TABLE = {
+      brt: { # UTC-3, 9AM to 5PM
+        start_time: Time.utc(2000, 'Jan', 1, 12, 0, 0),
+        end_time:   Time.utc(2000, 'Jan', 1, 20, 0, 0),
+      },
+      brst: { # UTC-2, 9AM to 5PM
+        start_time: Time.utc(2000, 'Jan', 1, 11, 0, 0),
+        end_time:   Time.utc(2000, 'Jan', 1, 19, 0, 0),
+      },
+      est: { # UTC-5, 9AM to 5PM
+        start_time: Time.utc(2000, 'Jan', 1, 14, 0, 0),
+        end_time:   Time.utc(2000, 'Jan', 1, 22, 0, 0),
+      },
+      edt: { # UTC-4, 9AM to 5PM
+        start_time: Time.utc(2000, 'Jan', 1, 13, 0, 0),
+        end_time:   Time.utc(2000, 'Jan', 1, 21, 0, 0),
+      },
+      cet: { # UTC+1, 9AM to 5PM
+        start_time: Time.utc(2000, 'Jan', 1,  8, 0, 0),
+        end_time:   Time.utc(2000, 'Jan', 1, 16, 0, 0),
+      },
+      cest: { # UTC+2, 9AM to 5PM
+        start_time: Time.utc(2000, 'Jan', 1,  7, 0, 0),
+        end_time:   Time.utc(2000, 'Jan', 1, 15, 0, 0),
+      },
+      ist: { # UTC+5:30, 9AM to 5PM
+        start_time: Time.utc(2000, 'Jan', 1,  3, 30, 0),
+        end_time:   Time.utc(2000, 'Jan', 1, 11, 30, 0),
+      },
+    }
+  end
+end

data/symian.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'symian/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'symian'
+  spec.version       = Symian::VERSION
+  spec.authors       = ['Mauro Tortonesi']
+  spec.email         = ['mauro.tortonesi@unife.it']
+  spec.description   = %q{A Decision Support Tool for the Performance Optimization of IT Support Organizations}
+  spec.summary       = %q{A support tool for strategic and business-driven decision making in the performance optimization of the IT incident management process}
+  spec.homepage      = 'https://github.com/mtortonesi/symian'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/).reject{|x| x == '.gitignore' }
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '~> 4.0.0'
+  spec.add_dependency 'awesome_print', '~> 1.2.0'
+  spec.add_dependency 'erv', '~> 0.0.2'
+  spec.add_dependency 'ice_nine', '~> 0.11.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.6.2'
+  spec.add_development_dependency 'rake', '~> 10.1.1'
+  spec.add_development_dependency 'minitest-spec-context', '~> 0.0.3'
+end