Solver Options Reference — gmSolverID Position Map and Parameters

24.1 The gmSolverID Position Map

gmSolverID is one of IGW-NET's most important fields. It is also one of the most opaque without a position map. This section is that map.

24.1.1 Structure of gmSolverID

The gmSolverID field is a comma-separated string with optional colon separator. The parser's default when the field is missing: "15,4000,0.0001,1.0".

Basic layout:

solverID,maxIter,tolerance,damping[:transportFlags][,pos4,pos5,...,densityFlag,autoCalib,nRealizations,MFsolverStr]

In practice the parser's .solver property handles the colon-separated transport split and decodes positions 0-3 for flow; the .stochastic, .refined_grid, and related properties decode positions 17-20 for engine flags.

24.1.2 Complete position catalog

The parser decodes all of this into readable form; users shouldn't need to edit gmSolverID directly in most cases. The Solver Options dialog provides the UI for adjusting these values.

24.2 Flow Solver Variants

Position 0 of gmSolverID selects the flow solver algorithm. The parser catalog SOLVER_NAMES lists the options.

24.2.1 The native IGW flow solvers

24.2.2 MODFLOW 6 IMS — activated automatically

When the model has an unstructured grid with local refinement (Ch. 13 nested-model pattern), the native IGW solvers cannot proceed — only MODFLOW 6 with IMS (Iterative Model Solution) handles DISV discretization. IGW-NET detects this automatically and activates MODFLOW 6 IMS via position 20 MFsolverStr. The flow solver ID in position 0 becomes less meaningful in this case; MF6 IMS is the actual solver in use.

The parser's .refined_grid property detects this case (line 1000 of the parser) and reports: "This model uses an unstructured grid with local refinement... This requires the MODFLOW 6 solver (DISV discretization)."

24.2.3 MODFLOW-NWT — for difficult unconfined problems

MODFLOW-NWT (Newton-Raphson variant, Ch. 20 §20.3.3) is available for unconfined-aquifer problems where wetting-drying cells cause convergence issues. NWT's Newton-Raphson formulation handles these transitions more robustly than classical Picard iterations. Selecting NWT goes through the MFsolverStr configuration at position 20 rather than the basic solver ID at position 0.

24.3 Convergence Parameters

Positions 1-3 control how the iterative solver decides it has converged. These are the parameters you're most likely to adjust when a simulation doesn't converge cleanly.

24.3.1 Max iterations (position 1)

Default: 4000

The maximum number of iterations the solver will take before giving up. If the iteration count reaches this limit, the solver terminates — with whatever solution it had at the last iteration, whether or not the convergence criterion was met.

• Default 4000 is adequate for most structured-grid problems. Most well-posed problems converge in a few hundred iterations.
• Increase to 8000 or 16000 for slowly-converging problems that would eventually reach tolerance — large domains, strong nonlinearities (unconfined with significant wetting/drying), T-PROGS models with extreme K contrasts.
• If 16000 isn't enough, the issue is almost certainly not iteration count — it's a conceptual or parameterization problem. Stop increasing iterations and diagnose the real cause.

24.3.2 Convergence tolerance (position 2)

Default: 0.0001 m

The convergence criterion: iteration stops when the maximum head change between successive iterations falls below this value (in meters). Smaller tolerance = tighter convergence = more iterations needed.

• Default 0.0001 m (0.1 mm) is tight — appropriate for detailed work where local head gradients matter.
• Loosen to 0.001 m or 0.01 m for regional-scale modeling where this level of precision isn't needed. Faster convergence; adequate for regional flow patterns.
• Tighten below 0.0001 m only when specific sensitivity analysis requires it; usually not worth the extra iterations.

24.3.3 Damping factor (position 3)

Default: 1.0 (no damping)

The damping factor scales the head change applied at each iteration. Damping = 1.0 applies the full iteration step; damping = 0.5 applies half; damping = 0.3 applies 30%. Reduced damping slows convergence but stabilizes iterations that oscillate.

