Skip to content

Release Notes OSMOSE 4.4.0

Jump to bottom Edit New page
Ricardo Oliveros Ramos edited this page Jun 11, 2026 · 2 revisions

🌊 OSMOSE 4.4.0 — Java Release Notes

1. 🎯 Overview

This release introduces major architectural improvements, new biological capabilities, expanded economic modeling, and significant refactoring of internal processes, especially:

  • Background species system overhaul
  • Region‑aware mortality
  • Fishing & discards tracked in numbers
  • Maturity ogive (stochastic reproduction) (see here for details)
  • New egg size bioenergetics formulation
  • Reworked restart logic
  • Large configuration key migration
  • Simplified bioenergetics computation when lack of data (see Simplified Bioenergetics)
  • Post-reproduction mortality (see here)

These changes modernize the modeling framework and extend its biological, ecological, and economic realism.

1. ⚙️ Configuration Changes (User Level)

1.1. Renamed (breaking) configuration keys

Module toggles

Old Key New Key
simulation.bioen.enabled module.bioenergetics.enabled
simulation.genetic.enabled module.genetics.enabled
fisheries.enabled module.multispecies.fisheries.enabled
economy.enabled module.bioeconomics.enabled

Restart system

Old Key New Key
output.restart.enabled simulation.restart.enabled
output.restart.recordfrequency.ndt simulation.restart.recordfrequency.ndt
output.restart.spinup simulation.restart.spinup.nyear

Bioenergetic module

Old Key New Key
predation.ingestion.rate.max.bioen.spX predation.ingestion.rate.max.spX
predation.coef.ingestion.rate.max.larvae.bioen.sp predation.larval.ingestion.rate.increase.ratio.spX
species.bioen.maturity.eta.spX species.maturity.eta.spX
species.bioen.maturity.r.spX species.maturity.r.spX
species.bioen.maturity.m0.spX species.bioen.maturity.m0.spX
species.bioen.maturity.m1.spXX species.maturity.m1.spX

These renames are mandatory for existing configurations.

1.2. New configuration keys

Post-reproduction mortality

  • species.reproduction.strategy.sp# = iteroparous or semelparous
  • species.reproduction.postspawning.survivaltime.sp# = post-reproduction survival time (in years). Used only for semelparous

Simulation & reproducibility

  • simulation.fixed.seed.enabled: used to control the stochasticity of a simulation and allow replicable runs
  • simulation.nschool.multiplier: Parameter to multiply the number of schools for all species (default one):

Maturity ogive

See here for details

  • species.maturity.mode: controls whether stochastic (stochastic) or deterministic (legacy) production is used.
  • species.maturity.l50.sp#: mean of the gaussian - species.maturity.l75.sp#

Egg size (bioenergetics)

  • species.egg.density.sp#: density of eggs (in $g.cm^{-3}$) used to compute length from weight.

Background species & biomass scaling

  • species.multiplier.sp#: multiplier to control background species biomass
  • species.multiplier.log.sp#: multiplier to control background species biomass (in log value)

Background movement & map handling

  • movement.randomwalk.range.sp#: allow to specify the range of random walk for background species.
  • movement.netcdf.enabled: allow map distributions from NetCDF for Background species

Bioeconomics module

The bioeconomic module is now functional. Parameters are fully described here

  • species.stock.elasticity.sp#
  • baseline.costs.t0.sp#
  • price.time.trend.sp#
  • species.consumption.elasticity.sp#
  • species.sizeconsumption.elasticity.sp#
  • species.size.preference.sp#
  • weight.fish.consumption
  • substitution.elasticity
  • elasticity.demand.fish

Gradient based movements

See details here

  • movement.random.walk.coef.sp#: Random walk coefficient (between 0 and 1)
  • movement.base.search.radius.sp#: perception (integer, ranging from 1 to 0)

Predation on LTL

  • simulation.resources.computePercent.legacy: if set to True, the LTL percentage that is eaten by a school is computed based on the original linear relationship. Else, it will use a $\log$ relationship.

Bioenergetics

Parameters to control whether a simplified bioenergetic implementation should be used (see here for details)

  • species.bioenergetics.model.sp: full or simple
  • predation.efficiency.critical.spX
  • species.temperature.tmin.spX
  • species.temperature.tmax.spX
  • species.temperature.topt.spX
  • predation.ingestion.rate.max.spX

3. ⭐ User‑Facing Changes

3.1. Major New Features

Gradient-based movement distribution

LTL predation

  • Possibility to use a log version of the computePercent method

✔ Region‑specific mortality

Mortality is now tracked per output region. Arrays such as nDead and ageDeath are now 2‑dimensional: [region][mortality_cause].

✔ Fishing & discards tracked in numbers

Fishing/discard tracking moved from biomass to abundance:

  • fishedBiomass → fishedAbundance
  • discardedBiomass → discardedAbundance
  • Biomass now computed on demand using abundance × mass functions.

✔ Background species & maps overhaul

A new full subsystem handles background species:

  • Background schools are now real “schools” integrated into the simulation
  • Background movement powered by maps (CSV/NetCDF)
  • New classes for background distribution and filtering
  • Background schools populate the grid using class-based biomass and spatial maps
  • Full per-timestep movement/redistribution support
  • Consistent inclusion of background schools in outputs

3.2. Biological Process Enhancements

✔ Stochastic maturity ogive

Optional probabilistic (not deterministic) maturity (see here for details):

  • Uses parameters species.maturity.l50.sp# & species.maturity.l75.sp#
  • A normal CDF calculates probability of maturing between timesteps
  • Once mature, always mature

✔ Improved egg size under bioenergetics

Under the bioenergetics module:

  • Egg size uses a spherical egg model based on density
  • New config key: species.egg.density.sp#

This replaces the adult-coefficient-based egg mass–length conversion.

3.3. Expanded Bioeconomics Module

Economic modelling expanded significantly:

  • Harvesting costs
  • Consumer utility of fish consumption
  • Species & size‑class prices
  • Profit and profit margin
  • Multi‑elasticity modeling
  • Multi‑dimensional harvested/accessible biomass arrays: [fishery][species][size-class]

New parameters include elasticities, cost time trends, size preferences and more.

3.4. Simulation & Restart Enhancements

✔ More robust restart system

  • Restart keys migrated to simulation.restart.*
  • Intelligent fallback between plain and per-rank files
  • Required global attribute in restart NetCDF: step
  • Improved error messages

✔ Deterministic simulation mode

simulation.fixed.seed.enabled enforces reproducible random number generation for:

  • Movement
  • Reproduction
  • Genetics
  • Resource forcing
  • Fishing selectivity

3.5. Output Behavior Improvements

✔ NetCDF chunking default changed

Default chunking now uses the standard NetCDF-4 chunking strategy for improved performance.

✔ Background species always included in outputs

Refactor ensures consistent treatment of background schools in spatial, fisheries, mortality, and predator-prey outputs.

4. 💥 Breaking Changes

⚠ Fishing/discards API changed

  • fishedBy() / discardedBy() replaced by fishedNBy() / discardedNBy()
  • Fishing inputs/outputs now primarily use numbers, not biomass

⚠ Mortality API changed

incrementNdead() now requires the timestep:

incrementNdead(MortalityCause cause, double nDead, int timeStep)

⚠ Region indexing mandatory

nDead, ageDeath, caught fish, discards, mortality outputs and other arrays now include a region dimension.

⚠ Restart NetCDF must include global attribute step

Restart files missing this field will cause the simulation to abort.

⚠ Many configuration keys renamed or restructured

Old keys will not work without migration.

⚠ Species background biomass reading and scaling logic changed

Existing background configurations relying on older semantics may need adjustment.

5. 👨‍💻 Developer‑Facing Notes

5.1. Background Species Refactor

A very large subsystem rewrite:

  • BackgroundProcess executes each timestep
  • BackgroundMapDistribution controls school movement
  • BackgroundMapSet handles map loading (CSV/NetCDF)
  • Schools moved to cells via probability maps
  • Schools reinitialized/reset when maps change
  • Background species are tracked with real biomass × class distributions

This will impact any tool, plugin, or analysis code accessing background species.

5.2. Aggregation Interface Changes

New abstract methods required in AbstractSchool / IAggregation:

  • isMature()
  • isAlive()
  • getClassIndex()
  • isOut()

Plus new utilities:

  • resetAccessiblePreyIndex()
  • addAccessiblePreyIndex()
  • getAccessiblePreyIndex()

Internal arrays:

  • nDead and ageDeath become 2D arrays [region][cause].

5.3. Configuration Parsing Changes

  • Many key comparisons now use equalsIgnoreCase()
  • Path resolution uses getAbsolutePath() instead of getCanonicalPath() (fix for Windows)
  • Restart key structure updated
  • More defensive parsing for command-line arguments

5.4. Bioeconomics Engine Rewrite

Developers integrating with the economy module must update:

  • New matrices for biomass accessibility and harvest
  • New cost and price calculations
  • Multi-parameter elasticity and preference models
  • Utility & profit functions rewritten
  • Many new configuration points

