Skip to content

Abstract vessel performance into configs, generalise performance calculation#343

Draft
thomaszwagerman wants to merge 6 commits intomainfrom
tz/vessel_performance
Draft

Abstract vessel performance into configs, generalise performance calculation#343
thomaszwagerman wants to merge 6 commits intomainfrom
tz/vessel_performance

Conversation

@thomaszwagerman
Copy link
Contributor

@thomaszwagerman thomaszwagerman commented Feb 4, 2026

Closes #336, these are very much breaking changes. Should be released as 2.0.0.

Target will be main once tz/ruff -> v1.1.9 are merged.

Added

  • Model Registry System: Plugin-based architecture for resistance and consumption models using @register_model decorator.
  • Generic Vessel Classes: Ship, Glider, AUV, and Aircraft classes replacing hard-coded vessel types.
  • Resistance Models: Three pluggable resistance models:
    • ice_froude: Froude number-based ice resistance with configurable k/b/n coefficients
    • wind_drag: Angle-dependent wind drag with interpolation options (linear/cubic/spline)
    • wave_kreitner: Kreitner wave resistance with beam/length/block coefficient parameters
  • Consumption Models: Three pluggable consumption models:
    • polynomial_fuel: Speed and resistance-based fuel consumption with polynomial coefficients
    • polynomial_battery: Speed and depth-based battery consumption for underwater vehicles
    • constant_consumption: Fixed-rate consumption for simple vehicles
  • Configuration Validation: Comprehensive JSON schema for vessel configurations with detailed parameter documentation including units.
  • Documentation:
    • Vessel configuration gallery with ready-to-use examples (docs/config/vessel_gallery.md)
    • Resistance models theory documentation (docs/methods/resistance_models.md)
    • Complete model parameters reference (docs/reference/model_parameters.md)
  • Example Configurations: Updated vessel configs for SDA, SDA_wind, Slocum, and BoatyMcBoatFace using new format.
  • Unit Tests: 27 comprehensive tests covering model registry, all resistance/consumption models, generic vessel classes, and factory.

Changed

  • Vessel Configuration Format: vessel_type replaced with vessel_class + explicit model specifications.
  • Configuration Structure: All vessel-specific parameters (beam, force_limit, etc.) now explicitly defined in model params rather than top-level.
  • VesselFactory: Simplified factory using VESSEL_CLASSES mapping instead of hard-coded requirements dictionary.
  • Physical Constants: Now configurable per-vessel (gravity, air_density, rho_water) with sensible defaults.
  • Model Composition: Vessels compose multiple resistance models; total resistance is sum of all active models.

Removed

  • Legacy Vessel Classes (BREAKING): Deleted 12 hard-coded vessel files:
    • SDA.py, SDA_wind.py, example_ship.py (ships)
    • slocum.py (gliders)
    • boatymcboatface.py (AUVs)
    • twin_otter.py, windracer.py (aircraft)
    • abstract_ship.py, abstract_glider.py, abstract_alr.py, abstract_plane.py, abstract_uav.py (abstract classes)
  • Configuration Fields (BREAKING):
    • vessel_type (replaced by vessel_class)
    • hull_type (slender/blunt distinction now encoded in k/b/n coefficients)
    • Top-level beam, force_limit (now in resistance model params)

@thomaszwagerman thomaszwagerman changed the base branch from main to v1.1.9 February 4, 2026 13:23
@thomaszwagerman thomaszwagerman changed the base branch from v1.1.9 to tz/ruff February 4, 2026 13:23
@thomaszwagerman thomaszwagerman self-assigned this Feb 4, 2026
Base automatically changed from tz/ruff to v1.1.9 February 10, 2026 14:28
Base automatically changed from v1.1.9 to main February 10, 2026 14:48
@thomaszwagerman
Copy link
Contributor Author

Marking some specific vessel performance tests as XFAIL, see #344

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Vessel performance models: abstract out into configs and consolidate

1 participant