Assignment 11 — Trust, but Visualize

Goal

Extend the one-dimensional reservoir model to compute transmissibility and accumulation from reservoir geometry and fluid properties. Then use reproducible visualizations and independent numerical comparisons to decide whether an agent's implementation is correct. A passing test suite or a confident explanation is not sufficient evidence by itself.

The original four-block example is specified in inputs.yml. Verification also uses an eight-block problem with different prescribed pressures at each end. Do not edit the supplied inputs or tests to make an implementation pass.

Engineering task: assignment11.py

Implement these four methods of OneDimReservoir, retaining their interfaces:

1. compute_transmissibility() returns the unconverted value $kA/(\mu\Delta x)$.
2. compute_accumulation() returns $A\Delta x\phi c_t/B_w$ for each uniform block.
3. fill_matrices() constructs sparse T, sparse diagonal B, and vector Q.
4. solve_one_step() updates self.p with the requested explicit or implicit method.

The remaining methods are provided; do not rewrite them. Dictionaries and YAML filenames are accepted as inputs. Support at least two blocks and preserve the original four-block exercise. Use scipy.sparse and, for the implicit solve, scipy.sparse.linalg.cg with atol=1e-8, rtol=0.0. Check its status and raise RuntimeError on failure without replacing the previous pressure. Reject an unknown solver with ValueError.

Equations, units, and boundaries

Let $\Delta x=L/N$, converted face conductance $\tau=f kA/(\mu\Delta x)$, and block storage $b=A\Delta x\phi c_t/B_w$. Here $f$ is the supplied conversion factor, $k$ is permeability (mD), $A$ cross-sectional area (ft²), $\mu$ viscosity (cP), $\phi$ porosity, $c_t$ compressibility (psi⁻¹), and $B_w$ formation volume factor. Use the course's supplied field-unit convention consistently: $\tau$ has units of volume/(day·psi), $b$ volume/psi, pressure psi, and time days. Apply the conversion factor once in T and Q, not in the value returned by compute_transmissibility() or in B.

The balance is

$$ \mathbf{B}\frac{dp}{dt}+\mathbf{T}p=Q. $$

Interior rows of T have diagonal $2\tau$ and adjacent entries $-\tau$. For a prescribed pressure at a boundary face, the adjacent block diagonal is $3\tau$ and its source is $2\tau p_{boundary}$; the factor two accounts for the half-block distance. For a no-flow boundary, that diagonal is $\tau$ and the boundary source is zero. Left and right contributions must use their own indices and values. The provided helper supports prescribed pressure and zero prescribed flux only; nonzero flux and unknown types raise ValueError.

T and B have shape (N, N); p and Q have shape (N,), and $\mathbf{B}=b\mathbf{I}$. With time step $\Delta t$:

$$ p^{n+1}=p^n+\Delta t \mathbf{B}^{-1}(Q-\mathbf{T}p^n) \quad\text{(explicit)}, $$

$$ (\mathbf{T}+\mathbf{B}/\Delta t)p^{n+1}=\mathbf{B}p^n/\Delta t+Q \quad\text{(implicit)}. $$

A cell-centered pressure is not the boundary-face pressure. A constant-property reservoir with prescribed pressures at both ends has a linear steady profile evaluated at the block centers. With two closed ends, a uniform initial pressure must remain unchanged.

Agent exercise: implement and check

Ask the agent to explain the equations, units, array shapes and boundary conditions, and propose a bounded implementation plan. Review the plan before allowing edits. Implement the four methods in assignment11.py, run the supplied numerical tests, and inspect the diff. Do not change tests or inputs to make an implementation pass. Independently rerun the tests before accepting the agent's work.

Optional visual diagnostics — for your own use only

verification.ipynb is a supplied, ready-to-run plotting aid. You may use it, make your own plots, or skip it. It imports your implementation from assignment11.py; it does not replace the solver. No notebook writing, predictions, interpretations, figures, diagnostic arrays, or error reports are required for submission or grading.

The examples illustrate pressure evolution with unequal end pressures, explicit versus implicit behavior at identical physical times, time-step refinement, and a separate faulty-input example. verification_cases.py supplies independent benchmarks assembled from physical inputs. Its transient reference is exact in time on the fixed discrete grid, not an exact continuum solution.

Use the plots to investigate boundary indexing, unit conversions, instability and time-step error. Stable implicit results can still be inaccurate. Agreement with a reference built from the same defective solver would be circular. These are suggestions for diagnosing your own implementation, not graded tasks.

Run and submit

Open this repository in Codespaces, or install environment.yml with conda or micromamba. Codespaces is configured to install the Python and Jupyter VS Code extensions; the environment includes the notebook kernel and plotting packages. Container creation automatically registers Python 3 (Assignment 11) using /opt/conda/bin/python, the default interpreter. The supplied notebook targets that kernel. For an existing Codespace, run Codespaces: Rebuild Container to apply this setup. If VS Code remembers a different kernel, select Python 3 (Assignment 11) once in the notebook kernel picker. Run the existing numerical tests from the repository root:

python -m unittest -v test.py

Only the solver is graded using the supplied numerical tests. Notebook diagnostics are optional and ungraded.

For optional plots, open verification.ipynb in VS Code and click Run All after implementing your solver. No copying or terminal commands are needed. Notebook edits and saved outputs are local diagnostics only: the submission process leaves them on your machine and submits only assignment11.py. There is no requirement to run or edit the notebook or write explanations in it.

Submit only assignment11.py. Do not change the supplied tests or inputs. The numerical tests will fail until you implement the required solver methods. When your implementation is ready and the tests pass, tell the agent submit assignment 11. Review the changes and approve the submission when prompted, then verify your commit and GitHub Actions result. Do not submit plots, notebook outputs or diagnostic prose.