Running the Simulation

7.1 What SIMULATE Does

Behind the single click, the platform runs a pipeline of steps. Understanding them helps when something goes wrong — you'll know which step failed.

7.1.1 The simulation pipeline

Every simulation performs the same core operation: mapping your conceptual model (xyz) onto the numerical grid (ijk), then solving flow equations on the ijk representation. The conceptual model is what you built — zones, wells, polylines, layers, and attributes at their real-world coordinates. The numerical model is the grid-based approximation — cells with one value each, indexed by row/column/layer. Discretization is the xyz → ijk mapping, and it happens fresh on every SIMULATE. This is why you can edit your conceptual model freely between simulations — the grid doesn't persist in the way the conceptual model does; it gets rebuilt each time from whatever the current conceptual model looks like. See Ch. 1 §1.5.1 for the full conceptual-vs-numerical framing.

The SIMULATE pipeline in detail:

7.1.2 The real-time streaming difference

IGW-NET's native IGW solver is real-time streaming. Results arrive as the solver computes them — you watch heads converge, plumes migrate, and particles animate while the simulation is still in progress. This is different from a traditional batch solver, where the simulation runs to completion and only then produces outputs.

7.2 Simulation Settings

Most simulation behavior is controlled from a single tab in Domain Attributes. For steady-state base models, you rarely need to touch these settings. For transient, multi-layer, or refined work, this is where you configure the solver.

7.2.1 Opening Simulation Settings

7.2.2 What the fields mean

7.2.3 The solver options

7.3 Grid Resolution

Grid NX controls how coarsely or finely your conceptual model (xyz) is approximated by the numerical model (ijk). It is the single setting that most directly trades simulation speed for spatial detail — and deciding when to raise it, when to add sublayers, and when to use a submodel instead is one of the highest-leverage skills in IGW-NET. Each of these choices is ultimately the same question: where does the ijk approximation need to be faithful to the xyz reality, and where can a coarser approximation suffice?

7.3.1 How Grid NX works

NX is the number of cells along the longer side of your domain's bounding rectangle. For a domain that is 20 km × 10 km and NX = 40, the solver uses a 40 × 20 grid of 500 m × 500 m cells. Doubling NX to 80 produces 250 m × 250 m cells — roughly 4× as many cells overall, so simulation time roughly quadruples.

7.3.2 The "more resolution is always better" trap

A common instinct — especially among novices, students, and even experienced practitioners coming from other platforms — is that cranking NX higher produces a better model. Push NX to 200, 300, 500 — surely that gives a more accurate answer? This instinct is mostly wrong, and acting on it causes more real problems than almost any other grid-resolution decision.

What actually happens when you raise NX aggressively:

• Compute cost grows super-linearly. Doubling NX quadruples the cell count (2D) or octuples it (3D with sublayers), but simulation time often grows faster than that because solver iterations multiply. An NX = 300 run can be 10× slower than NX = 150, not 4×.
• Convergence deteriorates. Larger linear systems are more ill-conditioned. What converged cleanly at NX = 80 may iterate sluggishly at NX = 160 and may not converge at all at NX = 300. Adding resolution worsens numerical stability beyond a point.
• You may get nothing at all. A failed simulation returns no result — unlike the hope that "at least it'll be a fine-resolution answer," a brute-force attempt that doesn't converge leaves you with neither fine nor coarse. A converged coarse model beats a failed fine one every time.
• Most of the fine resolution is wasted. In a large domain, the features that actually need fine resolution typically occupy a small fraction of the area. Uniformly raising NX over the whole domain is paying fine-grid compute cost for regions where coarse cells would have been perfectly adequate.

This connects directly to Ch. 13 §13.5.1's four-dimension argument for hierarchy. The same reasoning that makes hierarchical models better for cognition, management, and infrastructure also makes them better numerically — a hierarchy of well-posed small problems is easier to solve, debug, and iterate than one big problem at the edge of numerical stability. "More resolution" is not the answer; "hierarchical resolution" is.

7.3.3 When to raise NX

• When cells are obviously too large to resolve features of interest (e.g., a 1 km river on a 2.5 km grid).
• When pumping wells, point sources, or sharp features produce visibly "blocky" results in the head field.
• When convergence is fine but the physics being simulated has scales smaller than the grid can see.
• But — before raising NX, ask whether the detail you need is uniform across the domain (raise NX) or localized (use a submodel instead; see §7.3.4).

7.3.4 When NOT to raise NX (use submodels instead)

If you only need fine resolution in a specific subarea, raising NX on the whole parent is wasteful. A 100 km × 100 km domain at NX = 160 has 25,600 cells; most of those cells are in regions where coarser resolution would be perfectly adequate. The submodel approach — parent at NX = 40, submodel covering the area of interest at NX = 80 or higher — gives you the same local detail for a fraction of the computational cost and keeps each individual simulation well-posed (§7.3.2).

7.4 Sublayers and Vertical Discretization

IGW-NET's default 2D solution (1 sublayer) handles most regional and site-scale flow problems. For cases where vertical variation matters, sublayers turn a conceptual layer into a fully 3D computational stack.

7.4.1 What sublayers do

A sublayer value of N means each conceptual layer is subdivided into N computational layers in the vertical. The solver then computes heads, flows, and concentrations in all three dimensions — including vertical head gradients, downward seepage, upward discharge, and vertical plume migration. How the subdivision is positioned vertically matters as much as the number — see §7.4.3 below for the water-table-as-top approach that keeps the subdivision numerically well-posed.

7.4.2 When to increase sublayers

7.4.3 How sublayers are positioned vertically — and why water table as top matters

When you set Number of SubLayers = N, IGW-NET subdivides each conceptual layer into N computational layers. But there is a crucial question this raises: what defines the top elevation of the uppermost sublayer? The answer matters enormously for numerical stability and for getting a defensible 3D solution.

Why conceptual layers exist in the first place

Before discussing how to subdivide, a reminder of what a conceptual layer is. Conceptual layers in IGW-NET are chosen to follow major geological units in the xyz reality. A typical regional model of unconsolidated sediments overlying bedrock has one conceptual layer: the unconsolidated aquifer. The conceptual bottom is the bedrock top (from the Data Center or a site-specific raster). The conceptual top defaults to the DEM — the land surface — because for an unconfined aquifer there's no formal upper geological boundary; the aquifer extends up to the water table, which itself sits somewhere below the DEM.

Multiple conceptual layers are used when the geology genuinely has multiple distinct hydrogeologic units — e.g., an upper unconfined aquifer, an intermediate aquitard, and a deep confined aquifer. Each conceptual layer has its own top, bottom, and attributes. Sublayers then subdivide each of those conceptual layers for finer vertical resolution within each geological unit.

The naive approach — subdividing with DEM as the top

The straightforward interpretation of "subdivide the conceptual layer into N sublayers" is to divide the gap between the DEM (top) and the bedrock top (bottom) into N equal parts. This seems obvious, and it is what many simpler platforms do. But it produces a serious problem for unconfined aquifers:

• The DEM has local microtopography everywhere. Small pits, mounds, gullies, buildings, and measurement noise produce rapid up-and-down variation at the sub-10-meter scale. The DEM is the land surface, not the top of the saturated aquifer.
• The real top of the saturated zone is the water table, which is a smooth surface sitting 1–20 meters below the DEM on average, not tracking the DEM's microtopography.
• Subdividing with DEM as top produces chaotic sublayer thicknesses. Where the DEM dips into a small valley, the uppermost sublayer becomes very thin; where the DEM rises on a mound, it becomes thick. Adjacent cells in the upper sublayer can have thicknesses differing by 10× or more.
• This produces dry cells. The uppermost sublayer is above the water table in most places (since the DEM is above the water table). A "cell" above the water table has no saturated thickness — it's dry. The solver handles dry cells, but poorly: iterations multiply, convergence degrades, results become unreliable. On a coarse NX it might work; on finer NX with many sublayers, you get a numerical disaster.

The underlying problem — unconfined flow is nonlinear

The water-table question is not a minor inconvenience. It is a manifestation of one of the well-known hard problems in computational groundwater modeling: unconfined flow is a nonlinear free-surface problem. The top of the saturated aquifer — the water table — is itself an unknown that depends on the solution. Flow equations are written for saturated conditions; the elevation of the saturated zone is what the flow field determines; but solving the flow field requires knowing where the saturated zone is. This circular dependence makes unconfined flow a nonlinear problem that no amount of standard linear-solver sophistication resolves on its own.

The traditional approach in conventional modeling platforms is a fully nonlinear coupled iteration within each simulation: guess a water table, build the cell geometry based on that guess, solve the flow field, update the water table from the result, rebuild cell geometry, solve again, repeat until both the water table and the head field simultaneously converge. This works in principle but is fragile and slow. Each outer iteration rebuilds the grid, introduces step-wise changes to cell thicknesses (cells near the water table can suddenly appear or disappear — the "re-wetting" and "de-wetting" problem), and destabilizes the inner linear solve. Convergence failures are common, especially with many cells, sharp gradients, or thin unconfined layers. Users of traditional platforms know the symptoms: solutions that take forever, diverge entirely, or converge to different answers depending on starting conditions.

The IGW-NET approach — linearize within, iterate between

IGW-NET takes a different approach: linearize the problem within each individual simulation, and iterate between simulations. The mechanism is the Water Table as Top flag combined with the exchange field — IGW-NET's internal mechanism for carrying state between successive simulations.

Within each simulation, the top of the uppermost sublayer is fixed — taken from the previous simulation's head field via the exchange field. With a fixed top, the sublayer geometry is fully determined before the solver runs: every cell has a known thickness, every cell is guaranteed saturated, no re-wetting/de-wetting can happen mid-solve. The flow equations become a clean linear problem — the kind that standard solvers handle in seconds with robust convergence. No nonlinear outer loop is needed inside the simulation.

The nonlinearity doesn't disappear, but it moves outside the simulation: each simulation produces an updated head field; if that updated water table differs meaningfully from the top elevation that was used, you re-simulate with the new head as the new top. This outer loop converges very quickly because the 2D-to-3D correction is usually small — the water table the 2D solve produces is already a good approximation, and the 3D correction is a modest perturbation rather than a dramatic restructuring. One or two iterations typically suffice; convergence of the outer loop is essentially free compared to solving the nonlinear problem monolithically.

The practical workflow

When to skip water table as top

One case where you don't use Water Table as Top: deeply confined aquifers, where the conceptual layer's top is a confining unit (not the land surface) and the aquifer is always fully saturated under pressure. In that case the conceptual layer's top is already a physically-defined elevation (the bottom of the overlying aquitard or confining unit), and subdividing directly produces well-posed sublayers without water-table iteration. For such cases, Water Table as Top should be off.

For everything else — shallow unconfined aquifers, regional unconsolidated-sediment systems, most site-scale studies — Water Table as Top is the right default once you move from 1 sublayer to more.

7.5 Transient Simulation

Steady-state simulation answers the question "what is the long-term flow pattern?" Transient simulation answers "how does the system respond to changes over time?" The setup is slightly more involved but follows a predictable pattern.

7.5.1 The transient workflow

7.5.2 The "never accumulate" architecture

As Chapter 1 §1.3.6 noted, IGW-NET operates on one architectural principle across transient flow, Monte Carlo, particle tracking, and transport: simulate, analyze, visualize, discard. Running statistics — mean fields, variance maps, cumulative fluxes, exceedance probabilities — are updated on the fly as each time step or realization completes; the underlying snapshot is then discarded. Memory usage stays constant regardless of how long or how deep the simulation runs.

This is not a clever optimization. It is the only architecture that lets a cloud-native service handle serious modeling — long-horizon transient simulations, probabilistic capture-zone analyses that need hundreds of realizations to converge, high-resolution particle tracking over decades. Platforms that accumulate snapshots in memory hit limits quickly and compromise by running shortened simulations, fewer realizations, or coarser resolution. IGW-NET refuses that trade by never accumulating the data in the first place.

7.5.3 When to save time snapshots

• When producing figures for a publication — you need specific time snapshots (e.g., year 1, year 5, year 10) preserved exactly.
• When doing frame-by-frame video analysis of plume migration.
• When you plan to re-analyze the simulation with different post-processing without rerunning.

For exploratory work, live streaming with running statistics is the faster path. For archival work, saving snapshots at key times is the right choice.

7.6 When Things Go Wrong

The base model is designed to always converge. When it doesn't, something specific in your refinement has introduced numerical difficulty. Here are the common failure modes and how to diagnose them.

7.6.1 Dry cells

A dry cell is a grid cell where the computed head has fallen below the aquifer bottom — meaning the aquifer thickness at that cell is zero. Dry cells have zero transmissivity, so the solver can't move water through them, and nearby heads can swing wildly.

Common causes:

• Bedrock raster too close to surface. If you switched the aquifer bottom from the default constant to a Data Center bedrock raster, and the bedrock rises to near-surface somewhere in the domain, those cells are thin enough that local drawdown dries them out. Fix: revert to the constant bottom, or add a minimum-thickness floor.
• Very low K locally. A zone with K set very low can produce huge drawdowns at any pumping well nearby. Fix: check K values in zones, look for values that are orders of magnitude lower than neighbors.
• Pumping rate too high. A well pumping at an unsustainable rate for the local K and aquifer thickness will eventually dry out its cells. Fix: reduce pumping, or check that Q is correctly specified (in m³/day, with correct sign).

7.6.2 Non-convergence with no clear cause

If the solver reports non-convergence but there are no obvious dry cells or extreme gradients:

1. Re-run the base model. Revert your recent refinements to the base model — if it converges, your refinement introduced the issue. Re-apply changes one at a time to isolate which one.
2. Relax convergence tolerance. If the residual is just above threshold, loosening tolerance is a pragmatic fix. Be honest with yourself: a loosely-converged solution is approximate, and you should note this when using results.
3. Check for features near boundaries. A well too close to a no-flow boundary, or a polyline that straddles it, can create local numerical difficulty.
4. Check the projection. In rare cases, an inappropriate projection for a very large domain can introduce numerical issues. Re-accept the default UTM suggestion.

7.6.3 Slow simulation

If simulation is taking noticeably longer than expected:

• Grid NX may be higher than necessary. Reduce for exploration, raise again for final runs.
• Sublayers may be too many for the problem. Use 1 for 2D studies, 3-5 for most 3D needs.
• The domain may be too large for the question. Consider a smaller domain with a submodel for detail.
• Network issues may be slowing streaming. Usually transient; try again.