Link to documenation in README

[krystophny]

• Diss Patrick
• Presentation Rigorosum

Patrick agrees to re-use text with CC BY

[krystophny]

Automated triage pass (Claude), grounded in the repository at fd2c56b. Verify before acting.

Still open and still needed: at fd2c56b the README.md contains no link to any physics or method documentation, and no citation metadata exists anywhere in the tree (rg -in 'lainer|dissertation|thesis|rigorosum|doi|arxiv' over the working tree returns only incidental hits — an include guard in src/magnetic_differential_equation.h:5, @author: lainer_p headers in scripts/outdated_plots/, and one dangling code comment discussed below). Refining into an implementable spec.

Purpose

MEPHIT solves a hybrid kinetic/MHD model for the linear plasma response to RMPs, and the only complete written derivation of that model is Patrick Lainer's dissertation. Right now a new user reading README.md learns how to build and run the code but has no route to the equations behind currn_model, the FLR2 response, the resonant-layer treatment, or the Fourier–FEM decoupling. Worse, the code already assumes the thesis exists as a reference without ever citing it: src/mephit_mesh.F90:1850 reads

    ! note discrepancy with thesis, where we have (2 L - 1) fine separations,
    ! while here we have (2 * add_fine + 1) * fine_sep due to refine_unit_partition

"the thesis" is unresolvable for anyone who is not in the group. Patrick has agreed to CC BY reuse, so the text can be linked, quoted and adapted — but that grant needs to be recorded in the repository, because LICENSE is MIT (Copyright (c) 2024 Plasma Physics at ITPcp, TU Graz) and readers will otherwise assume MIT covers the prose too.

Current state

• README.md (8.3 kB, last substantive change 3a5e93e) has sections: Installation, Initial build, Coil geometry, Setting up working directories, Running simulations, Plotting results, Call graphs. There is no Documentation, Physics, References or Citation section, and no author/attribution block.
• The only documentation pointer in the README is the Doxygen call-graph paragraph, which explicitly disclaims itself: "While the Doxygen documentation of the source code is horribly out of date, the EXTRACT_ALL = YES option of Doxygen is useful for generating call graphs."
• No CITATION.cff, no doc/, no docs/ — ls at the repo root shows only cmake data setup scripts src test plus CMakeLists.txt CMakePresets.json Makefile LICENSE README.md pyproject.toml requirements.txt doxygen.conf .gitignore. Sibling repos in the org already carry the artefacts this issue wants: GLISS/CITATION.cff, rabe/CITATION.cff, vmecpp/CITATION.cff, and SIMPLE/DOC, NEO-2/DOC, libneo/doc, NEO-RT/doc. MEPHIT is the outlier.
• Two link defects to fix in the same PR, since this issue is about README link hygiene:
  • README.md, "Setting up working directories": [`data/mephit_g33353_2900_EQH.in`](data/mephit_g33353_2900.in) — the link target data/mephit_g33353_2900.in does not exist; ls data/ gives mephit_g33353_2900_EQH.in, mephit_g000001.0001_TCFP_hip.in, mephit_illustration.in. Link text and target disagree.
  • The same section links the field-line-integration config to [field line integration](src/preload_for_SYNCH.f90). That file exists but is not compiled — its basename does not appear in CMakeLists.txt. Either annotate it as reference-only or point at the live path, src/field_line_integration_for_SYNCH.f90.

Reproduction / evidence

This is a documentation task, so the recipe is a verification recipe, not a bug repro. From a clean checkout:

git -C MEPHIT grep -niE 'lainer|dissertation|thesis|rigorosum|doi|citation' -- README.md
# expected today: no output  -> confirms the gap
ls MEPHIT/CITATION.cff
# expected today: No such file or directory
# every relative link in the README must resolve:
grep -oP '\]\(\K[^)#:]+(?=\))' MEPHIT/README.md | grep -v '^http' | while read -r f; do
  [ -e "MEPHIT/$f" ] || echo "BROKEN: $f"
done
# expected today: BROKEN: data/mephit_g33353_2900.in

The primary source to link is confirmed public: TUGRAZonline thesis record 90496 — Lainer, Patrick, Hybride Modellierung der Plasma-Antwort auf dreidimensionale magnetische Störungen in Tokamaks mit kinetischer Theorie und MHD (full text in English), 128 pp., 2025, Institut für Theoretische Physik – Computational Physics, examiners M. Heyn and S. Murakami, with a "Volltext (Repository)" download link:
https://online.tugraz.at/tug_online/wbAbs.showThesis?pThesisNr=90496&pOrgNr=37&pPersNr=216

The Rigorosum presentation has no public URL yet. That is the one blocking unknown in this issue: it must be deposited somewhere citable (Zenodo under CC BY, giving a DOI) or committed to doc/ before it can be linked. Do not link a Nextcloud//proj/plasma path — the README already suffers from ITPcp-only paths and those are useless to external readers.

Behaviour (BDD)

Scenario: README points a new user at the physics
  Given a clean checkout of MEPHIT at main
  When I open README.md
  Then a top-level section "## Documentation" appears before "## Installation"
  And it contains the string "online.tugraz.at/tug_online/wbAbs.showThesis?pThesisNr=90496"
  And it names the dissertation author "Patrick Lainer" and the year 2025
  And it states that the reused text is licensed CC BY 4.0, distinct from the MIT LICENSE of the code

Scenario: every relative link in the README resolves
  Given a clean checkout of MEPHIT at main
  When I extract each markdown target not starting with "http" from README.md
  Then every extracted path exists in the working tree
  And in particular the config example links to data/mephit_g33353_2900_EQH.in, not data/mephit_g33353_2900.in

Scenario: citation metadata is machine-readable
  Given CITATION.cff at the repository root
  When I run "cffconvert --validate -i CITATION.cff"
  Then it exits 0
  And the file lists Christopher G. Albert and Patrick Lainer as authors
  And "preferred-citation" is the 2025 dissertation with its TUGRAZonline URL

Scenario: the dangling in-code thesis reference becomes resolvable
  Given src/mephit_mesh.F90 at line ~1850
  When I read the comment above the call to refine_resonant_surfaces
  Then "thesis" is qualified as "Lainer 2025" with a section or equation number
  And doc/README.md maps that reference to the corresponding thesis section

Implementation plan

1. doc/ (new directory), doc/README.md (new file). One page: "Physics and numerics documentation for MEPHIT". Contents: (a) bibliographic entry for the dissertation with the TUGRAZonline URL above; (b) the Rigorosum presentation entry (see step 2); (c) a short mapping table from thesis chapter → source file, at minimum: iteration scheme → src/mephit_iter.F90 (mephit_run at :109, perteq_iterate at :506); preconditioner/Arnoldi → precond_compute at src/mephit_iter.F90:388 and arnoldi_break in src/mephit_util.f90; MDE finite differences → FDM_t/FDM_compute_matrix/FDM_solve at src/mephit_iter.F90:42, 817, 898; FLR2 kinetic response → src/mephit_flr2.f90 and src/hyper1F1.c; mesh refinement at resonant surfaces → refine_resonant_surfaces in src/mephit_mesh.F90; RT0/L1 elements → src/mephit_pert.f90; Fourier–FEM magnetostatics → scripts/maxwell_daemon.edp. (d) An explicit attribution paragraph: "Text and figures in this directory are adapted from Lainer (2025) and are licensed CC BY 4.0 by permission of the author."
2. Deposit the Rigorosum slides. Preferred: upload the PDF to Zenodo under CC BY 4.0 in the ITPcp community, then use the resulting DOI. Fallback if that is not wanted: commit doc/rigorosum_lainer_2025.pdf (check size first; if > ~5 MB prefer Zenodo) and link it relatively. Either way record the choice in doc/README.md.
3. doc/LICENSE-CC-BY-4.0.txt (new file). Verbatim CC BY 4.0 legal code or the canonical https://creativecommons.org/licenses/by/4.0/ deed link plus a one-paragraph statement of the grant Patrick gave. This is what stops MIT from being assumed over the prose.
4. README.md — add ## Documentation immediately after the # MEPHIT title, before ## Installation. Three to six lines: one sentence naming the physics model (linear hybrid kinetic/MHD plasma response to RMPs of a single toroidal mode n), the dissertation link, the presentation link, a pointer to doc/, and a sentence on the CC BY/MIT split.
5. README.md — add ## Citation near the end, after "Call graphs": "If you use MEPHIT in published work, cite …" plus a fenced BibTeX @phdthesis entry for Lainer 2025, and a pointer to CITATION.cff.
6. README.md — fix the two link defects listed under Current state: retarget the config example to data/mephit_g33353_2900_EQH.in, and either retarget the field-line-integration link to src/field_line_integration_for_SYNCH.f90 or mark src/preload_for_SYNCH.f90 as not built.
7. CITATION.cff (new file at repo root). Model it on GLISS/CITATION.cff (cff-version: 1.2.0, type: software, authors, repository-code, license: MIT, keywords), adding a preferred-citation: block of type: thesis for Lainer 2025. Keywords: tokamak, resonant magnetic perturbations, plasma response, MHD, kinetic theory, finite element.
8. src/mephit_mesh.F90:1850 — change note discrepancy with thesis to note discrepancy with Lainer (2025), Sec. <n> once the section number is looked up. One-line comment edit, no behaviour change.
9. .github/workflows/main.yml — optional link check. The workflow currently has a single code job (checkout → setup/debian.sh → make) and is build-only. Adding a cheap docs job that runs a markdown link checker (e.g. lycheeverse/lychee-action restricted to relative links, or the five-line grep/[ -e ] loop from Reproduction) makes scenario 2 enforced rather than aspirational. Keep it a separate job so it cannot block the build gate. Note this touches the same file as issue Test target exits successfully without running tests #35 (test target exits successfully without running tests) — coordinate ordering if both are in flight.

