Struct cnetworks::Network

pub struct Network { /* private fields */ }

Network is the main graph data structure. Internally it is represented as an adjacency list of node objects.

Implementations

impl Network

pub fn new(size: usize, model: Model, weight: Weight) -> Self

Creates a new network of given size and desired model with a random seed. Use Model::None if you want a network with no pre-established connections.

Note that this is equivalent to calling Network::with_seed() with a random alphanumeric seed of length 64.

Examples

Creating a network of chosen model and random link weight:

let net = Network::new(10, Model::ER { p: 0.4, whole: true }, Weight::Uniform);
assert!(net.is_whole());
assert_eq!(net.seed().len(), 64);
assert_eq!(net.size(), 10);
println!("{:?}", net);

Creating a network with no links and establishing them “by hand”:

let mut net = Network::new(10, Model::None, Weight::Constant { c: 0.25 });
net.link(1, 2)?;
net.link(4, 7)?;
assert!(!net.is_whole());
assert_eq!(net.get_link(1,2)?, Some(0.25));
assert_eq!(net.get_link(4,7)?, Some(0.25));
println!("{:?}", net);

pub fn with_seed(size: usize, model: Model, weight: Weight, seed: &str) -> Self

Same as Network::new(), but with a specified seed for the internal random number generator. This makes the network entirely deterministic, allowing full reproducibility between simulations.

Examples

let seed = "Boaty McBoatface";
let net1 = Network::with_seed(10, Model::ER { p: 0.75, whole: false, }, Weight::Uniform, seed);
let net2 = Network::with_seed(10, Model::ER { p: 0.75, whole: false, }, Weight::Uniform, seed);
for node in 0..9 {
assert_eq!(net1.links_of(node), net2.links_of(node));
}

pub fn size(&self) -> usize

Returns the network size, ie. the total number of nodes.

pub fn model(&self) -> &Model

Returns the Model of the network.

pub fn set_model(&mut self, name: &str)

Sets the model of the network to Model::Custom variant with the specified string.

Examples

let mut net = Network::default();
net.set_model("Custom model name!");
assert_eq!(net.model(), &Model::Custom("Custom model name!".to_string()));

pub fn weight(&self) -> &Weight

Get the type of link weight.

pub fn seed(&self) -> &str

Get the network-local rng thread seed. This is a random alphanumeric string of length 64, unless explicitly specified during construcion with Network::with_seed().

pub fn rng_lock(&self) -> TryLockResult<MutexGuard<'_, Xoshiro256Plus>>

Tries to lock the network-local rng thread from it’s Mutex. This is effectively calling Mutex::try_lock.

pub fn rng(&mut self) -> LockResult<&mut Xoshiro256Plus>

Returns the network-local rng thread from it’s Mutex, borrowing it mutably. This effectively calling Mutex::get_mut, and thus borrow-checked at compile time.

pub fn scramble_rng(&mut self)

Scrambles the built-in random number generator with a new random seed. Useful for when a cloned network needs a different RNG source.

Examples

let net = Network::default();
let mut net2 = net.clone();

assert_eq!(net.seed(), net2.seed());
assert_eq!(net.rng_lock().unwrap().next_u32(), net2.rng_lock().unwrap().next_u32());

net2.scramble_rng();
assert_ne!(net.seed(), net2.seed());
assert_ne!(net.rng_lock().unwrap().next_u32(), net2.rng_lock().unwrap().next_u32());

pub fn nodes(&self) -> impl Iter<usize> + '_

Returns iterator with the node indexes.

The iteration order is deterministic, but not stable, as it is deterministaically perturbed when removing links.

