plot-skill

# 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