Skip to main content
`Ctrl`+`K`

# 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:

1. Create a network object.

       DMNetworkCreate(MPI_Comm comm, DM *dm);

2. 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, `name` is the component name, `size` is the size of component data, and `compkey` is an integer key that can be used for setting/getting the component at a vertex or an edge.

3. A `DMNETWORK` can consist of one or more physical subnetworks. Each subnetwork has its own mathematical model. When multiple subnetworks are used one can (optionally) provide coupling information between subnetworks. That is vertices that are shared between multiple subnetworks; edges can only belong to a single subnetwork. The number of subnetwork is set by calling

       DMNetworkSetNumSubNetworks(DM dm, PetscInt nsubnet, PetscInt Nsubnet);

   Here, `nsubnet` and `Nsubnet` are the local and global number of subnetworks.

4. A subnetwork is added to the network by calling

       DMNetworkAddSubnetwork(DM dm, const char* name, PetscInt ne, PetscInt edgelist[], PetscInt *netnum);

   Here `name` is the subnetwork name, `ne` is the number of local edges on the subnetwork, and `edgelist` is the connectivity for the subnetwork. The output `netnum` is the global numbering of the subnetwork in the network. Each element of `edgelist` is an integer array of size `2*ne` containing 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 — v3
   subnetwork 1: v1 — v2 — v0
   The two subnetworks are coupled by merging vertex 0 from subnetwork 0 with vertex 2 from subnetwork 1.
   The `edgelist` of this network is
   edgelist[0] = {0,1,1,2,2,3}
   edgelist[1] = {1,2,2,0}

   The coupling is done by calling

       DMNetworkAddSharedVertices(DM dm, PetscInt anet, PetscInt bnet, PetscInt nsv, PetscInt asv[], PetscInt bsv[]);

   Here `anet` and `bnet` are the first and second subnetwork global numberings returned by `DMNetworkAddSubnetwork()`, `nsv` is the number of vertices shared by the two subnetworks, `asv` and `bsv` are the vertex indices in the subnetwork `anet` and `bnet` .

5. The next step is to have `DMNETWORK` create a bare layout (graph) of the network by calling

       DMNetworkLayoutSetUp(DM dm);

6. 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 `p` is the network vertex/edge point in the range obtained by either `DMNetworkGetVertexRange()`/`DMNetworkGetEdgeRange()`, `DMNetworkGetSubnetwork()`, or `DMNetworkGetSharedVertices()`; `compkey` is the component key returned when registering the component (`DMNetworkRegisterComponent()`); `compdata` holds the data for the component; and `nvar` is 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.

7. Set up network internal data structures.

       DMSetUp(DM dm);

8. Distribute the network (also moves components attached with vertices/edges) to multiple processors.

       DMNetworkDistribute(DM dm, const char partitioner[], PetscInt overlap, DM *distDM);

9. Associate the `DM` with a PETSc solver:

       KSPSetDM(KSP ksp, DM dm) or SNESSetDM(SNES snes, DM dm) or TSSetDM(TS ts, DM dm).

## 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);

    DMNetworkGetSubnetwork(DM dm, PetscInt netnum, PetscInt *nv, PetscInt *ne, const PetscInt **vtx, const PetscInt **edge);

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

    DMNetworkGetComponent(DM dm, PetscInt p, PetscInt compnum, PetscInt *compkey, void **component, PetscInt *nvar)

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.