Struct net_ensembles::sw::SwEnsemble

pub struct SwEnsemble<T: Node, R> { /* private fields */ }

Implements small-world graph ensemble

• for more details look at documentation of module sw

Sampling

• for markov steps look at MarkovChain trait
• for simple sampling look at SimpleSample trait

Other

• for topology functions look at GenericGraph
• to access underlying topology or manipulate additional data look at WithGraph trait
• to use or swap the random number generator, look at HasRng trait

Minimal example

use net_ensembles::{SwEnsemble, EmptyNode};
use net_ensembles::traits::*; // I recommend always using this
use rand_pcg::Pcg64; //or whatever you want to use as rng
use net_ensembles::rand::SeedableRng; // I use this to seed my rng, but you can use whatever

let rng = Pcg64::seed_from_u64(12);

// now create small-world ensemble with 200 nodes
// and a rewiring probability of 0.3 for each edge
let sw_ensemble = SwEnsemble::<EmptyNode, Pcg64>::new(200, 0.3, rng);

Simple sampling example

use net_ensembles::{SwEnsemble, EmptyNode};
use net_ensembles::traits::*; // I recommend always using this
use rand_pcg::Pcg64; //or whatever you want to use as rng
use net_ensembles::rand::SeedableRng; // I use this to seed my rng, but you can use whatever
use std::fs::File;
use std::io::{BufWriter, Write};

let rng = Pcg64::seed_from_u64(122);

// now create small-world ensemble with 100 nodes
// and a rewiring probability of 0.3 for each edge
let mut sw_ensemble = SwEnsemble::<EmptyNode, Pcg64>::new(100, 0.3, rng);

// setup file for writing
let f = File::create("simple_sample_sw_example.dat")
    .expect("Unable to create file");
let mut f = BufWriter::new(f);
f.write_all(b"#diameter bi_connect_max average_degree\n")
    .unwrap();

// simple sample for 10 steps
sw_ensemble.simple_sample(10,
    |ensemble|
    {
        let diameter = ensemble.graph()
            .diameter()
            .unwrap();

        let bi_connect_max = ensemble.graph()
            .clone()
            .vertex_biconnected_components(false)[0];

        let average_degree = ensemble.graph()
            .average_degree();

        write!(f, "{} {} {}\n", diameter, bi_connect_max, average_degree)
            .unwrap();
    }
);

// or just collect this into a vector to print or do whatever
let vec = sw_ensemble.simple_sample_vec(10,
    |ensemble|
    {
        let diameter = ensemble.graph()
            .diameter()
            .unwrap();

        let transitivity = ensemble.graph()
            .transitivity();
        (diameter, transitivity)
    }
);
println!("{:?}", vec);

Save and load example

• only works if feature "serde_support" is enabled
• Note: "serde_support" is enabled by default
• I need the #[cfg(feature = "serde_support")] to ensure the example does compile if you opt out of the default feature
• you can do not have to use serde_json, look here for more info

use net_ensembles::traits::*; // I recommend always using this
use serde_json;
use rand_pcg::Pcg64;
use net_ensembles::{SwEnsemble, EmptyNode, rand::SeedableRng};
use std::fs::File;

let rng = Pcg64::seed_from_u64(95);
// create small-world ensemble
let sw_ensemble = SwEnsemble::<EmptyNode, Pcg64>::new(200, 0.3, rng);

#[cfg(feature = "serde_support")]
{
    // storing the ensemble in a file:

    let sw_file = File::create("store_SW.dat")
          .expect("Unable to create file");

    // or serde_json::to_writer(sw_file, &sw_ensemble);
    serde_json::to_writer_pretty(sw_file, &sw_ensemble);

    // loading ensemble from file:

    let mut read = File::open("store_SW.dat")
        .expect("Unable to open file");

    let sw: SwEnsemble::<EmptyNode, Pcg64> = serde_json::from_reader(read).unwrap();
}

Implementations

impl<T, R> SwEnsemble<T, R>where
    T: Node + SerdeStateConform,
    R: Rng,

pub fn new(n: usize, r_prob: f64, rng: R) -> Self

Initialize

• create new SwEnsemble graph with n vertices
• r_prob is probability of rewiring for each edge
• rng is consumed and used as random number generator in the following
• internally uses SwGraph<T>::new(n)

pub fn new_with_distance(
    n: usize,
    distance: NonZeroUsize,
    r_prob: f64,
    rng: R
) -> Result<Self, GraphErrors>

Initialize

• create new SwEnsemble graph with n vertices
• r_prob is probability of rewiring for each edge
• rng is consumed and used as random number generator in the following
• internally uses SwGraph<T>::new(n)
• distance: Initial ring will be created by connecting every node to the neighbors which are not more than distance away in the ring

pub fn make_connected(&mut self)

