You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A Python module for generating random network flows problem instances in [DIMACS graph format](http://dimacs.rutgers.edu/archive/Challenges/), including an implementation of the NETGEN algorithm ([Klingman et al. 1974](https://doi.org/10.1287/mnsc.20.5.814)).
5
+
A Python module for generating random network flows problem instances in [DIMACS graph format](#dimacs-file-format), including an implementation of the NETGEN algorithm ([Klingman et al. 1974](https://doi.org/10.1287/mnsc.20.5.814)).
6
6
7
7
## Introduction
8
8
9
-
This package defines a variety of scripts for generating random instances of network flows problems subject to tuneable parameters. This can be accomplished within Python by importing `pynetgen` as a module, or from the command line by calling `pynetgen` as a shell script.
9
+
This package defines a variety of scripts for generating random instances of network flows problems subject to tuneable parameters. This can be accomplished within Python by importing `pynetgen` as a [module](#module-usage), or from the command line by calling `pynetgen` as a [shell script](#command-line-usage).
10
10
11
11
PyNETGEN began as a Python implementation of NETGEN, a random network flows problem instance generator defined in:
12
12
@@ -18,6 +18,69 @@ An alternate network generation algorithm is also included for generating grid-b
18
18
19
19
> S. Sadeghi, A. Seifi, and E. Azizi. Trilevel shortest path network interdiction with partial fortification. _Computers & Industrial Engineering_, 106:400-411, 2017. [doi:10.1016/j.cie.2017.02.006](https://doi.org/10.1016/j.cie.2017.02.006).
20
20
21
+
## Network Generation Algorithms
22
+
23
+
Two different random network generation algorithms are defined. Both are capable of generating minimum-cost network flows problems according to a set of tuneable parameters that control things like the size of the network and the acceptable ranges of arc costs and capacities, and both have measures in place to guarantee that the resulting problem is feasible. To briefly describe each algorithm:
24
+
25
+
* The NETGEN algorithm (`netgen_generate`) begins by defining source and sink nodes and randomly distributing supply among them. It then generates a set of "skeleton arcs" to create paths from the sources to the sinks. Skeleton arcs are guaranteed to have enough capacity to carry all required flow, ensuring that the problem instance is feasible, but they can also be specified to have maximum cost in order to discourage uninteresting solutions that utilize only skeleton arcs. After the skeleton is defined, arcs are randomly generated between pairs of randomly-selected nodes until the desired density is reached.
26
+
* The grid-based algorithm (`grid_generate`) defines a rectangular array of nodes with a specified number of columns and rows. A single master source is placed on one side, and a master sink is placed on the other. Arcs are generated in a square (or square with diagonal) grid pattern, and can be specified to be directed either strictly from the source side to the sink side or in both directions. The "skeleton arcs" consist of the first row of the grid, which is guaranteed to have enough capacity to carry all required flow, but at high cost.
27
+
28
+
By default both algorithms produce a minimum-cost flow problem instance. If the minimum and maximum arc costs are both set to exactly 1, and if the number of sources does not equal the total supply (easily achieved by setting the supply to 0), then a maximum flow problem is generated instead.
29
+
30
+
## Usage
31
+
32
+
PyNETGEN can be installed from [PyPI](https://pypi.org/project/pynetgen) via the console command
33
+
```
34
+
$ pip install pynetgen
35
+
```
36
+
37
+
After installation, PyNETGEN can be used either by importing it as a module or through its shell script.
38
+
39
+
### Module Usage
40
+
41
+
PyNETGEN can be imported from within Python using
42
+
```python
43
+
import pynetgen
44
+
```
45
+
which grants access to the two main public functions `netgen_generate()` and `grid_generate()`. For detailed descriptions of the algorithms see their docstrings via `help(netgen_generate)` and `help(grid_generate)`. This includes brief descriptions of the network structures and a detailed lists of network parameters.
46
+
47
+
### Command Line Usage
48
+
49
+
PyNETGEN can be run through the command line using the `pynetgen` shell script
For basic usage instructions, access the documentation via
54
+
```
55
+
$ pynetgen --help
56
+
```
57
+
For detailed instructions for the NETGEN and grid-based algorithms, including a brief description of the network's structure and a detailed list of network parameters, use
58
+
```
59
+
$ pynetgen netgen help
60
+
```
61
+
or
62
+
```
63
+
$ pynetgen grid help
64
+
```
65
+
66
+
## DIMACS File Format
67
+
68
+
The resulting network is output as a file in [DIMACS graph format](http://dimacs.rutgers.edu/archive/Challenges/) (or printed to the screen, in case no file path is given). To give a brief description of the format, a DIMACS graph file is a pure text file in which every line begins with either the letter `c`, `p`, `n`, or `a` to specify what type of information it defines. In the case of a minimum-cost flows problem:
69
+
70
+
*`c` indicates a comment line. The output file begins with a header made up of comment lines describing the parameters used to generate the problem.
71
+
*`p` indicates the problem definition. This follows the header and has the format `p min NODES DENSITY`, where:
72
+
*`NODES` is the total number of nodes.
73
+
*`DENSITY` is the total number of arcs.
74
+
*`n` indicates a node definition. The node definitions follow the problem definition, and have the format `n ID SUPPLY`, where:
75
+
*`ID` is a unique numerical index given to all nodes (starting at 1).
76
+
*`SUPPLY` is the supply value of the node (positive for sources, negative for sinks). In order to save space, only nodes with nonzero supply values are included.
77
+
*`a` indicates an arc definition. The arc definitions follow the node definitions, and have the format `a FROM TO MINCAP MAXCAP COST`, where:
78
+
*`FROM` and `TO` are the node indices of the arc's origin and destination, respectively.
79
+
*`MINCAP` and `MAXCAP` are the arc's lower and upper capacity bounds, respectively.
80
+
*`COST` is the arc's unit flow cost.
81
+
82
+
The output file for a maximum-flow problem is mostly the same, except that the objective is `max` instead of `min`, and source and sink nodes are given the `SUPPLY` values `s` and `t`, respectively, rather than a specific number.
83
+
21
84
## Project Status
22
85
23
-
This is a work in progress. It currently includes only a few necessary submodules and some of the overall framework, and it is not yet release-ready.
86
+
This is a work in progress. The NETGEN algorithm is complete but mostly untested, while the grid-based algorithm has not yet been implemented.
0 commit comments