Automated Run-Time Control of TOUGH4 Simulations Using OpenCLAW

Hi everyone,

I’d like to share an approach we’ve been using to automatically monitor and steer TOUGH4 simulations during run-time, without modifying TOUGH4 source code. This is based on combining TOUGH4’s built-in run-time parameter update capability with a lightweight external AI agent call OpenCLAW.

The motivation is simple: for large, nonlinear simulations (multiphase, compositional, phase transitions, etc.), fixed numerical settings chosen before the run are often not optimal for the entire simulation.

What is OpenCLAW?

OpenCLAW is an AI agent which can be used as supervisory tool that:

• Monitors TOUGH4 log/output files while the simulation is running

• Diagnoses numerical behavior (e.g., convergence difficulty, frequent time-step cuts)

• Adjusts TOUGH4 computing parameters dynamically during execution

Think of it as a “numerical autopilot” that sits outside TOUGH4 and reacts to what the simulation is doing.

Importantly:

• No TOUGH4 source-code changes are required

• It works entirely through files TOUGH4 already reads and writes

Why This Works Well with TOUGH4

TOUGH4 already supports run-time modification of numerical parameters, including:

• Simulation end time (SimulationTimeEnd)

• Maximum time step (MaxTimeStep)

• Newton convergence criteria (relative, absolute, PV limits)

• Maximum Newton iterations

• Time-step reduction factor

• SAVE / time-series output frequency

• Program options via the IE array

• Monitoring of selected elements or connections

All of these can be updated through a text file named:

Parameter_Update_File

TOUGH4 periodically scans this file during the run. If it detects changes made after the simulation starts, it immediately applies them.

This file-based interface is what OpenCLAW uses as its control channel.

How OpenCLAW Operates 

1. Monitor
   OpenCLAW continuously parses TOUGH4 log files, looking at:

   • Number of Newton iterations

   • Time-step acceptance/rejection

   • Repeated convergence failures

   • Phase changes at key locations

   • Time-step size and convergence behavior

2. Decide
   Based on predefined rules (currently heuristic / rule-based) or  any rules and actions that users provided:

   • Is the time step too aggressive?

   • Are Newton tolerances too tight or too loose?

   • Do we need more diagnostics at a specific element or connection?

3. Act
   OpenCLAW updates Parameter_Update_File to:

   • Reduce or increase time-step size

   • Adjust convergence criteria

   • Change SAVE or time-series output frequency

   • Activate monitoring for specific elements or connections

   • Change program options (through IE array)

TOUGH4 then picks up these changes automatically during its next scan.

Typical Use Cases

Some examples where this has been useful:

• Tightening Newton tolerances only during phase appearance/disappearance

• Automatically reducing time-step size after repeated NR failures

• Increasing output frequency temporarily to diagnose a local instability

• Relaxing conservative settings once the system becomes stable again

• Stop simulation at certain condiitons

• Monitoring fluid behavior at any elements and connections.

This avoids both:

• Overly conservative settings for the entire run

• Manual stop–edit–restart cycles

Advantages

• No source-code modification of TOUGH4

• Improves robustness of long, nonlinear simulations

• Reduces manual trial-and-error tuning

• Enables targeted diagnostics only when needed

• Natural path toward more intelligent / automated workflows

Final Thoughts

TOUGH4 already provides the hooks needed for adaptive control. OpenCLAW simply exploits those hooks in a systematic way. In practice, this turns TOUGH4 into a self-adjusting simulation system rather than a static one.