Merge pull request #155 from benchmark-urbanism/dev

## Summary

- Adaptive per-distance sampling for centrality (experimental): `sample=True` with Hoeffding-bound calibrated probabilities per distance threshold
- Convenience wrappers: `closeness_shortest`, `closeness_simplest`, `betweenness_shortest`, `betweenness_simplest`
- OD-matrix betweenness: `build_od_matrix`, `betweenness_od`
- QGIS plugin for network centrality analysis with custom parameter dialog
- Graph mutation: `set_node_live`, `remove_street_node`, `remove_street_edge`
- Brandes multi-predecessor betweenness with configurable tolerance
- New plugin page, sampling guide, and visibility module docs
- Regenerated API docs reflecting all signature changes
- Updated Python version range to 3.10-3.13
- Remove paper build artifacts from tracking

## Breaking changes

- Rename `jitter_scale` parameter to `tolerance` in `node_centrality_shortest`, `node_centrality_simplest`, and `segment_centrality`
- Rename Rust methods: `local_node_centrality_shortest` → `centrality_shortest`, `local_node_centrality_simplest` → `centrality_simplest`, `local_segment_centrality` → `segment_centrality`

## Acknowledgements

Thanks to Robin Lovelace (@Robinlovelace) for initiating the adaptive sampling idea and for contributing to its development.

Author: songololo

.claude/settings.json

@@ -0,0 +1,22 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(export PATH=\"$HOME/.cargo/bin:$HOME/.local/bin:$PATH\")",
+      "Bash(/Users/gareth/.local/bin/uv run maturin develop:*)",
+      "Bash(export PATH=\"$HOME/.cargo/bin:/usr/bin:/bin:/usr/local/bin:$PATH\")",
+      "Bash(maturin develop:*)",
+      "Bash(source:*)",
+      "Bash(HOME=/Users/gareth)",
+      "Bash(export:*)",
+      "Bash(. \"$HOME/.cargo/env\")",
+      "Bash(echo:*)",
+      "Read(//Users/gareth/.cargo/**)",
+      "Bash(. /Users/gareth/.cargo/env)",
+      "Bash(grep:*)",
+      "Bash(.venv/bin/pytest tests/ --ignore=tests/metrics/test_visibility.py -x)",
+      "Bash(.venv/bin/pytest tests/rustalgos/test_centrality.py tests/metrics/test_networks.py -x -v)",
+      "Bash(.venv/bin/pytest tests/ --ignore=tests/metrics/test_visibility.py --ignore=tests/tools/test_io.py -x)",
+      "Bash(.venv/bin/pytest:*)"
+    ]
+  }
+}

.github/workflows/build_qgis_plugin.yml

@@ -0,0 +1,62 @@
+name: build qgis plugin zip
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: write
+
+jobs:
+  build-qgis-plugin:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build QGIS plugin zip
+        run: python qgis_plugin/build_plugin.py
+
+      - name: Verify plugin zip contents
+        run: |
+          python - <<'PY'
+          import zipfile
+          from pathlib import Path
+
+          zips = sorted(Path("qgis_plugin").glob("cityseer-qgis-*.zip"))
+          if not zips:
+              raise SystemExit("No QGIS plugin zip was generated.")
+          zip_path = zips[-1]
+          required = {
+              "cityseer_qgis/__init__.py",
+              "cityseer_qgis/provider.py",
+              "cityseer_qgis/metadata.txt",
+              "cityseer_qgis/LICENSE",
+          }
+          with zipfile.ZipFile(zip_path) as zf:
+              names = set(zf.namelist())
+          missing = sorted(required - names)
+          if missing:
+              raise SystemExit(f"Missing files in {zip_path.name}: {missing}")
+          print(f"Verified {zip_path.name}")
+          PY
+
+      - name: Upload QGIS plugin zip artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: qgis-plugin-zip
+          path: qgis_plugin/cityseer-qgis-*.zip
+          if-no-files-found: error
+
+      - name: Attach zip to GitHub release (tags)
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: qgis_plugin/cityseer-qgis-*.zip

.github/workflows/generate_changelog.yml

