Caught while following the README as a brand-new user:
layup --help tagline reads "Awesome layup survey simulator suite" — layup is an orbit-fitting package; "survey simulator" is Sorcha. Misleading at the very first command.- README Setup says
git submodule update --init fetches "assist, eigen, and rebound"; the actual submodules are eigen and autodiff (assist/rebound are pip dependencies).
- README Quickstart calls
layup bootstrap "a few hundred MB"; it is actually ~1.5 GB. Update the figure and note the disk requirement.
layup --help lists 10 verbs, but log is missing from the "most common verbs" blurb (and external docs say "11"). Reconcile to 10 and document (or hide) log.- The Use the Python API section points to
docs/notebooks/orbit_fitting_api.ipynb but doesn't mention that Jupyter is required — a base pip install -e . has no jupyter (it is in the [dev] extra), so a new user hits command not found: jupyter. Tell readers to pip install -e ".[dev]".
- Typo:
unpack help says "covarience" -> "covariance". Minor: demo prepare suggests -o demo_orbitfit_output while the Quickstart uses -o my_orbit; make them consistent.
Found during a clean-room, fresh-user install + test run-through (fresh venv + --recursive clone, following the README Quickstart), 2026-07-10.
Caught while following the README as a brand-new user:
layup --helptagline reads "Awesome layup survey simulator suite" — layup is an orbit-fitting package; "survey simulator" is Sorcha. Misleading at the very first command.git submodule update --initfetches "assist, eigen, and rebound"; the actual submodules are eigen and autodiff (assist/rebound are pip dependencies).layup bootstrap"a few hundred MB"; it is actually ~1.5 GB. Update the figure and note the disk requirement.layup --helplists 10 verbs, butlogis missing from the "most common verbs" blurb (and external docs say "11"). Reconcile to 10 and document (or hide)log.docs/notebooks/orbit_fitting_api.ipynbbut doesn't mention that Jupyter is required — a basepip install -e .has nojupyter(it is in the[dev]extra), so a new user hitscommand not found: jupyter. Tell readers topip install -e ".[dev]".unpackhelp says "covarience" -> "covariance". Minor:demo preparesuggests-o demo_orbitfit_outputwhile the Quickstart uses-o my_orbit; make them consistent.Found during a clean-room, fresh-user install + test run-through (fresh venv +
--recursiveclone, following the README Quickstart), 2026-07-10.