BCG_incomplete_mkts#

  • Series: lecture-python-advanced.myst

  • File: lectures/BCG_incomplete_mkts.md

  • Audit date: 2026-08-26

  • Corpus snapshot: b83d6da399

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

  • Overall score: 7.1 / 10

  • Priority: HIGH

Score breakdown#

Category

Score

One-line note

Writing

3/10

qe-writing-005 ×16; qe-writing-001 ×7; qe-writing-003 ×5, +3 more.

Math

7.5/10

qe-math-011 (proposed) ×2; qe-math-009 ×4.

Code

7.5/10

qe-code-001 ×9.

JAX

out of scope

JAX rules target lecture-jax.

Figures

4.5/10

qe-fig-003 ×9; qe-fig-005 ×2; qe-fig-010 ×1, +2 more.

References

10/10

no mechanical violations detected.

Links

10/10

no mechanical violations detected.

Admonitions

N/A

no admonitions, exercises or solutions.

Issues#

Critical#

None found.

High severity#

  • [qe-code-001] (reviewer) — Follow PEP8 unless closer to mathematical notation. Count: 9. Lines: 714, 761, 824, 898, 1021, 1030, 1060, 1839, 1864. Example: the two code cells are the least PEP8-conformant in the series. (1) Every keyword default in the constructor signature is spaced, 𝜒1 = 0, w10 = 0.9, ktop = 0.25 (714-734), and so is every keyword at the call site, BCG_incomplete_markets(w10 = w10, w20 = w20, ktop = 0.5, btop = 2.5) at 1839 - PEP8 asks for no spaces around = in a keyword argument or default. (2) Four statements end in a stray semicolon: rhs = const_qq1/((ww10-qq1*𝜃1)**(-𝜓1)); at 898, and the same at 943, 1461, 1536. (3) Lines 1021 and 1023 are indented 17 spaces under an if at 12, a five-space step that no other block in the file uses. (4) formattedList (1030, 1061) is camelCase with no mathematical justification; PEP8 asks for formatted_list. (5) Comparison and assignment operators are unspaced in the loop guards: while V_crit>1e-4 (824), b_crit=1 (834), while b_crit>1e-5 (836), k_crit=1 (844), while k_crit>1e-5 (846), while V_crit>1e-5 (1403). (6) Commas without a following space run through every call: quad(intqq1,epstar,bound, args=...) (889, 919, 937, 982, 1005, 1006), return kss,bss,Vss,qss,pss,... (1072), return Q1,Q2,P1,P2 (1130), np.linspace(kbot,ktop,N) (1160), eq_valuation(c10ss, c11ss, c20ss, c21ss,N=30) (1228, 1609, 1661), plt.subplots(3,2,figsize=(12,12)) (1864), plot(wlist,q1list,label='agent 1',color='green') (1911-1927). (7) if (rhs > qq1):, if (kfoc > 0):, if (bfoc > 0):, if (value_x > V): wrap their conditions in redundant parentheses (899, 929, 944, 986, 1009, 1020, 1462, 1486, 1516, 1537, 1573). (8) The banner comments #*****..., #=========== Setup ===========#, #======== (736, 785-787, 859-862, 869-871, 954-956, 971-977, 996-998, 1041-1043, 1075-1077) have no space after the #, and 1060 sits at 7 spaces inside an 8-space body. (9) self.u = njit(lambda c: (c**(1-𝜓)) / (1-𝜓)) at 761 references a name 𝜓 that the constructor never binds - it takes 𝜓1 and 𝜓2 - and only escapes a NameError because njit is lazy and self.u is never called.

  • [qe-fig-003] — No matplotlib embedded titles. Count: 9. Lines: 1866, 1868, 1870, 1872, 1874, 1889, 1915, 1922, 1926. Example: .set_title.

  • [qe-fig-008] — Use lw=2 for line charts. Count: 13. Lines: 1865, 1867, 1869, 1871, 1873, 1888, 1911, 1912, 1913, 1918, …. Example: plot() without lw=.

  • [qe-writing-001] — Use one sentence per paragraph. Count: 7. Lines: 567, 574, 630, 688, 692, 698, 1331. Example: 4 sentences in one paragraph.

  • [qe-writing-002] (reviewer) — Keep writing clear, concise, and valuable. Count: 6. Lines: 69, 155, 566, 629, 1896, 1932. Example: 69 is a 42-word single sentence carrying an inline {doc} link (“Note that the absence of complete markets means that now we cannot compute competitive equilibrium prices and allocations by first solving the simple planning problem that we did in …”), and 155-158 is 41 words that say only that price-taking is consistent (“a powerful device for making a host of competitive agents take as given the equilibrium prices that turn out to be determined by the decisions of hosts of agents who are just like them”). Two parenthetical apologies for the notation appear instead of a fix - 566-568 (“In this step we abuse notation by freezing \(V, k, b\) … little \(k, b\) are frozen at guessed at value of \(K, B\)”, which is also ungrammatical) and 629-631 (“Here we confess to abusing notation again, but now in a different way”). And three sentences carry no information: “Please stare at the above panels” (1896), “It is rewarding to stare at the above plots too” (1932) and “These subtle distinctions bear more thought and exploration” (1316).

  • [qe-writing-003] (reviewer) — Maintain logical flow. Count: 5. Lines: 566, 615, 700, 1217, 1423. Example: the pseudo-code section is the spine of the lecture and its internal cross-references do not resolve. The list at 558-661 writes 1. for all twelve items and gives its sub-bullets no letters, yet the prose inside it refers to “this step 6” (566-568), “steps 6Aa through 6Ad” (615), “steps 4 through 7A” (640), “steps 3 through 7B” (646), “step 6, and the firm choices … from step 7” (647-648), “steps 1 through 8” (654) and “In step 7, we interpret frozen \(c^i\)s as Big \(C^i\)” (630) - labels a reader cannot match to anything rendered. The documented parameter list at 686-700 does not match the signature either: it lists a single $\psi$: risk parameter where the class takes 𝜓1 and 𝜓2 (720-721), and omits Vl, Vh, kbot, ktop, bbot, btop, which the second example then has to set by hand (1839). At 1217-1218 the prose states “the equilibrium firm value is \(V=0.101\), with capital \(k = 0.151\) and debt \(b=0.484\)” while the cell immediately above (1211-1214) prints -kss+qss+pss*bss, Vss and 𝜃1ss - so two of the three numbers claimed are never shown, and all three are hard-coded in prose against a computed cell. And off_eq_check still carries the comment block “We impose the following: Agent 1 buys equity / Agent 2 buys equity and all debt” (1423-1425) inside the very function the prose at 1347-1350 introduces by saying “Importantly, we relax the condition that only agent 2 holds bonds”.

  • [qe-writing-005] (reviewer) — Use bold for definitions, italic for emphasis. Count: 16. Lines: 59, 60, 1280, 1281, 1284, 1308, 1320, 1334, 1349, 1591, …. Example: bold is used for emphasis at least as often as for definitions, and italic is used for emphasis alongside it, so neither convention is readable as a signal. Definitional bold is correct in places - price taker (145), symmetric (160), rational conjectures (66, 409), out-of-equilibrium (403) - but bold is emphasis at 59-60 (individual, aggregate, is in one sentence), 1280-1284 (both, and, in equilibrium), 1308 and 1314 (market’s), 1320 (stable), 1334-1335 (new twice), 1349 (both), 1591-1592 (not twice) and 1711-1712 (at the equilibrium). Meanwhile the same emphatic job is done in italic at 73 (different), 1302 (qualified), 1311 (unqualified), 1582 and 1715 (stability), 1694 (decrease) and 1899 (hedging desires). Separately, the quotation from BCG at 534-537 is set as a whole italic paragraph with math spliced into it rather than as a blockquote or {epigraph}, so the italics there read as emphasis too.

  • [qe-writing-008] — Remove excessive whitespace between words. Count: 41. Lines: 39, 45, 49, 60, 62, 64, 67, 144, 292, 299, …. Example: 2 spaces.

