ras-commander 0.80.1__py3-none-any.whl → 0.80.3__py3-none-any.whl

ras_commander/HdfResultsPlan.py

@@ -6,14 +6,23 @@ Attribution:
     Copyright (c) 2024 fema-ffrd, MIT license
 
 Description:
-    Provides static methods for extracting unsteady flow results, volume accounting,
-    and reference data from HEC-RAS plan HDF files.
+    Provides static methods for extracting both unsteady and steady flow results,
+    volume accounting, and reference data from HEC-RAS plan HDF files.
 
 Available Functions:
-    - get_unsteady_info: Extract unsteady attributes
-    - get_unsteady_summary: Extract unsteady summary data
-    - get_volume_accounting: Extract volume accounting data
-    - get_runtime_data: Extract runtime and compute time data
+    Unsteady Flow:
+        - get_unsteady_info: Extract unsteady attributes
+        - get_unsteady_summary: Extract unsteady summary data
+        - get_volume_accounting: Extract volume accounting data
+        - get_runtime_data: Extract runtime and compute time data
+        - get_reference_timeseries: Extract reference line/point timeseries
+        - get_reference_summary: Extract reference line/point summary
+
+    Steady Flow:
+        - is_steady_plan: Check if HDF contains steady state results
+        - get_steady_profile_names: Extract steady state profile names
+        - get_steady_wse: Extract WSE data for steady state profiles
+        - get_steady_info: Extract steady flow attributes and metadata
 
 Note:
     All methods are static and designed to be used without class instantiation.
@@ -378,4 +387,326 @@ class HdfResultsPlan:
 
         except Exception as e:
             logger.error(f"Error reading reference {reftype} summary: {str(e)}")
