OrcaFlex Vessel Setup Skill

Configure 6-DOF vessels in OrcaFlex with hydrodynamic properties, RAO import, and calculation settings.

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 vessel configuration
6-DOF initialization and positioning
AQWA vessel import with RAO loading
Vessel type management

When to Use

Creating new vessels in OrcaFlex models
Configuring 6-DOF motion properties
Importing vessel hydrodynamics from AQWA
Setting up vessel calculation options
Defining vessel types with RAO data
Configuring drift, damping, and wave loads

Vessel Configuration Components

Vessel Object

| Property | Description | Units | |----------|-------------|-------| | Name | Unique vessel identifier | - | | VesselType | Reference to vessel type | - | | Draught | Operating draft | m | | InitialPosition | X, Y, Z coordinates | m | | Orientation | Heading angle | deg | | Connection | Connection point type | - |

Vessel Type

| Property | Description | Units | |----------|-------------|-------| | Name | Type identifier | - | | Length | Reference length | m | | DisplacementRAOs | Motion response operators | m/m, deg/m | | LoadRAOs | Force response operators | kN/m | | StiffnessAddedMassDamping | Hydrodynamic coefficients | - | | QTFs | Quadratic Transfer Functions | - |

Configuration

Basic Vessel Configuration

# configs/vessel_config.yml

vessel:
  name: "FPSO"
  vessel_type: "FPSO_Type"

  # Position and orientation
  initial_position:
    x: 0.0      # m
    y: 0.0      # m
    z: 0.0      # m (relative to sea surface)

  orientation: 0.0    # deg (heading)
  draught: 15.5       # m

  # Calculation settings
  calculation:
    include_applied_loads: "6 DOF"
    primary_motion: "6 DOF calculated (no wave load RAOs)"
    superimposed_motion: "None"

    # Wave load options
    wave_load: "Calculated from RAOs (first order)"
    drift_load: "Calculated from QTFs"

    # Environmental loads
    current_load: "Calculated"
    wind_load: "Calculated"

    # Damping
    damping_calculation: "From hydrodynamic database"

vessel_type:
  name: "FPSO_Type"
  length: 300.0        # m

  # RAO data source
  hydrodynamic_data:
    source: "aqwa"     # or "orcaflex", "csv"
    file: "data/fpso_aqwa.lis"

  # RAO import settings
  rao_import:
    displacement_raos: true
    load_raos: true
    stiffness_added_mass_damping: true
    qtfs: true
    qtf_type: "Full"   # or "Newman"

AQWA Import Configuration

# configs/aqwa_vessel_import.yml

aqwa_import:
  # Source file
  source_file: "data/vessel_aqwa.lis"

  # Body mapping (for multi-body systems)
  body_mapping:
    - aqwa_body: 1
      orcaflex_vessel: "FPSO"
    - aqwa_body: 2
      orcaflex_vessel: "Shuttle_Tanker"

  # Data to import
  import_data:
    displacement_raos: true
    load_raos: true
    added_mass: true
    damping: true
    stiffness: true
    qtfs:
      enabled: true
      type: "Full"     # Full or Newman approximation

  # RAO conventions
  conventions:
    frequency_units: "rad/s"
    phase_convention: "OrcaFlex"   # Check AQWA vs OrcaFlex sign

Python API

Basic Vessel Creation

from digitalmodel.modules.fea_model.Vessel_components import Vessel
from digitalmodel.modules.fea_model.VesselType_components import VesselType

def create_vessel(config: dict) -> dict:
    """
    Create OrcaFlex vessel configuration.

    Args:
        config: Vessel configuration dictionary

    Returns:
        OrcaFlex-ready vessel properties
    """
    # Create vessel type
    vessel_type = VesselType(
        name=config["vessel_type"]["name"],
        length=config["vessel_type"]["length"]
    )

    # Create vessel object
    vessel = Vessel(
        name=config["vessel"]["name"],
        vessel_type=vessel_type.name,
        draught=config["vessel"]["draught"]
    )

    # Set position
    vessel.set_initial_position(
        x=config["vessel"]["initial_position"]["x"],
        y=config["vessel"]["initial_position"]["y"],
        z=config["vessel"]["initial_position"]["z"]
    )

    # Set orientation
    vessel.set_orientation(config["vessel"]["orientation"])

    # Get OrcaFlex properties
    return vessel.get_orcaflex_properties()

# Example usage
config = {
    "vessel": {
        "name": "FPSO",
        "draught": 15.5,
        "initial_position": {"x": 0, "y": 0, "z": 0},
        "orientation": 0.0
    },
    "vessel_type": {
        "name": "FPSO_Type",
        "length": 300.0
    }
}

vessel_props = create_vessel(config)

AQWA Vessel Import

