Simple Cycle Flow Decomposition Python Module (Version 1.0)
Takes a flow matrix representing a closed flow network and determines the simple cycle flow decomposition consistent with Min-Ping Qian's decycling algorithm [1],[2]. This is accomplished by percolating the network from a starting node, and then logging the simple cycles encountered. More information can be found in reference [3].
- Python3
- NumPy library
- MatPlotLib library (examples only)
Download CycFlowDec.py and place it in your $PYTHONPATH. On a Unix system, this can be accomplished by the following:
mkdir ~/python_modules
Place CycFlowDec.py in ~/python_modules. Update your ~/.bashrc to include
export PYTHONPATH="~/python_modules":$PYTHONPATH.
Include from CycFlowDec import CycFlowDec in your Python script. See the definitions section and examples for specific usage hints.
Constructor of the CycFlowDec class.
F: NumPy (N x N) array. Flow matrix of the network to decycle, where N is the number of network nodes. The entry F[m,n] corresponds to the flow from node n to node m.
state: Integer. The starting node for percolation.
tol: Float. The minimum contribution tolerance to extend percolation in the network. Should be on the range [0,1]. For small networks (N < ~10) tol=0 should be fine. For larger networks, tol can be increased to accelerate percolation at the cost of maximum achievable accuracy.
Runs percolating cyclic flow decomposition on F. Stores cycles as keys in the dictionary CycFlowDec.cycles, whose items correspond to the unscaled cycle weights. Cycles are defined as tuples, where the first node is the lowest index node in the cycle.
burnin: Integer. Number of steps to equilibrate percolation.
nstep: Integer. Number of steps to log cycles. Small, even numbers are often optimal, such as 2 or 4. See ref. [3], Appendix B for a brief discussion.
Scales cycle weights to flow values in CycFlowDec.cycles using the total network flow.
Returns the mean relative error (MRE) of the decycled network flows with respect to the original network flows. Scales cycles weights to flow values with CycFlowDec.scale_cycles() if it hadn't been called previously.
tol: Float. Minimum flow tolerance for edges to contribute to the MRE calculation.
See Examples folder. Examples require matplotlib. Execute with python <example.py>. Three node and seven node examples should complete instantly; the 64 node example requires around 5 minutes. The 64 node example is a Markov state model network instance of a Cl-/H+ antiporter [4].
[1] Minping, Qian, and Qian Min. "Circulation for recurrent Markov chains." Zeitschrift für Wahrscheinlichkeitstheorie und Verwandte Gebiete 59.2 (1982): 203-210.
[2] Kalpazidou, Sophia L. Cycle representations of Markov processes. Vol. 28. Springer Science & Business Media, 2007.
[3] Bernardi, Austen, and Swanson, Jessica M.J. "CycFlowDec: A Python module for decomposing flow networks using simple cycles." SoftwareX 14 (2021).
[4] Mayes, Heather B., et al. "Multiscale kinetic modeling reveals an ensemble of Cl–/H+ exchange pathways in ClC-ec1 antiporter." Journal of the American Chemical Society 140.5 (2018): 1793-1804.