Metadata-Version: 2.4
Name: foamplot
Version: 1.0.0
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/)

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`](https://pypi.org/project/plotille/).

Inspired by [`asciichartpy`](https://github.com/kroitor/asciichart/tree/master/asciichartpy).

## 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="./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="./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="./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 ...]
```

| 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