from digitalmodel.modules.fea_model.preprocess.load_vessel import LoadVessel
import OrcFxAPI

def import_vessel_from_aqwa(
    model: OrcFxAPI.Model,
    aqwa_file: str,
    vessel_name: str,
    import_config: dict = None
) -> OrcFxAPI.OrcaFlexObject:
    """
    Import vessel hydrodynamics from AQWA.

    Args:
        model: OrcaFlex model
        aqwa_file: Path to AQWA .lis file
        vessel_name: Name for the vessel type
        import_config: Optional import settings

    Returns:
        OrcaFlex vessel type object
    """
    # Default import settings
    if import_config is None:
        import_config = {
            "displacement_raos": True,
            "load_raos": True,
            "stiffness_added_mass_damping": True,
            "qtfs": True,
            "qtf_type": "Full"
        }

    # Create vessel type
    vessel_type = model.CreateObject(OrcFxAPI.otVesselType, vessel_name)

    # Configure data import
    vessel_type.DisplacementRAOs = OrcFxAPI.vdtLoadRAOs
    vessel_type.LoadRAOs = OrcFxAPI.vdtLoadRAOs

    if import_config.get("stiffness_added_mass_damping"):
        vessel_type.StiffnessAddedMassDamping = OrcFxAPI.vdtStiffnessAddedMassDamping

    # Set import file
    vessel_type.ImportFile = aqwa_file

    # Configure QTF import
    if import_config.get("qtfs"):
        if import_config.get("qtf_type") == "Full":
            vessel_type.FullQTFImportMethod = OrcFxAPI.fqimFromFile
        else:
            vessel_type.NewmanApproximation = True

    # Execute import
    vessel_type.ImportHydrodynamicData()

    return vessel_type

# Example usage
model = OrcFxAPI.Model()
vessel_type = import_vessel_from_aqwa(
    model=model,
    aqwa_file="data/fpso_aqwa.lis",
    vessel_name="FPSO_Type"
)

print(f"Imported vessel type: {vessel_type.Name}")

Vessel Calculation Settings

import OrcFxAPI

def configure_vessel_calculations(
    vessel: OrcFxAPI.OrcaFlexObject,
    settings: dict
) -> None:
    """
    Configure vessel calculation options.

    Args:
        vessel: OrcaFlex vessel object
        settings: Calculation settings dictionary
    """
    # Primary motion
    motion_map = {
        "6 DOF calculated": OrcFxAPI.vmCalculated,
        "6 DOF calculated (no wave load RAOs)": OrcFxAPI.vmCalculatedNoRAO,
        "Prescribed": OrcFxAPI.vmPrescribed,
        "None": OrcFxAPI.vmNone
    }
    vessel.PrimaryMotion = motion_map.get(
        settings.get("primary_motion", "6 DOF calculated"),
        OrcFxAPI.vmCalculated
    )

    # Wave loads
    wave_load_map = {
        "Calculated from RAOs (first order)": OrcFxAPI.wlCalculatedFromRAOs,
        "Calculated (full hydrodynamic)": OrcFxAPI.wlCalculated,
        "None": OrcFxAPI.wlNone
    }
    vessel.IncludeWaveLoad = wave_load_map.get(
        settings.get("wave_load", "Calculated from RAOs (first order)"),
        OrcFxAPI.wlCalculatedFromRAOs
    )

    # Drift loads
    drift_load_map = {
        "Calculated from QTFs": OrcFxAPI.dlCalculatedFromQTFs,
        "Newman approximation": OrcFxAPI.dlNewmanApproximation,
        "None": OrcFxAPI.dlNone
    }
    vessel.IncludeDriftLoad = drift_load_map.get(
        settings.get("drift_load", "None"),
        OrcFxAPI.dlNone
    )

    # Current load
    vessel.IncludeCurrentLoad = settings.get("current_load", True)

    # Wind load
    vessel.IncludeWindLoad = settings.get("wind_load", True)

# Example usage
vessel = model["FPSO"]
configure_vessel_calculations(vessel, {
    "primary_motion": "6 DOF calculated",
    "wave_load": "Calculated from RAOs (first order)",
    "drift_load": "Calculated from QTFs",
    "current_load": True,
    "wind_load": True
})

Multi-Body Import

import OrcFxAPI

def import_multi_body_system(
    model: OrcFxAPI.Model,
    aqwa_file: str,
    body_mapping: list
) -> dict:
    """
    Import multi-body system from AQWA.

    Args:
        model: OrcaFlex model
        aqwa_file: Path to AQWA .lis file
        body_mapping: List of {aqwa_body: int, orcaflex_vessel: str}

    Returns:
        Dictionary of vessel type objects
    """
    vessel_types = {}

    for mapping in body_mapping:
        aqwa_body = mapping["aqwa_body"]
        vessel_name = mapping["orcaflex_vessel"]

        # Create vessel type
        vessel_type = model.CreateObject(
            OrcFxAPI.otVesselType,
            f"{vessel_name}_Type"
        )

        # Configure body map
        body_map = OrcFxAPI.VesselTypeDataDiffractionImportBodyMap()
        body_map.AQWABody = aqwa_body
        body_map.OrcaFlexVesselType = vessel_type

        # Set import file and body mapping
        vessel_type.ImportFile = aqwa_file
        vessel_type.DiffractionImportBodyMap = [body_map]

        # Import data
        vessel_type.ImportHydrodynamicData()

        vessel_types[vessel_name] = vessel_type

    return vessel_types

# Example: FPSO + Shuttle Tanker system
body_mapping = [
    {"aqwa_body": 1, "orcaflex_vessel": "FPSO"},
    {"aqwa_body": 2, "orcaflex_vessel": "Shuttle_Tanker"}
]

vessel_types = import_multi_body_system(
    model=model,
    aqwa_file="data/multi_body_aqwa.lis",
    body_mapping=body_mapping
)

Output Formats

Vessel Properties YAML

Vessels:
  - Name: FPSO
    VesselType: FPSO_Type
    Draught: 15.5
    Connection: Free
    InitialPosition: [0.0, 0.0, 0.0]
    InitialHeading: 0.0

    Calculation:
      PrimaryMotion: 6 DOF calculated
      SuperimposedMotion: None
      IncludeWaveLoad: Calculated from RAOs (first order)
      IncludeDriftLoad: Calculated from QTFs
      IncludeCurrentLoad: Yes
      IncludeWindLoad: Yes

VesselTypes:
  - Name: FPSO_Type
    Length: 300.0
    DisplacementRAOs: Imported from file
    LoadRAOs: Imported from file
    StiffnessAddedMassDamping: Imported from file
    QTFs: Full QTFs from file

Common Use Cases

1. FPSO with AQWA Hydrodynamics

# Import FPSO hydrodynamics from AQWA
vessel_type = import_vessel_from_aqwa(
    model=model,
    aqwa_file="fpso_aqwa.lis",
    vessel_name="FPSO_Type",
    import_config={
        "displacement_raos": True,
        "load_raos": True,
        "qtfs": True,
        "qtf_type": "Full"
    }
)

# Create vessel using the type
vessel = model.CreateObject(OrcFxAPI.otVessel, "FPSO")
vessel.VesselType = "FPSO_Type"
vessel.Draught = 22.5
vessel.InitialPosition = [0, 0, 0]

2. Shuttle Tanker Approach

# Shuttle tanker at offset position
vessel = model.CreateObject(OrcFxAPI.otVessel, "Shuttle_Tanker")
vessel.VesselType = "Shuttle_Type"
vessel.InitialPosition = [80, 0, 0]  # 80m offset from FPSO
vessel.InitialHeading = 180  # Stern-to-stern

3. Barge for Installation

# Installation barge
vessel = model.CreateObject(OrcFxAPI.otVessel, "Installation_Barge")
vessel.VesselType = "Barge_Type"
vessel.PrimaryMotion = OrcFxAPI.vmPrescribed  # Follow prescribed motion

Best Practices

Data Import

Verify AQWA output - Check analysis completed successfully
Check sign conventions - AQWA vs OrcaFlex phase conventions
Validate RAO magnitudes - Compare with expected responses
Test at single frequency - Verify motion response

Vessel Configuration

Correct draught - Match analysis loading condition
Coordinate system - Align with AQWA body axes
Connection point - Set appropriate attachment
Calculation options - Match analysis requirements

Multi-Body Systems

Body mapping - Match AQWA body numbers
Coupling terms - Include hydrodynamic interaction
Connection constraints - Link vessels appropriately

Error Handling

try:
    vessel_type = import_vessel_from_aqwa(model, aqwa_file, "Vessel_Type")
except OrcFxAPI.OrcaFlexError as e:
    print(f"Import failed: {e}")
    print("Check AQWA file path and format")

except FileNotFoundError:
    print("AQWA file not found")

except ValueError as e:
    print(f"Configuration error: {e}")

Related Skills

orcaflex-modeling - Run OrcaFlex simulations
orcaflex-rao-import - RAO data import
aqwa-analysis - AQWA analysis
hydrodynamics - Hydrodynamic coefficients

References

OrcaFlex: Vessel Type Data
OrcaFlex: Importing Hydrodynamic Data
ANSYS AQWA: Output File Format
Source: src/digitalmodel/modules/fea_model/Vessel_components.py
Source: src/digitalmodel/modules/fea_model/VesselType_components.py
Source: src/digitalmodel/modules/fea_model/preprocess/load_vessel.py