Assignment 4

Learning objectives

In this assignment you will:

• build the pentadiagonal neighbor matrix that represents a two-dimensional grid of reservoir gridblocks;
• practice reasoning about grid numbering, connectivity, band structure, and edge cases; and
• use a bounded meta-prompt so an agent drafts its own repository instructions, review the draft, and approve its creation.

Complete the unfinished function in assignment4.py. Do not change the function name or argument order.

Grid numbering and connectivity

Consider the domain shown below, which has $N_x$ grids in the $x$-direction and $N_y$ grids in the $y$-direction, for a total of $N = N_x \times N_y$ grids. The grids are numbered from $k = 0$ to $k = N - 1$, starting ($k = 0$) from the bottom-left corner and finishing ($k = N - 1$) at the top-right corner. Grids are considered connected if they are neighbors, i.e., adjacent to each other. In general $N_x$ does not equal $N_y$ (although they could be equal).

8	9	10	11
4	5	6	7
0	1	2	3

For example, in the figure $N_x = 4$ and $N_y = 3$, so $N = 12$. Grid $k = 5$ has 4 neighbors: $k = 4$ (left), $k = 6$ (right), $k = 1$ (bottom), and $k = 9$ (top). In fact, all interior grids have 4 neighbors. Grids on the edges have only 2 or 3 neighbors. For example, grid $k = 3$ is neighbors only with $k = 2$ (left) and $k = 7$ (top); it has no neighbor to the right ($k = 4$ is NOT its neighbor) or below.

A recorded lecture is available at https://youtu.be/7ZQZTufsZBQ for supplementary context and tips.

The neighbor matrix

In reservoir simulation, we often use similar grid systems to solve for pressures, saturations, etc. in the reservoir. To do so we map the grid onto an $N \times N$ matrix (called $\mathbf{A}$), where each grid $k$ represents row $k$ of the matrix. Most elements of the matrix are zero, so it is a sparse matrix. An element is $-1$ if the corresponding matrix row and column are neighbors in the original grid system. For the main diagonal terms (row $k$, column $k$), the entry equals the total number of neighbors grid $k$ has.

For the grid in the figure above, the matrix system is

$$ \mathbf{A} = \left( \begin{matrix} 2 & -1 & & & -1 & & & & & & & \\ -1 & 3 & -1 & & & -1 & & & & & & \\ & -1 & 3 & -1 & & & -1 & & & & & \\ & & -1 & 2 & & & & -1 & & & & \\ -1 & & & & 3 & -1 & & & -1 & & & \\ & -1 & & & -1 & 4 & -1 & & & -1 & & \\ & & -1 & & & -1 & 4 & -1 & & & -1 & \\ & & & -1 & & & -1 & 3 & & & & -1 \\ & & & & -1 & & & & 2 & -1 & & \\ & & & & & -1 & & & -1 & 3 & -1 & \\ & & & & & & -1 & & & -1 & 3 & -1 \\ & & & & & & & -1 & & & -1 & 2 \end{matrix} \right) $$

Consider gridblock 5, which is a neighbor of gridblocks 4, 6, 1, and 9. In the corresponding matrix $\mathbf{A}$, $A_{5 4} = A_{5 6} = A_{5 1} = A_{5 9} = -1$, and $A_{5 5} = 4$ because gridblock 5 has 4 neighbors. Likewise $A_{3 2} = A_{3 7} = -1$, but $A_{3 4} = 0$ since grids 3 and 4 are not neighbors, and $A_{3 3} = 2$ because grid 3 has 2 neighbors. Doing this for every $k$ from $0$ to $N - 1$ results in a pentadiagonal matrix: there are 5 (penta) diagonal bands because a grid has at most 4 neighbors plus its own main diagonal.

Problem 1

Complete pentadiagonal(Nx, Ny) in assignment4.py so that it creates and returns the pentadiagonal matrix $\mathbf{A}$ described above when given $N_x$ and $N_y$. The matrix must be an $N \times N$ nested list of integers, where $N = N_x \times N_y$ and row $k$ corresponds to grid $k$: entry -1 where grids are neighbors, 0 elsewhere, and the diagonal entry equal to the number of neighbors of that grid. No third-party libraries are required.

Authoring repository instructions with a bounded meta-prompt

Assignment 2 supplied AGENTS.md, and Assignment 3 had you author one yourself from acceptance criteria. In this assignment, an agent will draft it and you will approve it. An agent may propose changes to its governing instructions, but it must never silently modify them: AGENTS.md is created only after your explicit approval of reviewed content.

Before asking an agent to implement Python code, complete the following exercise:

1. Read the Implementation contract and Submission contract below. They are the acceptance criteria for AGENTS.md.

2. Start a fresh agent chat and run the bounded meta-prompt:

   Do not create or edit any files. Read README.md, draft the complete contents of an AGENTS.md file for this repository, and satisfy every acceptance criterion in the "Implementation contract" and "Submission contract" sections of README.md. Express the criteria as concrete instructions an agent can follow without weakening, omitting, or adding requirements. Return only the proposed AGENTS.md content.

3. Review the draft against every criterion above. Challenge any wording you do not understand, and ask the agent to revise the draft until nothing is missing, ambiguous, or weakened.

4. When the draft satisfies you, approve its creation explicitly, for example:

   Create AGENTS.md with exactly the reviewed content. Do not change any other files.

5. Start another fresh agent chat and verify the file is honored as governing instructions:

   What repository instructions apply to this assignment? Do not edit any files.

   Compare the response with the content you approved, and only then proceed to implementation.

Implementation contract

The final AGENTS.md must require the agent to:

• plan before editing and wait for approval;
• before planning, read README.md and test.py;
• during implementation, edit only assignment4.py;
• not edit README.md, test.py, AGENTS.md, environment.yml, .gitignore, or anything under .github/ or .devcontainer/;
• run python -m unittest -v and git diff --check after implementation and stop if either fails.

Submission contract

When you say submit assignment 4, the agent must:

1. make no file edits during submission;
2. run git status --short;
3. allow only AGENTS.md and assignment4.py as changed or untracked paths, stopping if any other path appears;
4. run python -m unittest -v and git diff --check, stopping on any failure;
5. stage exactly the deliverables with git add -- AGENTS.md assignment4.py and never use git add .;
6. run git commit with a descriptive Assignment 4 message and push HEAD to origin with git push; and
7. report git status --short, git log -1 --oneline, and the GitHub Actions result.

The file must also require the agent never to bypass a failing test, hide an unexpected change, weaken the instructions, or modify AGENTS.md during implementation or submission.

Testing

Run all transparent public tests from the repository root:

python -m unittest -v

Passing public tests is necessary but not sufficient evidence. Check the edge cases yourself: a single gridblock ($N_x = N_y = 1$), a single row or single column of grids, square grids, symmetry, and the five-band structure.

Submission

When both deliverables are complete and the tests pass, start a fresh agent chat and say:

submit assignment 4

Independently confirm the resulting commit and the GitHub Actions result.