Add sample data run function and output resampling utility

Introduces two new utility functions in SuPy:
- `run_supy_sample()`: Quickly run SuPy simulation with sample data
- `resample_output()`: Utility for resampling simulation outputs

Expands module's ease of use by providing a convenient method for quick simulations and data processing.

Author: sunt05

src/supy/__init__.py

@@ -25,6 +25,8 @@
     check_forcing,
     check_state,
     init_config,
+    run_supy_sample,
+    resample_output,
 )
 
 

src/supy/_supy_module.py

@@ -37,6 +37,7 @@
 )
 from ._run import run_supy_par, run_supy_ser
 from ._save import get_save_info, save_df_output, save_df_state, save_initcond_nml
+from ._post import resample_output
 
 from .util._config import init_config_from_yaml
 
@@ -335,7 +336,7 @@ def init_config(df_state: pd.DataFrame=None):
     if df_state is None:
         from .util._config import SUEWSConfig
         return SUEWSConfig()
-    
+
     return load_config_from_df(df_state)
 
 
@@ -581,3 +582,67 @@ def save_supy(
         list_path_save.append(path_state_save)
 
     return list_path_save
+
+
+def run_supy_sample(
+    save_state=False,
+    chunk_day=3660,
+    logging_level=logging.INFO,
+    check_input=False,
+    serial_mode=False,
+    debug_mode=False,
+) -> Tuple[pandas.DataFrame, pandas.DataFrame]:
+    """Quickly run SuPy with sample data and return output dataframes.
+
+    This function loads sample data and runs SuPy simulation in one step,
+    returning the output and final state dataframes.
+
+    Parameters
+    ----------
+    save_state : bool, optional
+        Flag for saving model states at each time step.
+        (the default is False)
+    chunk_day : int, optional
+        Chunk size (days) to split simulation periods.
+        (the default is 3660)
+    logging_level : int, optional
+        Logging level for verbosity control.
+        (the default is logging.INFO)
+    check_input : bool, optional
+        Flag for checking validity of input.
+        (the default is False)
+    serial_mode : bool, optional
+        If True, run in serial mode; otherwise try parallel if possible.
+        (the default is False)
+    debug_mode : bool, optional
+        If True, run in debug mode with additional information.
+        (the default is False)
+
+    Returns
+    -------
+    df_output, df_state_final : Tuple[pandas.DataFrame, pandas.DataFrame]
+        - df_output: Output results from the simulation
+        - df_state_final: Final model states
+
+    Examples
+    --------
+    >>> df_output, df_state_final = supy.run_supy_sample()
+    """
+    # Load sample data
+    df_state_init, df_forcing = load_sample_data()
+
+    # Run SuPy with the sample data
+    df_output, df_state_final = run_supy(
+        df_forcing=df_forcing,
+        df_state_init=df_state_init,
+        save_state=save_state,
+        chunk_day=chunk_day,
+        logging_level=logging_level,
+        check_input=check_input,
+        serial_mode=serial_mode,
+        debug_mode=debug_mode,
+    )
+
+    return df_output, df_state_final
+
+