Predation diffusion and external diffusion

.claude/skills/upgrade-mizer-data.md

@@ -0,0 +1,66 @@
+# Upgrade MizerParams / MizerSim data objects
+
+Use this skill after any change to the `MizerParams` or `MizerSim` S4 class
+definition — new slots, removed slots, changed slot types, or new entries in
+named lists such as `@rates_funcs`.
+
+## Steps
+
+### 1. Update `upgradeParams()` in `R/upgrade.R`
+
+Add code that patches old objects to the new state. Place it just before the
+final block:
+
+```r
+params@mizer_version <- packageVersion("mizer")
+params <- validParams(params, info_level = 0)
+```
+
+Example — adding a new `rates_funcs` entry:
+
+```r
+# Add Diffusion rate function if missing (added in 2.5.4.9122)
+if (is.null(params@rates_funcs[["Diffusion"]])) {
+    params@rates_funcs[["Diffusion"]] <- "mizerDiffusion"
+}
+```
+
+### 2. Bump the version threshold in `needs_upgrading()` in `R/upgrade.R`
+
+Change the comparison to the **new** version so that existing objects stored
+with the old version are detected as needing an upgrade:
+
+```r
+!.hasSlot(params, "mizer_version") ||
+    params@mizer_version < "2.5.4.9122"   # ← new version
+```
+
+### 3. Bump the version in `DESCRIPTION`
+
+```
+Version: 2.5.4.9122
+```
+
+### 4. Reload, upgrade, and save the data objects
+
+```r
+devtools::load_all()
+NS_params <- upgradeParams(NS_params)
+NS_sim    <- upgradeSim(NS_sim)
+save(NS_params, file = "data/NS_params.rda", compress = "xz")
+save(NS_sim,    file = "data/NS_sim.rda",    compress = "xz")
+```
+
+### 5. Reload again before running tests
+
+```r
+devtools::load_all()
+devtools::test()
+```
+
+## Why this matters
+
+Tests load `NS_params` and `NS_sim` from the `data/` directory. If those
+objects predate the class change they will be missing new slots or list
+entries, causing errors that look like rate-function or projection failures
+rather than the real cause (stale stored objects).

.gitignore

@@ -9,4 +9,7 @@ docs/dev
 .vscode
 .positai
 .claude
+!.claude/
+!.claude/skills/
+!.claude/skills/**
 .codex

AGENTS.md

@@ -42,7 +42,9 @@ devtools::clean_dll(); devtools::load_all()
 - Use snapshot tests for complex outputs
 - Run `devtools::document()` after adding or changing exports
 - Run `devtools::load_all()` before running tests
+- After modifying the `MizerParams` or `MizerSim` class (new/removed slots, changes to `@rates_funcs`, etc.), follow the steps in `.claude/skills/upgrade-mizer-data.md`. Claude Code users can invoke this as `/upgrade-mizer-data`.
 
 ## Before Submitting
 
-Update `NEWS.md` when adding features or fixing bugs.
+- After adding a new file under `R/`, add it to the `Collate:` field in `DESCRIPTION` (roxygen2 does not manage this automatically in this package).
+- Update `NEWS.md` when adding features or fixing bugs.

DESCRIPTION

@@ -19,7 +19,7 @@ Authors@R: c(person("Gustav", "Delius", email="gustav.delius@york.ac.uk",
                     comment = c(ORCID = "0000-0002-8478-3430")),
              person("Richard", "Southwell", email="richard.southwell@york.ac.uk",
                     role=c("ctb", "cph")))
-Version: 2.5.4.9113
+Version: 2.5.4.9123
 License: GPL-3
 Imports:
     assertthat,
@@ -47,6 +47,7 @@ Suggests:
     roxygen2,
     knitr,
     rmarkdown,
+    quarto,
     pkgdown,
     covr,
     spelling
@@ -71,7 +72,8 @@ Collate:
     'setMetadata.R'
     'setExtMort.R'
     'setExtEncounter.R'
-    'setDiffusion.R'
+    'diffusion.R'
+    'setExtDiffusion.R'
     'setReproduction.R'
     'setResource.R'
     'setFishing.R'
@@ -114,13 +116,13 @@ Collate:
     'steadySingleSpecies.R'
     'defaults_edition.R'
     'validSpeciesParams.R'
-RoxygenNote: 7.3.3
 Roxygen: list(markdown = TRUE)
 Encoding: UTF-8
 LazyData: true
 URL: https://sizespectrum.org/mizer/, https://github.com/sizespectrum/mizer
 BugReports: https://github.com/sizespectrum/mizer/issues
 Language: en-GB
 RdMacros: lifecycle
-VignetteBuilder: knitr
+VignetteBuilder: knitr, quarto
 Config/testthat/edition: 3
+Config/roxygen2/version: 8.0.0

NAMESPACE

@@ -3,7 +3,7 @@
 S3method("[",ArraySpeciesBySize)
 S3method("[",ArraySpeciesByTime)
 S3method("catchability<-",MizerParams)
-S3method("diffusion<-",MizerParams)
+S3method("ext_diffusion<-",MizerParams)
 S3method("ext_encounter<-",MizerParams)
 S3method("ext_mort<-",MizerParams)
 S3method("gear_params<-",MizerParams)
@@ -43,12 +43,12 @@ S3method(calibrateNumber,MizerParams)
 S3method(calibrateYield,MizerParams)
 S3method(catchability,MizerParams)
 S3method(compareParams,MizerParams)
-S3method(diffusion,MizerParams)
 S3method(distanceMaxRelRDI,MizerParams)
 S3method(distanceSSLogN,MizerParams)
 S3method(dw,MizerParams)
 S3method(dw_full,MizerParams)
 S3method(expandSizeGrid,MizerParams)
+S3method(ext_diffusion,MizerParams)
 S3method(ext_encounter,MizerParams)
 S3method(ext_mort,MizerParams)
 S3method(finalN,MizerSim)
@@ -62,6 +62,7 @@ S3method(getCommunitySlope,MizerParams)
 S3method(getCommunitySlope,MizerSim)
 S3method(getCriticalFeedingLevel,MizerParams)
 S3method(getDiet,MizerParams)
+S3method(getDiffusion,MizerParams)
 S3method(getEGrowth,MizerParams)
 S3method(getERepro,MizerParams)
 S3method(getEReproAndGrowth,MizerParams)
@@ -181,7 +182,7 @@ S3method(search_vol,MizerParams)
 S3method(selectivity,MizerParams)
 S3method(setBevertonHolt,MizerParams)
 S3method(setColours,MizerParams)
-S3method(setDiffusion,MizerParams)
+S3method(setExtDiffusion,MizerParams)
 S3method(setExtEncounter,MizerParams)
 S3method(setExtMort,MizerParams)
 S3method(setFishing,MizerParams)
@@ -207,7 +208,7 @@ S3method(validSim,MizerSim)
 S3method(w,MizerParams)
 S3method(w_full,MizerParams)
 export("catchability<-")
-export("diffusion<-")
+export("ext_diffusion<-")
 export("ext_encounter<-")
 export("ext_mort<-")
 export("gear_params<-")
@@ -231,6 +232,7 @@ export("resource_rate<-")
 export("search_vol<-")
 export("selectivity<-")
 export("species_params<-")
+export("use_predation_diffusion<-")
 export(ArraySpeciesBySize)
 export(ArraySpeciesByTime)
 export(BevertonHoltRDD)
@@ -262,14 +264,14 @@ export(constant_other)
 export(customFunction)
 export(default_pred_kernel_params)
 export(defaults_edition)
-export(diffusion)
 export(distanceMaxRelRDI)
 export(distanceSSLogN)
 export(double_sigmoid_length)
 export(dw)
 export(dw_full)
 export(emptyParams)
 export(expandSizeGrid)
+export(ext_diffusion)
 export(ext_encounter)
 export(ext_mort)
 export(finalN)
@@ -283,6 +285,7 @@ export(getCommunitySlope)
 export(getComponent)
 export(getCriticalFeedingLevel)
 export(getDiet)
+export(getDiffusion)
 export(getEGrowth)
 export(getERepro)
 export(getEReproAndGrowth)
@@ -367,6 +370,7 @@ export(matchYields)
 export(maturity)
 export(melt)
 export(metab)
+export(mizerDiffusion)
 export(mizerEGrowth)
 export(mizerERepro)
 export(mizerEReproAndGrowth)
@@ -437,7 +441,7 @@ export(selectivity)
 export(setBevertonHolt)
 export(setColours)
 export(setComponent)
-export(setDiffusion)
+export(setExtDiffusion)
 export(setExtEncounter)
 export(setExtMort)
 export(setFishing)
@@ -464,6 +468,7 @@ export(species_params)
 export(steady)
 export(steadySingleSpecies)
 export(truncated_lognormal_pred_kernel)
+export(use_predation_diffusion)
 export(validEffortVector)
 export(validGearParams)
 export(validGivenSpeciesParams)

NEWS.md

@@ -1,5 +1,14 @@
 # Development version 2.5.4.9102
 
+- `MizerParams` gains a `use_predation_diffusion` slot (logical, default `FALSE`).
+  When `FALSE` (the default), [mizerDiffusion()] omits the predation-induced
+  diffusion term, preserving the behaviour of previous mizer versions. Set to
+  `TRUE` to enable the jump-growth diffusion term.
+
+- `diffusion()` / `diffusion<-()` / `setDiffusion()` have been renamed to
+  `ext_diffusion()` / `ext_diffusion<-()` / `setExtDiffusion()` to follow the
+  same naming convention as `setExtMort()` and `setExtEncounter()`.
+
 - The `MizerSim` accessors defined in `R/MizerSim-class.R` (`validSim()`,
   `N()`, `NResource()`, `finalN()`, `finalNResource()`, `idxFinalT()`,
   `getTimes()`, `getEffort()`, and `getParams()`) are now registered as S3
@@ -115,8 +124,8 @@
 - The numerical scheme now supports diffusion in the McKendrick-von Foerster
   equation, allowing individual variability in growth to be modelled. A new
   `diffusion` slot in `MizerParams` holds the diffusion coefficient (species x
-  size). Use `setDiffusion()` / `diffusion()` / `diffusion<-()` to set and
-  retrieve it.
+  size). Use `setExtDiffusion()` / `ext_diffusion()` / `ext_diffusion<-()` to
+  set and retrieve it.
 - New `getFlux()` function calculates the flux of individuals entering each size
   class, combining the advective flux from somatic growth and the diffusive flux.
 - `getRequiredRDD()` is now exported. It calculates the recruitment rate needed