5.5. Initialization & Restart Logic

  • Genetic diversity and trait values may now be restored from restart files
  • Population initialization more modular
  • Schools created during reproduction have improved genetic initialization logic

6. 🐞 Bug Fixes

  • Correction of the BiomassDietStageOutput.write method. There was a bug in the indexing during the conversion from 2D to 1D.
  • In SimulationStep, movementProcess.run() is now called before indicators.initStep(). This in order to make sure that the initial biomass is always less than the total predated biomass.
  • In spatial outputs (SpatialAbundanceOutput.java and SpatialBiomassOutput.java), only cut-off ages were working, not cut-off length. This has been corrected.
  • Correction in MPA initialization when using restart files. In some cases, the isUpToDate variable of the setMPA method was always true, therefore the fishing effort was never modified. Besides, MPA index as defined in the configuration files (.mpaXX) were expected to start from 0 onward. Now any index can work, as for species.
  • Correction in the reading of files from regular expressions. Canonical path was replaced by absolute paths to make it work on Windows
  • Correct a bug in Surveys and OutputRegion. When school was out of the domain, the code crashed. Fixed by assuming that outside schools are out of the survey region.
  • Correct a bug in the NetcdfPopulator.java when genetic is enabled. The genotype was not instanciated.
  • Correct a bug in the RelativeBiomassPopulator.java when genetic and/or bioenegetic was on. Genotype was not instanciated and maturity and gonadic weight were not initialized
  • Species name validation now supports hyphens

7. 📦 Summary Table

Category Summary
New Features Region‑specific mortality, stochastic maturity ogive, density-based egg size, background movement maps, expanded bioeconomics
Breaking Changes New fishing/discard APIs, mortality API requires timestep, config key renames, restart requirements, region dimension added
Behavioral Changes NetCDF chunking change, background school process rewrite, new maturity logic, numbers-based fishing
Developer Refactors Background species subsystem, economy engine, school interface changes, initialization/restart logic
Bug Fixes Improved validation, safer parsing, corrected map logic, more robust biomass and egg handling

8. ✔ Short Summary

  • Region‑specific mortality
  • Fishing/discards tracked in numbers
  • Background school overhaul (movement maps, biomass classes)
  • Stochastic maturity ogive (L50/L75)
  • Egg size from spherical-density model
  • Bioeconomics: costs, utility, prices, profit
  • Config key migration to module.* and simulation.restart.*
  • Restart requires global attribute 'step'
  • NetCDF chunking uses 'standard' by default

🌊 OSMOSE 4.4.0 — R Release Notes

🚀 Highlights

  • New end-to-end calibration workflow: add setup, test, run-model, and check utilities for OSMOSE calibrations, including automatic generation of parameter bounds/templates and observed-data scaffolding.
  • Much richer output handling: improved reading/structuring of fishery & survey outputs, including by-fishery-by-species arrays, time/class aggregation, and functional group rollups.
  • Major get_var() upgrade: new subsetting, safer behavior, and replicate sampling features make extraction of outputs more flexible and robust.

✨ New Features

1) Calibration framework (new public API)

A complete set of calibration utilities was added, centered around:

  • osmose_calibration_setup() Creates a calibration directory structure, writes guess/min/max/phase parameter files, installs scripts/templates, runs pre-flight model checks, and creates (or consumes) observed-data templates plus calibration settings.

  • osmose_calibration_test() Runs automated tests (data compatibility + sequential and parallel “smoke tests”) to validate that the calibration environment is correctly configured.

  • osmose_calibration_runmodel() Runs the calibration-ready model using the calibration directory and parameter sets, with safeguards against mixing calibrated vs non-calibrated parameters.

  • osmose_calibration_check() Re-runs the model with best parameters from results/restart and returns a calibration object combining simulated/observed/settings/cv.

  • osmose_calibration_outputs() Produces a curated list of calibration-ready outputs (surveys, landings, catch-at-length, penalties for growth/mortality/collapse/outburst, etc.).

2) Calibration parameter helpers (new internal + exported utilities)

New helpers make it easier to transform, replicate, and write parameter sets:

  • Parameter manipulation & transformations:
    • set_par(), transform_par(), replicate_par()
    • logit(), ilogit() helpers
  • Parameter extraction logic for calibration/grouped parameters:
    • get_par2(), get_par_phase(), get_calibration_parameters(), get_osmose_parameter()
  • Writers:
    • write_osmose_parameter() (writes guess/min/max/phase entries for a parameter block)
  • Calibration settings creators:
    • .create_calibration_settings() plus type-specific helpers (simple/survey)

