Skip to content

CLAUDE.md

Latest commit

 

History

History
262 lines (185 loc) · 17.5 KB

CLAUDE.md

File metadata and controls

262 lines (185 loc) · 17.5 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

University course materials repository for "Introduction to Planetary Science" at the Kapteyn Astronomical Institute of the University of Groningen. The main lecturer is Tim Lichtenberg from the Kapteyn Institute. This course is a BSc Astronomy mandatory course for 2nd-year students, covering fundamental concepts in planetary science, including planet formation, solar system dynamics, exoplanets, and astrobiology. The repository contains lecture notes, figures, and planning documents for the course. The lecture notes are written in MyST Markdown and built into HTML and PDF formats using Jupyter Book. The course emphasizes scientific accuracy, proper citation of sources, and clear explanations suitable for undergraduate students.

Repository Structure

  • book/ — Jupyter Book source (MyST Markdown lecture notes, built to HTML and PDF)
    • book/_config.yml — Jupyter Book configuration (XeLaTeX, MathJax3, bibliography)
    • book/_toc.yml — Table of contents
    • book/intro.md — Landing page
    • book/01_introduction/ through book/14_synthesis/ — 14 lecture chapters, each with a .md file and figures/ directory
    • book/references.bib — BibTeX bibliography
    • book/_static/custom.css — Custom styles
  • planning/ — Curriculum outlines and course planning documents
  • content/course2025 — Symlink to Google Drive containing previous lecture materials (slides, data, etc.); gitignored and not tracked
  • .github/workflows/book.yml — GitHub Actions workflow deploying HTML to GitHub Pages

