Read and analyze simulation binary output files. Use when extracting summary data, grid properties, or running flow diagnostics (time-of-flight, tracer, allocation, F-Phi, Lorenz) from completed simulations.
This skill provides tools for reading and analyzing simulation binary output files.
The Results skill enables agents to:
Reads time-series data from simulation summary files (.UNSMRY / .SMSPEC).
Usage:
read_simulation_summary(
case_path: str,
variables: List[str],
entities: Optional[List[str]] = None
) -> str
Parameters:
case_path: Path to the .DATA file (tool finds corresponding .SMSPEC file)variables: Summary variables to extract (e.g., ["FOPR", "FOPT", "WBHP"])entities: Optional well/group names to filter results (e.g., ["PROD1", "INJ1"])Example:
read_simulation_summary(
case_path="SPE1CASE1.DATA",
variables=["FOPR", "FOPT"],
entities=["PROD1"]
)
Returns: Summary data with time range, timesteps, and variable values.
When to use:
Reads static grid properties from initialization files (.INIT / .EGRID).
Usage:
read_grid_properties(
case_path: str,
properties: List[str]
) -> str
Parameters:
case_path: Path to the .DATA file (tool finds corresponding .INIT or .EGRID file)properties: Properties to extract (e.g., ["PORO", "PERMX", "PERMY"])Example:
read_grid_properties(
case_path="SPE1CASE1.DATA",
properties=["PORO", "PERMX"]
)
Returns: Grid dimensions, property statistics (min, max, mean), and property arrays.
When to use:
Note: Spatial visualization (grid structure, permeability, porosity, pore volume, pressure, saturation, etc.) is not in the tool catalog; the agent suggests using a GUI (e.g. ResInsight) for those (Section 2.0).
Runs flow diagnostics on simulation results using pyflowdiagnostics. Computes time-of-flight (TOF), tracer concentrations, flow allocation factors, F-Phi (flow-storage capacity) curves, and Lorenz coefficients.
Usage:
run_flow_diagnostics(
case_path: str,
time_step_ids: Optional[List[int]] = None,
) -> str
Parameters:
case_path: Path to the .DATA file (simulation must have been run with RPTRST FLOWS)time_step_ids: Report step IDs to analyze (e.g. [1, 2, 3]). Default: last report step from SMSPECRequirement: Simulation must include flux output in RPTRST:
RPTRST
BASIC=2 FLOWS PRESSURE ALLPROPS /
Output: Creates {case_stem}.fdout/ directory with JSON, CSV, Excel, and GRDECL files.
When to use:
This skill integrates with the Simulator Agent's decision tree (TOOL_DECISION_TREE.md):
Results Analysis (Section 2.6):
read_simulation_summary (via LLM choice)
read_grid_properties (via LLM choice)
run_flow_diagnostics (via LLM choice)
After Simulation (Section 3.3):
run_and_heal → summarize → optionally use results tools for detailed analysis
Tools are implemented as LangChain tools with Pydantic input schemas. The skill uses:
All tools return descriptive error messages if:
Tools automatically resolve output file paths from the DATA file path:
CASE.DATA → CASE.SMSPEC (summary)CASE.DATA → CASE.INIT or CASE.EGRID (grid properties)plot_summary_metric for visualization instead of raw data extraction