shrewd 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1fb0db5cb8f287f162dd3832976cc02b28ff950a
+  data.tar.gz: 68db1125777aa925467df4a711ea63f3207690db
+SHA512:
+  metadata.gz: 6b54c374656059836ec26c9d92f7a279f64107bbb2fe605159973b4904b6eb74a5dab34a34fb79dab68518448ee88e7c45c228846d9e06bda3a3fd1ccab669c3
+  data.tar.gz: 876aa24eb1be625b5b9a131a6c1de3fb7c533ef8669e3c08a79738144cb56ce37ec0c4e6da6b0abc914eaee23c7217f02e79d99315ee40531672431b21d4a30c

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+.DS_Store
+Gemfile.lock

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,11 @@
+# Source
+source "https://rubygems.org"
+
+# Gems defined in gemspec
+gemspec
+
+# Gems
+group :test do
+  gem 'rake'
+  gem 'rspec'
+end

data/README.md

@@ -0,0 +1,416 @@
+# Shrewd
+Shrewd is a Ruby gem that helps you build discrete event simulations
+using a event-based workflow.
+
+## Installing Shrewd
+Shrewd can be found on RubyGems at [this link](http://rubygems.org/gems/shrewd).
+Install Shrewd with RubyGems:
+
+```shell
+gem install shrewd
+```
+
+Include in your Gemfile:
+
+```ruby
+gem 'shrewd'
+```
+
+## What is a Discrete Event Simulation?
+A [discrete event simulation](https://en.wikipedia.org/wiki/Discrete_event_simulation)
+is a method of simulating a system whose state fluctuates over time.
+Discrete event simulations are known as such because, unlike continuous
+simulations, the state of the simulation is modified at discrete points in time
+rather than continuously. These simulations are used to model thousands of
+different systems, including traffic congestion, manufacturing throughput,
+aircraft wind resistance, economic policies, etc. Simulations can provide
+insights into the effects of resource scarcity and constraints in ways that
+other forms of statistical analysis cannot provide. They're also extremely fun
+to model and visualize!
+
+## How does a Discrete Event Simulation Work?
+Discrete event simulations can be modeled in a number of different ways. This
+gem uses an approach known as event-based modeling.
+
+Event-based modeling involves several core concepts: Events, Processes, and
+State Variables.
+
+**State Variables** hold the state of the simulated system. They can represent
+everything from the length of a queue for a bathroom in Disneyland, to the
+number of available taxis in New York City, to a binary value representing a
+factory in a state of downtime. The rationale for these variables and their
+underlying values ultimately represent and define the system that you are
+simulating.
+
+The state of the system is modified in a simulation by **events**. Events occur at
+discrete points in time and do two things: modify the state of the system by
+modifying system state variables and initiate processes.
+
+An example of an event might be an "arrival" event which represents a
+customer "arriving" in line a retail store. At this point in time, the state of
+the system is modified by incrementing the queue by 1.
+
+In order to trigger future events, events often initiate **processes** that schedule
+future events. A process can have boolean conditions that verify the process
+should be initiated. These might verify, for example, that there is a cashier
+able to handle a newly arrived customer. If the conditions pass, the process
+schedules a given event at a given point in the future.
+
+In the example of our "arrival" event above, an arrival event might have a
+process that it initiates after incrementing the queue to schedule a "service"
+event. If there is an available cashier, the customer will be helped
+immediately by immediately scheduling a service event, which would decrement
+the queue by 1. If there is not a cashier available, then the "service" event is
+not scheduled by the process.
+
+## Your First Simulation
+Let's put these concepts into practice. In this example, we will model a
+simple grocery store queue. For the sake of simplicity, there will be one queue
+and the person at the front of the queue will be sent to the first available
+employee (5 total), where the customer will be serviced over a period of 1 to 4
+minutes (uniformly randomly distributed). Customers will arrive to the queue
+every 0 to 5 minutes (uniformly randomly distributed).
+
+First, we'll initialize the state variables for our simulation. The state of
+this system is determined by the number of the customers in the queue and the
+number of available employees.
+
+
+```ruby
+# Create system variables
+queue = Shrewd::Variable.new('Queue', '# of customers in the queue.', 0)
+employees = Shrewd::Variable.new('Employees', '# of available employees.', 5)
+variables = [queue, employees]
+```
+
+We will then initialize the events in the simulation. The main events of the
+simulation are the arrival of customers to the queue every 0 to 5 minutes, the
+start of a customer service, and finally the end of the customer service 1 to 4
+minutes after the start.
+
+```ruby
+# Create events
+customer_arrival = Shrewd::Event.new('Customer Arrival',
+                                   'Customer arrives to grocery store.')
+customer_arrival.action = Proc.new { |vars| vars[:queue].increment }
+
+start  = Shrewd::Event.new('Start Service', 'Start customer service.')
+start.action = Proc.new do |vars|
+  vars[:queue].decrement
+  vars[:employees].decrement
+end
+
+finish = Shrewd::Event.new('Finish Service', 'Finish customer service.')
+finish.action = Proc.new { |vars| vars[:employees].increment }
+```
+
+We now define the processes for the simulation. The processes include the
+arrival process which schedules a new arrival event, a start process that
+schedules the service start event, and a service process that schedules the
+finish service event.
+
+```ruby
+# Create processes
+arrival = Shrewd::Process.new('Arrival', 'Arrival of a customer.')
+arrival.delay = Proc.new { |vars| Random.new.rand * 5 }
+arrival.event = customer_arrival
+
+start_service = Shrewd::Process.new('Start Service',
+                                    'Start customer service.')
+start_service.delay = Proc.new { |vars| 0 }
+start_service.conditions = Proc.new do |vars|
+  vars[:employees] > 0 && vars[:queue] > 0
+end
+start_service.event = start
+
+service_widget = Shrewd::Process.new('Service', 'Servicing a customer.')
+service_widget.delay = Proc.new { |vars| Random.new.rand * 3 + 1 }
+service_widget.event = finish
+```
+
+We then add these processes to the events that trigger them.
+
+```ruby
+# Add processes to events
+customer_arrival.processes << arrival << start_service
+start.processes          << service_widget
+finish.processes         << start_service
+initial_processes        = [ arrival ]
+```
+
+Finally, we can initialize and run the simulation for 10,000 minutes.
+
+```ruby
+# Create simulation
+simulation = Shrewd::Simulation.new(variables, initial_processes)
+simulation.start(10000)
+log = simulation.print_log
+log.each do |entry|
+  puts "#{entry[:time]} - #{entry[:event].name}"
+end
+```
+
+## Simulations
+`Shrewd::Simulation` is the core of the Shrewd gem. Its instances
+orchestrate simulations by providing an interface to build a discrete event
+simulation, hold the state of the simulation during runtime, manage the
+simulation during runtime, and track historical data of the simulation.
+At any time, a simulation instance can only hold the state for a single
+simulation. If you wish to run multiple concurrent simulations, you must
+instantiate multiple simulation instances.
+
+### Creating a Simulation
+You can create a simulation by initializing a simulation object with an array
+of the state variables that will be used during the simulation and an array of
+the process that should be run at the start of the simulation.
+
+```ruby
+sim_variables = [Shrewd::Variable instances...]
+initial_processes = [Shrewd::Process instances...]
+my_sim = Shrewd::Simulation.new(sim_variables, initial_processes)
+```
+
+### Modifying a Simulation
+While you cannot add or remove state variables from a simulation once created,
+you can add or remove processes by modifying the `initial_processes` attribute.
+
+```ruby
+# add an initial process
+my_sim.initial_processes << Shrewd::Process.new('New Process')
+
+# remove an initial process
+last_process = my_sim.initial_processes.pop
+```
+
+### Running a Simulation
+You can start a simulation by calling the `start` method and providing the
+length of simulation time that the simulation should run. For example, if you
+were to run your simulation for 10,000 units of time you would start the
+simulation with:
+
+```ruby
+my_sim.start(10000)
+```
+
+The default simulation length, if a time length is not provided to the `start`
+method, is 1000 time units.
+
+### Printing the Simulation Results
+You can see the results of the simulation by retrieving the simulation log.
+
+```ruby
+my_sim.print_log
+```
+
+The log will have will have an array of event hashes of the format:
+`{ event: event_object, time: event_time }`.
+
+### Resetting a Simulation
+If you wish to reset your simulation to run another instance, you can use the
+reset method.
+```ruby
+my_sim.reset
+```
+This will clear the simulation logs, reset the clock to 0, and will return the
+state variables to their initial state.
+
+## Variables
+`Shrewd::Variable` is a finite simulation state variable, which must be
+initialized before the simulation is started. State variables are modified in
+quantity by `Shrewd::Event` instances through the course of the simulation. They
+are commonly used in the conditions for `Shrewd::Process` instances, determining
+whether or not there are available resources to schedule the corresponding
+simulation event (see how Processes work in the documentation below).
+
+An example of a state variable might be the number of cashiers at a grocery
+store. Once a customer arrives, a cashier become occupied for a time to help the
+customer, thereby decreasing the number of the available cashier variables by
+one. If customers arrive and there are no available cashiers to help them, the
+customers are added to a queue. This queue would be represented by another
+state variable that is incremented as customers arrive and decremented as
+customers are served.
+
+State variables can also be parameterized so that multiple instances of a
+Variable can exist. This proves useful in, for example, a simulation of a
+manufacturing plant which processes multiple different types of products. Each
+product must under go the same events in the manufacturing system, e.g.
+assembly, washing, testing, etc. It is much cleaner and easier in the case to
+parameterize a single variable rather than create instance variables to
+represent each different product.
+
+### Creating a State Variable
+You can create a state variable by passing in the name, description, and
+initial values of the variables.
+
+```ruby
+my_var = Shrewd::Variable.new("Queue", "A queue at a grocery store.", 0)
+```
+
+Only the name is required. If a value is not specified, the state variable will
+default to 0.
+
+### Modifying a State Variable
+You can modify the name, description, and value of a state variable at any
+point before or during the simulation.
+
+```ruby
+# modify name
+my_var.name = "Employees"
+
+# modify description
+my_var.description = "Number of available employees in a grocery store."
+
+# modify value
+my_var.value = 20
+```
+
+### Incrementing a State Variable
+You can increment a state variable using the increment helper.
+
+```ruby
+# increment variable by 1
+my_var.increment
+
+# increment variable by 10
+my_var.increment(10)
+```
+
+### Decrementing a State Variable
+You can decrement a state variable using the decrement helper.
+
+```ruby
+# decrement variable by 1
+my_var.decrement
+
+# decrement variable by 10
+my_var.decrement(10)
+```
+
+### Comparing State Variables
+You can compare state variables with number values.
+
+```ruby
+if my_var > 10
+  puts "Greater than 10."
+elsif my_var == 10
+  puts "Equal to 10."
+end
+```
+
+## Events
+`Shrewd::Event` denotes an event in time during a discrete event simulation.
+Events can change the state of the system by modifying state variables.
+during simulation runtime. Events are scheduled by `Shrewd::Process` instances.
+A historical record of events for a simulation run is recorded by the
+`Shrewd::Simulation` instance. After an event changes the system state by
+modifying simulation state variables, it can execute one or many processes,
+which in turn schedules future events.
+
+### Creating an Event
+You can create an event by providing a name, description, an array of
+processes that this event will enqueue when it is triggered (after the action
+is complete), and a ruby block that defines the action the event will take
+when triggered.
+
+```ruby
+# define processes that this event will trigger
+processes = [Shrewd::Process.new("Service")]
+
+# define action that will occurr when event is triggered
+action = proc { |vars| vars[:queue].increment }
+
+# create event
+my_event = Shrewd::Event.new("Arrival", "Description", processes, action)
+```
+
+
+The name attribute is the only required attribute to create an event.
+The simulation state variables will be injected into the event action block.
+The event action block is the primary way by which you modify the state of the
+system throughout the simulation.
+
+### Modifying an Event
+The name, description, processes, and action attributes of events are all
+modifiable before and event during the simulation. It is not recommended to
+modify events during the simulation.
+
+```ruby
+# modify name
+my_event.name = "Start Service"
+
+# modify description
+my_event.description = "Start the service for a customer in the queue."
+
+# modify processes
+my_event.processes = [Shrewd::Process.new("Finish")]
+
+# modify action
+my_event.action = proc do |vars|
+  vars[:queue].decrement
+  vars[:employees].decrement
+end
+```
+
+## Processes
+`Shrewd::Process` is a process that is ultimately triggered by an event. Each
+process can have conditions that determine whether the process should carry out.
+If it passes the conditions, the process schedules one `Shrewd::Event` in a
+provided time in the future.
+
+The conditions for a process can use state variables as well as randomized
+numbers, and are defined by a Ruby block. The time in the future at which the
+corresponding event should be schedule is also defined by a ruby block. This
+allows you greater control over this time variable, allowing you to use random
+distributions or define the time conditioned on the state of the system.
+
+### Creating a Process
+You can create a process by providing the name, description, the
+`Shrewd::Event` to schedule, a ruby conditions block , and a ruby time block.
+
+The conditions block should provide a boolean return. A value of `true` means
+that the process passed the validations and can schedule the event. A value of
+`false` will prevent the process from scheduling the event. If a conditions
+block is not provided, then the process will always schedule the event.
+
+The time block should return the value of time in the future at which the
+future event should be scheduled. If not provided, the time block will default
+to 0 (event will be scheduled immediately).
+
+```ruby
+# define event that this process will enqueue
+event = Shrewd::Event.new("Start Service")
+
+# define conditions - conditions must return boolean
+conditions = proc { |vars| vars[:queue] > 0 }
+
+# define time until event is enqueued - time must return a
+time = proc { |vars| Random.new.rand > 0.5 }
+
+# create the process
+my_process = Shrewd::Process.new("Service", "Servicing a customer.", event, conditions, time)
+```
+
+The name attribute is the only required attribute to create a process. If an
+event is not provided, then no events will be queued by the process.
+
+### Modifying a Process
+You can modify the name, description, event, conditions block, and time block
+of a process at any point before or during a simulation. It is not recommended
+to modify a process during a simulation.
+
+```ruby
+# modify name
+my_process.name = "Finish"
+
+# modify description
+my_process.description = "Finishing a customer's service."
+
+# modify event
+my_process.event = Shrewd::Event.new("Finish Service")
+
+# modify conditions block
+my_process.conditions = proc { |vars| vars[:queue] > 0 }
+
+# modify time block
+my_process.time = proc { |vars| Random.new.rand < 0.1 }
+```

data/lib/shrewd.rb

@@ -0,0 +1 @@
+require 'shrewd/simulation'