Collection

---
name: aqwa-analysis
description: Integrate with AQWA hydrodynamic software for RAO computation, damping analysis, and coefficient extraction. Use for AQWA file processing, RAO calculation, hydrodynamic coefficient extraction, and pre/post processing workflows.
---

# 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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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

| Class | Purpose |
|-------|---------|
| `AqwaAnalysis` | Main analysis router |
| `AqwaRAOs` | RAO computation and export |
| `AqwaReader` | File parsing (LIS, DAT, MES) |
| `AqwaPreProcess` | Input file generation |
| `AqwaPostProcess` | Results post-processing |
| `AqwaValidator` | Result validation |

## 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

```yaml
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

```csv
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

```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

```python
# 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

```python
# 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](../hydrodynamics/SKILL.md) - Coefficient management
- [orcaflex-modeling](../orcaflex-modeling/SKILL.md) - Apply RAOs in OrcaFlex
- [mooring-design](../mooring-design/SKILL.md) - Vessel motion input

## References

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