# Orcawave Analysis Diffractionspec Specyml Conventions

> Sub-skill of orcawave-analysis: DiffractionSpec Conventions (spec.yml to OrcaWave).

- Skill: `vamseeachanta/orcawave-analysis-diffractionspec-specyml-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vamseeachanta/orcawave-analysis-diffractionspec-specyml-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamseeachanta/orcawave-analysis-diffractionspec-specyml-conventions/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vamseeachanta (https://skillmd.com/u/vamseeachanta)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamseeachanta/orcawave-analysis-diffractionspec-specyml-conventions

---


# DiffractionSpec Conventions (spec.yml to OrcaWave)

## DiffractionSpec Conventions (spec.yml to OrcaWave)


The `DiffractionSpec` schema (`input_schemas.py`) is the canonical input format. Key conventions:

**Unit Handling:**
- Spec stores **pure SI** (kg, m, s, kg.m^2)
- `OrcaWaveBackend` divides mass, density, inertia by 1000 for OrcaFlex-SI (te)
- **EXCEPTION**: `external_damping` and `external_stiffness` 6x6 matrices pass through **without conversion** -- values must already be in OrcaFlex-SI units

**Mesh Paths:**
- `mesh_file` is relative to the spec.yml directory
- Runner copies mesh to output dir; backend strips to filename via `Path().name`
- **Known issue**: `_MESH_FORMAT_MAP` maps `dat` to `"Wamit dat"` -- AQWA .dat meshes need `"Aqwa dat"` but the enum lacks this variant

**Multi-Document YAML:**
- OrcaWave YAMLs have `%YAML 1.1` + `---` creating multi-doc streams
- Some files have UTF-8 BOM -- always use `encoding='utf-8-sig'` + `yaml.safe_load_all()`

**Canonical spec.yml Examples:**
- Barge: `docs/modules/orcawave/L02_barge_benchmark/spec.yml`
- Ship (QTF + roll damping): `docs/modules/orcawave/L03_ship_benchmark/spec.yml`
- Spar (rad/s freqs): `docs/modules/orcawave/L04_spar_benchmark/spec.yml`

**Frequency Input:**
- `input_type: period` -- values in seconds (backend uses directly)
- `input_type: frequency` -- values in rad/s (backend converts to periods via 2*pi/omega)
- OrcaWave always receives `WavesReferredToBy: "period (s)"`

---