OrcaFlex Monolithic to Modular Converter Skill

Convert large monolithic OrcaFlex YAML files into organized modular structures with reusable includes and parameterized inputs.

Version Metadata

yaml

version: 1.0.0
python_min_version: '3.10'
orcaflex_version: '>=11.0'
compatibility:
  tested_python:
  - '3.10'
  - '3.11'
  - '3.12'
  - '3.13'
  os:
  - Windows
  - Linux
  - macOS

When to Use

Converting large single-file YAML models to maintainable modular format
Extracting reusable components (line types, buoy types, environments)
Preparing models for parametric analysis
Creating template libraries from existing models
Standardizing model organization across projects

Directory Structure Convention

Target Structure

<example_folder>/
├── monolithic.yml           # Original single-file (preserved)
└── modular/
    ├── master.yml           # Entry point with includes
    ├── includes/            # Component definitions
    │   ├── 01_general.yml
    │   ├── 02_var_data.yml
    │   ├── 03_environment.yml
    │   ├── 05_line_types.yml
    │   ├── 07_lines.yml
    │   ├── 08_buoys.yml
    │   ├── 09_shapes.yml
    │   ├── 10_groups.yml
    │   ├── 13_supports.yml
    │   └── 14_morison.yml
    └── inputs/
        └── parameters.yml   # Extracted parameters

Naming Conventions

Convention	Example	Rationale
Folder name	`30in_pipeline/`	Descriptive, filesystem-safe
Original file	`monolithic.yml`	Clear purpose identification
Entry point	`master.yml`	Standard modular entry
Include prefix	`01_`, `02_`	Dependency ordering

Include File Ordering

Critical: Include order matters due to OrcaFlex dependencies.

yaml

# master.yml - Correct dependency order
- includefile: includes/01_general.yml      # Global settings first
- includefile: includes/02_var_data.yml     # Variable data
- includefile: includes/03_environment.yml  # Environment before objects
- includefile: includes/05_line_types.yml   # Types before instances
- includefile: includes/13_supports.yml     # Supports before lines
- includefile: includes/14_morison.yml      # Morison elements
- includefile: includes/09_shapes.yml       # Shapes before buoys
- includefile: includes/08_buoys.yml        # Buoys before lines connect
- includefile: includes/07_lines.yml        # Lines reference types/buoys
- includefile: includes/10_groups.yml       # Groups reference objects

Dependency Rules

Types before instances - LineTypes before Lines
Connections before dependents - Buoys before Lines that connect to them
Global before specific - General/Environment before objects
References resolved - Define before reference

Component Mapping

Section	Include File	Contents
General	`01_general.yml`	Units, simulation settings
Variable Data	`02_var_data.yml`	Tags, variables
Environment	`03_environment.yml`	Water depth, waves, current, wind
Line Types	`05_line_types.yml`	Cable/chain/riser properties
Lines	`07_lines.yml`	Line instances, connections
Buoys	`08_buoys.yml`	3D/6D buoy definitions
Shapes	`09_shapes.yml`	Drawing shapes
Groups	`10_groups.yml`	Object groupings
Supports	`13_supports.yml`	Support definitions
Morison	`14_morison.yml`	Morison elements

Parameter Extraction

Extract key parameters to inputs/parameters.yml for parametric studies:

yaml

# inputs/parameters.yml
parameters:
  environment:
    water_depth: 8
    current_speed: 1
    current_direction: 270
    wind_speed: 8.87
    water_density: 1.03

  waves:
    hs: 0
    tp: 8
    wave_direction: 180

  simulation:
    stage_durations: [8, 16]
    time_step: 0.1

Conversion Process

Step 1: Analyze Monolithic File

python

import yaml
from pathlib import Path

def analyze_monolithic(yml_path: Path) -> dict:
    """Identify sections in monolithic YAML."""
    with open(yml_path) as f:
        content = yaml.safe_load(f)

    sections = {
        'General': content.get('General', {}),
        'Environment': content.get('Environment', {}),
        'LineTypes': content.get('LineTypes', []),
        'Lines': content.get('Lines', []),
        'Buoys': content.get('Buoys', []),
        # ... etc
    }
    return sections

Step 2: Create Modular Structure

python

def create_modular_structure(base_dir: Path):
    """Create standard directory structure."""
    (base_dir / 'modular' / 'includes').mkdir(parents=True, exist_ok=True)
    (base_dir / 'modular' / 'inputs').mkdir(parents=True, exist_ok=True)

Step 3: Split Sections

python