@@ -0,0 +1,47 @@
+name: Generate Changelog
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to generate changelog for (leave empty for latest)"
+        required: false
+        type: string
+permissions:
+  contents: write
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Determine tag
+        id: tag
+        run: |
+          if [ -n "${{ github.event.inputs.tag }}" ]; then
+            echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT
+          else
+            echo "tag=${{ github.ref_name }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Generate changelog
+        uses: orhun/git-cliff-action@v4
+        id: cliff
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+        env:
+          OUTPUT: CHANGES.md
+
+      - name: Create or update GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.tag }}
+          body_path: CHANGES.md
+          draft: false
+          prerelease: ${{ contains(steps.tag.outputs.tag, 'a') || contains(steps.tag.outputs.tag, 'b') }}

.github/workflows/publish_package.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.github/workflows/publish_package_dev.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: Checkout code
         uses: actions/checkout@v4

.gitignore

@@ -1,11 +1,12 @@
 # mac
 .DS_Store
+CLAUDE.md
 
 # astro
 .astro
 
-# cache
-*cache*
+# cache directories (trailing slash = directories only)
+*cache*/
 
 # code profiling
 .prof
@@ -123,3 +124,24 @@ bin/
 include/
 man/
 
+# QGIS plugin build artifacts
+qgis_plugin/*.zip
+
+# LaTeX generated files
+*.aux
+*.bbl
+*.blg
+*.fdb_latexmk
+*.fls
+*.lof
+*.lot
+*.out
+*.toc
+*.synctex.gz
+missfont.log
+
+# Paper build artifacts (auto-generated by analysis scripts)
+analysis/sampling/paper/main.pdf
+analysis/sampling/paper/figures/
+analysis/sampling/paper/tables/
+

.vscode/settings.json

@@ -31,13 +31,62 @@
     "editor.defaultFormatter": "rust-lang.rust-analyzer",
     "editor.formatOnSave": true
   },
-  "python.testing.pytestArgs": [
-    "tests"
-  ],
+  "python.testing.pytestArgs": ["tests"],
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": true,
   "files.readonlyInclude": {
     "**/.cargo/registry/src/**/*.rs": true,
-    "**/lib/rustlib/src/rust/library/**/*.rs": true,
+    "**/lib/rustlib/src/rust/library/**/*.rs": true
+  },
+  "latex-workshop.latex.tools": [
+    {
+      "name": "pdflatex",
+      "command": "/Library/TeX/texbin/pdflatex",
+      "args": [
+        "-synctex=1",
+        "-interaction=nonstopmode",
+        "-file-line-error",
+        "%DOC%"
+      ]
+    },
+    {
+      "name": "latexmk",
+      "command": "/Library/TeX/texbin/latexmk",
+      "args": [
+        "-pdf",
+        "-synctex=1",
+        "-interaction=nonstopmode",
+        "-file-line-error",
+        "%DOC%"
+      ],
+      "env": {
+        "PATH": "/Library/TeX/texbin:/usr/local/bin:/usr/bin:/bin"
+      }
+    },
+    {
+      "name": "bibtex",
+      "command": "/Library/TeX/texbin/bibtex",
+      "args": ["%DOCFILE%"]
+    }
+  ],
+  "latex-workshop.latex.recipes": [
+    {
+      "name": "latexmk",
+      "tools": ["latexmk"]
+    },
+    {
+      "name": "pdflatex -> bibtex -> pdflatex * 2",
+      "tools": ["pdflatex", "bibtex", "pdflatex", "pdflatex"]
+    }
+  ],
+  "latex-workshop.latex.autoBuild.run": "onSave",
+  "latex-workshop.latex.autoClean.run": "never",
+  "latex-workshop.latex.clean.subfolder.enabled": true,
+  "latex-workshop.view.pdf.viewer": "tab",
+  "latex-workshop.synctex.afterBuild.enabled": true,
+  "latex-workshop.formatting.latex": "tex-fmt",
+  "files.watcherExclude": {
+    "**/temp/**": true,
+    "**/.cache/**": true
   }
 }