Flockwork module¶
This module provides functions related to the flockwork temporal network model.

tacoma.flockwork.
convert_to_edge_activity_parameters
(N, P, gamma=1.0)[source]¶ Convert the FlockworkP parameters math:P and \(\gamma\) to the corresponding parameters in the edge activity model \(\rho\) and \(\omega\).
Parameters: Returns:  rho (float) – The network density.
 omega (float) – The rate with which a link is either switched on or off.

tacoma.flockwork.
convert_to_edge_activity_parameters_plus_minus
(N, P, gamma=1.0)[source]¶ Convert the FlockworkP parameters math:P and \(\gamma\) to the corresponding parameters in the edge activity model \(\omega^{+}\) and \(\omega^{}\).
Parameters: Returns:  omega_plus (float) – The rate with which inactive edges are activated.
 omega_minus (float) – The rate with which active edges are deactivated.

tacoma.flockwork.
convert_to_varying_edge_activity_parameters
(N, reconnection_rates, disconnection_rates)[source]¶ Convert the FlockworkP parameters math:alpha and \(\beta\) to the corresponding parameters in the edge activity model \(\rho\) and \(\omega\).
Parameters:  N (int) – number of nodes
 t (numpy.ndarray of float) – time points at which \(\alpha\) and :math`beta` change
 reconnection_rates (numpy.ndarray of float) – values of \(\alpha\) for the corresponding time values in
t
.  disconnection_rates (numpy.ndarray of float) – values of \(\beta\) for the corresponding time values in
t
.  tmax (float) – time at which the simulation is supposed to end.
Returns:  rho (float) – The network density.
 omega (float) – The rate with which a link is either switched on or off.

tacoma.flockwork.
degree_distribution
(N, P)[source]¶ Get the equilibrium degree distribution of a FlockworkP model given node number N and probability to reconnect P.
Parameters: Returns: Degree distribution of this configuration. The \(k\)th entry of this array is the probability that a node has degree \(k\).
Return type: numpy.ndarray

tacoma.flockwork.
degree_moment
(N, P, m)[source]¶ Get the \(m\)th moment of the degree of an FlockworkP model equilibrium configuration given node number N and probability to reconnect P.
Parameters: Returns: <k^m> – The \(m\)th moment of the degree distribution.
Return type:

tacoma.flockwork.
estimated_mean_group_size_distribution
(temporal_network)[source]¶ Compute the mean group size distribution for a temporal network under the assumption that it can be described reasonably by a flockworkP model.
Parameters: temporal_network ( edge_changes
oredge_lists
) – A temporal network.Returns: mean_distribution – The average group size distribution of the temporal network which is closer to to the _true_ group size distribution than measuring over the binned system. The result is an array of length N with its ith entry containing the mean number of groups of size m = i + 1. Return type: numpy.array

tacoma.flockwork.
flockwork_P
(N, P, t_run_total, rewiring_rate=1.0, initial_edges=None, seed=0, return_edge_changes_with_histograms=False)[source]¶ Simulate a flockwork Pmodel where the disconnection rate per node is \(\gamma\) and reconnection probability is \(P\). In order to start with an equilibrated initial state, use
tacoma.flockwork.flockwork_P_equilibrium_configuration()
or just passinitial_edges = None
to this function. The total event rate is \(N\gamma\) such that in one unit of time there’s an expected number of \(N\) events.Parameters:  N (int) – number of nodes
 P (float) – The reconnection probability. Has to be \(0\leq P\leq 1\)
 t_run_total (float) – The total run time in units of \(\gamma^{1}\).
 rewiring_rate (float, default : 1.0) – Event rate \(\gamma\) per node per unit of time.
 initial_edges (list of tuple of int, default : None) – The initial state of the network as an edge list.
If None is provided, the initial state will be taken
from an equilibrium configuration generated with
tacoma.flockwork.flockwork_P_equilibrium_configuration()
 seed (int, default : 0) – The random seed.
 return_edge_changes_with_histograms (bool, default : False) – Instead of the converted
_tacoma.edge_changes
, return the original instance of_tacoma.edge_changes_with_histograms
.
Returns: The simulated network. if return_edge_changes_with_histograms is True, returns an instance of
_tacoma.edge_changes_with_histograms
instead.Return type:

