NetworCh Introduction and examples
NetworCh manuals: Getting started
NetworCh: Introduction and examples
Nicolas Bertin
October 2016
Obtaining NetworCh
The NetworCh library is maintained through the SVN server of the group. To obtain the latest version, you can use the following commands:
mkdir NetworCh.svn cd NetworCh.svn/ svn co https://micro.stanford.edu/svn/NetworCh .
The core of the NetworCh library is mainly written in Matlab and therefore does not require any installation. The Matlab functions are found in subfolder matlab/. In order to use these functions from your Matlab installation, do not forget to add the library directory to your Matlab path, or use the following command at the beginning of your scripts:
addpath(genpath('<path to NetworCh.svn>/matlab'));
A list of the main functions available in the library is provided here: NetworCh Documentation.
NetworCh basics
Network representation
A network is a collection of vertices (nodes) joined by edges (links). In NetworCh, each network/structure is represented by a list of nodes position rn and a list of links links. The first three columns of rn are reserved for the (x,y,z) spatial coordinates of each node. The two first columns of links must contain the id of nodes connected by the edges.
For example, a simple network consisting of two nodes A = (xa,ya,za) and B = (xb,yb,zb) joined by a single segment can be initialized as:
% Nodes rn = zeros(2,3); rn(1,1:3) = [xa,ya,za]; rn(2,1:3) = [xb,yb,zb]; % Links links = zeros(1,2); links(1,1:2) = [1,2];
Network visualization
A network can be plotted with function plot_structure:
plot_structure(rn,links);
Note that function plot_structure uses the spatial coordinates rn(:,1:3) to position nodes and does not rely and graph drawing algorithm to generate a planar layout of the network.
In many situations, the nodes of the network are contained in a rectangular box (e.g. the simulation box in DD or MD simulations). In NetworCh, such a volume is defined with array bounds. Array bounds specifies the bounds of the volume in the following manner: bounds = [xmin,xmax;ymin,ymax;zmin,zmax]. For example, if we assume that our structure is contained in a cubic simulation box of edge size L centered in the origin (0,0,0), it can be visualized using:
bounds = L/2*[-1,1;-1,1;-1,1]; plot_structure(rn,links,bounds);
By default, periodic boundary conditions will be applied for the visualization when argument bounds is specified in function plot_structure, such that nodes whose position lies outside the volume defined by bounds will be folded back to the volume.
Importing/Creating networks
NetworCh can generate or import networks from different sources.
Test structures
Several simple test structures are provided within the library to test its functions. Test structures are generated by using the test_structure function:
[rn,links,bounds] = test_structure(id);
where id is the index of the test structure to generate.
DD structures
When working with DD structures, the following additional data convention are used: the fourth column of the nodes position array rn(:,4) is reserved for the nodal constraint (e.g. unconstrained or pinned node), while entries links(i,3:5) and links(i,6:8) contain the components of the Burgers vector and that of the slip plane normal associated with segment i, respectively.
DDLab
The format used in NetworCh to represent networks is the same as that used in DDLab to represent dislocation nodes and segments. Therefore, DDLab dislocation structures can be directly manipulated with the library.
ParaDiS
DD structures can be imported from ParaDiS data files using function read_nodes:
[rn,links,bounds] = read_nodes(datafile);
where datafile is the path to the ParaDiS data file.
DXA analysis (Ovito)
DD structures can be imported from DXA files generated with Ovito by using the read_dxa_file function:
[rn,links,bounds] = read_dxa_file(cafilename);
where cafilename is the path to the DXA ca file.
MD structures
CGSD structures
CGSD structures can be imported using function read_cgsd
[cn,bnds,vol] = read_cgsd(filename);
where filename contains the path and name (without extension) of the CGSD data files filename.cn and filename.bnd (Note that both the positions and bonds files must have the same name, only their extension should differ).
Similarly to the other import functions, array cn contains the position of the atoms/beads, bnds contains the bonds information, and vol specifies the bounds of the simulation volume.
Networks generation
Random networks can be generated using function random_network. For instance
[rn,links] = random_network(n,P,bounds);
will generate a network of n nodes randomly positionned within bounds, and whose degree distribution (number of connections per node) is specified with array P. The algorithm to generate such a network is based on the configuration model, with the additional constraint that links must join nodes that are in the spatial vicinity of one another.
Exporting networks
Networks can be exported in standard graph formats GML and GEXF for visualization / analysis with other network tools with the following functions:
export_gml('filename.gml',rn,links);
export_gexf('filename.gexf',rn,links);
Properties can be associated with nodes or links. For instance, the weight of the links can be exported by specifying property 'EdgeWeights':
export_gml('filename.gml',rn,links,'EdgeWeights',weights);
where array weights contains the list of weight associated with each link such that size(weights,1) = size(links,1).