-            return pd.DataFrame()
+            return pd.DataFrame()
+
+    # ==================== STEADY STATE METHODS ====================
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def is_steady_plan(hdf_path: Path) -> bool:
+        """
+        Check if HDF file contains steady state results.
+
+        Args:
+            hdf_path (Path): Path to HEC-RAS plan HDF file
+            ras_object (RasPrj, optional): Specific RAS object to use. If None, uses the global ras instance.
+
+        Returns:
+            bool: True if the HDF contains steady state results, False otherwise
+
+        Notes:
+            - Checks for existence of Results/Steady group
+            - Does not guarantee results are complete or valid
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                return "Results/Steady" in hdf_file
+        except Exception as e:
+            logger.error(f"Error checking if plan is steady: {str(e)}")
+            return False
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_steady_profile_names(hdf_path: Path) -> List[str]:
+        """
+        Extract profile names from steady state results.
+
+        Args:
+            hdf_path (Path): Path to HEC-RAS plan HDF file
+            ras_object (RasPrj, optional): Specific RAS object to use. If None, uses the global ras instance.
+
+        Returns:
+            List[str]: List of profile names (e.g., ['50Pct', '10Pct', '1Pct'])
+
+        Raises:
+            FileNotFoundError: If the specified HDF file is not found
+            KeyError: If steady state results or profile names are not found
+            ValueError: If the plan is not a steady state plan
+
+        Example:
+            >>> from ras_commander import HdfResultsPlan, init_ras_project
+            >>> init_ras_project(Path('/path/to/project'), '6.6')
+            >>> profiles = HdfResultsPlan.get_steady_profile_names('01')
+            >>> print(profiles)
+            ['50Pct', '20Pct', '10Pct', '4Pct', '2Pct', '1Pct', '0.2Pct']
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                # Check if this is a steady state plan
+                if "Results/Steady" not in hdf_file:
+                    raise ValueError(f"HDF file does not contain steady state results: {hdf_path.name}")
+
+                # Path to profile names
+                profile_names_path = "Results/Steady/Output/Output Blocks/Base Output/Steady Profiles/Profile Names"
+
+                if profile_names_path not in hdf_file:
+                    raise KeyError(f"Profile names not found at: {profile_names_path}")
+
+                # Read profile names dataset
+                profile_names_ds = hdf_file[profile_names_path]
+                profile_names_raw = profile_names_ds[()]
+
+                # Decode byte strings to regular strings
+                profile_names = []
+                for name in profile_names_raw:
+                    if isinstance(name, bytes):
+                        profile_names.append(name.decode('utf-8').strip())
+                    else:
+                        profile_names.append(str(name).strip())
+
+                logger.info(f"Found {len(profile_names)} steady state profiles: {profile_names}")
+                return profile_names
+
+        except FileNotFoundError:
+            raise FileNotFoundError(f"HDF file not found: {hdf_path}")
+        except KeyError as e:
+            raise KeyError(f"Error accessing steady state profile names: {str(e)}")
+        except Exception as e:
+            raise RuntimeError(f"Error reading steady state profile names: {str(e)}")
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_steady_wse(
+        hdf_path: Path,
+        profile_index: Optional[int] = None,
+        profile_name: Optional[str] = None
+    ) -> pd.DataFrame:
+        """
+        Extract water surface elevation (WSE) data for steady state profiles.
+
+        Args:
+            hdf_path (Path): Path to HEC-RAS plan HDF file
+            profile_index (int, optional): Index of profile to extract (0-based). If None, extracts all profiles.
+            profile_name (str, optional): Name of profile to extract (e.g., '1Pct'). If specified, overrides profile_index.
+            ras_object (RasPrj, optional): Specific RAS object to use. If None, uses the global ras instance.
+
+        Returns:
+            pd.DataFrame: DataFrame containing WSE data with columns:
+                - River: River name
+                - Reach: Reach name
+                - Station: Cross section river station
+                - Profile: Profile name (if multiple profiles)
+                - WSE: Water surface elevation (ft)
+
+        Raises:
+            FileNotFoundError: If the specified HDF file is not found
+            KeyError: If steady state results or WSE data are not found
+            ValueError: If profile_index or profile_name is invalid
+
+        Example:
+            >>> # Extract single profile by index
+            >>> wse_df = HdfResultsPlan.get_steady_wse('01', profile_index=5)  # 100-year profile
+
+            >>> # Extract single profile by name
+            >>> wse_df = HdfResultsPlan.get_steady_wse('01', profile_name='1Pct')
+
+            >>> # Extract all profiles
+            >>> wse_df = HdfResultsPlan.get_steady_wse('01')
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                # Check if this is a steady state plan
+                if "Results/Steady" not in hdf_file:
+                    raise ValueError(f"HDF file does not contain steady state results: {hdf_path.name}")
+
+                # Paths to data
+                wse_path = "Results/Steady/Output/Output Blocks/Base Output/Steady Profiles/Cross Sections/Water Surface"
+                xs_attrs_path = "Results/Steady/Output/Geometry Info/Cross Section Attributes"
+                profile_names_path = "Results/Steady/Output/Output Blocks/Base Output/Steady Profiles/Profile Names"
+
+                # Check required paths exist
+                if wse_path not in hdf_file:
+                    raise KeyError(f"WSE data not found at: {wse_path}")
+                if xs_attrs_path not in hdf_file:
+                    raise KeyError(f"Cross section attributes not found at: {xs_attrs_path}")
+
+                # Get WSE dataset (shape: num_profiles × num_cross_sections)
+                wse_ds = hdf_file[wse_path]
+                wse_data = wse_ds[()]
+                num_profiles, num_xs = wse_data.shape
+
+                # Get profile names
+                if profile_names_path in hdf_file:
+                    profile_names_raw = hdf_file[profile_names_path][()]
+                    profile_names = [
+                        name.decode('utf-8').strip() if isinstance(name, bytes) else str(name).strip()
+                        for name in profile_names_raw
+                    ]
+                else:
+                    # Fallback to numbered profiles
+                    profile_names = [f"Profile_{i+1}" for i in range(num_profiles)]
+
+                # Get cross section attributes
+                xs_attrs = hdf_file[xs_attrs_path][()]
+
+                # Determine which profiles to extract
+                if profile_name is not None:
+                    # Find profile by name
+                    try:
+                        profile_idx = profile_names.index(profile_name)
+                    except ValueError:
+                        raise ValueError(
+                            f"Profile name '{profile_name}' not found. "
+                            f"Available profiles: {profile_names}"
+                        )
+                    profiles_to_extract = [(profile_idx, profile_name)]
+
+                elif profile_index is not None:
+                    # Validate profile index
+                    if profile_index < 0 or profile_index >= num_profiles:
+                        raise ValueError(
+                            f"Profile index {profile_index} out of range. "
+                            f"Valid range: 0 to {num_profiles-1}"
+                        )
+                    profiles_to_extract = [(profile_index, profile_names[profile_index])]
+
+                else:
+                    # Extract all profiles
+                    profiles_to_extract = list(enumerate(profile_names))
+
+                # Build DataFrame
+                rows = []
+                for prof_idx, prof_name in profiles_to_extract:
+                    wse_values = wse_data[prof_idx, :]
+
+                    for xs_idx in range(num_xs):
+                        river = xs_attrs[xs_idx]['River']
+                        reach = xs_attrs[xs_idx]['Reach']
+                        station = xs_attrs[xs_idx]['Station']
+
+                        # Decode byte strings
+                        river = river.decode('utf-8') if isinstance(river, bytes) else str(river)
+                        reach = reach.decode('utf-8') if isinstance(reach, bytes) else str(reach)
+                        station = station.decode('utf-8') if isinstance(station, bytes) else str(station)
+
+                        row = {
+                            'River': river.strip(),
+                            'Reach': reach.strip(),
+                            'Station': station.strip(),
+                            'WSE': float(wse_values[xs_idx])
+                        }
+
+                        # Only add Profile column if extracting multiple profiles
+                        if len(profiles_to_extract) > 1:
+                            row['Profile'] = prof_name
+
+                        rows.append(row)
+
+                df = pd.DataFrame(rows)
+
+                # Reorder columns
+                if 'Profile' in df.columns:
+                    df = df[['River', 'Reach', 'Station', 'Profile', 'WSE']]
+                else:
+                    df = df[['River', 'Reach', 'Station', 'WSE']]
+
+                logger.info(
+                    f"Extracted WSE data for {len(profiles_to_extract)} profile(s), "
+                    f"{num_xs} cross sections"
+                )
+
+                return df
+
+        except FileNotFoundError:
+            raise FileNotFoundError(f"HDF file not found: {hdf_path}")
+        except KeyError as e:
+            raise KeyError(f"Error accessing steady state WSE data: {str(e)}")
+        except Exception as e:
+            raise RuntimeError(f"Error reading steady state WSE data: {str(e)}")
+
+    @staticmethod
+    @log_call
+    @standardize_input(file_type='plan_hdf')
+    def get_steady_info(hdf_path: Path) -> pd.DataFrame:
+        """
+        Get steady flow attributes and metadata from HEC-RAS HDF plan file.
+
+        Args:
+            hdf_path (Path): Path to HEC-RAS plan HDF file
+            ras_object (RasPrj, optional): Specific RAS object to use. If None, uses the global ras instance.
+
+        Returns:
+            pd.DataFrame: DataFrame containing steady flow attributes including:
+                - Program Name
+                - Program Version
+                - Type of Run
+                - Run Time Window
+                - Solution status
+                - And other metadata attributes
+
+        Raises:
+            FileNotFoundError: If the specified HDF file is not found
+            KeyError: If steady state results are not found
+            ValueError: If the plan is not a steady state plan
+
+        Example:
+            >>> info_df = HdfResultsPlan.get_steady_info('01')
+            >>> print(info_df['Solution'].values[0])
+            'Steady Finished Successfully'
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                # Check if this is a steady state plan
+                if "Results/Steady" not in hdf_file:
+                    raise ValueError(f"HDF file does not contain steady state results: {hdf_path.name}")
+
+                attrs_dict = {}
+
+                # Get attributes from Results/Steady/Output
+                output_path = "Results/Steady/Output"
+                if output_path in hdf_file:
+                    output_group = hdf_file[output_path]
+                    for key, value in output_group.attrs.items():
+                        if isinstance(value, bytes):
+                            attrs_dict[key] = value.decode('utf-8')
+                        else:
+                            attrs_dict[key] = value
+
+                # Get attributes from Results/Steady/Summary
+                summary_path = "Results/Steady/Summary"
+                if summary_path in hdf_file:
+                    summary_group = hdf_file[summary_path]
+                    for key, value in summary_group.attrs.items():
+                        if isinstance(value, bytes):
+                            attrs_dict[key] = value.decode('utf-8')
+                        else:
+                            attrs_dict[key] = value
+
+                # Add flow file information from Plan Data
+                plan_info_path = "Plan Data/Plan Information"
+                if plan_info_path in hdf_file:
+                    plan_info = hdf_file[plan_info_path]
+                    for key in ['Flow Filename', 'Flow Title']:
+                        if key in plan_info.attrs:
+                            value = plan_info.attrs[key]
+                            if isinstance(value, bytes):
+                                attrs_dict[key] = value.decode('utf-8')
+                            else:
+                                attrs_dict[key] = value
+
+                if not attrs_dict:
+                    logger.warning("No steady state attributes found in HDF file")
+                    return pd.DataFrame()
+
+                logger.info(f"Extracted {len(attrs_dict)} steady state attributes")
+                return pd.DataFrame(attrs_dict, index=[0])
+
+        except FileNotFoundError:
+            raise FileNotFoundError(f"HDF file not found: {hdf_path}")
+        except KeyError as e:
+            raise KeyError(f"Error accessing steady state info: {str(e)}")
+        except Exception as e:
+            raise RuntimeError(f"Error reading steady state info: {str(e)}")

