Package: pynetgen
PyNETGENA Python module for generating random network flows problem instances inDIMACS graph format, including an implementation of the NETGEN algorithm (Klingman et al. 1974).IntroductionThis 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 importingpynetgenas amodule, or from the command line by callingpynetgenas ashell script.PyNETGEN began as a Python implementation of NETGEN, a random network flows problem instance generator defined in:D. Klingman, A. Napier, and J. Stutz. NETGEN: A Program for generating large scale capacitated assignment, transportation, and minimum cost flow network problems.Management Science, 20(5):814-821, 1974.doi:10.1287/mnsc.20.5.814.This package's implementation of NETGEN is based on aC implementationof NETGEN by Norbert Schlenker (1989). The original implementation was used to generate random minimum-cost flow, maximum flow, and assignment problems, exported in DIMACS graph format.An alternate network generation algorithm is also included for generating grid-based graphs similar to those described for the test problems of: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.Network Generation AlgorithmsTwo 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. Both also have measures in place to guarantee that the resulting problem is feasible. To briefly describe each algorithm: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.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 paths that move along the rows of the network.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.UsagePyNETGEN can be installed fromPyPIvia the console command$ pip install pynetgenAfter installation, PyNETGEN can be used either by importing it as a module or through its shell script.Module UsagePyNETGEN can be imported from within Python usingimportpynetgenwhich grants access to the two main public functionsnetgen_generate()andgrid_generate(). For detailed descriptions of the algorithms see their docstrings viahelp(netgen_generate)andhelp(grid_generate). This includes brief descriptions of the network structures and a detailed lists of network parameters.Command Line UsagePyNETGEN can be run through the command line using thepynetgenshell script$ pynetgen [-h] [-v] [-q] [-f [FILE]] arg_list [arg_list ...]For basic usage instructions, access the documentation via$ pynetgen --helpFor 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$ pynetgen netgen helpor$ pynetgen grid helpDIMACS File FormatThe resulting network is output as a file inDIMACS graph format(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 letterc,p,n, orato specify what type of information it defines.In the case of a minimum-cost flows problem, the lines are formatted as follows:cindicates a comment line. The output file begins with a header made up of comment lines describing the parameters used to generate the problem.pindicates the problem definition. This follows the header and has the formatp min NODES DENSITY, where:NODESis the total number of nodes.DENSITYis the total number of arcs.nindicates a node definition. The node definitions follow the problem definition, and have the formatn ID SUPPLY, where:IDis a unique numerical index given to all nodes (starting at 1).SUPPLYis 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.aindicates an arc definition. The arc definitions follow the node definitions, and have the formata FROM TO MINCAP MAXCAP COST, where:FROMandTOare the node indices of the arc's origin and destination, respectively.MINCAPandMAXCAPare the arc's lower and upper capacity bounds, respectively.COSTis the arc's unit flow cost.The output file for a maximum-flow problem follows the same format with the following exceptions:The objective ismaxinstead ofmin.Source and sink nodes are given aSUPPLYvalue ofsort, respectively, rather than a specific number.Arc definitions omit the cost and lower capacity bound, now having the formata FROM TO MAXCAP.