hydrodynamics

Manage hydrodynamic coefficients, wave spectra, and environmental loading for vessel response analysis. Use for 6×6 matrix management, wave spectrum modeling, OCIMF loading calculations, and RAO interpolation.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026⬇️3downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive suite for marine hydrodynamics, enabling engineers to manage 6×6 hydrodynamic matrices, model diverse wave spectra (JONSWAP, Bretschneider, PM), and calculate OCIMF-compliant environmental loads. It automates complex tasks like RAO interpolation and displacement RAO quality validation, ensuring physical consistency and data integrity for vessel response analysis and offshore engineering simulations.

Use Cases

  • Vessel Response Analysis: Managing 6×6 added mass and damping matrices for FPSO, semi-submersibles, and ship motion simulations.
  • Environmental Loading: Calculating wind and current loads based on OCIMF guidelines for mooring system design and station-keeping studies.
  • Wave Spectrum Modeling: Generating and analyzing JONSWAP, Pierson-Moskowitz, and bimodal Ochi-Hubble spectra for offshore site condition assessments.
  • RAO Quality Assurance: Validating displacement RAO data for physical correctness, including phase angle checks at infinite periods and resonance peak detection.
  • Hydrodynamic Database Management: Storing, retrieving, and interpolating frequency-dependent coefficients for seamless integration with marine analysis software like AQWA, WAMIT, or OrcaFlex.
namehydrodynamics
description"Manage hydrodynamic coefficients, wave spectra, and environmental loading\
updated'2026-01-07'

Hydrodynamics Skill

Manage hydrodynamic coefficients, wave spectra, and environmental loading for vessel and floater response analysis.

Version Metadata

version: 1.0.0
python_min_version: '3.10'
compatibility:
  tested_python:
  - '3.10'
  - '3.11'
  - '3.12'
  - '3.13'
  os:
  - Windows
  - Linux
  - macOS

Changelog

[1.0.0] - 2026-01-07

Added:

  • Initial version metadata and dependency management
  • Semantic versioning support
  • Compatibility information for Python 3.10-3.13

Changed:

  • Enhanced skill documentation structure

When to Use

  • 6×6 added mass and damping matrix management
  • Wave spectrum modeling (JONSWAP, Bretschneider, PM)
  • OCIMF wind and current loading calculations
  • RAO interpolation and frequency-dependent coefficients
  • Hydrodynamic coefficient database management
  • Kramers-Kronig causality validation

Prerequisites

  • Python environment with digitalmodel package installed
  • Hydrodynamic coefficient data (from AQWA, WAMIT, etc.)
  • Environmental data for wave/wind/current loading

Analysis Types

1. Coefficient Database Management

Store and retrieve hydrodynamic coefficients.

hydrodynamics:
  coefficient_database:
    flag: true
    vessel_name: "FPSO"
    source_file: "data/hydro_coefficients.json"
    coefficients:
      - added_mass
      - damping
      - wave_excitation
    output:
      database_file: "results/coefficient_db.json"

2. Wave Spectra Modeling

Generate and analyze wave spectra.

hydrodynamics:
  wave_spectra:
    flag: true
    spectrum_type: "jonswap"  # jonswap, bretschneider, pm, custom
    parameters:
      hs: 3.5  # Significant wave height (m)
      tp: 10.0  # Peak period (s)
      gamma: 3.3  # JONSWAP peakedness
    frequency_range:
      min: 0.02
      max: 0.5
      n_points: 100
    output:
      spectrum_file: "results/wave_spectrum.csv"
      plot_file: "results/spectrum_plot.html"

3. OCIMF Environmental Loading

Calculate wind and current loads per OCIMF guidelines.

hydrodynamics:
  ocimf_loading:
    flag: true
    vessel:
      length: 300.0
      beam: 50.0
      draft: 20.0
      displacement: 200000
    environment:
      wind_speed: 25.0
      wind_direction: 45.0
      current_speed: 1.5
      current_direction: 90.0
    output:
      loads_file: "results/ocimf_loads.json"

4. RAO Interpolation

Interpolate RAOs across frequencies and directions.

hydrodynamics:
  rao_interpolation:
    flag: true
    input_raos: "data/vessel_raos.csv"
    target_frequencies: [0.05, 0.1, 0.15, 0.2, 0.25]
    target_directions: [0, 30, 60, 90, 120, 150, 180]
    method: "cubic"  # linear, cubic, spline
    output:
      interpolated_file: "results/interpolated_raos.csv"

5. Displacement RAO Quality Checks

Validate displacement RAO data for physical correctness and consistency.

hydrodynamics:
  rao_quality_check:
    flag: true
    input_file: "data/vessel_raos.yml"  # OrcaFlex format
    vessel_type: auto  # auto, ship, fpso, semi_submersible, spar, barge
    tolerances:
      amplitude: 0.05  # 5% tolerance
      phase: 10.0      # 10 degrees tolerance
    checks:
      - long_period_phase  # Phase angles at T → infinity
      - peak_detection     # Natural period validation
      - vessel_type_detection
    output:
      html_report: "reports/rao_qa/quality_report.html"
      csv_summary: "reports/rao_qa/quality_summary.csv"

