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

ras_commander/project_init.py

@@ -0,0 +1,174 @@
+from .project_config import ProjectConfig
+from pathlib import Path
+
+def init_ras_project(ras_project_folder, hecras_version_or_path):
+    """
+    Initialize a HEC-RAS project.
+
+    This function sets up a HEC-RAS project by validating the project folder,
+    determining the HEC-RAS executable path, and initializing the project configuration.
+
+    Args:
+        ras_project_folder (str): Path to the HEC-RAS project folder.
+        hecras_version_or_path (str): Either the HEC-RAS version number or the full path to the HEC-RAS executable.
+
+    Returns:
+        ProjectConfig: An initialized ProjectConfig object containing the project configuration.
+
+    Raises:
+        FileNotFoundError: If the specified RAS project folder does not exist.
+
+    Note:
+        This function prints a confirmation message upon successful initialization.
+        
+    Future Development Roadmap: 
+    
+    1. Load critical keys and values from the project files into the project config
+        Implemented:
+        - Project Name
+        - Project Folder
+        - Lists of plan, flow, unsteady, and geometry files
+        - HEC-RAS Executable Path
+        
+        Not Implemented:
+        - Units 
+        - Coordinate System 
+        - rasmap file path (replace prj file path extension with ".rasmap" and add it to the project config)
+        - Current Plan
+        - Description (including checks to see if it is a valid string and within the default max length)
+        - DSS Start Date=01JAN1999 (note format is MMDDYYY)
+        - DSS Start Time=1200 (note format is HHMM)
+        - DSS End Date=04JAN1999 (note format is MMDDYYY)
+        - DSS End Time=1200 (note format is HHMM)
+        - DSS File=dss
+        - DSS File=Bald_Eagle_Creek.dss 
+              
+    Other not implemented:
+    
+    2. Load critical keys and lists of string values from the plan files into the project config
+        - Plan Title
+        - Plan Shortid
+        - Simulation Date
+        - Geometry File
+        - Flow File (may not be present) - if present, the plan is a 1D steady plan
+        - Unsteady File (may not be present) - if present, the plan is a 1D or 2D unsteady plan
+        - UNET D2 Name (may not be present) - if present, the plan is a 2D plan
+        - Type (1D Steady, 1D Unsteady, 1D/2D, or 2D)
+        - UNET 1D Methodology
+       
+    3. Load critical keys and strings from the unsteady flow files into the project config
+        - Flow Title
+        - Pandas Dataframe for any Boundary Conditions present and whether they are defined in the file or whether they use a DSS file input
+           - One dataframe for all unsteady flow files, with each Boundary Location in each file having its own row
+           - For each unsteady flow filereturn an appended dataframe with each boundary condition and it's "Boundary Name", "Interval", "DSS Path", "Flow Hydrograph Slope", and whether Use DSS is True or False
+           - Need to incorporate knowledge from the excel methods we used for setting boundary conditions
+           
+    4. Load critical keys and strings from the steady flow files into the project config
+        - Flow Title
+        - Since steady models are not as commonly used, this is a low priority integration (external contributions are welcome)
+               
+    
+    5. Load critical keys and values from the rasmap file into the project config
+        - rasmap_projection_string
+        - Version   #Ex: <Version>2.0.0</Version> 
+        - RASProjectionFilename Filename=".\Terrain\Projection.prj"
+        
+        - List of ras terrains as pandas dataframes
+            - for each, list of tiff files and order
+            - flag whether terrain mods exist 
+            
+        - List of Infiltration hdf files as pandas dataframes
+            - Mapping of infiltration layers to geometries
+            
+        - List of land cover hdf files as pandas dataframes
+            - Mapping of land cover to geometries
+        
+        - List of all Mannings N layers, hdf files and mapping to geometries as pandas dataframes
+            
+    6. Create a list of all valid hdf plan files are present in the project folder, and flag whether they contain a completed simulation
+    
+    This roadmap for the project_init function will provide the basic information needed to support most basic hec-ras automation workflows.  
+    
+    Remember, this project init might be called multiple times.  Every time, it should clear any previously created datafrarmes and variables and replace them.  It is important that revisions can be made, init be re-run, and information is current and reflects the current state of the project. 
+
+        
+        
+    """
+    # Check if the provided paths exist
+    if not Path(ras_project_folder).exists():
+        raise FileNotFoundError(f"The specified RAS project folder does not exist: {ras_project_folder}, Please check the path and try again.")
+    
+    hecras_exe_path = get_hecras_exe_path(hecras_version_or_path)
+    
+    config = ProjectConfig()
+    config.initialize(ras_project_folder, hecras_exe_path)
+    print(f"HEC-RAS project initialized: {config.project_name}")
+    return config
+
+
+def get_hecras_exe_path(hecras_version_or_path):
+    """
+    Determine the HEC-RAS executable path based on the input.
+    
+    Args:
+    hecras_version_or_path (str): Either a version number or a full path to the HEC-RAS executable.
+    
+    Returns:
+    str: The full path to the HEC-RAS executable.
+    
+    Raises:
+    ValueError: If the input is neither a valid version number nor a valid file path.
+    FileNotFoundError: If the executable file does not exist at the specified or constructed path.
+    """
+    
+    
+    # hecras_exe_path should be changed to hecras_version_or_path
+    # Based on whether a full path is provided, or a version number is provided, the path will be set accordingly
+    # By default, HEC-RAS is installed in the Program Files (x86) folder 
+    # For example: hecras_exe_path = r"C:\Program Files (x86)\HEC\HEC-RAS\6.5\Ras.exe" for version 6.5
+    # an f string to build the path based on the version number
+    # hecras_exe_path = f"C:\Program Files (x86)\HEC\HEC-RAS\{hecras_version}\Ras.exe"
+    # where hecras_version is one of the following: 
+    
+    # List of HEC-RAS version numbers
+    ras_version_numbers = [
+        "6.5", "6.4.1", "6.3.1", "6.3", "6.2", "6.1", "6.0",
+        "5.0.7", "5.0.6", "5.0.5", "5.0.4", "5.0.3", "5.0.1", "5.0",
+        "4.1", "4.0", "3.1.3", "3.1.2", "3.1.1", "3.0", "2.2"
+    ]
+    
+    hecras_path = Path(hecras_version_or_path)
+    
+    # Check if the input is a full path
+    if hecras_path.is_file() and hecras_path.suffix.lower() == '.exe':
+        return str(hecras_path)
+    
+    # Check if the input is a version number
+    if hecras_version_or_path in ras_version_numbers:
+        default_path = Path(f"C:/Program Files (x86)/HEC/HEC-RAS/{hecras_version_or_path}/Ras.exe")
+        if default_path.is_file():
+            return str(default_path)
+        else:
+            raise FileNotFoundError(f"HEC-RAS executable not found at the expected path: {default_path}")
+    
+    # Check if it's a newer version
+    try:
+        version_float = float(hecras_version_or_path)
+        if version_float > max(float(v) for v in ras_version_numbers):
+            newer_version_path = Path(f"C:/Program Files (x86)/HEC/HEC-RAS/{hecras_version_or_path}/Ras.exe")
+            if newer_version_path.is_file():
+                return str(newer_version_path)
+            else:
+                raise FileNotFoundError(f"Newer version of HEC-RAS was specified. Check the version number or pass the full Ras.exe path as the function argument instead of the version number. The script looked for the executable at: {newer_version_path}")
+    except ValueError:
+        pass  # Not a valid float, so not a version number
+    
+    raise ValueError(f"Invalid HEC-RAS version or path: {hecras_version_or_path}. "
+                     f"Please provide a valid version number from {ras_version_numbers} "
+                     "or a full path to the HEC-RAS executable.")
+    # Return the validated HEC-RAS executable path
+    return hecras_exe_path
+
+
+
+

ras_commander/project_management.py

@@ -0,0 +1,227 @@
+"""
+Project management operations for HEC-RAS projects.
+"""
+import os
+import re
+import shutil
+from pathlib import Path
+from .file_operations import FileOperations
+from .project_config import ProjectConfig
+
+class ProjectManager:
+    """
+    A class for functions that interface with the HEC-RAS project's project file.
+    """
+    @staticmethod
+    def get_next_available_number(existing_numbers):
+        """
+        Determine the first available number for plan, unsteady, steady, or geometry files from 01 to 99.
+        Parameters:
+        existing_numbers (pandas.Series): Series of existing numbers as strings (e.g., ['01', '02', '03'])
+        Returns:
+        str: First available number as a two-digit string
+        """
+        existing_set = set(existing_numbers.astype(int))
+        for num in range(1, 100):
+            if num not in existing_set:
+                return f"{num:02d}"
+        return None
+
+    @staticmethod
+    def copy_plan_from_template(template_plan, new_plan_shortid=None):
+        """
+        Create a new plan file based on a template and update the project file.
+        Parameters:
+        template_plan (str): Plan file to use as template (e.g., 'p01')
+        new_plan_shortid (str, optional): New short identifier for the plan file
+        Returns:
+        str: New plan number
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+
+        new_plan_num = ProjectManager.get_next_available_number(config.ras_plan_entries['plan_number'])
+        template_plan_path = config.project_folder / f"{config.project_name}.{template_plan}"
+        new_plan_path = config.project_folder / f"{config.project_name}.p{new_plan_num}"
+        shutil.copy(template_plan_path, new_plan_path)
+        print(f"Copied {template_plan_path} to {new_plan_path}")
+
+        with open(new_plan_path, 'r') as f:
+            plan_lines = f.readlines()
+
+        shortid_pattern = re.compile(r'^Short Identifier=(.*)$', re.IGNORECASE)
+        for i, line in enumerate(plan_lines):
+            match = shortid_pattern.match(line.strip())
+            if match:
+                current_shortid = match.group(1)
+                if new_plan_shortid is None:
+                    new_shortid = (current_shortid + "_copy")[:24]
+                else:
+                    new_shortid = new_plan_shortid[:24]
+                plan_lines[i] = f"Short Identifier={new_shortid}\n"
+                break
+
+        with open(new_plan_path, 'w') as f:
+            f.writelines(plan_lines)
+
+        print(f"Updated short identifier in {new_plan_path}")
+
+        with open(config.project_file, 'r') as f:
+            lines = f.readlines()
+
+        new_plan_line = f"Plan File=p{new_plan_num}\n"
+        plan_file_pattern = re.compile(r'^Plan File=p(\d+)', re.IGNORECASE)
+        insertion_index = None
+        for i, line in enumerate(lines):
+            match = plan_file_pattern.match(line.strip())
+            if match:
+                current_number = int(match.group(1))
+                if current_number > int(new_plan_num):
+                    insertion_index = i
+                    break
+
+        if insertion_index is not None:
+            lines.insert(insertion_index, new_plan_line)
+        else:
+            last_plan_index = max([i for i, line in enumerate(lines) if plan_file_pattern.match(line.strip())], default=-1)
+            if last_plan_index != -1:
+                lines.insert(last_plan_index + 1, new_plan_line)
+            else:
+                lines.append(new_plan_line)
+
+        with open(config.project_file, 'w') as f:
+            f.writelines(lines)
+
+        print(f"Updated {config.project_file} with new plan p{new_plan_num}")
+        return f"p{new_plan_num}"
+
+    @staticmethod
+    def copy_geometry_from_template(template_geom):
+        """
+        Copy geometry files from a template, find the next geometry number,
+        and update the project file accordingly.
+        Parameters:
+        template_geom (str): Geometry number to be used as a template (e.g., 'g01')
+        Returns:
+        str: New geometry number (e.g., 'g03')
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+
+        template_geom_filename = f"{config.project_name}.{template_geom}"
+        template_geom_path = config.project_folder / template_geom_filename
+
+        if not template_geom_path.is_file():
+            raise FileNotFoundError(f"Template geometry file '{template_geom_path}' does not exist.")
+
+        template_hdf_path = template_geom_path.with_suffix('.hdf')
+        if not template_hdf_path.is_file():
+            raise FileNotFoundError(f"Template geometry .hdf file '{template_hdf_path}' does not exist.")
+
+        next_geom_number = ProjectManager.get_next_available_number(config.ras_geom_entries['geom_number'])
+
+        new_geom_filename = f"{config.project_name}.g{next_geom_number}"
+        new_geom_path = config.project_folder / new_geom_filename
+
+        shutil.copyfile(template_geom_path, new_geom_path)
+        print(f"Copied '{template_geom_path}' to '{new_geom_path}'.")
+
+        new_hdf_path = new_geom_path.with_suffix('.hdf')
+        shutil.copyfile(template_hdf_path, new_hdf_path)
+        print(f"Copied '{template_hdf_path}' to '{new_hdf_path}'.")
+
+        with open(config.project_file, 'r') as file:
+            lines = file.readlines()
+
+        new_geom_line = f"Geom File=g{next_geom_number}\n"
+        geom_file_pattern = re.compile(r'^Geom File=g(\d+)', re.IGNORECASE)
+        insertion_index = None
+        for i, line in enumerate(lines):
+            match = geom_file_pattern.match(line.strip())
+            if match:
+                current_number = int(match.group(1))
+                if current_number > int(next_geom_number):
+                    insertion_index = i
+                    break
+
+        if insertion_index is not None:
+            lines.insert(insertion_index, new_geom_line)
+        else:
+            header_pattern = re.compile(r'^(Proj Title|Current Plan|Default Exp/Contr|English Units)', re.IGNORECASE)
+            header_indices = [i for i, line in enumerate(lines) if header_pattern.match(line.strip())]
+            if header_indices:
+                last_header_index = header_indices[-1]
+                lines.insert(last_header_index + 2, new_geom_line)
+            else:
+                lines.insert(0, new_geom_line)
+
+        with open(config.project_file, 'w') as file:
+            file.writelines(lines)
+
+        print(f"Inserted 'Geom File=g{next_geom_number}' into project file '{config.project_file}'.")
+        return f"g{next_geom_number}"
+
+    @staticmethod
+    def copy_unsteady_from_template(template_unsteady):
+        """
+        Copy unsteady flow files from a template, find the next unsteady number,
+        and update the project file accordingly.
+        Parameters:
+        template_unsteady (str): Unsteady flow number to be used as a template (e.g., 'u01')
+        Returns:
+        str: New unsteady flow number (e.g., 'u03')
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+
+        template_unsteady_filename = f"{config.project_name}.{template_unsteady}"
+        template_unsteady_path = config.project_folder / template_unsteady_filename
+
+        if not template_unsteady_path.is_file():
+            raise FileNotFoundError(f"Template unsteady flow file '{template_unsteady_path}' does not exist.")
+
+        next_unsteady_number = ProjectManager.get_next_available_number(config.ras_unsteady_entries['unsteady_number'])
+
+        new_unsteady_filename = f"{config.project_name}.u{next_unsteady_number}"
+        new_unsteady_path = config.project_folder / new_unsteady_filename
+
+        shutil.copyfile(template_unsteady_path, new_unsteady_path)
+        print(f"Copied '{template_unsteady_path}' to '{new_unsteady_path}'.")
+
+        template_hdf_path = template_unsteady_path.with_suffix('.hdf')
+        new_hdf_path = new_unsteady_path.with_suffix('.hdf')
+
+        if template_hdf_path.is_file():
+            shutil.copyfile(template_hdf_path, new_hdf_path)
+            print(f"Copied '{template_hdf_path}' to '{new_hdf_path}'.")
+        else:
+            print(f"No corresponding '.hdf' file found for '{template_unsteady_filename}'. Skipping '.hdf' copy.")
+
+        with open(config.project_file, 'r') as file:
+            lines = file.readlines()
+
+        new_unsteady_line = f"Unsteady File=u{next_unsteady_number}\n"
+        unsteady_file_pattern = re.compile(r'^Unsteady File=u(\d+)', re.IGNORECASE)
+        insertion_index = None
+        for i, line in enumerate(lines):
+            match = unsteady_file_pattern.match(line.strip())
+            if match:
+                current_number = int(match.group(1))
+                if current_number > int(next_unsteady_number):
+                    insertion_index = i
+                    break
+
+        if insertion_index is not None:
+            lines.insert(insertion_index, new_unsteady_line)
+        else:
+            last_unsteady_index = max([i for i, line in enumerate(lines) if unsteady_file_pattern.match(line.strip())], default=-1)
+            if last_unsteady_index != -1:
+                lines.insert(last_unsteady_index + 1, new_unsteady_line)
+            else:
+                lines.append(new_unsteady_line)
+
+        with open(config.project_file, 'w') as file:
+            file.writelines(lines)
+
+        print(f"Inserted 'Unsteady File=u{next_unsteady_number}' into project file '{config.project_file}'.")
+        return f"u{next_unsteady_number}"

ras_commander/project_setup.py

@@ -0,0 +1,15 @@
+# REVISION NOTE: We should be able to move these functions into the project_management.py file and delete this file. 
+
+from pathlib import Path
+from .file_operations import FileOperations
+
+def find_hecras_project_file(folder_path):
+    return FileOperations.find_hecras_project_file(folder_path)
+
+def load_project_data(project_file):
+    return {
+        'ras_plan_entries': FileOperations.get_plan_entries(project_file),
+        'ras_flow_entries': FileOperations.get_flow_entries(project_file),
+        'ras_unsteady_entries': FileOperations.get_unsteady_entries(project_file),
+        'ras_geom_entries': FileOperations.get_geom_entries(project_file)
+    }

ras_commander/unsteady_operations.py

@@ -0,0 +1,172 @@
+"""
+Operations for handling unsteady flow files in HEC-RAS projects.
+"""
+from pathlib import Path
+from .project_config import ProjectConfig
+import re
+
+class UnsteadyOperations:
+    """
+    Class for all operations related to HEC-RAS unsteady flow files.
+    """
+    @staticmethod
+    def copy_unsteady_files(dst_folder, template_unsteady):
+        """
+        Copy unsteady flow files from a template to the next available unsteady number
+        and update the destination folder accordingly.
+
+        Parameters:
+        dst_folder (str): Destination folder path
+        template_unsteady (str): Template unsteady flow number (e.g., 'u01')
+
+        Returns:
+        str: New unsteady flow number (e.g., 'u03')
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+
+        src_folder = config.project_folder
+        dst_folder = Path(dst_folder)
+        dst_folder.mkdir(parents=True, exist_ok=True)
+
+        # Determine the next available unsteady number
+        existing_numbers = []
+        unsteady_file_pattern = re.compile(r'^Flow File=u(\d+)', re.IGNORECASE)
+
+        for plan_file in src_folder.glob("*.p[0-9][0-9]"):
+            with open(plan_file, 'r') as file:
+                lines = file.readlines()
+                for line in lines:
+                    match = unsteady_file_pattern.match(line.strip())
+                    if match:
+                        existing_numbers.append(int(match.group(1)))
+
+        if existing_numbers:
+            existing_numbers.sort()
+            next_number = 1
+            for num in existing_numbers:
+                if num == next_number:
+                    next_number += 1
+                else:
+                    break
+        else:
+            next_number = 1
+
+        next_unsteady_number = f"{next_number:02d}"
+
+        # Copy the template unsteady file to the new unsteady file
+        template_unsteady_filename = f"{config.project_name}.u{template_unsteady}"
+        src_u_file = src_folder / template_unsteady_filename
+        if src_u_file.exists():
+            new_unsteady_filename = f"{config.project_name}.u{next_unsteady_number}"
+            dst_u_file = dst_folder / new_unsteady_filename
+            dst_u_file.write_bytes(src_u_file.read_bytes())
+            print(f"Copied {src_u_file} to {dst_u_file}")
+        else:
+            raise FileNotFoundError(f"Template unsteady file '{src_u_file}' does not exist.")
+
+        # Copy the corresponding .hdf file
+        src_hdf_file = src_folder / f"{template_unsteady_filename}.hdf"
+        if src_hdf_file.exists():
+            new_hdf_filename = f"{new_unsteady_filename}.hdf"
+            dst_hdf_file = dst_folder / new_hdf_filename
+            dst_hdf_file.write_bytes(src_hdf_file.read_bytes())
+            print(f"Copied {src_hdf_file} to {dst_hdf_file}")
+        else:
+            print(f"No corresponding .hdf file found for '{template_unsteady_filename}'. Skipping '.hdf' copy.")
+        config = ProjectConfig()
+        return f"u{next_unsteady_number}"
+
+    @staticmethod
+    def rename_unsteady_files(old_number, new_number):
+        """
+        Rename unsteady flow files in the project folder.
+        Parameters:
+        old_number (str): Old unsteady flow number (e.g., 'u01')
+        new_number (str): New unsteady flow number (e.g., 'u02')
+        Returns:
+        None
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        folder = config.project_folder
+        old_u_file = next(folder.glob(f"*.{old_number}"), None)
+        if old_u_file:
+            new_u_file = folder / old_u_file.name.replace(old_number, new_number)
+            old_u_file.rename(new_u_file)
+            print(f"Renamed {old_u_file} to {new_u_file}")
+        else:
+            print(f"No .{old_number} file found in {folder}")
+        
+        old_hdf_file = next(folder.glob(f"*.{old_number}.hdf"), None)
+        if old_hdf_file:
+            new_hdf_file = folder / old_hdf_file.name.replace(old_number, new_number)
+            old_hdf_file.rename(new_hdf_file)
+            print(f"Renamed {old_hdf_file} to {new_hdf_file}")
+        else:
+            print(f"No .{old_number}.hdf file found in {folder}")
+
+    @staticmethod
+    def update_unsteady_reference_in_plan(plan_file, new_unsteady_number):
+        """
+        Update the unsteady flow reference in a plan file.
+        
+        Parameters:
+        plan_file (str): Full path to the plan file
+        new_unsteady_number (str): New unsteady flow number (e.g., 'u02')
+        
+        Returns:
+        None
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        plan_path = Path(plan_file)
+        if not plan_path.is_file():
+            raise FileNotFoundError(f"Plan file '{plan_path}' not found. Check that the file exists.")
+        
+        with open(plan_path, 'r') as f:
+            lines = f.readlines()
+        updated = False
+        for i, line in enumerate(lines):
+            if line.startswith("Unsteady File=") or line.startswith("Flow File=u"):
+                lines[i] = f"Unsteady File={new_unsteady_number}\n"
+                updated = True
+                break
+        if updated:
+            with open(plan_path, 'w') as f:
+                f.writelines(lines)
+            print(f"Updated unsteady flow reference in {plan_file} to {new_unsteady_number}")
+        else:
+            print(f"No unsteady flow reference found in {plan_file}")
+            
+    @staticmethod
+    def modify_unsteady_flow_parameters(unsteady_file, modifications):
+        """
+        Modify parameters in an unsteady flow file.
+        Parameters:
+        unsteady_file (str): Full path to the unsteady flow file
+        modifications (dict): Dictionary of modifications to apply, where keys are parameter names and values are new values
+        Returns:
+        None
+        """
+        config = ProjectConfig()
+        config.check_initialized()
+        
+        unsteady_path = Path(unsteady_file)
+        with open(unsteady_path, 'r') as f:
+            lines = f.readlines()
+        updated = False
+        for i, line in enumerate(lines):
+            for param, new_value in modifications.items():
+                if line.startswith(f"{param}="):
+                    lines[i] = f"{param}={new_value}\n"
+                    updated = True
+                    print(f"Updated {param} to {new_value}")
+        if updated:
+            with open(unsteady_path, 'w') as f:
+                f.writelines(lines)
+            print(f"Applied modifications to {unsteady_file}")
+        else:
+            print(f"No matching parameters found in {unsteady_file}")