Skip to main content

Generates doubly-periodic random 2D Darcy flow fields with arbitrary mean flow direction

Project description


This is a Python package for generating 2D periodic random groundwater flux fields with any user specified mean flow vector. Periodic random hydraulic conductivity fields are generated that are locally multi-Gaussian with user-selectable semi-variograms and anisotropy structures. Darcy flux fields are solved exactly using a finite volume approach on these conductivity fields with periodic boundary conditions and an enforced mean flow angle. Inter-cell fluxes are directly reported for compatibility with particle tracking algorithms based on the Pollock method.


This package generates random, periodic, locally Gaussian conductivity fields by use of the fast Fourier transform approach. It solves the steady-state groundwater flow equation on a random heterogeneous conductivity field, with periodic boundary conditions in both directions. Solution is finite volume, and formulated directly for the interfacial fluxes rather than for heads.

Two classes and three functions are exposed, whose usage details are illustrated below.


  • DomainData(nr, nc, dr, dc) constructs an object representing an nr by nc rectangular structured grid whose cells have dimension dr by dc. Internally, the code works with coordinate axes r ("row") and c ("column"). r is the 0-based row index for interacting with external codes, increasing r corresponds to increasing y. c is the 0-based column index for interacting with external codes, increasing c corresponds to increasing x.

  • RandomKField(dd, model_ref, var, corr_len, f_lambda, azimuth) constructs an object representing a lognormal K field defined on the DomainData grid dd, with user-defined structural parameters. model_ref represents the reference number of chosen covariance model (1 indicates exponential covariance and 2 indicates Gaussian covariance). var is the log-variance of the field, and corr_len is its correlation length (in the direction of the principal axis of anisotropy). Geometric anisotropy is defined by f_lambda, the ratio of major axis correlation length to minor axis correlation length, and azimuth, the angle of the major axis of anisotropy above the c-axis (i.e., x-axis).


  • solve_q(K, angle=0) returns a tuple (qr, qc), each component of which is a Numpy array of the same shape as the RandomKField K. Element (i,j) of array qr represents the positive-directed outward-bound flux in the r-direction originating in cell (i,j) of field K. This is to say the flux from domain grid cell (i,j) to (i+1,j), assuming both cells are in the interior of the domain. Fluxes wrap around due to periodicity, so that if R is the largest row index, element (R,j) of qr represents the flux from grid cell (R,j) to (0,j) of the domain. qc is similarly defined, but contains the positive-directed outward-bound flux in the c-direction for each domain grid cell. qr and qc are normalized so that the mean Darcy flux has unit norm. angle represents the mean flow angle (in radians) above the c-axis (i.e., x-axis).

  • plot_lognormal_field(K) generates a colormap plot of the base-10 logarithm of RandomKField object K.

  • plot_quiver(K, qr, qc) generates a quiver plot of interpolated cell-centre Darcy fluxes contained in the Numpy arrays qr and qc (discussed above). the RandomKField object K must be passed as a way of indirectly accessing the DomainData grid dimension parameters.


The package is imported into your Python namespace by the command: import periodicgw

The example code below demonstrates how to generate a random, periodic, locally Gaussian conductivity field with user-selectable semi-variograms and anisotropy structures and solve the steady-state groundwater flow equation on a previously saved conductivity field. Note that the defined correlation length in both the major- and minor- direction should be larger than the grid cell size.

from numpy import pi
from pickle import dump, load
from periodicgw import DomainData, RandomKField, solve_q, plot_lognormal_field, plot_quiver

# Generate a random, periodic, log-normal conductivity field locally Gaussian semi-variogram
dd = DomainData(nr=50, nc=100, dr=2, dc=2)
K = RandomKField(dd, model_ref=2, var=.5, corr_len=dd.num_cols*dd.dc/20, f_lambda=.5, azimuth=0*pi/2)
with open('k_field_test.pickle',"wb") as dump_file:
	dump(K, dump_file)

# Read the previously saved conductivity field with exponential covariance
with open("k_field_test.pickle", "rb") as read_file:
	saved_K = load(read_file)

# Compute the periodic Darcy flow field resulting from enforcing mean flow in the +c (x-axis) direction          
q_r, q_c = solve_q(saved_K, angle=0)
plot_quiver(saved_K, q_r, q_c) 

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

periodicgw-1.1.tar.gz (10.5 kB view hashes)

Uploaded Source

Built Distribution

periodicgw-1.1-py3-none-any.whl (11.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page