Executable articles — Jupyter Book & iNQspace
Castalia Institute — Mag.AI-Science
Mag.AI-S treats scientific writing and code as one surface: an executable article is narrative (Markdown), math, figures, and runnable computation that readers (and reviewers) can trace from claim to implementation. The program standardizes how that surface is produced and graded.
Two layers, one artifact line¶
| Layer | Role |
|---|---|
| Jupyter Book / MyST (this repo) | Published course materials: program hub, each course book, syllabi, lectures, and Jupyter notebooks listed in each course’s myst.yml. Builds to static sites on Magisterium. |
| iNQspace | Execution environment: where notebooks and pipelines actually run, where data and tool scopes attach, and where lineage (versions, seeds, outputs) is recorded for faculty review. |
Students author and iterate in iNQspace; the canonical public map for each module lives in the Jupyter Book for that course. The notebook files in courses/AINS-S####/notebooks/ are part of the same Git lineage as the prose—not a separate “lab handout.”
What counts as an executable article¶
At minimum, an executable article for this program includes:
Readable narrative — assumptions, methods, and limits stated in Markdown (in the notebook and/or linked lectures).
Runnable cells — code or queries that reproduce a table, figure, or intermediate result material to the claim.
Reproducibility metadata — environment notes, seeds, data references, or pointers to iNQspace lineage as your faculty requires.
Honest scope — what was not run, what would break if data shifted, and what a reviewer should re-run first.
Faculty may require additional structure (e.g. SAMWISE prompts, MCP tool logs); see the course syllabus.
Jupyter Book conventions (per course)¶
Each course book under courses/AINS-S####/ includes:
SYLLABUS.md,lectures/*.mdnotebooks/*.ipynb— executable articles and lab sequences, built into the same sidebar as the lectures
Regenerate myst.yml after adding or renaming notebooks: python3 scripts/generate_course_myst.py (the generator includes the notebook pattern when the notebooks/ tree contains .ipynb files).
Placeholders named 00_executable_article_placeholder.ipynb mark where cohort-specific notebooks will land; replace or extend them with real modules.
Why not “slides + separate notebook dump”¶
Slides-first teaching hides the mechanism of science. Executable articles force alignment between what you claim in prose and what your code actually does—the same alignment peer review and replication demand.
Related¶
Design — degree philosophy and learning model
Full curriculum — Executable articles & iNQspace spine
Assessment — inspectable artifacts