ras-commander 0.57.0__py3-none-any.whl → 0.59.0__py3-none-any.whl

ras_commander/RasExamples.py

@@ -122,8 +122,16 @@ class RasExamples:
         self._save_to_csv()
 
     @classmethod
-    def extract_project(cls, project_names: Union[str, List[str]]):
-        """Extract one or more specific HEC-RAS projects from the zip file."""
+    def extract_project(cls, project_names: Union[str, List[str]]) -> 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
+            
+        Returns:
+            Path: Single Path object if one project extracted
+            List[Path]: List of Path objects if multiple projects extracted
+        """
         logger.debug(f"Extracting projects: {project_names}")
         
         # Initialize if needed
@@ -178,7 +186,8 @@ class RasExamples:
             except Exception as e:
                 logger.error(f"An error occurred while extracting project '{project_name}': {str(e)}")
 
-        return extracted_paths
+        # Return single path if only one project was extracted, otherwise return list
+        return extracted_paths[0] if len(project_names) == 1 else extracted_paths
 
     @classmethod
     def _find_zip_file(cls):

ras_commander/RasPrj.py

@@ -828,7 +828,6 @@ def init_ras_project(ras_project_folder, ras_version=None, ras_object=None):
     Initialize a RAS project.
 
     USE THIS FUNCTION TO INITIALIZE A RAS PROJECT, NOT THE INITIALIZE METHOD OF THE RasPrj CLASS.
-    The initialize method of the RasPrj class only modifies the global 'ras' object.
 
     Parameters:
     -----------
@@ -838,8 +837,10 @@ def init_ras_project(ras_project_folder, ras_version=None, ras_object=None):
         The version of RAS to use (e.g., "6.6").
         The version can also be a full path to the Ras.exe file.
         If None, the function will attempt to use the version from the global 'ras' object or a default path.
-    ras_object : RasPrj, optional
-        An instance of RasPrj to initialize. If None, the global 'ras' object is used.
+    ras_object : RasPrj or str, optional
+        If None, the global 'ras' object is updated.
+        If a RasPrj instance, that instance is updated.
+        If any other value is provided, a new RasPrj instance is created and returned.
 
     Returns:
     --------
@@ -852,16 +853,24 @@ def init_ras_project(ras_project_folder, ras_version=None, ras_object=None):
 
     ras_exe_path = get_ras_exe(ras_version)
 
+    # Determine which RasPrj instance to use
     if ras_object is None:
+        # Use the global 'ras' object
         logger.info("Initializing global 'ras' object via init_ras_project function.")
         ras_object = ras
     elif not isinstance(ras_object, RasPrj):
-        logger.error("Provided ras_object is not an instance of RasPrj.")
-        raise TypeError("ras_object must be an instance of RasPrj or None.")
+        # Create a new RasPrj instance
+        logger.info("Creating a new RasPrj instance.")
+        ras_object = RasPrj()
 
     # Initialize the RasPrj instance
     ras_object.initialize(ras_project_folder, ras_exe_path)
     
+    # Always update the global ras object as well
+    if ras_object is not ras:
+        ras.initialize(ras_project_folder, ras_exe_path)
+        logger.info("Global 'ras' object also updated to match the new project.")
+    
     logger.info(f"Project initialized. ras_object project folder: {ras_object.project_folder}")
     return ras_object
 

{ras_commander-0.57.0.dist-info → ras_commander-0.59.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: ras-commander
-Version: 0.57.0
+Version: 0.59.0
 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.
@@ -34,27 +34,20 @@ Dynamic: summary
 
 RAS Commander is a Python library for automating HEC-RAS operations, providing a set of tools to interact with HEC-RAS project files, execute simulations, and manage project data. This library was initially conceptualized in the Australian Water School course "AI Tools for Modelling Innovation", and subsequently expanded to cover the basic functionality of the HECRASController COM32 interface using open-source python libraries.  This library uses a Test Driven Development strategy, leveraging the publicly-available HEC-RAS Example projects to create repeatable demonstration examples.  The "Commmander" moniker is inspired by the "Command Line is All You Need" approach to HEC-RAS automation that was first implemented in the HEC-Commander Tools repository. 
 
-## Contributors:
-William Katzenmeyer, P.E., C.F.M. 
+## Repository Author:
+(William Katzenmeyer, P.E., C.F.M.)[https://engineeringwithllms.info]
 
-Sean Micek, P.E., C.F.M. 
-
-Aaron Nichols, P.E., C.F.M. 
-
-(Additional Contributors Here)  
-
-## Don't Ask Me, Ask ChatGPT! 
+## Don't Ask Me, Ask GPT! 
 
 This repository has several methods of interaction with Large Language Models and LLM-Assisted Coding built right in: 
 
 1. **[RAS Commander Library Assistant GPT](https://chatgpt.com/g/g-TZRPR3oAO-ras-commander-library-assistant)**: A specialized GPT model with access to the ras-commander codebase and library, available for answering queries and providing code suggestions.   You can even upload your own plan, unsteady and HDF files to inspect and help determine how to automate your workflows or visualize your results, although this ability is still limited by OpenAI's GPT frameworks and may not be useful for long conversations.
 
-2. **[Purpose-Built Knowledge Base Summaries](https://github.com/billk-FM/ras-commander/tree/main/ai_tools/assistant_knowledge_bases)**: Up-to-date compilations of the documentation and codebase for use with large language models like Claude or GPT-4. Look in 'ai_tools/assistant_knowledge_bases/' in the repo.  The repo's codebase (without documentation and examples) has been curated to stay within the current ~200k context window limitations of frontier models, and for tasks that do not need an understanding of the underlying code, the Comprehensive Library Guide and any relevant examples from the example folder should be adequate context for leveraging the ras-commander API to complete tasks. 
+2. **[Purpose-Built Knowledge Base Summaries](https://github.com/gpt-cmdr/ras-commander/tree/main/ai_tools/assistant_knowledge_bases)**: Up-to-date compilations of the documentation and codebase for use with large language models like Claude or GPT-4. Look in 'ai_tools/assistant_knowledge_bases/' in the repo.  The repo's codebase (without documentation and examples) has been curated to stay within the current ~200k context window limitations of frontier models, and for tasks that do not need an understanding of the underlying code, the Comprehensive Library Guide and any relevant examples from the example folder should be adequate context for leveraging the ras-commander API to complete tasks. 
 
-3. **[Cursor IDE Integration](https://github.com/billk-FM/ras-commander/blob/main/.cursorrules)**: Custom rules(.cursorrules) for the Cursor IDE to provide context-aware suggestions and documentation.  Just open the repository folder in Cursor to recognize these instructions.  You can create your own folders "/workspace/, "/projects/", or "my_projects/" as these are already in the .gitignore, and place your custom scripts there for your projects.  This will allow easy referencing of the ras-commander documents and individual repo files, the automatic loading of the .cursorrules file.  Alternatvely, download the github repo into your projects folder to easily load documents and use cursor rules files.
-
-5. **[RAS-Commander Library Assistant](https://github.com/billk-FM/ras-commander/blob/main/library_assistant)**: A full-featured interface for multi-turn conversations, using your own API keys and the ras-commander library for context.  The library assistant allows you to load your own scripts and chat with specific examples and/or function classes in the RAS-Commander library to effectively utilize the library's functions in your workflow.  To reduce hallucinations, a file browser is included which adds full files to the conversation to ensure grounded responses.  A dashboard shows you the total context and estimated cost of each request.  **Now with support for OpenAI's o1 and o3-mini, and Deepseek V3 and R1 models using US-based Together.ai**
+3. **[Cursor IDE Integration](https://github.com/gpt-cmdr/ras-commander/blob/main/.cursorrules)**: Custom rules(.cursorrules) for the Cursor IDE to provide context-aware suggestions and documentation.  Just open the repository folder in Cursor to recognize these instructions.  You can create your own folders "/workspace/, "/projects/", or "my_projects/" as these are already in the .gitignore, and place your custom scripts there for your projects.  This will allow easy referencing of the ras-commander documents and individual repo files, the automatic loading of the .cursorrules file.  Alternatvely, download the github repo into your projects folder to easily load documents and use cursor rules files.
 
+5. **[RAS-Commander Library Assistant](https://github.com/gpt-cmdr/ras-commander/blob/main/library_assistant)**: A full-featured interface for multi-turn conversations, using your own API keys and the ras-commander library for context.  The library assistant allows you to load your own scripts and chat with specific examples and/or function classes in the RAS-Commander library to effectively utilize the library's functions in your workflow.  To reduce hallucinations, a file browser is included which adds full files to the conversation to ensure grounded responses.  A dashboard shows you the total context and estimated cost of each request.  **Now with support for OpenAI's o1 and o3-mini, and Deepseek V3 and R1 models using US-based Together.ai**
 
 ## Background
 The ras-commander library emerged from the initial test-bed of AI-driven coding represented by the HEC-Commander tools Python notebooks. These notebooks served as a proof of concept, demonstrating the value proposition of automating HEC-RAS operations. The transition from notebooks to a structured library aims to provide a more robust, maintainable, and extensible solution for water resources engineers.
@@ -71,8 +64,6 @@ HEC-RAS Project Management & Execution
 - Progress tracking and logging
 - Execution error handling and recovery
 
-
-  
 HDF Data Access & Analysis
 - 2D mesh results processing (depths, velocities, WSE)
 - Cross-section data extraction
@@ -82,7 +73,6 @@ HDF Data Access & Analysis
 - Fluvial-pluvial boundary calculations
 - Infiltration and precipitation data handling
 
-  
 RAS ASCII File Operations
 - Plan file creation and modification
 - Geometry file parsing examples 
@@ -99,7 +89,6 @@ First, create a virtual environment with conda or venv (ask ChatGPT if you need
 
 In your virtual environment, install ras-commander using pip:
 ```
-pip install h5py numpy pandas requests tqdm scipy xarray geopandas matplotlib ipython tqdm psutil shapely fiona pathlib rtree rasterstats
 pip install --upgrade ras-commander
 ```
 If you have dependency issues with pip (especially if you have errors with numpy), try clearing your local pip packages 'C:\Users\your_username\AppData\Roaming\Python\' and then creating a new virtual environment.  
@@ -124,10 +113,6 @@ except ImportError:
 ```
 It is highly suggested to fork this repository before going this route, and using Git to manage your changes!  This allows any revisions to the ras-commander classes and functions to be actively edited and developed by end users. The folders "/workspace/, "/projects/", or "my_projects/" are included in the .gitignore, so users can place you custom scripts there for any project data they don't want to be tracked by git.
 
-
-
-  
-
 ## Quick Start Guide
 
 ```
@@ -147,9 +132,9 @@ RasCmdr.compute_plan("01", dest_folder=r"/path/to/results", overwrite_dest=True)
 ### Execute plans in parallel
 ```
 results = RasCmdr.compute_parallel(
-    plan_numbers=["01", "02"],
+    plan_number=["01", "02"],
     max_workers=2,
-    cores_per_run=2,
+    num_cores=2,
     dest_folder=r"/path/to/results",
     overwrite_dest=True
 )
@@ -160,7 +145,62 @@ results = RasCmdr.compute_parallel(
 RasPlan.set_geom("01", "02")
 ```
 
-Certainly! I'll provide you with an updated Key Components section and Project Organization diagram based on the current structure of the ras-commander library.
+### Execution Modes
+
+RAS Commander provides three methods for executing HEC-RAS plans:
+
+#### Single Plan Execution
+```python
+# Execute a single plan
+success = RasCmdr.compute_plan("01", dest_folder=r"/path/to/results")
+print(f"Plan execution {'successful' if success else 'failed'}")
+```
+
+#### Sequential Execution of Multiple Plans
+```python
+# Execute multiple plans in sequence in a test folder
+results = RasCmdr.compute_test_mode(
+    plan_number=["01", "02", "03"],
+    dest_folder_suffix="[Test]"
+)
+for plan, success in results.items():
+    print(f"Plan {plan}: {'Successful' if success else 'Failed'}")
+```
+
+#### Parallel Execution of Multiple Plans
+```python
+# Execute multiple plans concurrently
+results = RasCmdr.compute_parallel(
+    plan_number=["01", "02", "03"],
+    max_workers=3,
+    num_cores=2
+)
+for plan, success in results.items():
+    print(f"Plan {plan}: {'Successful' if success else 'Failed'}")
+```
+
+### Working with Multiple Projects
+
+RAS Commander allows working with multiple HEC-RAS projects simultaneously:
+
+```python
+# Initialize multiple projects
+project1 = init_ras_project(path1, "6.6")
+project2 = init_ras_project(path2, "6.6")
+
+# Perform operations on each project
+RasCmdr.compute_plan("01", ras_object=project1, dest_folder=folder1)
+RasCmdr.compute_plan("01", ras_object=project2, dest_folder=folder2)
+
+# Compare results between projects
+print(f"Project 1: {project1.project_name}")
+print(f"Project 2: {project2.project_name}")
+
+# Always specify the ras_object parameter when working with multiple projects
+# to avoid confusion with the global 'ras' object
+```
+
+This is useful for comparing different river systems, running scenario analyses across multiple watersheds, or managing a suite of related models.
 
 #### Key Components
 
@@ -190,8 +230,6 @@ Certainly! I'll provide you with an updated Key Components section and Project O
 
 ### Project Organization Diagram
 
-### Project Organization Diagram
-
 ```
 ras_commander
 ├── ras_commander
@@ -222,24 +260,16 @@ ras_commander
 │   ├── HdfPlot.py
 │   └── HdfResultsPlot.py
 ├── examples
-│   ├── 01_project_initialization.py
-│   ├── 02_plan_operations.py
-│   ├── 03_geometry_operations.py
-│   ├── 04_unsteady_flow_operations.py
-│   ├── 05_utility_functions.py
-│   ├── 06_single_plan_execution.py
-│   ├── 07_sequential_plan_execution.py
-│   ├── 08_parallel_execution.py
-│   ├── 09_specifying_plans.py
-│   ├── 10_arguments_for_compute.py
-│   ├── 11_Using_RasExamples.ipynb
-│   ├── 12_plan_set_execution.py
-│   ├── 13_multiple_project_operations.py
-│   ├── 14_Core_Sensitivity.ipynb
-│   ├── 15_plan_key_operations.py
-│   ├── 16_scanning_ras_project_info.py
-│   ├── 17_parallel_execution_ble.py
-│   └── HEC_RAS_2D_HDF_Analysis.ipynb
+│   ├── 00_Using_RasExamples.ipynb
+│   ├── 01_project_initialization.ipynb
+│   ├── 02_plan_and_geometry_operations.ipynb
+│   ├── 03_unsteady_flow_operations.ipynb
+│   ├── 04_multiple_project_operations.ipynb
+│   ├── 05_single_plan_execution.ipynb
+│   ├── 06_executing_plan_sets.ipynb
+│   ├── 07_sequential_plan_execution.ipynb
+│   ├── 08_parallel_execution.ipynb
+│   └── 09_plan_parameter_operations.ipynb
 ├── tests
 │   └── ... (test files)
 ├── .gitignore
@@ -267,8 +297,6 @@ Example usage:
 from ras_commander import RasExamples
 
 ```
-ras_examples = RasExamples()
-ras_examples.get_example_projects()  # Downloads example projects if not already present
 categories = ras_examples.list_categories()
 projects = ras_examples.list_projects("Steady Flow")
 extracted_paths = ras_examples.extract_project(["Bald Eagle Creek", "Muncie"])
@@ -321,7 +349,6 @@ 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
@@ -358,13 +385,33 @@ boundary = HdfFluvialPluvial.calculate_fluvial_pluvial_boundary(
 )
 ```
 
-## Documentation
+## Examples
 
-For detailed usage instructions and API documentation, please refer to the [Comprehensive Library Guide](Comprehensive_Library_Guide.md).
+Check out the examples in the repository to learn how to use RAS Commander:
 
-## Examples
+### Project Setup
+- `00_Using_RasExamples.ipynb`: Download and extract HEC-RAS example projects
+- `01_project_initialization.ipynb`: Initialize HEC-RAS projects and explore their components
+
+### File Operations
+- `02_plan_and_geometry_operations.ipynb`: Clone and modify plan and geometry files
+- `03_unsteady_flow_operations.ipynb`: Extract and modify boundary conditions
+- `09_plan_parameter_operations.ipynb`: Retrieve and update plan parameters
+
+### Execution Modes
+- `05_single_plan_execution.ipynb`: Execute a single plan with specific options
+- `06_executing_plan_sets.ipynb`: Different ways to specify and execute plan sets
+- `07_sequential_plan_execution.ipynb`: Run multiple plans in sequence
+- `08_parallel_execution.ipynb`: Run multiple plans in parallel
 
-Check out the `examples/` directory for sample scripts demonstrating various features of ras-commander.
+### Advanced Operations
+- `04_multiple_project_operations.ipynb`: Work with multiple HEC-RAS projects simultaneously
+
+These examples demonstrate practical applications of RAS Commander for automating HEC-RAS workflows, from basic operations to advanced scenarios.
+
+## Documentation
+
+For detailed usage instructions and API documentation, please refer to the [Comprehensive Library Guide](Comprehensive_Library_Guide.md).
 
 ## Future Development
 
@@ -375,10 +422,9 @@ The ras-commander library is an ongoing project. Future plans include:
 
 ## Related Resources
 
-- [HEC-Commander Blog](https://github.com/billk-FM/HEC-Commander/tree/main/Blog)
+- [HEC-Commander Blog](https://github.com/gpt-cmdr/HEC-Commander/tree/main/Blog)
 - [GPT-Commander YouTube Channel](https://www.youtube.com/@GPT_Commander)
-- [ChatGPT Examples for Water Resources Engineers](https://github.com/billk-FM/HEC-Commander/tree/main/ChatGPT%20Examples)
-
+- [ChatGPT Examples for Water Resources Engineers](https://github.com/gpt-cmdr/HEC-Commander/tree/main/ChatGPT%20Examples)
 
 ## Contributing
 
@@ -415,8 +461,7 @@ These acknowledgments recognize the contributions and inspirations that have hel
 
 4. Chris Goodell, "Breaking the HEC-RAS Code" - Studied and used as a reference for understanding the inner workings of HEC-RAS, providing valuable insights into the software's functionality and structure.
 
-5. [HEC-Commander Tools](https://github.com/billk-FM/HEC-Commander) - Inspiration and initial code base for the development of RAS Commander.
-
+5. [HEC-Commander Tools](https://github.com/gpt-cmdr/HEC-Commander) - Inspiration and initial code base for the development of RAS Commander.
 
 ## Official RAS Commander AI-Generated Songs:
 
@@ -426,14 +471,13 @@ These acknowledgments recognize the contributions and inspirations that have hel
 
 ## Other Resources
 
-Notebook version of RAS-Commander: [RAS-Commander Notebook in the HEC-Commander Tools Repository](https://github.com/billk-FM/HEC-Commander/tree/main/RAS-Commander)
+Notebook version of RAS-Commander: [RAS-Commander Notebook in the HEC-Commander Tools Repository](https://github.com/gpt-cmdr/HEC-Commander/tree/main/RAS-Commander)
 Youtube Tutorials for HEC-Commander Tools and RAS-Commander: [GPT-Commander on YouTube](https://www.youtube.com/@GPT_Commander/videos)
 
 ## LICENSE
 
 This software is released under the MIT license.
 
-
 ## Contact
 
 For questions, suggestions, or support, please contact:

{ras_commander-0.57.0.dist-info → ras_commander-0.59.0.dist-info}/RECORD

@@ -17,18 +17,18 @@ ras_commander/HdfUtils.py,sha256=VkIKAXBrLwTlk2VtXSO-W3RU-NHpfHbE1QcZUZgl-t8,152
 ras_commander/HdfXsec.py,sha256=flREnFFrIZu4SSKGRQeX9w3SS49q0UWPJnq4zO7DbUM,27342
 ras_commander/LoggingConfig.py,sha256=gWe5K5XTmMQpSczsTysAqpC9my24i_IyM8dvD85fxYg,2704
 ras_commander/RasCmdr.py,sha256=2i9gR5koFfBLwvhYAbNgQFNKKUKqxD1Hf6T9SN9sx-s,26558
-ras_commander/RasExamples.py,sha256=O4h5WwtewoFZjHqQ4i1hhbUUDSCW6TU4MloXqhQTt8U,17090
+ras_commander/RasExamples.py,sha256=6IZ96LcAsk5LYFehdD0zDW5wyZWxQa6OQu2N9upxWXA,17536
 ras_commander/RasGeo.py,sha256=M0sVNKlWmmbve8iMXLWq25WgbxqLWBo7_1oDg_rALzU,5607
 ras_commander/RasGpt.py,sha256=N_7p2nucWrBBXdB2k2ZKvOeOdXNmFD9dIY3W7_5i5nw,1206
 ras_commander/RasMapper.py,sha256=A7xupixCmgXFiSfQs3oWBMBstrO8XcxieMeZWKTcbPQ,3271
 ras_commander/RasPlan.py,sha256=1HAn31oyz0hGv2r7GVNCLWcAZFcRjYTBNdL19mabvmw,53651
-ras_commander/RasPrj.py,sha256=9F0UVQZ2RfjhDf5717aJcEChL6z5BD8agGWAlUvqe0E,37472
+ras_commander/RasPrj.py,sha256=epORKnwdzAovAO-whadvkOhJ8ruXPqmPjGCouHdqzuo,37783
 ras_commander/RasToGo.py,sha256=TKujfaV1xQhFaOddF4g2ogGy6ky-CLlfelSMPD2J3Nk,1223
 ras_commander/RasUnsteady.py,sha256=KfCXAag-_bPwwS3JbPZH-s4hbaoHACO0mlRnGrzbFgA,32092
 ras_commander/RasUtils.py,sha256=P2-aBL61kdRINsjnBpstZVD6VVc7hI_D3RUXqr6ldmc,34863
 ras_commander/__init__.py,sha256=mceEWRQJkDBi1o3zVg7DpG2qMrMnKHwwuK3GwyxoVr4,2132
-ras_commander-0.57.0.dist-info/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
-ras_commander-0.57.0.dist-info/METADATA,sha256=H1Px65L0_yV2AKMfnDgZ_ukH4GicbbJRaSX4g8Xxzd4,22494
-ras_commander-0.57.0.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
-ras_commander-0.57.0.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
-ras_commander-0.57.0.dist-info/RECORD,,
+ras_commander-0.59.0.dist-info/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
+ras_commander-0.59.0.dist-info/METADATA,sha256=Ai5tJpr_j9k8uO1SDIIz0WFLJu2QhAKesqh5ZB1mPWY,24307
+ras_commander-0.59.0.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+ras_commander-0.59.0.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
+ras_commander-0.59.0.dist-info/RECORD,,