Simulation

The Simulation module is the layer that transforms the 3D scene from a static representation into a predictive tool. Based on a built subsurface model, one or more source points, and propagation hypotheses, the engine calculates the spatial and temporal evolution of contaminants. This page outlines the module, its inputs, its outputs, and how the technical sub-pages interconnect.

What the Engine Simulates

The simulation engine covers the three major types of processes that determine the fate of a contaminant in the subsurface: transport (advection, dispersion), reaction (degradation, transformation), and matrix interaction (adsorption, desorption). Each of these processes can be enabled or disabled independently depending on the user's modeling goals.

Process	Modeled Phenomenon	Key Parameters
Advection	Contaminant movement with water flow	Darcy velocity, effective porosity
Dispersion	Longitudinal and transverse spreading of the plume	Longitudinal and transverse dispersivity
Molecular Diffusion	Spreading by thermal agitation in low-mobility zones	Diffusion coefficient
Adsorption	Reversible retention on the solid matrix	Kd, Koc, organic matter content
Degradation	Chemical or biological transformation of the compound	Rate constant k, degradation pathways
Redox Speciation	Change of form based on local pH and Eh	Eh-pH diagrams, equilibria
Isotopic Fractionation	Enrichment of the residual molecule	Epsilon per pathway

Engine Inputs

A simulation takes three families of inputs, which already exist within IsoFind and are simply consumed by the engine.

Input	Origin	Role
Subsurface	Stratigraphic layers defined in the scene	Local porosity, permeability, adsorption
Sources	Points or zones declared in the Simulation tab	Mass, flow rate, isotopic signature, duration
Boundary Conditions	Hydraulic gradient, inflows, fixed zones	Driving force of the flow
Target Compound	Molecular or elemental reference database	Determines Kd, k, applicable pathways
Geochemical Conditions	Measured samples or values imposed per layer	Adjusts kinetics and speciation locally

A simulation does not need to be calibrated against measurements to be useful: it can run in exploratory mode to assess a situation before field data is available. This is a common use case during the initial diagnostic phase to guide sampling strategy.

Engine Outputs

At each time step, the engine produces a set of 3D fields interpolated onto the calculation grid. These fields can be visualized in the scene using all available rendering modes (isosurfaces, cross-sections, volumes, points).

Output	Unit	Interpretation
Compound Concentration	mg/L, µg/L, ng/L depending on case	Extent and intensity of the plume
Metabolite Concentration	Same as parent compound	Degradation progress
Residual Isotopic Signature	‰	Enrichment linked to fractionation
Accumulated Mass	kg	Mass balance per zone
Residence Time	years	Apparent age at each point
Flux at Boundaries	kg/year	Outgoing contamination at boundaries

Time Step and Simulated Duration

The engine operates using explicit time steps. The total simulated duration and the time step are set by the user, with default values consistent with flow velocity and grid resolution. A time step that is too large can lead to numerical instabilities (automatically flagged); a step that is too small unnecessarily increases calculation time.

Typical Simulated Duration	Recommended Time Step	Use Case
A few days	1 to 6 hours	Recent leak, rapid transport
A few months to years	1 to 10 days	Active plume monitoring, remediation
Decades	1 month to 1 year	Legacy migration, PFAS, historical chlorinated solvents
Centuries to Millennia	1 to 10 years	Mining contexts, geological storage

Accessing the Simulation Module

3D Visualization > Simulation > New Scenario > Target Compound > Source & Boundary Conditions > Duration > Run

A scenario is a persistent object: it stores its input parameters and results. The latest simulation results are stored on the front-end in sessionStorage['isofind_sim_result'], allowing report blocks and hypothesis comparisons to consume them without re-calculation. Multiple scenarios can coexist in the same scene and be compared side-by-side in the dedicated multi-hypothesis page.

Residual ML Coupling

In parallel with the simulation engine, IsoFind offers local supervised learning to correct the gap between the geochemical prior (calculated by the Nexus bridge) and observations. This residual ML is a lightweight MLP trained on the δ_observed − δ_prior residuals at each sampling point.

Step	Endpoint	Description
1. Prior Calculation	POST /api/predict/prior	Returns δ_prior, f_reduced, f_mix, delta_mix, and residual for each point
2. Training	POST /api/predict/train	Sklearn MLP (ONNX output) on residuals, minimum 6 valid points
3. Inference	POST /api/predict/infer	Applies the model to the entire 3D grid to produce the corrected ML field
4. Model Status	GET /api/predict/model-status	Checks availability and metrics (MAE, RMSE, R², CV-MAE)

The MLP architecture adapts to the data volume: (32, 16) for fewer than 20 points, (64, 32) up to 50 points, and (128, 64, 32) beyond. The feature vector includes eleven inputs: normalized x, y, depth/depth_max, pH, Eh/500, DO/10, log10(Cr+1), reduced fraction, mixing fraction, delta_mix, and prior. The model is exported to ONNX when the skl2onnx dependency is available, enabling offline inference without Sklearn.

Residual ML is not a substitute for the Nexus bridge: it comes after, to capture local signals that the generic geochemical model might miss. A well-calculated prior limits the necessary correction, which is a good sign of consistency. Conversely, a high and spatially structured residual suggests an unmodeled process in the bridge that warrants investigation.

Module Sub-pages

The detailed operation of the engine is divided into three sub-pages, each addressing a specific question.

Engine Principles: Solved equations, numerical scheme, stability conditions.
Hydrogeological Parameters: Gradient, piezometry, boundary conditions, sources.
Speciation and Propagation: How reactions are coupled with transport.

Important Limits

The IsoFind engine is designed for exploratory simulations and decision support, not for certified regulatory modeling. For those purposes, specialized codes (MODFLOW, FEFLOW, COMSOL) remains the gold standard.

Simulations rendered by IsoFind rely on parameters whose uncertainty is often greater than the difference between two plausible scenarios. Presenting a simulation result as a precise numerical prediction is misleading; presenting it as a tool for qualitative understanding is accurate. The hypothesis comparison module exists to materialize this nuance.