OpenFOAM-Residuals

A Python tool to parse and plot residual data from OpenFOAM case directories. This tool is designed to work with output from Eddy3D, an airflow and microclimate simulation plugin for Rhino and Grasshopper, but can be used with standard OpenFOAM residual files as well.

Features

• Automatic Detection: Recursively finds residuals*.dat and OpenFOAM log.* files in case directories.
• Batch Processing: Handle multiple case directories or single files.
• Plotting: Generates high-quality PNG plots of residuals vs. iterations.
• Data Export: Exports cleaned data for further analysis.
• Smart Scaling: Automatically adjusts plot scales based on residual magnitude.

Requirements

• Python 3.10 or later

Installation

Install from PyPI:

pip install openfoam-residuals

or with uv:

uv add openfoam-residuals

Development Setup

1. Clone the repository:

   git clone https://github.com/Eddy3D-Dev/OpenFOAM-Residuals.git
   cd OpenFOAM-Residuals

2. Install dependencies:

   uv sync

Usage

You can run the tool directly using uv run:

Single File

Plot residuals for a specific file (residuals*.dat or log.*):

uv run python -m openfoam_residuals.main -f /path/to/residuals.dat

Case Directory

Automatically find and plot all residual files in a directory (recursive):

uv run python -m openfoam_residuals.main -w /path/to/case/dir

Multiple Directories

Process multiple case directories at once:

uv run python -m openfoam_residuals.main -w case1 -w case2

Options

• -o, --out: Specify output directory (default: exports).
• --no-plots: Skip plot generation and only export data.
• -v, --verbose: Increase logging verbosity (e.g., -vv).

Development

Running Tests

uv run pytest

License

GNU General Public License v3 (GPLv3)