add docs for stater tracking

Author: geraintpalmer

AUTHORS.rst

@@ -14,3 +14,4 @@ Ciw has been developed by the following contributors:
 + `Emma Aspland <https://github.com/EmmaAspland>`_
 + `Henry Wilde <https://github.com/daffidwilde>`_
 + `timlathy <https://github.com/timlathy>`_
++ `Michalis Panayides <https://github.com/11michalis11>`_

docs/Guides/deadlock.rst

@@ -48,54 +48,4 @@ Running until deadlock (using a :code:`ciw.trackers.NaiveBlocking` object)::
     >>> Q.times_to_deadlock # doctest:+SKIP
     {((0, 0),): 0.94539784..., ((1, 0),): 0.92134933..., ((2, 0),): 0.68085451..., ((3, 0),): 0.56684471..., ((3, 1),): 0.0, ((4, 0),): 0.25332344...}
 
-Here the keys correspond to states recorded by the state tracker.
-
-
-
-.. _state-trackers:
-
-How to Set a State Tracker
-==========================
-
-Ciw has the option to activate a state :code:`tracker` in order to track the state of the system as the simulation progresses towards deadlock.
-In the example above a :code:`NaiveBlocking` was used.
-The default is the basic :code:`StateTracker` which does nothing.
-The state trackers have their uses when simulating until deadlock, as a time to deadlock is recorded for every state the simulation reaches.
-
-For a list and explanation of the state trackers that Ciw currently supports see :ref:`refs-statetrackers`.
-
-Consider the M/M/2/1 queue with a feedback loop.
-The following states are expected if a NaiveBlocking Tracker is used: ((0, 0)), ((1, 0)), ((2, 0)), ((3, 0)), ((2, 1)), ((1, 2)).
-Simulating until deadlock, the :code:`times_to_deadlock` dictionary will contain a subset of these states as keys::
-
-    >>> import ciw
-    >>> N = ciw.create_network(
-    ...    arrival_distributions=[ciw.dists.Exponential(6.0)],
-    ...    service_distributions=[ciw.dists.Exponential(5.0)],
-    ...    routing=[[0.5]],
-    ...    number_of_servers=[2],
-    ...    queue_capacities=[1]
-    ... )
-
-    >>> ciw.seed(1)
-    >>> Q = ciw.Simulation(N,
-    ...     deadlock_detector=ciw.deadlock.StateDigraph(),
-    ...     tracker=ciw.trackers.NaiveBlocking()
-    ... )
-    >>> Q.simulate_until_deadlock()
-    >>> Q.times_to_deadlock # doctest:+SKIP
-    {((0, 0),): 1.3354..., ((1, 0),): 1.3113..., ((1, 2),): 0.0, ((2, 0),): 1.0708..., ((2, 1),): 0.9353..., ((3, 0),): 0.9568...}
-
-The following states are expected if a MatrixBlocking Tracker is used: ((()), (0)), ((()), (1)), ((()), (2)), ((()), (3)), (((1)), (3)), (((1, 2)), (3)).
-
-    >>> ciw.seed(1)
-    >>> Q = ciw.Simulation(N,
-    ...     deadlock_detector=ciw.deadlock.StateDigraph(),
-    ...     tracker=ciw.trackers.MatrixBlocking()
-    ... )
-    >>> Q.simulate_until_deadlock()
-    >>> Q.times_to_deadlock # doctest:+SKIP
-    {((((),),), (0,)): 1.3354..., ((((),),), (1,)): 1.3113..., ((((),),), (2,)): 1.0708..., ((((),),), (3,)): 0.9568..., ((((1,),),), (3,)): 0.9353..., ((((1, 2),),), (3,)): 0.0}
-
-Notice that in this simple case, the NaiveBlocking and MatrixBlocking trackers correspond to the same states.
-In other examples, where customers may get blocked in different orders and to different places, then the two trackers may track different system states.
+Here the keys correspond to states recorded by the state tracker. Note in order for :code:`times_to_deadlock` to be meaningful, a state tracker must be used.

docs/Guides/index.rst

@@ -19,6 +19,7 @@ Contents:
    baulking.rst
    server_schedule.rst
    dynamic_customerclasses.rst
+   state_trackers.rst
    deadlock.rst
    process_based.rst
    behaviour.rst

docs/Guides/state_trackers.rst

@@ -0,0 +1,54 @@
+.. state-trackers:
+
+===============================
+How to Track the System's State
+===============================
+
+The system's state is the configuration of individuals around the system. It can be measured in a variety of ways - for example, a state can be the number of customers waiting at each node.
+
+Ciw has the option to activate a state :code:`tracker` in order to track the state of the system as the simulation progresses through the simulation. This tracker has a number of uses: the system state's full history can be obtained, from which state probabilities can be found, and it has uses when investigating deadlock.
+
+The default is the basic :code:`StateTracker` which does nothing.
+A number of other state trackers can be implemented, which record the system's state in a number of ways. These objects inherit from the basic :code:`StateTracker` class, and so custom state trackers can also be implemented by doing this.
+For a list and explanation of the state trackers that Ciw currently supports see :ref:`refs-statetrackers`.
+
+
+Example: consider an M/M/1 queue. The :code:`SystemPopulation` tracker defines a state as the number of individuals in the system::
+
+    >>> import ciw
+    >>> N = ciw.create_network(
+    ...    arrival_distributions=[ciw.dists.Exponential(0.1)],
+    ...    service_distributions=[ciw.dists.Exponential(0.2)],
+    ...    number_of_servers=[1]
+    ... )
+
+    >>> ciw.seed(1)
+    >>> Q = ciw.Simulation(N,
+    ...     tracker=ciw.trackers.SystemPopulation()
+    ... )
+    >>> Q.simulate_until_max_time(250)
+
+Now the system's history can be viewed::
+
+    >>> Q.statetracker.history # doctest:+SKIP
+    [[0.0, 0],
+     [1.44291..., 1],
+     [10.84369..., 0],
+     [15.87259..., 1],
+     [17.34491..., 0],
+     [22.71318..., 1],
+     [25.69774..., 0],
+     ...
+    ]                                  
+
+This shows that the system was in state :code:`0` from time 0.0 to 1.44291, was in state :code:`1` from time 1.44291 to 10.84369, went back to state :code:`0` from 10.84369 to time 15.87259, and so on.
+
+From this we can obtain the proportion of time the system spend in each state::
+
+    >>> Q.statetracker.state_probabilities() # doctest:+SKIP
+    {0: 0.55425..., 1: 0.24676..., 2: 0.13140..., 3: 0.06757...}
+
+So the system was in state :code:`0` (no individuals in the system) 55.4% of the time, in state :code:`1` (one individual in the system) 24.7% of the time, state :code:`2` (two individuals in the system) 13.1% of the time, and state :code:`3` (three individuals in the system) 6.8% of the time.
+
+
+Note that different trackers represent different states in different ways, see :ref:`refs-statetrackers` for a list of implemented trackers.