ras-commander 0.1.0__py2.py3-none-any.whl

ras_commander/utilities.py

@@ -0,0 +1,195 @@
+"""
+Utility functions for the ras_commander library.
+"""
+import shutil
+import logging
+import time
+from pathlib import Path
+from .project_config import ProjectConfig
+
+class Utilities:
+    """
+    A class containing the utility functions for the ras_commander library.
+    When integrating new functions that do not clearly fit into other classes, add them here.
+    """
+    @staticmethod
+    def create_backup(file_path, backup_suffix="_backup"):
+        """
+        Create a backup of the specified file.
+        Parameters:
+        file_path (str): Path to the file to be backed up
+        backup_suffix (str): Suffix to append to the backup file name
+        Returns:
+        str: Path to the created backup file
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        original_path = Path(file_path)
+        backup_path = original_path.with_name(f"{original_path.stem}{backup_suffix}{original_path.suffix}")
+        shutil.copy2(original_path, backup_path)
+        print(f"Backup created: {backup_path}")
+        return str(backup_path)
+
+    @staticmethod
+    def restore_from_backup(backup_path, remove_backup=True):
+        """
+        Restore a file from its backup.
+        Parameters:
+        backup_path (str): Path to the backup file
+        remove_backup (bool): Whether to remove the backup file after restoration
+        Returns:
+        str: Path to the restored file
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        backup_path = Path(backup_path)
+        original_path = backup_path.with_name(backup_path.stem.rsplit('_backup', 1)[0] + backup_path.suffix)
+        shutil.copy2(backup_path, original_path)
+        print(f"File restored: {original_path}")
+        if remove_backup:
+            backup_path.unlink()
+            print(f"Backup removed: {backup_path}")
+        return str(original_path)
+
+    @staticmethod
+    def safe_remove(file_path):
+        """
+        Safely remove a file if it exists.
+        Parameters:
+        file_path (str): Path to the file to be removed
+        Returns:
+        bool: True if the file was removed, False if it didn't exist
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        path = Path(file_path)
+        if path.exists():
+            path.unlink()
+            print(f"File removed: {path}")
+            return True
+        else:
+            print(f"File not found: {path}")
+            return False
+
+    @staticmethod
+    def ensure_directory(directory_path):
+        """
+        Ensure that a directory exists, creating it if necessary.
+        Parameters:
+        directory_path (str): Path to the directory
+        Returns:
+        str: Path to the ensured directory
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        path = Path(directory_path)
+        path.mkdir(parents=True, exist_ok=True)
+        print(f"Directory ensured: {path}")
+        return str(path)
+
+    @staticmethod
+    def list_files_with_extension(extension):
+        """
+        List all files in the project directory with a specific extension.
+        Parameters:
+        extension (str): File extension to filter (e.g., '.prj')
+        Returns:
+        list: List of file paths matching the extension
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        files = list(config.project_folder.glob(f"*{extension}"))
+        return [str(file) for file in files]
+
+    @staticmethod
+    def get_file_size(file_path):
+        """
+        Get the size of a file in bytes.
+        Parameters:
+        file_path (str): Path to the file
+        Returns:
+        int: Size of the file in bytes
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        path = Path(file_path)
+        if path.exists():
+            size = path.stat().st_size
+            print(f"File size: {size} bytes")
+            return size
+        else:
+            print(f"File not found: {path}")
+            return None
+
+    @staticmethod
+    def get_modification_time(file_path):
+        """
+        Get the last modification time of a file.
+        Parameters:
+        file_path (str): Path to the file
+        Returns:
+        float: Last modification time as a timestamp
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        path = Path(file_path)
+        if path.exists():
+            mtime = path.stat().st_mtime
+            print(f"Last modified: {mtime}")
+            return mtime
+        else:
+            print(f"File not found: {path}")
+            return None
+
+    @staticmethod
+    def get_plan_path(current_plan_number):
+        """
+        Get the path for a plan file with a given plan number.
+        Parameters:
+        current_plan_number (str or int): The plan number (01 to 99)
+        Returns:
+        str: Full path to the plan file with the given plan number
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        current_plan_number = f"{int(current_plan_number):02d}"  # Ensure two-digit format
+        plan_name = f"{config.project_name}.p{current_plan_number}"
+        return str(config.project_folder / plan_name)
+
+    @staticmethod
+    def retry_remove_folder(folder_path: str, max_attempts: int = 5, initial_delay: float = 1.0) -> bool:
+        """
+        Attempts to remove a folder with retry logic and exponential backoff.
+        Args:
+            folder_path (str): Path to the folder to be removed.
+            max_attempts (int): Maximum number of removal attempts.
+            initial_delay (float): Initial delay between attempts in seconds.
+        Returns:
+            bool: True if the folder was successfully removed, False otherwise.
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        folder = Path(folder_path)
+        for attempt in range(max_attempts):
+            try:
+                if folder.exists():
+                    shutil.rmtree(folder)
+                return True
+            except PermissionError:
+                if attempt < max_attempts - 1:
+                    delay = initial_delay * (2 ** attempt)  # Exponential backoff
+                    logging.warning(f"Failed to remove folder {folder}. Retrying in {delay} seconds...")
+                    time.sleep(delay)
+                else:
+                    logging.error(f"Failed to remove folder {folder} after {max_attempts} attempts. Skipping.")
+                    return False
+        return False

ras_commander-0.1.0.dist-info/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2024 William M. Katzenmeyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.

ras_commander-0.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.1
+Name: ras_commander
+Version: 0.1.0
+Summary: A library for automating HEC-RAS operations using python functions.
+Home-page: https://github.com/yourusername/ras_commander
+Author: William Katzenmeyer, P.E., C.F.M.
+Author-email: heccommander@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+
+## RAS-Commander Library Organization
+
+| Directory/File | Purpose |
+|---|---|
+| ras_commander/__init__.py | Initializes the library and defines the public API. |
+| ras_commander/execution.py | Handles execution of HEC-RAS simulations. |
+| ras_commander/file_operations.py | Provides functions for reading and parsing HEC-RAS project files. |
+| ras_commander/geometry_operations.py | Provides functions for manipulating geometry files. |
+| ras_commander/plan_operations.py | Provides functions for modifying and updating plan files. |
+| ras_commander/project_config.py | Defines the ProjectConfig class for managing project-level information. |
+| ras_commander/project_init.py | Provides the `init_ras_project` function to initialize a project. |
+| ras_commander/project_management.py | Provides functions for managing HEC-RAS projects (e.g., copying files, updating project file). |
+| ras_commander/project_setup.py | Provides helper functions for project setup (e.g., finding project file, loading project data). |
+| ras_commander/unsteady_operations.py | Provides functions for manipulating unsteady flow files. |
+| ras_commander/utilities.py | Provides general utility functions (e.g., file backup, directory creation). |
+
+
+## Project Organization Diagram
+
+```
+ras_commander
+├── execution.py
+├── file_operations.py
+├── geometry_operations.py
+├── plan_operations.py
+├── project_config.py
+├── project_init.py
+├── project_management.py
+├── project_setup.py
+├── unsteady_operations.py
+└── utilities.py
+```
+
+## Functions Overview
+
+| Function | Arguments | Purpose |
+|---|---|---|
+| `init_ras_project` | `ras_project_folder`, `hecras_exe_path` | Initializes a HEC-RAS project by setting up the `ProjectConfig` with project details. |
+| `compute_hecras_plan` | `plan_file` | Executes a HEC-RAS plan file. |
+| `compute_hecras_plan_from_folder` | `test_plan_file`, `test_folder_path` | Execute a single HEC-RAS plan from a folder other than the project path.
+| `recreate_test_function` | `project_folder` | Recreates the -test function from the HEC-RAS interface, primarily by copying the project directory, forcing recomputation, and running each plan. |
+| `run_plans_parallel` | `config`, `max_workers`, `cores_per_run` | Run HEC-RAS plans in parallel. |
+| `run_all_plans_parallel` | `project_folder`, `hecras_exe_path` | Run all HEC-RAS plans in parallel from a project folder path. | 
+| `find_hecras_project_file` | `folder_path` | Locates the HEC-RAS project file (.prj) within a given folder. |
+| `get_project_name` | `project_path` | Extracts the project name from the project file path. |
+| `get_plan_entries` | `project_file` | Parses the project file to extract plan file information into a DataFrame. |
+| `get_flow_entries` | `project_file` | Parses the project file to extract steady flow file information into a DataFrame. |
+| `get_unsteady_entries` | `project_file` | Parses the project file to extract unsteady flow file information into a DataFrame. |
+| `get_geom_entries` | `project_file` | Parses the project file to extract geometry file information into a DataFrame. |
+| `clear_geometry_preprocessor_files` | `plan_file` | Deletes the geometry preprocessor files (.cXX) associated with a plan file. |
+| `clear_geometry_preprocessor_files_for_all_plans` |  | Deletes geometry preprocessor files for all plans in the project directory. |
+| `copy_geometry_files` | `dst_folder`, `template_geom` | Copies geometry files from a template to a destination folder, assigning the next available geometry number. |
+| `rename_geometry_files` | `old_number`, `new_number` | Renames geometry files (both .gXX and .gXX.hdf) in the project folder. |
+| `update_geometry_reference_in_plan` | `plan_file`, `new_geometry_number` | Updates the "Geom File=" entry in a plan file to reference a new geometry number. |
+| `apply_geometry_to_plan` | `plan_file`, `geometry_number` | Sets the geometry file used by a plan file. |
+| `apply_flow_to_plan` | `plan_file`, `flow_number` | Sets the steady flow file used by a plan file. |
+| `copy_plan_from_template` | `template_plan` | Creates a new plan file by copying a template and updates the project file with the new plan entry. |
+| `get_next_available_number` | `existing_numbers` | Finds the next available number (e.g., for plans, unsteady flows) based on existing ones. |
+| `apply_unsteady_to_plan` | `plan_file`, `unsteady_number` | Sets the unsteady flow file used by a plan file. |
+| `set_num_cores` | `plan_file`, `num_cores` | Sets the maximum number of cores to be used for a plan file. |
+| `update_geompre_flags` | `file_path`, `run_htab_value`, `use_ib_tables_value` | Updates the geometry preprocessor flags in a plan file. |
+| `get_plan_full_path` | `plan_number` | Returns the full path to a plan file based on its number. |
+| `get_results_full_path` | `plan_number` | Returns the full path to a plan's results file (.hdf) based on its number. |
+| `get_flow_full_path` | `flow_number` | Returns the full path to a steady flow file based on its number. |
+| `get_unsteady_full_path` | `unsteady_number` | Returns the full path to an unsteady flow file based on its number. |
+| `get_geom_full_path` | `geometry_number` | Returns the full path to a geometry file based on its number. |
+| `copy_unsteady_files` | `dst_folder`, `template_unsteady` | Copies unsteady flow files from a template to a destination folder, assigning the next available unsteady number. |
+| `rename_unsteady_files` | `old_number`, `new_number` | Renames unsteady flow files (both .uXX and .uXX.hdf) in the project folder. |
+| `update_unsteady_reference_in_plan` | `plan_file`, `new_unsteady_number` | Updates the "Unsteady File=" entry in a plan file to reference a new unsteady flow number. |
+| `modify_unsteady_flow_parameters` | `unsteady_file`, `modifications` | Modifies parameters within an unsteady flow file based on a dictionary of changes. |
+| `create_backup` | `file_path`, `backup_suffix` | Creates a backup copy of a file. |
+| `restore_from_backup` | `backup_path`, `remove_backup` | Restores a file from a backup copy. |
+| `safe_remove` | `file_path` | Removes a file if it exists, handling potential errors. |
+| `ensure_directory` | `directory_path` | Creates a directory if it does not exist. |
+| `list_files_with_extension` | `extension` | Lists files with a specific extension in the project directory. |
+| `get_file_size` | `file_path` | Returns the size of a file in bytes. |
+| `get_modification_time` | `file_path` | Returns the last modification time of a file. |
+| `get_plan_path` | `current_plan_number` | Returns the full path to a plan file based on its number. |
+| `retry_remove_folder` | `folder_path`, `max_attempts`, `initial_delay` | Attempts to remove a folder with retry and a delay. |
+
+
+
+## Potential Uses of RAS-Commander Functions
+
+The RAS-Commander library offers a wide range of functionalities that can be used to automate various aspects of HEC-RAS modeling workflows. Here are some potential uses:
+
+**1. Automated Plan Creation and Execution:**
+
+* **Batch processing of multiple scenarios:** RAS-Commander allows you to create new plan files based on templates, modify plan parameters (e.g., geometry, flow, unsteady flow files, number of cores), and execute them in parallel. This can be useful for analyzing multiple scenarios with different inputs or model configurations.
+* **Sensitivity analysis and optimization:** By combining RAS-Commander with other libraries (e.g., for parameter sampling or optimization), you can automate sensitivity analysis and parameter optimization studies.
+* **Monte Carlo simulations:** RAS-Commander can be used to automate the execution of Monte Carlo simulations by creating multiple plan files with randomly sampled input parameters.
+
+**2. Project Management and Organization:**
+
+* **Automated file management:** Functions for copying, renaming, and updating file references help maintain consistency and organization within your HEC-RAS project.
+* **Backup and restore functionalities:** Ensure project integrity by creating backups of project files and restoring them when needed.
+* **Project setup and initialization:** Streamline the process of setting up new HEC-RAS projects with standardized configurations.
+
+**3. Advanced Modeling Techniques:**
+
+* **Coupled modeling:** RAS-Commander can be used to automate the setup and execution of coupled models (e.g., HEC-RAS with other hydrodynamic or hydrologic models).
+* **Data assimilation and calibration:** By integrating RAS-Commander with data assimilation or calibration tools, you can automate the process of updating model parameters based on observed data.
+* **Post-processing and analysis:** RAS-Commander can be used to extract results from HEC-RAS output files and perform post-processing and analysis tasks.
+
+
+**4. Integration with Other Tools:**
+
+* **Python scripting and automation:** RAS-Commander can be easily integrated into Python scripts and workflows for more complex automation tasks.
+* **Web applications and dashboards:** Develop web applications and dashboards that allow users to interact with HEC-RAS models and visualize results through a user-friendly interface.
+* **Integration with GIS software:** RAS-Commander can be used to link HEC-RAS models with GIS software for spatial analysis and visualization.
+
+
+**Examples:**
+
+* **Floodplain mapping:** Automate the creation of floodplain maps for different return periods by creating and executing multiple plan files with varying flow conditions.
+* **Dam break analysis:** Automate the setup and execution of dam break simulations by modifying unsteady flow parameters and boundary conditions.
+* **Bridge scour analysis:** Automate the assessment of bridge scour potential by integrating HEC-RAS with bridge scour analysis tools.
+
+
+By automating repetitive tasks and providing a framework for managing complex workflows, RAS-Commander can significantly improve the efficiency and reproducibility of HEC-RAS modeling projects. This can lead to better decision-making and more accurate and reliable results. 

ras_commander-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+ras_commander/__init__.py,sha256=FGdtPP0qfQ_F0psnuLpL5txmhvqhkV9-40DZ1dEhpBI,655
+ras_commander/execution.py,sha256=hq2K4pIcAgch-zvV_nezxw9OpdOEenePxqWbCPFuSpw,13960
+ras_commander/file_operations.py,sha256=ufi00mh52C9-off_tA0aMp3U4mm066gMkwPZYiFN8hg,7274
+ras_commander/geometry_operations.py,sha256=-HhYTNEFmR64MLlfa7hxogJBCHw4iBScGFMTQLfDlJg,6961
+ras_commander/plan_operations.py,sha256=I0r-4QnhSqfehy63xcreKSnE-ozzv3R-4HyO-9c3dSI,12496
+ras_commander/project_config.py,sha256=zbSwSVt8F9v77QEjRUjMbLBxisiimmQO2mf7eb4juvc,2886
+ras_commander/project_init.py,sha256=6eCHtqaKTXb5AK47Brs8o0fNCa0e3Jmh3QvyVhzp7n8,8330
+ras_commander/project_management.py,sha256=CplIJ36ZIukm45Re9T2wQ_v96CqC9150upN06JvqYK8,9730
+ras_commander/project_setup.py,sha256=nJXbi0WHwdoJsP50R2vNtL0eil5PUXZv379KiL40KPA,673
+ras_commander/unsteady_operations.py,sha256=QBXUO2Mw3yzk7K9piu-Q39D_yI3BDUqLY0gweofrIWc,6808
+ras_commander/utilities.py,sha256=-UeGrrWl_xp4WTROmqZliojmunMgWW7jqPM8KN4p_1Q,6807
+ras_commander-0.1.0.dist-info/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
+ras_commander-0.1.0.dist-info/METADATA,sha256=-iFeNHkytgdvbjvDLXB68u3Xm8gOGNBSH7n2cO0hjpI,10903
+ras_commander-0.1.0.dist-info/WHEEL,sha256=XRxW4r1PNiVhMpP4bT9oWtu3HyndxpJ84SkubFgzp_Y,109
+ras_commander-0.1.0.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
+ras_commander-0.1.0.dist-info/RECORD,,

ras_commander-0.1.0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (72.1.0)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

ras_commander-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ras_commander