examples

 1"""Runnable illustrations of the simulator.
 2
 3Each is a plain, top-to-bottom script -- run as `python examples/buildup.py`, say --
 4whose docstring says what it shows, and whose figures are reproduced on its page here.
 5
 6They double as regression tests: `tests/test_examples.py` runs them all
 7(plotting included) and compares the output with `tests/references.py`.
 8
 9![Panels extracted from the examples](collage_features.png)
10
11- `examples.quarter_five_spot` reproduces Fig. 6 of the reference paper -- this is
12  what verifies our agreement with the Matlab codes -- and then varies it: the
13  implicit transport scheme, and *scheduled* (time-varying) injection rates, which
14  steer the water front.
15- `examples.buckley_leverett` is the only *verification* among them: in 1D the
16  saturation equation is exactly solvable (by the Welge tangent construction),
17  so here the numerical profile is compared with the truth rather than with
18  ourselves, and the error is shown to vanish under grid refinement.
19- `examples.egg` is the one *validation* against an external simulator: the Egg
20  model (a channelized, 12-well benchmark reservoir), flattened from 7 layers to
21  one by vertical averaging, reproduces the water cuts and oil rates of its
22  published 3D solution (ECLIPSE 100) to within 0.01 and about 5%. Also the second
23  example in metric units, and the one with non-quadratic relative permeabilities
24  (Corey exponents 3/4 with end-points, ref `minires.fluids.Fluid`).
25- `examples.inactive_cells`: an irregular reservoir on the rectangular grid --
26  an outline and a sealing fault, cut out by `minires.ResSim.active`.
27- `examples.aquifer`: water beyond part of the boundary, feeding a lone producer
28  -- a BHP-controlled "well" in the contact cells (`minires.wells.aquifer_WI`),
29  at constant pressure, or depleting (Fetkovich: a `well_controls` override).
30- `examples.logo`: a smiley -- an outline and a hole cut out by `active`,
31  an aquifer along the bottom -- for the picture alone.
32- `examples.random_fields`: the Gaussian random fields (`minires.geostat`) that
33  the heterogeneous examples draw their $\\log K$ from (and the tutorials of
34  HistoryMatching their prior ensembles), in 1D and 2D, and the effect of the
35  variogram's range.
36
37These concern the *well model* (`minires.wells.peaceman_WI`), i.e. the sub-grid
38relation between a well and the (much larger) cell that holds it:
39
40- `examples.well_control`: the two ways to control a well -- prescribing its rate and
41  letting its pressure follow, or the reverse -- shown to be one model seen from
42  either end. Also why the well model is needed at all: a well's *cell* pressure
43  is a grid artefact, whereas the bottom-hole pressure derived from it is not.
44  Its setting is a lone producer depleting a closed reservoir, whose transient
45  and boundary-dominated regimes are seen in the drawdown.
46- `examples.well_path`: a well completed along a polyline rather than in a single
47  cell, and the two ways its rate then gets divided among the completions --
48  statically (in proportion to the well index) or, under BHP control, solved for.
49
50The next ones illustrate what slight compressibility (`minires.ResSim.ct` > 0) brings:
51
52- `examples.pressure_diffusion`: the pressure equation becomes parabolic, so that a
53  change of rate propagates at *finite speed* (diffusivity `η = K λ / (φ ct)`),
54  instead of being felt everywhere instantaneously. Also illustrates that the
55  pressure level is now meaningful (anchored by `p0`), whereas the incompressible
56  pressure is only defined up to a constant.
57- `examples.buildup`: production *without* injection (impossible if incompressible),
58  with the resulting material-balance decline, `dp̄/dt = -q / (ct Vp)`; then
59  shutting the well in, and the ensuing pressure buildup. Monitor points far
60  from the well respond late -- and keep declining after the shut-in, before
61  turning around. Posed in metric units, and interpreted as a well test.
62- `examples.voidage_replacement`: the only *two-phase* one of these -- waterflooding
63  while injecting only half of what is produced (impossible if incompressible).
64  The front then advances more slowly, and by a different pattern, since some of
65  the oil is instead driven by expansion.
66
67The last two illustrate the adjoint (`minires.tlm`), i.e. gradients of an
68objective wrt the initial state, the permeability field and the BHP controls, checked
69against finite differences:
70
71- `examples.water_cut_gradient`: the sensitivity of one producer's water cut, to the
72  permeability field and to the producers' BHP schedule.
73- `examples.history_match_gradient`: a few steepest-descent steps towards a
74  synthetic truth.
75"""