AQWA Analysis Skill

AQWA Analysis Skill

Integrate with ANSYS AQWA hydrodynamic software for RAO computation, added mass/​damping extraction, and hydrodynamic coefficient management.

When to Use

• AQWA hydrodynamic analysis post-processing
• RAO (Response Amplitude Operator) computation
• Hydrodynamic coefficient extraction
• AQWA file processing (LIS, DAT, MES)
• Added mass and damping matrix extraction
• Viscous damping determination
• Pre/​post processing workflows

Prerequisites

• Python environment with digitalmodel package installed
• AQWA output files (LIS, DAT, or MES format)
• For running AQWA: ANSYS AQWA license

Analysis Types

1. RAO Extraction

Extract RAOs from AQWA results.

aqwa_analysis:
  rao_extraction:
    flag: true
    input_file: "aqwa_results/​vessel.LIS"
    vessel_name: "FPSO"
    wave_directions: [0, 45, 90, 135, 180]
    output:
      rao_file: "results/​vessel_raos.csv"
      plot_file: "results/​rao_plots.html"
      format: "amplitude_phase"  # or real_imaginary

2. Hydrodynamic Coefficients

Extract added mass and damping matrices.

aqwa_analysis:
  coefficients:
    flag: true
    input_file: "aqwa_results/​vessel.LIS"
    frequencies: "all"  # or specific list [0.1, 0.2, 0.3]
    output:
      added_mass_file: "results/​added_mass.csv"
      damping_file: "results/​damping.csv"
      matrices_file: "results/​hydro_matrices.json"

3. AQWA File Processing

Parse and process AQWA output files.

aqwa_analysis:
  file_processing:
    flag: true
    files:
      - path: "aqwa_results/​vessel.LIS"
        type: "lis"
      - path: "aqwa_results/​vessel.DAT"
        type: "dat"
    extract:
      - "raos"
      - "added_mass"
      - "damping"
      - "wave_forces"
      - "drift_forces"
    output_directory: "results/​aqwa_processed/"

4. Viscous Damping

Determine viscous damping from decay tests or empirical methods.

aqwa_analysis:
  viscous_damping:
    flag: true
    method: "empirical"  # or decay_test
    vessel:
      length: 300.0
      beam: 50.0
      draft: 20.0
    motions: ["roll", "pitch", "heave"]
    empirical_factors:
      roll_percentage: 5.0   # % of critical
      pitch_percentage: 3.0
      heave_percentage: 2.0
    output:
      damping_file: "results/​viscous_damping.json"

Python API

RAO Extraction

from digitalmodel.modules.aqwa.aqwa_raos import AqwaRAOs

# Initialize RAO extractor
raos = AqwaRAOs()

# Load AQWA results
raos.load("aqwa_results/​vessel.LIS")

# Get RAO for specific motion and direction
surge_rao = raos.get_rao(
    motion="surge",
    wave_direction=180.0  # degrees (head seas)
)

# Get all RAOs as DataFrame
rao_df = raos.to_dataframe()
# Columns: frequency, direction, surge_amp, surge_phase, sway_amp, ...

# Plot RAOs
raos.plot_rao(
    motions=["heave", "pitch", "roll"],
    directions=[0, 90, 180],
    output_file="results/​rao_comparison.html"
)

# Export to OrcaFlex format
raos.export_orcaflex("vessel_raos.yml")

Hydrodynamic Coefficient Extraction

from digitalmodel.modules.aqwa.aqwa_reader import AqwaReader
from digitalmodel.modules.aqwa.aqwa_analysis import AqwaAnalysis

# Initialize reader
reader = AqwaReader()

# Load AQWA output
data = reader.read("aqwa_results/​vessel.LIS")

# Get added mass matrix at specific frequency
frequency = 0.1  # rad/​s
added_mass = data.get_added_mass(frequency)
# Returns 6x6 numpy array

# Get damping matrix
damping = data.get_damping(frequency)
# Returns 6x6 numpy array

# Get frequency-dependent matrices
frequencies = data.get_frequencies()
for freq in frequencies:
    A = data.get_added_mass(freq)
    B = data.get_damping(freq)
    print(f"ω = {freq:.3f}: A33 = {A[2,2]:.1f}, B33 = {B[2,2]:.1f}")

AQWA Analysis Router

from digitalmodel.modules.aqwa.aqwa_analysis import AqwaAnalysis

# Initialize analysis
aqwa = AqwaAnalysis()

# Configure analysis
cfg = {
    "aqwa": {
        "input_file": "aqwa_results/​vessel.LIS",
        "extract": ["raos", "added_mass", "damping", "drift_forces"],
        "output_directory": "results/"
    }
}

# Run extraction
results = aqwa.run(cfg)

# Access results
raos = results["raos"]
added_mass = results["added_mass"]
damping = results["damping"]
drift = results["drift_forces"]

Pre-Processing

from digitalmodel.modules.aqwa.aqwa_preprocess import AqwaPreProcess

# Initialize pre-processor
preprocess = AqwaPreProcess()

# Generate AQWA input from vessel geometry
preprocess.generate_input(
    vessel_geometry="geometry/​hull.stl",
    water_depth=1000.0,
    wave_frequencies=[0.05, 0.1, 0.15, 0.2, 0.3, 0.5, 0.8, 1.0],
    wave_directions=[0, 45, 90, 135, 180],
    output_file="aqwa_input/​vessel.dat"
)

Post-Processing

