house_auction#

  • Series: lecture-python.myst

  • File: lectures/house_auction.md

  • Audit date: 2026-08-26

  • Corpus snapshot: e25fdf2345

  • Categories audited: writing, math, code, references, links, admonitions (JAX out of scope)

  • Overall score: 8.3 / 10

  • Priority: HIGH

Score breakdown#

Category

Score

One-line note

Writing

3/10

qe-writing-006 ×12; qe-writing-005 ×10; qe-writing-001 ×7, +5 more.

Math

10/10

no mechanical violations detected.

Code

7/10

qe-code-001 ×90.

JAX

out of scope

JAX rules target lecture-jax.

Figures

N/A

no figures or plotting code.

References

10/10

no mechanical violations detected.

Links

10/10

no mechanical violations detected.

Admonitions

10/10

no mechanical violations detected.

Issues#

Critical#

None found.

High severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 90. Lines: 295, 298, 340, 343, 390, 457, 459, 849, 939, 1088, …. Example: PEP8 spacing is ignored across the whole file: 90 distinct lines carry violations, of which the twelve listed are representative. The counts by kind are 140 missing spaces after a comma or dict colon (v[:,ii], zip(bid_info.keys(),winner_list), np.array([[8,5,9,4],...])), 19 missing spaces around an operator (result=[] 295, V==np.max(V) 1097, len(i)>1 1254), 16 spaces around a keyword-argument equals (any(axis = 0) 343, 383, 471, 535, 720, 730, 784, 795), 3 unspaced % format operators (849, 855, 1280), 3 under-indented continuations (1387, 1400, 1411), 2 single-space inline comments (1088, 1089), 2 double spaces after = (390, 736), and a blank line at end of file (1288). None of this is the mathematical-notation exception: the numeric literals at 939, 967, 977, 987 and 998 are data, not matrix notation, and axis = 0 has no defence.

  • [qe-writing-001] — Use one sentence per paragraph. Count: 7. Lines: 221, 1077, 1101, 1109, 1126, 1137, 1344. Example: 4 sentences in one paragraph.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 10. Lines: 37, 60, 176, 189, 192, 964, 974, 984, 995, 1006. Example: bold does two jobs it should not. It carries emphasis at 37 (‘at most one house’), 60 (‘simultaneously’), 176 and 189 (‘plus \(\epsilon\)’) and 192 (‘any house’), where italic is the convention; and it substitutes for headings in ‘## Robustness Checks’, where the five cases are marked ‘1. number of houses = number of buyers’ (964), ‘2. multilple excess buyers’ (974), ‘3. more houses than buyers’ (984), ‘4. some houses have extremely high reservation prices’ (995) and ‘5. reservation prices are so high that the auction can’t start’ (1006) instead of ### subheadings that the TOC could pick up.

  • [qe-writing-006] — Capitalize lecture titles properly. Count: 12. Lines: 52, 87, 102, 114, 117, 241, 659, 960, 1020, 1064, …. Example: H2 Title Case: ‘Ascending Bids Auction for Multiple Goods’ (Bids, Auction, Multiple, Goods).

  • [qe-writing-008] — Remove excessive whitespace between words. Count: 97. Lines: 23, 25, 27, 29, 31, 33, 35, 50, 60, 68, …. Example: 2 spaces.

Medium severity#

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 3. Lines: 117, 161, 964. Example: the auction’s rules are stated three times over 180 lines. Lines 52-83 give them as the auctioneer’s protocol, ‘### Basic Setting’ (117-151) restates the same setting as the seller’s problem (\(n\) houses, at most one per buyer, \(v_{ij}\) private, surplus \(v_{ij}-p_i\), outputs \(p\), \(Q\), \(S\)), and ‘## Pseudocode’ (161-199) gives them a third time as inputs, protocols and outputs - with the \(S\) and \(Q\) definitions at 197-199 copied verbatim from 148-151. The five robustness cases at 964-1006 then repeat the parameter-matrix construction five times with no shared helper.

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 2. Lines: 114, 1344. Example: ‘## Ascending Bid Auction’ at 114 opens a section on the mechanism that ‘## Ascending Bids Auction for Multiple Goods’ at 52 has already described under a near-identical title, so the reader cannot tell from the headings which section is the overview and which the specification. Line 1344 asserts that ‘the generalized second-price auction described in our pseudo code above does indeed satisfy (1)’ - a bare numeric reference to {eq}`eq:GC1`, which the same paragraph cites properly by label two lines earlier.

  • [qe-writing-004] — Avoid unnecessary capitalization in narrative text. Count: 1. Lines: 1211. Example: mid-sentence ‘Class’.

Low severity#

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 1. Lines: 351. Example: 1412 lines with no figure at all, for a mechanism whose whole content is a price path: five rounds are worked through by hand at 351-657, each printing a price vector and a bid table, and the class then reports the same thing as text (849-921). One chart of the \(n\) house prices against round number, with the temporary winner marked, would show convergence - ‘the auction ends when the price of no house changes from one round to the next’ (76) - in a way that reading six successive printed vectors cannot.

Strengths#

  • The pseudocode section (161-227) is unusually complete for this corpus - inputs, auction protocols, outputs and the buyer’s strategy - and it closes by naming the two ambiguities the protocol leaves open (219-223) and saying exactly how the code resolves them, which is why the custom argmax and np.random.choice appear later without explanation needed.

  • The auction is worked through by hand over five labelled rounds (351-657) before the class is written at 659, so ascending_bid_auction arrives as a packaging of something the reader has already seen operate.

  • Five robustness cases stress the implementation on the boundaries that matter - equal numbers of houses and buyers, excess buyers, excess houses, one prohibitive reservation price, and reservation prices so high the auction cannot start (960-1014).

  • The Groves-Clarke half does not stop at the algorithm: it states the VCG allocation and payment rules as labelled equations {eq}`eq:GC1` and {eq}`eq:GC2` (1324-1332), interprets the payment as an externality (1336-1342), and then verifies it numerically by re-running the mechanism with each buyer excluded in turn (1373-1411).

  • The minimum bid increment is written ϵ in the code to match the \(\epsilon\) of the text (340, 469, 718, 969), and the install cell pins prettytable<3.18 (20) rather than leaving the build to float.