cfdfig 0.1.0

CLI tool for publication-ready CFD plots and case tracking

cfdfig

A CLI tool for generating publication-ready CFD plots and tracking simulation cases.

Built for researchers who need reproducible, journal-quality visualizations without complicated dependencies or black-box processing.

Features

• Publication-Ready Plots - Journal-safe matplotlib styling with vector (PDF) and raster (PNG) outputs
• Reproducible Workflows - File-based case tracking with YAML metadata
• Solver-Agnostic - Works with OpenFOAM, SU2, and custom CFD solvers
• HPC-Friendly - Pure CLI, no web UI, no external databases
• Methods Export - Auto-generate text for journal paper methods sections
• Deterministic - No randomness, no AI—just reliable CFD visualization

Installation

# Clone the repository
git clone <repository-url>
cd cfd-visualiser

# Install in development mode
pip install -e .

# Or install from PyPI (when published)
pip install cfdfig

Requirements

• Python 3.10+
• matplotlib, pandas, numpy
• typer, PyYAML

Quick Start

1. Initialize a CFD Case

cfdfig init my_airfoil_case --description "NACA 0012 validation at Re=3e6"
cd my_airfoil_case

This creates:

my_airfoil_case/
├── cfdfig.yaml        # Case and run metadata
├── outputs/           # Place solver logs here
├── figures/           # Generated plots go here
└── README.md

2. Add Your Solver Outputs

Place your solver log files and force data in the outputs/ directory:

cp /path/to/solver/log.simpleFoam outputs/
cp /path/to/solver/forceCoeffs.dat outputs/

3. Register a Run

cfdfig add-run \
  --id baseline \
  --solver simpleFoam \
  --turbulence kOmegaSST \
  --mesh v1_coarse \
  --cells 150000 \
  --notes "Initial validation run"

4. Generate Plots

# Plot residuals
cfdfig plot residuals

# Plot force coefficients
cfdfig plot forces

# List all runs
cfdfig list-runs

# Display case info
cfdfig info

Command Reference

cfdfig init

Initialize a new CFD case with directory structure and metadata template.

cfdfig init <case_name> [OPTIONS]

Options:
  -p, --path PATH          Directory to create case in
  -d, --description TEXT   Case description

cfdfig add-run

Register a new CFD run with metadata for reproducibility.

cfdfig add-run [OPTIONS]

Required:
  --id TEXT              Unique run identifier
  --solver TEXT          Solver name (e.g., simpleFoam, pimpleFoam)
  --turbulence TEXT      Turbulence model (e.g., kOmegaSST, SA)
  --mesh TEXT            Mesh version/identifier

Optional:
  --cells INTEGER        Number of mesh cells
  --numerics TEXT        Numerical schemes information
  --notes TEXT           Additional notes

cfdfig plot residuals

Generate log-scale residual convergence plots.

cfdfig plot residuals [OPTIONS]

Options:
  -r, --run TEXT         Run ID for labeling
  -l, --log PATH         Path to log file (auto-detected if not specified)
  -o, --output TEXT      Output filename without extension
  -t, --title TEXT       Plot title

cfdfig plot forces

Plot force coefficients (Cl, Cd, Cm) over time.

cfdfig plot forces [OPTIONS]

Options:
  -f, --file PATH        Path to force coefficient file
  -o, --output TEXT      Output filename
  -t, --title TEXT       Plot title
  --x-axis TEXT          X-axis variable (time or iteration)

cfdfig compare

Compare residuals from multiple runs.

cfdfig compare <field> <run1> <run2> [run3...] [OPTIONS]

Arguments:
  field                  Field to compare (Ux, p, k, etc.)
  runs                   Run IDs to compare

Options:
  -o, --output TEXT      Output filename
  -t, --title TEXT       Plot title

Example:

cfdfig compare Ux baseline refined fine_mesh

cfdfig export-methods

Generate a methods section for journal papers.

cfdfig export-methods [OPTIONS]

Options:
  -o, --output PATH      Save to file (prints to console if not specified)

cfdfig list-runs

Display all runs in the current case as a formatted table.

cfdfig info

Show case information and statistics.

File Formats

cfdfig.yaml Structure

schema_version: '1.0'
case:
  name: my_case
  description: Case description
  created: '2025-12-24T10:00:00'
runs:
  - id: run1
    solver: simpleFoam
    turbulence_model: kOmegaSST
    mesh_version: v1
    mesh_cells: 150000
    numerics: Second-order upwind
    notes: Initial run
    added: '2025-12-24T10:15:00'

Supported Log Formats

OpenFOAM: Automatically parses residuals from standard OpenFOAM solver output:

Solving for Ux, Initial residual = 0.1234, Final residual = 0.0001

Force Coefficients: CSV or space-delimited format:

# Time  Cd      Cl      Cm
0.0     0.045   0.320   -0.015
1.0     0.044   0.316   -0.014

Plot Styling

All plots use the journal.mplstyle configuration for publication quality:

• Fonts: Times New Roman / Computer Modern
• DPI: 300 (print quality)
• Format: PDF (vector) + PNG (raster)
• Line widths: Optimized for journal submission
• Color scheme: Colorblind-friendly palette
• Grid: Subtle dotted grid lines

Customize by editing cfdfig/styles/journal.mplstyle.

Example Workflow

See the complete example in examples/openfoam_case/:

# Navigate to example
cd examples/openfoam_case

# View case structure
cfdfig info

# Generate plots
cfdfig plot residuals
cfdfig plot forces

# Export methods section
cfdfig export-methods

Development

Running Tests

pip install -e ".[dev]"
pytest tests/

Code Formatting

black cfdfig/
ruff check cfdfig/

Design Principles

1. Deterministic: No randomness, same input = same output
2. No AI: Human-controlled, explainable visualizations
3. Reproducible: All metadata tracked in version-controllable YAML
4. Academic Quality: Journal-submission-ready plots
5. CLI-First: Scriptable, HPC-compatible, no GUI required
6. File-Based: No external databases, works offline

Use Cases

• Comparing turbulence models across multiple runs
• Grid independence studies
• Convergence monitoring
• Generating figures for papers and presentations
• Archiving CFD simulation metadata
• Reproducing published results

Contributing

This is a research tool focused on reliability and academic standards. Contributions welcome for:

• Additional solver parsers (SU2, Fluent, etc.)
• New plot types (Cp distributions, velocity profiles)
• Enhanced metadata schemas
• Bug fixes and documentation improvements

License

MIT License - See LICENSE file for details.

Citation

If you use this in your research:

@software{cfdfig2025,
  title={cfdfig: CLI for CFD visualization},
  author={Your Name},
  year={2025},
  url={https://github.com/yourusername/cfdfig}
}

Support

For issues, questions, or feature requests, open an issue on GitHub.

---

Built for researchers. No AI, no complexity.