# ----------------------------------*- Org -*----------------------------------
# Filename: README
# Description: README file for the MATLAB project of the lecture 851-0585-04G
#              Modelling and Simulating Social Systems with MATLAB.  The README
#              file is written in emacs org-mode, see http://orgmode.org/
# Author: Fabian Wermelinger
# Email: fabianw@student.ethz.ch
# Created: Mon Oct 24 22:33:58 2011 (+0200)
# Version: 
# Last-Updated: Sun Dec  4 12:36:46 2011 (+0100)
#           By: Fabian Wermelinger
#     Update #: 17
# -----------------------------------------------------------------------------
# README starts here
# -----------------------------------------------------------------------------

* Members
  | Name                | E-Mail                   | Departement |
  |---------------------+--------------------------+-------------|
  | Sebastian Heinekamp | heinekas@student.ethz.ch | DPHYS       |
  | Tileman Conring     | tconring@gmail.com       | DPHYS       |
  | Fabian Wermelinger  | fabianw@student.ethz.ch  | DMAVT       |
  |---------------------+--------------------------+-------------| 
  
* GitHub remote location
  [[git://github.com/tconring/Arabian-Spring.git]] (read only)

* Project
** Introduction
   A few months ago in some Arabian countries there were some kind of
   revolutionary movements. In some countries they were successful while in
   other countries they struggled. Our aim of this research project is to
   understand the mechanisms of the success of the Arabian spring.  We want to
   build a society based on a small world graph with, e.g. three clusters,
   where each cluster represents a country adjacent to another. These clusters
   shall be formed with individual probabilities, generating different
   homogeneity of each country as such. With the focus on one country, we want
   to analyze the spreading of opinion changes between nodes (where each node
   has an agent assigned to) in that particular cluster based on an SIR(S)
   model. Further, the propagation of the opinion formation across the clusters
   shall be investigated.  The probability of “infection” shall depend on local
   quantities such as the number of connected links to a node (clustering
   coefficient). This may result in a stronger influence of one particular node
   connected to another in the same cluster, but it may also spread across
   clusters since there will be nodes with connections to individual nodes of
   another cluster. In that case, a global quantity such as the link lengths of
   the two clusters in question may also influence the opinion spreading across
   them.  In a first simplified step, we assume that links between nodes will
   exist during all times.

** Research Plan
   Fundamental Questions:
   How does the structure p of multiple s-connected networks influence the
   spreading of opinion formation based on an SIR(S) model, where p ranges from
   0 (large-world, regular ring lattice) to 1 (disordered network, random) and
   s defines the probability that one node of a given network will be connected
   with a node of another network?
   
   Expected Results:
   Prediction of a date where a certain amount of nodes of the main network has
   a mind state to uprise against the government and how long it will take from
   there on to spread over to the other networks, depending on their structure
   p and connectivity s.  We assume that the opinion formation will be faster
   in a more random like network than it would be in a regular ring lattice.
   
** MATLAB
*** Network
    Each network is an assembly of N nodes generated with independent
    functions.  The output of these functions must be a sparse matrix S.  See
    the MATLAB help for the sparse() function in order to generate sparse
    matrices in MATLAB.

*** Agents
    If a network has N nodes, then there are N agents.  Hence, the number of
    agents is determined by the size of the sparse matrix S.  Agent information
    is stored in a structure array.  See the MATLAB help for more information
    on structures in MATLAB.  Each element (i.e. agent) in that array has
    several fields assigned to.  Suppose agent(i) is the i-th agent in the
    array of agents, then the following fields are assigned to it:

    + agent(i).state: The state variable defines the current mind state of the
      agent.  It is a either 0 or 1, where 0 means pro regime and 1 means con
      regime.
      
    + agent(i).nbr: The nbr variable is a list of integers to the j-th neighbor
      of the i-th agent.  The length of that list is the number of agents who
      know agent i, and vice versa.
      
    + agent(i).threshold: The threshold defines the willingness of an agent to
      jump over to the group of agents who are con regime.  It is a floating
      point value on the interval [0 1], where 0 means that the agent will only
      change its mind if ALL of its immediate neighbors (and higher order
      neighbors, depending on par.nbrDepth) already possess a state of 1.  On
      the otherhand, 1 means that the agent will step to the group even if ALL
      of its immediate (and higher order) neighbors still possess a state
      of 0.  An agent with threshold 1 is a very radical one and can be seen as
      an initiator of a later riot.
    
    + agent(i).citizen: The citizen variable defines one agents citizenship.
      That is, the membership to a certain cluster of the global network.  The
      variable holds an integer representing the number of the cluster where
      agent(i) is resident of.  For example, agent(i).citizen = 1 means that
      agent i is citizen of cluster 1.  A node of cluster i shall be connected
      to a node of cluster j with probability p.  Hence, the agent function
      takes a first argument p, followed by s arguments, where each of the s
      arguments is a sparse matrix S, generated with the network function.

    The structure array of agents must be generated with an independent
    function, taking the global probability p and s sparse matrices S (
    generated with the network function) as arguments.
**** Old agent properties
    + agent(i).state   The state variable defines the current mind state of the
                       agent.  It is a numeric value on the interval [0 1],
                       where 0 means pro regime and 1 means con regime.  Hence,
                       a state of 0.5 means undecided.
    + agent(i).nbr     The nbr variable is a list of integers to the j-th
                       neighbor of the i-th agent.  The length of that list is
                       the number of agents who know agent i, and vice versa.
    + agent(i).alpha   The alpha variable is a scalar between 0 and 1.  It
                       defines the influence of agent i on its neighbors j.  A
                       value of 0 means no influence, whereas 1 means very high
                       influence.  However, the influence of agent i on its
                       neighbor j can only take effect once the probability
                       beta of infection is met.  Beta defines the rate of
                       infection of the SIR(S) model and is a global value,
                       given to the solver function.  The alpha value is a
                       network dependent value.
    + agent(i).citizen The citizen variable defines one agents citizenship.
                       That is, the membership to a certain cluster of the
                       global network.  The variable holds an integer
                       representing the number of the cluster where agent(i) is
                       resident of.  For example, agent(i).citizen = 1 means
                       that agent i is citizen of cluster 1.  A node of cluster
                       i shall be connected to a node of cluster j with
                       probability p.  Hence, the agent function takes a first
                       argument p, followed by s arguments, where each of the s
                       arguments is a sparse matrix S, generated with the
                       network function.
*** Solver
    The solver function is an independent function taking an array of agents
    and a parameter structure as arguments.  It implements the SIR(S) model and
    solves (or iterates) through a given amount of time.  It generates a
    residual to track the development of the individual mind states over time.