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:

python

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

python

from digitalmodel.modules.aqwa import AQWAAnalysis

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

Workflow 2: AQWA → OrcaFlex Conversion

python

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

python

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

python

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

python

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

bash

# (Uses existing AQWA CLI if available)

BEMRosetta Module

bash

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

bash

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

Output Formats

OrcaFlex Vessel Type YAML

yaml

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

Coefficient CSV

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

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

Search AI Tools

diffraction-analysis

Install this agent skill to your Project

SKILL.md

Diffraction Analysis Master Skill

Overview

Version

Module Comparison

When to Use Each Module

Feature Matrix

Unified Data Schema

DiffractionResults Structure

Typical Workflows

Workflow 1: AQWA Analysis Only

Workflow 2: AQWA → OrcaFlex Conversion

Workflow 3: OrcaWave Analysis

Workflow 4: AQWA vs OrcaWave Comparison

Workflow 5: Complete Pipeline with QTF

CLI Commands

AQWA Module

BEMRosetta Module

Diffraction Module

Output Formats

OrcaFlex Vessel Type YAML

Coefficient CSV

QTF CSV

Validation Criteria

Coefficient Validation

Kramers-Kronig Causality

RAO Validation

Best Practices

Related Skills

Module Locations

References