Quality Checks:

  • Long Period Phase: Validates phase angles approach expected values as period → infinity (Orcina convention)
  • Peak Detection: Identifies resonance peaks and validates against vessel type natural period ranges
  • Vessel Type Detection: Auto-detects vessel type from RAO characteristics with confidence score
  • Active DOF Validation: Checks appropriate DOFs are active for each wave heading

Python API

Coefficient Database

from digitalmodel.modules.hydrodynamics.coefficient_database import CoefficientDatabase

# Initialize database
db = CoefficientDatabase()

# Store coefficients
db.store(
    vessel_name="FPSO",
    frequency=0.1,
    added_mass=added_mass_matrix,  # 6x6 numpy array
    damping=damping_matrix         # 6x6 numpy array
)

# Retrieve coefficients
A, B = db.get_matrices(vessel_name="FPSO", frequency=0.1)

# Get all frequencies
frequencies = db.get_frequencies("FPSO")

Frequency-Dependent Matrices

from digitalmodel.modules.hydrodynamics.freq_dependent import FrequencyDependentMatrix

# Initialize with frequency-dependent data
fdm = FrequencyDependentMatrix()
fdm.load("hydro_data.json")

# Interpolate to specific frequency
A_interp = fdm.interpolate_added_mass(frequency=0.15)
B_interp = fdm.interpolate_damping(frequency=0.15)

# Get infinite frequency added mass
A_inf = fdm.get_infinite_frequency_added_mass()

Wave Spectra

from digitalmodel.modules.hydrodynamics.wave_spectra import WaveSpectra

# Create JONSWAP spectrum
spectrum = WaveSpectra()
frequencies, S = spectrum.jonswap(
    hs=3.5,       # Significant wave height (m)
    tp=10.0,      # Peak period (s)
    gamma=3.3,    # Peakedness parameter
    freq_min=0.02,
    freq_max=0.5,
    n_points=100
)

# Alternative spectra
freq, S_pm = spectrum.pierson_moskowitz(hs=3.5, tp=10.0)
freq, S_bs = spectrum.bretschneider(hs=3.5, tp=10.0)

# Calculate spectral moments
m0 = spectrum.spectral_moment(frequencies, S, n=0)
m2 = spectrum.spectral_moment(frequencies, S, n=2)
Tz = np.sqrt(m0/m2)  # Zero-crossing period

OCIMF Loading

from digitalmodel.modules.hydrodynamics.ocimf_loading import OCIMFLoading

# Initialize calculator
ocimf = OCIMFLoading()

# Define vessel
vessel = {
    "length": 300.0,
    "beam": 50.0,
    "draft": 20.0,
    "displacement": 200000
}

# Calculate wind load
wind_load = ocimf.wind_load(
    vessel=vessel,
    wind_speed=25.0,
    wind_direction=45.0  # degrees from bow
)
# Returns: {"Fx": ..., "Fy": ..., "Mz": ...}

# Calculate current load
current_load = ocimf.current_load(
    vessel=vessel,
    current_speed=1.5,
    current_direction=90.0
)

Coefficient Interpolation

from digitalmodel.modules.hydrodynamics.interpolator import CoefficientsInterpolator

# Initialize interpolator
interp = CoefficientsInterpolator()

# Load RAO data
interp.load_raos("vessel_raos.csv")

# Interpolate to new frequencies
new_freqs = [0.05, 0.1, 0.15, 0.2]
interpolated = interp.interpolate_frequencies(new_freqs, method="cubic")

# Interpolate to new directions
new_dirs = [0, 45, 90, 135, 180]
interpolated = interp.interpolate_directions(new_dirs)

Causality Validation

from digitalmodel.modules.hydrodynamics.validation import HydroValidator

# Initialize validator
validator = HydroValidator()

# Load frequency-dependent coefficients
validator.load_coefficients("hydro_data.json")

# Kramers-Kronig check
kk_result = validator.kramers_kronig_check()
if not kk_result["passed"]:
    print(f"Causality issues at: {kk_result['violations']}")

# Check matrix properties
sym_check = validator.check_symmetry()
pd_check = validator.check_positive_definite()

Displacement RAO Quality Checks

import yaml
from digitalmodel.modules.marine_analysis import (
    RAODataValidators,
    VesselType,
    DisplacementRAOQualityReport
)
from digitalmodel.modules.marine_analysis.rao_quality_report import RAOQualityReportGenerator

# Load OrcaFlex RAO data
with open("vessel_raos.yml", 'r') as f:
    rao_data = yaml.safe_load(f)

# Initialize validators
validators = RAODataValidators()

