#############
Description
#############

**************************************************************
Homophily-based Distance Depending Forest Fire Network Service
**************************************************************

|SHoBNetPy Logo|

SHoBNetPy (Spatial Homophily-based Network generator for ABM)
offers a network generation algorithm for agent-based models for
social simulation. It accounts for agent type (milieu)-specific degree distribution,
distance distributions and composition preferences.
Furthermore, it explicitly addresses modularity of resulting networks.

The original forest fire algorithm by Leskovec et al. (2007) is adapted and extended in 
several ways: the fulfillment of degree distributions most likely requires more than one
ambassador to connect with. To mitigate ordering effects, agents are assigned ambassadors
in a randomly pre-defined chain: the first agent is linked to its first ambassador.
Then, every other agent is linked to its first randomly chosen ambassador before the first
agent in the chain is connected to its second random ambassador.

SHoBNetPy generates links on the `networkx.Graph` object which is an component of a
`mesa.space.NetworkGrid`. Therefore, by accessing `mesa.space.NetworkGrid` teh modeller
can manipulate the network and request e.g. an agent's network partners (neighbours).

********
Features
********

The `SHoBNetworkGrid <../api/network.py>`_ seeks to incorporate important features relevant for ABM:

1. Agent type (milieu)-specific degree distributions

2. Agent type (milieu)-specific distance distributions

3. Agent type (milieu)-specific milieu composition preferences

4. Focus on modularity

|Test Network Visualisation|

*********
Algorithm
*********

|HDFF Network Generator|

Important parameters
====================

Apart from the milieu composition preferences, degree and distance
distributions, the algorithm considers two important parameters that
allow to control the resulting networks modularity quite well:

``settings.main.prob_burning_forward``
   While exploring an ambassador's neighbours this probability
   determines the likelihood that the focal agent is linked from
   ambassador's **outgoing** links.

``settings.network.prob_burning_backward``
   While exploring an ambassador's neighbours this probability
   determines the likelihood that the focal agent is linked from
   ambassador's **incoming** links. This seems especially important for
   relations of social influence.

Two more parameters are important to adjust the precision for milieu
composition and distance distribution (Note that the sum of both has to
be ``1.0``):

``settings.network.dim_weight_milieu``
   Determines the weight for milieu composition preferences when
   calculating a link's probability. The higher the value the more
   accurate milieu composition preferences can be fulfilled.

``settings.network.dim_weight_geo``
   Determines the weight for distance related link probability when
   calculating a link's probability. The higher the value the more
   accurate distance distributions can be fulfilled.

See :ref:`app_concepts_configuration_settings` for a list of all relevant parameters.


**********
Background
**********

SHoBNetPy is a port of the Homophily-based Distance Depending
Forest Fire (HDFF) network generator from the original Java library
`MoRe <https://more4abm.sourceforge.net/>`_.

The algorithm is described in more detail in [1], section 11.10.

[1] Holzhauer, S. Dynamic Social Networks in Agent-based Modelling
kassel university press, 2017, doi: 10.19211/KUP9783737602631 

.. |SHoBNetPy Logo| image:: ./shobnetpy_logo.png

.. |HDFF Network Generator| image:: ./setup_init_hdff_algo.png

.. |Test Network Visualisation| image:: ./test_network.png