Diffraction Analysis Master Skill

Overview

This skill provides guidance on hydrodynamic diffraction/radiation analysis using the available modules in digitalmodel. Three primary modules handle different aspects of the workflow:

| Module | Purpose | Primary Use Case | |--------|---------|------------------| | aqwa | Native AQWA analysis | Direct AQWA .LIS file processing | | orcawave | OrcaWave diffraction | OrcaFlex-integrated analysis | | bemrosetta | Format conversion | AQWA → OrcaFlex workflow, mesh conversion | | diffraction | Unified schemas | Data structures and comparison framework |

Version

Skill Version: 1.0.0
Updated: 2026-01-27
Category: Offshore Engineering

Module Comparison

When to Use Each Module

| Scenario | Recommended Module | Reason | |----------|-------------------|--------| | Parse AQWA .LIS files | aqwa or bemrosetta | Native parsing, no external dependencies | | Run OrcaWave analysis | orcawave | Direct OrcaFlex API integration | | Convert AQWA → OrcaFlex | bemrosetta | Purpose-built converter with validation | | Compare AQWA vs OrcaWave | diffraction | Unified schema comparison framework | | Handle QTF data | bemrosetta | QTF parser and OrcaFlex export | | Convert mesh formats | bemrosetta | GDF/DAT/STL conversion | | Store/retrieve coefficients | hydrodynamics | Coefficient database |

Feature Matrix

| Feature | aqwa | orcawave | bemrosetta | diffraction | |---------|------|----------|------------|-------------| | Parse AQWA .LIS | ✅ | ❌ | ✅ | ✅ (via converter) | | Parse OrcaWave | ❌ | ✅ | ❌ | ✅ (via converter) | | RAO extraction | ✅ | ✅ | ✅ | ✅ | | Added mass/damping | ✅ | ✅ | ✅ | ✅ | | QTF (2nd order) | ❌ | ✅ | ✅ | ❌ | | Export to OrcaFlex | ❌ | Native | ✅ | ✅ | | Mesh conversion | ❌ | ❌ | ✅ | ❌ | | Coefficient validation | ❌ | ❌ | ✅ | ✅ | | Comparison framework | ❌ | ❌ | ❌ | ✅ |

Unified Data Schema

All modules use the unified schema from diffraction.output_schemas:

from digitalmodel.modules.diffraction import (
    DiffractionResults,  # Complete analysis container
    RAOSet, RAOComponent, # RAO data structures
    AddedMassSet, DampingSet,  # Coefficient matrices
    HydrodynamicMatrix,  # 6×6 frequency-dependent matrix
    FrequencyData, HeadingData,  # Discretization
    DOF, Unit,  # Enumerations
)

DiffractionResults Structure

DiffractionResults
├── vessel_name: str
├── frequencies: FrequencyData
├── headings: HeadingData
├── raos: RAOSet
│   ├── surge: RAOComponent (magnitude, phase)
│   ├── sway: RAOComponent
│   ├── heave: RAOComponent
│   ├── roll: RAOComponent
│   ├── pitch: RAOComponent
│   └── yaw: RAOComponent
├── added_mass: AddedMassSet
│   └── matrices: List[HydrodynamicMatrix]  # 6×6 per frequency
├── damping: DampingSet
│   └── matrices: List[HydrodynamicMatrix]
└── source_file: str

Typical Workflows

Workflow 1: AQWA Analysis Only

from digitalmodel.modules.aqwa import AQWAAnalysis

# Direct AQWA analysis
analysis = AQWAAnalysis(folder="aqwa_results/")
analysis.run()

Workflow 2: AQWA → OrcaFlex Conversion

from digitalmodel.modules.bemrosetta import (
    AQWAParser, OrcaFlexConverter, validate_coefficients
)

# Parse AQWA
parser = AQWAParser()
results = parser.parse("analysis.LIS")

# Validate
report = validate_coefficients(results)
if report.is_valid:
    # Convert to OrcaFlex
    converter = OrcaFlexConverter(output_dir="./orcaflex")
    converter.convert(results)

Workflow 3: OrcaWave Analysis

from digitalmodel.modules.orcawave import OrcaWaveAnalysis

# Run OrcaWave (requires OrcFxAPI)
analysis = OrcaWaveAnalysis()
analysis.setup_model(vessel_file="vessel.yml")
analysis.run_diffraction()
results = analysis.get_results()

Workflow 4: AQWA vs OrcaWave Comparison

from digitalmodel.modules.diffraction import (
    DiffractionComparator,
    AQWAConverter,
    OrcaWaveConverter,
)

# Convert both sources to unified schema
aqwa_results = AQWAConverter("aqwa_folder/").convert_to_unified_schema()
orcawave_results = OrcaWaveConverter(model).convert_to_unified_schema()

# Compare
comparator = DiffractionComparator()
report = comparator.compare(aqwa_results, orcawave_results)
print(f"RAO match: {report.rao_match_percentage:.1f}%")

Workflow 5: Complete Pipeline with QTF

from digitalmodel.modules.bemrosetta import (
    AQWAParser, QTFParser, OrcaFlexConverter,
    CoefficientValidator, CausalityChecker,
)

# Parse main results
parser = AQWAParser()
results = parser.parse("analysis.LIS")

# Parse QTF
qtf_parser = QTFParser()
qtf_data = qtf_parser.parse("analysis.QTF")

# Validate
coef_validator = CoefficientValidator(check_symmetry=True)
coef_report = coef_validator.validate(results)

causality_checker = CausalityChecker()
kk_report = causality_checker.validate(results)

# Convert with QTF
converter = OrcaFlexConverter(output_dir="./output")
converter.set_qtf_data(qtf_data)
converter.convert(results)

CLI Commands

AQWA Module

# (Uses existing AQWA CLI if available)

BEMRosetta Module

bemrosetta convert analysis.LIS -o ./output
bemrosetta convert analysis.LIS --qtf analysis.QTF -o ./output
bemrosetta info analysis.LIS
bemrosetta validate analysis.LIS --strict --causality
bemrosetta convert-mesh hull.gdf -o hull.stl
bemrosetta status

Diffraction Module

# Batch processing
python -m digitalmodel.modules.diffraction.batch_processor config.yml

Output Formats

OrcaFlex Vessel Type YAML

VesselType:
  Name: FPSO
  Category: Vessel
  PrimaryMotion: Calculated (6 DOF)
  RAOOrigin: [0, 0, 0]
  RAOPhaseConvention: AQWA

Coefficient CSV

Frequency_rad/s,A11,A12,A13,A14,A15,A16,...
0.3,1.0e7,0.0,0.0,0.0,0.0,0.0,...
0.4,1.1e7,0.0,0.0,0.0,0.0,0.0,...

QTF CSV

Freq1_rad/s,Freq2_rad/s,Heading_deg,Surge_Re,Surge_Im,...
0.3,0.3,0.0,1.2e5,0.0,...

Validation Criteria

Coefficient Validation

Symmetry: Added mass and damping matrices should be symmetric
Positive definiteness: Diagonal elements non-negative
Physical limits: No NaN/Inf values, reasonable magnitudes

Kramers-Kronig Causality

Added mass A(ω) and damping B(ω) must satisfy K-K relations
Tolerance: typically 10% relative error acceptable

RAO Validation

Magnitude non-negative
Phase in reasonable range (-360° to 360°)
Physical trends (heave RAO → 1.0 at low frequency)

Best Practices

Always validate coefficients before using in OrcaFlex
Check K-K causality for added mass/damping consistency
Compare results when both AQWA and OrcaWave are available
Use unified schema for interoperability
Document water depth and frequency range assumptions

Related Skills

| Skill | Description | |-------|-------------| | aqwa-analysis | AQWA .LIS processing and RAO extraction | | orcawave-analysis | OrcaWave diffraction/radiation analysis | | bemrosetta | AQWA → OrcaFlex converter with QTF support | | hydrodynamics | 6×6 matrices, wave spectra, OCIMF loading | | orcaflex-rao-import | Multi-format RAO import to OrcaFlex | | orcawave-to-orcaflex | OrcaWave to OrcaFlex conversion | | orcawave-aqwa-benchmark | Cross-validation comparison |

Module Locations

src/digitalmodel/modules/
├── aqwa/                    # AQWA analysis tools
├── orcawave/                # OrcaWave analysis
├── bemrosetta/              # Format conversion
│   ├── parsers/             # AQWA, QTF parsers
│   ├── converters/          # OrcaFlex export
│   ├── mesh/                # GDF, DAT, STL handlers
│   └── validators/          # Coefficient, causality
├── diffraction/             # Unified schemas
│   ├── output_schemas.py    # DiffractionResults
│   ├── aqwa_converter.py    # AQWA to unified
│   ├── orcawave_converter.py # OrcaWave to unified
│   ├── orcaflex_exporter.py # Export to OrcaFlex
│   └── comparison_framework.py # Compare results
└── hydrodynamics/           # Coefficient database

References

OrcaFlex Documentation: https://www.orcina.com/webhelp/OrcaFlex/
WAMIT Manual: https://www.wamit.com/manual.htm
BEMRosetta: https://github.com/BEMRosetta/BEMRosetta