ras-commander 0.22.0.dev0__py2.py3-none-any.whl → 0.24.0.dev0__py2.py3-none-any.whl

ras_commander/{RasCommander.py → RasCmdr.py}

@@ -25,64 +25,64 @@ import queue
 from threading import Thread, Lock
 import time
 
-
-class RasCommander:
+# TO DO: 
+# 1. Alternate Run Mode for compute_plan and compute_parallel:  Using Powershell to execute the HEC-RAS command and hide the RAS window and all child windows.
+#    If this is implemented, and the plan has a popup, then the plan will not execute.  This is a deal breaker for many scenarios, and should only be used
+#    as a special option for those who don't want to deal with the popups, or want to run in the background.  This option should be limited to non-commercial use.
+# 2. Implment compute_plan_remote to go along with compute_plan.  This will be a compute_plan that is run on a remote machine via a psexec command.
+#    First, we will use the keyring package to securely store the remote machine username and password.
+#    Second, we will implement the psexec command to execute the HEC-RAS command on the remote machine.
+#    Each machine will need to be initialized as a remote_worker object, which will store the machine name, username, password, ras_exe_path, local folder path and other relevant info.
+#    A separate RasRemote class will be created to handle the creation of the remote_worker objects and the necessary abstractions. 
+#    The compute_plan_remote function will live in RasCmdr, and will be a thin abstraction above the RasRemote class, since the functions will be simliar to the existing compute_plan functions, but specific to remote execution.  
+
+
+class RasCmdr:
     @staticmethod
     def compute_plan(
         plan_number,
-        compute_folder=None, 
-        ras_object=None
-        ):
+        dest_folder=None, 
+        ras_object=None,
+        clear_geompre=False,
+        num_cores=None,
+        overwrite_dest=False
+    ):
         """
         Execute a HEC-RAS plan.
 
         Args:
             plan_number (str, Path): The plan number to execute (e.g., "01", "02") or the full path to the plan file.
-            compute_folder (str, Path, optional): Name of the folder or full path for computation.
+            dest_folder (str, Path, optional): Name of the folder or full path for computation.
                 If a string is provided, it will be created in the same parent directory as the project folder.
                 If a full path is provided, it will be used as is.
-                If the compute_folder already exists, a ValueError will be raised to prevent overwriting.
             ras_object (RasPrj, optional): Specific RAS object to use. If None, uses the global ras instance.
+            clear_geompre (bool, optional): Whether to clear geometry preprocessor files. Defaults to False.
+            num_cores (int, optional): Number of cores to use for the plan execution. If None, the current setting is not changed.
+            overwrite_dest (bool, optional): If True, overwrite the destination folder if it exists. Defaults to False.
 
         Returns:
             bool: True if the execution was successful, False otherwise.
 
         Raises:
-            ValueError: If the specified compute_folder already exists and is not empty.
-
-        Example:
-            # Execute plan "01" in the current project folder
-            RasCommander.compute_plan("01")
-
-            # Execute plan "02" in a new compute folder
-            RasCommander.compute_plan("02", compute_folder="ComputeRun1")
-
-            # Execute a specific plan file in a new compute folder
-            RasCommander.compute_plan(r"C:\path\to\plan.p01.hdf", compute_folder="ComputeRun2")
-
-        Notes:
-            When using a compute_folder:
-            - A new RasPrj object is created for the computation.
-            - The entire project is copied to the new folder before execution.
-            - Results will be stored in the new folder, preserving the original project.
+            ValueError: If the specified dest_folder already exists and is not empty, and overwrite_dest is False.
         """
-        # Initialize RasPrj object with the default "ras" object if no specific object is provided
         ras_obj = ras_object or ras
         ras_obj.check_initialized()
         
-        # Determine the compute folder path and plan path
-        if compute_folder is not None:
-            compute_folder = Path(ras_obj.project_folder).parent / compute_folder if isinstance(compute_folder, str) else Path(compute_folder)
+        if dest_folder is not None:
+            dest_folder = Path(ras_obj.project_folder).parent / dest_folder if isinstance(dest_folder, str) else Path(dest_folder)
+            
+            if dest_folder.exists():
+                if overwrite_dest:
+                    shutil.rmtree(dest_folder)
+                elif any(dest_folder.iterdir()):
+                    raise ValueError(f"Destination folder '{dest_folder}' exists and is not empty. Use overwrite_dest=True to overwrite.")
             
-            # Check if the compute folder exists and is empty
-            if compute_folder.exists() and any(compute_folder.iterdir()):
-                raise ValueError(f"Compute folder '{compute_folder}' exists and is not empty. Please ensure the compute folder is empty before proceeding.")
-            elif not compute_folder.exists():
-                shutil.copytree(ras_obj.project_folder, compute_folder)
+            dest_folder.mkdir(parents=True, exist_ok=True)
+            shutil.copytree(ras_obj.project_folder, dest_folder, dirs_exist_ok=True)
             
-            # Initialize a new RAS project in the compute folder
             compute_ras = RasPrj()
-            compute_ras.initialize(compute_folder, ras_obj.ras_exe_path)
+            compute_ras.initialize(dest_folder, ras_obj.ras_exe_path)
             compute_prj_path = compute_ras.prj_file
         else:
             compute_ras = ras_obj
@@ -95,6 +95,22 @@ class RasCommander:
             print(f"Error: Could not find project file or plan file for plan {plan_number}")
             return False
 
+        # Clear geometry preprocessor files if requested
+        if clear_geompre:
+            try:
+                RasGeo.clear_geompre_files(compute_plan_path, ras_object=compute_ras)
+                print(f"Cleared geometry preprocessor files for plan: {plan_number}")
+            except Exception as e:
+                print(f"Error clearing geometry preprocessor files for plan {plan_number}: {str(e)}")
+
+        # Set the number of cores if specified
+        if num_cores is not None:
+            try:
+                RasPlan.set_num_cores(compute_plan_path, num_cores=num_cores, ras_object=compute_ras)
+                print(f"Set number of cores to {num_cores} for plan: {plan_number}")
+            except Exception as e:
+                print(f"Error setting number of cores for plan {plan_number}: {str(e)}")
+
         # Prepare the command for HEC-RAS execution
         cmd = f'"{compute_ras.ras_exe_path}" -c "{compute_prj_path}" "{compute_plan_path}"'
         print("Running HEC-RAS from the Command Line:")
@@ -124,164 +140,16 @@ class RasCommander:
         ras_obj.unsteady_df = ras_obj.get_unsteady_entries()
 
 
