# CAA Verification Kit — AI agent guide

## Getting started

Read your assignment and Verification_Kit/README.md. Give your coding agent
these documents, the public kit and your solver source. Choose MATLAB or
Python and identify the interpreter and dependencies.

The kit checks C4 + RK4 through A_zero, B_24, B_36, B_48, B_72 and C_gaussian,
including plane-wave convergence. Implement the student adapter, then use the
commands in the original README to run your solver and generate reports.

## Starting instruction

> Read the assignment, AGENT_GUIDE.md and Verification_Kit/README.md. Inspect
> my solver and implement the student adapter. Use the supplied cases.json,
> verify.py and validate_solver.m. Run A first, then all four B grids and C.
> Save commands, environment, raw results and reports in separate attempt
> directories. Diagnose the first failing check, make a focused correction
> and rerun. Summarize checked cases, numerical errors and changes.

## Adapter contract

Python implements solve_case(case). MATLAB implements
result = student_solver(case_config). Return schema_version
caa-verification/1.0 and the supplied case_id.

Fields use rows=y and columns=x. Convert NumPy arrays to JSON lists. Return
finite double-precision x, y, time, p_final, u_final and v_final, together
with zero_history for A and probe_p for C. The original README and cases.json
specify the complete shapes, coordinates, tolerances and reference values.

Use the supplied dt and n_steps, including 199 steps for C, and record actual
time labels. Periodic grids omit the repeated upper endpoint; non-periodic
grids include both endpoints. Use the fixed one-based probe indices, subtracting
one in Python. The sponge uses the maximum of side contributions at corners.
The outer boundary uses the ghost closure specified in the README.

## Debugging sequence

1. ERROR: inspect the schema, field shapes, finite values and execution errors.
2. Grid or time failure: correct coordinates and integration scheduling, then
   rerun the numerical checks marked NOT_RUN.
3. A failure: inspect initialization and each p/u/v snapshot.
4. B failure: inspect derivatives, periodic wrapping, RK stages and pressure
   errors. Use all four grids to evaluate convergence order.
5. C failure: inspect the initial conditions, sponge, fixed probe indices and
   agreement between final probe samples and final-field entries.
6. Save the diagnostic, source change and rerun result together.

Follow-up instruction:

> Read the raw result and report, starting with the first failed check. Explain
> the cause, make a focused correction to my solver and rerun the affected
> case. Then run all six baseline cases. Compare the before-and-after errors
> and retain both attempts.

## Web result check

Run your solver locally and select the per-case JSON files from its results
folder on the CAA page. The website checks the supplied arrays with the original
checker. Select all six cases for the complete baseline, or a subset while
debugging. Download the JSON report from the result panel. Run the local kit
for its Markdown report.

The web interface accepts POST /teaching/mech5961/caa/api/check with
same-origin CSRF protection and application/json:

    {"results": [<raw result object>, ...]}

Supply 1–6 distinct known cases, up to 12 MB total. Obtain the CSRF token from
the page in the same browser session. The response includes
baseline_checkpoint_passed, selected_checks_passed, complete_abc_scope,
individual checks and numerical metrics. PARTIAL SCOPE identifies a passing
subset. HTTP 200 returns a report; HTTP 429 asks you to retry shortly.

## Organising results

Keep solver and adapter source, the supplied kit, raw per-case JSON, reports,
environment and commands together. Record AI-assisted changes and the decisions
you reviewed. Organise the remaining assignment experiments by task, with their
configurations, figures and numerical results. Use the assignment's submission
format and dates.