User Interface Tutorial — 2D Steady Flow in Heterogeneous Aquifers

1 Interface Overview

The applet window is divided into three regions: a toolbar at the top, a main canvas in the center, and a data panel on the right.

Toolbar

Start

Properties

Head

Flow

Animation

Zoom Controls

Zoom In

⊙ Reset

Zoom Out

Main Canvas — domain grid, head contours, flow paths, particle cloud

Status bar — current step message and cursor coordinates

Data Panel

Head tab

Velocity tab

Paths tab

Export tab

Toolbar (top): Five step buttons (Start → Properties → Head → Flow → Animation) are enabled sequentially as each step completes. Three zoom controls sit below them.
Main canvas (center): Displays the domain, drawn head contours, K color map, flow paths, and particle cloud.
Data panel (right): Four tabs — Head, Velocity, Paths, Export — update live as the simulation progresses.
Status bar (bottom of canvas): Shows the current step prompt and cursor coordinates.

2 5-Step Workflow Overview

The applet is driven by five sequential steps shown in the toolbar. Complete them in order — each step unlocks the next.

Start Properties Head Flow Animation

1. Start

→

2. Properties

→

3. Head

→

4a. Flow (Path)

→

5a. Animation

or

4b. Flow (Particle)

→

5b. Animation

Step	Button	What it does
1	Start	Define the grid dimensions and hydraulic gradient.
2	Properties	Assign hydraulic conductivity and porosity to the domain — by zone, random, or Fgen92 field.
3	Head	Solve the steady-state flow equation (FEM) and draw head contours.
4a/4b	Flow	Choose flow-path tracking (click to place seed points) or particle-cloud mode (draw a polygon to seed particles).
5a/5b	Animation	Configure time step and playback speed, then click the canvas to start the animation.

3 Start — Define the Grid

Click Start to open the setup dialog. This defines the rectangular flow domain and the mean hydraulic gradient driving flow.

Parameter	Default	Description
Grid spacing (m)	10	Physical distance between finite element nodes. Smaller spacing gives finer resolution but a slower solve.
Number of columns	30	Number of grid columns in the x-direction. Domain width = columns × spacing.
Number of rows	20	Number of grid rows in the y-direction. Domain height = rows × spacing.
Average hydraulic gradient	0.01	Mean head gradient driving flow from left to right; sets the boundary head difference h₁ − h₂.

Click OK — the domain grid is drawn on the canvas and the Properties button becomes active.

4 Properties — Assign Hydraulic Conductivity

Click Properties to open the zone editor. Up to 5 zones are available, each with its own color, hydraulic conductivity K (m/s), and porosity (%).

Zone 1

Zone 2

Zone 3

Zone 4

Zone 5

Mode	Description
Select above	Select a zone row, click OK, then draw a polygon on the canvas to paint that zone. Right-click or double-click to close the polygon. Draw zones as needed — last drawn wins where polygons overlap.
Randomize	Assigns a random K zone to every grid cell instantly — quick way to create discrete heterogeneity.
Fgen92	Opens the Fgen92 dialog to generate a spatially correlated, continuous random log-K field with a user-specified correlation length and variance.

Tip: Edit K and porosity values in the zone table before clicking OK. The K contrast between zones controls how strongly heterogeneity influences particle spreading.

Fgen92 — Spatially Correlated Random K Field

Selecting Fgen92 and clicking OK opens a full-screen dialog that generates a log-normal hydraulic conductivity field using the FGEN92 spectral simulation algorithm. The dialog has three panels:

Left Panel — Parameters

Nx (cols) / Ny (rows)

Grid size Δx, Δy

Mean (ln K)

Variance / Nugget

Spectrum type

λ_x, λ_y (corr. lengths)

Seed / nfull_x / nfull_y

Compute Log K Field

Output Statistics

Mean / Variance / Std Dev

Min K / Max K

OK (Apply to Model)

Log K Field Plot — color map of the generated field; hover for coordinates and ln K value; click to lock a cross-section line

Cross-Section Plot — ln K profile along the selected row or column; updates live on hover

Right Panel

Hover readout (x, y, ln K, K)

Color Scheme

Smooth gradient

5 / 10 / Custom classes

Cross Section

Horizontal / Vertical

Locked lines list

Autocovariance

Additional Output

Display Log K Output

Field Parameters (left panel)

Parameter	Description
Mean (ln K)	Mean of the natural log of hydraulic conductivity. E.g., −5.2 gives geometric mean K ≈ 5.5×10⁻³ m/s.
Variance	Variance of ln K. Higher values produce stronger K contrasts. Typical range: 0.5–3.0; default 1.04.
Nugget	Spatially uncorrelated variance added to the spectrum. Usually 0 for smoothly correlated fields.
Correlation model	Exponential: exponentially decaying autocovariance — common for natural aquifers. Gaussian: smoother, bell-shaped autocovariance.
Lambda_x (m)	Correlation length in x (flow direction). Controls how far K patches extend along flow. Larger = longer connected features.
Lambda_y (m)	Correlation length in y. Typically smaller than Lambda_x in layered aquifers, producing horizontally elongated patterns.
Random Seed	Integer seed for the PRNG. The same seed always produces the same field realization.
nfull_x / nfull_y	Full periodic grid size for the spectral FFT (power of 2, ≥ Nx and Ny). Larger improves spectral accuracy.

Output Statistics (left panel)

Statistic	Description
Mean	Sample mean of ln K across all grid cells — should be close to the input Mean (ln K).
Variance	Sample variance of ln K — should be close to the input Variance.
Std Dev	Sample standard deviation of ln K.
Min K / Max K	Minimum and maximum hydraulic conductivity values (in m/s) in the generated field.

