about

Flowgen generates flowcharts from annotated C++ source code.

The challenge   Modern high-performance computing often involves fairly complex algorithms written in C++. This complexity comes, roughly speaking, from the difference between two aspects: the high-level (abstract) design on one hand, and the details of the specific code implementation on the other. Moreover, the high-level design is not always easily understood from the implementation. The intricate mixture of the two aspects creates an understanding gap between different (groups of) developers with different expertise, hampering their collaboration on a given code. Code developers would thus like to disentangle the two. Software documentation for developers does not however offer a human-understandable, high-level overview of what the code actually does. It also fails to keep this overview up to date with the code. Good coding standards and strategies such as code modularity or incremental development surely aid collaborative work, but cannot substitute for a higher-level view. Providing such a view in visual form is the challenge we seek to meet.

The resolution   Comments provide the building blocks for a successful resolution of this challenge. A requirement for proper comments is a part of any coding standard nowadays. In particular, most code includes (some) comments on the actions carried out in the succeeding lines. We propose using these comments, extending them with annotations that allow us to render them along with the code in a graphical manner. The tool we construct uses the annotations, along with information derived from C++ control structures, to produce a Unified Modeling Language (UML) activity diagram [wikipedia, other info] or flowchart in non-specialized language. This approach can be applied to the full set of functions in a code package, or to a subset of them, as well as to class methods (member functions). Our focus is on producing a “high-level” activity diagram, one related closely to the algorithm as designed and written by its architects and developers, rather than a “low-level” one more closely tied to source code. Existing tools generate diagrams of the latter type.

We call the tool Flowgen. It generates a set of interconnected high-level UML activity diagrams, one for each annotated function or method in the C++ sources. Flowgen’s approach is independent of any particular programming paradigm [info]. Its approach is modeled on that of Doxygen, the de facto standard tool for generating documentation from annotated C++ sources. It binds source code and activity diagrams together, so that it is easier to maintain consistency between the two. It provides behavioral diagrams, which complement Doxygen’s structural information. We are currently applying Flowgen to the VINCIA code, a plug-in to the high-energy physics event generator PYTHIA 8, used to simulate proton-proton collisions at CERN’s Large Hadron Collider. We believe it will be useful in a broad range of computing codes. (Downloads from GitHub)

In this website we present the annotations grammar (INPUT) and the resulting flowcharts (OUTPUT) that are generated with Flowgen.
The specifications for the annotations grammar may be written as well in the Extended Backus-Naur Form, EBNF format. Download the current file from this link [To be revised]. In order to visualize conveniently the EBNF format, one can use the software EBNF Visualizer.

If you use Flowgen in connection with scientific research work, please refer to this publication: doi:10.1016/j.cpc.2015.05.029.

Corresponding author: