Networks#
The DMNetwork class provides abstractions for representing general unstructured networks such as communication networks, power grid, computer networks, transportation networks, electrical circuits, graphs, and others.
Application flow#
The general flow of an application code using DMNetwork is as follows:
Create a network object.
DMNetworkCreate(MPI_Comm comm, DM *dm);
Create components and register them with the network. A “component” is specific application data at a vertex/edge of the network required for its residual evaluation. For example, components could be resistor/inductor data for circuit applications, edge weights for graph problems, or generator/transmission line data for power grids. Components are registered by calling
DMNetworkRegisterComponent(DM dm, const char *name, size_t size, PetscInt *compkey);
Here,
nameis the component name,sizeis the size of component data type, andcompkeyis an integer key that can be used for setting/getting the component at a vertex or an edge.A DMNetwork can consist of one or more physical subnetworks. When multiple physical subnetworks are used one can (optionally) provide coupling information between subnetworks which consist only of shared vertices of the physical subnetworks. The topological sizes of the network are set by calling
DMNetworkSetNumSubNetworks(DM dm, PetscInt nsubnet, PetscInt Nsubnet);
Here,
nsubnetandNsubnetare the local and global number of subnetworks.A subnetwork is added to the network by calling
DMNetworkAddSubnetwork(DM dm, const char* name, PetscInt ne, PetscInt edgelist[], PetscInt *netnum);
Here
nameis the subnetwork name,neis the number of local edges on the subnetwork, andedgelistis the connectivity for the subnetwork. The outputnetnumis the global numbering of the subnetwork in the network. Each element ofedgelistis an integer array of size2*necontaining the edge connectivity for the subnetwork.As an example, consider a network comprised of 2 subnetworks that are coupled. The topological information for the network is as follows:subnetwork 0: v0 — v1 — v2 — v3subnetwork 1: v1 — v2 — v0The two subnetworks are coupled by merging vertex 0 from subnetwork 0 with vertex 2 from subnetwork 1.Theedgelistof this network isedgelist[0] = {0,1,1,2,2,3}edgelist[1] = {1,2,2,0}The coupling is done by calling
Here
anetandbnetare the first and second subnetwork global numberings returned byDMNetworkAddSubnetwork(),nsvis the number of vertices shared by the two subnetworks,asvandbsvare the vertex indices in the subnetworkanetandbnet.The next step is to have DMNetwork create a bare layout (graph) of the network by calling
DMNetworkLayoutSetUp(DM dm);
After completing the previous steps, the network graph is set up, but no physics is associated yet. This is done by adding the components and setting the number of variables to the vertices and edges.
A component and number of variables are added to a vertex/edge by calling
DMNetworkAddComponent(DM dm, PetscInt p, PetscInt compkey, void* compdata, PetscInt nvar)
where
pis the network vertex/edge point in the range obtained by eitherDMNetworkGetVertexRange()/DMNetworkGetEdgeRange(),DMNetworkGetSubnetwork(), orDMNetworkGetSharedVertices();compkeyis the component key returned when registering the component (DMNetworkRegisterComponent());compdataholds the data for the component; andnvaris the number of variables associated to the added component at this network point. DMNetwork supports setting multiple components at a vertex/edge. At a shared vertex, DMNetwork currently requires the owner process of the vertex adds all the components and number of variables.DMNetwork currently assumes the component data to be stored in a contiguous chunk of memory. As such, it does not do any packing/unpacking before/after the component data gets distributed. Any such serialization (packing/unpacking) should be done by the application.
Set up network internal data structures.
Distribute the network (also moves components attached with vertices/edges) to multiple processors.
DMNetworkDistribute(DM dm, const char partitioner[], PetscInt overlap, DM *distDM);
Associate the
DMwith a PETSc solver:
Utility functions#
DMNetwork provides several utility functions for operations on the
network. The most commonly used functions are: obtaining iterators for
vertices/edges,
DMNetworkGetEdgeRange(DM dm, PetscInt *eStart, PetscInt *eEnd);
DMNetworkGetVertexRange(DM dm, PetscInt *vStart, PetscInt *vEnd);
checking the status of a vertex,
DMNetworkIsGhostVertex(DM dm, PetscInt p, PetscBool *isghost);
DMNetworkIsSharedVertex(DM dm, PetscInt p, PetscBool *isshared);
and retrieving local/global indices of vertex/edge component variables for inserting elements in vectors/matrices,
DMNetworkGetLocalVecOffset(DM dm, PetscInt p, PetscInt compnum, PetscInt *offset);
DMNetworkGetGlobalVecOffset(DM dm, PetscInt p, PetscInt compnum, PetscInt *offsetg).
In network applications, one frequently needs to find the supporting edges for a vertex or the connecting vertices covering an edge. These can be obtained by the following two routines.
DMNetworkGetConnectedVertices(DM dm, PetscInt edge, const PetscInt *vertices[]);
DMNetworkGetSupportingEdges(DM dm, PetscInt vertex, PetscInt *nedges, const PetscInt *edges[]).
Retrieving components and number of variables#
The components and the corresponding number of variables set at a vertex/edge can be accessed by
input compnum is the component number, output compkey is the key set by DMNetworkRegisterComponent. An example
of accessing and retrieving the components and number of variables at vertices is:
PetscInt Start,End,numcomps,key,v,compnum;
void *component;
DMNetworkGetVertexRange(dm, &Start, &End);
for (v = Start; v < End; v++) {
DMNetworkGetNumComponents(dm, v, &numcomps);
for (compnum=0; compnum < numcomps; compnum++) {
DMNetworkGetComponent(dm, v, compnum, &key, &component, &nvar);
compdata = (UserCompDataType)(component);
}
}
The above example does not explicitly use the component key. It is
used when different component types are set at different vertices. In
this case, compkey is used to differentiate the component type.