ras-commander 0.48.0__tar.gz → 0.49.0__tar.gz

{ras_commander-0.48.0/ras_commander.egg-info → ras_commander-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ras-commander
-Version: 0.48.0
+Version: 0.49.0
 Summary: A Python library for automating HEC-RAS operations
 Home-page: https://github.com/billk-FM/ras-commander
 Author: William M. Katzenmeyer
@@ -118,26 +118,56 @@ Certainly! I'll provide you with an updated Key Components section and Project O
 - `RasUnsteady`: Manages unsteady flow file operations
 - `RasUtils`: Contains utility functions for file operations and data management
 - `RasExamples`: Manages and loads HEC-RAS example projects
-- `RasHdf`: Provides utilities for working with HDF files in HEC-RAS projects
+
+### New Components:
+- `HdfBase`: Core functionality for HDF file operations
+- `HdfBndry`: Enhanced boundary condition handling
+- `HdfMesh`: Comprehensive mesh data management
+- `HdfPlan`: Plan data extraction and analysis
+- `HdfResultsMesh`: Advanced mesh results processing
+- `HdfResultsPlan`: Plan results analysis
+- `HdfResultsXsec`: Cross-section results processing
+- `HdfStruc`: Structure data management
+- `HdfPipe`: Pipe network analysis tools
+- `HdfPump`: Pump station analysis capabilities
+- `HdfFluvialPluvial`: Fluvial-pluvial boundary analysis
+- `RasMapper`: RASMapper interface
+- `RasToGo`: Go-Consequences integration
+- `HdfPlot` & `HdfResultsPlot`: Specialized plotting utilities
+
+## Project Organization Diagram
 
 ## Project Organization Diagram
 
 ```
 ras_commander
-├── .github
-│   └── workflows
-│       └── python-package.yml
 ├── ras_commander
 │   ├── __init__.py
 │   ├── _version.py
+│   ├── Decorators.py
+│   ├── LoggingConfig.py
 │   ├── RasCmdr.py
 │   ├── RasExamples.py
 │   ├── RasGeo.py
-│   ├── RasHdf.py
 │   ├── RasPlan.py
 │   ├── RasPrj.py
 │   ├── RasUnsteady.py
-│   └── RasUtils.py
+│   ├── RasUtils.py
+│   ├── RasToGo.py
+│   ├── RasGpt.py
+│   ├── HdfBase.py
+│   ├── HdfBndry.py
+│   ├── HdfMesh.py
+│   ├── HdfPlan.py
+│   ├── HdfResultsMesh.py
+│   ├── HdfResultsPlan.py
+│   ├── HdfResultsXsec.py
+│   ├── HdfStruc.py
+│   ├── HdfPipe.py
+│   ├── HdfPump.py
+│   ├── HdfFluvialPluvial.py
+│   ├── HdfPlot.py
+│   └── HdfResultsPlot.py
 ├── examples
 │   ├── 01_project_initialization.py
 │   ├── 02_plan_operations.py
@@ -236,10 +266,45 @@ plan_number = "01"
 runtime_data = RasHdf.get_runtime_data(plan_number, ras_object=custom_ras)
 print(runtime_data)
 ```
-
 This class simplifies the process of extracting and analyzing data from HEC-RAS HDF output files, supporting tasks such as post-processing and result visualization.
 
 
+### Infrastructure Analysis
+```python
+from ras_commander import HdfPipe, HdfPump
+
+# Analyze pipe network
+pipe_network = HdfPipe.get_pipe_network(hdf_path)
+conduits = HdfPipe.get_pipe_conduits(hdf_path)
+
+# Analyze pump stations
+pump_stations = HdfPump.get_pump_stations(hdf_path)
+pump_performance = HdfPump.get_pump_station_summary(hdf_path)
+```
+
+### Advanced Results Analysis
+```python
+from ras_commander import HdfResultsMesh
+
+# Get maximum water surface and velocity
+max_ws = HdfResultsMesh.get_mesh_max_ws(hdf_path)
+max_vel = HdfResultsMesh.get_mesh_max_face_v(hdf_path)
+
+# Visualize results
+from ras_commander import HdfResultsPlot
+HdfResultsPlot.plot_results_max_wsel(max_ws)
+```
+
+### Fluvial-Pluvial Analysis
+```python
+from ras_commander import HdfFluvialPluvial
+
+boundary = HdfFluvialPluvial.calculate_fluvial_pluvial_boundary(
+    hdf_path,
+    delta_t=12  # Time threshold in hours
+)
+
+
 ## Documentation
 
 For detailed usage instructions and API documentation, please refer to the [Comprehensive Library Guide](Comprehensive_Library_Guide.md).

{ras_commander-0.48.0 → ras_commander-0.49.0}/README.md

@@ -107,26 +107,56 @@ Certainly! I'll provide you with an updated Key Components section and Project O
 - `RasUnsteady`: Manages unsteady flow file operations
 - `RasUtils`: Contains utility functions for file operations and data management
 - `RasExamples`: Manages and loads HEC-RAS example projects
-- `RasHdf`: Provides utilities for working with HDF files in HEC-RAS projects
+
+### New Components:
+- `HdfBase`: Core functionality for HDF file operations
+- `HdfBndry`: Enhanced boundary condition handling
+- `HdfMesh`: Comprehensive mesh data management
+- `HdfPlan`: Plan data extraction and analysis
+- `HdfResultsMesh`: Advanced mesh results processing
+- `HdfResultsPlan`: Plan results analysis
+- `HdfResultsXsec`: Cross-section results processing
+- `HdfStruc`: Structure data management
+- `HdfPipe`: Pipe network analysis tools
+- `HdfPump`: Pump station analysis capabilities
+- `HdfFluvialPluvial`: Fluvial-pluvial boundary analysis
+- `RasMapper`: RASMapper interface
+- `RasToGo`: Go-Consequences integration
+- `HdfPlot` & `HdfResultsPlot`: Specialized plotting utilities
+
+## Project Organization Diagram
 
 ## Project Organization Diagram
 
 ```
 ras_commander
-├── .github
-│   └── workflows
-│       └── python-package.yml
 ├── ras_commander
 │   ├── __init__.py
 │   ├── _version.py
+│   ├── Decorators.py
+│   ├── LoggingConfig.py
 │   ├── RasCmdr.py
 │   ├── RasExamples.py
 │   ├── RasGeo.py
-│   ├── RasHdf.py
 │   ├── RasPlan.py
 │   ├── RasPrj.py
 │   ├── RasUnsteady.py
-│   └── RasUtils.py
+│   ├── RasUtils.py
+│   ├── RasToGo.py
+│   ├── RasGpt.py
+│   ├── HdfBase.py
+│   ├── HdfBndry.py
+│   ├── HdfMesh.py
+│   ├── HdfPlan.py
+│   ├── HdfResultsMesh.py
+│   ├── HdfResultsPlan.py
+│   ├── HdfResultsXsec.py
+│   ├── HdfStruc.py
+│   ├── HdfPipe.py
+│   ├── HdfPump.py
+│   ├── HdfFluvialPluvial.py
+│   ├── HdfPlot.py
+│   └── HdfResultsPlot.py
 ├── examples
 │   ├── 01_project_initialization.py
 │   ├── 02_plan_operations.py
@@ -225,10 +255,45 @@ plan_number = "01"
 runtime_data = RasHdf.get_runtime_data(plan_number, ras_object=custom_ras)
 print(runtime_data)
 ```
-
 This class simplifies the process of extracting and analyzing data from HEC-RAS HDF output files, supporting tasks such as post-processing and result visualization.
 
 
+### Infrastructure Analysis
+```python
+from ras_commander import HdfPipe, HdfPump
+
+# Analyze pipe network
+pipe_network = HdfPipe.get_pipe_network(hdf_path)
+conduits = HdfPipe.get_pipe_conduits(hdf_path)
+
+# Analyze pump stations
+pump_stations = HdfPump.get_pump_stations(hdf_path)
+pump_performance = HdfPump.get_pump_station_summary(hdf_path)
+```
+
+### Advanced Results Analysis
+```python
+from ras_commander import HdfResultsMesh
+
+# Get maximum water surface and velocity
+max_ws = HdfResultsMesh.get_mesh_max_ws(hdf_path)
+max_vel = HdfResultsMesh.get_mesh_max_face_v(hdf_path)
+
+# Visualize results
+from ras_commander import HdfResultsPlot
+HdfResultsPlot.plot_results_max_wsel(max_ws)
+```
+
+### Fluvial-Pluvial Analysis
+```python
+from ras_commander import HdfFluvialPluvial
+
+boundary = HdfFluvialPluvial.calculate_fluvial_pluvial_boundary(
+    hdf_path,
+    delta_t=12  # Time threshold in hours
+)
+
+
 ## Documentation
 
 For detailed usage instructions and API documentation, please refer to the [Comprehensive Library Guide](Comprehensive_Library_Guide.md).

{ras_commander-0.48.0 → ras_commander-0.49.0}/ras_commander/Decorators.py

@@ -16,7 +16,6 @@ def log_call(func):
         return result
     return wrapper
 
-
 def standardize_input(file_type: str = 'plan_hdf'):
     """
     Decorator to standardize input for HDF file operations.
@@ -41,6 +40,14 @@ def standardize_input(file_type: str = 'plan_hdf'):
         def wrapper(*args, **kwargs):
             logger = logging.getLogger(func.__module__)
             
+            # Check if the function expects an hdf_path parameter
+            sig = inspect.signature(func)
+            param_names = list(sig.parameters.keys())
+            
+            # If first parameter is 'hdf_file', skip path processing
+            if param_names and param_names[0] == 'hdf_file':
+                return func(*args, **kwargs)
+                
             # Handle both static method calls and regular function calls
             if args and isinstance(args[0], type):
                 # Static method call, remove the class argument
@@ -49,6 +56,16 @@ def standardize_input(file_type: str = 'plan_hdf'):
             hdf_input = kwargs.pop('hdf_path', None) or kwargs.pop('hdf_input', None) or (args[0] if args else None)
             ras_object = kwargs.pop('ras_object', None) or (args[1] if len(args) > 1 else None)
 
+            # If no hdf_input provided, return the function unmodified
+            if hdf_input is None:
+                return func(*args, **kwargs)
+
+            # NEW: If input is already a Path and exists, use it directly regardless of file_type
+            if isinstance(hdf_input, Path) and hdf_input.is_file():
+                logger.info(f"Using existing HDF file: {hdf_input}")
+                new_args = (hdf_input,) + args[1:]
+                return func(*new_args, **kwargs)
+
             hdf_path = None
 
             # If hdf_input is already an h5py.File object, use its filename

ras_commander-0.49.0/ras_commander/HdfBase.py

@@ -0,0 +1,307 @@
+"""
+HdfBase: Core HDF File Operations for HEC-RAS
+
+This module provides fundamental methods for interacting with HEC-RAS HDF files.
+It serves as a foundation for more specialized HDF classes.
+
+Attribution:
+    Derived from the rashdf library (https://github.com/fema-ffrd/rashdf)
+    Copyright (c) 2024 fema-ffrd - MIT License
+
+Features:
+    - Time parsing and conversion utilities
+    - HDF attribute and dataset access
+    - Geometric data extraction
+    - 2D flow area information retrieval
+
+Classes:
+    HdfBase: Base class containing static methods for HDF operations
+
+Key Methods:
+    Time Operations:
+        - get_simulation_start_time(): Get simulation start datetime
+        - get_unsteady_timestamps(): Get unsteady output timestamps
+        - parse_ras_datetime(): Parse RAS datetime strings
+    
+    Data Access:
+        - get_2d_flow_area_names_and_counts(): Get 2D flow area info
+        - get_projection(): Get spatial projection
+        - get_attrs(): Access HDF attributes
+        - get_dataset_info(): Explore HDF structure
+        - get_polylines_from_parts(): Extract geometric polylines
+
+Example:
+    ```python
+    from ras_commander import HdfBase
+    
+    with h5py.File('model.hdf', 'r') as hdf:
+        start_time = HdfBase.get_simulation_start_time(hdf)
+        timestamps = HdfBase.get_unsteady_timestamps(hdf)
+    ```
+"""
+import re
+from datetime import datetime, timedelta
+import h5py
+import numpy as np
+import pandas as pd
+import xarray as xr
+from typing import List, Tuple, Union, Optional, Dict, Any
+from pathlib import Path
+import logging
+from shapely.geometry import LineString, MultiLineString
+
+from .HdfUtils import HdfUtils
+from .Decorators import standardize_input, log_call
+from .LoggingConfig import setup_logging, get_logger
+
+logger = get_logger(__name__)
+
+class HdfBase:
+    """
+    Base class for HEC-RAS HDF file operations.
+
+    This class provides static methods for fundamental HDF file operations,
+    including time parsing, attribute access, and geometric data extraction.
+    All methods are designed to work with h5py.File objects or pathlib.Path
+    inputs.
+
+    Note:
+        This class is not meant to be instantiated. All methods are static
+        and should be called directly from the class.
+    """
+
+    @staticmethod
+    def get_simulation_start_time(hdf_file: h5py.File) -> datetime:
+        """
+        Extract the simulation start time from the HDF file.
+
+        Args:
+            hdf_file: Open HDF file object containing RAS simulation data.
+
+        Returns:
+            datetime: Simulation start time as a datetime object.
+
+        Raises:
+            ValueError: If Plan Information is not found or start time cannot be parsed.
+        
+        Note:
+            Expects 'Plan Data/Plan Information' group with 'Simulation Start Time' attribute.
+        """
+        plan_info = hdf_file.get("Plan Data/Plan Information")
+        if plan_info is None:
+            raise ValueError("Plan Information not found in HDF file")
+        time_str = plan_info.attrs.get('Simulation Start Time')
+        return HdfUtils.parse_ras_datetime(time_str.decode('utf-8'))
+
+    @staticmethod
+    def get_unsteady_timestamps(hdf_file: h5py.File) -> List[datetime]:
+        """
+        Extract the list of unsteady timestamps from the HDF file.
+
+        Args:
+            hdf_file (h5py.File): Open HDF file object.
+
+        Returns:
+            List[datetime]: A list of datetime objects representing the unsteady timestamps.
+        """
+        group_path = "Results/Unsteady/Output/Output Blocks/Base Output/Unsteady Time Series/Time Date Stamp (ms)"
+        raw_datetimes = hdf_file[group_path][:]
+        return [HdfUtils.parse_ras_datetime_ms(x.decode("utf-8")) for x in raw_datetimes]
+
+    @staticmethod
+    @standardize_input(file_type='plan_hdf')
+    def get_2d_flow_area_names_and_counts(hdf_path: Path) -> List[Tuple[str, int]]:
+        """
+        Get the names and cell counts of 2D flow areas from the HDF file.
+
+        Args:
+            hdf_path (Path): Path to the HDF file.
+
+        Returns:
+            List[Tuple[str, int]]: A list of tuples containing the name and cell count of each 2D flow area.
+
+        Raises:
+            ValueError: If there's an error reading the HDF file or accessing the required data.
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                flow_area_2d_path = "Geometry/2D Flow Areas"
+                if flow_area_2d_path not in hdf_file:
+                    return []
+                
+                attributes = hdf_file[f"{flow_area_2d_path}/Attributes"][()]
+                names = [HdfUtils.convert_ras_string(name) for name in attributes["Name"]]
+                
+                cell_info = hdf_file[f"{flow_area_2d_path}/Cell Info"][()]
+                cell_counts = [info[1] for info in cell_info]
+                
+                return list(zip(names, cell_counts))
+        except Exception as e:
+            logger.error(f"Error reading 2D flow area names and counts from {hdf_path}: {str(e)}")
+            raise ValueError(f"Failed to get 2D flow area names and counts: {str(e)}")
+
+    @staticmethod
+    @standardize_input(file_type='plan_hdf')
+    def get_projection(hdf_path: Path) -> Optional[str]:
+        """
+        Get the projection information from the HDF file.
+
+        Args:
+            hdf_path (Path): Path to the HDF file.
+
+        Returns:
+            Optional[str]: The projection information as a string, or None if not found.
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                proj_wkt = hdf_file.attrs.get("Projection")
+                if proj_wkt is None:
+                    return None
+                if isinstance(proj_wkt, bytes) or isinstance(proj_wkt, np.bytes_):
+                    proj_wkt = proj_wkt.decode("utf-8")
+                return proj_wkt
+        except Exception as e:
+            logger.error(f"Error reading projection from {hdf_path}: {str(e)}")
+            return None
+
+    @staticmethod
+    @standardize_input(file_type='plan_hdf')
+    def get_attrs(hdf_file: h5py.File, attr_path: str) -> Dict[str, Any]:
+        """
+        Get attributes from an HDF file at a specified path.
+
+        Args:
+            hdf_file (h5py.File): The opened HDF file.
+            attr_path (str): Path to the attributes in the HDF file.
+
+        Returns:
+            Dict[str, Any]: Dictionary of attributes.
+        """
+        try:
+            if attr_path not in hdf_file:
+                logger.warning(f"Path {attr_path} not found in HDF file")
+                return {}
+            
+            return HdfUtils.hdf5_attrs_to_dict(hdf_file[attr_path].attrs)
+        except Exception as e:
+            logger.error(f"Error getting attributes from {attr_path}: {str(e)}")
+            return {}
+
+    @staticmethod
+    @standardize_input(file_type='plan_hdf')
+    def get_dataset_info(file_path: Path, group_path: str = '/') -> None:
+        """
+        Recursively explore and print the structure of an HDF5 file.
+
+        Displays detailed information about groups, datasets, and their attributes
+        in a hierarchical format.
+
+        Args:
+            file_path: Path to the HDF5 file.
+            group_path: Starting group path to explore (default: root '/').
+
+        Prints:
+            - Group and dataset names with hierarchical indentation
+            - Dataset shapes and data types
+            - All attributes for groups and datasets
+        """
+        def recurse(name, obj, indent=0):
+            spacer = "    " * indent
+            if isinstance(obj, h5py.Group):
+                print(f"{spacer}Group: {name}")
+                HdfBase.print_attrs(name, obj)
+                for key in obj:
+                    recurse(f"{name}/{key}", obj[key], indent+1)
+            elif isinstance(obj, h5py.Dataset):
+                print(f"{spacer}Dataset: {name}")
+                print(f"{spacer}    Shape: {obj.shape}")
+                print(f"{spacer}    Dtype: {obj.dtype}")
+                HdfBase.print_attrs(name, obj)
+            else:
+                print(f"{spacer}Unknown object: {name}")
+
+        try:
+            with h5py.File(file_path, 'r') as hdf_file:
+                if group_path in hdf_file:
+                    print("")
+                    print(f"Exploring group: {group_path}\n")
+                    group = hdf_file[group_path]
+                    for key in group:
+                        print("")
+                        recurse(f"{group_path}/{key}", group[key], indent=1)
+                else:
+                    print(f"Group path '{group_path}' not found in the HDF5 file.")
+        except Exception as e:
+            print(f"Error exploring HDF5 file: {e}")
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_polylines_from_parts(hdf_path: Path, path: str, info_name: str = "Polyline Info", 
+                              parts_name: str = "Polyline Parts", 
+                              points_name: str = "Polyline Points") -> List[LineString]:
+        """
+        Extract polylines from HDF file parts data.
+
+        Args:
+            hdf_path: Path to the HDF file.
+            path: Internal HDF path to polyline data.
+            info_name: Name of polyline info dataset.
+            parts_name: Name of polyline parts dataset.
+            points_name: Name of polyline points dataset.
+
+        Returns:
+            List of Shapely LineString/MultiLineString geometries.
+
+        Note:
+            Expects HDF datasets containing:
+            - Polyline information (start points and counts)
+            - Parts information for multi-part lines
+            - Point coordinates
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                polyline_info_path = f"{path}/{info_name}"
+                polyline_parts_path = f"{path}/{parts_name}"
+                polyline_points_path = f"{path}/{points_name}"
+
+                polyline_info = hdf_file[polyline_info_path][()]
+                polyline_parts = hdf_file[polyline_parts_path][()]
+                polyline_points = hdf_file[polyline_points_path][()]
+
+                geoms = []
+                for pnt_start, pnt_cnt, part_start, part_cnt in polyline_info:
+                    points = polyline_points[pnt_start : pnt_start + pnt_cnt]
+                    if part_cnt == 1:
+                        geoms.append(LineString(points))
+                    else:
+                        parts = polyline_parts[part_start : part_start + part_cnt]
+                        geoms.append(
+                            MultiLineString(
+                                list(
+                                    points[part_pnt_start : part_pnt_start + part_pnt_cnt]
+                                    for part_pnt_start, part_pnt_cnt in parts
+                                )
+                            )
+                        )
+                return geoms
+        except Exception as e:
+            logger.error(f"Error getting polylines: {str(e)}")
+            return []
+
+    @staticmethod
+    def print_attrs(name: str, obj: Union[h5py.Dataset, h5py.Group]) -> None:
+        """
+        Print the attributes of an HDF5 object (Dataset or Group).
+
+        Args:
+            name (str): Name of the object
+            obj (Union[h5py.Dataset, h5py.Group]): HDF5 object whose attributes are to be printed
+        """
+        if len(obj.attrs) > 0:
+            print(f"    Attributes for {name}:")
+            for key, value in obj.attrs.items():
+                print(f"        {key}: {value}")
+
+
+