Introduction
============

A more technical introduction to the project
--------------------------------------------

The framework can can create a virtual complex network with virtual agents
that can interact with each other. This can be used for example to study
the spread of an epidemic over this simulated network and compare it
with a phenomenon in the real world. Agent-based simulation tools
generally operate on a simple topology such as grids or lattices, but
this framework goes beyond this limitation by providing support for
simulation over complex topologies (i.e. any kind of non-regularly 
connected graph). In addition, this project is not 
limited to a static network, but also takes into account temporal
networks, where processes can dynamically change the underlying network
structure over time. 

A less technical introduction to the project
--------------------------------------------

This document explains the creation of a new programming tool
for simulating complex problems. The project allows people with a
background in programming to simulate a situation, in which people,
animals, computers, or abstract agents connect to each other
arbitrarily. To give two concrete examples, it allows to simulate how a
disease spreads in an human population, and it can simulate how
connected computer servers that provide a service (such as Skype) can
suddenly fail. It does this by creating virtual agents with a
certain behaviour that are interconnected, and where behaviour and
connections can change over time.

An example output of a simple complex network simulation model
--------------------------------------------------------------

Imagine we take a social network of people, and one person has a disease. This person can now infect their friends with that disease. For this scenario we write a small model consisting of code for:

	* A network graph (e.g. a scale-free network)
	* An agent specification (e.g. spread disease on random neighbour)
	* Some output parameters (e.g. red colour for infected)
	* (optional) A network structure evolution (e.g. change links between agents)
	
then this project produces a visualisation of how the disease spreads in the network. (animated gif! - but it also produces static images)

        .. image:: figures/SIR_scale_free.gif
		   :width: 400px
		   :height: 300px	

and a plot showing the evolution of infected people:

	    .. figure:: figures/plot_SIR_scale_free.png
		   :width: 400px
		   :height: 300px   
	
The result data used for plotting and animation can of course also be used for integration in other analysis. 	


What do I mean with Complex Networks and Agent-Based Simulations?
-----------------------------------------------------------------

An **agent-based simulation** **(ABS)** is a system of multiple
autonomous agents that interact with each other. We can think of these
agents to for example represent people or animals, but they can also
represent something more abstract. In an ABS, each agent has a state
(e.g. alive or dead) and a defined behaviour (e.g. transmit a disease
when infected). The simulation then lets these agents interact with each
other, and looks at the overall change in agent states.

**Complex networks** are a type of graphs consisting of nodes and edges
like any other graph, but they tend to represent something specific
taken from the real world, such as people and friendship links, or the
topology of a P2P network. Many different systems such as power grids,
ecosystems, or the brain can be represented as a complex network.
	
What is different in this package compared to normal agent-based simulations?
-----------------------------------------------------------------------------

In basic agent-based simulations, the rules as to which agent is allowed
to interact with which other agents are very simple: Either every agent
can interact with every other agent, or agents are limited in their
interaction with their neighbouring agents, as if agents were living on
a chessboard (see e.g. for an overview of agent-based simulations).
Clearly, these rules are not a very realistic scenario, so this project
tries to address this issue by modeling the connections of the
agents as a complex network, thus **supporting *any* network
topology** underneath the simulation environment.

The main goal of this project hence was to implement a
*framework* for agent-based simulations over complex networks, i.e.
building support to run any kind of complex simulations based on a
specific network topology. A secondary goal was to then create one or
two simulation models representing a specific scenario. 

Quick links to 

:ref:`install`

:ref:`code`