3) New S3 methods for usability (head()/tail() on OSMOSE outputs)

New head.* and tail.* methods preserve OSMOSE output class when slicing:

  • tail.osmose.biomass, tail.osmose.abundance, tail.osmose.yield, tail.osmose.yieldN
  • head.osmose.biomass, head.osmose.abundance, head.osmose.yield, head.osmose.yieldN

4) Configuration checks: egg density validation

A new internal check warns when egg density appears unrealistic:

  • .check_density() computes density from egg weight and egg size and emits warnings for “lower than seawater”, “abnormal”, or “wrong” density ranges.

📈 Output & Data Handling Improvements

1) readOsmoseFiles() gains survey-aware grouping and safer behavior

  • New argument bySurvey (in addition to bySpecies) supports more structured output folder parsing.
  • Combined grouping (bySpecies + bySurvey) is supported, with logic based on how many “grouping dimensions” are requested.
  • Returns NULL when no matching files exist, avoiding downstream failures.

2) Fishery outputs expanded and reshaped

New NetCDF-based fishery outputs are supported and integrated:

  • Added reading/representation of:
    • yieldByFisheryBySpecies, yieldNByFisheryBySpecies, accessibleBiomassByFishery
  • New reshaping and aggregation helpers:
    • .reshapeFishery() (with by="fishery"|"species" and aggregate=TRUE/FALSE)
    • Aggregations across time/class/year:
      • .aggregate_catch_bytime(), .aggregate_catch_byclass(), .aggregate_catch_byyear()
  • New “observed.*” fields are produced from reshaped fishery catches (e.g., observed.landings, observed.discards) to feed calibration workflows.

3) Surveys are treated as first-class outputs

  • Survey outputs now support bySurvey and include additional survey datasets (e.g., mortality/predator pressure) where available.
  • Survey outputs can be filtered to their target species based on config.

4) More robust CSV/NetCDF reading

  • CSV readers now fail gracefully and return NULL on read errors instead of erroring.
  • NetCDF reader .read_osmose_ncdf() was hardened:
    • uses try(nc_open(...)) and returns NULL if opening fails
    • adds dimension names (time, species, fishery, replicates) and handles species_names / fisheries_names attributes

🧰 API Enhancements & Behavior Changes

1) get_var() is significantly enhanced

get_var.osmose() now supports:

  • hierarchical subsetting:
    • sp, srv, fsh arguments for species / survey / fishery selection
  • safer behavior:
    • no.error=TRUE returns NULL instead of throwing when variables are missing
  • output shaping and replicate sampling:
    • drop, size, random, replace for slicing/sampling replicates
  • new generic helpers/methods:
    • get_var.default(), get_var.osmose.calibration(), get_var.list, get_var.NULL

Potential breaking change: code that relied on get_var() erroring on missing variables may need updates if no.error=TRUE is used or propagated.

2) Plotting behavior improved for plot.osmose()

  • plot.osmose() now passes derived metadata (initialYear, freq) when plotting extracted variables, improving plot correctness for time axes.

3) Printing osmose objects is more informative

  • print.osmose() now prints model name/version from configuration, replicate count, species list, and a compact list of available outputs (excluding empty/system fields).

🛠️ Refactoring, Maintenance, and Internal Changes

Cache management cleanup

  • cacheManager, cachePath, flushCache, updateCache were refactored:
    • consistent TRUE/FALSE, clearer assignments, explicit return(invisible(NULL))
    • updated jar URL naming consistency for 4.3.2/4.3.3 entries

Version parsing supports 4-part versions

  • Version validation now accepts X.Y.Z.W in addition to X, X.Y, X.Y.Z.

Output trimming helper

  • New .trim_matrix() drops trailing all-NA columns more safely when reading some outputs.

Minor consistency/documentation improvements

  • Author name capitalization normalized (e.g., “Nicolas BARRIER”).
  • Roxygen imports expanded (notably utils::relist/as.relistable and several calibrar functions).

⚠️ Notes for Upgraders

Potential breaking/behavioral changes

  • Fishery outputs: previous yieldByFishery structures are replaced/extended by new arrays and reshaped derivatives (landingsBy*, discardsBy*, etc.). If you depended on legacy fields, update to the new names.
  • readOsmoseFiles() grouping: introducing bySurvey changes how files can be grouped/parsed; calling code may need to specify bySpecies/bySurvey explicitly.
  • get_var() signature expanded: if you were using ... forwarding into get_var.osmose() you may want to ensure no name collisions with new formal args (sp, srv, fsh, size, etc.).
Add a custom footer

Clone this wiki locally