The pipeline that takes plain English to converged simulation results.
The simulation workflow orchestrator is the engine behind every SimPilot simulation. It takes a natural language description and executes a structured pipeline of research, setup, execution, and error recovery -- all without manual intervention.
Pipeline overview
Research
The agent searches the built-in knowledge base to find similar simulation cases. Results include solver recommendations, directory layouts, and configuration patterns. If no relevant tutorials are found, the agent falls back to web search for published case studies and forum solutions.
Detailed Templates
With a solver identified, the agent retrieves configuration templates, execution scripts, and command references in parallel. These results form the template that guides all subsequent file generation.
Case Setup
The agent creates the solver-specific directory structure. For OpenFOAM, this scaffolds:
The structure varies by solver -- the active solver plugin defines which directories and files are required.
Geometry Import
When the user uploads a geometry file (STEP, STL, or OBJ), this intermediate step runs before meshing:
Imports the geometry file into the case directory
Performs bounding box analysis to determine spatial extents
Classifies the flow type (internal, external, or mixed) based on geometry topology
Sizes the computational domain relative to the geometry bounds
This step is skipped for simple parametric geometries that can be defined directly in the mesh configuration.
Mesh Setup
The agent configures the computational mesh using one of four modes:
Standard (blockMesh) -- blockMesh background + snappyHexMesh refinement
Custom -- Import a pre-built .msh file
GMSH -- Agentic GMSH script generation with a 6-retry validation loop
Geometry (snappyHexMesh) -- Automated pipeline using imported geometry bounds
cfMesh -- Alternative automatic mesh generation via the cfMesh family
The mode is selected automatically based on the geometry source and user preferences.
File Generation
The agent iterates through the solver's defined file generation order, creating each configuration file in sequence. For OpenFOAM, this typically follows:
system/controlDict -- Simulation time, write intervals, output format
system/fvSchemes -- Discretization schemes for each equation term
system/fvSolution -- Linear solver settings and relaxation factors
constant/transportProperties -- Fluid properties
constant/turbulenceProperties -- Turbulence model configuration
0/* -- Boundary condition files for each field variable
Each file is generated with cross-file consistency -- previously written files are injected as context so boundary names, field variables, and solver settings remain synchronized.
Run Script Generation
The agent creates the execution script that chains all commands in the correct order (mesh generation, decomposition for parallel runs, solver execution, post-processing). A fallback script is also generated to handle common failure modes like mesh quality issues.
Pre-simulation inspection
Before executing any solver, the agent runs a mandatory pre-simulation inspection protocol. This includes mesh verification (checkMesh with quality thresholds), field file consistency checks (dimensions, patch names, required turbulence fields), scheme and solver consistency validation, and controlDict verification. The solver only proceeds after all checks pass. See Error Recovery for the full debugging protocols.
Step 7: Simulation and recovery
The execution phase is where the agent demonstrates its autonomous capabilities. The solver runs, the agent evaluates the command result, and recovery begins only when the evidence shows the run failed. Recovery is retry-aware: each attempted fix is tracked so the next retry can avoid repeating the same approach.
Recovery guardrails
Infrastructure errors (missing solver environment, command not found) trigger an early bail-out. Soft errors from completed runs (warnings that are not hard failures) are filtered and do not count as errors.
Error escalation strategy
The retry loop uses a tiered approach, escalating its diagnostic tools as failures accumulate:
Local evidence and targeted retrieval
On the first failure, the agent evaluates the command output, reads the smallest relevant local evidence, and gathers context in a fixed order: skills, agent_resources/, internal knowledge, memory, and official docs. Only the specific failing files are touched.
This handles the majority of cases: typos in boundary names, incorrect solver settings, missing field files, and mesh-quality configuration mistakes.
Retry history and different fixes
When failures persist, the agent compares the new failure against prior attempts. Retries are classified as fixed, still failing, or different error. If a prior fix failed, the next retry should take a materially different approach instead of repeating the same edit.
Diagnostician and web escalation
If the root cause is still unclear or the failure keeps shifting, the agent can delegate focused diagnosis to agent("error-diagnostician"). Web search and direct URL retrieval remain available as late-stage escalation tools for official documentation, issue trackers, and community references not already captured locally.
Recovery cycle
Each iteration follows this sequence:
Run -- Execute the solver
Evaluate -- Classify the result as success, explicit failure, or silent solver failure
Gather context -- Pull targeted evidence from skills, local references, knowledge, memory, docs, and only then the web if needed
Fix -- Apply a narrow file edit or configuration change tied to the diagnosed cause
Retry -- Rerun and compare the outcome against prior attempts
Autonomous error-fix agent
SimPilot includes a dedicated error-diagnostician subagent for focused troubleshooting. It can inspect logs with read-only commands, gather docs and memory context, and recommend the next targeted fix when the primary workflow needs deeper diagnosis.
Post-run processing
On successful convergence, the workflow automatically:
Extracts quantities -- Drag, lift, pressure drop, residuals, and other metrics are extracted from solver output and cached for future queries
Generates a report artifact -- A rich document artifact is produced with sections for executive summary, setup details, mesh quality, solver settings, convergence data, results, and provenance
The report appears as a document artifact in the chat and can be exported as PDF, HTML, or Markdown. Visualization is handled by the post-processing phase of the pipeline -- see Engineering Pipeline for details. Interactive dashboards can also be generated -- see Interactive Dashboards.
Final report
The report includes:
Executive summary -- Key findings and simulation outcome
Setup details -- Solver, boundary conditions, and physical properties
Convergence -- Final residual levels for each solved field
Key results -- Physical quantities like forces, flow rates, pressure drops, or temperatures
Error recovery log -- If retries were needed, a summary of what went wrong and how it was fixed
Provenance -- Which knowledge base sources influenced the configuration
Continuing after completion
The workflow is not a dead end. After the report, you can ask follow-up questions, extract specific quantities, request different visualizations in the 3D viewer, modify parameters, or launch a parameter sweep -- all within the same conversation.