foam-cfd-unified-7b/README.md

---
language: en
license: apache-2.0
base_model: Qwen/Qwen2.5-Coder-7B-Instruct
tags:
  - cfd
  - openfoam
  - gmsh
  - fluid-dynamics
  - fine-tuned
  - qwen2.5
  - qlora
pipeline_tag: text-generation
---

# foam-cfd-unified-7B

A single **Qwen2.5-Coder-7B-Instruct** model fine-tuned for end-to-end CFD workflows —
covering Gmsh mesh generation, OpenFOAM boundary condition files, and BC JSON patch specs.

---

## What this model does

| Task | Input | Output |
|---|---|---|
| **Mesh generation** | Plain-English geometry description | Gmsh `.geo` script |
| **OpenFOAM case files** | Flow prompt + mesh patches | `0/U`, `0/p`, `0/k`, `0/epsilon` BC files |
| **BC patch spec** | Flow description + existing BC template | Compact JSON diff applied on top of template |

**Example prompts:**
- `"Lid driven cavity, Re=1000, 0.1m x 0.1m"`
- `"Flow over a cylinder, diameter=0.05m, Re=100"`
- `"2D backward-facing step, step height 0.05m, Re=500"`
- `"NACA 0012 airfoil, chord=1m, AoA=5deg, Re=1e6"`

---

## Model info

| Field | Value |
|---|---|
| Base model | Qwen2.5-Coder-7B-Instruct |
| Fine-tuning method | QLoRA (LoRA r=64, alpha=16, 4-bit NF4) via Unsloth |
| Training examples | 20,505 (mesh-gen + foam-gen + patch-gen + raft-patch-gen) |
| Validation examples | 2,277 |
| VRAM required | ~6 GB (4-bit inference) / ~16 GB (full precision) |
| Sequence length | 4096 tokens |

---

## Quickstart — use with the foam-cfd-ai server

### 1. Clone the deployment repo

```bash
git clone https://github.com/AGN000/foam-cfd-deploy
cd foam-cfd-deploy
pip install -r requirements.txt
```

### 2. Download this model

```bash
pip install huggingface_hub
python3 -c "
from huggingface_hub import snapshot_download
snapshot_download(
    'arungovindneelan/foam-cfd-unified-7b',
    local_dir='checkpoints/unified/merged'
)
"
```

### 3. Build the RAG index

Requires OpenFOAM 11 tutorials (usually at `/opt/openfoam11/tutorials`):

```bash
python3 -m rag.build_index
```

### 4. Start the inference server

```bash
python3 -m inference.server --model checkpoints/unified/merged --port 8000
```

### 5. Run a simulation end-to-end

```bash
# Quick demo
python3 demo.py "Lid driven cavity, Re=1000"

# Or call the API directly
curl -X POST http://localhost:8000/simulate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "flow over a cylinder, Re=100, diameter 0.1m"}'
```

---

## Direct Python usage (without the server)

```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_id = "arungovindneelan/foam-cfd-unified-7b"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    device_map="auto",
)

# Generate a Gmsh mesh script
messages = [
    {"role": "system", "content": "You are a CFD mesh generation expert. Generate valid Gmsh .geo scripts."},
    {"role": "user", "content": "Create a 2D lid-driven cavity mesh, 0.1m x 0.1m, structured 50x50 grid."},
]
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(text, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model.generate(**inputs, max_new_tokens=1024, temperature=0.1, do_sample=True)

response = tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(response)
```

---

## System requirements

- Linux (Ubuntu 20.04+)
- Python 3.10+
- NVIDIA GPU with >= 8 GB VRAM (tested on H100, A100, RTX 3090)
- CUDA 12.x
- OpenFOAM 11 (for simulation — not required for model inference alone)

---

## Repository structure

```
foam-cfd-ai/
  checkpoints/unified/merged/   <- this model
  inference/
    server.py                   <- FastAPI server (POST /generate /mesh /simulate)
    mesh_pipeline.py            <- Gmsh script generation + validation
  rag/
    build_index.py              <- build vector store from OpenFOAM tutorials
    llm_case_generator.py       <- LLM-driven BC file generation
    rag_case_builder.py         <- RAG + LLM -> OpenFOAM case directory
    retriever.py                <- vector search over tutorial chunks
  simulation/
    case_builder.py             <- hardcoded fallback case builder
    foam_runner.py              <- runs foamRun -solver incompressibleFluid
  training/
    train.py                    <- QLoRA fine-tuning (Unsloth + TRL)
    config_unified.yaml         <- training config for this model
  demo.py                       <- end-to-end demo script
  requirements.txt
```

---

## API endpoints (when server is running)

| Endpoint | Method | Description |
|---|---|---|
| `/health` | GET | Server health check |
| `/generate` | POST | Generate Gmsh `.geo` script from prompt |
| `/mesh` | POST | Generate + validate mesh, return stats |
| `/simulate` | POST | Full pipeline: mesh → OpenFOAM case → run → results |

### Example: `/simulate`

```bash
curl -X POST http://localhost:8000/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "NACA 0012 airfoil, chord 1m, AoA 5 degrees, Re 1e6",
    "n_iter": 500
  }'
```

Response:
```json
{
  "status": "converged",
  "solver": "simpleFoam",
  "iterations": 487,
  "residuals": {
    "Ux": {"initial": 1.0, "final": 3.2e-5},
    "Uy": {"initial": 1.0, "final": 8.7e-5},
    "p":  {"initial": 1.0, "final": 2.1e-4}
  },
  "case_dir": "/tmp/foam_cases/20260407_094950_airfoil"
}
```

---

## Training data breakdown

| Task | Examples | Description |
|---|---|---|
| mesh-gen | ~5,000 | Gmsh `.geo` script generation |
| foam-gen | ~5,000 | Full OpenFOAM BC file generation |
| patch-gen | ~5,000 | JSON BC patch spec generation |
| raft-patch-gen | ~5,505 | RAFT-style retrieval-augmented patch generation |
| **Total** | **20,505** | Unified training set |

---

## License

Apache 2.0 — same as the Qwen2.5-Coder base model.