yaml-configuration

What this skill does

# YAML Configuration Management Skill

Master YAML for configuration-driven engineering workflows, enabling reproducible analyses and automated model generation.

## When to Use This Skill

Use YAML configuration when you need:
- **Configuration-driven workflows** - Separate data from code
- **Reproducible analyses** - Version-controlled parameters
- **Model templates** - Reusable configurations
- **Complex nested structures** - Hierarchical data organization
- **Human-readable configs** - Easy to review and modify
- **Automated model generation** - OrcaFlex, FEA, CAD models

**Avoid when:**
- Binary data needed (use pickle, HDF5)
- Extremely large datasets (use CSV, databases)
- Real-time performance critical (use JSON)

## Core Capabilities

### 1. Basic YAML Syntax

**Scalars:**
```yaml
# Strings
project_name: "FPSO Mooring Analysis"
description: Simple mooring system

# Numbers
water_depth: 1500        # Integer
wave_height: 8.5         # Float
scientific: 1.5e-3       # Scientific notation

# Booleans
include_current: true
dynamic_analysis: false

# Null values
optional_parameter: null
# or
optional_parameter: ~
```

**Lists:**
```yaml
# Inline list
mooring_lines: [1, 2, 3, 4, 5, 6]

# Block list
vessel_types:
  - FPSO
  - Semi-submersible
  - TLP
  - SPAR

# List of dictionaries
load_cases:
  - name: "Operating"
    Hs: 4.5
    Tp: 10.0
  - name: "Storm"
    Hs: 8.5
    Tp: 12.0
```

**Dictionaries:**
```yaml
# Nested dictionaries
vessel:
  name: "FPSO Vessel"
  dimensions:
    length: 320
    beam: 58
    draft: 22
  mass_properties:
    displacement: 150000
    lcg: 160
    vcg: 15
```

### 2. Advanced Features

**Anchors and Aliases (Reuse):**
```yaml
# Define anchor
default_material: &steel
  name: "Steel"
  density: 7850
  youngs_modulus: 200e9

# Reuse with alias
chain_material: *steel

mooring_line:
  material: *steel  # References same data

# Merge keys
base_config: &base
  version: 1.0
  author: "Engineering Team"

analysis_1:
  <<: *base  # Merge base_config
  name: "Analysis 1"
  parameters:
    duration: 3600

analysis_2:
  <<: *base  # Merge base_config
  name: "Analysis 2"
  parameters:
    duration: 7200
```

**Multi-line Strings:**
```yaml
# Preserve newlines (literal style)
description: |
  This is a multi-line string.
  Newlines are preserved.
  Use for comments or descriptions.

# Fold newlines (folded style)
notes: >
  This string will have
  newlines replaced with spaces,
  except for blank lines.

  This starts a new paragraph.
```

**Comments:**
```yaml
# This is a comment
project: "Mooring Analysis"  # Inline comment

# Comments for documentation
vessel:
  # Main dimensions
  length: 320  # meters
  beam: 58     # meters
```

## Complete Examples

### Example 1: OrcaFlex Mooring Configuration

```yaml
# config/mooring_analysis.yaml
---
metadata:
  analysis_name: "FPSO Mooring System"
  analysis_type: "dynamic_mooring"
  created: "2026-01-06"
  author: "Marine Engineering Team"
  version: 1.0

environment:
  water_depth: 1500  # meters
  wave:
    type: "JONSWAP"
    Hs: 8.5  # meters
    Tp: 12.0  # seconds
    gamma: 3.3
    direction: 0  # degrees
  current:
    surface_speed: 1.2  # m/s
    direction: 0  # degrees
    profile: "linear"  # or "power_law"
  wind:
    speed: 25  # m/s
    direction: 0  # degrees

vessel:
  name: "FPSO_Model"
  type: "Vessel"
  dimensions:
    length: 320  # meters
    beam: 58
    draft: 22
  mass_properties:
    mass: 150000  # tonnes
    lcg: 160  # from aft perpendicular
    vcg: 15  # from keel
    radii_of_gyration:
      roll: 22
      pitch: 95
      yaw: 95

mooring_system:
  configuration: "spread"  # or "turret"
  number_of_lines: 12
  lines:
    - name: "Line_1"
      type: "chain_wire_chain"
      azimuth: 0  # degrees
      segments:
        - type: "chain"
          length: 500
          diameter: 127  # mm
          grade: "R4"
        - type: "wire"
          length: 1000
          diameter: 120  # mm
        - type: "chain"
          length: 500
          diameter: 127  # mm
      anchor:
        type: "drag_embedment"
        capacity: 5000  # kN
    - name: "Line_2"
      type: "chain_wire_chain"
      azimuth: 30
      # ... similar structure

  pretension:
    method: "automatic"  # or "manual"
    target: 2000  # kN

analysis_parameters:
  static:
    tolerance: 0.001
    max_iterations: 100
  dynamic:
    duration: 10800  # seconds (3 hours)
    time_step: 0.05  # seconds
    ramp_time: 300  # seconds
    output_interval: 1.0  # seconds

output:
  format: "html"  # or "csv", "excel"
  include_plots: true
  statistics: ["max", "min", "mean", "std"]
  results:
    - "vessel_motions"
    - "mooring_tensions"
    - "anchor_loads"
```

### Example 2: Hydrodynamic Analysis Configuration

```yaml
# config/hydrodynamic_analysis.yaml
---
analysis:
  type: "frequency_domain"
  software: "AQWA"  # or "WAMIT", "OrcaWave"

geometry:
  input_file: "../models/vessel_geometry.gdf"
  mesh:
    element_size: 2.0  # meters
    refinement_zones:
      - location: "bow"
        size: 0.5
      - location: "stern"
        size: 0.5

wave_directions:
  start: 0
  end: 180
  step: 15  # degrees

wave_frequencies:
  min: 0.1  # rad/s
  max: 2.0
  number: 40
  spacing: "logarithmic"  # or "linear"

mass_properties:
  displacement: 150000  # tonnes
  center_of_gravity:
    x: 160  # from origin
    y: 0
    z: 15
  radii_of_gyration:
    Rxx: 22  # roll
    Ryy: 95  # pitch
    Rzz: 95  # yaw

water_depth: 1500  # meters, or "infinite"

output:
  added_mass: true
  damping: true
  wave_excitation: true
  raos: true
  drift_forces: true
  qtf: false  # Quadratic Transfer Functions (slow)

  export_formats:
    - "txt"
    - "csv"
    - "yml"

  plots:
    - "added_mass_vs_frequency"
    - "damping_vs_frequency"
    - "rao_amplitude_vs_frequency"
    - "rao_phase_vs_frequency"
```

### Example 3: Fatigue Analysis Configuration

```yaml
# config/fatigue_analysis.yaml
---
analysis:
  name: "Mooring Line Fatigue Assessment"
  type: "spectral_fatigue"
  standard: "DNV-RP-C203"

input_data:
  tension_rao:
    file: "../results/mooring_rao.csv"
    format: "csv"
    columns:
      frequency: "freq_rad_s"
      amplitude: "tension_amplitude_kN"

  wave_scatter:
    file: "../data/wave_scatter_diagram.yml"
    annual_probability: true

material:
  type: "chain"
  grade: "R4"
  diameter: 127  # mm
  sn_curve:
    class: "F3"  # DNV classification
    m: 3.0  # S-N curve slope
    a: 1.52e12  # S-N curve constant
    thickness_exponent: 0.25

stress_concentration:
  factor: 1.2  # SCF
  location: "connector"

analysis_parameters:
  short_term:
    duration: 3  # hours
    bins: 100

  long_term:
    design_life: 25  # years
    damage_limit: 1.0

output:
  damage_per_sea_state: true
  annual_damage: true
  fatigue_life: true
  utilization: true

  plots:
    - "damage_vs_hs_tp"
    - "cumulative_damage"
    - "rainflow_histogram"

  export:
    format: ["html", "csv"]
    include_raw_data: false
```

### Example 4: Multi-Analysis Workflow

```yaml
# config/workflow_config.yaml
---
workflow:
  name: "Complete Mooring Analysis Workflow"
  version: 1.0

stages:
  - stage: 1
    name: "Hydrodynamic Analysis"
    config: "../config/hydrodynamic_analysis.yaml"
    outputs:
      - "../results/added_mass.csv"
      - "../results/damping.csv"
      - "../results/raos.csv"

  - stage: 2
    name: "Mooring Static Analysis"
    config: "../config/mooring_static.yaml"
    inputs:
      - "../results/vessel_properties.yml"
    outputs:
      - "../results/mooring_configuration.yml"
      - "../results/static_tensions.csv"

  - stage: 3
    name: "Mooring Dynamic Analysis"
    config: "../config/mooring_dynamic.yaml"
    dependencies: [1, 2]  # Requires stages 1 and 2
    inputs:
      - "../results/raos.csv"
      - "../results/mooring_configuration.yml"
    outputs:
      - "../results/dynamic_tensions.csv"
      - "../reports/mooring_report.html"

  - stage: 4
    name: "Fatigue Assessment"
    config: "../con