tacoma.flockwork.
flockwork_P_contact_time_distributions_for_varying_alpha_beta
(tau, N, k_initial, t, alpha, beta, tmax, sampling_points=10)[source]¶ Compute the mean group size distribution for a FlockworkP system with varying rates.
Parameters:  tau (numpy.ndarray of float) – durations for which to evaluate the probability density
 N (int) – Number of nodes
 k_initial (float) – initial mean degree
 t (numpy.ndarray of float) – time points at which \(\alpha(t)\) and \(\beta(t)\) change
 alpha (numpy.ndarray of float) – active reconnection rate associated with
the time points in
t
 beta (numpy.ndarray of float) – active disconnection rate associated with
the time points in
t
 tmax (float) – final time
 sampling_points (int, default : 10) – how many points to sample in between two time points in t
Returns:  P_tau_c (numpy.array) – Mean probability density of values at
tau
(contact duration)  P_tau_ic (numpy.array) – Mean probability density of values at
tau
(intercontact duration)

tacoma.flockwork.
flockwork_P_equilibrium_configuration
(N, P, shuffle_nodes=True, return_histogram=False, seed=0, shuffle_group_sizes=False, dist=None, use_binomial=True, construct_edges=True)[source]¶ Get an equilibrium configuration of a FlockworkP model given node number N and probability to reconnect P.
Parameters:  N (int) – Number of nodes
 P (float) – Probability to reconnect
 shuffle_nodes (bool, default : True) – Shuffle the node order in which nodes are distributed to groups. ‘True’ is recommended.
 return_group_size_histogram (bool, default : False) – Return a numpy array containing the counts of groups of size \(g\).
 seed (int, default : 0) – The random seed. RNG is initialized randomly if
seed = 0
.  shuffle_group_sizes (bool, default : False) – Shuffle the order of group sizes in which nodes are distributed to groups. ‘True’ is recommended.
 dist (np.array, default : None) – Is computed from N and P if None is provided
 use_binomial (bool, default : True) – whether to draw from a Binomial instead of a Poisson (conceptually more sound)
 construct_edgelist (bool, default : True) – if to actually construct the edgelist.
Returns:

tacoma.flockwork.
flockwork_P_equilibrium_group_size_distribution
(N, P)[source]¶ Get the equilibrium group size distribution of a FlockworkP model given node number N and probability to reconnect P.
Parameters: Returns: Group size distribution of this configuration. The mth entry of this array contains the expected number of nodes of groups of size m.
Return type: numpy.ndarray

tacoma.flockwork.
flockwork_P_group_life_time_distributions_for_varying_alpha_beta
(tau, max_group_size, N, k_initial, t, alpha, beta, tmax, min_group_size=2, sampling_points=10)[source]¶ Compute the mean group size distribution for a FlockworkP system with varying rates.
Parameters:  tau (numpy.ndarray of float) – durations for which to evaluate the probability density
 max_group_size (int) – until which group size the life time distribution should be computed
 N (int) – Number of nodes
 k_initial (float) – initial mean degree
 t (numpy.ndarray of float) – time points at which \(\alpha(t)\) and \(\beta(t)\) change
 alpha (numpy.ndarray of float) – active reconnection rate associated with
the time points in
t
 beta (numpy.ndarray of float) – active disconnection rate associated with
the time points in
t
 tmax (float) – final time
 min_group_size (int, default : 2) – min group size the life time distribution should be computed for
 sampling_points (int, default : 10) – how many points to sample in between two time points in t
Returns: P_taus – list of Mean probability density of values at
tau
(contact duration)Return type: list of numpy.ndarray

tacoma.flockwork.
flockwork_P_mean_degree_and_group_size_distribution_for_varying_alpha_beta
(N, k_initial, t, alpha, beta, tmax, sampling_points=10)[source]¶ Compute the mean group size distribution for a FlockworkP system with varying rates.
Parameters:  N (int) – Number of nodes
 k_initial (float) – initial mean degree
 t (numpy.ndarray of float) – time points at which \(\alpha(t)\) and \(\beta(t)\) change
 alpha (numpy.ndarray of float) – active reconnection rate associated with
the time points in
t
 beta (numpy.ndarray of float) – active disconnection rate associated with
the time points in
t
 tmax (float) – final time
 sampling_points (int, default : 10) – how many points to sample in between two time points in t
Returns:  P_g (numpy.array) – An array of times at which the mean degree was evaluated
 P_k (numpy.array) – An array of mean degree values corresponding to the times in t.

tacoma.flockwork.
flockwork_P_mean_degree_for_varying_alpha_beta
(N, k_initial, t, alpha, beta, tmax, sampling_points=10)[source]¶ Compute the mean group size distribution for a FlockworkP system with varying rates.
Parameters:  N (int) – Number of nodes
 k_initial (float) – initial mean degree
 t (numpy.ndarray of float) – time points at which \(\alpha(t)\) and \(\beta(t)\) change
 alpha (numpy.ndarray of float) – active reconnection rate associated with
the time points in
t
 beta (numpy.ndarray of float) – active disconnection rate associated with
the time points in
t
 tmax (float) – final time
 sampling_points (int, default : 10) – how many points to sample in between two time points in t
Returns:  t (numpy.array) – An array of times at which the mean degree was evaluated
 k (numpy.array) – An array of mean degree values corresponding to the times in t.

tacoma.flockwork.
flockwork_P_mean_degree_for_varying_rates
(flockwork_P_params, N=None)[source]¶ Compute the mean group size distribution for a FlockworkP system with varying rates.
Parameters: Returns:  t (numpy.array) – An array of times at which the mean degree was evaluated
 k (numpy.array) – An array of mean degree values corresponding to the times in t.

tacoma.flockwork.
flockwork_P_mean_group_size_distribution_from_mean_degree_distribution
(flockwork_P_params, dk, N=None)[source]¶ Compute the mean group size distribution for a FlockworkP system with varying rates from the mean degree distribution which is fitted as \(\left\langle k\right\rangle^{\alpha}\), hence this returns
\[\left\langle N_m \right\rangle = \int dk P(k) \times N_m( k/(k+1) )\]Parameters:  flockwork_P_params (
dict
) – Contains all parameters necessary for a FlockworkP simulation, especially the timedependent rewiring rate and timedependent reconnection probability  dk (float) – resolution of <k>space for the solution of the integral.
 N (int, default : None) – If given, compute everything for N nodes, where N is different from N in flockwork_P_params.
Returns: mean_distribution – An array of length N with its ith entry containing the mean number of groups of size m = i + 1.
Return type: numpy.array
 flockwork_P_params (

tacoma.flockwork.
group_size_distribution_asymptotics
(N, P, mmax=None, simple_pochhammer_approximation=True)[source]¶ Get the asymptotic equilibrium group size distribution of a FlockworkP model given node number N and probability to reconnect P.
Parameters:  N (int) – Number of nodes
 P (float) – Probability to reconnect
 mmax (int, default = None) – The maximum group size for which to calculate the asymptotics
 simple_pochhammer_approximation (bool, default = True) – Whether to use a simple first order Pochhammer approximation or the Gammafunction approximation.
Returns:  ms (numpy.ndarray) – group size vector
 dist (numpy.ndarray) – Asymptotic group size distribution

tacoma.flockwork.
mean_degree
(N, P, m)[source]¶ Get the exact theoretical mean degree \(\left< k\right>\) for a FlockworkP model.
Parameters: Returns: <k> – The mean degree.
Return type:

tacoma.flockwork.
naive_varying_rate_flockwork_simulation
(N, t, reconnection_rates, disconnection_rates, tmax)[source]¶ Do a naive simulation of a Flockwork systems where the reconnection and disconnection rate vary over time as step functions. It is called naive because the rate change will not be considered when evaluating the interevent time at time points when the rates change. I.e. at a rate change at time t, the new Flockwork model will be initiated as if the last event happened at time t. This error is neglibile if the upper bounded mean interevent time at rate changes is \(\tau=(N(\alpha_{\mathrm{min}}+\beta_{\mathrm{min}})^{1}\ll \Deltat_\mathrm{min}\) where \(\Deltat_\mathrm{min}\) is the minimal time between two rate changes.
Parameters:  N (int) – number of nodes
 t (numpy.ndarray of float) – time points at which \(\alpha\) and :math`beta` change
 reconnection_rates (numpy.ndarray of float) – values of \(\alpha\) for the corresponding time values in
t
.  disconnection_rates (numpy.ndarray of float) – values of \(\beta\) for the corresponding time values in
t
.  tmax (float) – time at which the simulation is supposed to end.
Returns: edge_changes – The simulated Flockwork instance.
Return type: