fortranspire

An LLM + MCP pipeline that ports legacy Fortran HPC kernels to GPU (OpenACC) and differentiable JAX.

fortranspire automates the four transformations a senior HPC engineer would perform by hand when porting a Fortran 90 kernel to GPU and Python:

1. Parse the source with Loki (ECMWF) — deterministic AST analysis of INTENT, SAVE, COMMON, POINTER, and inline loops.

2. Extract the kernels into a MODULE with explicit INTENT(INOUT) arguments — one LLM call against any OpenAI-compatible endpoint.

3. Annotate purity (PURE/ELEMENTAL) and insert OpenACC pragmas (!$acc parallel loop collapse(...), !$acc data copyin/copy).

4. Wrap in Cython (NumPy typed memoryviews, iso_c_binding header) and validate with gfortran and nvfortran -acc.

The pipeline is exposed as a CLI and as a Model Context Protocol (MCP) server, so it is callable from any MCP-aware client (Claude Desktop, Cursor, VS Code, Mistral Le Chat connectors) or any CI runner.

Getting started

• Quickstart with mistral-vibe (60 seconds)
  • Prerequisites
  • Step 1 — Install fortranspire and mistral-vibe
  • Step 2 — Register fortranspire in ~/.vibe/config.toml
  • Step 3 — Pick a Fortran target (PHYEX is the demo)
  • Step 4 — Launch vibe and talk
  • Step 5 — Push it further
  • Why this matters
  • Next steps
• Installation
  • Prerequisites
  • From PyPI
  • From source (recommended for development)
  • Optional extras
  • Compiler detection
  • Docker
  • Verifying the install
• Quickstart
  • 1. Configure the LLM endpoint
  • 2. Run Phase 1 — Fortran → GPU + Cython
  • 3. Run Phase 2 — Fortran → JAX (optional)
  • 4. Analyze-only mode (no LLM, CI hook)
  • 5. Use the MCP server from an IDE
  • Next steps
• Configuration
  • LLM endpoint
  • MCP server
  • Pipeline behavior
  • Compiler toolchain
  • Loading the .env

Concepts

• Architecture
  • LLM budget per run
  • State shape
  • Human-in-the-loop
  • Where the LLM intervenes (and where it does not)
  • Why an agent, not a one-shot prompt
  • Why this sequence?
• Fortran patterns & transformation rules
  • Summary table
  • 1. INTENT — the key to everything else
  • 2. COMMON blocks — the global state to eliminate
  • 3. SAVE — hidden state between calls
  • 4. POINTER — dangerous aliasing for GPU
  • 5. Array of Structures → Structure of Arrays (AoS → SoA + collapse)
  • 6. Nested dependencies — non-parallelisable loops
  • 7. ELEMENTAL + OpenACC — the right pattern
  • 8. Explicit types — no compiler-inferred mixed precision
  • 9. Logical flags USE_xx → compile-time directives
  • 10. MPI halo exchange → GHEX (GPU-to-GPU)
  • 11. Fortran I/O → xarray / zarr + DLPack
  • See also
• LLM endpoints
  • What “sovereignty” means here
  • A — Mistral La Plateforme (EU-hosted, operated by Mistral AI)
  • B — Self-hosted (full sovereignty)
  • C — Other compatible backends
  • Quality vs. cost tradeoff
• Mistral integration
  • Path 1 — Agent as a Mistral La Plateforme consumer
  • Path 2 — Per-stage model selection (Codestral + Mistral-Large)
  • Path 3 — Agent as an MCP provider for Le Chat / Mistral Agents API
  • Path 4 — Submission to the Le Chat connector directory
  • Cheat sheet
• Le Chat connector (preparation kit)
  • Submission package
  • Checklist before submission
  • Operating recommendations
  • Related
• Documenting a legacy Fortran codebase
  • Quick start
  • What the inline docstring looks like
  • Operating modes
  • Cost model
  • Pairing with the analyzer
  • Limitations
• 4. PyTree State Injection
  • Key Observations:
• 5. XLA Optimizations and @jax.jit
  • Key Observations:
• 6. Performance Verdict
  • Key Recommendations for Improvement:
  • Expected Performance Gains:
• Fortran → gt4py.next — pattern correspondences
  • 1. Why gt4py.next is the right shape for this pipeline
  • 2. The one mental-model shift
  • 3. Pattern correspondence table
  • 4. INTENT → arguments and returns (shared with Phase 2)
  • 5. Neighbour access — the heart of a stencil
  • 6. Conditionals → where, never if
  • 7. Unstructured neighbours → connectivity + neighbor_sum (the primary horizontal model)
  • 8. Vertical recurrence → scan_operator
  • 9. Dimensions, dtypes, and the portability score
  • 10. What does not map — and must be reported, not emitted
  • 11. Verified against gt4py.next 1.2.1
  • 11bis. The domain and halos live in the driver (issue #82)
  • 12. Where this plugs into the pipeline
  • See also
• Fortran → gt4py.next — visual cheat-sheet
  • The one shift, in one line
  • Correspondence table
  • Two worked examples
  • The FORT032 portability score
  • Backends (at call time)
  • See also
• JAX ↔ gt4py.next — the two functional targets
  • Why they share a front half
  • Side-by-side correspondence
  • The three that look alike but aren’t
  • The divergence that decides the target
  • Validation — two philosophies
  • What is identical
  • See also
• Geometry catalogue & software decomposition
  • The geometry catalogue
  • The decomposition it proposes
  • Spectral truncation is an alias, not a geometry
  • The grid imposes the decomposition
  • Interactive from an agent (MCP)
  • Why interactive
  • See also

Integrations

• Use fortranspire from Claude Code
  • Local skill (recommended)
  • Remote MCP (advanced)
  • Troubleshooting
• Use fortranspire from mistral-vibe
  • Prerequisites
  • Self-hosted runner on a Mac mini (stdio)
  • Talking to it in natural language
  • 5-minute demo on PHYEX
  • Alternative — permanent HTTP service (CI / LAN access)
  • Why both Claude Code and mistral-vibe?
  • Known gaps
• 🖥️ Tutoriel : Mode Interactif (Human-in-the-Loop)
  • 1. Pourquoi le mode interactif ?
  • 2. Activation du mode
  • 3. Lancement du pipeline Phase 1
  • 4. Déroulement de l’interaction
  • 5. Intégration MCP (IDE natif)
  • 6. Mode CI/CD (automatique)
• Claude Code GitHub Action — porting from a PR comment
  • Setup
  • Who can trigger it
  • The workspace jail
  • Secrets stay off the command line
  • What Claude is told to do
  • Cost control
  • Relationship to the other surfaces
• GitHub Copilot cloud agent
  • Two files, one setting
  • Smoke test
  • Secrets, if you ever need them
  • Limits worth knowing
  • Why not the porting tools too
• GitHub App — /fortranspire commands on issues and PRs
  • Commands
  • What the App will not do
  • Setup
  • How a request flows
  • Operating notes
• Le Chat connector — hosted MCP for Mistral’s agent surface
  • What the public connector exposes — and what it deliberately does not
  • Deploy on a small EU VPS
  • Register with the directory
  • Acceptance
  • Relationship to the other MCP surfaces

Reference

• API reference
  • fortranspire.server
  • fortranspire.config
  • fortranspire.agent.code_agent
  • fortranspire.agent.cli
  • fortranspire.agent.translation_graph
  • fortranspire.agent.translation_graph_phase1
  • fortranspire.tools.file_tools
  • fortranspire.tools.search_tools
  • fortranspire.tools.shell_tools

Project

• Contributing to fortranspire
• Security Policy
• Code of Conduct
• Changelog

Indices

• Index

• Module Index

• Search Page