foamplot 1.0.0

Unix terminal plotter for foamLog-generated numeric files

foamplot

Plot OpenFOAM-style residual/log files as line charts in the terminal. Useful for monitoring solver output on servers.

foamplot reads numeric values from one or more files and draws a live terminal plot using Unicode/Braille characters. It is useful for watching residuals, objective values, forces, coefficients, or any scalar log that grows line by line.

Built on top of plotille.

Inspired by asciichartpy.

Install

pip install foamplot

or, as an isolated CLI app:

pipx install foamplot

Demo

foamplot --demo -i 0.1 -W 80

Plot OpenFOAM Residuals

foamplot works directly with residual files generated by foamLog.

Static plot

Run an OpenFOAM case and write the solver output to a log file:

# at your working directory
cp -r "$FOAM_TUTORIALS/incompressible/icoFoam/cavity/cavity" .
cd cavity

blockMesh | tee log.blockMesh
icoFoam | tee log.icoFoam

Run foamLog to extract residuals into logs/:

foamLog log.icoFoam

Plot any generated file in logs/:

foamplot logs/p_0

You can also plot multiple files, up to 5 series:

foamplot logs/p_0 logs/Ux_0 logs/Uy_0

Monitor residuals live

Run an OpenFOAM case and write the solver output to a log file. For example, using the official motorBike tutorial:

# at your working directory
cp -r "$FOAM_TUTORIALS/incompressible/simpleFoam/motorBike" .
cd motorBike

./Allrun

Update the residual files live in another terminal:

watch -n 0.2 foamLog log.simpleFoam

Follow the generated residual file:

foamplot logs/p_0 --follow

Two options control the horizontal view:

foamplot logs/p_0 --follow -W 120 -p 200

Option	Meaning
-W, --plot-width	Plot width in terminal columns.
-p, --points	Maximum number of latest points to keep.

Behaviour:

• If points < plot-width, the curve grows to the right.
• If plot-width < points < max points, the curve is compressed into the plot width.
• If points > max points, only the latest points are shown and the plot scrolls.

In follow mode, the plot refreshes in place. Press Ctrl+C to stop.

Other useful examples

Name the series:

foamplot logs/p_0 logs/Ux_0 logs/Uy_0 --names p,Ux,Uy

Because foamplot is mainly intended for residual histories, the default scale is log10. In log mode, only positive values are plotted.

For zero or negative values, use a linear scale:

foamplot logs/p_0 --scale linear

Customize the plot size:

foamplot logs/p_0 --plot-width 160 --height 30

Show only the latest 200 values:

foamplot logs/p_0 --points 200

Refresh every second in follow mode:

foamplot logs/p_0 --follow --interval 1

Plot Other Data Files

foamplot can also plot simple numeric text files.

For example:

1	1
2	0.270842
3	0.134221
4	0.0782715
5	0.0602821
6	0.0495971
7	0.0428131
8	0.0384169
9	0.0360277
10	0.0341129

By default, foamplot uses the last numeric token on each line. For the file above, it plots the second column.

foamplot data.txt

To select a specific numeric token, use --column. The index is zero-based:

foamplot data.txt --column 1

Options

usage: foamplot [-h] [-p POINTS] [-W PLOT_WIDTH] [-H HEIGHT]
                [-i INTERVAL] [-c COLUMN] [--names NAMES]
                [-f] [--demo] [--demo-points DEMO_POINTS]
                [--demo-lines DEMO_LINES] [--phase-step PHASE_STEP]
                [--scale {log,linear}]
                [files ...]

Option	Description
files	Input files. Each file becomes one series.
-p, --points	Number of latest lines to read. Default: 1000.
-W, --plot-width	Plot width in terminal columns. Default: 120.
-H, --height	Plot height. Default: 20.
-i, --interval	Refresh interval in seconds. Default: 0.5.
-c, --column	Zero-based numeric token to use. Default: last number.
--names	Comma-separated series names.
-f, --follow	Keep refreshing the plot.
--demo	Run the built-in sine-wave demo.
--demo-points	Number of demo points. Default: 100.
--demo-lines	Number of demo series, 1 to 5. Default: 1.
--phase-step	Phase increment in demo mode. Default: 0.25.
--scale	log or linear. Default: log.

Notes

• Requires Python 3.6+.
• Intended for Linux/macOS terminals.
• Uses tail -n internally.
• Requires a Unicode-capable terminal.
• In log mode, only positive values are plotted.
• Use --scale linear for values that may be zero or negative.
• foamplot --follow redraws the files you pass to it. It does not run foamLog automatically.

License

MIT