yaml-configuration

name	yaml-configuration
version	1.0.0
description	YAML for configuration-driven engineering workflows, model setup, and analysis parameters
author	workspace-hub
category	programming
tags	["yaml","configuration","engineering","orcaflex","automation","data-structures"]
platforms	["yaml","python"]

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:

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

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

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

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

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

# 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

# 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  
     
     
  
       
       
       
    
       
       
       


     
   
  
      
       
         
      
          
           
             
           
          
           
             
          
           
             
      
         
           
      
       
       
      

  
       
       


  
     
     
  
       
       
       
       


     
   
   [, , , ]
  
     
     
     

Example 2: Hydrodynamic Analysis Configuration

# 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
     
  
       
       
       

   


   
   
   
   
   
     

  
     
     
     

  
     
     
     
     

Example 3: Fatigue Analysis Configuration

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

  
       
     


   
   
   
   

  
     
     
     

  
     [, ]
     

Example 4: Multi-Analysis Workflow

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

    
     
     
     []
    
       
    
       
       


     
   
   

Example 5: Vessel Library

# config/vessel_library.yaml
---
# Vessel templates library

vessels:
  fpso_standard: &fpso
    type: "FPSO"
    dimensions:
      length: 320
      beam: 58
      draft: 22
    mass: 150000
    mooring: "spread"

  semi_sub_standard: &semi
    type: "Semi-submersible"
    dimensions:
      length: 110
      beam: 78
      draft: 25
    mass: 45000
    mooring: "tendon"

  spar_standard: &spar
    type: "SPAR"
    dimensions:
      length: 200  # height
      diameter: 40
      draft: 180
    mass: 30000
    mooring: "taut"

# Use templates in specific projects
project_1:
  vessel:
    <<: *fpso
    name: 
    
         


  
     
     

Example 6: Parameter Variations

# config/parametric_study.yaml
---
parametric_study:
  name: "Mooring Pretension Sensitivity"
  base_config: "../config/mooring_analysis.yaml"

  parameters:
    - name: "pretension"
      type: "linear"
      min: 1000
      max: 3000
      steps: 11
      unit: "kN"

    - name: "water_depth"
      type: "list"
      values: [1000, 1500, 2000, 2500]
      unit: "m"

  combinations: "full_factorial"  # or "latin_hypercube"

  output:
    summary_table: true
    plots:
      - type: "line"
        x: "pretension"
        y: "max_tension"
      - type: "contour"
        x: "pretension"
        y: "water_depth"
        z: 

Python Integration

Loading YAML in Python

import yaml
from pathlib import Path

def load_config(config_file: str) -> dict:
    """Load YAML configuration file."""
    with open(config_file, 'r') as f:
        config = yaml.safe_load(f)
    return config

# Usage
config = load_config('../config/mooring_analysis.yaml')

water_depth = config['environment']['water_depth']
vessel_name = config['vessel']['name']
num_lines = config['mooring_system']['number_of_lines']

Writing YAML from Python

import yaml

def save_config(config: dict, output_file: str):
    """Save configuration to YAML file."""
    with open(output_file, 'w') as f:
        yaml.dump(config, f, default_flow_style=False, sort_keys=False)

# Create configuration
config = {
    'analysis': {
        'name': 'Test Analysis',
        'duration': 3600
    },
    'parameters': {
        'Hs': 8.5,
        'Tp': 12.0
    }
}

save_config(config, '../config/generated_config.yaml')

Validation

import yaml
from jsonschema import validate, ValidationError

def validate_config(config_file: str, schema_file: str) -> bool:
    """Validate YAML against JSON schema."""
    with open(config_file) as f:
        config = yaml.safe_load(f)

    with open(schema_file) as f:
        schema = yaml.safe_load(f)

    try:
        validate(instance=config, schema=schema)
        return True
    except ValidationError as e:
        print(f"Validation error: {e.message}")
        return False

Merging Configs

def merge_configs(base_config: dict, override_config: dict) -> dict:
    """Deep merge two configuration dictionaries."""
    import copy

    result = copy.deepcopy(base_config)

    for key, value in override_config.items():
        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
            result[key] = merge_configs(result[key], value)
        else:
            result[key] = value

    return result

# Usage
base = load_config('../config/default.yaml')
custom = load_config('../config/custom.yaml')
merged = merge_configs(base, custom)

Best Practices

1. Use Consistent Indentation

# ✅ Good: 2 spaces
vessel:
  dimensions:
    length: 320
    beam: 58

# ❌ Bad: Mixed indentation
vessel:
   dimensions:
     length: 320
   beam: 58

2. Quote Strings When Needed

# Quote strings that could be interpreted as numbers or booleans
name: "12345"  # Without quotes, would be number
flag: "true"   # Without quotes, would be boolean

# Quote strings with special characters
description: "Wave height: 8.5m"

3. Use Anchors for Reusability

# Define common material
steel: &steel
  density: 7850
  E: 200e9

# Reuse
chain_material: *steel
pipe_material: *steel

4. Add Comments for Clarity

environment:
  water_depth: 1500  # meters, site-specific
  wave:
    Hs: 8.5  # 100-year return period
    Tp: 12.0  # Associated peak period

5. Organize Logically

# Group related items
analysis:
  # ... analysis settings

environment:
  # ... environmental parameters

vessel:
  # ... vessel properties

mooring:
  # ... mooring system

Common Patterns

Pattern 1: Configuration Hierarchy

# Global defaults
defaults: &defaults
  version: 1.0
  units: "SI"
  precision: 6

# Project-specific configs inherit defaults
project_a:
  <<: *defaults
  name: "Project A"
  # ... specific settings

project_b:
  <<: *defaults
  name: "Project B"
  # ... specific settings

Pattern 2: Environment-Specific Configs

# development.yaml
database:
  host: "localhost"
  port: 5432

# production.yaml
database:
  host: "prod-server.example.com"
  port: 5432

Pattern 3: Parameterized Templates

# template.yaml
analysis:
  name: "${PROJECT_NAME}"
  water_depth: ${WATER_DEPTH}
  wave_height: ${HS}

Installation

# Python YAML library
pip install pyyaml

# With validation
pip install pyyaml jsonschema

# Advanced features
pip install ruamel.yaml  # Preserves comments and formatting

Resources

• YAML Official Spec: https://yaml.org/spec/
• PyYAML Documentation: https://pyyaml.org/wiki/PyYAMLDocumentation
• YAML Lint: http://www.yamllint.com/
• JSON Schema: https://json-schema.org/

---

Use this skill to create maintainable, version-controlled configurations for all DigitalModel analyses!