Metadata-Version: 2.4
Name: foamplot
Version: 1.0.4
Summary: Unix terminal plotter for foamLog-generated numeric files
Project-URL: Homepage, https://github.com/YOUR_GITHUB_USERNAME/foamplot
Project-URL: Repository, https://github.com/YOUR_GITHUB_USERNAME/foamplot
Project-URL: Issues, https://github.com/YOUR_GITHUB_USERNAME/foamplot/issues
Author-email: Songrui Li <lsongrui2024@gmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: cli,foamlog,openfoam,plot,plotille,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Terminals
Requires-Python: >=3.6
Requires-Dist: plotille>=4
Description-Content-Type: text/markdown

# foamplot

[![PyPI version](https://img.shields.io/pypi/v/foamplot.svg)](https://pypi.org/project/foamplot/)
[![Python versions](https://img.shields.io/pypi/pyversions/foamplot.svg)](https://pypi.org/project/foamplot/)
[![License](https://img.shields.io/pypi/l/foamplot.svg)](LICENSE)
[![Package status](https://img.shields.io/pypi/status/foamplot.svg)](https://pypi.org/project/foamplot/)

A lightweight terminal plotting tool for OpenFOAM-style residual and log files.

`foamplot` reads numeric data from one or more files and draws live line plots directly in the terminal, suitable for monitoring residuals, forces, and other scalar log that grows line by line.

Unlike `foamMonitor`, which relies on `gnuplot_x11` and an available X display, `foamplot` renders directly in the Unix terminal, no GUI session, X11 forwarding, or gnuplot window is required.

It works seamlessly with OpenFOAM workflows, but also supports any software that generates text files in a compatible format.

Inspired by [`asciichart`](https://github.com/kroitor/asciichart/), but using Unicode/Braille characters for higher-resolution plots.

Built on top of [`plotille`](https://pypi.org/project/plotille/), adding file monitoring, log-scale visualization, and live updating. 

Thanks to `plotille`, `foamplot` does not require any other other external Python packages like NumPy, Matplotlib, pandas, or gnuplot.

## Install

```bash
pip install foamplot
```

or, as an isolated CLI app:

```bash
pipx install foamplot
```

## Demo

```bash
foamplot --demo -i 0.1 -W 80
```

<img src="https://raw.githubusercontent.com/lsongrui/foamplot/main/docs/demo_black.gif" alt="foamplot demo" width="700">

## 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:

```bash
# 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/`:

```bash
foamLog log.icoFoam
```

Plot any generated file in `logs/`:

```bash
foamplot logs/p_0
```

<img src="https://raw.githubusercontent.com/lsongrui/foamplot/main/docs/example1.png" alt="foamplot single-series example" width="700">

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

```bash
foamplot logs/p_0 logs/Ux_0 logs/Uy_0
```

<img src="https://raw.githubusercontent.com/lsongrui/foamplot/main/docs/example2.png" alt="foamplot multi-series example" width="700">

### Monitor residuals live

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

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

./Allrun
```

Update the residual files live in another terminal:

```bash
watch -n 0.2 foamLog log.simpleFoam
```

Follow the generated residual file:

```bash
foamplot logs/p_0 --follow
```

Two options control the horizontal view:

```bash
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:

```bash
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:

```bash
foamplot logs/p_0 --scale linear
```

Customize the plot size:

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

Show only the latest 200 values:

```bash
foamplot logs/p_0 --points 200
```

Refresh every second in follow mode:

```bash
foamplot logs/p_0 --follow --interval 1
```

## Plot Other Data Files

`foamplot` can also plot simple numeric text files.

For example:

```text
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.

```bash
foamplot data.txt
```

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

```bash
foamplot data.txt --column 1
```

## Options

```text
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 ...]
```

```bash
positional arguments:
  files                 foamLog-generated file(s); each file becomes one line

optional arguments:
  -h, --help            show this help message and exit
  -p POINTS, --points POINTS
                        latest lines to read from each file
  -W PLOT_WIDTH, --plot-width PLOT_WIDTH
                        maximum plot width in terminal columns
  -H HEIGHT, --height HEIGHT
                        chart height
  -i INTERVAL, --interval INTERVAL
                        refresh interval in seconds
  -c COLUMN, --column COLUMN
                        zero-based numeric token; default: last number
  --names NAMES         comma-separated series names, e.g. pa,p,ux
  -f, --follow          keep refreshing the file(s)
  --demo                run demo instead of reading files
  --demo-kind {sine,cfd}
                        demo data type
  --demo-points DEMO_POINTS
                        maximum retained demo points before the live window
                        starts scrolling
  --demo-lines DEMO_LINES
                        number of demo lines, 1 to 5
  --scale {log,linear}  plot scale for file mode
```

## 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

