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 Flockwork-P parameters math:P and \(\gamma\) to the corresponding parameters in the edge activity model \(\rho\) and \(\omega\).

Parameters:

N (int) – Number of nodes
P (float) – Probability to reconnect
gamma (float, default = 1) – Rewiring rate.

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 Flockwork-P parameters math:P and \(\gamma\) to the corresponding parameters in the edge activity model \(\omega^{+}\) and \(\omega^{-}\).

Parameters:

N (int) – Number of nodes
P (float) – Probability to reconnect
gamma (float, default = 1) – Rewiring rate.

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 Flockwork-P 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 Flockwork-P model given node number N and probability to reconnect P.

Parameters:	N (int) – Number of nodes P (float) – Probability to reconnect
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 Flockwork-P model equilibrium configuration given node number N and probability to reconnect P.

Parameters:	N (int) – Number of nodes P (float) – Probability to reconnect
Returns:	<k^m> – The \(m\)-th moment of the degree distribution.
Return type:	float

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 flockwork-P model.

Parameters:	temporal_network (`edge_changes` or `edge_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 i-th 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 P-model 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 pass initial_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.edge_changes`

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 Flockwork-P 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 (inter-contact 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 Flockwork-P 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:

list of tuple of int – edge list of equilibrium configuration
numpy.ndarray – group size counter of this configuration (only if return_group_size_histogram is True)

tacoma.flockwork.flockwork_P_equilibrium_group_size_distribution(N, P)[source]¶

Get the equilibrium group size distribution of a Flockwork-P model given node number N and probability to reconnect P.

Parameters:	N (int) – Number of nodes P (float) – Probability to reconnect
Returns:	Group size distribution of this configuration. The m-th 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 Flockwork-P 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 Flockwork-P 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 Flockwork-P 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 Flockwork-P system with varying rates.

Parameters:

flockwork_P_params (dict) – Contains all parameters necessary for a Flockwork-P simulation, especially the time-dependent rewiring rate and time-dependent reconnection probability
N (int, default : None) – If given, compute everything for N nodes, where N is different from N in flockwork_P_params.

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 Flockwork-P 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 Flockwork-P simulation, especially the time-dependent rewiring rate and time-dependent 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 i-th entry containing the mean number of groups of size m = i + 1.
Return type:	numpy.array

tacoma.flockwork.group_size_distribution_asymptotics(N, P, mmax=None, simple_pochhammer_approximation=True)[source]¶

Get the asymptotic equilibrium group size distribution of a Flockwork-P 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 Gamma-function 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 Flockwork-P model.

Parameters:	N (int) – Number of nodes P (float) – Probability to reconnect
Returns:	<k> – The mean degree.
Return type:	float

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 inter-event 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 inter-event 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:	`_tacoma.edge_changes`