-    def compute_test_mode(
-        plan_numbers=None, 
-        folder_suffix="[Test]", 
-        clear_geompre=False, 
-        max_cores=None, 
-        ras_object=None
-    ):
-        """
-        Execute HEC-RAS plans in test mode.
-
-        This function creates a separate test folder, copies the project there, and executes the specified plans.
-        It allows for isolated testing without affecting the original project files.
-
-        Args:
-            plan_numbers (list of str, optional): List of plan numbers to execute. 
-                If None, all plans will be executed. Default is None.
-            folder_suffix (str, optional): Suffix to append to the test folder name. 
-                Defaults to "[Test]".
-            clear_geompre (bool, optional): Whether to clear geometry preprocessor files.
-                Defaults to False.
-            max_cores (int, optional): Maximum number of cores to use for each plan.
-                If None, the current setting is not changed. Default is None.
-            ras_object (RasPrj, optional): Specific RAS object to use. If None, uses the global ras instance.
-
-        Returns:
-            None
-
-        Example:
-            Run all plans: RasCommander.compute_test_mode()
-            Run specific plans: RasCommander.compute_test_mode(plan_numbers=["01", "03", "05"])
-            Run plans with a custom folder suffix: RasCommander.compute_test_mode(folder_suffix="[TestRun]")
-            Run plans and clear geometry preprocessor files: RasCommander.compute_test_mode(clear_geompre=True)
-            Run plans with a specific number of cores: RasCommander.compute_test_mode(max_cores=4)
-            
-        Notes:
-            - This function executes plans in a separate folder for isolated testing.
-            - If plan_numbers is not provided, all plans in the project will be executed.
-            - The function does not change the geometry preprocessor and IB tables settings.  
-                - To force recomputing of geometry preprocessor and IB tables, use the clear_geompre=True option.
-            - Plans are executed sequentially.
-        """
-        
-        # This line of code is used to initialize the RasPrj object with the default "ras" object if no specific object is provided.
-        ras_obj = ras_object or ras
-        # This line of code is used to check if the RasPrj object is initialized.
-        ras_obj.check_initialized()
-        
-        print("Starting the compute_test_mode...")
-           
-        # Use the project folder from the ras object
-        project_folder = ras_obj.project_folder
-
-        # Check if the project folder exists
-        if not project_folder.exists():
-            print(f"Error: Project folder '{project_folder}' does not exist.")
-            return
-
-        # Create test folder with the specified suffix in the same directory as the project folder
-        compute_folder = project_folder.parent / f"{project_folder.name} {folder_suffix}"
-        print(f"Creating the test folder: {compute_folder}...")
-
-        # Check if the compute folder exists and is empty
-        if compute_folder.exists():
-            if any(compute_folder.iterdir()):
-                raise ValueError(
-                    f"Compute folder '{compute_folder}' exists and is not empty. "
-                    "Please ensure the compute folder is empty before proceeding."
-                )
-        else:
-            try:
-                shutil.copytree(project_folder, compute_folder)
-            except FileNotFoundError:
-                print(f"Error: Unable to copy project folder. Source folder '{project_folder}' not found.")
-                return
-            except PermissionError:
-                print(f"Error: Permission denied when trying to create or copy to '{compute_folder}'.")
-                return
-            except Exception as e:
-                print(f"Error occurred while copying project folder: {str(e)}")
-                return
-
-        # Initialize a new RAS project in the compute folder
-        try:
-            compute_ras = RasPrj()
-            compute_ras.initialize(compute_folder, ras_obj.ras_exe_path)
-            compute_prj_path = compute_ras.prj_file
-        except Exception as e:
-            print(f"Error initializing RAS project in compute folder: {str(e)}")
-            return
-
-        if not compute_prj_path:
-            print("Project file not found.")
-            return
-        print(f"Project file found: {compute_prj_path}")
-
-        # Get plan entries
-        print("Getting plan entries...")
-        try:
-            ras_compute_plan_entries = compute_ras.plan_df
-            print("Retrieved plan entries successfully.")
-        except Exception as e:
-            print(f"Error retrieving plan entries: {str(e)}")
-            return
-
-        # Filter plans if plan_numbers is provided
-        if plan_numbers:
-            ras_compute_plan_entries = ras_compute_plan_entries[
-                ras_compute_plan_entries['plan_number'].isin(plan_numbers)
-            ]
-            print(f"Filtered plans to execute: {plan_numbers}")
-
-        # Optimize by iterating once to clear geompre files and set max cores
-        if clear_geompre or max_cores is not None:
-            print("Processing geometry preprocessor files and core settings...")
-            for plan_file in ras_compute_plan_entries['full_path']:
-                if clear_geompre:
-                    try:
-                        RasGeo.clear_geompre_files(plan_file)
-                        print(f"Cleared geometry preprocessor files for {plan_file}")
-                    except Exception as e:
-                        print(f"Error clearing geometry preprocessor files for {plan_file}: {str(e)}")
-                if max_cores is not None:
-                    try:
-                        RasPlan.set_num_cores(plan_file, num_cores=max_cores)
-                        print(f"Set max cores to {max_cores} for {plan_file}")
-                    except Exception as e:
-                        print(f"Error setting max cores for {plan_file}: {str(e)}")
-            print("Geometry preprocessor files and core settings processed successfully.")
-
-        # Run plans sequentially
-        print("Running selected plans sequentially...")
-        for _, plan in ras_compute_plan_entries.iterrows():
-            plan_number = plan["plan_number"]
-            start_time = time.time()
-            try:
-                RasCommander.compute_plan(plan_number, ras_object=compute_ras)
-            except Exception as e:
-                print(f"Error computing plan {plan_number}: {str(e)}")
-            end_time = time.time()
-            run_time = end_time - start_time
-            print(f"Total run time for plan {plan_number}: {run_time:.2f} seconds")
-
-        print("All selected plans have been executed.")
-        print("compute_test_mode completed.")
-
-        ras_obj = ras_object or ras
-        ras_obj.plan_df = ras_obj.get_plan_entries()
-        ras_obj.geom_df = ras_obj.get_geom_entries()
-        ras_obj.flow_df = ras_obj.get_flow_entries()
-        ras_obj.unsteady_df = ras_obj.get_unsteady_entries()
 
     @staticmethod
     def compute_parallel(
-        plan_numbers: list[str] | None = None,
+        plan_number: str | list[str] | None = None,
         max_workers: int = 2,
-        cores_per_run: int = 2,
+        num_cores: int = 2,
+        clear_geompre: bool = False,
         ras_object: RasPrj | None = None,
-        dest_folder: str | Path | None = None
+        dest_folder: str | Path | None = None,
+        overwrite_dest: bool = False
     ) -> dict[str, bool]:
         """
         Execute HEC-RAS plans in parallel using multiple worker threads.
@@ -290,21 +158,20 @@ class RasCommander:
         in parallel. It allows for isolated and concurrent execution of multiple plans.
 
         Args:
-            plan_numbers (list[str], optional): List of plan numbers to execute. 
-                If None, all plans will be executed. Default is None.
-            max_workers (int, optional): Maximum number of worker threads to use.
-                Default is 2.
-            cores_per_run (int, optional): Number of cores to use for each plan execution.
-                Default is 2.
+            plan_number (str | list[str] | None): Plan number, list of plan numbers, or None to execute all plans.
+            max_workers (int, optional): Maximum number of worker threads to use. Default is 2.
+            num_cores (int, optional): Number of cores to use for each plan execution. Default is 2.
+            clear_geompre (bool, optional): Whether to clear geometry preprocessor files. Defaults to False.
             ras_object (RasPrj, optional): Specific RAS object to use. If None, uses the global ras instance.
             dest_folder (str | Path, optional): Destination folder for the final computed results.
                 If None, results will be stored in a "[Computed]" folder next to the original project.
+            overwrite_dest (bool, optional): If True, overwrite the destination folder if it exists. Defaults to False.
 
         Returns:
             dict[str, bool]: A dictionary with plan numbers as keys and boolean values indicating success (True) or failure (False).
 
         Raises:
-            ValueError: If the destination folder exists and is not empty.
+            ValueError: If the destination folder exists and is not empty, and overwrite_dest is False.
             FileNotFoundError: If a plan file is not found.
 
         Notes:
@@ -314,10 +181,9 @@ class RasCommander:
             - The function automatically handles cleanup and consolidation of results after execution.
         
         Revision Notes:
-            - Removed redundant variable initializations.
-            - Streamlined worker folder creation and RAS object initialization.
-            - Optimized the consolidation of results from worker folders.
-            - Removed debug print statements for cleaner execution logs.
+            - Added support for clear_geompre flag as a pass-through to compute_plan.
+            - Simplified worker thread logic by removing redundant operations.
+            - Removed duplicate RAS object initialization in worker threads.
         """
         ras_obj = ras_object or ras
         ras_obj.check_initialized()
@@ -327,65 +193,42 @@ class RasCommander:
         if dest_folder is not None:
             dest_folder_path = Path(dest_folder)
             if dest_folder_path.exists():
-                if any(dest_folder_path.iterdir()):
-                    raise ValueError(
-                        f"\nError: Destination folder already exists: '{dest_folder_path}'\n"
-                        f"To prevent accidental overwriting of results, this operation cannot proceed.\n"
-                        f"Please take one of the following actions:\n"
-                        f"1. Delete the folder manually and run the operation again.\n"
-                        f"2. Use a different destination folder name.\n"
-                        f"3. Programmatically delete the folder before calling compute_parallel, like this:\n"
-                        f"   if Path('{dest_folder_path}').exists():\n"
-                        f"       shutil.rmtree('{dest_folder_path}')\n"
-                        f"This safety measure ensures that you don't inadvertently overwrite existing results."
-                    )
-            else:
-                try:
-                    dest_folder_path.mkdir(parents=True, exist_ok=True)
-                except PermissionError:
-                    raise PermissionError(f"Unable to create destination folder '{dest_folder_path}'. Permission denied.")
-            try:
-                shutil.copytree(project_folder, dest_folder_path, dirs_exist_ok=True)
-            except shutil.Error as e:
-                raise IOError(f"Error copying project to destination folder: {str(e)}")
-            project_folder = dest_folder_path  # Update project_folder to the new destination
-
-        if plan_numbers:
-            if isinstance(plan_numbers, str):
-                plan_numbers = [plan_numbers]
-            ras_obj.plan_df = ras_obj.plan_df[ras_obj.plan_df['plan_number'].isin(plan_numbers)]
+                if overwrite_dest:
+                    shutil.rmtree(dest_folder_path)
+                elif any(dest_folder_path.iterdir()):
+                    raise ValueError(f"Destination folder '{dest_folder_path}' exists and is not empty. Use overwrite_dest=True to overwrite.")
+            dest_folder_path.mkdir(parents=True, exist_ok=True)
+            shutil.copytree(project_folder, dest_folder_path, dirs_exist_ok=True)
+            project_folder = dest_folder_path
+
+        if plan_number:
+            if isinstance(plan_number, str):
+                plan_number = [plan_number]
+            ras_obj.plan_df = ras_obj.plan_df[ras_obj.plan_df['plan_number'].isin(plan_number)]
 
         num_plans = len(ras_obj.plan_df)
         max_workers = min(max_workers, num_plans) if num_plans > 0 else 1
         print(f"Adjusted max_workers to {max_workers} based on the number of plans: {num_plans}")
 
-        # Clean up existing worker folders
+        # Clean up existing worker folders and create new ones
+        worker_ras_objects = {}
         for worker_id in range(1, max_workers + 1):
             worker_folder = project_folder.parent / f"{project_folder.name} [Worker {worker_id}]"
             if worker_folder.exists():
                 shutil.rmtree(worker_folder)
-                print(f"Removed existing worker folder: {worker_folder}")
-
-        # Create worker folders and initialize RAS objects
-        worker_ras_objects = {}
-        for worker_id in range(1, max_workers + 1):
-            worker_folder = project_folder.parent / f"{project_folder.name} [Worker {worker_id}]"
             shutil.copytree(project_folder, worker_folder)
             
-            worker_ras_instance = RasPrj()
             worker_ras_instance = init_ras_project(
                 ras_project_folder=worker_folder,
                 ras_version=ras_obj.ras_exe_path,
-                ras_instance=worker_ras_instance
+                ras_instance=RasPrj()
             )
             worker_ras_objects[worker_id] = worker_ras_instance
 
-        # Prepare plan queue with plan numbers
         plan_queue = queue.Queue()
         for plan_number in ras_obj.plan_df['plan_number']:
             plan_queue.put(plan_number)
 
-        # Initialize results dictionary and thread locks
         execution_results: dict[str, bool] = {}
         results_lock = Lock()
         queue_lock = Lock()
@@ -399,16 +242,13 @@ class RasCommander:
                     plan_number = plan_queue.get()
                 
                 try:
-                    plan_path = RasPlan.get_plan_path(plan_number, ras_object=worker_ras_obj)
-                    if not plan_path:
-                        raise FileNotFoundError(f"Plan file not found: {plan_number}")
-
-                    RasPlan.set_num_cores(plan_number, cores_per_run, ras_object=worker_ras_obj)
-
                     print(f"Worker {worker_id} executing plan {plan_number}")
-
-                    success = RasCommander.compute_plan(plan_number, ras_object=worker_ras_obj)
-
+                    success = RasCmdr.compute_plan(
+                        plan_number, 
+                        ras_object=worker_ras_obj, 
+                        clear_geompre=clear_geompre,
+                        num_cores=num_cores
+                    )
                     with results_lock:
                         execution_results[plan_number] = success
                     print(f"Completed: Plan {plan_number} in worker {worker_id}")
@@ -418,30 +258,20 @@ class RasCommander:
                     print(f"Failed: Plan {plan_number} in worker {worker_id}. Error: {str(e)}")
 
         # Start worker threads
-        worker_threads = []
-        for worker_id in range(1, max_workers + 1):
-            worker_ras_instance = worker_ras_objects[worker_id]
-            worker_ras_instance.plan_df = worker_ras_instance.get_plan_entries()
-            worker_ras_instance.geom_df = worker_ras_instance.get_geom_entries()
-            worker_ras_instance.flow_df = worker_ras_instance.get_flow_entries()
-            worker_ras_instance.unsteady_df = worker_ras_instance.get_unsteady_entries()
-            
-            thread = Thread(target=worker_thread, args=(worker_id,))
+        worker_threads = [Thread(target=worker_thread, args=(worker_id,)) for worker_id in range(1, max_workers + 1)]
+        for thread in worker_threads:
             thread.start()
-            worker_threads.append(thread)
-            print(f"Started worker thread {worker_id}")
 
         # Wait for all threads to complete
-        for worker_id, thread in enumerate(worker_threads, 1):
+        for thread in worker_threads:
             thread.join()
-            print(f"Worker thread {worker_id} has completed.")
 
         # Consolidate results
         final_dest_folder = dest_folder_path if dest_folder is not None else project_folder.parent / f"{project_folder.name} [Computed]"
         final_dest_folder.mkdir(exist_ok=True)
         print(f"Final destination for computed results: {final_dest_folder}")
 
-        for worker_id, worker_ras in worker_ras_objects.items():
+        for worker_ras in worker_ras_objects.values():
             worker_folder = worker_ras.project_folder
             try:
                 for item in worker_folder.iterdir():
@@ -453,7 +283,6 @@ class RasCommander:
                             dest_path.unlink()
                     shutil.move(str(item), final_dest_folder)
                 shutil.rmtree(worker_folder)
-                print(f"Moved results and removed worker folder: {worker_folder}")
             except Exception as e:
                 print(f"Error moving results from {worker_folder} to {final_dest_folder}: {str(e)}")
 
@@ -462,4 +291,159 @@ class RasCommander:
         for plan_number, success in execution_results.items():
             print(f"Plan {plan_number}: {'Successful' if success else 'Failed'}")
 
-        return execution_results
+        return execution_results
+    
+    
+    
+    @staticmethod
+    def compute_test_mode(
+        plan_number=None, 
+        dest_folder_suffix="[Test]", 
+        clear_geompre=False, 
+        num_cores=None, 
+        ras_object=None,
+        overwrite_dest=False
+    ):
+        """
+        Execute HEC-RAS plans in test mode.  This is a re-creation of the HEC-RAS command line -test flag, 
+        which does not work in recent versions of HEC-RAS.
+        
+        As a special-purpose function that emulates the original -test flag, it operates differently than the 
+        other two compute_ functions.  Per the original HEC-RAS test flag, it creates a separate test folder,
+        copies the project there, and executes the specified plans in sequential order.
+        
+        For most purposes, just copying a the project folder, initing that new folder, then running each plan 
+        with compute_plan is a simpler and more flexible approach.  This is shown in the examples provided
+        in the ras-commander library.
+
+        Args:
+            plan_number (str, list[str], optional): Plan number or list of plan numbers to execute. 
+                If None, all plans will be executed. Default is None.
+            dest_folder_suffix (str, optional): Suffix to append to the test folder name to create dest_folder. 
+                Defaults to "[Test]".
+                dest_folder is always created in the project folder's parent directory.
+            clear_geompre (bool, optional): Whether to clear geometry preprocessor files.
+                Defaults to False.
+            num_cores (int, optional): Maximum number of cores to use for each plan.
+                If None, the current setting is not changed. Default is None.
+            ras_object (RasPrj, optional): Specific RAS object to use. If None, uses the global ras instance.
+            overwrite_dest (bool, optional): If True, overwrite the destination folder if it exists. Defaults to False.
+
+        Returns:
+            None
+
+        Example:
+            Run all plans: RasCommander.compute_test_mode()
+            Run a specific plan: RasCommander.compute_test_mode(plan_number="01")
+            Run multiple plans: RasCommander.compute_test_mode(plan_number=["01", "03", "05"])
+            Run plans with a custom folder suffix: RasCommander.compute_test_mode(dest_folder_suffix="[TestRun]")
+            Run plans and clear geometry preprocessor files: RasCommander.compute_test_mode(clear_geompre=True)
+            Run plans with a specific number of cores: RasCommander.compute_test_mode(num_cores=4)
+            
+        Notes:
+            - This function executes plans in a separate folder for isolated testing.
+            - If plan_number is not provided, all plans in the project will be executed.
+            - The function does not change the geometry preprocessor and IB tables settings.  
+                - To force recomputing of geometry preprocessor and IB tables, use the clear_geompre=True option.
+            - Plans are executed sequentially.
+            - Because copying the project is implicit, only a dest_folder_suffix option is provided.
+            - For more flexible run management, use the compute_parallel or compute_sequential functions.
+        """
+        
+        # This line of code is used to initialize the RasPrj object with the default "ras" object if no specific object is provided.
+        ras_obj = ras_object or ras
+        # This line of code is used to check if the RasPrj object is initialized.
+        ras_obj.check_initialized()
+        
+        print("Starting the compute_test_mode...")
+           
+        # Use the project folder from the ras object
+        project_folder = ras_obj.project_folder
+
+        # Check if the project folder exists
+        if not project_folder.exists():
+            print(f"Error: Project folder '{project_folder}' does not exist.")
+            return
+
+        # Create test folder with the specified suffix in the same directory as the project folder
+        compute_folder = project_folder.parent / f"{project_folder.name} {dest_folder_suffix}"
+        print(f"Creating the test folder: {compute_folder}...")
+
+        # Check if the compute folder exists and is empty
+        if compute_folder.exists():
+            if overwrite_dest:
+                shutil.rmtree(compute_folder)
+            elif any(compute_folder.iterdir()):
+                raise ValueError(
+                    f"Compute folder '{compute_folder}' exists and is not empty. "
+                    "Use overwrite_dest=True to overwrite."
+                )
+        else:
+            try:
+                shutil.copytree(project_folder, compute_folder)
+            except FileNotFoundError:
+                print(f"Error: Unable to copy project folder. Source folder '{project_folder}' not found.")
+                return
+            except PermissionError:
+                print(f"Error: Permission denied when trying to create or copy to '{compute_folder}'.")
+                return
+            except Exception as e:
+                print(f"Error occurred while copying project folder: {str(e)}")
+                return
+
+        # Initialize a new RAS project in the compute folder
+        try:
+            compute_ras = RasPrj()
+            compute_ras.initialize(compute_folder, ras_obj.ras_exe_path)
+            compute_prj_path = compute_ras.prj_file
+        except Exception as e:
+            print(f"Error initializing RAS project in compute folder: {str(e)}")
+            return
+
+        if not compute_prj_path:
+            print("Project file not found.")
+            return
+
+
+        # Get plan entries
+        print("Getting plan entries...")
+        try:
+            ras_compute_plan_entries = compute_ras.plan_df
+            print("Retrieved plan entries successfully.")
+        except Exception as e:
+            print(f"Error retrieving plan entries: {str(e)}")
+            return
+
+        if plan_number:
+            if isinstance(plan_number, str):
+                plan_number = [plan_number]
+            ras_compute_plan_entries = ras_compute_plan_entries[
+                ras_compute_plan_entries['plan_number'].isin(plan_number)
+            ]
+            print(f"Filtered plans to execute: {plan_number}")
+
+        print("Running selected plans sequentially...")
+        for _, plan in ras_compute_plan_entries.iterrows():
+            plan_number = plan["plan_number"]
+            start_time = time.time()
+            try:
+                RasCommander.compute_plan(
+                    plan_number,
+                    ras_object=compute_ras,
+                    clear_geompre=clear_geompre,
+                    num_cores=num_cores
+                )
+            except Exception as e:
+                print(f"Error computing plan {plan_number}: {str(e)}")
+            end_time = time.time()
+            run_time = end_time - start_time
+            print(f"Total run time for plan {plan_number}: {run_time:.2f} seconds")
+
+        print("All selected plans have been executed.")
+        print("compute_test_mode completed.")
+
+        ras_obj = ras_object or ras
+        ras_obj.plan_df = ras_obj.get_plan_entries()
+        ras_obj.geom_df = ras_obj.get_geom_entries()
+        ras_obj.flow_df = ras_obj.get_flow_entries()
+        ras_obj.unsteady_df = ras_obj.get_unsteady_entries()

ras_commander/RasExamples.py

@@ -10,13 +10,13 @@ from datetime import datetime
 
 class RasExamples:
     """
-    A class for quickly loading HEC-RAS example projects for testing and development of ras_commander.
+    A class for quickly loading HEC-RAS example projects for testing and development of ras-commander.
 
     This class provides functionality to download, extract, and manage HEC-RAS example projects.
     It supports both default HEC-RAS example projects and custom projects from user-provided URLs.
 
     Expected folder structure:              Notes:
-    ras_commander/
+    ras-commander/
     ├── examples/                           # This is examples_dir
     │   ├── example_projects/               # This is projects_dir
     │   │   ├── Balde Eagle Creek/          # Individual Projects from Zip file
@@ -24,9 +24,9 @@ class RasExamples:
     │   │   └── ...
     │   ├── Example_Projects_6_5.zip        # HEC-RAS Example Projects zip file will be downloaded here
     │   ├── example_projects.csv            # CSV file containing cached project metadata
-    │   └── 01_project_initialization.py    # ras_commander library examples are also at this level
+    │   └── 01_project_initialization.py    # ras-commander library examples are also at this level
     │   └── ...
-    └── ras_commander/                      # Code for the ras_commander library
+    └── ras_commander/                      # Code for the ras-commander library
 
     Attributes:
         base_url (str): Base URL for downloading HEC-RAS example projects.

ras_commander/RasPrj.py

@@ -10,7 +10,7 @@ Functions:
     get_ras_exe: Determine the HEC-RAS executable path based on the input.
 
 DEVELOPER NOTE:
-This class is used to initialize a RAS project and is used in conjunction with the RasCommander class to manage the execution of RAS plans.
+This class is used to initialize a RAS project and is used in conjunction with the RasCmdr class to manage the execution of RAS plans.
 By default, the RasPrj class is initialized with the global 'ras' object.
 However, you can create multiple RasPrj instances to manage multiple projects.
 Do not mix and match global 'ras' object instances and custom instances of RasPrj - it will cause errors.

ras_commander/RasUnsteady.py

@@ -10,8 +10,6 @@ class RasUnsteady:
     Class for all operations related to HEC-RAS unsteady flow files.
     """
     
-    
-
     @staticmethod
     def update_unsteady_parameters(unsteady_file, modifications, ras_object=None):
         """
@@ -27,6 +25,18 @@ class RasUnsteady:
 
         Note:
             This function updates the ras object's unsteady dataframe after modifying the unsteady flow file.
+        
+        Example:
+            from ras_commander import RasCmdr
+            
+            # Initialize RAS project
+            ras_cmdr = RasCmdr()
+            ras_cmdr.init_ras_project(project_folder, ras_version)
+            
+            # Update unsteady parameters
+            unsteady_file = r"path/to/unsteady_file.u01"
+            modifications = {"Parameter1": "NewValue1", "Parameter2": "NewValue2"}
+            RasUnsteady.update_unsteady_parameters(unsteady_file, modifications, ras_object=ras_cmdr.ras)
         """
         ras_obj = ras_object or ras
         ras_obj.check_initialized()
@@ -60,5 +70,4 @@ class RasUnsteady:
         else:
             print(f"No matching parameters found in {unsteady_file}")
 
-        ras_obj = ras_object or ras
         ras_obj.unsteady_df = ras_obj.get_unsteady_entries()

ras_commander/RasUtils.py

@@ -1,5 +1,5 @@
 """
-Utility functions for the ras_commander library.
+Utility functions for the ras-commander library.
 """
 import os
 import shutil
@@ -11,7 +11,7 @@ from typing import Union
 
 class RasUtils:
     """
-    A class containing utility functions for the ras_commander library.
+    A class containing utility functions for the ras-commander library.
     When integrating new functions that do not clearly fit into other classes, add them here.
     """
 
@@ -258,8 +258,8 @@ class RasUtils:
         FileNotFoundError: If the plan file doesn't exist
 
         Example:
-        >>> update_plan_entries(1, "Geom", 2)
-        >>> update_plan_entries("path/to/plan.p01", "Geom", 2)
+        >>> RasUtils.update_plan_file(1, "Geom", 2)
+        >>> RasUtils.update_plan_file("path/to/plan.p01", "Geom", 2)
         """
         ras_obj = ras_object or ras
         ras_obj.check_initialized()

ras_commander/__init__.py

@@ -1,7 +1,7 @@
 from importlib.metadata import version, PackageNotFoundError
 
 try:
-    __version__ = version("ras_commander")
+    __version__ = version("ras-commander")
 except PackageNotFoundError:
     # package is not installed
     __version__ = "unknown"
@@ -12,19 +12,19 @@ from .RasPrj import RasPrj
 from .RasPlan import RasPlan
 from .RasGeo import RasGeo
 from .RasUnsteady import RasUnsteady
-from .RasCommander import RasCommander
+from .RasCmdr import RasCmdr
 from .RasUtils import RasUtils
 from .RasExamples import RasExamples
 
 # Import all attributes from these modules
 from .RasPrj import *
-from .RasPrj import *
 from .RasPlan import *
 from .RasGeo import *
 from .RasUnsteady import *
-from .RasCommander import *
+from .RasCmdr import *
 from .RasUtils import *
 from .RasExamples import *
+
 # Define __all__ to specify what should be imported when using "from ras_commander import *"
 __all__ = [
     "ras",
@@ -34,7 +34,7 @@ __all__ = [
     "RasPlan",
     "RasGeo",
     "RasUnsteady",
-    "RasCommander",
+    "RasCmdr",
     "RasUtils",
     "RasExamples"
-]
+]

ras_commander/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.22.0.dev0'
-__version_tuple__ = version_tuple = (0, 22, 0, 'dev0')
+__version__ = version = '0.24.0.dev0'
+__version_tuple__ = version_tuple = (0, 24, 0, 'dev0')

{ras_commander-0.22.0.dev0.dist-info → ras_commander-0.24.0.dev0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
-Name: ras_commander
-Version: 0.22.0.dev0
+Name: ras-commander
+Version: 0.24.0.dev0
 Summary: A library for automating HEC-RAS operations using python functions.
 Author-email: "William Katzenmeyer, P.E., C.F.M." <heccommander@gmail.com>
-Project-URL: Homepage, https://github.com/yourusername/ras_commander
+Project-URL: Homepage, https://github.com/billk-FM/ras-commander
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -11,9 +11,15 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 
-# RAS-Commander (ras_commander)
+# Start of Selection
+# RAS Commander (ras-commander)
 
-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 is an evolution of the RAS-Commander 1.0 Python Notebook Application previously released under the HEC-Commander tools.
+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 is an evolution of the RASCommander 1.0 Python Notebook Application previously released under HEC-Commander tools.
+
+Contributors:
+William Katzenmeyer, P.E., C.F.M. - billk@fenstermaker.com
+Sean Micek, P.E., C.F.M. - smicek@fenstermaker.com
+Aaron Nichols, P.E., C.F.M. - anichols@fenstermaker.com
 
 ## Features
 
@@ -26,9 +32,10 @@ ras_commander is a Python library for automating HEC-RAS operations, providing a
 
 ## Installation
 
-Install ras_commander using pip:
+Install ras-commander using pip:
 
 ```bash
+pip install pandas requests pathlib # Only 3 requirements for ras-commander, needs to be added to the requirements.txt file so pip install works
 pip install ras-commander
 ```
 
@@ -42,19 +49,21 @@ For a full list of dependencies, see the `requirements.txt` file.
 ## Quick Start
 
 ```python
-from ras_commander import init_ras_project, RasCommander, RasPlan
+from ras_commander import init_ras_project, RasCmdr, RasPlan
 
 # Initialize a project
-init_ras_project("/path/to/project", "6.5")
+init_ras_project(r"/path/to/project", "6.5")
 
 # Execute a single plan
-RasCommander.compute_plan("01")
+RasCmdr.compute_plan("01", dest_folder=r"/path/to/results", overwrite_dest=True)
 
 # Execute plans in parallel
-results = RasCommander.compute_parallel(
+results = RasCmdr.compute_parallel(
     plan_numbers=["01", "02"],
     max_workers=2,
-    cores_per_run=2
+    cores_per_run=2,
+    dest_folder=r"/path/to/results",
+    overwrite_dest=True
 )
 
 # Modify a plan
@@ -64,7 +73,7 @@ RasPlan.set_geom("01", "02")
 ## Key Components
 
 - `RasPrj`: Manages HEC-RAS projects
-- `RasCommander`: Handles execution of HEC-RAS simulations
+- `RasCmdr`: Handles execution of HEC-RAS simulations
 - `RasPlan`: Provides functions for modifying and updating plan files
 - `RasGeo`: Handles operations related to geometry files
 - `RasUnsteady`: Manages unsteady flow file operations
@@ -77,27 +86,7 @@ For detailed usage instructions and API documentation, please refer to the [Comp
 
 ## Examples
 
-Check out the `examples/` directory for sample scripts demonstrating various features of ras_commander.
-
-## Development
-
-### Setting up the development environment
-
-1. Clone the repository:
-   ```
-   git clone https://github.com/yourusername/ras_commander.git
-   ```
-2. Create a virtual environment and activate it:
-   ```
-   python -m venv venv
-   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
-   ```
-3. Install the development dependencies:
-   ```
-   pip install -r requirements.txt
-   ```
-Certainly! I'll provide an updated Project Organization Diagram based on the current structure of the ras_commander library. Here's the updated diagram:
-
+Check out the `examples/` directory for sample scripts demonstrating various features of ras-commander.
 
 ## Project Organization Diagram
 
@@ -108,7 +97,7 @@ ras_commander
 │       └── python-package.yml
 ├── ras_commander
 │   ├── __init__.py
-│   ├── RasCommander.py
+│   ├── RasCmdr.py
 │   ├── RasExamples.py
 │   ├── RasGeo.py
 │   ├── RasPlan.py
@@ -142,10 +131,9 @@ ras_commander
 └── requirements.txt
 ```
 
-
 ## Inclusion of .cursorrules and ai_tools for AI-driven Coding Experience
 
-Open the ras_commander folder in the Cursor IDE, and it will automatically include the .cursorrules file in your instructions.  Additionally, two other provided methods for interacting with the library though your current AI subscriptions: 
+Open the ras_commander folder in the Cursor IDE, and it will automatically include the .cursorrules file in your instructions.  Additionally, two other provided methods for interacting with the library through your current AI subscriptions: 
 
 - ChatGPT:  ras_commander GPT Assistant (LINK HERE)
 - Latest LLM summaries of the code base:
@@ -156,63 +144,58 @@ Open the ras_commander folder in the Cursor IDE, and it will automatically inclu
 
 There are a series of scripts provided in the "llm_summaries" folder that provide summaries of the code base, and the docstrings of the functions.  They can be run in your local environment, or provided to ChatGPT's code interpreter for execution.  
 
-## RAS-Commander GPT Assistant 
-
-The ras_commander GPT assistant has access the entire code base, and can be a helpful tool for understanding the library and its capabilities.  However, it is subject to the same context window limitations and file retrieval limtations as I have covered in ADD BLOG LINK HERE.  For best results, use the llm summaries above to provide robust context to the model before asking to generate complex workflows. 
-
-## Contributing
+## RAS-Cmdr GPT Assistant 
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and suggest improvements.
+The RAS Commander GPT assistant has access to the entire code base, and can be a helpful tool for understanding the library and its capabilities.  However, it is subject to the same context window limitations and file retrieval limitations as I have covered in ADD BLOG LINK HERE.  For best results, use the llm summaries above to provide robust context to the model before asking to generate complex workflows. 
 
-## Style Guide
-
-This project follows a specific style guide to maintain consistency across the codebase. Please refer to the [Style Guide](STYLE_GUIDE.md) for details on coding conventions, documentation standards, and best practices.
+## Current Uses and Roadmap Items
 
+### Potential Uses (Roadmap Items) of HEC-RAS Automation Functions
 
-## License
-
-ras_commander is released under the MIT License. See the license file for details.
-
-## Acknowledgments
-
-ras_commander is based on the HEC-Commander project's "Command Line is All You Need" approach, leveraging the HEC-RAS command-line interface for automation. The initial development of this library was presented in the HEC-Commander Tools repository.  In a 2024 Australian Water School webinar, Bill demonstrated the derivation of basic HEC-RAS automation functions from plain language instructions. Leveraging the previously developed code and AI tools, the library was created. The primary tools used for this initial development were Anthropic's Claude, GPT-4o, Google's Gemini Experimental models,and the Cursor AI Coding IDE.
+This set of functions provides a powerful foundation for automating various aspects of HEC-RAS modeling workflows. Here are some potential applications:
 
+1. **Calibration and Sensitivity Analysis:**
+    - **Automated Parameter Variation:** Users can create multiple simulation scenarios with varying parameters (e.g., Manning's n values, boundary conditions, initial conditions) to calibrate their model against observed data.
+    - **Sensitivity Testing:** Evaluate the impact of different input parameters on model outputs by generating a range of scenarios and analyzing the results. This helps identify critical parameters that require more attention during calibration.
 
+2. **Real-time Forecasting:**
+    - **Dynamic Model Updates:** Integrate with external data sources (e.g., weather forecasts, streamflow observations) to automatically update boundary conditions and initial conditions in unsteady flow files before running the simulation.
+    - **Ensemble Forecasting:** Generate multiple forecasts by incorporating uncertainty in input data and model parameters. This provides a more comprehensive understanding of potential future flow conditions.
 
-## Contact
-
-For questions, suggestions, or support, please contact:
-William Katzenmeyer, P.E., C.F.M. - billk@fenstermaker.com
+3. **Scenario Analysis:**
+    - **Land Use Change Impacts:** Evaluate the effects of land use changes on flood risk by modifying Manning's n values using `extract_2d_mannings_tables`, `modify_2d_mannings_table`, and `write_2d_mannings_tables` and running simulations with updated geometry files.
+    - **Climate Change Impacts:** Analyze the potential impacts of projected climate changes on flood risk by adjusting precipitation patterns and other relevant parameters in unsteady flow files.
 
+4. **Batch Processing and High-Performance Computing:**
+    - **Large-scale Model Runs:** Utilize `run_plans_parallel` to execute multiple simulations concurrently on a multi-core system, significantly reducing processing time for large-scale models or complex scenarios.
+    - **Automated Report Generation:** Integrate with Python libraries like matplotlib and bokeh to automatically generate customized reports summarizing simulation results, including tables, figures, and maps.
 
+5. **Model Development and Testing:**
+    - **Rapid Prototyping:** Quickly set up and run new model configurations using template files and automated workflows, facilitating rapid model development and testing.
+    - **Regression Testing:** Ensure model integrity and consistency after code changes or updates by automatically running a predefined set of simulations and comparing results with expected outputs.
 
+6. **User-Friendly Interfaces:**
+    - **GUI Development:** Integrate with Python GUI libraries like Tkinter or PyQt to create user-friendly interfaces for automating HEC-RAS workflows, allowing non-programmers to access the power of automation.
 
+## Contributing
 
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and suggest improvements.
 
+## Style Guide
 
+This project follows a specific style guide to maintain consistency across the codebase. Please refer to the [Style Guide](STYLE_GUIDE.md) for details on coding conventions, documentation standards, and best practices.
 
+## License
 
-NOTES: INCORPORATE INTO THE README.MD FILE ABOVE UNDER A NEW SECTION FOR CURRENT USES AND ROADMAP ITEMS, THEN DELETE THIS NOTE
+ras-commander is released under the MIT License. See the license file for details.
 
+## Acknowledgments
 
-Potential Uses of HEC-RAS Automation Functions
-This set of functions provides a powerful foundation for automating various aspects of HEC-RAS modeling workflows. Here are some potential applications:
-1. Calibration and Sensitivity Analysis:
-Automated Parameter Variation: Users can create multiple simulation scenarios with varying parameters (e.g., Manning's n values, boundary conditions, initial conditions) to calibrate their model against observed data.
-Sensitivity Testing: Evaluate the impact of different input parameters on model outputs by generating a range of scenarios and analyzing the results. This helps identify critical parameters that require more attention during calibration.
-2. Real-time Forecasting:
-Dynamic Model Updates: Integrate with external data sources (e.g., weather forecasts, streamflow observations) to automatically update boundary conditions and initial conditions in unsteady flow files before running the simulation.
-Ensemble Forecasting: Generate multiple forecasts by incorporating uncertainty in input data and model parameters. This provides a more comprehensive understanding of potential future flow conditions.
-3. Scenario Analysis:
-Land Use Change Impacts: Evaluate the effects of land use changes on flood risk by modifying Manning's n values using extract_2d_mannings_tables, modify_2d_mannings_table, and write_2d_mannings_tables and running simulations with updated geometry files.
-Climate Change Impacts: Analyze the potential impacts of projected climate changes on flood risk by adjusting precipitation patterns and other relevant parameters in unsteady flow files.
-4. Batch Processing and High-Performance Computing:
-Large-scale Model Runs: Utilize run_plans_parallel to execute multiple simulations concurrently on a multi-core system, significantly reducing processing time for large-scale models or complex scenarios.
-Automated Report Generation: Integrate with Python libraries like matplotlib and bokeh to automatically generate customized reports summarizing simulation results, including tables, figures, and maps.
-5. Model Development and Testing:
-Rapid Prototyping: Quickly set up and run new model configurations using template files and automated workflows, facilitating rapid model development and testing.
-Regression Testing: Ensure model integrity and consistency after code changes or updates by automatically running a predefined set of simulations and comparing results with expected outputs.
-6. User-Friendly Interfaces:
-GUI Development: Integrate with Python GUI libraries like Tkinter or PyQt to create user-friendly interfaces for automating HEC-RAS workflows, allowing non-programmers to access the power of automation.
+RAS Commander is based on the HEC-Commander project's "Command Line is All You Need" approach, leveraging the HEC-RAS command-line interface for automation. The initial development of this library was presented in the HEC-Commander Tools repository.  In a 2024 Australian Water School webinar, Bill demonstrated the derivation of basic HEC-RAS automation functions from plain language instructions. Leveraging the previously developed code and AI tools, the library was created. The primary tools used for this initial development were Anthropic's Claude, GPT-4o, Google's Gemini Experimental models, and the Cursor AI Coding IDE.
 
+## Contact
 
+For questions, suggestions, or support, please contact:
+William Katzenmeyer, P.E., C.F.M. - billk@fenstermaker.com
+# End of Selection
+```

ras_commander-0.24.0.dev0.dist-info/RECORD

@@ -0,0 +1,14 @@
+ras_commander/RasCmdr.py,sha256=1_DquIgN-5Ljl6a7Tv5dd4ge96HxHXP_dDGaK_BJNEY,21599
+ras_commander/RasExamples.py,sha256=yGWvhFGi9zp88d0ba8m76He6BXwUD-3Snzl4EVo3B-w,13548
+ras_commander/RasGeo.py,sha256=0yNqnjEWh4KcItI9hUPczJ3AhPjld4rFY-W-gNUrnUI,3933
+ras_commander/RasPlan.py,sha256=FU2o9nagq6UXv04WRY6gG01Ef0wOEsJJdqVqMjZ45O0,51789
+ras_commander/RasPrj.py,sha256=g_4XorQ3U_cXk9suPwHDzFcHJeD942oFYFSts3L8klw,15158
+ras_commander/RasUnsteady.py,sha256=_2Sq3ga5ufWQY7pRiUdlGl8NyeakSk8ungHQOf_swSk,2922
+ras_commander/RasUtils.py,sha256=0parcRgrOKfgU6v-oSiiULQN1K3KbtpbtLLL4Vs0Vok,11744
+ras_commander/__init__.py,sha256=uY-IIzmE36WvC1IwQR1OSvll0SY7COcb7rhVw6uvuoA,1050
+ras_commander/_version.py,sha256=ZJJDzsOZCQxqZUvHLC-ADhN-BxwfDGPzKi0nQowJWZI,426
+ras_commander-0.24.0.dev0.dist-info/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
+ras_commander-0.24.0.dev0.dist-info/METADATA,sha256=Wo9hW6r5e-UFBg2IfLIOE4WiX_PiQe6XDppqEQWEQCo,10008
+ras_commander-0.24.0.dev0.dist-info/WHEEL,sha256=AHX6tWk3qWuce7vKLrj7lnulVHEdWoltgauo8bgCXgU,109
+ras_commander-0.24.0.dev0.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
+ras_commander-0.24.0.dev0.dist-info/RECORD,,

ras_commander/README.md

@@ -1,187 +0,0 @@
-"""
-# Developer's README
-
-These notes should be followed by any developer who wants to use this library orcontribute to this project.
-
------
-
-
-# Developer's README for ras_commander
-
-## Project Overview
-
-ras_commander is a Python library for automating HEC-RAS operations. It provides a set of classes and functions to interact with HEC-RAS project files, execute simulations, and manage project data.
-
-## Project Structure
-
-The library is organized into several key modules:
-
-- `RasPrj.py`: Handles project initialization and manages project-level information.
-- `RasCommander.py`: Manages execution of HEC-RAS simulations.
-- `RasPlan.py`: Provides functions for modifying and updating plan files.
-- `RasGeo.py`: Handles operations related to geometry files.
-- `RasUnsteady.py`: Manages unsteady flow file operations.
-- `RasUtils.py`: Contains utility functions for file operations and data management.
-
-## Key Concepts
-
-### RAS Instance Management
-
-The library supports both a global `ras` instance and the ability to create multiple instances for different projects:
-
-- Use the global `ras` instance for simple, single-project scenarios.
-- Create multiple `RasPrj` instances for working with multiple projects simultaneously.
-
-### Function Design
-
-Most functions in the library follow this pattern:
-
-```python
-def some_function(param1, param2, ras_object=None):
-    ras_obj = ras_object or ras
-    ras_obj.check_initialized()
-    # Function implementation
-```
-
-This design allows for flexibility in using either the global instance or a specific project instance.
-
-## ras_commander Best Practices
-
-1. Always check if a project is initialized before performing operations:
-   ```python
-   ras_obj.check_initialized()
-   ```
-
-2. Use the `ras_object` parameter in functions to specify which project instance to use.
-
-3. For complex projects with multiple HEC-RAS folders, prefer passing explicit `ras_object` instances to functions for clarity.
-
-4. Use type hints and descriptive variable names to improve code readability.
-
-5. Handle exceptions appropriately, especially for file operations and HEC-RAS interactions.
-
-6. When adding new functionality, consider its placement within the existing class structure.
-
-7. Update the `__init__.py` file when adding new modules or significant functionality.
-
-## Testing
-
-- Write unit tests for all new functions and methods.
-- Ensure tests cover both single-project and multi-project scenarios.
-- Use the `unittest` framework for consistency with existing tests.
-
-## Documentation
-
-- Keep docstrings up-to-date with any changes to function signatures or behavior.
-- Update the main README.md file when adding new features or changing existing functionality.
-- Consider adding or updating example scripts in the `examples/` directory for new features.
-- Build a notebook first!  We have AI to help us integrate functions into the library once we have a working example. 
-
-
-## Performance Considerations
-
-- For parallel execution of plans, refer to the "Benchmarking is All You Need" blog post in the HEC-Commander repository for guidance on optimal core usage.
-
-## Abbreviations
-
-Consistently use these abbreviations throughout the codebase:
-
-- ras: HEC-RAS
-- prj: Project
-- geom: Geometry
-- pre: Preprocessor
-- geompre: Geometry Preprocessor
-- num: Number
-- init: Initialize
-- XS: Cross Section
-- DSS: Data Storage System
-- GIS: Geographic Information System
-- BC: Boundary Condition
-- IC: Initial Condition
-- TW: Tailwater
-
-## Future Development
-
-Refer to the "Future Development Roadmap" for planned enhancements and features to be implemented.
-
-By following these guidelines, we can maintain consistency, readability, and reliability across the ras_commander library.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-# Understanding and Using RAS Instances in ras_commander
-
-The `RasPrj` class now supports both a global instance named `ras` and the ability to create multiple instances for different projects.
-
-Key points about RAS instances:
-
-1. **Global Instance**: A default global instance named `ras` is still available for backwards compatibility and simple use cases.
-2. **Multiple Instances**: Users can create and manage multiple `RasPrj` instances for different projects.
-3. **Flexible Function Calls**: Most functions now accept an optional `ras_object` parameter, allowing use of specific project instances.
-4. **Consistent State**: Each instance maintains its own project state, ensuring data consistency within each project context.
-
-## Using RAS Instances
-
-### Global Instance
-For simple, single-project scenarios:
-
-```python
-from ras_commander import ras, init_ras_project
-
-# Initialize the global instance
-init_ras_project("/path/to/project", "6.5")
-
-# Use the global instance
-print(f"Working with project: {ras.project_name}")
-plan_file = ras.get_plan_path("01")
-```
-
-### Multiple Instances
-For working with multiple projects:
-
-```python
-from ras_commander import RasPrj, init_ras_project
-
-# Create and initialize separate instances
-project1 = init_ras_project("/path/to/project1", "6.5")
-project2 = init_ras_project("/path/to/project2", "6.5")
-
-# Use specific instances in function calls
-RasPlan.set_geom("01", "02", ras_object=project1)
-RasPlan.set_geom("01", "03", ras_object=project2)
-```
-
-### Best Practices
-1. Always check if a project is initialized before using:
-   ```python
-   def my_function(ras_object=None):
-       ras_obj = ras_object or ras
-       ras_obj.check_initialized()
-       # Proceed with operations using ras_obj
-   ```
-
-2. Use the `ras_object` parameter in functions to specify which project instance to use.
-
-3. For any advance usage with multiple projects, you shouldprefer passing explicit `ras_object` instances to functions for clarity and to avoid unintended use of the global instance.
-
-By supporting both a global instance and multiple instances, ras_commander provides flexibility for various usage scenarios while maintaining simplicity for basic use cases.
-
-"""

ras_commander-0.22.0.dev0.dist-info/RECORD

@@ -1,15 +0,0 @@
-ras_commander/README.md,sha256=MNWyvD9-MA3m3_HRZCk4uzrtIjyyYhhFs5CZ9M8ZNEo,5936
-ras_commander/RasCommander.py,sha256=tpi_RqFLxrV08eFhcVoaf1e_j9539lMpyPKIT0EjHT0,21814
-ras_commander/RasExamples.py,sha256=qNV1KK42S0TllyQ3wWnahQT2GEW1R-_39XI-fOYQemQ,13548
-ras_commander/RasGeo.py,sha256=0yNqnjEWh4KcItI9hUPczJ3AhPjld4rFY-W-gNUrnUI,3933
-ras_commander/RasPlan.py,sha256=FU2o9nagq6UXv04WRY6gG01Ef0wOEsJJdqVqMjZ45O0,51789
-ras_commander/RasPrj.py,sha256=LhlMR6qP9xvLMiPFuwRhRM5yosyLH2h1EyZbnhKgxE8,15163
-ras_commander/RasUnsteady.py,sha256=rsJH45WQU_30lytEgKY2Uxb4LYyHjgJ82UhA2rWzHOM,2442
-ras_commander/RasUtils.py,sha256=aSPkqhbfxomEhNZVL9MAZ_Lf0IF3y5L89tcC5WJAkXs,11732
-ras_commander/__init__.py,sha256=eoOVbWnLH-e405O6ADkO6qhx45a0n60CFgFl7mj4HYs,1089
-ras_commander/_version.py,sha256=Ss5vVtwnG84xro0FVNRmQeuiMm2EPPdx1J-Vny18ryM,426
-ras_commander-0.22.0.dev0.dist-info/LICENSE,sha256=_pbd6qHnlsz1iQ-ozDW_49r86BZT6CRwO2iBtw0iN6M,457
-ras_commander-0.22.0.dev0.dist-info/METADATA,sha256=8nFhNB_dSh_OY_tt2pkqNMiPQJELc4mifgoMJks4ao4,10057
-ras_commander-0.22.0.dev0.dist-info/WHEEL,sha256=AHX6tWk3qWuce7vKLrj7lnulVHEdWoltgauo8bgCXgU,109
-ras_commander-0.22.0.dev0.dist-info/top_level.txt,sha256=i76S7eKLFC8doKcXDl3aiOr9RwT06G8adI6YuKbQDaA,14
-ras_commander-0.22.0.dev0.dist-info/RECORD,,