diff --git a/CHANGELOG.md b/CHANGELOG.md index 0e5b497..3b79aef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,10 @@ will make up v0.1.0. per-modality support-status table - `tools/ci/check_doc_links.py`, a link checker for relative Markdown links, run as a required `doc_links` CI job +- `docs/tutorials/`, an index of end-to-end tutorials grouped by application + area. The materials tutorial moved from `docs/materials_prism_tutorial.md` to + `docs/tutorials/material_science/materials_prism_tutorial.md`; notebooks stay + next to their scripts in `applications//` ### Changed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fcce00..312dabb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -274,6 +274,7 @@ descriptions and return types where they are not obvious from the signature. | `modalities/` | Encoders, projectors, output decoders | | `models/` | Backbone integrations | | `evaluation/` | Universal evaluator, vLLM inference | + | `tutorials/` | End-to-end walkthroughs, one folder per application area; notebooks stay in the top-level `applications//`, not `docs/applications/` | | `applications/` | Scientific applications (BioReason, KEGG, materials) | | `api/` | API reference for the public `src.*` surface | | `development/` | CI and contributor tooling | diff --git a/README.md b/README.md index 8d839a4..9463ec1 100644 --- a/README.md +++ b/README.md @@ -375,6 +375,7 @@ PRISM/ [docs/index.md](docs/index.md) indexes every page. Most-used entry points: - [docs/getting-started.md](docs/getting-started.md) — clone → environment → first run +- [docs/tutorials/README.md](docs/tutorials/README.md) — end-to-end tutorials by application area (BioReason, materials, …) - [docs/platforms/site_paths.md](docs/platforms/site_paths.md) — configuring the `PRISM_*` roots - [docs/platforms/aurora_operations.md](docs/platforms/aurora_operations.md) — Aurora ops, env, CCL tuning, troubleshooting - [docs/training/training.md](docs/training/training.md) — training stages diff --git a/docs/index.md b/docs/index.md index 4bb281a..badbe1f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -98,6 +98,18 @@ loadable as Claude agent skills or read as docs. See the | [getting-started.md](getting-started.md) | Clone, pick a platform, build an environment, run a first job | | [training/cli.md](training/cli.md) | Unified CLI (`prism`) reference: installation, commands, options, examples | +### Tutorials — `tutorials/` + +End-to-end walkthroughs, grouped by application area. Pages live in +`tutorials//`; notebooks live next to their scripts in the top-level +[`applications//`](../applications/) directory. + +| Document | Description | +|----------|-------------| +| [tutorials/README.md](tutorials/README.md) | Every tutorial by application area, and where a new one goes | +| [../applications/bioreason/bioreason_demo.ipynb](../applications/bioreason/bioreason_demo.ipynb) | BioReason notebook: train a DNA + language model through projector alignment, SFT, GRPO, and KEGG evaluation on Aurora | +| [tutorials/material_science/materials_prism_tutorial.md](tutorials/material_science/materials_prism_tutorial.md) | Materials: jointly train on crystal structures and text descriptions to predict a material property | + ### Platforms — `platforms/` Environment build and job submission, one page per machine, plus the diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 0000000..4f27cd8 --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,29 @@ +# Tutorials + +Hands-on walkthroughs of PRISM on a scientific application, grouped by +application area. Each one walks a single configuration from environment and +data through training. + +Tutorial pages live here, in `docs/tutorials//`. Notebooks live in +[`applications//`](../../applications/), next to the scripts they call. + +For reference material on the same applications, such as pipeline designs and +evaluation invocations, see [`docs/applications/`](../applications/). + +| Area | Tutorial | Modalities | Platform | +|---|---|---|---| +| Biology | [BioReason: train a DNA + language model](../../applications/bioreason/bioreason_demo.ipynb) (notebook): projector alignment, SFT, GRPO, and KEGG evaluation, submitted as chained PBS jobs | DNA + text | Aurora | +| Materials science | [Jointly train on material descriptions and crystal structures](material_science/materials_prism_tutorial.md): predict a material property from a CIF crystal graph and a text description | Crystal graph + text | CUDA, XPU, or CPU | + +## Adding a tutorial + +- Put Markdown pages in `docs/tutorials//`, where `` is the + application's directory under `applications/`, or the name that directory + would take if the application has no scripts there yet. +- Put a notebook in `applications//`, next to the scripts it runs, and + link to it from this page. +- Add a row to the table above and to the Tutorials section of + [`docs/index.md`](../index.md). +- Run `make docs` before pushing. It checks relative links in Markdown files + the same way CI does. Links inside notebooks are not checked, so test those + by hand after moving a notebook. diff --git a/docs/materials_prism_tutorial.md b/docs/tutorials/material_science/materials_prism_tutorial.md similarity index 98% rename from docs/materials_prism_tutorial.md rename to docs/tutorials/material_science/materials_prism_tutorial.md index 9d4461e..e41a5eb 100644 --- a/docs/materials_prism_tutorial.md +++ b/docs/tutorials/material_science/materials_prism_tutorial.md @@ -89,7 +89,7 @@ python applications/material_science/stage_materials_text_model.py \ --cache-dir /path/to/shared/huggingface/hub ``` -Then point Hugging Face at that cache when launching training, according to your cluster's setup. The tokenizer and model name passed to `--text-model` must match the staged model. On Polaris, see [the materials guide](applications/materials_multimodal.md) for the PBS launcher and cache environment settings. +Then point Hugging Face at that cache when launching training, according to your cluster's setup. The tokenizer and model name passed to `--text-model` must match the staged model. On Polaris, see [the materials guide](../../applications/materials_multimodal.md) for the PBS launcher and cache environment settings. ## 5. What PRISM does with the two inputs