# 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 uses file watching to react to changes in log files
for updating a progress bar. For live plot it uses
[matplotlib](https://matplotlib.org/).

## Usage

```bash
mpywatch [OPTIONS]
```

## Show Progress at Command Line

The progress display is based on
[watchdog](https://python-watchdog.readthedocs.io/) for monitoring file events
and [rich](https://rich.readthedocs.io/) 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.

For example to monitor a log file and show simulation progress

```bash
mpywatch --progress log.foamRun
```

or to monitor a specific case directory

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

## Real-time plots of simulation data (experimental)

Note, that this is an experimental feature, and might cause unexpected
behaviour. The real-time plotting is based on
[matplotlib](https://matplotlib.org/). 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`

```cpp
#includeFunc residuals(p_rgh)
```

now, launch the solver and run

```bash
mpywatch --progress log.foamRun --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.