Field Plot and Color Schemes (center & right panels)

The center panel shows a color map of the generated ln K field (blue = low K, red = high K). Hover over any cell to see its coordinates and ln K value. Four color schemes are selectable from the right panel:

Scheme	Description
Smooth Shading	Continuous gradient — best for visualizing full spatial variability.
Contour by 5% Steps	20 discrete color bands — useful for identifying distinct high/low K regions.
Contour by 10% Steps	10 discrete color bands.
Custom No. of Contours	Enter any number of color bands in the adjacent box.

Cross-Section Controls (right panel)

Choose Horizontal or Vertical to set the transect direction.
Hover over the field plot — the cross-section profile updates live at the cursor's row or column.
Click the field to lock a cross-section line. Locked lines appear as dashed overlays on the field and are listed below the controls with a × button to remove each one.
Autocovariance — shows the empirical autocovariance in x and y compared to the theoretical model curve.
Additional Output — reports detailed variance and truncation statistics from the spectral simulation.
Display Log K Output — opens a 2D table of ln K values and a Download CSV button exporting the field as an x-vs-y array.

Applying the Field

Click OK (Apply to Model) to close the dialog. The domain redraws with the continuous K color map, and the Head button becomes active.

Tip: Correlation length relative to domain size controls the visual character of the field. When Lambda_x is close to the domain width, the field shows a few large coherent features; when Lambda_x is much smaller, the field appears more randomly speckled.

5 Head — Solve the Flow Equation

Click Head and enter the number of contour intervals (typically 10–30). The applet solves the steady-state groundwater flow equation using FEM and draws head contour lines over the domain.

Boundary	Condition
Left (AD)	Specified head h₁ (higher)
Right (BC)	Specified head h₂ = 0 (lower)
Top (AB) and Bottom (DC)	No-flow (∂h/∂y = 0)

Head statistics (min, max, cursor value) appear in the Head tab of the right data panel. Once flow paths are added, head contours turn grey so paths remain visually distinct.

Tip: With a heterogeneous K field applied, head contours will curve — converging toward high-K zones and spreading in low-K zones — rather than being straight vertical lines.

6 Flow — Track Paths or Set Up Particles

Click Flow to open the flow options dialog. Two modes are available:

4a — Flow Path Tracking

Select Flow path tracking and click OK. Then click anywhere on the canvas to place a seed point — a flow line is computed through that point.

Option	Description
Forward and backward	Traces the flow path in both directions from the seed point.
Forward only	Traces only downstream from the seed point.
Backward only	Traces only upstream from the seed point.

Right-click any flow line to open a context menu to change its color, thickness, or remove it.

4b — Particle Cloud

Select Particle movement, set the initial particle spacing (m), and click OK. Then draw a polygon on the canvas — particles are seeded on a regular grid inside the polygon. The Animation step then moves them forward in time.

Line Style

Set the default line color and thickness in the dialog before clicking OK. Individual lines can be restyled via right-click after placement.

7 Animation — Run the Simulation

Click Animation to configure and run the animation. Parameters available for both flow-path and particle modes:

Parameter	Description
Travel time per sim. second	How many days or years of transport are represented by one second of animation playback.
Time unit	Days or years — sets the display unit for the elapsed time label.
Frames per second	Animation playback speed: 1, 5, 10, 15, or 20 fps.

Additional parameters for particle mode only:

Parameter	Description
Longitudinal dispersivity α_L	Adds stochastic longitudinal spreading to particle paths.
Transverse dispersivity α_T	Adds stochastic transverse spreading to particle paths.
Show center of mass ± N std. dev.	Draws an ellipse showing the centroid and spatial spread of the particle cloud.
Plot spatial variance vs time	Opens a secondary graph of S_xx and S_yy over time.
Plot spatial mean vs time	Opens a secondary graph of x_c and y_c over time.

After clicking OK, click the canvas to start the animation. Click again to pause or resume. Elapsed time updates in the status bar.

Tip: Set α_L = α_T = 0 to see purely mechanical spreading due to K heterogeneity. Add small dispersivity values to simulate pore-scale mixing on top of macro-scale spreading.

8 Data Panel

The right panel has four tabs that update as the simulation progresses:

Tab	Contents
Head	Min and max head values across the domain; head value at the cursor position.
Velocity	Max Darcy flux and seepage velocity; qx, qy, vx, vy, \|q\|, \|v\| at cursor; average seepage velocity per zone.
Paths	For flow-path mode: number of tracked paths and max/min travel time. For particle mode: particle count, spacing, max/min travel time, and dispersivity values.
Export	Buttons to display and download head data, velocity field, flow-path data, and properties grid.

9 Zoom & Pan

Action	Effect
Mouse wheel	Zoom in or out centered on the cursor position.
+ button	Zoom in by 1.5×.
⊙ button	Reset zoom to fit the full domain in the canvas.
− button	Zoom out by 1.5×.
Shift + drag	Pan the view.
Middle-mouse drag	Pan the view.

10 Export Data

From the Export tab in the right data panel, display and download simulation results:

Dataset	Contents	Formats
Head Data	Node positions and computed hydraulic head values.	TXT, CSV
Velocity Field	Darcy flux and seepage velocity components at each element centroid.	TXT, CSV
Flow / Particle Paths	Coordinates and travel times for each tracked path or particle.	TXT, CSV
Properties Grid	Element K zones, hydraulic conductivity, and porosity.	TXT, CSV

The Log K field can also be downloaded as a 2D x-vs-y CSV table from the Display Log K Output button inside the Fgen92 dialog.