from digitalmodel.modules.aqwa.aqwa_postprocess import AqwaPostProcess

# Initialize post-processor
postprocess = AqwaPostProcess()

# Load results
postprocess.load("aqwa_results/​vessel.LIS")

# Generate comprehensive report
postprocess.generate_report(
    output_file="results/​aqwa_report.html",
    include=[
        "summary",
        "rao_plots",
        "coefficient_tables",
        "drift_force_plots"
    ]
)

# Validate results
validation = postprocess.validate()
if validation["warnings"]:
    for warning in validation["warnings"]:
        print(f"Warning: {warning}")

Result Validation

from digitalmodel.modules.aqwa.aqwa_validator import AqwaValidator

# Initialize validator
validator = AqwaValidator()

# Load results
validator.load("aqwa_results/​vessel.LIS")

# Run validation checks
results = validator.validate()

# Check for common issues
if not results["symmetry_check"]:
    print("Warning: RAOs not symmetric for symmetric vessel")
if not results["low_frequency_check"]:
    print("Warning: Low frequency added mass may be inaccurate")
if not results["radiation_check"]:
    print("Warning: Radiation damping check failed")

# Kramers-Kronig causality check
kk_result = validator.kramers_kronig_check()
if not kk_result["passed"]:
    print(f"Causality violation at frequencies: {kk_result['violations']}")

Key Classes

File Format Support

LIS Files (Listing Output)

Primary output file containing:

• RAOs (amplitude and phase)
• Added mass matrices
• Damping matrices
• Wave excitation forces
• Drift forces

DAT Files (Data Input)

Input file containing:

• Hull geometry
• Mass properties
• Analysis settings
• Wave conditions

MES Files (Mesh)

Mesh definition:

• Panel geometry
• Node coordinates
• Panel connectivity

Configuration Examples

Complete AQWA Workflow

basename: aqwa_analysis

aqwa_analysis:
  # Step 1: Process AQWA output
  file_processing:
    flag: true
    input_file: "aqwa_results/​fpso.LIS"
    output_directory: "results/"

  # Step 2: Extract RAOs
  rao_extraction:
    flag: true
    wave_directions: [0, 30, 60, 90, 120, 150, 180]
    output:
      rao_file: "results/​fpso_raos.csv"
      orcaflex_file: "results/​fpso_raos.yml"
      plots: "results/​rao_plots.html"

  # Step 3: Extract coefficients
  coefficients:
    flag: true
    output:
      added_mass: "results/​added_mass.csv"
      damping: "results/​damping.csv"

  # Step 4: Add viscous damping
  viscous_damping:
    flag: true
    method: "percentage_critical"
    values:
      roll: 5.0
      pitch: 3.0
      heave: 2.0

  # Step 5: Validate results
  validation:
    flag: true
    checks:
      - symmetry
      - low_frequency
      - kramers_kronig
    output:
      report: "results/​validation_report.json"

Output Formats

RAO CSV Format

frequency_rad_s,direction_deg,surge_amp,surge_phase,sway_amp,sway_phase,heave_amp,heave_phase,roll_amp,roll_phase,pitch_amp,pitch_phase,yaw_amp,yaw_phase
0.100,0.0,0.985,178.2,0.000,0.0,1.023,-2.5,0.000,0.0,0.156,175.8,0.000,0.0
0.100,90.0,0.000,0.0,0.978,175.4,1.015,-3.2,2.345,-8.5,0.000,0.0,0.012,92.1

Coefficient Matrices JSON

{
  "frequencies_rad_s": [0.1, 0.2, 0.3, 0.5, 0.8],
  "added_mass": {
    "0.1": [[1.2e6, 0, 0, 0, 1.5e7, 0],
            [0, 1.3e6, 0, -1.2e7, 0, 0],
            ...],
    "0.2": [...]
  },
  "damping": {
    "0.1": [[2.5e5, 0, 0, 0, 3.2e6, 0],
            ...],
    "0.2": [...]
  }
}

Best Practices

1. Frequency range - Ensure frequencies cover wave spectrum of interest
2. Direction resolution - Use 30° or finer for asymmetric vessels
3. Panel density - Verify mesh convergence for accurate results
4. Low frequency - Check added mass at low frequencies for stability
5. Viscous damping - Always add viscous damping for roll motion

Common Issues

Mesh Quality

# Check mesh quality before running
from digitalmodel.modules.aqwa.mesh_check import AqwaMeshCheck

mesh = AqwaMeshCheck()
mesh.load("geometry/​hull.mes")
quality = mesh.check_quality()

if quality["min_aspect_ratio"] < 0.1:
    print("Warning: Poor aspect ratio panels detected")
if quality["intersecting_panels"] > 0:
    print(f"Error: {quality['intersecting_panels']} intersecting panels")

Result Validation

# Always validate extracted coefficients
validator = AqwaValidator()
validator.load("results/​vessel.LIS")

# Check physical consistency
if not validator.check_positive_definite_damping():
    print("Warning: Damping matrix not positive definite")

if not validator.check_symmetric_added_mass():
    print("Warning: Added mass matrix not symmetric")

Related Skills

• hydrodynamics - Coefficient management
• orcaflex-modeling - Apply RAOs in OrcaFlex
• mooring-design - Vessel motion input

References

• ANSYS AQWA User Manual
• DNV-RP-C205: Environmental Conditions and Environmental Loads
• Newman, J.N.: Marine Hydrodynamics