release 0.12.6: correctness fixes from a full review, and a website theory page

Engine: unbuildable cells are no longer counted as green periphery, isolated
centres are tracked correctly, and green access, green corridors and corridor
spans treat unbuildable land as a barrier, matching centre access; a new build
must itself keep green access; parameter validation hardened; centre seeds on
unbuildable land are rejected. A golden test asserts the incremental green
arrays equal a fresh rebuild on the final state.

Plugin: input layers are snapshotted on the main thread before the background
run; the engine install runs as a background task; stranded centre seeds snap
to the nearest buildable cell; the confirm button is labelled Run; re-fetching
OSM data first releases layers loaded from the previous GeoPackage; grid edge
rounding, locale-free load, leap-day temporal setup, GDAL open options and
transform checks fixed; dead code removed.

Packaging and docs: the plugin zip now carries the LICENSE file; metadata
credits D'Acci and Voto and points at the correct homepage; the recommended-
plan notes describe the shipped pipeline; the website gains a theory page
comparing the published model rule by rule, an extended Departures section,
Copernicus and ODbL attribution, per-page titles, and regenerated figures.

Author: songololo

.github/workflows/ci.yml

@@ -140,6 +140,8 @@ jobs:
       - name: Build plugin zip
         run: |
           mkdir -p dist
+          # the plugin repository requires a licence file inside the zip
+          cp LICENSE isobenefit_qgis/LICENSE
           zip -r dist/isobenefit_qgis.zip isobenefit_qgis \
             -x '*/__pycache__/*' '*.pyc'
       - uses: actions/upload-artifact@v4

README.md

@@ -37,7 +37,7 @@ If the automatic install is blocked (e.g. a locked-down environment), the dialog
 shows the exact command to run yourself, which is simply:
 
 ```bash
-<qgis-python> -m pip install "isobenefit>=0.12,<0.13"
+<qgis-python> -m pip install "isobenefit>=0.12.6,<0.13"
 ```
 
 ## Usage

core/Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "isobenefit"
-version = "0.12.5"
+version = "0.12.6"
 edition = "2021"
 license = "AGPL-3.0-or-later"
 description = "Rust simulation core for the Isobenefit Urbanism QGIS plugin"

core/Cargo.toml

@@ -186,9 +186,11 @@ pub fn agg_dijkstra_dist(
 
 /// Builds the green-periphery (`green_itx`) and green-access (`green_acc`) arrays.
 ///
-/// `green_itx`: built/centre cells -> 1; their rook-adjacent green cells -> 2
-/// (the developable periphery). `green_acc`: for every periphery (==2) cell, the
-/// accessibility footprint summed together — computed in parallel.
+/// `green_itx`: unbuildable cells -> -1; built/centre cells -> 1; green cells
+/// rook-adjacent to built -> 2 (the developable periphery). `green_acc`: for every
+/// periphery (==2) cell, the accessibility footprint summed together — computed in
+/// parallel. Footprints traverse `[0, 1, 2]` only, so unbuildable cells (water,
+/// carved corridors) block green access exactly as they block centre access.
 pub fn prepare_green_arrs(
     state: &Array2<i16>,
     max_distance_m: f64,
@@ -198,7 +200,9 @@ pub fn prepare_green_arrs(
     let mut green_itx = Array2::<i16>::zeros((rows, cols));
     for y in 0..rows {
         for x in 0..cols {
-            if state[[y, x]] > 0 {
+            if state[[y, x]] < 0 {
+                green_itx[[y, x]] = -1;
+            } else if state[[y, x]] > 0 {
                 green_itx[[y, x]] = 1;
                 for (ny, nx) in iter_nbs(rows, cols, y, x, true) {
                     if state[[ny, nx]] == 0 {
@@ -285,6 +289,25 @@ mod tests {
         assert!(dist[[0, 4]].is_infinite());
     }
 
+    #[test]
+    fn unbuildable_blocks_green_access() {
+        // built column at x=0, unbuildable column at x=2: periphery footprints
+        // from x=1 must not cross the barrier to reach x>=3
+        let mut state = Array2::<i16>::zeros((5, 5));
+        for y in 0..5 {
+            state[[y, 0]] = 1;
+            state[[y, 2]] = -1;
+        }
+        let (itx, acc) = prepare_green_arrs(&state, 300.0, 100.0);
+        for y in 0..5 {
+            assert_eq!(itx[[y, 2]], -1);
+            assert_eq!(itx[[y, 1]], 2);
+            assert_eq!(acc[[y, 3]], 0);
+            assert_eq!(acc[[y, 4]], 0);
+            assert!(acc[[y, 1]] > 0);
+        }
+    }
+
     #[test]
     fn prepare_green_arrs_marks_periphery() {
         // a single built cell in a green field -> its rook neighbours become itx==2

core/src/access.rs

@@ -81,16 +81,18 @@ pub fn count_cont_nbs(state: &Array2<i16>, y: usize, x: usize, targets: &[i16])
     (total, longest, adds.len() as i64)
 }
 
-/// Length of the run of non-built (`<= 0`) cells from `start` along a 1-D line,
-/// in the positive or negative direction, stopping at the first built (`> 0`) cell
-/// or the array edge.
+/// Length of the run of green (`== 0`) cells from `start` along a 1-D line, in
+/// the positive or negative direction, stopping at the first non-green cell
+/// (built `> 0` or unbuildable `< 0`) or the array edge. Unbuildable land is not
+/// usable green, so water or a carved corridor terminates a span rather than
+/// extending it.
 pub fn green_span(line: ArrayView1<i16>, start: usize, positive: bool) -> i64 {
     let n = line.len();
     let mut span: i64 = 0;
     if positive {
         let mut i = start + 1;
         while i < n {
-            if line[i] > 0 {
+            if line[i] != 0 {
                 break;
             }
             span += 1;
@@ -102,7 +104,7 @@ pub fn green_span(line: ArrayView1<i16>, start: usize, positive: bool) -> i64 {
         }
         let mut i = start as i64 - 1;
         while i >= 0 {
-            if line[i as usize] > 0 {
+            if line[i as usize] != 0 {
                 break;
             }
             span += 1;
@@ -208,6 +210,14 @@ mod tests {
         assert_eq!(green_span(line.view(), 4, false), 0);
     }
 
+    #[test]
+    fn green_span_stops_at_unbuildable() {
+        // water/carved corridors terminate a green span; they do not extend it
+        let line = array![0i16, 0, -1, 0, 0];
+        assert_eq!(green_span(line.view(), 0, true), 1);
+        assert_eq!(green_span(line.view(), 4, false), 1);
+    }
+
     #[test]
     fn green_spans_blocks_short_corridor() {
         // a single green cell flanked by built on the row -> span 0 both sides on x,

core/src/neighbours.rs

@@ -32,6 +32,7 @@ impl PySimulation {
         total_iters, random_seed,
     ))]
     fn new(
+        py: Python<'_>,
         state: PyReadonlyArray2<i16>,
         origin: PyReadonlyArray2<i16>,
         density: PyReadonlyArray2<f32>,
@@ -62,22 +63,30 @@ impl PySimulation {
             density_factors_km2,
         )
         .map_err(PyValueError::new_err)?;
-        let inner = Simulation::new(
-            state.as_array().to_owned(),
-            origin.as_array().to_owned(),
-            density.as_array().to_owned(),
-            &centre_seeds,
-            params,
-            total_iters,
-            random_seed,
-        )
-        .map_err(PyValueError::new_err)?;
+        let state = state.as_array().to_owned();
+        let origin = origin.as_array().to_owned();
+        let density = density.as_array().to_owned();
+        // the constructor's green-access build is the heaviest single call; run it
+        // (and its rayon fan-out) without holding the GIL
+        let inner = py
+            .allow_threads(|| {
+                Simulation::new(
+                    state,
+                    origin,
+                    density,
+                    &centre_seeds,
+                    params,
+                    total_iters,
+                    random_seed,
+                )
+            })
+            .map_err(PyValueError::new_err)?;
         Ok(Self { inner })
     }
 
     /// Run one iteration.
-    fn step(&mut self) {
-        self.inner.step();
+    fn step(&mut self, py: Python<'_>) {
+        py.allow_threads(|| self.inner.step());
     }
 
     /// Run to completion (or until the population target is reached).