shrewd 0.0.0

data/lib/shrewd/entities/event.rb

@@ -0,0 +1,56 @@
+# Event
+#
+# An Event changes the state of one or more simulation resources.
+# Each event also has one or more processes.
+#
+# e.g. When modeling a queue, an Event would exist that denotes the
+#      arrival of a new customer, thereby changing the state of the system
+#      by incrementing the queue by 1.
+#
+# Instance Variables:
+#
+# - @name               Name of the event.
+#                       e.g. @name = 'Customer Arrival'
+#
+# - @description        Description of the event.
+#                       e.g. @description = 'The arrival of a single customer
+#                                            to the queue.'
+#
+# - @processes          An array of Shrewd::Process objects that are to be
+#                       executed following this event. These processes will
+#                       schedule future events.
+#                       e.g. @processes = [ Shrewd::Process.new('Process') ]
+#
+# - @action             A proc that is called to modify system and local state.
+#                       This is the method by which events modify the system.
+#                       The system state variables are injected.
+#                       e.g. @action = Proc.new do |variables|
+#                                        variables[:queue].decrement
+#                                        variables[:employees].decrement
+#                                      end
+
+class Shrewd::Event
+  attr_accessor :name, :description, :processes, :action
+
+  # Initialize the event
+  #
+  # Input:
+  # - name            name of the event
+  # - description     description of the event (optional)
+  # - processes       processes to be executed after event
+  # - action          proc that changes the state of system variables
+  def initialize(name, description = "", processes = [], action = nil)
+    @name = name
+    @description = description
+    @processes = processes
+    @action = action
+  end
+
+  # Trigger the event's action
+  #
+  # Input:
+  # - state_variables       system state variables
+  def trigger(state_variables)
+    @action.call(state_variables) if @action
+  end
+end

data/lib/shrewd/entities/process.rb

@@ -0,0 +1,83 @@
+# Process
+#
+# A Process is triggered by an Event to schedule another Event.
+# Each Process schedules an event in a given (or randomized) period of time.
+# A Process can have conditions that determine if the associated Event
+# should be queued.
+#
+# e.g. When modeling customer arrivals to a retail store, each customer
+#      arrival Event would create a process that schedules a service Event,
+#      in which a employee would service the customer.
+#
+# Instance Variables:
+#
+# - @name             Name of the process.
+#                     e.g. @name = 'Service Customer'
+#
+# - @description      Description of the process.
+#                     e.g. @description = 'An employee servicing a customer.'
+#
+# - @event            Event that the process triggers after checking conditions.
+#                     e.g. @event = Shrewd::Event.new('Target')
+#
+# - @conditions       A proc that returns a boolean. If the result is true then
+#                     the @event is added to the event queue. The proc is
+#                     provided the system state variables.
+#                     e.g. @conditions = Proc.new do |variables|
+#                                                   if variables[:employees] > 0
+#                                                     true
+#                                                   else
+#                                                     false
+#                                                   end
+#                                                 end
+#
+# - @delay            A proc that returns a number. This number determines how
+#                     far in the future the event should be scheduled to
+#                     execute (relative to current time).
+#                     e.g. @delay = Proc.new do |variables|
+#                                     if variables[:queue] > 5
+#                                       15
+#                                     else
+#                                       10
+#                                     end
+#                                   end
+
+class Shrewd::Process
+  attr_accessor :name, :description, :event,
+                :conditions, :delay
+
+  # Initialize the Process
+  #
+  # Input:
+  # - name                name of the process
+  # - description         description of the process
+  # - event               event that this process will trigger
+  # - conditions          proc that returns bool to validate event scheduling
+  # - delay               proc that returns the time to schedule the event
+  def initialize(name, description = '', event = nil,
+                 conditions = nil, delay = nil)
+    @name = name
+    @description = description
+    @event = event
+    @conditions = conditions
+    @delay = delay
+  end
+
+  # Validate the conditions to determine if event should be scheduled
+  def validated?(state_variables)
+    if @conditions
+      @conditions.call(state_variables)
+    else
+      true
+    end
+  end
+
+  # Retrieve the calculated delay time
+  def delay_time(state_variables)
+    if @delay
+      @delay.call(state_variables)
+    else
+      0
+    end
+  end
+end

data/lib/shrewd/entities/variable.rb

@@ -0,0 +1,58 @@
+# Variable
+#
+# A Variable represents a state variable of the simulation system.
+# Each Variable has a finite quantity and can be incremented, decremented, or
+# assigned over the course of the simulation. A Variable can also have a boolean
+# value.
+#
+# e.g. For a supermarket checkout simulation, a finite Variable
+#      would be the number of cashiers.
+#
+# Instance Variables:
+# - @value            integer value of variable
+#                     e.g. @value = 5
+# - @name             name of the variable
+#                     e.g. @name = 'Queue'
+# - @description      description of the variable
+#                     e.g. @description = 'Number of customers in line.'
+
+class Shrewd::Variable
+  include Comparable
+  attr_accessor :name, :description, :value
+
+  # Initialize the variable
+  #
+  # Input:
+  # - name              name of the variable
+  # - description       description of the variable (optional)
+  # - default           default value for variable (optional)
+  def initialize(name, description = '', default = 0)
+    @value = default
+    @name = name
+    @description = description
+  end
+
+  # Increment the value of the variable
+  #
+  # Input:
+  # - amount          the amount to increment the variable (optional)
+  def increment(amount = 1)
+    @value += amount
+  end
+
+  # Decrement the value of the variable
+  #
+  # Input:
+  # - amount          the amount to decrement the variable (optional)
+  def decrement(amount = 1)
+    @value -= amount
+  end
+
+  # Compare variable value to number
+  #
+  # Input:
+  # - val        the value to be compared with
+  def <=>(val)
+    @value <=> val
+  end
+end

data/lib/shrewd/simulation.rb

@@ -0,0 +1,166 @@
+# Simulation
+#
+# A Simulation is a container for a simulation that holds the current
+# state of the system via state variables as well as holds the pending
+# and historical events of the simulation.
+#
+# A simulation can be started and stopped with a Simulation instance.
+#
+# One or multiple initial Processes must be provided to the Simulation
+# which will started at time 0.
+#
+# A Simulation can also be stepped through once stopped to observe the system
+# state changes one event at a time.
+#
+# Instance Variables:
+# - @variables          a hash of system variables whose key is the snake case
+#                       name of the provided variable, and the value is the
+#                       variable
+#
+#                       e.g. @variables = [ Shrewd::Variable.new('Queue')]
+#
+# - @initial_processes  the initial process
+#                       e.g. @initial_processes = [Shrewd::Process.new('proc')]
+#
+# - @queue              array of hashes of events to be processed and their
+#                       respective times of execution
+#                       e.g. @queue = [ { time: @clock,
+#                                         event: Shrewd::Event.new('Event') }]
+#
+# - @log                array of events and their time of execution
+#                       e.g. @log << { event: Shrewd::Event.new, time: 15 }
+#
+# - @clock              int value representing current clock time
+#                       e.g. @clock = 5
+module Shrewd
+  class Simulation
+    attr_accessor :initial_processes
+
+    # Initialize the simulation
+    #
+    # Input:
+    # - variables     hash of the initial state of simulation state variables
+    # - initial       initial process that will be triggered
+    #
+    # Return:
+    # - [Shrewd::Simulation]: new simulation instance
+    def initialize(variables = [], initial = nil)
+      @variables          = {}
+      @initial_processes  = initial
+      @queue              = []
+      @log                = []
+      @clock              = 0
+
+      # assign variables
+      variables.each do |variable|
+        name = variable.name.downcase.gsub(/\s+/,"_").to_sym
+        @variables[name] = variable
+      end
+
+      # save initial state
+      @initial_state = @variables
+    end
+
+    # Start the simulation with a default length of 1000
+    def start(length = 1000)
+      create_initial_event
+
+      while @queue.any?
+        # Set the clock
+        event = @queue.shift
+        @clock = event[:time].to_i
+        break if @clock > length
+
+        # Retrieve current event
+        current_event = event[:event]
+        current_event.trigger(@variables)
+
+        # Queue events spawned by processes
+        current_event.processes.each do |process|
+          if process.validated?(@variables)
+            process_time = process.delay_time(@variables)
+            add_to_queue({ event: process.event, time: @clock + process_time })
+          end
+        end
+
+        # Log the event
+        @log << { event: current_event, time: @clock }
+      end
+    end
+
+    # Print a log of the simulation events
+    def print_log
+      @log
+    end
+
+    # Reset the simulation
+    def reset
+      @log        = []
+      @queue      = []
+      @clock      = 0
+      @variables  = @initial_state
+    end
+
+    private
+      # Create the 'start' event of the simulation. The start event will call
+      # the initial process.
+      def create_initial_event
+        name = 'Start'
+        description = 'The first event of the simulation.'
+
+        initial_event = Shrewd::Event.new(name, description)
+        initial_event.processes = @initial_processes
+        add_to_queue({ event: initial_event, time: @count })
+      end
+
+      # Add event to queue according to time of event.
+      #
+      # Input:
+      # - event             the event/time hash to add to the queue
+      def add_to_queue(event)
+        size = @queue.size
+        return @queue << event if size == 0
+
+        # binary search
+        index = search(event, 0, @queue.size - 1)
+        if index > @queue.size - 1
+          @queue.push(event)
+        else
+          @queue.insert(index, event)
+        end
+      end
+
+      # Binary search to identify location in queue to add event, based on
+      # the time the event will be triggered.
+      #
+      # Input:
+      # - event           the event/time hash to add to the queue
+      # - lo              low index in the search
+      # - hi              high index in the search
+      def search(event, lo, hi)
+        # Low and high values
+        low_time = @queue[lo][:time]
+        high_time = @queue[hi][:time]
+
+        # Event time is higher or lower than bounds
+        return lo if low_time > event[:time]
+        return hi + 1 if high_time <= event[:time]
+        return lo if hi == lo
+
+        # Midpoint
+        midpoint = ((lo + hi) / 2).floor
+
+        # Compare event to midpoint
+        if event[:time] < @queue[midpoint][:time]
+          search(event, 0, midpoint - 1)
+        else
+          search(event, midpoint + 1, @queue.size - 1)
+        end
+      end
+  end
+end
+
+# require simulation entities
+require_relative 'entities/event'
+require_relative 'entities/process'
+require_relative 'entities/variable'

data/shrewd.gemspec

@@ -0,0 +1,14 @@
+Gem::Specification.new do |s|
+  s.name            = 'shrewd'
+  s.version         = '0.0.0'
+  s.date            = '2015-10-23'
+  s.summary         = 'A gem for event-based discrete event simulations.'
+  s.description     = 'A gem for that provides an easy interface to build ' +
+                      'and run discrete event simulations. Shrewd uses an ' +
+                      'event-based approach to designing simulations.'
+  s.authors         = 'Sherbie'
+  s.files           = `git ls-files`.split("\n")
+  s.require_path    = 'lib'
+  s.homepage        = 'http://rubygems.org/gems/shrewd'
+  s.license         = 'MIT'
+end

data/spec/integration/simple_spec.rb