# Run quality check (auto-detects vessel type)
report = validators.validate_displacement_rao_quality(
    rao_data,
    source_file="vessel_raos.yml",
    vessel_type=None,  # Auto-detect, or specify VesselType.SHIP
    amplitude_tolerance=0.05,  # 5%
    phase_tolerance=10.0       # degrees
)

# Access results
print(f"Vessel Type: {report.vessel_type.value}")
print(f"Confidence: {report.vessel_type_confidence:.1%}")
print(f"Overall Status: {report.overall_status}")
print(f"Pass Rate: {report.pass_rate:.1f}%")
print(f"Total/Passed/Warnings/Failed: {report.total_checks}/{report.passed_checks}/{report.warning_checks}/{report.failed_checks}")

# Check phase results
for check in report.phase_checks:
    if check.status == 'FAIL':
        print(f"FAIL: {check.dof} @ {check.heading}° - {check.message}")

# Check peak detection results
for check in report.peak_checks:
    print(f"{check.dof}: Peak at {check.peak_period:.1f}s (expected {check.expected_range[0]:.1f}-{check.expected_range[1]:.1f}s)")

# Generate HTML report
generator = RAOQualityReportGenerator(output_dir="reports/rao_qa")
html_path = generator.generate_html_report(report, report_name="vessel_quality")
print(f"HTML report: {html_path}")

# Export CSV summary
csv_path = generator.export_csv_summary(report, report_name="vessel_summary")
print(f"CSV summary: {csv_path}")

# Get active DOFs for a heading
active_dofs = RAODataValidators.get_active_dofs_for_heading(180.0)
print(f"Active DOFs at head seas: {active_dofs}")
# Output: ['surge', 'heave', 'pitch']

Wave Direction Convention:

  • 0° = Head seas (waves from bow, approaching vessel)
  • 90° = Beam seas from starboard
  • 180° = Following seas (waves from stern)
  • 270° = Beam seas from port

Expected Long Period Values (Orcina Convention):

DOF Head Seas (0°) Beam Seas (90°) Following (180°)
Surge Amp=1.0, Phase=-90° Inactive Amp=1.0, Phase=90°
Sway Inactive Amp=1.0, Phase=-90° Inactive
Heave Amp=1.0, Phase=0° Amp=1.0, Phase=0° Amp=1.0, Phase=0°
Roll Inactive Amp=1.0, Phase=-90° Inactive
Pitch Amp=1.0, Phase=90° Inactive Amp=1.0, Phase=-90°
Yaw Inactive Inactive Inactive

Phase Convention Support:

  • PhaseConvention.ORCINA - Phase lag from wave crest (OrcaFlex, OrcaWave)
  • PhaseConvention.ISO_6954 - Phase lead over wave (AQWA, WAMIT)
  • Auto-detection based on file extension (.yml → Orcina, .lis → ISO)

Key Classes

Class Purpose
CoefficientDatabase Coefficient storage and retrieval
FrequencyDependentMatrix 6×6 matrix interpolation
WaveSpectra Spectrum generation (JONSWAP, PM, etc.)
OCIMFLoading OCIMF wind/current calculations
CoefficientsInterpolator 2D interpolation (freq × direction)
HydroValidator Kramers-Kronig and matrix validation
RAODataValidators RAO quality checks (phase, peaks, vessel type)
RAOQualityReportGenerator HTML/CSV quality report generation

Wave Spectrum Types

Spectrum Application
JONSWAP Fetch-limited seas (North Sea)
Pierson-Moskowitz Fully developed seas
Bretschneider General two-parameter spectrum
ISSC Modified Pierson-Moskowitz
Ochi-Hubble Bimodal sea states

Output Formats

Coefficient Database JSON

{
  "vessel_name": "FPSO",
  "frequencies_rad_s": [0.1, 0.2, 0.3],
  "added_mass": {
    "0.1": [[1.2e6, 0, 0, 0, 1.5e7, 0], ...],
    "0.2": [[1.1e6, 0, 0, 0, 1.4e7, 0], ...]
  },
  "damping": {
    "0.1": [[2.5e5, 0, 0, 0, 3.2e6, 0], ...],
    "0.2": [[2.8e5, 0, 0, 0, 3.5e6, 0], ...]
  }
}

Wave Spectrum CSV

frequency_rad_s,frequency_hz,period_s,spectral_density
0.314,0.050,20.0,0.123
0.628,0.100,10.0,2.456
0.942,0.150,6.67,1.234

Best Practices

  1. Frequency range - Cover full wave spectrum of interest (typically 0.02-0.5 rad/s)
  2. Direction convention - Use consistent direction convention (from/to, bow=0°)
  3. Unit consistency - Verify units (rad/s vs Hz, degrees vs radians)
  4. Causality check - Validate coefficients with Kramers-Kronig before use
  5. Matrix symmetry - Verify added mass symmetry for physical consistency

References

  • DNV-RP-C205: Environmental Conditions and Environmental Loads
  • OCIMF: Mooring Equipment Guidelines
  • Newman, J.N.: Marine Hydrodynamics