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