Keep in mind that it’s possible to have a network of nodes with non-sequential and non-ordered indexes, such as (0,2,3), (100, 101, 150) or (10, 0, 1) using Network::attach and Network::detach`.

pub fn links(&self) -> impl Iter<(usize, usize)> + '_

Returns iterator of links in the network as (first index, second index) pairs. This is intended mostly for explicit iteration over network links, as using Network::get_link or Network::links_of will be faster than Iterator::find and others.

The iteration order is deterministic, but not stable, as it is deterministaically perturbed when removing links.

Examples

One common use case is counting edges in the graph.

let net = Network::new(100, Model::ER { p: 0.05, whole: true }, Weight::default());
println!("Network has a total of {} links", net.links().count());

pub fn exists(&self, index: usize) -> bool

Return true if a node with specified index exists in the network.

pub fn is_whole(&self) -> bool

Returns true if the network is whole, ie. if there is only one component or if the network is empty.

pub fn deg_of(&self, node: usize) -> Result<usize>

Returns the degree of a given node, ie. the number of it’s closest neighbors.

Returns cn::Err::NoSuchNode if specified node does not exist.

pub fn links_of(&self, node: usize) -> Result<&IndexMap<usize, f64>>

Returns links of a given node as cn::IndexMap of (target, weight) pairs.

Returns cn::Err::NoSuchNode if specified node does not exist.

pub fn get_link(&self, i: usize, j: usize) -> Result<Option<f64>>

Returns the weight of the link between nodes i and j, None if such link does not exist.

Returns cn::Err::LinkToSelf if i and j are the same, cn::Err::NoSuchNode if either i or j does not exist.

pub fn size_connected(&self) -> usize

Returns the number of connected nodes in the network, ie. those for which Network::deg_of > 0.

pub fn deg_avg(&self) -> f64

Returns the arithmetical average of node degrees in the network.

pub fn deg_total(&self) -> usize

Returns the total degree of the network, ie. sum of degrees over all of the nodes.

pub fn deg_distr(&self) -> VecMap<usize>

Returns the histogram of node degrees as a cn::VecMap of (degree, occurrences) pairs.

pub fn link(&mut self, i: usize, j: usize) -> Result<Option<f64>>

Establishes a link between nodes i and j using network’s weight. Updates the link weight and returns the old value if it already exist, None otherwise.

Returns cn::Err::NoSuchNode if i and j are the same or do not exist.

pub fn link_exact(
    &mut self,
    i: usize,
    j: usize,
    weight: f64
) -> Result<Option<f64>>

Establishes a link between nodes i and j with specified weight. Updates the link weight and returns the old value if it already exist, None otherwise.

Returns cn::Err::NoSuchNode if i and j do not exist, cn::Err::LinkToSelf if they are the same, cn::Err::BadWeight the weight is not in the range (0, 1].

pub fn unlink(&mut self, i: usize, j: usize) -> Result<Option<f64>>

Unsafely removes a link between nodes i and j. Does not perform a check whether the network is still whole. Returns the weight of the removed connection or None if the connection does not exist.

Returns cn::Err::NoSuchNode if i and j do not exist and cn::Err::LinkToSelf if they are the same.

pub fn unlink_safe(&mut self, i: usize, j: usize) -> Result<Option<f64>>

Safely removes a link between nodes i and j, ensuring the network does not split. Performs a breadth-first search to check whether the network is still whole. Returns the weight of removed link, None if the link does not exist or cannot be safely removed.

Returns cn::Err::NoSuchNode if i and j do not exist and cn::Err::LinkToSelf if they are the same.

pub fn disconnect(&mut self, node: usize) -> Result<IndexMap<usize, f64>>

Unsafely disconnects a node from the network by removing all of its links. Does not check if the network is still whole. Returns the removed links as a cn::IndexMap of (target, weight) pairs.

Returns cn::Err::NoSuchNode if node does not exist.

pub fn disconnect_safe(
    &mut self,
    node: usize
) -> Result<Option<IndexMap<usize, f64>>>

Safely disconnects a node from the network by removing all of its links. Performs a breadth-first search to check whether the network is still whole. Returns the removed links as a cn::IndexMap of (target, weight) pairs or None if node cannot be safely disconnected.

Returns cn::Err::NoSuchNode if node does not exist.

pub fn disconnect_all(&mut self)

Removes ALL links in the network.

Sets the model to Model::None such that the initial linking process can be conducted again, eg. with Model::init_er, Model::init_ba or manually.

pub fn attach(&mut self, node: usize) -> Result<()>

Attaches a new node to the network. The node must be connected to the rest of the network manually, as no links will be automatically established.

Returns cn::Err::NodeExists if there already exists a node with the specified index.

Examples

let mut net = Network::default();
assert!(net.attach(2).is_ok());
assert!(net.attach(2).is_err());

pub fn attach_skip(&mut self, indexes: &[usize])

Like Network::attach, but attach many nodes skipping over the already-existing ones instead of raising an error.

pub fn detach(&mut self, node: usize) -> Result<()>

Completely removes node from the network, disconnecting it first.

Returns cn::Err::NoSuchNode if node with specified index does not exist.

Examples

let mut net = Network::default();
assert!(net.detach(2).is_err());

pub fn components(&self) -> Vec<VecSet>

Returns vector of components present in the network, ordered largest to smallest.

Examples

let net = Network::new(100, Model::ER { p: 0.05, whole: false }, Weight::default() );
let components = net.components();
println!("Largest component: {:?}", components.first().expect("No components"));
println!("Smallest component: {:?}", components.last().expect("No components"));

pub fn into_largest_component(self) -> Self

Transform the network into the largest contained component by removing all nodes not in the largest component. Leaves self unchanged if there is no largest component.

Examples

let mut net = Network::new(10, Model::None, Weight::default() );
net.link(0, 1)?;
net.link(0, 2)?;
net.link(0, 3)?;
assert_eq!(net.clone().into_largest_component().links().count(), 3);
assert_eq!(net.clone().into_largest_component().size(), 4);

pub fn stitch_together(&mut self)

Stitches the network together if it is composed of more than one component. Connects random elements from smaller components to the largest one, extending it until it covers the entire network.

Examples

let mut net = Network::new(100, Model::ER { p: 0.0001, whole: false }, Weight::default() );
assert!(!net.is_whole());
assert_ne!(net.components().len(), 1 );
net.stitch_together();
assert!(net.is_whole());
assert_eq!(net.components().len(), 1 );

Trait Implementations

impl Clone for Network

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Network

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Network

fn default() -> Self

Same as Network::new() with the following properites:

• Model::None
• Weight::default()
• Network::size() of 0

Note that by default the network is empty. Nodes must be manually attached using Network::attach() and linked using Network::link().

Examples

Creating a default network and attaching nodes manually

let mut net = Network::default();
assert!(net.is_whole()); // empty network is considered whole
for i in [1,2] {
    net.attach(i)?;
}
net.link(1,2)?;
assert_eq!(net.get_link(1,2), Ok(Some(1.0)));
assert!(net.is_whole());