No sibling-repo changes are required; libneo is untouched by this.

Acceptance criteria

• git grep -c 'pThesisNr=90496' README.md returns ≥ 1.
• README.md contains a ## Documentation section before ## Installation and a ## Citation section.
• The relative-link loop in Reproduction / evidence prints nothing (currently prints BROKEN: data/mephit_g33353_2900.in).
• CITATION.cff exists at the repo root and cffconvert --validate -i CITATION.cff exits 0.
• doc/README.md exists and its source-file mapping table cites paths that all exist (while read p; do [ -e "$p" ] || echo MISSING "$p"; done over the table's paths prints nothing).
• doc/LICENSE-CC-BY-4.0.txt exists and README.md states which files it covers.
• The Rigorosum presentation is reachable from the README by a URL or repo-relative path that resolves without ITPcp network access.
• make still succeeds on ubuntu-24.04 per .github/workflows/main.yml; no source file other than the one comment in src/mephit_mesh.F90 is modified.

References

• P. Lainer, Hybrid modelling of the plasma response to three-dimensional magnetic perturbations in tokamaks with kinetic theory and MHD, PhD thesis, TU Graz, 2025 (TUGRAZonline thesis no. 90496; German metadata title, English full text). The primary artefact this issue is about.
• M. F. Heyn, I. B. Ivanov, S. V. Kasilov, W. Kernbichler et al., Quasilinear modelling of RMP interaction with a tokamak plasma: application to ASDEX Upgrade ELM mitigation experiments, Nucl. Fusion 54, 064005 (2014) — the kinetic resonant-layer response lineage that src/mephit_flr2.f90 implements; should appear in doc/README.md alongside the thesis.
• J.-K. Park and N. C. Logan, Self-consistent perturbed equilibrium with neoclassical toroidal torque in tokamaks, Phys. Plasmas 24, 032505 (2017) — GPEC, the code MEPHIT is benchmarked against (read_Bnvac_GPEC at src/mephit_pert.f90:980, compute_gpec_jacfac at src/mephit_mesh.F90:2378); GPEC's own documentation site is the model for what "linked documentation" should look like.
• Citation File Format 1.2.0, https://citation-file-format.github.io/ — the schema for step 7; already in use in this org (GLISS/CITATION.cff, vmecpp/CITATION.cff, rabe/CITATION.cff).
• For the in-repo-documentation pattern, compare sibling ITPcp codes: SIMPLE/DOC, NEO-2/DOC, libneo/doc, NEO-RT/doc.

Scope and risk

Single small PR, documentation-only apart from one comment line in src/mephit_mesh.F90. Nothing can break at build or run time. The one real blocker is external to the code: the Rigorosum presentation needs a durable public location (Zenodo DOI preferred) before step 2 can be closed — if that stalls, land steps 1, 3–8 and leave a single unchecked box rather than blocking the whole PR. If the optional CI link check in step 9 is judged out of scope, split it into its own issue and link it to #35.