cfdfig 0.1.1
CLI tool for publication-ready CFD plots and case tracking
License: MIT
Requires Python: >=3.9

# 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

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

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

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

### 3. Register a Run

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

### 4. Generate Plots

```bash
# 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.

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

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

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

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

```bash
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:
```bash
cfdfig compare Ux baseline refined fine_mesh
```

### `cfdfig export-methods`

Generate a methods section for journal papers.

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

```yaml
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/`:

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

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

### Code Formatting

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

```bibtex
@software{cfdfig2025,
  title={cfdfig: CLI for CFD visualization},
  author={Tejas},
  year={2025},
  url={https://github.com/tejase/cfdfig}
}
```

## Support

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

---

Built for researchers. No AI, no complexity.