hms-commander 0.1.0__tar.gz

hms_commander-0.1.0/.readthedocs.yaml

@@ -0,0 +1,24 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_install:
+      # Install mkdocs dependencies
+      - pip install -e ".[docs]"
+
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

hms_commander-0.1.0/CLAUDE.md

@@ -0,0 +1,280 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with hms-commander.
+
+---
+
+## Project Overview
+
+**hms-commander** is a Python library for automating HEC-HMS (Hydrologic Engineering Center's Hydrologic Modeling System) operations. It provides a comprehensive API for interacting with HEC-HMS project files, executing simulations, and processing results, following the architectural patterns established by ras-commander.
+
+---
+
+## Development Environment
+
+### Package Management
+- **Agent scripts and tools**: Use `uv` for installation, `python` for execution
+- **User-facing docs**: Use `pip` for broader compatibility
+- **Fast installation**: `uv pip install -e ".[all]"` (10-100x faster than pip)
+
+### Build Commands
+- **Install locally**: `pip install -e .` (for development)
+- **Install from build**: `pip install hms-commander`
+- **Install with optional dependencies**: `pip install -e ".[all]"` (includes dev, gis, dss)
+
+### Dependencies
+- **Python**: Requires 3.10+
+- **Core packages**: pandas, numpy, pathlib, tqdm, requests
+- **Optional GIS**: geopandas, pyproj, shapely
+- **Optional DSS**: ras-commander, pyjnius
+
+### Testing Environments (Conda)
+- **hmscmdr_local**: Local development version (use when making code changes)
+  - `conda create -n hmscmdr_local python=3.11`
+  - `conda activate hmscmdr_local && pip install -e ".[all]"`
+  - Editable install, changes immediately reflected in notebooks
+
+- **hmscmdr_pip**: Published package version (use for release validation)
+  - `conda create -n hmscmdr_pip python=3.11`
+  - `conda activate hmscmdr_pip && pip install hms-commander`
+  - Matches end-user experience
+
+**See**: `.claude/rules/project/development-environment.md` for complete testing protocols
+
+---
+
+## Architecture Overview
+
+### Core Classes
+
+**File Operations**: HmsBasin, HmsMet, HmsControl, HmsGage, HmsRun, HmsGeo
+**Execution**: HmsCmdr, HmsJython
+**Data**: HmsDss, HmsResults
+**Utilities**: HmsUtils, HmsExamples
+**Project**: HmsPrj (initialization and multi-project support)
+
+### Key Architectural Patterns
+
+**Static Classes**: All core classes use static methods, no instantiation required.
+See: `.claude/rules/python/static-classes.md`
+
+**File Parsing**: Shared HmsFileParser eliminates duplication.
+See: `.claude/rules/python/file-parsing.md`
+
+**Clone Workflows**: Non-destructive, traceable, GUI-verifiable (CLB Engineering approach).
+See: `.claude/rules/hec-hms/clone-workflows.md`
+
+---
+
+## Quick Start
+
+### Initialize and Execute
+
+```python
+from hms_commander import init_hms_project, HmsCmdr
+
+init_hms_project(r"C:\Projects\watershed")
+HmsCmdr.compute_run("Run 1")
+```
+
+### Access Project Data
+
+```python
+from hms_commander import hms
+
+# After initialization, access dataframes
+subbasins = hms.basin_df
+met_models = hms.met_df
+runs = hms.run_df
+```
+
+### Direct File Operations (No Initialization)
+
+```python
+from hms_commander import HmsBasin, HmsMet
+
+subbasins = HmsBasin.get_subbasins("project.basin")
+HmsMet.set_gage_assignment("project.met", "Sub1", "Gage1")
+```
+
+---
+
+## Detailed Documentation
+
+### For Complete API
+
+**Code**: `hms_commander/*.py` - All classes have comprehensive docstrings
+**Examples**: `examples/*.ipynb` - Working demonstrations
+**API Docs**: `docs/api/*.md` - Generated reference
+**File Formats**: `tests/projects/2014.08_HMS/File Parsing Guide/` - HMS file structures
+
+### For Patterns and Workflows
+
+**See**: `.claude/rules/` for organized knowledge:
+
+**Python Patterns** (`.claude/rules/python/`):
+- static-classes.md - Core HMS pattern
+- file-parsing.md - HmsFileParser utilities
+- constants.md - Centralized magic numbers
+- decorators.md, path-handling.md, error-handling.md, naming-conventions.md
+
+**HMS Domain Knowledge** (`.claude/rules/hec-hms/`):
+- execution.md - HmsCmdr, HmsJython, version detection
+- basin-files.md - HmsBasin operations
+- met-files.md - HmsMet operations
+- control-files.md - HmsControl operations
+- dss-operations.md - HmsDss, HmsResults
+- clone-workflows.md - CLB Engineering LLM Forward approach
+- version-support.md - HMS 3.x vs 4.x differences
+
+**Testing** (`.claude/rules/testing/`):
+- example-projects.md - HmsExamples usage
+- tdd-approach.md - No mocks, use real HMS projects
+
+---
+
+## Key Principles
+
+### 1. Static Classes, No Instantiation
+
+```python
+# ✅ Correct
+HmsBasin.get_subbasins("project.basin")
+
+# ❌ Wrong
+basin = HmsBasin()  # Don't do this
+```
+
+### 2. Test with Real Projects, Not Mocks
+
+```python
+from hms_commander import HmsExamples, HmsBasin
+
+HmsExamples.extract_project("tifton")  # Real HMS project
+subbasins = HmsBasin.get_subbasins("tifton/tifton.basin")
+```
+
+### 3. HMS Version Awareness
+
+**HMS 3.x (32-bit)**: Requires `python2_compatible=True`
+**HMS 4.x (64-bit)**: Default Python 3 syntax
+
+See: `.claude/rules/hec-hms/version-support.md`
+
+### 4. Clone for QAQC
+
+Non-destructive workflows enable side-by-side comparison in HEC-HMS GUI.
+
+See: `.claude/rules/hec-hms/clone-workflows.md`
+
+---
+
+## Differences from ras-commander
+
+| Aspect | ras-commander | hms-commander |
+|--------|---------------|---------------|
+| Primary Files | .prj, .p##, .g##, .hdf | .hms, .basin, .met, .control |
+| Results Format | HDF5 | DSS (via RasDss) |
+| Execution | Subprocess (Ras.exe) | Jython scripts (hec-hms.cmd) |
+| Project Discovery | .prj file | .hms file |
+| Data Storage | HDF groups/datasets | ASCII text sections |
+| Parsing Approach | h5py library | Regex/text parsing |
+
+**Integration**: hms-commander uses ras-commander's RasDss for DSS operations (no code duplication).
+
+---
+
+## Cross-Repository Integration: HMS→RAS Workflows
+
+**hms-commander** and **ras-commander** work together for integrated watershed-to-river modeling.
+
+### Workflow Pattern
+
+```
+HEC-HMS (Watershed)          HEC-RAS (River)
+    ↓                            ↓
+Precipitation                Geometry
+    ↓                            ↓
+Runoff Generation        ←─── Import HMS Flows
+    ↓                            ↓
+DSS Output               Hydraulic Analysis
+```
+
+### HMS Responsibilities (This Library)
+
+1. **Generate Hydrographs**: Execute simulations, create DSS results
+2. **Extract Flows**: Use HmsResults to get peak flows and time series
+3. **Document Spatial Reference**: Use HmsGeo to provide outlet locations
+4. **Validate Quality**: Check peaks, volumes, time series completeness
+
+```python
+from hms_commander import init_hms_project, HmsCmdr, HmsResults, HmsGeo
+
+# Execute HMS
+init_hms_project("watershed")
+HmsCmdr.compute_run("Design_Storm")
+
+# Extract for RAS
+flows = HmsResults.get_outflow_timeseries(dss_file, "Outlet")
+lat, lon = HmsGeo.get_project_centroid_latlon("project.geo")
+
+# Handoff: DSS file, pathname, outlet location
+```
+
+### RAS Responsibilities (ras-commander)
+
+1. **Import HMS DSS**: Use RasUnsteady to import boundary conditions
+2. **Spatial Matching**: Match HMS outlets to RAS cross sections
+3. **Hydraulic Analysis**: Run unsteady flow with HMS upstream BCs
+4. **Validation**: Compare HMS peaks vs RAS peaks
+
+### Shared Infrastructure
+
+**RasDss**: Both libraries use the same DSS operations
+- HMS: `HmsDss` (wraps RasDss)
+- RAS: `RasDss` (direct)
+- Result: No format conversion, consistent pathnames
+
+### Skills and Subagents
+
+- **Skill**: `.claude/skills/linking-hms-to-hecras/` - HMS side workflow
+- **Skill** (ras-commander): `importing-hms-boundaries/` - RAS side workflow
+- **Subagent**: `.claude/subagents/hms-ras-workflow-coordinator.md` - Coordinates both sides
+- **Rules**: `.claude/rules/integration/hms-ras-linking.md` - Integration patterns
+
+See these files for complete HMS→RAS integration workflows.
+
+---
+
+## Common Pitfalls to Avoid
+
+- ❌ Don't instantiate static classes like `HmsBasin()`
+- ❌ Don't use mocks in tests - use `HmsExamples.extract_project()`
+- ❌ Don't forget `python2_compatible=True` for HMS 3.x
+- ✅ Always specify `hms_object` when working with multiple projects
+- ✅ Use pathlib.Path for all path operations
+- ✅ Handle file encodings (UTF-8 with Latin-1 fallback)
+
+---
+
+## Navigation
+
+### Primary Sources (Authoritative)
+- **Code**: `hms_commander/*.py` (docstrings)
+- **Examples**: `examples/*.ipynb` (workflows)
+- **File Formats**: `tests/projects/.../File Parsing Guide/`
+- **API Docs**: `docs/api/*.md`
+
+### Framework Documentation
+- **Patterns**: `.claude/rules/python/`
+- **HMS Knowledge**: `.claude/rules/hec-hms/`
+- **Testing**: `.claude/rules/testing/`
+- **Documentation**: `.claude/rules/documentation/`
+
+### Task Coordination
+- **Memory**: `.agent/` (multi-session state)
+- **Agents**: `hms_agents/` (production workflows)
+- **Research**: `feature_dev_notes/` (feature development)
+
+### Complete Framework
+See: `.claude/CLAUDE.md` for hierarchical knowledge organization