Experimental! Connect the connected components

• resets edges, to connect the connected components
• intended as starting point for a markov chain, if you require connected graphs
• do not use this to independently (simple-) sample connected networks, as this will skew the statistics
• This is still experimental, this member might change the internal functionallity resulting in different connected networks, without prior notice
• This member might be removed in braking releases

pub fn draw_edge(&mut self) -> (usize, usize)

• draws random edge (i0, i1)
• edge rooted at i0
• uniform probability
• result dependent on order of adjecency lists
• mut because it uses the rng

pub fn r_prob(&self) -> f64

• returns rewiring probability

pub fn set_r_prob(&mut self, r_prob: f64)

• set new value for rewiring probability

Note

• will only set the value, which will be used from now on
• if you also want to create a new sample, call randomize afterwards

pub fn contained_iter_neighbors_mut(
    &mut self,
    index: usize
) -> NContainedIterMut<'_, T, SwContainer<T>, IterWrapper<'_>>

• retuns GenericGraph::contained_iter_neighbors_mut
• otherwise you would not have access to this function, since no mut access to the graph is allowed

Trait Implementations

impl<T, R> AsRef<GenericGraph<T, SwContainer<T>>> for SwEnsemble<T, R>where
    T: Node,
    R: Rng,

fn as_ref(&self) -> &SwGraph<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T, R> Borrow<GenericGraph<T, SwContainer<T>>> for SwEnsemble<T, R>where
    T: Node,
    R: Rng,

fn borrow(&self) -> &SwGraph<T>

Immutably borrows from an owned value.

impl<T: Clone + Node, R: Clone> Clone for SwEnsemble<T, R>

fn clone(&self) -> SwEnsemble<T, R>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, R> Contained<T> for SwEnsemble<T, R>where
    T: Node,

fn get_contained(&self, index: usize) -> Option<&T>

Returns a reference to the element stored in the specified node or None if out of Bounds

fn get_contained_mut(&mut self, index: usize) -> Option<&mut T>

Returns a mutable reference to the element stored in the specified node or None if out of Bounds

unsafe fn get_contained_unchecked(&self, index: usize) -> &T

For a save alternative see get_contained

unsafe fn get_contained_unchecked_mut(&mut self, index: usize) -> &mut T

Returns a mutable reference to the element stored in the specified node

impl<T: Debug + Node, R: Debug> Debug for SwEnsemble<T, R>

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

Formats the value using the given formatter.

impl<'de, T: Node, R> Deserialize<'de> for SwEnsemble<T, R>where
    T: Deserialize<'de>,
    R: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
    __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T, R> Dot for SwEnsemble<T, R>where
    T: Node,

fn dot_from_indices<F, W, S1, S2>(
    &self,
    writer: W,
    dot_options: S1,
    f: F
) -> Result<(), Error>where
    S1: AsRef<str>,
    S2: AsRef<str>,
    W: Write,
    F: FnMut(usize) -> S2,

use function f to create labels depending on the index

for valid dot_options use dot_options! macro and take a look at module dot_constants

fn dot<S, W>(&self, writer: W, dot_options: S) -> Result<(), Error>where
    S: AsRef<str>,
    W: Write,

create dot file with empty labels

default implementation uses dot_from_indices

fn dot_string<S>(&self, dot_options: S) -> Stringwhere
    S: AsRef<str>,

same as self.dot(), but returns a String instead

fn dot_string_from_indices<F, S1, S2>(&self, dot_options: S1, f: F) -> Stringwhere
    S1: AsRef<str>,
    S2: AsRef<str>,
    F: FnMut(usize) -> S2,

same as self.dot_from_indices but returns String instead

fn dot_string_with_indices<S>(&self, dot_options: S) -> Stringwhere
    S: AsRef<str>,

same as self.dot_with_indices but returns String instead

fn dot_with_indices<S, W>(&self, writer: W, dot_options: S) -> Result<(), Error>where
    S: AsRef<str>,
    W: Write,

use index as labels for the nodes

default implementation uses dot_from_indices

impl<T, R> GraphIteratorsMut<T, GenericGraph<T, SwContainer<T>>, SwContainer<T>> for SwEnsemble<T, R>where
    T: Node + SerdeStateConform,
    R: Rng,

fn contained_iter_neighbors_mut(
    &mut self,
    index: usize
) -> NContainedIterMut<'_, T, SwContainer<T>, IterWrapper<'_>>

iterate over mutable additional information of neighbors of vertex index

iterator returns &mut T

sort_adj will affect the order

panics if index out of bounds

fn contained_iter_neighbors_mut_with_index(
    &mut self,
    index: usize
) -> INContainedIterMut<'_, T, SwContainer<T>>

iterate over mutable additional information of neighbors of vertex index