def split_to_includes(sections: dict, includes_dir: Path):
    """Write each section to separate include file."""

    section_mapping = {
        'General': '01_general.yml',
        'Environment': '03_environment.yml',
        'LineTypes': '05_line_types.yml',
        'Lines': '07_lines.yml',
        'Buoys': '08_buoys.yml',
    }

    for section, filename in section_mapping.items():
        if section in sections and sections[section]:
            output_path = includes_dir / filename
            with open(output_path, 'w') as f:
                yaml.dump({section: sections[section]}, f,
                         default_flow_style=False)

Step 4: Generate Master File

python

def generate_master(modular_dir: Path, original_meta: dict):
    """Generate master.yml with includes."""

    includes = sorted((modular_dir / 'includes').glob('*.yml'))

    master_content = [
        '%YAML 1.1',
        '# Type: Model',
        f'# Converted from: {original_meta["source"]}',
        f'# Created: {original_meta["timestamp"]}',
        '---',
    ]

    # Add includes in dependency order
    for inc in includes:
        master_content.append(f'- includefile: includes/{inc.name}')

    with open(modular_dir / 'master.yml', 'w') as f:
        f.write('\n'.join(master_content))

Lessons Learned

From Production Usage (2026-01-21)

Use descriptive folder names: 30in_pipeline is clearer than 5_tug_env_6D_buoys
Separate monolithic from modular: Keep original as monolithic.yml alongside modular/ directory
Extract parameters early: Identify parameters for parametric studies before splitting
Preserve metadata: Keep original file header (Program version, creation date, user)
Test after conversion: Load master.yml in OrcaFlex to verify integrity
Document include order: Include order is critical - document dependencies in master.yml

Common Pitfalls

Pitfall	Solution
Lines fail to load	Check LineTypes included before Lines
Buoy connections missing	Include Buoys before Lines that connect
Groups reference missing objects	Groups must be last
Parameters hardcoded	Extract to inputs/parameters.yml

Validation

Quick Validation

bash

# Load modular model in OrcaFlex
python -c "import OrcFxAPI; m = OrcFxAPI.Model('modular/master.yml'); print('OK')"

Full Validation

python

def validate_modular(master_path: Path, monolithic_path: Path) -> bool:
    """Compare modular vs monolithic models."""
    import OrcFxAPI

    model_mono = OrcFxAPI.Model(str(monolithic_path))
    model_mod = OrcFxAPI.Model(str(master_path))

    # Compare object counts
    mono_objects = len(list(model_mono.objects))
    mod_objects = len(list(model_mod.objects))

    if mono_objects != mod_objects:
        print(f"Object count mismatch: {mono_objects} vs {mod_objects}")
        return False

    print(f"Validation passed: {mod_objects} objects")
    return True

Example Usage

Convert Existing Model

bash

# 1. Create example folder
mkdir -p docs/modules/orcaflex/pipeline/installation/floating/30in_pipeline

# 2. Copy original as monolithic.yml
cp "original model.yml" 30in_pipeline/monolithic.yml

# 3. Run conversion (manual or scripted)
python -m digitalmodel.tools.orcaflex_modularize 30in_pipeline/monolithic.yml

# 4. Verify
ls -la 30in_pipeline/modular/

Parametric Study Setup

python

import yaml
from pathlib import Path

# Load parameters
params_path = Path('30in_pipeline/modular/inputs/parameters.yml')
with open(params_path) as f:
    params = yaml.safe_load(f)

# Modify for study
for hs in [2, 4, 6, 8]:
    params['parameters']['waves']['hs'] = hs
    case_dir = Path(f'cases/hs_{hs}')
    case_dir.mkdir(parents=True, exist_ok=True)

    # Save modified parameters
    with open(case_dir / 'parameters.yml', 'w') as f:
        yaml.dump(params, f)

Related Skills

orcaflex-file-conversion - Format conversion (.dat/.yml/.sim)
orcaflex-model-generator - Template-based model generation
orcaflex-modeling - Run OrcaFlex simulations

References

Example: docs/modules/orcaflex/pipeline/installation/floating/30in_pipeline/
Spec: specs/modules/orcaflex/monolithic-to-modular-converter/
OrcaFlex YAML Include Documentation

Version History

1.0.0 (2026-01-21): Initial release with directory conventions, include ordering, and lessons learned from production usage

Search AI Tools

orcaflex-monolithic-to-modular

Install this agent skill to your Project

SKILL.md

OrcaFlex Monolithic to Modular Converter Skill

Version Metadata

When to Use

Directory Structure Convention

Target Structure

Naming Conventions

Include File Ordering

Dependency Rules

Component Mapping

Parameter Extraction

Conversion Process

Step 1: Analyze Monolithic File

Step 2: Create Modular Structure

Step 3: Split Sections

Step 4: Generate Master File

Lessons Learned

From Production Usage (2026-01-21)

Common Pitfalls

Validation

Quick Validation

Full Validation

Example Usage

Convert Existing Model

Parametric Study Setup

Related Skills

References

Version History