docs(hpc): add Getting Started on NERSC guide#112
Closed
dkn16 wants to merge 10 commits into
Closed
Conversation
✅ Eval Results
Graders✅ spec_valid (1.00) Full output |
Member
|
Hi @dkn16, in the meantime the docs have been greatly updated. Could you try rebasing on @EiffL What do you think ? |
Member
|
Yes absolutely, I merged the PR from Alex, we now have a nice setup for the doc, you can rebase your edits from main. |
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
lightcone-cli | 08d33b2 | Commit Preview URL Branch Preview URL |
May 07 2026, 10:44 PM |
Reorganized away from the now-removed docs/hpc/ tree and into the new docs/user/ user-guide structure. The page is a focused, site- specific walkthrough: install Claude Code → pick a Python env (with the 40 GB home-quota → \$SCRATCH symlink note) → install lightcone-cli from PyPI or source → init a project → run on compute nodes via salloc + claude. Wired into the User Guide nav as "NERSC (Perlmutter)" right after "Running on a Cluster" (which it complements with site-specific overlays), and cross-linked from cluster.md so NERSC users land here naturally. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The NERSC page was duplicating content already covered by the generic install.md (Python env, lc install, Claude Code, lc setup) and cluster.md (lc build, podman-hpc, salloc + lc run pattern). Refactor into a tight site-specific overlay that links out to those pages and documents only what's actually different on Perlmutter: 1. module load conda (NERSC distributes Python via modules) 2. 40 GB home-quota workaround: env on \$SCRATCH + symlink 3. DVS doesn't honor flock() — Snakemake state must live on \$SCRATCH 4. salloc invocation needs -A <project> -q <qos> 5. podman-hpc just works (no NERSC-specific config beyond cluster.md) Result: 184 lines deleted, 28 added. The page now reads as a companion to install.md and cluster.md rather than a parallel universe of them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This reverts commit b66bb90.
Keep the full step-by-step recipe but bring its commands into line with how the generic pages describe them: - §0: add the missing https:// prefix on the Claude Code curl one-liner (matches install.md §4) - §2: drop the redundant astra-tools from the pip install command — it's a transitive dep, install.md §2 just says "pip install lightcone-cli". Mention uv as the modern alternative. - §2: add the lc setup step (matches install.md §3) so the global config is created. - §2: clarify that source install is a contributor route (most users should stick with PyPI); the ASTRA clone is only needed if you also want to hack on astra-tools itself. - §5: add the missing pre-flight (lc build) step before running on compute nodes, with a link to cluster.md's mechanics. - §5: reconcile the batch-not-supported caveat with cluster.md (which has a working sbatch template). The truth is: agent-driven runs are interactive-only (Claude Code can't run from a non- interactive sbatch), but raw lc run from a sbatch script works fine — that's what cluster.md describes. Document both paths. Net: 62 insertions, 9 deletions. Complete recipe preserved; only divergent details corrected. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
NERSC's canonical entry point is `module load python` (the Python distribution that ships with conda); `module load conda` loads Miniconda directly. Both work — switch the recommended command to `module load python` to match the rest of NERSC's user-facing docs, and keep a one-line note that `module load conda` is equivalent. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per docs.nersc.gov/development/languages/python/nersc-python/: \`module load python\` provides a ready-to-use Python distribution with conda, pip, and many scientific packages pre-installed. Users who just want to install lightcone-cli on top don't need to \`conda create\` first — \`pip install --user lightcone-cli\` works straight against the module. Restructure §1 to lead with the simpler path: - Default: \`module load python\` + \`pip install --user lightcone-cli\` - Fallback (when isolation or a different Python version is needed): conda env on top, which is also NERSC's recommended path when pip-installing custom packages Update §2 to match — two install paths corresponding to the two §1 choices. The dropped "Option B venv inside conda" was redundant once the default no longer requires a conda env. The 40 GB home-quota note remains, plus a pointer to NERSC's recommended \`/global/common/software/<project>/\` for larger envs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tall
Mirror the conventions from the new install.md:
- Rename §0 "Install Claude Code" → "Agentic CLI" (matches install.md
§4's broader framing — Claude Code is the current agent, not the
only one we'll ever support).
- Rename §1 "Pick a Python environment" → just "Python", matching
install.md §1.
- Add a uv "Recommendation" tip admonition in §1, mirroring the
install.md style. uv install one-liner included.
- §2 install commands switched to tabbed \`=== "uv"\` / \`=== "pip"\`
syntax matching install.md, and use the modern command spellings:
- \`uv tool install lightcone-cli\` (not \`uv pip install\`) for the
no-env path — uv tool creates an isolated venv with a ~/.local/bin
wrapper, which is exactly right for a shared NERSC python module
- \`python -m pip install --user lightcone-cli\` (not bare \`pip\`)
for the pip path, matching the new install.md
- \`uv pip install\` / \`python -m pip install\` inside a conda env
The site-specific structure (NERSC module + conda overlay + DVS/scratch
gotcha + interactive/batch SLURM walkthrough) is unchanged — only the
command details and section names migrated to match install.md's
conventions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
NERSC's official documentation (docs.nersc.gov) doesn't mention `uv` at all — their Python guidance covers conda, mamba, pip, and Spack. Recommending `uv` as the default path for NERSC users implies it's part of the supported stack, which it isn't. - Drop the §1 "Recommendation" tip pushing `uv` for NERSC. - §2 leads with `python -m pip install --user lightcone-cli` against the stock `module load python`, which is what NERSC actually documents and supports. - `uv tool install` is mentioned afterward as a cleaner alternative for users who already have uv installed (with the install one-liner inline so it's not a dead reference), but it's not framed as "recommended" for NERSC. - Drop the `=== "uv"` / `=== "pip"` tabbed syntax — install.md doesn't actually use that style; it just runs `pip install` and then offers uv as a follow-on. Match that simpler shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Visual + structural polish on the NERSC guide. No content was added
or removed; existing prose was rephrased for cadence and the
formatting was migrated to the same admonition / tab vocabulary
that index.md and install.md already use.
- Title shortened to "lightcone-cli on NERSC (Perlmutter)" (matches
the nav entry shape).
- Intro: added a quick-orientation `!!! tip` pointing at install.md /
cluster.md so readers know this page is the site-specific overlay.
- §1: converted the two `>` blockquote callouts ("When to create
your own conda env" / "Storage note") into proper `!!! note` and
`!!! warning` admonitions. They were already callouts in spirit.
- §2: renamed subsections to "Path A / B / C" — same ordering, but
the labeling makes the branching obvious. Inlined the conda-env
uv alternative as a comment so it doesn't need its own subsection.
- §4: switched the two example-prompt code blocks to `=== "Start
fresh"` / `=== "Migrate existing code"` tabs (matches the
"Quick start" tabs in user/index.md), and converted the trailing
"you're on a login node" reminder into a `!!! warning` — it's the
most common foot-gun in this section, easy to miss in plain prose.
- §5: same treatment — inline reminders ("Picking a QoS", "When to
use this path") promoted to `!!! note`; the DVS-flock gotcha is
now a `!!! danger`, since silent corruption is the right severity
level; the 12-week purge is a `!!! warning`.
- §7: switched updating section to `=== "PyPI install"` / `===
"Source install"` tabs. Most users only care about one.
- §8: kept config-survives-uninstall as a `!!! note` instead of a
trailing comment line.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The targets/ directory is no longer part of ~/.lightcone — only config.yaml lives there now. The §8 uninstall admonition was suggesting users would want to preserve a path that doesn't exist. (Separately, docs/architecture.md:278 still mentions targets/ alongside the old dagster.yaml — that's a stale Prism-era paragraph and a separate cleanup.) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Member
Author
|
closes, moved into #120 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A walkthrough for Perlmutter users: installing Claude Code, picking a Python environment (with a $SCRATCH-symlink note for the 40 GB home quota), installing lightcone-cli from PyPI or source, scaffolding a project, prompting the agent, and running on compute nodes via salloc + claude.
Put in
docs/hpc/nersc-install.mdfor now. Will move to user documentation later.Wired into the docs nav under HPC & SLURM and linked from the HPC overview's "See also" list.