iterator returns (index_neighbor: usize, neighbor: &mut T)

sort_adj will affect the order

panics if index out of bounds

fn contained_iter_mut(&mut self) -> ContainedIterMut<'_, T, SwContainer<T>>

get iterator over mutable additional information stored at each vertex in order of the indices

iterator returns a Node (for example EmptyNode or whatever you used)

impl<T, R> HasRng<R> for SwEnsemble<T, R>where
    T: Node + SerdeStateConform,
    R: Rng,

fn rng(&mut self) -> &mut R

Access RNG

If, for some reason, you want access to the internal random number generator: Here you go

fn swap_rng(&mut self, rng: &mut R)

Swap random number generator

• returns old internal rng

impl<T, R> MarkovChain<SwChangeState, SwChangeState> for SwEnsemble<T, R>where
    T: Node + SerdeStateConform,
    R: Rng,

fn m_step(&mut self) -> SwChangeState

Markov step

• use this to perform a markov step
• keep in mind, that it is not unlikely for a step to do Nothing as it works by drawing an edge and then reseting it with r_prob, else the edge is rewired
• result SwChangeState can be used to undo the step with self.undo_step(result)
• result should never be InvalidAdjecency or GError if used on a valid graph

fn undo_step(&mut self, step: &SwChangeState) -> SwChangeState

Undo a markov step

• rewires edge to old state
• Note: cannot undo InvalidAdjecency or GError, will just return InvalidAdjecency or GError respectively
• returns result of rewire

Important:

Restored graph is the same as before the random step except the order of nodes in the adjacency list might be shuffled!

fn undo_step_quiet(&mut self, step: &SwChangeState)

Undo a Monte Carlo step

• rewires edge to old state
• panics if you try to undo InvalidAdjecency or GError
• panics if rewire result (SwChangeState) is invalid (i.e. !result.is_valid())

Important:

Restored graph is the same as before the random step except the order of nodes in the adjacency list might be shuffled!

fn m_steps(&mut self, count: usize, steps: &mut Vec<S, Global>)

Markov steps

fn m_steps_quiet(&mut self, count: usize)

Markov steps without return

fn m_step_acc<Acc, AccFn>(&mut self, acc: &mut Acc, acc_fn: AccFn) -> Swhere
    AccFn: FnMut(&Self, &S, &mut Acc),

Accumulating markov step

fn m_steps_acc<Acc, AccFn>(
    &mut self,
    count: usize,
    steps: &mut Vec<S, Global>,
    acc: &mut Acc,
    acc_fn: AccFn
)where
    AccFn: FnMut(&Self, &S, &mut Acc),

Accumulating markov steps

fn m_steps_acc_quiet<Acc, AccFn>(
    &mut self,
    count: usize,
    acc: &mut Acc,
    acc_fn: AccFn
)where
    AccFn: FnMut(&Self, &S, &mut Acc),

Accumulating markov steps

fn undo_steps(&mut self, steps: &[S], res: &mut Vec<Res, Global>)

Undo markov steps

fn undo_steps_quiet(&mut self, steps: &[S])

Undo markov steps

fn steps_accepted(&mut self, _steps: &[S])

Function called whenever the steps are accepted.

fn steps_rejected(&mut self, _steps: &[S])

Function called whenever the steps are rejected.

impl<T: Node, R> Serialize for SwEnsemble<T, R>where
    T: Serialize,
    R: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>where
    __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T, R> SimpleSample for SwEnsemble<T, R>where
    T: Node + SerdeStateConform,
    R: Rng,

fn randomize(&mut self)

Randomizes the edges according to small-world model

• this is used by SwEnsemble::new to create the initial topology
• you can use this for sampling the ensemble
• runs in O(vertices)

fn simple_sample<F>(&mut self, times: usize, f: F)where
    F: FnMut(&Self),

do the following times times:

fn simple_sample_vec<F, G>(&mut self, times: usize, f: F) -> Vec<G, Global>where
    F: FnMut(&Self) -> G,

do the following times times:

impl<T, R> WithGraph<T, GenericGraph<T, SwContainer<T>>> for SwEnsemble<T, R>where
    T: Node + SerdeStateConform,
    R: Rng,

fn sort_adj(&mut self)

Sort adjecency lists

If you depend on the order of the adjecency lists, you can sort them

Performance

• internally uses pattern-defeating quicksort as long as that is the standard
• sorts an adjecency list with length d in worst-case: O(d log(d))
• is called for each adjecency list, i.e., self.vertex_count() times

fn at(&self, index: usize) -> &T

access additional information at index

fn at_mut(&mut self, index: usize) -> &mut T

mutable access to additional information at index

fn graph(&self) -> &SwGraph<T>

returns reference to the underlying topology aka, the GenericGraph

use this to call functions regarding the topology