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

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

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

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: "../config/fatigue_analysis.yaml" dependencies: [3] inputs:

  • "../results/dynamic_tensions.csv" outputs:
  • "../results/fatigue_damage.csv"
  • "../reports/fatigue_report.html"

execution: parallel: false # Run stages sequentially stop_on_error: true save_intermediate: true

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: "Project_1_FPSO" custom_modifications: draft: 24 # Override default

project_2: vessel: <<: *semi name: "Project_2_SemiSub"

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: "max_offset"

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!