OpenParable
Skip to content
← Back to skills

Plot Skill

Documents
plot_skill

Plot Skill is an Agent Skill for documents published in the NVIDIA/GenerativeAIExamples repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/NVIDIA/GenerativeAIExamples/blob/HEAD/industries/energy/simulation-workflow-agent/sim_agent/src/simulator_agent/skills/plot_skill/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/plot-skill, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Plotting Skill

This skill provides tools for visualizing and comparing simulation results.

Overview

The Plotting skill enables agents to:

  • Plot summary metrics from simulation outputs
  • Compare multiple cases on the same plot
  • Visualize time-series data (rates, cumulative production, etc.)
  • Resolve metric keywords automatically from user requests

Tools

plot_summary_metric

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 keywords
  • save_path: Optional path to save the plot image

Example:

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:

  • After simulation run when user asks to plot results (TOOL_DECISION_TREE.md Section 3.1)
  • When user requests specific metrics (e.g., "Plot cumulative oil production")
  • For visualizing time-series data from completed simulations

Metric Keywords: Common summary keywords include:

  • FOPT: Cumulative oil production
  • FOPR: Oil production rate
  • FWPT: Cumulative water production
  • FWPR: Water production rate
  • FGPT: Cumulative gas production
  • FGPR: Gas production rate
  • WBHP: Well bottom-hole pressure
  • WOPR: Well oil production rate

plot_compare_summary_metric

Plots 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 compare
  • metric_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 image

Example:

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:

  • After running multiple cases when user asks to compare (Section 3.1)
  • For comparing baseline vs modified scenarios
  • When analyzing differences between simulation cases

Workflow Integration

This skill integrates with the Simulator Agent's decision tree (TOOL_DECISION_TREE.md):

  1. Plot Results (Section 3.1):

    User asks to plot → plot_summary_metric (if run_and_heal exists in history)

  2. Compare Cases (Section 3.1):

    User asks to compare → plot_compare_summary_metric (if multiple cases available)

  3. After Simulation (Section 3.3):

    run_and_heal → summarize → "Do you want me to plot the results?"

Implementation Details

Tools are implemented as LangChain tools with Pydantic input schemas. The skill uses:

  • EclReader: Apache-2.0 reader for .SMSPEC/.UNSMRY summary files
  • Matplotlib: For generating plots
  • Metric resolution: Automatic keyword mapping from user requests
  • Time axis handling: Supports both date-based and step-based time axes

Error Handling

All tools return descriptive error messages if:

  • Output directories are not found
  • .SMSPEC files are missing
  • Requested metrics are not available
  • Case files cannot be found
  • Plot generation fails

Metric Resolution

The tool automatically resolves metric keywords from user requests:

  • Direct keywords (e.g., "FOPT") are used as-is
  • Natural language (e.g., "cumulative oil production") is mapped to keywords
  • Manual hints from simulator_manual can help with keyword mapping
  • Multiple metrics can be plotted together using comma-separated keywords

References