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

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.

Real-time Courant Number Information

The option --courant allows to monitor the mean and the maximum Courant number for a simulation based on the logfile written by the solver. The values are extracted from the logfile of foamRun, typically named log.foamRun if modular solvers are used. The information will be presented as a gauge plot based on matplotlib.

mpywatch --courant --solver-log "log.foamRun"

Offscreen Rendering

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.