Plot and compare simulation summary metrics. Use when visualizing time-series results, comparing multiple cases, or analyzing production performance. Supports single and multi-metric plots, case comparisons, and automatic metric keyword resolution.
This skill provides tools for visualizing and comparing simulation results.
The Plotting skill enables agents to:
Plots one or more summary metrics from simulation outputs on the same plot.
Usage:
plot_summary_metric(
output_dir: str,
metric_request: str,
manual_hint: Optional[str] = None,
save_path: Optional[str] = None
) -> str
Parameters:
output_dir: Directory containing simulation output files (must contain .SMSPEC file)metric_request: User request or summary keyword(s). For multiple metrics on one plot, use comma-separated keywords (e.g., "FOPT, FWPT" or "FOPT,FWPT")manual_hint: Optional manual context or retrieved snippet to help map keywordssave_path: Optional path to save the plot imageExample:
plot_summary_metric(
output_dir="/path/to/output",
metric_request="FOPT, FWPT",
save_path="/path/to/plot.png"
)
Returns: Confirmation message with plot details and save path (if provided). Displays the plot.
When to use:
Metric Keywords: Common summary keywords include:
FOPT: Cumulative oil productionFOPR: Oil production rateFWPT: Cumulative water productionFWPR: Water production rateFGPT: Cumulative gas productionFGPR: Gas production rateWBHP: Well bottom-hole pressureWOPR: Well oil production ratePlots a summary metric for two or more cases on the same axes for comparison.
Usage:
plot_compare_summary_metric(
output_dir: str,
metric_request: str,
case_stems: Optional[str] = None,
case_paths: Optional[str] = None,
save_path: Optional[str] = None
) -> str
Parameters:
output_dir: Directory to save the plot and, when not using case_paths, directory containing .SMSPEC files to comparemetric_request: Summary keyword to compare (e.g., "FOPT" for cumulative oil, "FOPR" for oil rate)case_stems: Comma-separated case name stems to compare (e.g., "SPE10_TOPLAYER,SPE10_TOPLAYER_AGENT_GENERATED"). If omitted and case_paths not set, all .SMSPEC files in output_dir are compared.case_paths: Comma-separated paths to simulator input files (or .SMSPEC) for the cases to compare. Use when comparing cases from different directories (e.g., "BASE/SPE10.DATA,INFILL/SPE10_INFILL.DATA").save_path: Optional path to save the comparison plot imageExample:
plot_compare_summary_metric(
output_dir="/path/to/output",
metric_request="FOPT",
case_stems="SPE10_TOPLAYER,SPE10_TOPLAYER_AGENT_GENERATED"
)
Returns: Confirmation message with comparison plot details and save path (if provided). Displays the plot with different line styles for each case.
When to use:
This skill integrates with the Simulator Agent's decision tree (TOOL_DECISION_TREE.md):
Plot Results (Section 3.1):
User asks to plot → plot_summary_metric (if run_and_heal exists in history)
Compare Cases (Section 3.1):
User asks to compare → plot_compare_summary_metric (if multiple cases available)
After Simulation (Section 3.3):
run_and_heal → summarize → "Do you want me to plot the results?"
Tools are implemented as LangChain tools with Pydantic input schemas. The skill uses:
All tools return descriptive error messages if:
The tool automatically resolves metric keywords from user requests:
simulator_manual can help with keyword mapping