Add Schelling segregation model lectures

[jstac]

Summary

This PR adds a new Racial Segregation section to the lecture series, containing five new lectures on the Schelling segregation model. The lectures form a progressive sequence that builds from pure Python through to parallelized JAX, making them a natural fit for this JAX-focused lecture site.

New lectures

The five lectures added are:

1. Schelling's Model of Racial Segregation (schelling.md) — Introduces the classic 1969 Schelling model of racial residential segregation. Covers the motivation (real-world segregation patterns in US cities), the model setup (agents on a grid with mild preferences for same-type neighbors), and a pure Python implementation. Includes satellite imagery of Columbus, Memphis, Washington DC, Houston, and Miami illustrating observed segregation patterns.

2. Schelling Model with NumPy (schelling_numpy.md) — Rewrites the model using NumPy arrays and vectorized operations for improved performance over the pure Python version, at some cost to readability.

3. Schelling Model with JAX (schelling_jax.md) — Ports the model to JAX, introducing JIT compilation and GPU/TPU acceleration. Demonstrates how JAX — widely used for AI workflows — can be repurposed for agent-based economic simulations.

4. Parallelizing the Algorithm (schelling_jax_parallel.md) — Addresses the inherently sequential nature of the basic Schelling algorithm by introducing a parallel variant. Explores how to restructure the computation to better exploit JAX's parallelization capabilities.

5. Segregation with Persistent Shocks (schelling_shocks.md) — Extends the model by adding persistent stochastic shocks, moving beyond the static equilibrium of the basic model to study ongoing dynamics.

Structural changes

• _toc.yml: Added a new "Racial Segregation" section (placed before the existing "Other" section), containing all five lectures in the sequence listed above.
• _static/fig/: New directory containing five .webp satellite images of US cities (Columbus, Memphis, Washington DC, Houston, Miami) used in the introductory lecture to illustrate real-world segregation patterns.
• _static/lecture_specific/schelling/: Four .png figures (schelling_fig1.png through schelling_fig4.png) used across the lectures.

Cross-references

The lectures use {doc} cross-references to link to each other in sequence (e.g., "In the {doc}previous lecture <schelling>..."), forming a coherent reading path through the material.

Build verification

• The book builds successfully with execute_notebooks: "off" (no new warnings — only pre-existing lexing warnings from !pip/!nvidia-smi commands in other lectures).
• Full build with notebook execution has not yet been run — these lectures are GPU-intensive and need to be built on a machine with a GPU. The cached notebook outputs are not yet generated.

TODO

• Run full build with notebook execution on a GPU-equipped machine
• Verify all notebook outputs render correctly

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for incomparable-parfait-2417f8 ready!

Name	Link
🔨 Latest commit	48a6002
🔍 Latest deploy log	https://app.netlify.com/projects/incomparable-parfait-2417f8/deploys/69d32ef5c9f662000899f6fd
😎 Deploy Preview	https://deploy-preview-296--incomparable-parfait-2417f8.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[jstac]

Build Failure Analysis

Both CI checks (preview and execution-checks) are failing for the same root cause:

1. sphinx_proof not loaded as a Sphinx extension

lectures/_config.yml line 36 lists extra_extensions but does not include sphinx_proof:

extra_extensions: [sphinx_multitoc_numbering, sphinxext.rediraffe, sphinxcontrib.youtube, sphinx.ext.todo, sphinx_exercise, sphinx_togglebutton, sphinx_tojupyter]

The package is installed (via environment.yml) but never activated, so the {prf:algorithm} directives in lectures/schelling.md (lines 218 and 346) produce:

WARNING: Unknown directive type: 'prf:algorithm' [myst.directive_unknown]

The build is configured to treat warnings as errors, so this causes the build to fail.

Fix: Add sphinx_proof to the extra_extensions list in lectures/_config.yml.

2. Version mismatch in collab.yml

.github/workflows/collab.yml (line 35) pins sphinx-proof==0.3.0, but environment.yml has sphinx-proof==0.4.0. The execution-checks job uses the older version from collab.yml.

Fix: Update collab.yml to use sphinx-proof==0.4.0 to match environment.yml.

[jstac]

@mmcky , can you please have a look. i asked claude to report on the issues but not fix so i don't tread on your toes.

I'm just running a build on the GPU server so I might add to this PR in the next 30 minutes -- I'll be done after that.

(PS spelling is colab not collab)

[jstac]

Local Build Results (GPU server)

Ran a local build on a GPU server using the quantecon conda environment. The build completed successfully but with 9 warnings. Beyond the prf:algorithm issue reported above, these additional (pre-existing) issues were found:

