Add Tutorial

Author: BenLauwens

docs/make.jl

@@ -1,14 +1,17 @@
 using Documenter
+using ResumableFunctions
 using SimJulia
 
 makedocs(
-  modules = [SimJulia],
-  clean   = true,
   format   = :html,
-  sitename = "SimJulia.jl",
+  sitename = "SimJulia",
+  authors = "Ben Lauwens",
   pages    = [
-    "Overview" => "index.md",
-    "Manual" => "manual.md",
+    "Home" => "index.md",
+    "Tutorial" => "tutorial.md",
+    "Topical Guides" => "guides/index.md",
+    "Examples" => ["Ross" => "examples/ross.md",],
+    "API" => "api.md"
   ]
 )
 

docs/src/api.md

@@ -0,0 +1 @@
+# API

docs/src/examples/ross.md

@@ -0,0 +1,89 @@
+# Ross, Simulation 5th edition:
+  
+## A repair problem
+
+### Source
+
+Ross, Simulation 5th edition, Section 7.7, p. 124-126
+
+### Description
+
+A system needs $n$ working machines to be operational. To guard against machine breakdown, additional machines are kept available as spares. Whenever a machine breaks down it is immediately replaced by a spare and is itself sent to the repair facility, which consists of a single repairperson who repairs failed machines one at a time. Once a failed machine has been repaired it becomes available as a spare to be used when the need arises. All repair times are independent random variables having the common distribution function $G$. Each time a machine is put into use the amount of time it functions before breaking down is a random variable, independent of the past, having distribution function $F$.
+
+The system is said to “crash” when a machine fails and no spares are available. Assuming that there are initially $n + s$ functional machines of which $n$ are put in use and $s$ are kept as spares, we are interested in simulating this system so as to approximate $E[T]$, where $T$ is the time at which the system crashes.
+
+### Code
+
+```jldoctest
+using Distributions
+using ResumableFunctions
+using SimJulia
+
+const RUNS = 5
+const N = 10
+const S = 3
+const SEED = 150
+const LAMBDA = 100
+const MU = 1
+
+srand(SEED)
+const F = Exponential(LAMBDA)
+const G = Exponential(MU)
+
+@resumable function machine(sim::Simulation, repair_facility::Resource, spares::Store{Process})
+    while true
+        try
+            @yield Timeout(sim, Inf)
+        catch exc
+        end
+        @yield Timeout(sim, rand(F))
+        get_spare = Get(spares)
+        @yield get_spare | Timeout(sim, 0.0)
+        state(get_spare) != SimJulia.idle ? interrupt(value(get_spare)) : throw(SimJulia.StopSimulation("No more spares!"))
+        @yield Request(repair_facility)
+        @yield Timeout(sim, rand(G))
+        @yield Release(repair_facility)
+        @yield Put(spares, active_process(sim))
+    end
+end
+
+@resumable function start_sim(sim::Simulation, repair_facility::Resource, spares::Store{Process})
+    procs = Process[]
+    for i=1:N
+        push!(procs, @process machine(sim, repair_facility, spares))
+    end
+    @yield Timeout(sim, 0.0)
+    for proc in procs
+        interrupt(proc)
+    end
+    for i=1:S
+        @yield Put(spares, @process machine(sim, repair_facility, spares))
+    end
+end
+
+function sim_repair()
+    sim = Simulation()
+    repair_facility = Resource(sim)
+    spares = Store{Process}(sim)
+    @process start_sim(sim, repair_facility, spares)
+    msg = run(sim)
+    stop_time = now(sim)
+    println("At time $stop_time: $msg")
+    stop_time
+end
+
+results = Float64[]
+for i=1:RUNS
+    push!(results, sim_repair())
+end
+println("Average crash time: ", sum(results)/RUNS)
+
+# output
+
+At time 5573.772841846017: No more spares!
+At time 1438.0294516073466: No more spares!
+At time 7077.413276961621: No more spares!
+At time 7286.490682742159: No more spares!
+At time 6820.788098062124: No more spares!
+Average crash time: 5639.298870243853
+```

docs/src/guides/index.md

@@ -0,0 +1 @@
+# Topical Guides

docs/src/index.md

@@ -1,3 +1,55 @@
 # Overview
 
-SimJulia is a discrete-event process-oriented simulation framework written in [Julia](http://julialang.org/) inspired by the Python library [SimPy](https://simpy.readthedocs.io/). Its preferred process dispatcher is based on semi-coroutines scheduling as implemented in [ResumableFunctions](git@github.com:BenLauwens/ResumableFunctions.jl.git). A `Process` in SimJulia is defined by a `@resumable function` yielding `Events`. SimJulia also provides three types of shared resources to model limited capacity congestion points: `Resources`, `Containers` and `Stores`. The API is modeled after the SimPy API but using some specific Julia semantics.
+SimJulia is a discrete-event process-oriented simulation framework written in [Julia](http://julialang.org/) inspired by the Python library [SimPy](https://simpy.readthedocs.io/). Its process dispatcher is based on semi-coroutines scheduling as implemented in [ResumableFunctions](https://github.com/BenLauwens/ResumableFunctions.jl.git). A `Process` in SimJulia is defined by a `@resumable function` yielding `Events`. SimJulia provides three types of shared resources to model limited capacity congestion points: `Resources`, `Containers` and `Stores`. The API is modeled after the SimPy API but some specific Julia semantics are used.
+
+The documentation contains a tutorial, topical guides explaining key concepts, a number of examples and the API reference. The tutorial, the topical guides and some examples are borrowed from the SimPy to allow a direct comparison and an easy migration path for users. The differences between SimJulia and SimPy are clearly documented.
+
+## Example
+
+A short example simulating two clocks ticking in different time intervals looks like this:
+
+```jldoctest
+julia> using ResumableFunctions
+
+julia> using SimJulia
+
+julia> @resumable function clock(sim::Simulation, name::String, tick::Float64)
+         while true
+           println(name, " ", now(sim))
+           @yield Timeout(sim, tick)
+         end
+       end
+clock (generic function with 1 method)
+
+julia> sim = Simulation()
+SimJulia.Simulation(0.0, DataStructures.PriorityQueue{SimJulia.BaseEvent,SimJulia.EventKey,Base.Order.ForwardOrdering}(), 0x0000000000000000, 0x0000000000000000, Nullable{SimJulia.AbstractProcess}())
+
+julia> @process clock(sim, "fast", 0.5)
+SimJulia.Process 1
+
+julia> @process clock(sim, "slow", 1.0)
+SimJulia.Process 3
+
+julia> run(sim, 2)
+fast 0.0
+slow 0.0
+fast 0.5
+slow 1.0
+fast 1.0
+fast 1.5
+```
+
+## Installation
+
+SimJulia is a registered package and can be installed by running:
+```julia
+Pkg.add("SimJulia")
+```
+
+## Authors
+
+* Ben Lauwens, Royal Military Academy, Brussels, Belgium.
+
+## License
+
+SimJulia is licensed under the MIT "Expat" License.