:class:`Dynamics`: Process dynamics over networks
=================================================

.. currentmodule:: epydemic

.. autoclass:: Dynamics
   :show-inheritance:

A :class:`Dynamics` object is an instance of `epyc.Experiment`, and
hence can be run either stand-alone or as part of a larger planned
experimental protocol. Each simulation is parameterised by a dict
providing the parameters used to condition the simulation, typically
providing event probabilities for the various events that may happen.

In stand-alone mode, a simulation is run by calling the :meth:`run`
method (inherited from `epyc.Experiment`), providing a dict of
parameters. The network dynamics then performs a single simulation
according to the following process:

* The simulation makes a copy of the prototype network it was supplied
  with at creation time or using :meth:`Dynamics.setNetworkPrototype`
* The :meth:`Dynamics.setUp` method initialises this network, typically setting
  values at each node and edge
* The :meth:`Dynamics.do` method is called to perform the simulation, returning
  a dict of experimental results
* The :meth:`Dynamics.tearDown` method is called to clean-up the simulation
  class, typically destroying the working copy of the prototype
  network

Running the experiment performs an event-based simulation where events
are drawn from two possible sources: *probabilistic* events generated
according to a user-specified discrete probability distribution
returned by :meth:`Dynamics.eventDistribution`; and *posted* events
posted by calls to :meth:`Dynamics.postEvent` and occurring at a fixed
simulation time.  :meth:`run` returns the dict of experimental results
generated by :meth:`Dynamics.do` plus other metadata.


  
Creating a dynamics class
-------------------------

.. automethod:: Dynamics.__init__


Attributes
----------

.. autoattribute:: Dynamics.TIME

.. autoattribute:: Dynamics.EVENTS

.. autoattribute:: Dynamics.DEFAULT_MAX_TIME
		   

Setting the network
-------------------

A :class:`Dynamics` object runs the process it describes over a
network. The network is treated as a prototype that is copied before
the start of each experiment, so that any manipulations or labelling
the experiment caries out are torn down before the next run.

.. automethod:: Dynamics.network

.. automethod:: Dynamics.setNetworkPrototype


Equilibrium
-----------

There are two ways of deciding whether a simulation has reached
equilibrium: by running the simulation for a fixed (long) time, or by
providing an explicit decision procedure.

.. automethod:: Dynamics.setMaximumTime

.. automethod:: Dynamics.at_equilibrium


Running the experiment
----------------------

A simulation takes the form of an `epyc` experiment which has set-up,
execution, and tear-down phases.

.. automethod:: Dynamics.setUp

.. automethod:: Dynamics.tearDown


Probabilistic events
--------------------

To fire events probabilistically, a dynamics makes use of an event
distribution provided by a sub-class.

.. automethod:: Dynamics.eventDistribution


Posted events
-------------

Posted events are fired at a fixed simulation time. Typically these
are used to provide fixed-time behaviours interspersed with
probabilistic events.

.. automethod:: Dynamics.postEvent

.. automethod:: Dynamics.pendingEvents

.. automethod:: Dynamics.runPendingEvents