docs: document physics option naming convention (GH#972)

Add comprehensive documentation for the physics option alias system:

In model.py:
- Detailed comment block explaining the 5 input format types
- Examples for each format type
- Note on case-insensitivity

In sample_config.yml:
- Header explaining the naming convention
- Inline comments showing valid values for each option
- Clear separation between multi-dimensional and single-dimensional options

Format types documented:
1. Numeric codes (legacy): storageheatmethod: 1
2. Model names: ohm, anohm, estm, ehc, narp, most, rst
3. Author-year (Xyy): K09, CN98, W16, J11
4. Descriptive: fixed, variable, auto, model, obs
5. Binary: yes/no

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: sunt05

.claude/rules/python/conventions.md

@@ -23,17 +23,32 @@ SUEWS-specific Python conventions. Complements ruff for standard linting.
 
 ## Critical Rules
 
-1. **Config separation**: No config objects in low-level functions
+1. **Python 3.9 compatibility**: Use `Optional[X]` not `X | None` for union types
+   ```python
+   from typing import Optional, Union
+
+   # BAD: PEP 604 syntax requires Python 3.10+
+   def foo(x: str | None = None): ...
+   def bar(items: list[int] | None): ...
+
+   # GOOD: Works on Python 3.9+
+   def foo(x: Optional[str] = None): ...
+   def bar(items: Optional[list[int]]): ...
+   ```
+   **Why**: PEP 604 union syntax (`X | Y`) requires Python 3.10+. Pydantic evaluates
+   type hints at runtime, so `from __future__ import annotations` is not a safe workaround.
+
+2. **Config separation**: No config objects in low-level functions
    ```python
    # BAD: def save_supy(df_output, config): ...
    # GOOD: def save_supy(df_output, freq_s: int = 3600): ...
    ```
 
-2. **Deep copy**: Use `copy.deepcopy()` for mutable state
+3. **Deep copy**: Use `copy.deepcopy()` for mutable state
 
-3. **Logging**: Use `logger_supy` not `print()`
+4. **Logging**: Use `logger_supy` not `print()`
 
-4. **pathlib**: Use `Path` not `os.path`
+5. **pathlib**: Use `Path` not `os.path`
 
 ---
 

pyproject.toml

@@ -139,6 +139,14 @@ markers = [
 line-length = 120
 target-version = "py39"
 
+[tool.ruff.lint]
+# FA102: Catch PEP 604 union syntax (X | None) which requires Python 3.10+
+# This prevents CI failures on Python 3.9 due to runtime TypeError
+extend-select = ["FA102"]
+
+# Note: FA102 auto-fix adds `from __future__ import annotations` which can break Pydantic
+# Instead, manually use Optional[X] from typing module (see .claude/rules/python/conventions.md)
+
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"

src/supy/data_model/core/model.py

@@ -132,8 +132,54 @@ def _coerce_enum_value(
     return v
 
 
-# Short aliases for physics options
-# Use explicit model names where they exist; otherwise use Xyy (author initial + year)
+# =============================================================================
+# Physics Option Aliases
+# =============================================================================
+#
+# Naming Convention for Physics Options
+# -------------------------------------
+# Physics options support multiple input formats for flexibility:
+#
+# 1. NUMERIC CODES (legacy, still supported)
+#    - Integer values matching Fortran interface
+#    - Example: storageheatmethod: 1
+#
+# 2. EXPLICIT MODEL NAMES (preferred for named models)
+#    - Use the established model acronym in lowercase
+#    - Examples:
+#      - ohm: Objective Hysteresis Model
+#      - anohm: Analytical OHM
+#      - estm: Element Surface Temperature Method
+#      - ehc: Explicit Heat Conduction
+#      - dyohm: Dynamic OHM
+#      - narp: Net All-wave Radiation Parameterization
+#      - most: Monin-Obukhov Similarity Theory
+#      - rst: Roughness Sublayer Theory
+#
+# 3. AUTHOR-YEAR FORMAT (Xyy) for methods without model names
+#    - Format: First letter of first author surname + two-digit year
+#    - Case-insensitive (K09, k09, K09 all work)
+#    - Examples:
+#      - K09: Kawai et al. 2009 (thermal roughness)
+#      - CN98: Campbell & Norman 1998 (stability functions)
+#      - W16: Ward et al. 2016 (stomatal conductance)
+#      - J11: Järvi et al. 2011 (stomatal conductance, QF)
+#      - B82: Brutsaert 1982 (thermal roughness)
+#      - M98: MacDonald et al. 1998 (momentum roughness)
+#      - GO99: Grimmond & Oke 1999 (roughness length)
+#
+# 4. GENERIC DESCRIPTIVE TERMS (for simple choices)
+#    - fixed, variable, auto: method selection
+#    - model, obs: modelled vs observed
+#    - provided, calc: use input vs calculate
+#
+# 5. BINARY OPTIONS (yes/no)
+#    - ohmincqf: yes/no (include QF in OHM)
+#    - snowuse: yes/no (enable snow module)
+#
+# All string inputs are case-insensitive.
+# =============================================================================
+
 # Maps short alias → enum member name
 STORAGE_HEAT_ALIASES = {
     "obs": "OBSERVED",