From eea33c22929c08dffd72f3a08b56a32c3a8ac4a2 Mon Sep 17 00:00:00 2001 From: Dominik Strebel Date: Tue, 10 Nov 2026 16:00:54 +0100 Subject: [PATCH 1/5] fix(analysis): a deep learning model trained within the work limit says what it left out MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Found in #1727's review (github-actions): in a run that can't be cancelled (a script, the assistant, the command line, a task), training fits a random subset of the sampled pixels, or fewer epochs, to stay within its work limit, and nothing said so (AGENTS.md › Never silent). - `neural::Trained` keeps the samples fitted of those kept for training and the epochs asked; `Trained::limited` words what was left out. - `dl.train` and `dl.classify` (when it trains) warn with the model's name and give it as `"limited"` in their answer, with where the work isn't capped. --- crates/analysis/src/neural.rs | 39 +++++++++++++++++++++++++-- crates/engine/src/cmd/deeplearning.rs | 20 +++++++++++++- docs/user-guide/analysis.md | 4 +-- 3 files changed, 58 insertions(+), 5 deletions(-) diff --git a/crates/analysis/src/neural.rs b/crates/analysis/src/neural.rs index 1e3b26d265..b780f930c8 100644 --- a/crates/analysis/src/neural.rs +++ b/crates/analysis/src/neural.rs @@ -221,6 +221,31 @@ pub struct Trained { /// The epochs run (fewer than asked when the work would pass [`MAX_WORK`] in a run that can't /// be cancelled). pub epochs: usize, + /// The epochs asked (within 1 to [`MAX_EPOCHS`]). + pub epochs_asked: usize, + /// The training samples fitted each epoch (fewer than [`Trained::training`] when they would + /// pass [`MAX_WORK`] in a run that can't be cancelled: a random subset). + pub fitted: usize, + /// The samples kept for training (the rest are held back to measure the accuracy). + pub training: usize, +} + +impl Trained { + /// What a run that can't be cancelled left out to stay within its work limit, to be said: `None` + /// when it fitted every training sample for every epoch asked. + pub fn limited(&self) -> Option { + if self.fitted >= self.training && self.epochs >= self.epochs_asked { + return None; + } + Some(format!( + "trained on {} of {} training samples for {} of {} epochs, the work limit of a run that can't be cancelled{}", + self.fitted, + self.training, + self.epochs, + self.epochs_asked, + crate::parallel::UNCAPPED_HINT + )) + } } /// Trains a classifier. `samples` are (band values, class index); `hidden` the units per hidden @@ -292,9 +317,11 @@ pub fn train( let per_sample = 3.0 * layers.iter().map(|l| l.w.len() + l.b.len()).sum::() as f64; let max_work = if crate::control::uncapped() { f64::INFINITY } else { MAX_WORK }; let mut fit = fit; + let training = fit.len(); fit.truncate(((max_work / per_sample).min(usize::MAX as f64) as usize).max(1)); let per_epoch = per_sample * fit.len().max(1) as f64; - let epochs = epochs.clamp(1, MAX_EPOCHS).min(((max_work / per_epoch).min(usize::MAX as f64) as usize).max(1)); + let epochs_asked = epochs.clamp(1, MAX_EPOCHS); + let epochs = epochs_asked.min(((max_work / per_epoch).min(usize::MAX as f64) as usize).max(1)); let (lr, momentum, batch) = (0.05f32, 0.9f32, 32usize); let mut vel: Vec<(Vec, Vec)> = layers.iter().map(|l| (vec![0.0; l.w.len()], vec![0.0; l.b.len()])).collect(); crate::control::begin(epochs); @@ -383,7 +410,7 @@ pub fn train( let model = Mlp { bands: bands.to_vec(), mean, std, layers, classes }; let correct = test.iter().filter(|&&i| samples.get(i).is_some_and(|(x, c)| model.predict(x).0 == *c)).count(); let accuracy = if test.is_empty() { 1.0 } else { correct as f64 / test.len() as f64 }; - Ok(Trained { model, accuracy, samples: samples.len(), epochs }) + Ok(Trained { model, accuracy, samples: samples.len(), epochs, epochs_asked, fitted: fit.len(), training }) } /// Classifies every pixel: class numbers (1-based, `nodata` where a band has no data) and each @@ -534,6 +561,14 @@ mod tests { // The largest network for every epoch would pass the work cap: fewer epochs run. let big = train(&[0, 1], vec!["out".into(), "in".into()], &samples, &[MAX_UNITS; MAX_LAYERS], MAX_EPOCHS).unwrap(); assert!(big.epochs < MAX_EPOCHS, "{} epochs", big.epochs); + // ...and it says so, with what it ran of what was asked. + let said = big.limited().expect("a capped run says what it left out"); + assert!(said.contains(&format!("for {} of {MAX_EPOCHS} epochs", big.epochs)), "{said}"); + assert_eq!(t.limited(), None, "a run within the limit says nothing"); + // Run so it can be cancelled, it fits every sample for every epoch and says nothing. + let control = crate::control::Control::stoppable(); + let whole = crate::run_under("Train", &control, || train(&[0, 1], vec!["out".into(), "in".into()], &samples, &[8], 3)).unwrap(); + assert_eq!((whole.fitted, whole.epochs, whole.limited()), (whole.training, 3, None)); assert!(train(&[0, 1], vec!["a".into(), "b".into()], &samples[..2], &[4], 1).is_err(), "too few"); } } diff --git a/crates/engine/src/cmd/deeplearning.rs b/crates/engine/src/cmd/deeplearning.rs index 625593603f..88052c5eeb 100644 --- a/crates/engine/src/cmd/deeplearning.rs +++ b/crates/engine/src/cmd/deeplearning.rs @@ -35,6 +35,21 @@ pub struct DlModel { /// Epochs the last training ran (not saved). #[serde(skip)] pub epochs: usize, + /// What the last training left out to stay within the work limit of a run that can't be + /// cancelled ([`neural::Trained::limited`]), said when the model is kept (not saved). + #[serde(skip)] + pub limited: Option, +} + +impl DlModel { + /// Says what its training left out to stay within the work limit, if anything (AGENTS.md › + /// Never silent), and puts it in the command's answer. + fn say_limited(&self, s: &mut Session, v: &mut Value) { + if let Some(what) = &self.limited { + s.warn(format!("{}: {what}", self.name)); + v["limited"] = json!(what); + } + } } fn need_raster(s: &Session) -> Option<&'static str> { @@ -51,6 +66,7 @@ pub fn commands() -> Vec { let (m, unread) = train(s, p)?; unread.say(s); let mut r = json!({"model": m.name, "accuracy": m.accuracy, "classes": m.model.classes, "epochs": m.epochs}); + m.say_limited(s, &mut r); r["replaced"] = json!(store(s, m)); Ok(r) }).inputs(training_inputs).roles(&[]).effects(crate::policy::Effects::NONE) @@ -209,7 +225,8 @@ impl Training { return Err(format!("the class '{c}' has fewer than 5 pixels with data under its polygons")); } let t = neural::train(bands, classes, &samples, hidden, epochs)?; - Ok(DlModel { name, model: t.model, accuracy: t.accuracy, epochs: t.epochs }) + let limited = t.limited(); + Ok(DlModel { name, model: t.model, accuracy: t.accuracy, epochs: t.epochs, limited }) } } @@ -342,6 +359,7 @@ pub(crate) fn classify_work(s: &Session, p: &Value) -> Result Date: Tue, 10 Nov 2026 17:13:41 +0100 Subject: [PATCH 2/5] test(engine): dl.train and dl.classify say a limited training, and a whole one doesn't; epochs out of 1 to 500 are refused, not cut --- crates/analysis/src/neural.rs | 7 +++++ crates/engine/src/cmd/deeplearning.rs | 7 ++++- crates/engine/src/tests.rs | 45 +++++++++++++++++++++++++++ 3 files changed, 58 insertions(+), 1 deletion(-) diff --git a/crates/analysis/src/neural.rs b/crates/analysis/src/neural.rs index b780f930c8..b4d64c65a4 100644 --- a/crates/analysis/src/neural.rs +++ b/crates/analysis/src/neural.rs @@ -565,6 +565,13 @@ mod tests { let said = big.limited().expect("a capped run says what it left out"); assert!(said.contains(&format!("for {} of {MAX_EPOCHS} epochs", big.epochs)), "{said}"); assert_eq!(t.limited(), None, "a run within the limit says nothing"); + // Too many samples for even one epoch of the largest network: a random subset is fitted, + // and said with its count. + let many: Vec<(Vec, usize)> = (0..12_000).map(|i| (vec![(i % 97) as f32, (i % 89) as f32], i % 2)).collect(); + let cut = train(&[0, 1], vec!["a".into(), "b".into()], &many, &[MAX_UNITS; MAX_LAYERS], 1).unwrap(); + assert!(cut.fitted < cut.training && cut.epochs == 1, "{} of {}", cut.fitted, cut.training); + let said = cut.limited().expect("a cut sample set is said"); + assert!(said.contains(&format!("on {} of {} training samples for 1 of 1 epochs", cut.fitted, cut.training)), "{said}"); // Run so it can be cancelled, it fits every sample for every epoch and says nothing. let control = crate::control::Control::stoppable(); let whole = crate::run_under("Train", &control, || train(&[0, 1], vec!["out".into(), "in".into()], &samples, &[8], 3)).unwrap(); diff --git a/crates/engine/src/cmd/deeplearning.rs b/crates/engine/src/cmd/deeplearning.rs index 88052c5eeb..2f815802a1 100644 --- a/crates/engine/src/cmd/deeplearning.rs +++ b/crates/engine/src/cmd/deeplearning.rs @@ -282,7 +282,12 @@ fn training(s: &Session, p: &Value) -> Result { Some(a) => a.iter().filter_map(Value::as_u64).map(|u| u as usize).take(neural::MAX_LAYERS).collect(), None => vec![32, 16], }; - let epochs = f(p, "epochs").unwrap_or(60.0).clamp(1.0, neural::MAX_EPOCHS as f64) as usize; + // Out of range is refused, not cut to it: the training would say nothing of the epochs left out. + let epochs = f(p, "epochs").unwrap_or(60.0); + if !(1.0..=neural::MAX_EPOCHS as f64).contains(&epochs) { + return Err(format!("epochs is 1 to {}, not {epochs}", neural::MAX_EPOCHS)); + } + let epochs = epochs as usize; // Without a name given, a new model never replaces one: it gets a name of its own. let (name, auto) = match ps(p, "model") { Some(_) => (name(&json!({"name": p.get("model")}), format!("{}_model", r.name)), None), diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index 56611c9cee..27ffba5ad9 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -38825,3 +38825,48 @@ fn a_topology_check_runs_ahead_and_is_taken() { let mut s = Session::new(Project::default()); assert!(!read_ahead(&mut s, "topology.validate", &json!({})).unwrap().reads()); } + +/// A model trained within the work limit of a run that can't be cancelled says what it left out, +/// in a notice naming it and as `"limited"` in the answer, from `dl.train` and from `dl.classify` +/// when it trains; one trained whole says nothing (AGENTS.md › Never silent). +#[test] +fn a_model_trained_within_the_work_limit_says_so() { + let mut s = world(); + s.run("layer.addDataBytes", &json!({"fileName": "scene.tif", "data": two_class_b64()})).unwrap(); + let training = json!({"type": "FeatureCollection", "features": [ + {"type": "Feature", "properties": {"class": "water"}, "geometry": {"type": "Polygon", "coordinates": [[[10.002, 45.002], [10.015, 45.002], [10.015, 45.035], [10.002, 45.035], [10.002, 45.002]]]}}, + {"type": "Feature", "properties": {"class": "field"}, "geometry": {"type": "Polygon", "coordinates": [[[10.025, 45.002], [10.038, 45.002], [10.038, 45.035], [10.025, 45.035], [10.025, 45.002]]]}}]}); + s.run("layer.addDataText", &json!({"fileName": "training.geojson", "text": training.to_string()})).unwrap(); + let limited = |s: &Session, mark: u64, name: &str| { + s.notices_since(mark).iter().filter(|n| n.text.starts_with(&format!("{name}: trained on "))).count() + }; + let small = json!({"layer": "scene", "training": "training", "classField": "class", "bands": [1, 2], "epochs": 5, "model": "small"}); + let mark = s.notice_mark(); + let r = s.run("dl.train", &small).unwrap(); + assert!(r.get("limited").is_none(), "{r}"); + assert_eq!(limited(&s, mark, "small"), 0); + // The largest network for every epoch passes the work limit: fewer epochs, said. + let big = json!({"layer": "scene", "training": "training", "classField": "class", "bands": [1, 2], "epochs": 500, + "hidden": [256, 256, 256, 256], "model": "big"}); + let mark = s.notice_mark(); + let r = s.run("dl.train", &big).unwrap(); + let said = r["limited"].as_str().unwrap_or_else(|| panic!("{r}")); + assert!(said.contains("of 500 epochs"), "{said}"); + assert_eq!(limited(&s, mark, "big"), 1); + // dl.classify that trains says it as the model is kept. + let mark = s.notice_mark(); + let r = s + .run( + "dl.classify", + &json!({"layer": "scene", "training": "training", "classField": "class", "bands": [1, 2], "epochs": 500, + "hidden": [256, 256, 256, 256], "model": "big2"}), + ) + .unwrap(); + assert!(r["limited"].as_str().is_some(), "{r}"); + assert_eq!(limited(&s, mark, "big2"), 1); + // More epochs than a training runs are refused, not cut without a word. + for epochs in [0, 501, 5000] { + let e = s.run("dl.train", &json!({"layer": "scene", "training": "training", "classField": "class", "epochs": epochs})).unwrap_err(); + assert!(e.contains("epochs is 1 to 500"), "{epochs}: {e}"); + } +} From c5ffccaee1d506acfac66bfaa8101eefb29f142e Mon Sep 17 00:00:00 2001 From: Dominik Strebel Date: Tue, 10 Nov 2026 18:37:18 +0100 Subject: [PATCH 3/5] fix(engine): epochs given as a fraction or not a number are refused too; neural::train refuses out-of-range epochs --- crates/analysis/src/neural.rs | 5 ++++- crates/engine/src/cmd/deeplearning.rs | 14 +++++++++----- crates/engine/src/tests.rs | 7 +++++-- 3 files changed, 18 insertions(+), 8 deletions(-) diff --git a/crates/analysis/src/neural.rs b/crates/analysis/src/neural.rs index b4d64c65a4..6840a551ba 100644 --- a/crates/analysis/src/neural.rs +++ b/crates/analysis/src/neural.rs @@ -320,7 +320,10 @@ pub fn train( let training = fit.len(); fit.truncate(((max_work / per_sample).min(usize::MAX as f64) as usize).max(1)); let per_epoch = per_sample * fit.len().max(1) as f64; - let epochs_asked = epochs.clamp(1, MAX_EPOCHS); + if !(1..=MAX_EPOCHS).contains(&epochs) { + return Err(format!("epochs is 1 to {MAX_EPOCHS}, not {epochs}")); + } + let epochs_asked = epochs; let epochs = epochs_asked.min(((max_work / per_epoch).min(usize::MAX as f64) as usize).max(1)); let (lr, momentum, batch) = (0.05f32, 0.9f32, 32usize); let mut vel: Vec<(Vec, Vec)> = layers.iter().map(|l| (vec![0.0; l.w.len()], vec![0.0; l.b.len()])).collect(); diff --git a/crates/engine/src/cmd/deeplearning.rs b/crates/engine/src/cmd/deeplearning.rs index 2f815802a1..7677ca9fa3 100644 --- a/crates/engine/src/cmd/deeplearning.rs +++ b/crates/engine/src/cmd/deeplearning.rs @@ -282,11 +282,15 @@ fn training(s: &Session, p: &Value) -> Result { Some(a) => a.iter().filter_map(Value::as_u64).map(|u| u as usize).take(neural::MAX_LAYERS).collect(), None => vec![32, 16], }; - // Out of range is refused, not cut to it: the training would say nothing of the epochs left out. - let epochs = f(p, "epochs").unwrap_or(60.0); - if !(1.0..=neural::MAX_EPOCHS as f64).contains(&epochs) { - return Err(format!("epochs is 1 to {}, not {epochs}", neural::MAX_EPOCHS)); - } + // A count given that isn't a whole number from 1 to 500 is refused, not cut to one or left + // for the default: the training would say nothing of the epochs left out. + let epochs = match p.get("epochs").filter(|v| !v.is_null()) { + None => 60.0, + Some(v) => v + .as_f64() + .filter(|e| (1.0..=neural::MAX_EPOCHS as f64).contains(e) && e.fract() == 0.0) + .ok_or_else(|| format!("epochs is 1 to {}, not {v}", neural::MAX_EPOCHS))?, + }; let epochs = epochs as usize; // Without a name given, a new model never replaces one: it gets a name of its own. let (name, auto) = match ps(p, "model") { diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index 27ffba5ad9..c70b229408 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -38838,7 +38838,10 @@ fn a_model_trained_within_the_work_limit_says_so() { {"type": "Feature", "properties": {"class": "field"}, "geometry": {"type": "Polygon", "coordinates": [[[10.025, 45.002], [10.038, 45.002], [10.038, 45.035], [10.025, 45.035], [10.025, 45.002]]]}}]}); s.run("layer.addDataText", &json!({"fileName": "training.geojson", "text": training.to_string()})).unwrap(); let limited = |s: &Session, mark: u64, name: &str| { - s.notices_since(mark).iter().filter(|n| n.text.starts_with(&format!("{name}: trained on "))).count() + s.notices_since(mark) + .iter() + .filter(|n| n.text.starts_with(&format!("{name}: trained on ")) && n.severity == rustgis_data::diagnostics::Severity::Warning) + .count() }; let small = json!({"layer": "scene", "training": "training", "classField": "class", "bands": [1, 2], "epochs": 5, "model": "small"}); let mark = s.notice_mark(); @@ -38865,7 +38868,7 @@ fn a_model_trained_within_the_work_limit_says_so() { assert!(r["limited"].as_str().is_some(), "{r}"); assert_eq!(limited(&s, mark, "big2"), 1); // More epochs than a training runs are refused, not cut without a word. - for epochs in [0, 501, 5000] { + for epochs in [json!(0), json!(501), json!(5000), json!(2.5), json!("500 epochs")] { let e = s.run("dl.train", &json!({"layer": "scene", "training": "training", "classField": "class", "epochs": epochs})).unwrap_err(); assert!(e.contains("epochs is 1 to 500"), "{epochs}: {e}"); } From 2b913212c15ff78a91178649da15b2e9c91257ff Mon Sep 17 00:00:00 2001 From: Dominik Strebel Date: Tue, 10 Nov 2026 19:11:56 +0100 Subject: [PATCH 4/5] fix(engine): epochs as a numeric string are read as other counts are, then checked --- crates/engine/src/cmd/deeplearning.rs | 4 ++-- crates/engine/src/tests.rs | 7 ++++++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/crates/engine/src/cmd/deeplearning.rs b/crates/engine/src/cmd/deeplearning.rs index 7677ca9fa3..578b6bc58b 100644 --- a/crates/engine/src/cmd/deeplearning.rs +++ b/crates/engine/src/cmd/deeplearning.rs @@ -286,8 +286,8 @@ fn training(s: &Session, p: &Value) -> Result { // for the default: the training would say nothing of the epochs left out. let epochs = match p.get("epochs").filter(|v| !v.is_null()) { None => 60.0, - Some(v) => v - .as_f64() + // Read as other counts are (a numeric string too), then checked. + Some(v) => f(p, "epochs") .filter(|e| (1.0..=neural::MAX_EPOCHS as f64).contains(e) && e.fract() == 0.0) .ok_or_else(|| format!("epochs is 1 to {}, not {v}", neural::MAX_EPOCHS))?, }; diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index c70b229408..c89776b593 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -38868,8 +38868,13 @@ fn a_model_trained_within_the_work_limit_says_so() { assert!(r["limited"].as_str().is_some(), "{r}"); assert_eq!(limited(&s, mark, "big2"), 1); // More epochs than a training runs are refused, not cut without a word. - for epochs in [json!(0), json!(501), json!(5000), json!(2.5), json!("500 epochs")] { + for epochs in [json!(0), json!(501), json!(5000), json!(2.5), json!("2.5"), json!("500 epochs")] { let e = s.run("dl.train", &json!({"layer": "scene", "training": "training", "classField": "class", "epochs": epochs})).unwrap_err(); assert!(e.contains("epochs is 1 to 500"), "{epochs}: {e}"); } + // A count as a numeric string is read as other counts are. + let r = s + .run("dl.train", &json!({"layer": "scene", "training": "training", "classField": "class", "bands": [1, 2], "epochs": "3"})) + .unwrap(); + assert_eq!(r["epochs"], 3, "{r}"); } From 12118a02ea29afac2e63e3b2afa43aeb34e30e9c Mon Sep 17 00:00:00 2001 From: Dominik Strebel Date: Tue, 10 Nov 2026 19:34:31 +0100 Subject: [PATCH 5/5] fix(ui): the Deep Learning pane sends the epochs typed as they are, for the command to read or refuse --- crates/ui-egui/src/analysispane.rs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/crates/ui-egui/src/analysispane.rs b/crates/ui-egui/src/analysispane.rs index 70e58c1f94..f5b0986882 100644 --- a/crates/ui-egui/src/analysispane.rs +++ b/crates/ui-egui/src/analysispane.rs @@ -902,12 +902,14 @@ pub fn workflows(app: &mut RustGisApp, ui: &mut Ui, t: &Tokens) { ui.horizontal(|ui| { ui.add(egui::TextEdit::singleline(&mut app.workflow.number).hint_text(tl!("epochs")).desired_width(60.0)); if ui.button(tl!("Train And Classify")).clicked() { - let epochs = app.workflow.number.trim().parse::().unwrap_or(60.0); - run( - app, - "dl.classify", - json!({"layer": app.workflow.layer, "training": app.workflow.layer2, "classField": app.workflow.field, "epochs": epochs}), - ); + // A blank box is the default; what is typed goes as it is, for the command to + // read or refuse (a fraction or text isn't cut or replaced without a word). + let mut p = json!({"layer": app.workflow.layer, "training": app.workflow.layer2, "classField": app.workflow.field}); + let typed = app.workflow.number.trim(); + if !typed.is_empty() { + p["epochs"] = json!(typed); + } + run(app, "dl.classify", p); } }); let models: Vec<(String, f64)> = app.session.project.dl_models.iter().map(|m| (m.name.clone(), m.accuracy)).collect();