Add AlphaMode enum for stringly-typed alpha_mode field

[waltsims]

• AlphaMode(str, Enum) with NO_ABSORPTION, NO_DISPERSION, STOKES
• kWaveMedium.post_init normalizes string inputs to enum
• Backward compatible: AlphaMode == "no_dispersion" works via str inheritance
• str returns the value so f-strings render cleanly

Greptile Summary

Adds AlphaMode(str, Enum) to replace the stringly-typed alpha_mode field and introduces a _to_alpha_mode helper that normalises the value at construction time (__post_init__) and again inside check_fields to cover post-construction string reassignment. Because AlphaMode inherits from str, all existing equality/membership comparisons across the codebase (checks.py, create_absorption_variables.py, kWaveSimulation.py) continue to work without modification.

Confidence Score: 5/5

Safe to merge — only P2 style findings, no logic or correctness issues.

All three changed files are correct. The str-Enum design preserves backward compatibility with every existing string comparison in the codebase. The two previous review concerns (post-construction bypass, unhelpful error message) are both addressed. Only minor style findings remain.

No files require special attention.

Important Files Changed

Filename	Overview
kwave/enums.py	Adds AlphaMode(str, Enum) with three members and an explicit str that returns self.value for clean f-string rendering.
kwave/kmedium.py	Introduces _to_alpha_mode helper, normalizes alpha_mode in post_init and check_fields, handles post-construction string reassignment; field comment omits AlphaMode.STOKES.
tests/test_kmedium.py	New test file covering construction normalization, invalid-input errors, post-construction string assignment, and backward-compatible string comparisons.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["caller sets alpha_mode\n(str, AlphaMode, or None)"] --> B{__post_init__ or\ncheck_fields}
    B --> C["_to_alpha_mode(value)"]
    C --> D{value is None or\nalready AlphaMode?}
    D -- Yes --> E["return as-is"]
    D -- No --> F["AlphaMode(value)"]
    F -- valid string --> G["AlphaMode enum member\n(NO_ABSORPTION / NO_DISPERSION / STOKES)"]
    F -- invalid --> H["ValueError with\nfriendly message"]
    G --> I["self.alpha_mode = AlphaMode member"]
    E --> I
    I --> J["Downstream comparisons\nalpha_mode == 'no_dispersion' ✓\nalpha_mode == 'stokes' ✓\nalpha_mode in list ✓"]

Loading

_{Reviews (3): Last reviewed commit: "Accept post-construction string assignme..." | Re-trigger Greptile}

[greptile-apps]

Post-construction string assignment silently breaks check_fields

check_fields is called from kWaveSimulation after the object is fully constructed (line 610 in kWaveSimulation.py). Since kWaveMedium is a plain dataclass, its attributes are mutable — a caller can legally write medium.alpha_mode = "no_dispersion" after __post_init__ runs, bypassing the normalization step. Under the old code that assignment would still pass the in [...] check; under this PR it raises a ValueError even for a valid string value, silently breaking previously-working patterns.

The type hint Optional[Union[AlphaMode, str]] reinforces the expectation that plain strings remain valid inputs throughout the object's lifetime. Fix by normalising strings in check_fields as well, or by converting alpha_mode to a property setter so normalisation is always applied on write:

# check the absorption mode input is valid (already normalized to AlphaMode in __post_init__)
if self.alpha_mode is not None:
    if isinstance(self.alpha_mode, str) and not isinstance(self.alpha_mode, AlphaMode):
        self.alpha_mode = AlphaMode(self.alpha_mode)  # late-normalise post-construction strings
    elif not isinstance(self.alpha_mode, AlphaMode):
        raise ValueError(
            f"medium.alpha_mode must be an AlphaMode enum value or one of "
            f"'no_absorption', 'no_dispersion', 'stokes', got {self.alpha_mode!r}"
        )

[greptile-apps]

Invalid string raises unhelpful ValueError from enum constructor

When an invalid string is passed at construction time (e.g. kWaveMedium(sound_speed=1500, alpha_mode="typo")), AlphaMode("typo") raises ValueError: 'typo' is not a valid AlphaMode — the more descriptive message in check_fields is never reached. Consider wrapping the conversion to re-raise with a clearer hint:

if isinstance(self.alpha_mode, str) and not isinstance(self.alpha_mode, AlphaMode):
    try:
        self.alpha_mode = AlphaMode(self.alpha_mode)
    except ValueError:
        valid = [m.value for m in AlphaMode]
        raise ValueError(
            f"medium.alpha_mode must be one of {valid}, got {self.alpha_mode!r}"
        )

[codecov]

Codecov Report

❌ Patch coverage is 94.44444% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 74.46%. Comparing base (ba553eb) to head (0a8ae37).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
kwave/enums.py	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #705      +/-   ##
==========================================
+ Coverage   74.40%   74.46%   +0.05%     
==========================================
  Files          56       56              
  Lines        8026     8040      +14     
  Branches     1570     1570              
==========================================
+ Hits         5972     5987      +15     
  Misses       1437     1437              
+ Partials      617      616       -1     

Flag	Coverage Δ
3.10	74.46% <94.44%> (+0.05%)	⬆️
3.11	74.46% <94.44%> (+0.05%)	⬆️
3.12	74.46% <94.44%> (+0.05%)	⬆️
3.13	74.46% <94.44%> (+0.05%)	⬆️
macos-latest	74.44% <94.44%> (+0.05%)	⬆️
ubuntu-latest	74.44% <94.44%> (+0.05%)	⬆️
windows-latest	74.45% <94.44%> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[waltsims]

@Greptile-app