ras-commander 0.1.6__tar.gz → 0.21.0__tar.gz

ras_commander-0.21.0/.cursorrules.txt

@@ -0,0 +1,118 @@
+# RAS Commander (ras_commander) Coding Assistant
+
+## Overview
+
+This Coding Assistant helps you write efficient and well-structured Python code for working with HEC-RAS projects using the ras_commander library.
+
+**Key Features:**
+
+* **Automates HEC-RAS tasks:** Streamlines project setup, plan execution, data management, and more.
+* **Pythonic interface:** Leverages familiar Python libraries like Pandas and pathlib for intuitive coding.
+* **Flexible execution:** Supports single plan, sequential, and parallel execution modes.
+* **Built-in examples:** Provides access to HEC-RAS example projects for learning and testing.
+
+**Core Concepts:**
+
+* **RAS Objects:** Represent HEC-RAS projects and their components (plans, geometry, flow files).
+* **Project Initialization:** Use `init_ras_project()` to set up a project.
+* **File Handling:** pathlib.Path ensures consistent file path management.
+* **Data Management:** Pandas DataFrames organize project data.
+* **Execution Modes:**  Choose from single, sequential, or parallel execution.
+
+
+## Classes, Functions and Arguments for ras_commander
+
+The ras_commander library provides several classes to interact with HEC-RAS projects:
+
+Class/Function	Required Arguments	Optional Arguments
+RasPrj		
+init_ras_project	ras_project_folder, ras_version	ras_instance
+get_ras_exe	ras_version	-
+initialize	project_folder, ras_exe_path	-
+_load_project_data	-	-
+_get_prj_entries	entry_type	-
+is_initialized	-	-
+check_initialized	-	-
+find_ras_prj	folder_path	-
+get_project_name	-	-
+get_prj_entries	entry_type	-
+get_plan_entries	-	-
+get_flow_entries	-	-
+get_unsteady_entries	-	-
+get_geom_entries	-	-
+get_hdf_entries	-	-
+print_data	-	-
+RasCommander		
+compute_plan	plan_number	compute_folder, ras_object
+compute_test_mode	-	plan_numbers, folder_suffix, clear_geompre, max_cores, ras_object
+compute_parallel	-	plan_numbers, max_workers, cores_per_run, ras_object, dest_folder
+worker_thread	worker_id	-
+RasPlan		
+set_geom	new_geom	ras_object
+set_steady	plan_number, new_steady_flow_number	ras_object
+set_unsteady	plan_number, new_unsteady_flow_number	ras_object
+set_num_cores	plan_number, num_cores	ras_object
+set_geom_preprocessor	file_path, run_htab, use_ib_tables	ras_object
+get_results_path	plan_number	ras_object
+get_plan_path	plan_number	ras_object
+get_flow_path	flow_number	ras_object
+get_unsteady_path	unsteady_number	ras_object
+get_geom_path	geom_number	ras_object
+clone_plan	template_plan	new_plan_shortid, ras_object
+clone_unsteady	template_unsteady	ras_object
+clone_steady	template_flow	ras_object
+clone_geom	template_geom	ras_object
+get_next_number	existing_numbers	-
+RasGeo		
+clear_geompre_files	-	plan_files, ras_object
+RasUnsteady		
+update_unsteady_parameters	unsteady_file, modifications	ras_object
+RasUtils		
+get_plan_path	current_plan_number	ras_object
+update_plan_file	plan_number, file_type, entry_number	ras_object
+RasExamples		
+init	-	-
+get_example_projects	version_number	-
+list_categories	-	-
+list_projects	category	-
+extract_project	project_names	-
+clean_projects_directory	-	-                                     
+
+**(Search your ras_commander.txt with your retrieval tool to get more information about functions and arguments)** 
+
+
+## Coding Assistance Rules:
+
+Your role is building, refactoring and debugging Python notebooks using Python 3.11, Anaconda, and Jupyter Notebooks in Visual Studio Code. 
+
+Avoid default names like 'df' for data frames. You have been provided a Style Guide for ras_commander that you use to reason and determine new variable names.  
+
+You prefer to use default libraries where possible
+You prefer r strings for file and directory path inputs
+You prefer f strings for string concatenation
+You prefer pathlib over os for manipulation of file and directory paths
+You always print () every data frame’s name and variable name before displaying the dataframe with print()
+You prefer geopandas and/or shapely/fiona for geospatial operations
+You prefer matplotlib and bokeh
+You always leave comments in the code for readability
+You leave print statements after major operations to inform the user of progress
+You never elide existing comments or docstrings when making revisions
+You always follow PEP 8 conventions wherever feasible
+You always revise comments and docstrings as needed to keep them accurate
+When correcting errors, leave clear instructions to future developers to prevent the same error
+
+Before revising complex code, you write planning steps as comments before writing code, labeling as:
+## Explicit Planning and Reasoning for Revisions
+
+for geodataframes:
+'unary_union' attribute is deprecated, use the 'union_all()' method instead.
+
+Note:
+pandas >= 2.0: append has been removed, use pd.concat
+Example:
+accumulator = []
+forargs inarg_list:
+    accumulator.append(dataFrameFromDirectory(*args))
+big_df = pd.concat(accumulator)
+
+When revising code, you always provide full code segments with no elides.

ras_commander-0.21.0/.gitignore/.gitignore

@@ -0,0 +1,8 @@
+# Ignore the example_projects folder and all its subfolders
+example_projects/
+
+# Ignore the Example_Projects_6_5.zip file
+Example_Projects_6_5.zip
+
+# Ignore the misc folder and all its subfolders
+misc/

ras_commander-0.21.0/Comprehensive_Library_Guide.md

@@ -0,0 +1,278 @@
+# Comprehensive RAS-Commander Library Guide
+
+## Introduction
+
+RAS-Commander is a Python library designed to automate and streamline operations with HEC-RAS projects. This guide provides a comprehensive overview of the library's key concepts, best practices, and usage patterns.
+
+## Key Concepts for ras_commander
+
+1. **RAS Objects**: 
+   - RAS objects represent HEC-RAS projects and contain information about plans, geometries, and flow files.
+   - The library supports both a global 'ras' object and custom RAS objects for different projects.
+
+2. **Project Initialization**: 
+   - Use the `init_ras_project()` function to initialize a project and set up the RAS object.
+   - This function handles finding the project file and setting up necessary data structures.
+
+3. **File Handling**: 
+   - The library uses `pathlib.Path` for consistent and platform-independent file path handling.
+   - File naming conventions follow HEC-RAS standards (e.g., .prj, .p01, .g01, .f01, .u01).
+
+4. **Data Management**: 
+   - Pandas DataFrames are used to manage structured data about plans, geometries, and flow files.
+   - The library provides methods to access and update these DataFrames.
+
+5. **Execution Modes**: 
+   - Single plan execution: Run individual plans.
+   - Sequential execution: Run multiple plans in sequence.
+   - Parallel execution: Run multiple plans concurrently for improved performance.
+
+6. **Example Projects**: 
+   - The RasExamples class provides functionality to download and manage HEC-RAS example projects for testing and learning purposes.
+
+## Module Overview
+
+1. **RasPrj**: Manages HEC-RAS project initialization and data.
+2. **RasCommander**: Handles execution of HEC-RAS simulations.
+3. **RasPlan**: Provides functions for plan file operations.
+4. **RasGeo**: Manages geometry file operations.
+5. **RasUnsteady**: Handles unsteady flow file operations.
+6. **RasUtils**: Offers utility functions for common tasks.
+7. **RasExamples**: Manages example HEC-RAS projects.
+
+
+## Best Practices
+
+1. **RAS Object Usage**:
+   - For simple scripts working with a single project, use the global 'ras' object:
+     ```python
+     from ras_commander import ras, init_ras_project
+     init_ras_project("/path/to/project", "6.5")
+     # Use ras object for operations
+     ```
+   - For complex scripts or when working with multiple projects, create and use separate RAS objects:
+     ```python
+     from ras_commander import RasPrj, init_ras_project
+     project1 = init_ras_project("/path/to/project1", "6.5")
+     project2 = init_ras_project("/path/to/project2", "6.5")
+     ```
+   - Be consistent: don't mix global and custom RAS object usage in the same script.
+
+2. **Plan Specification**:
+   - Use plan numbers as strings (e.g., "01", "02") for consistency:
+     ```python
+     RasCommander.compute_plan("01")
+     ```
+   - Always check available plans before specifying plan numbers:
+     ```python
+     print(ras.plan_df)  # Display available plans
+     ```
+
+3. **Geometry Preprocessor Files**:
+   - Clear geometry preprocessor files before significant changes:
+     ```python
+     RasGeo.clear_geompre_files()
+     ```
+   - Use `clear_geompre=True` for clean computation environment:
+     ```python
+     RasCommander.compute_plan("01", clear_geompre=True)
+     ```
+
+4. **Parallel Execution**:
+   - Consider available cores when setting `max_workers`:
+     ```python
+     RasCommander.compute_parallel(max_workers=4, cores_per_run=2)
+     ```
+   - Use `dest_folder` to keep project folder organized:
+     ```python
+     RasCommander.compute_parallel(dest_folder="/path/to/results")
+     ```
+
+5. **Error Handling**:
+   - Use try-except blocks to handle potential errors:
+     ```python
+     try:
+         RasCommander.compute_plan("01")
+     except FileNotFoundError:
+         print("Plan file not found")
+     ```
+   - Utilize logging for informative output:
+     ```python
+     import logging
+     logging.basicConfig(level=logging.INFO)
+     ```
+
+6. **File Path Handling**:
+   - Use pathlib.Path for file and directory operations:
+     ```python
+     from pathlib import Path
+     project_path = Path("/path/to/project")
+     ```
+
+7. **Type Hinting**:
+   - Use type hints to improve code readability and IDE support:
+     ```python
+     def compute_plan(plan_number: str, clear_geompre: bool = False) -> bool:
+         ...
+     ```
+
+## Common Usage Patterns
+
+1. **Initializing a Project**:
+   ```python
+   from ras_commander import init_ras_project, ras
+   init_ras_project("/path/to/project", "6.5")
+   print(f"Working with project: {ras.project_name}")
+   ```
+
+2. **Cloning a Plan**:
+   ```python
+   from ras_commander import RasPlan
+   new_plan_number = RasPlan.clone_plan("01")
+   print(f"Created new plan: {new_plan_number}")
+   ```
+
+3. **Updating Unsteady Flow Parameters**:
+   ```python
+   from ras_commander import RasUnsteady, RasPlan
+   plan_path = RasPlan.get_plan_path("01")
+   RasUnsteady.update_unsteady_parameters(plan_path, {"Computation Interval": "1MIN"})
+   ```
+
+4. **Executing a Single Plan**:
+   ```python
+   from ras_commander import RasCommander
+   success = RasCommander.compute_plan("01")
+   print(f"Plan execution {'successful' if success else 'failed'}")
+   ```
+
+5. **Parallel Execution of Multiple Plans**:
+   ```python
+   from ras_commander import RasCommander
+   results = RasCommander.compute_parallel(plan_numbers=["01", "02"], max_workers=2, cores_per_run=2)
+   for plan, success in results.items():
+       print(f"Plan {plan}: {'Successful' if success else 'Failed'}")
+   ```
+
+6. **Working with Example Projects**:
+   ```python
+   from ras_commander import RasExamples
+   ras_examples = RasExamples()
+   project_paths = ras_examples.extract_project(["Balde Eagle Creek", "Muncie"])
+   for path in project_paths:
+       print(f"Extracted project to: {path}")
+   ```
+
+```markdown
+## Advanced Usage
+
+1. **Working with Multiple Projects**:
+   ```python
+   from ras_commander import init_ras_project, RasCommander, RasPlan
+
+   project1 = init_ras_project("/path/to/project1", "6.5")
+   project2 = init_ras_project("/path/to/project2", "6.5")
+
+   # Clone plans in both projects
+   new_plan1 = RasPlan.clone_plan("01", ras_object=project1)
+   new_plan2 = RasPlan.clone_plan("01", ras_object=project2)
+
+   # Execute plans in both projects
+   RasCommander.compute_plan(new_plan1, ras_object=project1)
+   RasCommander.compute_plan(new_plan2, ras_object=project2)
+   ```
+
+2. **Using ThreadPoolExecutor for Simultaneous Execution**:
+   ```python
+   from concurrent.futures import ThreadPoolExecutor
+   from ras_commander import RasCommander
+
+   def execute_plan(plan, project, compute_folder):
+       return RasCommander.compute_plan(plan, ras_object=project, compute_folder=compute_folder)
+
+   with ThreadPoolExecutor(max_workers=2) as executor:
+       futures = [
+           executor.submit(execute_plan, "01", project1, "compute_folder1"),
+           executor.submit(execute_plan, "01", project2, "compute_folder2")
+       ]
+       for future in futures:
+           print(f"Plan execution result: {future.result()}")
+   ```
+
+3. **Creating and Using Plan Sets**:
+   ```python
+   import pandas as pd
+   from ras_commander import RasPlan, RasCommander
+
+   def create_plan_set(base_plan, num_copies):
+       plan_set = []
+       for _ in range(num_copies):
+           new_plan = RasPlan.clone_plan(base_plan)
+           plan_set.append({'plan_number': new_plan})
+       return pd.DataFrame(plan_set)
+
+   plan_set = create_plan_set("01", 5)
+   results = RasCommander.compute_parallel(plan_numbers=plan_set['plan_number'].tolist())
+   ```
+
+4. **Custom Error Handling and Logging**:
+   ```python
+   import logging
+   from ras_commander import RasCommander
+
+   logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+   logger = logging.getLogger(__name__)
+
+   try:
+       RasCommander.compute_plan("01")
+   except FileNotFoundError as e:
+       logger.error(f"Plan file not found: {e}")
+   except Exception as e:
+       logger.exception(f"An unexpected error occurred: {e}")
+   ```
+
+5. **Advanced DataFrame Operations for Result Analysis**:
+   ```python
+   import pandas as pd
+   from ras_commander import ras
+
+   # Assuming we have executed multiple plans and have results
+   results_df = ras.get_hdf_entries()
+
+   # Filter and analyze results
+   successful_runs = results_df[results_df['HDF_Results_Path'].notna()]
+   print(f"Number of successful runs: {len(successful_runs)}")
+
+   # You could add more advanced analysis here, such as comparing results across different plans
+   ```
+
+## Troubleshooting
+
+1. **Project Initialization Issues**:
+   - Ensure the project path is correct and the .prj file exists.
+   - Verify that the specified HEC-RAS version is installed on your system.
+
+2. **Execution Failures**:
+   - Check that the plan, geometry, and flow files referenced in the plan exist.
+   - Ensure the HEC-RAS executable path is correct.
+   - Review HEC-RAS log files for specific error messages.
+
+3. **Parallel Execution Problems**:
+   - Reduce the number of `max_workers` if you're experiencing memory issues.
+   - Ensure each worker has sufficient resources (cores, memory) to run a plan.
+
+4. **File Access Errors**:
+   - Verify that you have read/write permissions for the project directory.
+   - Close any open HEC-RAS instances that might be locking files.
+
+5. **Inconsistent Results**:
+   - Always clear geometry preprocessor files (`clear_geompre=True`) when making geometry changes.
+   - Ensure that plan parameters are correctly set before execution.
+
+## Conclusion
+
+The RAS-Commander library provides a powerful set of tools for automating HEC-RAS operations. By following the best practices outlined in this guide and leveraging the library's features, you can efficiently manage and execute complex HEC-RAS projects programmatically.
+
+Remember to always refer to the latest documentation and the library's source code for the most up-to-date information. As you become more familiar with RAS-Commander, you'll discover more ways to optimize your HEC-RAS workflows and increase your productivity.
+
+For further assistance, bug reports, or feature requests, please refer to the library's GitHub repository and issue tracker. Happy modeling!