@@ -0,0 +1,145 @@
+# SimpleSpec
+#
+# Simulation integrated tests through examples.
+
+require 'shrewd/simulation'
+
+describe "simulation" do
+
+  # Basic manufacturing example
+  #
+  # Uses a widget manufacturing example to test a simple simulation. Widgets
+  # will arrive into the system at a uniformly randomized time. An available
+  # machine will service each incoming widget. If there are not enough available
+  # machines at the time a widget arrives, then the widget will sit in the
+  # queue. The simulation will be run for a short amount of time, and its
+  # results verified.
+  context "manufacturing" do
+    before :all do
+      # Create system variables
+      queue = Shrewd::Variable.new('Queue')
+      machines = Shrewd::Variable.new('Machines', 'Machines', 5)
+      variables = [queue, machines]
+
+      # Create events
+      widget_arrival = Shrewd::Event.new('Widget Arrival',
+                                         'Widget arrives to manufacturer.')
+      widget_arrival.action = Proc.new do |variables|
+        variables[:queue].increment
+      end
+
+      start  = Shrewd::Event.new('Start Service', 'Start widget service')
+      start.action = Proc.new do |variables|
+        variables[:queue].decrement
+        variables[:machines].decrement
+      end
+
+      finish = Shrewd::Event.new('Finish Service', 'Finish widget service')
+      finish.action = Proc.new do |variables|
+        variables[:machines].increment
+      end
+
+      # create processes
+      arrival = Shrewd::Process.new('Arrival', 'Arrival of a Widget')
+      arrival.delay = Proc.new { |variables| 10 }
+      arrival.event = widget_arrival
+
+      start_service = Shrewd::Process.new('Start Service',
+                                          'Start Widget Service.')
+      start_service.delay = Proc.new { |variables| 0 }
+      start_service.conditions = Proc.new do |variables|
+        variables[:machines] > 0 && variables[:queue] > 0
+      end
+      start_service.event = start
+
+      service_widget = Shrewd::Process.new('Service', 'Servicing a Widget')
+      service_widget.delay = Proc.new { |variables| 15 }
+      service_widget.event = finish
+
+      # Add processes to events
+      widget_arrival.processes << arrival << start_service
+      start.processes          << service_widget
+      finish.processes         << start_service
+      initial_processes        = [ arrival ]
+
+      # Create simulation
+      @simulation = Shrewd::Simulation.new(variables, initial_processes)
+    end
+
+    it "creates a simulation" do
+      expect(@simulation).to be_an_instance_of Shrewd::Simulation
+    end
+
+    it "initializes processes" do
+      expect(@simulation.initial_processes).to be_an_instance_of Array
+      @simulation.initial_processes.each do |process|
+        expect(process).to be_an_instance_of Shrewd::Process
+      end
+    end
+
+    describe "when run" do
+      before :all do
+        @simulation_length = 1000
+        @simulation.start(@simulation_length)
+        @log = @simulation.print_log
+      end
+
+      it "does not last longer than simulation length" do
+        expect(@log.last[:time]).to be <= @simulation_length
+      end
+
+      it "has more or equal widgets starts than finishes" do
+        starts = 0
+        finishes = 0
+
+        @log.each do |entry|
+          if entry[:event].name == 'Start Service'
+            starts += 1
+          elsif entry[:event].name == 'Finish Service'
+            finishes += 1
+          end
+
+          expect(starts).to be >= finishes
+        end
+
+        expect(starts).to be > 0
+        expect(finishes).to be > 0
+        expect(starts).to be >= finishes
+      end
+
+      it "has more or equal widget arrivals than starts" do
+        starts = 0
+        arrivals = 0
+
+        @log.each do |entry|
+          if entry[:event].name == 'Start Service'
+            starts += 1
+          elsif entry[:event].name == 'Widget Arrival'
+            arrivals += 1
+          end
+
+          expect(arrivals).to be >= starts
+        end
+
+        expect(arrivals).to be > 0
+        expect(starts).to be > 0
+        expect(arrivals).to be >= starts
+      end
+
+      it "executes events in order" do
+        clock = 0
+
+        @log.each do |entry|
+          expect(entry[:time]).to be >= clock
+          clock = entry[:time]
+        end
+      end
+
+      after :all do
+        @log.each do |entry|
+          puts "time #{entry[:time]} - #{entry[:event].name}"
+        end
+      end
+    end
+  end
+end