Metadata-Version: 2.4
Name: sim-plugin-hpc
Version: 0.1.0
Summary: HPC-Cluster bridge for sim-cli — routes sim commands to a central job scheduler
Author: HPC-Cluster Team
License-Expression: Apache-2.0
Keywords: cae,hpc,plugin,scheduler,sim-cli,simulation
Requires-Python: >=3.9
Requires-Dist: httpx>=0.28
Requires-Dist: sim-cli-core>=0.3
Description-Content-Type: text/markdown

# sim-plugin-hpc

HPC-Cluster bridge for sim-cli — routes `sim` commands to a centralized CAE job scheduling platform.

## Overview

This plugin allows AI Agents using sim-cli to submit simulation jobs to an HPC-Cluster
scheduling platform via REST API, instead of running solvers locally.

```
AI Agent → sim-cli → sim-plugin-hpc → HTTP → HPC-Cluster API → 20 solvers
```

## Installation

```bash
cd C:\HPC-Cluster\extensions\sim-plugin-hpc
pip install -e .
```

Verify:

```bash
uv run sim check hpc
# Connected to HPC-Cluster (20 solvers, 0 running, 0 total jobs)
```

## Configuration

```bash
# Default: http://localhost:8000 — override for remote deployments
export HPC_URL=http://192.168.1.100:8000

# JWT token (required when auth.enabled=true)
export HPC_TOKEN=eyJ...
```

## Usage

### Batch Jobs (`/api/submit`)

Submit a solver input file — the system auto-detects the solver from the file extension.

```bash
# Auto-detection by suffix
uv run sim run --solver hpc model.bdf           # → nastran
uv run sim run --solver hpc panel.inp           # → abaqus
uv run sim run --solver hpc mesh.jou            # → ansys_fluent
uv run sim run --solver hpc part.adm            # → adams
uv run sim run --solver hpc model.mph           # → comsol
uv run sim run --solver hpc project.cst         # → cst
uv run sim run --solver hpc script.tcl          # → hypermesh
uv run sim run --solver hpc study.hst           # → hyperstudy
uv run sim run --solver hpc part.geo            # → gmsh
uv run sim run --solver hpc mesh.glf            # → pointwise
uv run sim run --solver hpc model.prt           # → nx_batchmesh
uv run sim run --solver hpc session.meta        # → metapost
uv run sim run --solver hpc workflow.zmf        # → isight
uv run sim run --solver hpc fatigue.ldf         # → fe_safe
uv run sim run --solver hpc optimize.par        # → tosca
```

**Ambiguous extensions — must specify `--software` explicitly:**

```bash
uv run sim run --solver hpc --software nastran input.dat
uv run sim run --solver hpc --software ansys_mechanical input.dat
uv run sim run --solver hpc --software paraview script.py
uv run sim run --solver hpc --software freecad script.py
uv run sim run --solver hpc --software calculix model.inp
```

**Custom resources and arguments:**

```bash
# Memory and CPU
uv run sim run --solver hpc --mem 32 --cpu 8 large_model.inp

# Extra solver CLI args
uv run sim run --solver hpc --args "batch=yes parallel=4" model.bdf

# Long-running jobs (default timeout: 10 hours)
uv run sim run --solver hpc --timeout 72000 --mem 64 huge_model.inp
```

**Async submit (fire-and-forget):**

```bash
uv run sim run --solver hpc --no-wait large_model.bdf
# Returns: Job submitted: nastran_abc123_1717345678 (status: submitted)
```

### Realtime Tasks (`/api/tasks`)

Lightweight operations with SSE progress streaming. Ideal for meshing, rendering, and quick tasks.

```bash
# Gmsh mesh generation (1-30s)
uv run sim run --solver hpc --task-type gmsh_mesh --geo part.geo

# HyperMesh Tcl mesh generation (10-120s)
uv run sim run --solver hpc --task-type hypermesh_mesh --tcl batch_mesh.tcl

# ParaView Python rendering (5-60s)
uv run sim run --solver hpc --task-type paraview_render --script visualize.py

# FreeCAD parametric modeling (30-300s)
uv run sim run --solver hpc --task-type freecad_model --script create_part.py

# Pointwise Glyph CFD mesh (30-300s)
uv run sim run --solver hpc --task-type pointwise_mesh --glf airfoil.glf
```

All realtime tasks return a `stream_url` for live SSE progress tracking.

### Inspect and Monitor

```bash
# List all 20 registered solvers
uv run sim inspect hpc.installed

# Check job status (replace <job_id> with actual value)
curl http://localhost:8000/api/jobs/<job_id>

# View cluster stats
curl http://localhost:8000/api/stats
```

## Supported Solvers (20 total)

| Category | Count | Solvers |
|----------|-------|---------|
| Interactive | 1 | ANSA (490 tools via Direct IAP) |
| FEA | 6 | Abaqus, Nastran, ANSYS Mechanical, ANSYS Fluent, CalculiX, Adams |
| Multiphysics | 2 | COMSOL, CST |
| Pre-processing | 5 | HyperMesh, HyperStudy, Gmsh, Pointwise, NX BatchMesher |
| Post-processing | 4 | ParaView, META Post, FreeCAD, Isight |
| SIMULIA | 2 | fe-safe, Tosca |

## Realtime Tasks (P6)

| Task Type | Tool | Duration |
|-----------|------|----------|
| `gmsh_mesh` | Gmsh mesh generation | 1-30s |
| `hypermesh_mesh` | HyperMesh Tcl mesh generation | 10-120s |
| `paraview_render` | ParaView Python rendering | 5-60s |
| `freecad_model` | FreeCAD parametric modeling | 30-300s |
| `pointwise_mesh` | Pointwise Glyph mesh generation | 30-300s |

## Extension Conflict Guide

| Extension | Conflict | Resolution |
|-----------|----------|------------|
| `.dat` | nastran / ansys_mechanical | Must pass `--software` |
| `.py` | paraview / freecad | Must pass `--software` |
| `.inp` | abaqus / calculix / fe_safe / tosca | Defaults to abaqus; others need `--software` |

## File Map

```
extensions/sim-plugin-hpc/
├── pyproject.toml              # Package config + sim.drivers / sim.skills entry points
├── README.md                   # This file
└── src/sim_plugin_hpc/
    ├── __init__.py             # Plugin info + skills_dir()
    ├── solver_map.py           # Extension → solver mapping + labels + realtime task list
    ├── client.py               # HpcClient — REST/SSE HTTP client (httpx)
    ├── driver.py               # HpcDriver — detect/lint/connect/run_file/launch
    └── _skills/
        └── hpc/
            └── SKILL.md        # AI Agent usage manual
```

## Key Design Decisions

| Design Point | Decision |
|-------------|----------|
| Extension conflicts | `.dat`/`.py` map to `None`; `detect()` returns `False`; `lint()` prompts `--software` |
| `.inp` default | Maps to `abaqus` (backward compat); `lint()` notes CalculiX needs explicit |
| Sync wait | `run_file()` defaults `wait=True`; polls every 2s + SSE incremental logs |
| Async mode | `--no-wait` returns `job_id` immediately; result referenced as `hpc://<job_id>` artifact |
| Virtual install | `detect_installed()` returns all 20 solvers, `source="hpc-cluster"` |
| Authentication | `HpcClient` supports `--token` JWT; all requests carry `Authorization: Bearer` |
| Realtime tasks | `launch()` maps to `POST /api/tasks`; 5 P6 task types |
| Remote logs | `wait_for_completion()` uses SSE for log streaming (works cross-machine); `job_logs()` reads local FS (same-machine only) |