ras_commander/RasExamples.py

@@ -128,11 +128,14 @@ class RasExamples:
         self._save_to_csv()
 
     @classmethod
-    def extract_project(cls, project_names: Union[str, List[str]]) -> Union[Path, List[Path]]:
+    def extract_project(cls, project_names: Union[str, List[str]], output_path: Union[str, Path] = None) -> Union[Path, List[Path]]:
         """Extract one or more specific HEC-RAS projects from the zip file.
         
         Args:
             project_names: Single project name as string or list of project names
+            output_path: Optional path where the project folder will be placed.
+                        Can be a relative path (creates subfolder in current directory)
+                        or an absolute path. If None, uses default 'example_projects' folder.
             
         Returns:
             Path: Single Path object if one project extracted
@@ -151,13 +154,26 @@ class RasExamples:
         if isinstance(project_names, str):
             project_names = [project_names]
 
+        # Determine the output directory
+        if output_path is None:
+            # Use default 'example_projects' folder
+            base_output_path = cls.projects_dir
+        else:
+            # Convert to Path object
+            base_output_path = Path(output_path)
+            # If relative path, make it relative to current working directory
+            if not base_output_path.is_absolute():
+                base_output_path = Path.cwd() / base_output_path
+            # Create the directory if it doesn't exist
+            base_output_path.mkdir(parents=True, exist_ok=True)
+
         extracted_paths = []
 
         for project_name in project_names:
             # Check if this is a special project
             if project_name in cls.SPECIAL_PROJECTS:
                 try:
-                    special_path = cls._extract_special_project(project_name)
+                    special_path = cls._extract_special_project(project_name, base_output_path)
                     extracted_paths.append(special_path)
                     continue
                 except Exception as e:
@@ -167,7 +183,7 @@ class RasExamples:
             # Regular project extraction logic
             logger.info("----- RasExamples Extracting Project -----")
             logger.info(f"Extracting project '{project_name}'")
-            project_path = cls.projects_dir
+            project_path = base_output_path
 
             if (project_path / project_name).exists():
                 logger.info(f"Project '{project_name}' already exists. Deleting existing folder...")
@@ -447,12 +463,13 @@ class RasExamples:
         return int(number * units[unit])
 
     @classmethod
-    def _extract_special_project(cls, project_name: str) -> Path:
+    def _extract_special_project(cls, project_name: str, output_path: Path = None) -> Path:
         """
         Download and extract special projects that are not in the main zip file.
         
         Args:
             project_name: Name of the special project ('NewOrleansMetro' or 'BeaverLake')
+            output_path: Base output directory path. If None, uses cls.projects_dir
             
         Returns:
             Path: Path to the extracted project directory
@@ -466,8 +483,11 @@ class RasExamples:
         logger.info(f"----- RasExamples Extracting Special Project -----")
         logger.info(f"Extracting special project '{project_name}'")
         
+        # Use provided output_path or default
+        base_path = output_path if output_path else cls.projects_dir
+        
         # Create the project directory
-        project_path = cls.projects_dir / project_name
+        project_path = base_path / project_name
         
         # Check if already exists
         if project_path.exists():
@@ -484,7 +504,7 @@ class RasExamples:
         
         # Download the zip file
         url = cls.SPECIAL_PROJECTS[project_name]
-        zip_file_path = cls.projects_dir / f"{project_name}_temp.zip"
+        zip_file_path = base_path / f"{project_name}_temp.zip"
         
         logger.info(f"Downloading special project from: {url}")
         logger.info("This may take a few moments...")

ras_commander/RasPrj.py

@@ -204,10 +204,19 @@ class RasPrj:
             
             # Set paths for geometry and flow files
             self._set_file_paths()
-            
+
             # Make sure all plan paths are properly set
             self._set_plan_paths()
-            
+
+            # Add flow_type column for deterministic steady/unsteady identification
+            if not self.plan_df.empty and 'unsteady_number' in self.plan_df.columns:
+                self.plan_df['flow_type'] = self.plan_df['unsteady_number'].apply(
+                    lambda x: 'Unsteady' if pd.notna(x) else 'Steady'
+                )
+            else:
+                if not self.plan_df.empty:
+                    self.plan_df['flow_type'] = 'Unknown'
+
         except Exception as e:
             logger.error(f"Error loading project data: {e}")
             raise

