科研技能库/绘图技能
图表可视化

plot_skill

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.

文件预览

7 个文件
assets
references
scripts
SKILL.md
5.6 KB · 可预览
---
name: plot_skill
description: 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.
license: Apache-2.0
metadata:
  author: sim-agent
  version: "1.0"
  category: simulator
compatibility: Requires matplotlib and simulation output files (.SMSPEC). Uses EclReader for summary (Apache-2.0).
---

# 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:**
```python
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:**
```python
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

- [Tool Decision Tree](references/TOOL_DECISION_TREE.md) - Routing logic
- [Simulation Tools README](../../tools/README.md) - Detailed tool documentation

SKILL.md

元数据
nameplot_skill
descriptionPlot 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.
licenseApache-2.0
metadata{ "author": "sim-agent", "version": "1.0", "category": "simulator" }
compatibilityRequires matplotlib and simulation output files (.SMSPEC). Uses EclReader for summary (Apache-2.0).

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:

python
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:

text
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:

python
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:

text
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):

    text
    User asks to plot → plot_summary_metric (if run_and_heal exists in history)
  2. Compare Cases (Section 3.1):

    text
    User asks to compare → plot_compare_summary_metric (if multiple cases available)
  3. After Simulation (Section 3.3):

    text
    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