hydrodynamics

Hydrodynamics Skill

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

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"

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()

Key Classes

Wave Spectrum Types

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

Related Skills

• aqwa-analysis - Extract coefficients from AQWA
• orcaflex-modeling - Apply in OrcaFlex models
• viv-analysis - Hydrodynamic coefficient usage

References

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