NVIDIA Simulation Skill
This skill provides tools for executing and managing simulations.
Overview
The Simulation skill enables agents to:
- Run simulations from simulator input files
- Run and heal run + auto-fix on failure, it will launch both run and monitor in one go from user input files
- Monitor simulation progress and status
- Stop running simulations when needed
- Manage simulation processes and output directories
Tools
run_and_heal
Runs a simulation and, on failure, automatically parses PRT errors, optionally consults RAG (simulator_manual, simulator_examples), and produces a fixed DATA file. Implemented as a chain: run_simulation in parallel with PRT wait + error parsing; if errors are found, extract keyword, call RAG tools if config is available, then create a fixed DATA file (e.g. *_FIXED.DATA).
Implementation: simulator_agent/tools/self_heal_chain.py
Usage (script):
python -m simulator_agent.tools.self_heal_chain \
--prt-loc-dir /path/to/output/ \
--data-file /path/to/CASE.DATA \
[--config /path/to/config.yaml] \
[--output-file /path/to/output/]
Parameters: data_file, output_dir (optional), num_mpi_processes (default: 1, for MPI parallel runs with np>1).
When to use:
- When the user wants to run a case and automatically attempt to fix and re-run on simulation failure (run-and-heal flow).
- Alternative to manual run_simulation → inspect failure → patch_simulation_input_keyword/modify_simulation_input_file → run_simulation.
run_simulation
Runs a simulation from a DATA file. Supports both foreground (wait for completion) and background (return immediately) execution.
Usage:
run_simulation(
data_file: str,
output_dir: Optional[str] = None,
num_threads: int = 1,
num_mpi_processes: int = 1,
additional_args: Optional[str] = None,
background: bool = True
) -> str
Parameters:
data_file: Path to the simulator input (DATA) file to runoutput_dir: Optional output directory (default: same directory as DATA file)num_threads: Number of threads for parallel simulation (default: 1)num_mpi_processes: Number of MPI processes (np). When > 1, runs viampirun -np N flow ...(default: 1). SetOPM_MPI_LAUNCHER=mpiexecto use mpiexec instead.additional_args: Optional additional command-line argumentsbackground: If True, start and return immediately. If False, wait for completion and return full report including return code, stdout, stderr, and parsed PRT errors on failure.
Example:
run_simulation(
data_file="SPE1CASE1_AGENT_GENERATED.DATA",
output_dir="/path/to/output",
num_threads=4,
background=False
)
Returns:
- Background mode: Simulation start confirmation with PID, output directory, and log paths
- Foreground mode: Full completion report with return code, stdout, stderr, and PRT errors (if failed)
When to use:
- Direct run (TOOL_DECISION_TREE.md Section 2.3) when user provides DATA file path + run intent
- After scenario modifications (Section 2.4) to execute the modified case
- HITL confirm run flow (Section 2.1) after user confirms
- After auto-fix (Section 2.2) to re-run the fixed case
monitor_simulation
Monitors the progress of a running simulation by reading the PRT file.
Usage:
monitor_simulation(
output_dir: str,
tail_lines: int = 80,
use_llm_summary: bool = False,
llm_model: Optional[str] = None
) -> str
Parameters:
output_dir: Directory containing simulation output files (must contain .PRT file)tail_lines: Number of lines to read from end of PRT file (default: 80)use_llm_summary: If True, use LLM to summarize the PRT tail (default: False)llm_model: Optional LLM model override for summary
Example:
monitor_simulation(
output_dir="/path/to/output",
tail_lines=100,
use_llm_summary=True
)
Returns: Simulation status (running/completed/failed) and PRT tail content, optionally with LLM summary.
When to use:
- When user asks to check simulation progress (Section 3.5, LLM choice)
- For background runs to track completion
- When debugging simulation issues
stop_simulation
Stops a running simulation by process ID.
Usage:
stop_simulation(
pid: int,
output_dir: Optional[str] = None,
force: bool = False
) -> str
Parameters:
pid: Process ID of the simulation to stopoutput_dir: Optional output directory with run metadataforce: If True, use SIGKILL (force kill). If False, use SIGTERM (graceful shutdown).
Example:
stop_simulation(
pid=12345,
output_dir="/path/to/output",
force=False
)
Returns: Confirmation message with PID, signal used, and metadata update status.
When to use:
- When user requests to stop a running simulation (Section 3.5, LLM choice)
- For process management and cleanup
Workflow Integration
This skill integrates with the Simulator Agent's decision tree (TOOL_DECISION_TREE.md):
Direct Run (Section 2.3):
run_and_heal (optionally after HITL confirm)Scenario Test Chain (Section 2.4):
parse_simulation_input_file → simulator_manual → simulator_examples → modify_simulation_input_file → run_and_healHITL Confirm Run (Section 2.1):
User confirms → run_and_healAfter run_and_heal (Section 3.3):
run_and_heal → (auto-fix if failed) → summarizeMonitoring (Section 3.5):
monitor_simulation (via LLM choice) stop_simulation (via LLM choice)
Implementation Details
Tools are implemented as LangChain tools with Pydantic input schemas. The skill uses:
- Subprocess management: For running Flow executables
- Process tracking: PID and metadata stored in run.json
- Output parsing: PRT file parsing for progress and errors
- Error handling: Comprehensive error messages and failure reporting
Error Handling
All tools return descriptive error messages if:
- DATA files are not found
- Flow executable is not available
- Output directories cannot be created
- Processes cannot be stopped
- PRT files cannot be read
Environment Variables
OPM_PROJECT_ROOT: Used to resolve paths in Docker environmentsOPM_FLOW_EXTRA_ARGS: Additional arguments passed to Flow (e.g.,--CheckSatfuncConsistency=0)
References
- Tool Decision Tree - Routing logic
- Simulation Tools README - Detailed tool documentation