Medium severity#

  • [qe-fig-001] — Do not set figure size unless necessary. Count: 2. Lines: 1864, 1909. Example: figsize=.

  • [qe-fig-005] — Descriptive figure names for cross-referencing. Count: 2. Lines: 1862, 1907. Example: code-cell figure without mystnb figure metadata.

  • [qe-fig-010] — Plotly figures require latex directive. Count: 1. Lines: 1. Example: plotly used with no {only} latex directive.

  • [qe-math-009] (reviewer) — Choose simplicity in mathematical notation. Count: 4. Lines: 353, 485, 1333, 1805. Example: the same derivative is written two ways: u^\prime in the displays at 353-356, 365-366, 375-376, 391-392, 445-446, 458-459, 521, 580, 592, 604, 637, 643 and 1805-1806, and the simpler u' in the four Leibniz derivatives at 485, 490, 494 and 498 - 46 occurrences of the long form against 8 of the short. Line 1333 introduces the abbreviation “IMRS’s” in prose for a quantity the algebra always writes out as the ratio \(u'(C_1^i(\epsilon))/u'(C_0^i)\) and the code calls IMRS1/IMRS2 (1104-1105), so a third name for one object. And 1803-1808 switches to \(Q^i, P^i\) for the per-agent valuations of the same equity and bond that the rest of the lecture prices as \(q\) and \(p\), with no statement of the relation between the two pairs.

  • [qe-math-011 (proposed)] — Distribution names in plain letters, not \mathcal / \mathbb. Count: 2. Lines: 201, 207. Example: decorated distribution {\mathcal N}.

  • [qe-writing-007] (reviewer) — Use visual elements to enhance understanding. Count: 3. Lines: 267, 558, 1251. Example: the payoff functions at 267-274, \(d^e = \max\{e^\epsilon Ak^\alpha - b, 0\}\) and \(d^b = \min\{e^\epsilon Ak^\alpha / b, 1\}\), are the kink that everything else in the lecture turns on, and they are never plotted - two lines against \(\epsilon\) with \(\epsilon^*\) marked would make default and the two claims that follow it visible at once. The twelve-step, four-deep nested bisection of 558-661 is described only in prose and would be carried far better by a flow diagram, especially since its own step labels do not resolve (see qe-writing-003). And the central verification - is the red dot at the top of the surface? - is asked five times of a fixed-camera 3D plotly surface exported to PNG (1251-1276, 1614-1640, 1666-1691, 1726-1752, 1756-1782), where a 2D slice \(V(k^*, b)\) against \(b\) with the chosen \(b\) marked would answer it unambiguously; the same 25-line plotly block is also pasted five times with only the data and the title changed.

