PUBLIC NOTEBOOK LOCATION
========================
The executable notebook artifacts now live at:
https://github.com/querygraph/eigenmath/tree/main/notebooks

Clone https://github.com/querygraph/eigenmath.git beside this repository, or set
EIGENMATH_ROOT to that checkout. Build, execution, and parity commands below now
read/write notebook artifacts there. HTML reading copies remain in this book's
notebooks directory. Book manuscripts, lessons, and frozen releases stay here.
Install the reusable mobile controls from eigenmath's versioned release wheel;
one installation serves every notebook in Notebook 7 and JupyterLab 4.

The Mathematics of Anthropology — executable teaching editions
=============================================================

These are complete companion notebooks, not slide summaries. Both contain the
full version 1.1.0 text, embedded reference figures, and interleaved executable
lessons. The Python and OCaml editions use the same numerical examples. Read
and run one edition at a time; compare the other when teaching implementation.

Files
-----
anthropology-math-python.ipynb  Python / NumPy teaching edition
anthropology-math-ocaml.ipynb   Native OCaml teaching edition
lessons.py                   Editable bilingual laboratory sources
build.py + notebook.json    Reproducible notebook builder and source provenance
coverage.json               All lesson locations and manuscript section counts
verification.json           Complete-text and successful-execution checks
check_pair.py + parity.json Numerical agreement between Python and OCaml
requirements.lock           Exact Python environment used for verification

The notebook edition and canonical companion text are version 1.1.0. Delivered filenames include this notebook
version and its source commit; notebook metadata also records the original book
version, manuscript commit, and content hashes. Preserve older deliveries. Make
corrections as notebook patch versions and regenerate from sources.

Read and teach
--------------
Open the .ipynb file in JupyterLab. Select the matching language kernel, then use
Kernel > Restart Kernel and Run All Cells. All code runs in order; subsequent
lessons reuse earlier definitions. Read the paragraph above a laboratory before
running it. Ask students to predict the output, run the cell, and then vary one
input. Assertions express reference examples and mathematical identities; when
changing the problem, examine which reference expectations also need changing.

Suggested sequence: vector prerequisites; standardized news coordinates; person
and article associations; balanced profiles; people SVD; reciprocal navigation;
neighbors and time; attention; proposed ontology calibration. The Mathematics of
Eigen Times provides the deeper prerequisites. Complete its early lessons first
if vectors, matrices, covariance, or singular value decomposition are new.

Original figures are embedded, with visible captions. Code uses tiny synthetic
inputs or explicitly frozen numerical fixtures. Historical archive-wide values
are retained as dated evidence, not regenerated from a private archive. Notebook
calculations make no network calls and require no credentials. Installation of
the runtimes/dependencies does require network access. Reference links are
optional reading, not dependencies of Run All.

Install Python
--------------
Use Python 3.12. In this folder:

  python3.12 -m venv .venv
  .venv/bin/python -m pip install -r requirements.lock
  .venv/bin/python -m ipykernel install --user --name math-companion-python --display-name "Python (Math companions)"
  .venv/bin/jupyter lab

Select Python (Math companions) for the Python notebook. On Windows, use the
equivalent .venv/Scripts commands. The lock records the tested macOS environment;
package availability on a different platform must be checked there.

Install OCaml
-------------
Install OCaml through opam and the Jupyter kernel in your chosen switch. These
lessons compute using native OCaml arrays and standard-library numerical helpers;
they do not require Owl, a Python bridge, or an external numerical service.

  opam install jupyter
  eval $(opam env)
  ocaml-jupyter-opam-genspec
  .venv/bin/jupyter kernelspec install --user --name ocaml-jupyter "$(opam var share)/jupyter"

Select OCaml for the OCaml notebook. The verified runtime was OCaml 5.5.1. If
your kernel is registered with a different name, select it in Jupyter or pass
that name to build.py execute. Kernel installation details and system-library
prerequisites are documented by OCaml Jupyter:
https://akabe.github.io/ocaml-jupyter/

Rebuild and verify (source checkout)
-----------------------------------
The delivered notebooks run on their own. Regenerating them also requires the
owning repository's manuscript and figures at the recorded revision.

  .venv/bin/python build.py build
  .venv/bin/python build.py execute --language python --kernel math-companion-python
  .venv/bin/python build.py execute --language ocaml --kernel ocaml-jupyter
  .venv/bin/python build.py verify --executed
  .venv/bin/python check_pair.py
  .venv/bin/python build.py html

Execution uses a fresh empty temporary working directory. Any missing fixture,
cell exception, missing manuscript section, or broken embedded attachment fails
verification. Sources of both language editions are kept together in lessons.py
so a numerical correction can be applied consistently. Eigenvector signs are
oriented consistently; reconstruction/projector checks handle sign ambiguity.

Notebook format and execution documentation:
https://nbformat.readthedocs.io/en/latest/format_description.html
https://nbclient.readthedocs.io/en/latest/client.html

Original book: https://firstpair.org/read/anthropology-math/
Source owner: https://github.com/querygraph/anthropology

Drafts and release safety
-------------------------
While editing, use an isolated output directory and pass --draft to every build,
execution, verification, parity and reader-export command. For example:

  export EIGENMATH_ROOT="$(mktemp -d /tmp/math-notebook-draft.XXXXXX)"
  python build.py build --draft
  python build.py execute --language python --draft
  python build.py execute --language ocaml --draft
  python build.py verify --executed --draft
  python check_pair.py --draft
  python build.py html --draft

Draft notebooks go under that directory's notebooks/; reports and HTML readers
live under .author/anthropology-math/. Draft operations reject the canonical public eigenmath
checkout and retain the existing release receipts in this source checkout.
A draft cannot pass release verification or delivery.

Before final builds, commit and push the complete source worktree. Restore
EIGENMATH_ROOT to the intended eigenmath checkout and run the same commands
without --draft. A released notebook version cannot be rebuilt or reexecuted;
corrections require a new semantic version. The bounded source inventory contains
canonical text, notebook code, figures, runtime lock and book build inputs; it
excludes generated readers, receipts, dist/ and release manifests. Verification
compares those inputs with the frozen source commit, so a subsequent artifact
storage commit does not change the edition's recorded source identity.

Every laboratory follows its parent heading's complete descendant explanation.
The builder preserves cell IDs for unchanged cells when material moves. It
checks all canonical prose and embedded figures, exact code and lesson order,
explicit internal anchors, and a complete unique RESULT_KEYS list. Each language
runs in a fresh kernel with an empty working directory; kernel errors and printed
OCaml Error/Exception diagnostics fail. Numerical receipts must include exactly
the declared finite values. Parity and reader receipts bind to notebook bytes.

After parity and HTML export, deliver.py DESTINATION writes immutable regular
versioned notebooks, readers, checksums and a source/study ZIP. It checks every
receipt and preflights every target before copying or updating release.json.
The owning book package may also bundle these validated study artifacts.

Notebook computations run offline after dependency installation. Notebook HTML
reading copies load MathJax from a CDN for equations and therefore need a network
connection in an ordinary browser. Book HTML and EPUB retain native MathML.