mle.md notebook execution failure

/lectures/mle.md: WARNING: Executing notebook failed: CellExecutionError

Error log: lectures/_build/html/reports/mle.err.log

wealth_dynamics.md notebook execution failure

/lectures/wealth_dynamics.md: WARNING: Executing notebook failed: CellExecutionError

Error log: lectures/_build/html/reports/wealth_dynamics.err.log

Unknown config value exercise_style

WARNING: unknown config value 'exercise_style' in override, ignoring

These three are pre-existing issues on main, not introduced by this PR. However, CI's -W flag (warnings as errors) means they also contribute to build failures.

[jstac]

all yours @mmcky . the local build on the GPU server flagged some problems with other lectures as well -- would you mind checking those too?

[Copilot]

Pull request overview

This PR adds a new “Racial Segregation” section to the lecture series, introducing a five-lecture sequence on the Schelling segregation model that progressively moves from pure Python to NumPy to JAX and parallel JAX, culminating in a persistent-shocks extension.

Changes:

• Added 5 new Schelling-model lectures (schelling*.md) covering Python, NumPy, JAX, parallel JAX, and persistent shocks.
• Updated lectures/_toc.yml to include a new “Racial Segregation” part with the five lectures in sequence.
• Added new static assets: 5 satellite .webp maps and 4 lecture-specific .png figures.

Reviewed changes

Copilot reviewed 6 out of 15 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
lectures/_toc.yml	Adds the new “Racial Segregation” section and orders the new lecture sequence.
lectures/schelling.md	Introduces the model and a pure-Python implementation plus background maps.
lectures/schelling_numpy.md	Reimplements the model with NumPy arrays and helper functions.
lectures/schelling_jax.md	Ports the model to JAX and introduces JIT + key-based RNG patterns.
lectures/schelling_jax_parallel.md	Introduces a parallel JAX variant and a “horse race” comparison.
lectures/schelling_shocks.md	Extends the parallel JAX model with persistent type-flip shocks.
lectures/_static/fig/columbus.webp	Satellite map used in the introductory lecture.
lectures/_static/fig/memphis.webp	Satellite map used in the introductory lecture.
lectures/_static/fig/washington_dc.webp	Satellite map used in the introductory lecture.
lectures/_static/fig/houston.webp	Satellite map used in the introductory lecture.
lectures/_static/fig/miami.webp	Satellite map used in the introductory lecture.
lectures/_static/lecture_specific/schelling/schelling_fig1.png	Lecture-specific figure used across the Schelling sequence.
lectures/_static/lecture_specific/schelling/schelling_fig2.png	Lecture-specific figure used across the Schelling sequence.
lectures/_static/lecture_specific/schelling/schelling_fig3.png	Lecture-specific figure used across the Schelling sequence.
lectures/_static/lecture_specific/schelling/schelling_fig4.png	Lecture-specific figure used across the Schelling sequence.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

num_unhappy returned from get_unhappy_agents is a JAX scalar (jax.Array). if num_unhappy == 0: will raise a TypeError because the condition is an array, not a Python bool. Convert to a Python scalar (e.g., num_unhappy = int(num_unhappy) / .item()) before the if (and reuse that scalar for the subsequent range).

Suggested change

	# Check if everyone is happy
	if num_unhappy == 0:
	break
	# Update only the unhappy agents
	for j in range(int(num_unhappy)):
	num_unhappy = int(num_unhappy)
	# Check if everyone is happy
	if num_unhappy == 0:
	break
	# Update only the unhappy agents
	for j in range(num_unhappy):

[mmcky]

Fixed in 1e38ec3. Added num_unhappy = int(num_unhappy) after get_unhappy_agents returns. The int() conversion must happen at the call site because get_unhappy_agents is @jit-compiled and can only return JAX arrays.

[github-actions]

🚀 Deployed on https://69d331f0cf8430a8d5c574b0--incomparable-parfait-2417f8.netlify.app

[mmcky]

@jstac this is now building and I have resolved the COPILOT review feedback. I have resolved the straightforward issues -- Are you happy with these code changes? The fixes are committed and the comment provides some context.

[mmcky]

@jstac 👀 on the code cell background in the preview. Looking into this now.

[mmcky]

@jstac this looks good to me now.

https://69d330e5b5b2cac0e3a13d13--incomparable-parfait-2417f8.netlify.app/intro.html

Let me know what you think of the code changes in 1e38ec3

[jstac]

Thanks @mmcky ! Looks good. Please go ahead and merge when ready.