High-level Instructions

  • *Always check and update planning/course_development.md when making any changes to the lecture content, schedule, or curriculum. This document serves as the master plan for the course and must reflect the current state of development.
  • When editing lecture content, ensure scientific accuracy by verifying all claims against authoritative sources and citing them properly in the ## References section.
  • When adding new lectures or sections, maintain the established structure and formatting conventions (MyST Markdown, math macros, citation style).
  • When searching for literature to cite, prioritize peer-reviewed journal articles, review papers, and authoritative databases (NASA, IAU) over textbooks or web sources. Always include a DOI when available.
  • When looking for literature, check content/books for authorative sources, but verify that they are still accurate and relevant before citing.
  • When looking for literature, check content/course2025 for previously used sources and lecture materials, but verify that they are still accurate and relevant before citing.
  • When looking for literature, use the NASA ADS database (https://ui.adsabs.harvard.edu/) to find recent papers on planetary science topics. Use the bibtex export option to generate BibTeX entries for new sources.
  • Give extra weight to the articles and referenced papers in https://ui.adsabs.harvard.edu/public-libraries/L2e3RhUYQnqmpIyMpWUG3A. In particular, the review articles in that library are likely to be highly relevant and authoritative sources for content and/or point to the most reliable sources.
  • When adding or editing content, ensure that all numerical values, equations, and historical claims are verified against primary sources or authoritative databases. Do not rely on training data alone for factual accuracy.
  • All lectures should have good visuals (figures, diagrams) where appropriate. When adding figures, ensure they are properly referenced in the text and included in the figures/ directory of the corresponding lecture.
  • For all figures prioritize original sources (e.g., from NASA missions, published papers; take the figures from arXiv) and figures from the public domain. Ensure proper attribution in the caption. Avoid using low-quality or uncredited images.
  • For figures, you can also use (cut out or screenshot) figures from contents/books and contents/course2025 if they are relevant and properly cited, but verify that they are still accurate and up to date before including them in the lecture notes.
  • Double and triple check all citations for accuracy, including author names, publication year, journal, and DOI. Do not invent DOIs — if unsure whether a DOI exists, omit it and flag for manual verification with a comment: % TODO: verify DOI.
  • Double and triple check all links (DOIs, URLs) to ensure they resolve correctly. For web resources, use the most stable/canonical URL available and note the access date in the BibTeX note field if the content is known to change frequently.
  • Double and trip check all math equations for dimensional consistency and physical correctness. After writing a derivation, verify that the units on both sides match and check limiting cases to ensure the equation behaves as expected.

Build System

Uses Jupyter Book v1 (jupyter-book<2) with Sphinx backend. Dependencies in pyproject.toml.

Environment setup

Requires Python 3.12+.

pip install .

Build commands

make html       # Build browsable HTML → book/_build/html/
make pdf        # Build PDF via pdfhtml → book/_build/pdf/
make pdflatex   # Build PDF via XeLaTeX → book/_build/latex/
make slides     # Build slide PDFs → slides/lectureNN/lectureNN.pdf
make clean      # Remove build artifacts + generated PNGs

Build artifacts in book/_build/ are gitignored. The pdflatex and slides targets auto-convert AVIF→PNG at build time (XeLaTeX cannot read AVIF natively).

Deployed site

HTML is auto-deployed to GitHub Pages on push to main: https://formingworlds.github.io/IntroductionToPlanetaryScience/

Key Technical Details

  • The course covers 14 lectures spanning planet formation through exoplanets and astrobiology (see planning/course_development.md for full curriculum, schedule, homework, and exam structure).
  • Each lecture includes a ~10 min blackboard derivation of a foundational concept.
  • Lecture notes use MyST Markdown with cross-reference labels (lecture01)= through (lecture14)=.
  • Math macros are defined in both mathjax3_config (HTML) and latex_elements.preamble (PDF) in _config.yml — new macros must be added to both.
  • The physics LaTeX package conflicts with Sphinx output; custom \dv, \dd, \pdv macros are used instead.
  • LaTeX packages available: amsmath, amssymb.
  • Custom math macros defined in _config.yml (available in both HTML and PDF):
    • \dv{f}{x} — total derivative, \dd — differential d, \pdv{f}{x} — partial derivative
    • \Msun, \Rsun, \Lsun — solar mass, radius, luminosity
    • \Mearth, \Rearth — Earth mass, radius
    • \Mjup, \Rjup — Jupiter mass, radius
    • \kB — Boltzmann constant
  • The sphinx-proof extension is loaded, providing theorem-like directives: {prf:theorem}, {prf:proof}, {prf:definition}, {prf:example}, etc.
  • Figures live in <lecture_dir>/figures/ and are referenced with MyST syntax: ```{figure} figures/filename.avif```
  • All raster images must use AVIF format (.avif). Do not commit JPEG or PNG files — convert to AVIF first using magick input.jpg -quality 65 output.avif. SVG vector graphics are kept as-is. See the "Image format" section below for details.

References & Citations

Every lecture must have a "References" section

Each lecture .md file in book/ must end with a dedicated ## References section that lists all sources cited in that lecture. This section:

  • Appears as the final section of the lecture, after all content sections

  • Uses BibTeX citations via sphinxcontrib-bibtex (configured in book/_config.yml)

  • All BibTeX entries live in book/references.bib (the single shared bibliography file)

  • Citations in the text use MyST syntax with explicit Chicago author-date roles (see Citation style below)

  • The references section renders the bibliography for that lecture using:

    ## References

```{bibliography}
:filter: docname in docnames
```

    The :filter: docname in docnames directive ensures only sources cited in that specific lecture are listed — not the entire bibliography.

Citation style

This project uses Chicago author-date citation style, configured in _config.yml as bibtex_reference_style: author_year. All citations must use explicit roles — do not use the bare {cite}`key` form.

Parenthetical citations: {cite:p}

Use {cite:p}`key` for citations that appear as a parenthetical reference at the end of a clause or sentence. This renders as (Author, Year).

The disk lifetime is roughly 3–5 Myr {cite:p}`Haisch2001`.

Do not wrap {cite:p} in manual parentheses — the role already adds them. Writing ({cite:p}key) produces double parentheses ((Author, Year)).

To cite multiple sources in one parenthetical, separate keys with commas:

Seismic data constrain the core and mantle {cite:p}`Stahler2021,Khan2021`.

Narrative (textual) citations: {cite:t}

Use {cite:t}`key` when the author is the grammatical subject of the sentence. This renders as Author (Year).

{cite:t}`Birch1952` established an empirical relationship between wave velocity and density.

Bibliography formatting

The bibliography list uses a custom pybtex Chicago style (bibtex_default_style: chicago in _config.yml), implemented in src/ips_styles/chicago.py and registered via entry points in pyproject.toml. This style:

  • Formats entries as: Author. Year. "Title." Journal Volume(Number): Pages. doi:DOI. URL.
  • Uses citation keys as labels (hidden by CSS in book/_static/custom.css)
  • Sorts entries alphabetically by author, then year, then title

After modifying the style, run pip install -e . to re-register the entry point.

BibTeX key format

  • Keys follow the format AuthorYear (e.g., Lichtenberg2021, Raymond2022), or AuthorYearLetter when there are multiple papers by the same first author in the same year (e.g., Wordsworth2013a, Wordsworth2013b)
  • Prefer DOI-bearing entries; include doi = {} field in every BibTeX entry where available
  • Prefer peer-reviewed journal articles over textbooks or web sources; use review articles where appropriate for broad topics

Open-access links in BibTeX entries

Every BibTeX entry must include a link to an open-access source, in order of preference:

  1. NASA ADS (preferred): url = {https://ui.adsabs.harvard.edu/doi/{DOI}/abstract} — works for most journal articles and conference papers indexed by ADS
  2. arXiv: eprint = {XXXX.XXXXX} with archivePrefix = {arXiv} — for preprints and papers with arXiv versions
  3. Publisher open access: Direct URL to an open-access PDF or landing page (e.g., Nature Communications, Science Advances, open-access journals)
  4. Institutional repository or other stable URL: Use the url field

For entries that have BOTH a DOI and an arXiv eprint, include both fields — the Chicago style will render both links. For books, include the ADS URL if the book is indexed there; otherwise omit the URL field (the DOI link is sufficient).

When adding or editing lecture content

  1. Every factual claim, equation, or dataset that originates from a specific source must be cited
  2. Add the corresponding BibTeX entry to book/references.bib if it does not already exist
  3. Verify that the ## References section with the {bibliography} directive is present at the end of the lecture file
  4. Always update planning/course_development.md to reflect the changes — this includes:
    • The lecture outline (section 2) if topics are added, removed, or reordered
    • The status table (section 5) to track progress (e.g., "Not started" → "In progress" → "Draft complete")
    • The homework or exam sections if related content changes

When adding or editing slide content

  1. Every factual claim, equation, or dataset that originates from a specific source must be cited on the slide where it appears
  2. The lectures should be dominated by figures and equations, with minimal text — citations should be included in the figure captions or as small footnotes on the slide. Text should mainly appear as bullet points or annotations on figures, not as large paragraphs.
  3. The corresponding BibTeX entry must be added to book/references.bib if it does not already exist
  4. The lecture notes (MyST Markdown) must also be updated to include the new content and citations, following the same process as above (add content, add citations, update references section, update course development plan)
  5. Ensure that the slide content and lecture notes are consistent with each other — if a new figure or dataset is added to the slides, it should also be described and cited in the lecture notes
  6. The slides should be visually engaging, with clear labels, legends, and annotations to aid understanding
  7. All slides should share a common visual style (colors, fonts, layout) consistent with the course branding.

Scientific Accuracy & Source Verification

Verification requirements

When writing or editing lecture content, invest substantial effort in verifying scientific accuracy. This is a university-level course — errors in the notes directly mislead students.

Specifically:

  • Numerical values (physical constants, planetary parameters, orbital elements, isotopic ratios, etc.) must be checked against authoritative sources (NASA Planetary Fact Sheets, IAU standards, recent review articles). Do not rely on training data alone — look up and cite the source.
  • Equations and derivations must be dimensionally consistent and physically correct. After writing a derivation, verify units on both sides and check limiting cases.
  • Historical claims (discovery dates, mission timelines, naming conventions) must be verified against primary or well-established secondary sources.
  • Planetary data should preferably reference NASA/JPL Solar System Dynamics, the Planetary Fact Sheet, or equivalent authoritative databases, with the access date noted where relevant.
  • Exoplanet statistics (occurrence rates, demographics, detection counts) change frequently — always cite the specific study and year, and note that numbers are approximate.

Common pitfalls to check

  • Confusing mass and weight, or mixing up $M_\oplus$ and $M_J$ scales
  • Using outdated values (e.g., number of confirmed exoplanets, Hubble constant, atmospheric compositions updated by recent missions)
  • Incorrect unit conversions (AU ↔ km, bar ↔ Pa, K ↔ °C)
  • Attributing discoveries or models to the wrong author or year
  • Citing retracted or superseded results without noting the update
  • Broken or non-persistent URLs — prefer DOIs over direct URLs for journal articles

Link and DOI verification

  • All DOIs should resolve correctly (format: https://doi.org/10.xxxx/...)
  • Do not invent DOIs — if unsure whether a DOI exists, omit it and flag for manual verification with a comment: % TODO: verify DOI
  • For web resources (NASA fact sheets, mission pages), use the most stable/canonical URL available
  • If a URL is known to change frequently, note the access date in the BibTeX note field

Content Style

  • Write at the level of a 2nd-year BSc Astronomy student (see prerequisites in planning/course_development.md)
  • Define technical terms on first use
  • Use SI units throughout; use astronomical conventions where standard (AU, solar masses, etc.)
  • Chemical formulae use plain LaTeX math mode with \mathrm{} (e.g., $\mathrm{CO_2}$, $\mathrm{H_2O}$). Do not use \ce{} from mhchem — it does not render reliably in the Jupyter Book build pipeline
  • Cross-reference other lectures using MyST labels: {ref}`lecture01` through {ref}`lecture14`

Image Format

All raster images in this repository use AVIF (AV1 Image File Format) as the standard format. Do not commit JPEG or PNG raster files.

Why AVIF

  • ~50% smaller than JPEG at equivalent visual quality, reducing repo size and page load times
  • Supports both photographic and graphic content well
  • Native browser support for the Jupyter Book HTML output

Conversion

Convert any new raster image to AVIF before adding it to the repository:

magick input.jpg -quality 65 output.avif    # photographic images
magick input.png -quality 65 output.avif    # diagrams / screenshots

Use quality 65 as the default. For images where compression artifacts are noticeable (fine line art, text-heavy diagrams), increase to 75–80.

SVG vector graphics

Keep SVG files as-is — do not convert them to AVIF. SVGs are resolution-independent and typically smaller for diagrams, charts, and schematics.

LaTeX compatibility

XeLaTeX cannot read AVIF files natively. The Makefiles handle this automatically:

  • make pdflatex and make slides run an avif2png step that generates temporary PNG files from AVIF before compiling LaTeX
  • Generated PNGs are gitignored (book/**/figures/*.png, slides/**/*.png)
  • In slide .tex files, use extensionless \includegraphics{image_name} so XeLaTeX finds the generated PNG
  • In book .md files, use the .avif extension in {figure} directives — the build system handles the LaTeX substitution

When adding figures

  1. Download or create the image in any format
  2. Convert to AVIF: magick source.jpg -quality 65 figures/name.avif
  3. Reference in MyST: ```{figure} figures/name.avif```
  4. Reference in slides: \includegraphics{name} (no extension)
  5. Delete the original source file — only commit the .avif