Skip to content

docs: README, London example, corrected Queensland figure, performance tables - #64

Merged
petercorke merged 6 commits into
mainfrom
docs/readme-london-benchmark
Oct 13, 2026
Merged

petercorke merged 6 commits into
mainfrom
docs/readme-london-benchmark

Conversation

@petercorke

Copy link
Copy Markdown
Owner

A review and extension of the README.

Corrections

  • The Queensland figure was wrong. roads.png was drawn from places.json, whose coordinates are in metres while the road distances are in km, so the A* heuristic was about 1,000 times too large and the route it found, 1,759 km via Rockhampton, was not the shortest. queensland.json (the same routes and distances, coordinates in km) gives 1,659 km via Roma, which is what the notebook and the snippet compute. The figure is regenerated from the snippet, axes in km.
  • The snippet now reads the same data file as the notebook it links to.
  • g.component(v) was documented as "the component that vertex v belongs to"; it takes a component number. v.label is the component of a vertex.
  • intro.rst: "pgaph-python" in the history paragraph.

Added

  • An Installation section (pip install pgraph-python, Python 3.9 or later).
  • A bigger example: routing through central London (the figure, the two routes and why they differ, a link to the notebook, the OpenStreetMap attribution).
  • The method lists now include path_UCS, closest, near, within, subgraph, coordinates, build_kdtree, metric/SE2Metric, copy, export and validate; vertex_class and edge_class in the subclassing section; a runnable subclassing snippet.
  • Performance: tables of the key operations for undirected and directed graphs at 100, 1,000 and 10,000 vertices, with the growth exponent, measured with examples/benchmark.py on current main.
  • An outline: ## Installation, ## Examples, ## Using pgraph, ## Performance, ## History.
  • Descriptive alternative text for the figures.

Docs only, apart from the regenerated PNG and the new docs/figs/london_route.png.

🤖 Generated with Claude Code

petercorke and others added 6 commits October 13, 2026 10:24
A subsection after the Queensland example with the map of the road network
and the routes there and back between Buckingham Palace and Tower Bridge,
drawn by the london notebook, and a link to it.  The figure is in docs/figs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Installation; the Queensland example reads the same data file as the notebook
it links to and gives the same path; component(c) takes a component number,
and v.label is the component of a vertex; path_UCS, the geometry methods,
metric, copy, export and validate are listed; vertex_class and edge_class in
the subclassing section; headings that make an outline; the two benchmark
tables, with the description of the runs in one paragraph above them.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e figures

The figure was drawn from places.json, whose coordinates are in metres while
the road distances are in km, so the A* heuristic was far too large and the
route it found, 1,759 km via Rockhampton, was not the shortest.  The notebook
and the snippet use queensland.json, in km: 1,659 km via Roma.  The figure is
drawn from that, with the axes in km.

The README figures have a description as their alternative text.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Measured on main with the faster planners, the components union-find, and the
vertex constructor that does not pay for the coordinate hook: a vertex is
1.5 us, the components after a change are 3.9 ms (undirected) and 5.9 ms
(directed) at 10,000 vertices.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@codacy-production

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

@codecov

codecov Bot commented Oct 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.26%. Comparing base (cdbc54a) to head (d555170).

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #64   +/-   ##
=======================================
  Coverage   97.26%   97.26%           
=======================================
  Files           3        3           
  Lines        1570     1570           
=======================================
  Hits         1527     1527           
  Misses         43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@petercorke
petercorke merged commit 6103438 into main Oct 13, 2026
14 checks passed
@petercorke
petercorke deleted the docs/readme-london-benchmark branch October 13, 2026 00:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant