mpywatch

The mpywatch tool is a command-line utility for monitoring progress and real-time plotting of data obtained from a simulation with the OpenFOAM Foundation software. It regularly checks a log file written by the solver for updating a progress bar. For live plot it uses matplotlib.

Usage

mpywatch [OPTIONS]

Show Progress at Command Line

The progress display is based on scheduled polling with schedule and rich for progress display. The TIME value is extracted from the logfile of foamRun, typically named log.foamRun if modular solvers are used. It is possible to specify other log files as well, important is the line TIME = ... s.

Note, that the tool extracts the endTime value from the system/controlDict to calculate the percentage. The value is read upon start of the watching process and not updated during the progress display. Hence, if you change endTime you have to restart the tool.

However, the tool can stay active in case you want to re-start your simulation. It will detect a new log file and restart the progress display accordingly. Use the option --interval to choose a suitable polling interval for all watch tasks. A offscreen mode is available with --offscreen and PNG images for the plots are written to disk.

For example to monitor a log file and show simulation progress

mpywatch --progress --solver-log log.foamRun

or to monitor a specific case directory

mpywatch --case /path/to/case --progress log.foamRun

Real-time plots of simulation data

The real-time plotting is based on matplotlib. At the moment only ASCII files with a column format and a whitespace as delimiter are supported. The brackets used by OpenFOAM Foundation software for indicating vectors are supported as well.

A plot is generated with the command line argument --plot. The following string is the file name relative to the case root directory, e.g., postProcessing/residuals.dat and the columns, which should be plotted as X and Y. If logarithmic scale is required it can be turned on for both axis with the keyword log.

As an example for plotting residuals for p_rgh, first insert the corresponding functionObject into system/functions

#includeFunc residuals(p_rgh)

now, launch the solver and run

mpywatch --plot 'postProcessing/residuals(p_rgh)/0/residuals.dat:0:log(1)'

for plotting the residuals of p_rgh with logarithmic y-axis. The range of the plots is adjusted automatically.

Offscreen plots of simulation data

It is possible to generate live plots by storing images in a file instead of showing them as a live plot. This can be done with the --offscreen flag. The plot will be stored in the desired frequency (set with --interval) in the root directory of the case

mpywatch --plot 'postProcessing/residuals(p_rgh)/0/residuals.dat:0:log(1)' --offscreen

This will result in a PNG file in the case root named residuals.live.png.