Docstrings · Fastnet.jl

Fastnet.FastNet — Type

FastNet(n,k,c,tlist;<keyword arguments>)

Create a FastNet object that represents a network structe.

Memory will be allocated for up to n nodes, up to k links. Nodes can be in one of c different states.

The argument tlist is an array or tuple of LinkType. This list tells the networks which types of links are important for you. For example in an epidemic simulation the we are particularly interested in links between infected and susceptible nodes. FastNet will do the necessary bookkeeping, to enable very fast counting, selection, etc. of the links that are in a state listed in tlist.

Note that the order of elements of tlist is not arbitrary. FastNet will think of links that match the first element of tlist as being in link state 1. The links that match the sceond type in link state 2, and so on.

WARNING: Each link in the network can only be in any one state at any time passing a tlist that contains overlapping link types (e.g. [LinkType([1,2],3),LinkType(3,1)] ) will result in an ArgumentError being thrown.

FastNet supports a number of optional keyword arguments:

nodealias : a vector of strings that will be used as names of node states in outputs
linkalias : a vector of strings that will be used as names of link states in outputs
rng : specifies a custom random number generator

The network will initially be empty (i.e. a null graph)

Examples

julia> using Fastnet

julia> FastNet(10,9,1,[])
Network of 0 nodes and 0 links

julia> FastNet(100,1000,3,[LinkType(1,2),LinkType(3,"*",1)])
Network of 0 nodes and 0 links

julia> using Random

julia> mt = MersenneTwister(1234);

julia> const S=1;

julia> const I=2;

julia> SI_link=LinkType(S,I)
Links of the form:  (1) --- (2)

julia> net=FastNet(10000,60000,2,[SI_link],nodealias=["S","I"],linkalias=["S-I"],rng=mt)
Network of 0 nodes and 0 links

Fastnet.FastSim — Type

FastSim(net,rates!,processes;<keyword arguments>)

Create a FastSim structure, representing a FastNet simulation run.

The first argument net is a FastNet structure that is be used in the simulation.

The second argument is the rates! function of the simulation. The rates function is a function that accepts two arguments. The first of these arguments is an MVector{Float64} (see StaticArrays Documentation for details). The second argument is a the current time in the simulation.

When the rates! function is called it should compute the total rates of at which the different processes occur in the system, given the current state of the network. The rates functions returns these values by filling the array that was passed as the first argument. The rates! should not have a return value.

Note that when rates are time dependent then the rates! function should use the time value passed to it rather than obtaining a time form the simulation structure. The simulation code assumes that the rates will remain constant until the next event. This should be harmless in almost all cases but can cause inaccuracy if your rates depend explicitely on time, the rates are very senstitive to time and events are rare.

The third argument is a Vector of functions that implements the processes. The processes are functions without arguments when they are called they should implement effect of the respecive process running once. Note that elemets of the process function vector should be in the same order as the corresponding rates computed by the rates! vector.

FastSim supports a number of optional keyword arguments:

saveas : A String specifying the pathname where results should be saved. If unspecified results aren't saved but can be optained using the results function.
output : a boolean variable that specifies if results should be printed on the console, by default this is true. Alternatively also an IOStream can be provided to which results should be written.
repfunc : This argument can be used to specify an alternative function to generate outputs and store results. See custimization for details.

Examples

julia> using Fastnet

julia> const Bored=1; const Excited=2;

julia> net=FastNet(1000,5000,2,[LinkType(Excited,Bored,1)]);

julia> randomgraph!(net);

julia> function rates!(rates,t)
         rates[1]=countlinks(net,1)*0.1
         rates[2]=countnodes(net,Excited)*0.2
         rates[3]=countnodes(net,Bored)*0.001
         end;

julia> function excitement_spreads()
         link=randomlink(net,1)
         nodestate!(net,linkdst(net,link),Excited)
         end;

julia> function get_bored()
         node=randomnode(net,Excited)
         nodestate!(net,node,Bored)
         end;

julia> function great_idea()
         node=randomnode(net,Bored)
         nodestate!(net,node,Excited)
         end;

julia> sim=FastSim(net,rates!,[excitement_spreads,get_bored,great_idea])
Simulation run, currently at time 0.0

Fastnet.LinkType — Type

LinkType(from,to,dir=2)

Create a LinkType structure that describes the properties of a type of link in the network.

Think of a LinkType as a set of criteria that describe a certain sort of link. The first two arguments specify the states of the nodes at the start and end of the link respectively. The third argument specified if the LinkType can either be 1 or 2, where dir=1 signifies that the link type should be interpreted as directed (unidirectional) and dir=2 signifies that it should be interpreted as undirected (bidirectional).

The state of the node at the start and end of this type of link can be specified in different ways. A value of 0 or * for from or to means that the respective node can be in any state. An integer value corresponding to a node state means that the node must be in the respective state. An Array or Tuple of Ints means that the node must be in one of the states listed.

Examples

julia> using Fastnet

julia> LinkType(3,4)
Links of the form:  (3) --- (4)

julia> LinkType(3,4,1)
Links of the form:  (3) --> (4)

julia> LinkType(3,4,2)
Links of the form:  (3) --- (4)

julia> LinkType("*",4)
Links of the form:  (any) --- (4)

julia> LinkType(4,0)
Links of the form:  (4) --- (any)

julia> LinkType((1,2),3)
Links of the form:  (1/2) --- (3)

julia> LinkType(4,[1,2],1)
Links of the form:  (4) --> (1/2)

Fastnet.adjacency! — Method

adjacency!(net,mat;S=1)

Create a network with given adjacency matrix.

The network in net is replaced with the new topology that is specified by the adjacency matrix mat. If direction of links matters note that the element mat[i,j] corresponds to the link from j to i.

Symmeric matrices will not result in parallel links, instead the link is placed in an arbitrary direction.

Note that node n in the matrix will be the node in position n in net after creation, which is not necessarily the node with ID n, if you need to find a particular node at a later time then it is best to save its id using the node(net,pos) function directly after calling adjacency!(net,mat).

If net is not large enough to accomodate the desired number of nodes or links an argument error will be thrown.

Keyword arguments are

S : The state of the nodes. All nodes will be set to this state.

Examples

julia> using Fastnet

julia> net=FastNet(1000,2000,2,[])
Network of 0 nodes and 0 links

julia> mat=[0 1 0; 1 0 1; 0 1 0]
3×3 Matrix{Int64}:
 0  1  0
 1  0  1
 0  1  0

julia> adjacency!(net,mat)
Network of 3 nodes and 2 links

Fastnet.adjacent — Method

adjacent(net,a,b)
adjacent_f(net,a,b)

Check if nodes with the id's a and b are adjacent in network net. If they are return the id a of the link connecting them. Otherwise return 0.

If multiple links connect the nodes the function will return a link in the direction a->b if such a link exists.

Calling adjacent(net,a,a) will return a self-loop on a if one exists.

The worst case performance of this function scales with the degree of node a. The fast (_f) verions sacrifice some safty checks for better performance. See basic concepts for details.

Examples

julia> using Fastnet

julia> net=FastNet(1000,2000,2,[])
Network of 0 nodes and 0 links

julia> makenodes!(net,100,1);

julia> net
Network of 100 nodes and 0 links

Fastnet.configmodel! — Method

configmodel!(net::FastNet,degreedist;<keyword arguments>)

Create a configuration model style network with prescribed degree distribution, degreedist.

The network in net is replaced with the new topology. The degree distribution is specified in terms of a vector of Float64 variables such that degreedist[k] is specifies, p<sub>k</sub>, the probability that a randomly drawn node has degree k. If the elements of degreedist add up to less than 1.0 the remaining nodes will have degree zero.

The network generation is fast and unbiased but isn't guaranteed to result in a simple graph. The algorithm will try to match the desired degree distribution as closely as possible, but small discrepancies can appear if the degree distribution would result in an odd degree sum or non integer numbers of nodes of certain degrees.

If there FastNet is not large enough to accomodate the desired number of links or nodes an argument error will be thrown.

The keyword arguments are

N : The number of nodes that will be used in the creation of the network
S : The state of the nodes. All nodes will be set to this state.

Examples

julia> using Fastnet

julia> net=FastNet(1000,2000,2,[])
Network of 0 nodes and 0 links

julia> configmodel!(net,[0.5,0.25,0.25],N=200)
Network of 200 nodes and 175 links

julia> degreedist(net)
3-element Vector{Float64}:
 0.5
 0.25
 0.25

julia> configmodel!(net,[0.5,0.25],N=200)
Network of 200 nodes and 100 links

julia> degreedist(net)
2-element Vector{Float64}:
 0.5
 0.25

Fastnet.countlinks — Method

countlinks(net)
countlinks(net,s)
countlinks_f(net)
countlinks_f(net,s)

Count the links in state s, or, if no state is provided, in the entire network.

Instead of the state s also an Array or Tuple of states can be passed. In this case the total number of nodes in all of the listed states is returned.

The links in a sincle class or the entire network are counted in constant time. For the tuples or array arguments the performance scales with the number of elements in the Tulps/Array. The fast (_f) verions sacrifice some safty checks for better performance. See basic concepts for details.

If performance is critical use this function rather than linkcounts.

See also makelink!

Examples

julia> using Fastnet

julia> net=FastNet(1000,2000,2,[])
Network of 0 nodes and 0 links

julia> n1=makenode!(net,1);

julia> n2=makenode!(net,2);

julia> makelink!(net,n1,n2);

julia> net
Network of 2 nodes and 1 links

julia> lnk=randomlink(net);

julia> destroylink!(net,lnk)

julia> net
Network of 2 nodes and 0 links

Fastnet.destroynode! — Method

destroynode!(net,nid)
destroynode_f!(net,nid)

Destroy the node with id nid in network net.

Worst-case performance of both versions of this function is O(ks*k)+O(ns) where ks is the number of tracked link states, k is the degree of the affected node and ns is the number of node states.

The fast (_f) verions sacrifice some safty checks for better performance. See basic concepts for details.

See also makelink!

Examples

julia> using Fastnet

julia> net=FastNet(1000,2000,2,[])
Network of 0 nodes and 0 links

julia> n1=makenode!(net,1);

julia> n2=makenode!(net,2);

julia> k1=makelink!(net,n1,n2);

julia> linkdst(net,k1)==n2
true

Fastnet.linkexists — Method

linkexists(net,kid)
linkexists_f(net,kid)

Return true node with id kid exists in net, false otherwise.

This function runs in constant time. The fast (_f) verions sacrifice some safty checks for better performance. See basic concepts for details.

See also makelink!

Examples

julia> using Fastnet

julia> net=FastNet(1000,2000,2,[])
Network of 0 nodes and 0 links

julia> n1=makenode!(net,1);

julia> n2=makenode!(net,1);

julia> linkexists(net,7)
false

julia> k=makelink!(net,n1,n2);

julia> linkexists(net,k)
true

Fastnet.linksrc — Method

linksrc!(net,kid)
linksrc_f!(net,kid)

Return the id of the node at the source of link kid in net.

All versions of this function run in constant time. The fast (_f) verion sacrifices some safty checks for better performance. See basic concepts for details.

See also makelink!

Examples

julia> using Fastnet

julia> net=FastNet(1000,2000,2,[])
Network of 0 nodes and 0 links

julia> n1=makenode!(net,1);

julia> n2=makenode!(net,2);

julia> k1=makelink!(net,n1,n2);

julia> linksrc(net,k1)==n1
true

Fastnet.linkstate — Method

linkstate(net,kid)
linkstate_f(net,kid)

Return the state of the link with id kid in network net.

Note that the link states are numbered in the order in which they were passed to the FastNet Constructor.

All version of this function run in constant time, but fast (_f) verion sacrifices some safty checks for better performance. See basic concepts for details.