Bug Fixes (#39)

docs/api.md

@@ -1,6 +1,6 @@
 # API Documentation
 
-::: river_route.MuskingumCunge
+::: river_route.Muskingum
     handler: python
     options:
       members_order: source

docs/index.md

@@ -1,14 +1,14 @@
 # River-Route
 
-The `river-route` Python package is a tool for routing catchment runoff volumes on vector stream networks using the Matrix Muskingum Cunge Method.
-It implements Matrix Muskingum Cunge routing. Inspired by the first linear routing implementation published by 
+The `river-route` Python package is a tool for routing catchment runoff volumes on vector stream networks using the Matrix Muskingum Method.
+It implements Matrix Muskingum routing. Inspired by the first implementation published by
 [Cedric David in 2011](https://doi.org/10.1175/2011JHM1345.1) which was corrected and improved by Riley Hales in 2023.
 
 ## Quick Start
 
 !!! note
-    `river-route` requires prepared watershed and runoff datasets. Refer to the [Tutorial](tutorial/basic-tutorial.md)
-    and [Advanced Tips](tutorial/advanced-tutorial.md).
+`river-route` requires prepared watershed and runoff datasets. Refer to the [Tutorial](tutorial/basic-tutorial.md)
+and [Advanced Tips](tutorial/advanced-tutorial.md).
 
 ```commandline
 pip install river-route
@@ -19,7 +19,7 @@ import river_route as rr
 
 (
     rr
-    .MuskingumCunge('/path/to/config.yaml')
+    .Muskingum('/path/to/config.yaml')
     .route()
 )
 ```
@@ -52,7 +52,7 @@ graph LR
         a[Calculate LHS] --> b
         b[Read Volumes Array] --> c
         c[Iterate On Routing Intervals] --> d
-        d[Solving Matrix\nMuskingum Cunge] --> e
+        d[Solving Matrix\nMuskingum] --> e
         e[Enforce Positive Flows] --> f & c
         f[Write Outflows to Disk] --> g
         g[Cache Final State]
@@ -72,7 +72,7 @@ graph LR
 
 ## Usage Example
 
-You can pass the configuration options to the `rr.MuskingumCunge` class init by specifying a path to a config file, use
+You can pass the configuration options to the `rr.Muskingum` class init by specifying a path to a config file, use
 keyword arguments, or use both a config file path and keyword arguments to supplement or override values from the config
 file.
 
@@ -82,14 +82,14 @@ import river_route as rr
 # Option 1 - Give all arguments via a configuration file
 (
     rr
-    .MuskingumCunge('/path/to/config.yaml')
+    .Muskingum('/path/to/config.yaml')
     .route()
 )
 
 # Option 2 - Give all arguments via keyword arguments
 (
     rr
-    .MuskingumCunge(**{
+    .Muskingum(**{
         'routing_params_file': '/path/to/routing_params.parquet',
         'connectivity_file': '/path/to/connectivity.parquet',
         'catchment_volumes_file': '/path/to/volumes.nc',
@@ -101,7 +101,7 @@ import river_route as rr
 # Option 3 - Use both a configuration file and keyword arguments
 (
     rr
-    .MuskingumCunge(
+    .Muskingum(
         '/path/to/config.yaml',
         **{
             'routing_params_file': '/path/to/routing_params.parquet',

docs/references/config-files.md

@@ -23,7 +23,7 @@ Every `river-route` process needs at least the following 4 variables
 
 An example yaml file is given below with the default values prepopulated where possible.
 
-```yaml title="Config File Example river-route v0.15.0"
+```yaml title="Config File Example river-route v1.0.3"
 {% include-markdown "../../examples/config.yaml" %}
 ```
 
@@ -39,7 +39,6 @@ The following table is a complete list of all configuration options and their pu
 | runoff_depths_files    | True     | File Path | Required Input      | List of paths to netCDF files with runoff depths to be routed.         |
 | weight_table_file      | True     | File Path | Required Input      | Path to the weight table file.                                         |
 | outflow_file           | True     | File Path | Required Input      | Path where the outflows netCDF file should be saved.                   |
-| routing                | False    | String    | Compute Options     | The routing method to use: "linear" or "nonlinear".                    |
 | input_type             | False    | String    | Compute Options     | Specify if runoff files are "sequential" time steps or an "ensemble"   |
 | runoff_type            | False    | String    | Compute Options     | Specify if runoff files are "incremental" or "cumulative"              |
 | dt_routing             | True     | Integer   | Compute Options     | Time interval in seconds between routing computations.                 |                              

docs/references/io-file-schema.md

@@ -7,19 +7,13 @@ routing_params_file: '/path/to/params.parquet'
 ```
 
 The routing parameters file is a parquet file. It has 3 columns and 1 row per river in the watershed. The index is
-ignored. If you use nonlinear routing, you can provide more columns with k and x values to use at different thresholds
-of Q. Nonlinear routing columns should be named k_1, x_1, q_1, followed by k_2, x_2, q_2, for as many thresholds as you
-chose. You may provide as many columns as you wish as long as you also provide a thresholds file. The rows (rivers)
-***must be sorted in topological order*** from upstream to downstream.
-
-| Column   | Data Type | Description                                                                    |
-|----------|-----------|--------------------------------------------------------------------------------|
-| river_id | integer   | Unique ID of a river segment                                                   |
-| k        | float     | the k parameter of the MuskingumCunge Cunge routing equation length / velocity |
-| x        | float     | the x parameter of the MuskingumCunge Cunge routing equation. x : [0, 0.5]     |
-| k_1      | float     | Optional, the k parameter of the MuskingumCunge Cunge routing equation at Q_1  |
-| x_1      | float     | Optional, the x parameter of the MuskingumCunge Cunge routing equation at Q_1  |
-| q_1      | float     | Optional, the minimum value of Q at which to start using use k_1 and x_1       |
+ignored. The rows (rivers) ***must be sorted in topological order*** from upstream to downstream.
+
+| Column   | Data Type | Description                                                              |
+|----------|-----------|--------------------------------------------------------------------------|
+| river_id | integer   | Unique ID of a river segment                                             |
+| k        | float     | the k parameter of the Muskingum routing equation length / velocity      |
+| x        | float     | the x parameter of the Muskingum routing equation. x : [0, 0.5]          |
 
 ### Connectivity File
 
@@ -125,5 +119,5 @@ initial_state_file: '/path/to/initial.parquet'
 final_state_file: '/path/to/final.parquet'
 ```
 
-State information are stored in parquet files. Muskingum Cunge routing solves for river discharge at time t+1 as a
+State information are stored in parquet files. Muskingum routing solves for river discharge at time t+1 as a
 function of inflow volumes at time t and time t+1, and the discharge at time t. 

docs/references/time-variables.md

@@ -37,6 +37,14 @@ dt_total == dt_runoff * number_of_time_steps
   be automatically constructed.
 - The length of the routing computations must be equal to the length of the runoff data.
 
+## Right and Left Aligned Time Series
+
+!!! warning
+    Runoff data may be given by right- or left-aligned dates and intervals. For example, hourly runoff data may say 5pm and the runoff number may 
+    represent the runoff that occurred from 4pm to 5pm (right-aligned) or from 5pm to 6pm (left-aligned). The routing calculations are performed and 
+    interpretations are most naturally computed with right-aligned dates but can be valid with left-aligned dates. Beware which alignment of your 
+    data or you might inadvertently average or shift data off by 1 interval/step.
+
 ## Limitations
 
 1. You must route each interval of runoff data at least 1 time before the next interval of runoff data. You should

docs/tutorial/advanced-tutorial.md

@@ -6,7 +6,7 @@ Depending on your preference, you may want to generate many config files in adva
 future use.
 
 The following code snippet demonstrates how to identify the essential input arguments and pass them as keyword arguments 
-to the `MuskingumCunge` class. You could alternatively write the inputs to a YAML or JSON file and use that config file 
+to the `Muskingum` class. You could alternatively write the inputs to a YAML or JSON file and use that config file 
 instead.
 
 ```python
@@ -30,7 +30,7 @@ os.makedirs(outputs, exist_ok=True)
 
 m = (
     rr
-    .MuskingumCunge(**{
+    .Muskingum(**{
         'routing_params_file': params_file,
         'connectivity_file': connectivity_file,
         'catchment_volumes_file': volume_files,
@@ -42,7 +42,7 @@ m = (
 
 ## Customizing Output File Type and Structure
 
-You can override the default function used by `river-route` when writing routed flows to disc. The MuskingumCunge class
+You can override the default function used by `river-route` when writing routed flows to disc. The Muskingum class
 formats the discharge data into a Pandas DataFrame and then calls the `write_outflows` method. By default, this function
 writes the dataframe to a netCDF file.
 
@@ -72,7 +72,7 @@ def custom_write_outflows(df: pd.DataFrame, outflow_file: str, runoff_file: str)
 
 (
     rr
-    .MuskingumCunge('../../examples/config.yaml')
+    .Muskingum('../../examples/config.yaml')
     .set_write_outflows(custom_write_outflows)
     .route()
 )
@@ -94,7 +94,7 @@ def write_outflows_to_sqlite(df: pd.DataFrame, outflow_file: str, runoff_file: s
 
 (
     rr
-    .MuskingumCunge('config.yaml')
+    .Muskingum('config.yaml')
     .set_write_outflows(write_outflows_to_sqlite)
     .route()
 )
@@ -119,7 +119,7 @@ def append_to_existing_file(df: pd.DataFrame, outflow_file: str, runoff_file: st
 
 (
     rr
-    .MuskingumCunge('config.yaml')
+    .Muskingum('config.yaml')
     .set_write_outflows(append_to_existing_file)
     .route()
 )
@@ -140,7 +140,7 @@ def save_partial_results(df: pd.DataFrame, outflow_file: str, runoff_file: str)
 
 (
     rr
-    .MuskingumCunge('config.yaml')
+    .Muskingum('config.yaml')
     .set_write_outflows(save_partial_results)
     .route()
 )

docs/tutorial/basic-tutorial.md

@@ -146,7 +146,7 @@ config_file_path = '/path/to/config.yaml'
 
 m = (
     rr
-    .MuskingumCunge(config_file_path)
+    .Muskingum(config_file_path)
     .route()
 )
 ```

examples/config.yaml

@@ -12,7 +12,6 @@ outflow_file: ''
 initial_state_file: ''
 final_state_file: ''
 # Compute Options - (Optional)
-routing: 'linear'            # "linear" or "nonlinear"
 input_type: 'sequential'     # "sequential" or "ensemble"
 runoff_type: 'incremental'   # "incremental" or "cumulative"
 dt_routing: 0                # defaults to time step of volume inputs