ras_commander/__init__.py

@@ -10,7 +10,7 @@ try:
     __version__ = version("ras-commander")
 except PackageNotFoundError:
     # package is not installed
-    __version__ = "0.80.1"
+    __version__ = "0.80.3"
 
 # Set up logging
 setup_logging()

{ras_commander-0.80.1.dist-info → ras_commander-0.80.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ras-commander
-Version: 0.80.1
+Version: 0.80.3
 Summary: A Python library for automating HEC-RAS 6.x operations
 Home-page: https://github.com/gpt-cmdr/ras-commander
 Author: William M. Katzenmeyer, P.E., C.F.M.

{ras_commander-0.80.1.dist-info → ras_commander-0.80.3.dist-info}/RECORD

@@ -9,7 +9,7 @@ ras_commander/HdfPlan.py,sha256=WINI3lp865cE99QXztgvKKIhVUTOqu4X41ZPBfhYJGU,1214
 ras_commander/HdfPlot.py,sha256=7MNI5T9qIz-Ava1RdlnB6O9oJElE5BEB29QVF5Y2Xuc,3401
 ras_commander/HdfPump.py,sha256=Vc2ff16kRISR7jwtnaAqxI0p-gfBSuZKzR3rQbBLQoE,12951
 ras_commander/HdfResultsMesh.py,sha256=FIUN_yZ6h1XrcaHuOdAQrozOBN_UKNNn3_l8lO703dk,44172
-ras_commander/HdfResultsPlan.py,sha256=gmeAceYHABubv0V8dJL2F5GN4Th7g92E_1y-Hc4JZjg,16626
+ras_commander/HdfResultsPlan.py,sha256=wsIUTyBFowJXeNwMsX0cZ00srqJDEwx5wENPpJLzatw,31479
 ras_commander/HdfResultsPlot.py,sha256=ylzfT78CfgoDO0XAlRwlgMNRzvNQYBMn9eyXyBfjv_w,7660
 ras_commander/HdfResultsXsec.py,sha256=-P7nXnbjOLAeUnrdSC_lJQSfzrlWKmDF9Z5gEjmxbJY,13031
 ras_commander/HdfStruc.py,sha256=SznjPvBWiqNVtviZvfCdjB_iwZF4UXxlIxITD8kwjP4,13733
@@ -17,16 +17,16 @@ ras_commander/HdfUtils.py,sha256=VkIKAXBrLwTlk2VtXSO-W3RU-NHpfHbE1QcZUZgl-t8,152
 ras_commander/HdfXsec.py,sha256=4DuJvzTTtn4zGcf1lv_TyWyRnYRnR_SE-iWFKix5QzM,27776
 ras_commander/LoggingConfig.py,sha256=gWe5K5XTmMQpSczsTysAqpC9my24i_IyM8dvD85fxYg,2704
 ras_commander/RasCmdr.py,sha256=37GnchoQ0fIAkPnssnCr1mRUXY8gm-hIMTmuHZlnYP8,34591
-ras_commander/RasExamples.py,sha256=oOI9id_98anyrTqqpnYbbs5VX7q1E0P-cC4wzqT3OTg,23411
+ras_commander/RasExamples.py,sha256=QFWnWnxACpQzewzA3QFMp4z4iEkg5PWf9cPDdMay7MA,24556
 ras_commander/RasGeo.py,sha256=Wy5N1yP7_St3cA3ENJliojQ2sb2w2dL8Fy8L_sZsykc,22208
 ras_commander/RasMap.py,sha256=20db61KkUz2CgjfCCYY8F-IYy5doHOtdnTKChiK0ENs,20257
 ras_commander/RasPlan.py,sha256=ogIpLqawXTsjLnKRZTqzZydn_EFVJZFZZGgHvJ_t_-c,65408
-ras_commander/RasPrj.py,sha256=oXPWuNC_403mUfqyysXyBVul0Xtz_0SKDxZdj4fvNYU,63448
+ras_commander/RasPrj.py,sha256=g9J_ewWrT0K1OP4BdEauU6VWq67m_JUqFXEr1AVIy2k,63893
 ras_commander/RasUnsteady.py,sha256=PdQQMiY7Mz1EsOQk6ygFQtlC2sFEa96Ntg-pznWVpLQ,37187
 ras_commander/RasUtils.py,sha256=0fm4IIs0LH1dgDj3pGd66mR82DhWLEkRKUvIo2M_5X0,35886
-ras_commander/__init__.py,sha256=JmYJNBvz2d0uf4YQXZbzoz6r8tVTudGzYDqFJ4BjBEE,2039
-ras_commander-0.80.1.dist-info/licenses/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
-ras_commander-0.80.1.dist-info/METADATA,sha256=zmpEsbQW0pNls6pvFCA490KtIqmBSGQKi3hNCKDj8OU,27941
-ras_commander-0.80.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ras_commander-0.80.1.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
-ras_commander-0.80.1.dist-info/RECORD,,
+ras_commander/__init__.py,sha256=v_fxJffY8lF74jv5gaihsKcLNE-b37dr5uJ6GvLx-Co,2039
+ras_commander-0.80.3.dist-info/licenses/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
+ras_commander-0.80.3.dist-info/METADATA,sha256=kiXYlVO31V56GC9n0JmU-tjQucNV5yHnXyKqloi65bY,27941
+ras_commander-0.80.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ras_commander-0.80.3.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
+ras_commander-0.80.3.dist-info/RECORD,,