orcaflex-environment-config

OrcaFlex Environment Configuration Skill

Configure complete environmental conditions for OrcaFlex simulations including waves, currents, wind, and seabed.

Version Metadata

version: 1.0.0
python_min_version: '3.10'
dependencies:
  orcaflex-modeling: '>=2.0.0,<3.0.0'
  hydrodynamics: '>=1.0.0,<2.0.0'
orcaflex_version: '>=11.0'
compatibility:
  tested_python:
  - '3.10'
  - '3.11'
  - '3.12'
  - '3.13'
  os:
  - Windows
  - Linux
  - macOS

Changelog

[1.0.0] - 2026-01-17

Added:

• Initial release with complete environment configuration
• Wave spectrum support (JONSWAP, Dean Stream, Ochi-Hubble)
• Current profile configuration
• Wind loading setup
• Seabed property management

When to Use

• Setting up wave conditions for simulations
• Configuring depth-varying current profiles
• Adding wind loads to vessel/structure analysis
• Defining seabed properties for touchdown regions
• Creating consistent environmental load cases
• Multi-directional wave/current combinations

Environment Components

Wave Types

Current Profile

Wind Parameters

Configuration

Complete Environment Configuration

# configs/environment_config.yml

environment:
  # General settings
  water_depth: 1500.0     # m
  water_density: 1025.0   # kg/m³
  air_density: 1.225      # kg/m³

  # Wave configuration
  waves:
    type: "JONSWAP"
    significant_height: 5.5    # m (Hs)
    peak_period: 12.0          # s (Tp)
    direction: 180.0           # deg (waves from)
    gamma: 3.3                 # JONSWAP peak enhancement
    spreading: "Cos2s"         # Directional spreading
    spreading_exponent: 2      # s parameter

    # Or multiple wave components
    components:
      - type: "JONSWAP"
        Hs: 4.0
        Tp: 10.0
        direction: 180.0
        gamma: 2.5
      - type: "Swell"
        Hs: 2.0
        Tp: 16.0
        direction: 210.0
        gamma: 6.0

  # Current configuration
  current:
    surface_speed: 1.2      # m/s
    direction: 165.0        # deg (flowing towards)
    profile_type: "Interpolated"

    # Depth profile
    depth_profile:
      - depth: 0.0
        factor: 1.0
      - depth: 50.0
        factor: 0.9
      - depth: 200.0
        factor: 0.5
      - depth: 500.0
        factor: 0.2
      - depth: 1500.0
        factor: 0.05

  # Wind configuration
  wind:
    speed: 25.0           # m/s (1-hour mean)
    direction: 180.0      # deg (from)
    reference_height: 10.0  # m above sea level
    profile: "Power Law"
    exponent: 0.12        # Wind shear exponent

    # Load inclusion
    apply_to:
      vessels: true
      lines: false
      buoys: true

  # Seabed configuration
  seabed:
    type: "Flat"          # or "3D Profile"
    stiffness: 100.0      # kN/m/m²
    friction: 0.5         # Coefficient
    damping: 1.0          # % critical
    slope: 0.0            # deg

Sea State Matrix Configuration

# configs/sea_states.yml

sea_states:
  # Design conditions
  100_year:
    Hs: 8.5
    Tp: 14.0
    gamma: 3.3
    current_speed: 1.5
    wind_speed: 35.0

  10_year:
    Hs: 6.5
    Tp: 12.5
    gamma: 3.0
    current_speed: 1.2
    wind_speed: 28.0

  1_year:
    Hs: 5.0
    Tp: 11.0
    gamma: 2.5
    current_speed: 1.0
    wind_speed: 22.0

  operational:
    Hs: 2.5
    Tp: 8.0
    gamma: 2.0
    current_speed: 0.5
    wind_speed: 12.0

# Heading combinations
headings:
  wave: [0, 15, 30, 45, 60, 75, 90]
  current_offset: 0    # degrees from wave
  wind_offset: 0       # degrees from wave

Python API

Basic Environment Setup

from digitalmodel.modules.fea_model.environment_components import Environment

def setup_environment(config: dict) -> dict:
    """
    Configure OrcaFlex environment from config.

    Args:
        config: Environment configuration dictionary

    Returns:
        OrcaFlex-ready environment properties
    """
    env = Environment()

    # Set general properties
    env.set_water_depth(config["water_depth"])
    env.set_water_density(config.get("water_density", 1025.0))

    # Configure waves
    wave_config = config["waves"]
    if wave_config["type"] == "JONSWAP":
        env.set_jonswap_spectrum(
            Hs=wave_config["significant_height"],
            Tp=wave_config["peak_period"],
            gamma=wave_config.get("gamma", 3.3),
            direction=wave_config["direction"]
        )

    # Configure current
    current_config = config["current"]
    env.set_current_profile(
        surface_speed=current_config["surface_speed"],
        direction=current_config["direction"],
        profile=current_config["depth_profile"]
    )

    # Configure wind
    wind_config = config["wind"]
    env.set_wind(
        speed=wind_config["speed"],
        direction=wind_config["direction"],
        reference_height=wind_config["reference_height"]
    )

    return env.get_orcaflex_environment()

# Example usage
config = {
    "water_depth": 1500.0,
    "waves": {
        "type": "JONSWAP",
        "significant_height": 5.5,
        "peak_period": 12.0,
        "direction": 180.0,
        "gamma": 3.3
    },
    "current": {
        "surface_speed": 1.2,
        "direction": 165.0,
        "depth_profile": [
            {"depth": 0, "factor": 1.0},
            {"depth": 500, "factor": 0.3}
        ]
    },
    "wind": {
        "speed": 25.0,
        "direction": 180.0,
        "reference_height": 10.0
    }
}

env_props = setup_environment(config)

Direct OrcFxAPI Configuration

import OrcFxAPI

def configure_orcaflex_environment(
    model: OrcFxAPI.Model,
    config: dict
) -> OrcFxAPI.OrcaFlexObject:
    """
    Configure environment directly in OrcFxAPI.

    Args:
        model: OrcaFlex model
        config: Environment configuration

    Returns:
        Environment object
    """
    env = model.environment
    general = model.general

    # General settings
    general.WaterDepth = config["water_depth"]
    general.WaterDensity = config.get("water_density", 1025.0)
    general.AirDensity = config.get("air_density", 1.225)

    # Wave configuration
    waves = config["waves"]

    if waves["type"] == "JONSWAP":
        env.WaveType = OrcFxAPI.wtIrregular
        env.WaveSpectrumType = OrcFxAPI.wsJONSWAP
        env.WaveHs = waves["significant_height"]
        env.WaveTp = waves["peak_period"]
        env.WaveGamma = waves.get("gamma", 3.3)
        env.WaveDirection = waves["direction"]

    elif waves["type"] == "Dean Stream":
        env.WaveType = OrcFxAPI.wtDeanStream
        env.WaveHeight = waves["height"]
        env.WavePeriod = waves["period"]
        env.StreamFunctionOrder = waves.get("order", 10)
        env.WaveDirection = waves["direction"]

    elif waves["type"] == "Regular":
        env.WaveType = OrcFxAPI.wtAiry
        env.WaveHeight = waves["height"]
        env.WavePeriod = waves["period"]
        env.WaveDirection = waves["direction"]

    # Directional spreading
    if waves.get("spreading"):
        env.SpreadingType = OrcFxAPI.stCosNTheta
        env.SpreadingExponent = waves.get("spreading_exponent", 2)

    return env

# Example
env = configure_orcaflex_environment(model, config)

Current Profile Configuration

import OrcFxAPI

def set_current_profile(
    model: OrcFxAPI.Model,
    surface_speed: float,
    direction: float,
    depth_factors: list
) -> None:
    """
    Configure depth-varying current profile.

    Args:
        model: OrcaFlex model
        surface_speed: Surface current speed (m/s)
        direction: Current direction (deg)
        depth_factors: List of (depth, factor) tuples
    """
    env = model.environment

    # Set current method
    env.CurrentMethod = OrcFxAPI.cmInterpolated
    env.RefCurrentSpeed = surface_speed
    env.RefCurrentDirection = direction

    # Set profile points
    env.NumberOfCurrentDataPoints = len(depth_factors)

    for i, (depth, factor) in enumerate(depth_factors):
        env.CurrentDepth[i] = depth
        env.CurrentFactor[i] = factor

# Example: Gulf of Mexico loop current profile
current_profile = [
    (0.0, 1.0),      # Surface
    (50.0, 0.95),    # Near surface
    (100.0, 0.8),    # Thermocline
    (300.0, 0.4),    # Mid-depth
    (600.0, 0.15),   # Deep
    (1500.0, 0.02)   # Near seabed
]

set_current_profile(
    model,
    surface_speed=1.5,
    direction=165.0,
    depth_factors=current_profile
)

Wind Configuration

import OrcFxAPI

def configure_wind(
    model: OrcFxAPI.Model,
    speed: float,
    direction: float,
    reference_height: float = 10.0,
    apply_to_vessels: bool = True,
    apply_to_lines: bool = False,
    apply_to_buoys: bool = True
) -> None:
    """
    Configure wind loading.

    Args:
        model: OrcaFlex model
        speed: Wind speed at reference height (m/s)
        direction: Wind from direction (deg)
        reference_height: Reference height above sea level (m)
        apply_to_vessels: Include wind on vessels
        apply_to_lines: Include wind on lines
        apply_to_buoys: Include wind on buoys
    """
    env = model.environment

    # Wind parameters
    env.WindSpeed = speed
    env.WindDirection = direction
    env.WindReferenceHeight = reference_height

    # Wind profile (power law)
    env.VerticalWindVariation = OrcFxAPI.vwvPowerLaw
    env.WindExponent = 0.12  # Typical offshore value

    # Apply to objects
    env.IncludeVesselWindLoads = apply_to_vessels
    env.IncludeLineWindLoads = apply_to_lines
    env.IncludeBuoyWindLoads = apply_to_buoys

# Example
configure_wind(
    model,
    speed=25.0,
    direction=180.0,
    reference_height=10.0,
    apply_to_vessels=True,
    apply_to_buoys=True
)

JONSWAP Gamma Calculation

import math

def calculate_jonswap_gamma(Hs: float, Tp: float) -> float:
    """
    Calculate JONSWAP gamma from Hs and Tp.

    Uses DNV-RP-C205 relationship.

    Args:
        Hs: Significant wave height (m)
        Tp: Peak period (s)

    Returns:
        JONSWAP gamma parameter
    """
    steepness = 2 * math.pi * Hs / (9.81 * Tp**2)

    # DNV-RP-C205 empirical relationship
    if steepness <= 0.031:
        gamma = 5.0
    elif steepness >= 0.054:
        gamma = 1.0
    else:
        gamma = math.exp(3.484 * (1 - 0.1975 * (0.036 - steepness) * Tp**4 / Hs**2))

    return max(1.0, min(7.0, gamma))

# Example
Hs = 5.5  # m
Tp = 12.0  # s
gamma = calculate_jonswap_gamma(Hs, Tp)
print(f"Calculated gamma: {gamma:.2f}")

Multi-Directional Waves

import OrcFxAPI

def configure_multi_directional_waves(
    model: OrcFxAPI.Model,
    wave_components: list
) -> None:
    """
    Configure multi-directional wave system.

    Args:
        model: OrcaFlex model
        wave_components: List of wave dictionaries
    """
    env = model.environment

    # Enable wave trains
    env.NumberOfWaveTrains = len(wave_components)

    for i, wave in enumerate(wave_components):
        env.WaveTrainType[i] = OrcFxAPI.wtIrregular
        env.WaveTrainSpectrumType[i] = OrcFxAPI.wsJONSWAP
        env.WaveTrainHs[i] = wave["Hs"]
        env.WaveTrainTp[i] = wave["Tp"]
        env.WaveTrainGamma[i] = wave.get("gamma", 3.3)
        env.WaveTrainDirection[i] = wave["direction"]

        # Optional: Set spectral seed
        if "seed" in wave:
            env.WaveTrainSeed[i] = wave["seed"]

# Example: Wind sea + swell
wave_components = [
    {"Hs": 4.0, "Tp": 10.0, "gamma": 2.5, "direction": 180, "seed": 12345},
    {"Hs": 2.0, "Tp": 16.0, "gamma": 6.0, "direction": 210, "seed": 67890}
]

configure_multi_directional_waves(model, wave_components)

Output Formats

Environment YAML Output

Environment:
  WaterDepth: 1500.0
  WaterDensity: 1025.0
  SeabedType: Flat
  SeabedStiffness: 100.0

  Waves:
    Type: JONSWAP
    Hs: 5.5
    Tp: 12.0
    Gamma: 3.3
    Direction: 180.0
    SpreadingType: Cos2s
    SpreadingExponent: 2

  Current:
    Method: Interpolated
    RefSpeed: 1.2
    RefDirection: 165.0
    Profile:
      - [0.0, 1.0]
      - [50.0, 0.9]
      - [200.0, 0.5]
      - [500.0, 0.2]

  Wind:
    Speed: 25.0
    Direction: 180.0
    ReferenceHeight: 10.0
    Profile: PowerLaw
    Exponent: 0.12

Best Practices

Wave Configuration

1. Gamma selection - Use calculated value or site-specific data
2. Frequency range - Ensure adequate coverage for RAO response
3. Duration - 3-hour simulations for design
4. Seed selection - Use consistent seeds for comparisons

Current Profile

1. Depth resolution - Include thermocline effects
2. Near-seabed - Adequate resolution at touchdown
3. Directionality - May differ from wave direction
4. Variation - Consider loop current or seasonal changes

Wind Loading

1. Gust factor - Include for dynamic response
2. Height correction - Apply appropriate profile
3. Drag coefficients - Verify vessel wind areas
4. Shielding - Consider in tandem operations

Error Handling

try:
    env_props = setup_environment(config)
except ValueError as e:
    print(f"Configuration error: {e}")
    print("Check wave/current/wind parameters")

except KeyError as e:
    print(f"Missing parameter: {e}")

Related Skills

• orcaflex-modeling - Run OrcaFlex simulations
• orcaflex-operability - Multi-sea-state analysis
• hydrodynamics - Wave spectra management
• mooring-design - Environmental loading

References

• DNV-RP-C205: Environmental Conditions and Loads
• API RP 2MET: Metocean
• OrcaFlex: Environment Data
• Source: src/digitalmodel/modules/fea_model/environment_components.py