Low severity#

None found.

Strengths#

  • The Big K, little k device is set up once and then honoured: 115-118 indexes an individual consumer by \(\omega\) and 133-135 a firm by \(\zeta\), 143-153 states exactly which objects each agent takes as given, and 160-166 says what symmetry means for consumers and firms separately - which is what lets 398-399 point at the big \(C^i\) sitting on the right side of the pricing functions at 389-394 and name that as the whole content of the rational-conjectures assumption.

  • The default threshold is derived rather than asserted and then reused everywhere without restatement: 257-262 turns the condition \(e^\epsilon A k^\alpha < b\) into \(\epsilon^* = \log(b/Ak^\alpha)\), 451-452 and 524-525 recall it at exactly the two points it is needed, it becomes the integration limit in every pricing formula at 456-461 and 484-499, and the code computes it at the same three places (856, 1112, 1415).

  • The four Leibniz-rule derivatives are written out one per display at 484-499 instead of being asserted, so the two first-order conditions {eq}`Eqn1` and {eq}`Eqn2` at 511-522 can be checked by hand against the code’s kfoc (984) and bfoc (1005-1007).

  • The qualified Modigliani-Miller claim is tested, not stated: the plan at 1326-1338 perturbs \(b\) off equilibrium in both directions, off_eq_check (1365-1579) relaxes the restriction that only agent 2 holds bonds so that the perturbation is admissible, the two experiments at 1601-1691 show the red dot off the peak in both directions, and the by-product that agent 1 then wants bonds is printed at 1704-1708.

  • The two lectures’ conclusions are laid side by side as matched bullet lists at 49-52 and 56-60, one line per claim, and 69-71 says exactly what incompleteness costs computationally - the planning problem is gone, so the equilibrium is found by solving simultaneous inequalities.

  • The comparative-statics sweep at 1830-1859 varies one thing, the endowment split \(w_0^2/(w_0^1+w_0^2)\), and plots all nine resulting panels against that same axis (1862-1891, 1907-1929), which is what makes the closing claim at 1934-1940 - equity valuations equalise across agent types while bond valuations do not - readable straight off the figures.