• Use 1.0 by default. Most problems don't need damping.
• Reduce to 0.5 if iterations oscillate — head changes swinging positive-negative between iterations without settling.
• Reduce further (0.3, 0.2) for strongly nonlinear unconfined problems where the free-surface iteration causes feedback loops.
• Trade-off: lower damping needs more iterations but is more likely to actually converge.

24.4 Transport Solver Options

When solute transport is active (Ch. 12), the gmSolverID string has a colon separator followed by transport-specific options. IGW-NET offers two transport solvers.

24.4.1 The colon separator

A colon in gmSolverID marks the end of flow options and the start of transport options. Example structure:

"15,4000,0.0001,1.0:0,1"

The "1" after the colon in position 1 indicates Magnet native transport. "0" would indicate MT3D.

24.4.2 Transport solver choice

For typical in-platform use, Magnet native transport is the right choice. MT3D becomes relevant when exporting for regulatory workflows that expect MT3D output (Ch. 20).

24.5 Engine-Selection Flags (Positions 17-20)

The higher positions of gmSolverID carry flags that trigger engine escalation — switching from the native IGW solver to MODFLOW 6, adding UCODE for calibration, enabling SEAWAT for density flow, or activating stochastic simulation.

24.5.1 Position 17 — Density flow flag

When this flag is set, SEAWAT activates for variable-density flow problems (coastal saltwater intrusion, brines, density-dependent plumes). Covered in Ch. 20 §20.1.1.

Default: 0 (disabled). Set to 1 when working with density-dependent problems. SEAWAT couples flow with solute density; the flow solve then depends on the salinity field, not just the prescribed K and boundaries.

24.5.2 Position 18 — Auto-calibration flag

When set, Automatic Calibration via UCODE activates. Covered in Ch. 18 §18.7.

Default: 0 (disabled). Set to 1 via the Automatic Calibration tool — UCODE then runs parameter estimation, varying the Calib-flagged multipliers (K, Recharge, others from DomainAttr → Aquifer Attributes → Multiplying Factors).

24.5.3 Position 19 — Monte Carlo realization count

When > 1 with auto-calibration (position 18) also active, Monte Carlo stochastic simulation runs. Covered in Ch. 19.

Default: 0 or 1 (single realization — deterministic). Set to larger values for ensemble analysis. IGW-NET's recursive-statistics architecture (Ch. 19 §19.6) means there's no storage-cost penalty for large realization counts.

24.5.4 Position 20 — MFsolverStr (MODFLOW variant)

JSON-encoded specification of the MODFLOW variant when MODFLOW is in use. Parsed by splitting on underscore and recognizing JSON content. The parser replaces "!" with "," inside the JSON (to avoid comma-collision with gmSolverID's outer comma-separated format) before JSON-parsing.

Structure (example): {"version":["mf6"]} indicating MODFLOW 6. Other possible values: mf2005, mfnwt, mfusg.

Default: null or "0" when the native IGW solver is active. Populated automatically when MODFLOW is triggered (unstructured grid → MF6; specific user override → whatever was selected).

The parser's .refined_grid property extracts this (line 1023 of the parser) to detect MF6 activation. Covered in Ch. 20 §20.1.3.

24.6 Convergence Troubleshooting

When a simulation doesn't converge, the fix is usually one of a small set of standard adjustments. This section catalogs them in order of typical effectiveness.

24.6.1 Diagnostic symptoms

Before adjusting, identify what's happening:

• Hits max iterations without converging — solver is making progress but slowly; more iterations may help
• Oscillates between iterations — head changes swing positive-negative; damping will help
• Converges to unreasonable heads — convergence is numerical but the solution is physically wrong; structural issue, not numerical
• Simulated heads above land surface — often the 10×-rainfall pitfall (Ch. 14 §14.7); check recharge units
• Wells go dry and simulation crashes — unconfined cells drying; switch to NWT

24.6.2 Escalation ladder