Merge pull request #160 from changliao1025/development

Development

Author: changliao1025

Diff for: README.md

@@ -38,6 +38,7 @@ PyFlowline also has three optional dependency packages
 1. `cython` for performance 
 2. `matplotlin` for visualization
 3. `cartopy` for visulization
+4. `simplekml` for Google Earth KML support
 
 ### Quickstart
 
@@ -55,6 +56,8 @@ We provide several examples in the `examples` folder to demonstrate the model ca
 
 This work was supported by the Earth System Model Development program areas of the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research as part of the multi-program, collaborative Integrated Coastal Modeling (ICoM) project and the Interdisciplinary Research for Arctic Coastal Environments (InteRFACE) project.
 
+This research was supported as part of the Next Generation Ecosystem Experiments-Tropics, funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research at Pacific Northwest National Laboratory. The study was also partly supported by U.S. Department of Energy Office of Science Biological and Environmental Research through the Earth and Environmental System Modeling program as part of the Energy Exascale Earth System Model (E3SM) project.
+
 ### License
 
 BSD 3-Clause License

Diff for: data/susquehanna/input/boundary_wgs.geojson

@@ -8,9 +8,10 @@ Users can run a PyFlowline simulation in the following steps:
 2. Install the package using `conda install -c conda-forge pyflowline`. Conda will automatically install all the required dependencies.
 3. Clone the latest PyFlowline repository from https://github.com/changliao1025/pyflowline. 
 4. Download the additional large MPAS mesh file `lnd_cull_mesh.nc` from https://github.com/changliao1025/pyflowline/releases/tag/0.2.0 and move it under the `data/susquehanna/input` folder.
-5. Open the `examples/susquehanna/pyflowline_susquehanna_mpas.json` file and change `sWorkspace_output` to the full path to the directory where you want to save the output (e.g. `/full/path/to/pyflowline/data/susquehanna/output`), change `"sFilename_mesh_netcdf"` to the full path to `lnd_cull_mesh.nc`, `"sFilename_mesh_boundary"` to the full path to `data/susquehanna/input/mesh_boundary_buffer.geojson`, and `"sFilename_basins"` to the full path to `examples/susquehanna/pyflowline_susquehanna_basins.json`.
+5. Open the `examples/susquehanna/pyflowline_susquehanna_mpas.json` file and change `sWorkspace_output` to the full path to the directory where you want to save the output (e.g. `/full/path/to/pyflowline/data/susquehanna/output`), change `"sFilename_mesh_netcdf"` to the full path to `lnd_cull_mesh.nc`, `"sFilename_mesh_boundary"` to the full path to `data/susquehanna/input/boundary_wgs.geojson`, and `"sFilename_basins"` to the full path to `examples/susquehanna/pyflowline_susquehanna_basins.json`.
 6. Open the `examples/susquehanna/pyflowline_susquehanna_basins.json` file and change `"sFilename_flowline_filter"` to the full path to `data/susquehanna/input/flowline.geojson`. Ignore the other settings in these json files for now.
 7. Open the preferred Python IDE (Visual Studio Code recommended) and run the  `examples/susquehanna/run_simulation_mpas.py` Python script. Optionally, you can also run the `notebooks/mpas_example.ipynb` notebook.
+The visualization of the model outputs is only experimental, and you can use other tools to visualize the model outputs.
 8. You should produce a list of model outputs in the `data/susquehanna/output` folder or the user-specified output folder.
 
 If you encounter any issues, refer to the FAQ or submit a GitHub issue (https://github.com/changliao1025/pyflowline/issues).

Diff for: docs/source/quickstart.rst

@@ -23,3 +23,12 @@ All the existing river network representation methods (except vector-based) only
 As a result, if a spatially-distributed hydrologic model uses the unstructured mesh as the spatial discretization, there is no way to represent the river network.
 
 To close this gap, PyFlowline was developed using a mesh-independent approach. At its core, PyFlowline uses the intersection between the vector river network and mesh to reconstruct the conceptual river network.
+
+
+*****************
+Important notice
+*****************
+
+1. PyFlowline is designed to run at regional to global scale, so all the datasets use the geographic coordinate system (GCS) with the WGS84 datum. See more details at https://pyflowline.readthedocs.io/en/latest/data/data.html
+
+2. Visualization of the PyFlowline outputs is only experimental. This feature is not fully developed yet. There is ongoing effort to use the `PyEarth` pythong package to provide this feature. 

Diff for: docs/source/readme.rst

@@ -31,6 +31,6 @@
     "sFilename_spatial_reference": "/qfs/people/liao313/workspace/python/pyhexwatershed_icom/data/susquehanna/input/boundary_proj_buff.shp",
     "sFilename_dem": "/qfs/people/liao313/workspace/python/pyhexwatershed_icom/data/susquehanna/input/dem_buff_ext.tif",     
     "sFilename_mesh_netcdf": "/qfs/people/liao313/workspace/python/pyflowline/data/susquehanna/input/lnd_cull_mesh.nc"  ,
-    "sFilename_mesh_boundary": "/qfs/people/liao313/workspace/python/pyflowline/data/susquehanna/input/mesh_boundary_buffer.geojson",
+    "sFilename_mesh_boundary": "/qfs/people/liao313/workspace/python/pyflowline/data/susquehanna/input/boundary_wgs.geojson",
     "sFilename_basins": "/qfs/people/liao313/workspace/python/pyflowline/examples/susquehanna/pyflowline_susquehanna_basins.json"
 }

Diff for: examples/susquehanna/pyflowline_susquehanna_mpas.json

@@ -29,7 +29,7 @@
 iCase_index = 1
 iFlag_visualization = 1
 sMesh = 'mpas'
-sDate='20230101'
+sDate='20230701'
 
 oPyflowline = pyflowline_read_model_configuration_file(sFilename_configuration_in, 
     iCase_index_in=iCase_index, sDate_in=sDate)
@@ -40,30 +40,31 @@
 
 oPyflowline.setup()
 if iFlag_visualization ==1:
-    oPyflowline.plot(sFilename_output_in = 'filter_flowline.png', sVariable_in = 'flowline_filter' )
+    #oPyflowline.plot(sVariable_in = 'flowline_filter', sFilename_output_in = 'filter_flowline.png'  )
     pass
 
 oPyflowline.flowline_simplification()
 
 if iFlag_visualization == 1:
 
     aExtent_meander = [-76.5,-76.2, 41.6,41.9] 
-    oPyflowline.plot( iFlag_title=1 ,sVariable_in='flowline_simplified' , sFilename_output_in = 'flowline_simplified.png', ) 
+    oPyflowline.plot( sVariable_in='flowline_simplified' , sFilename_output_in = 'flowline_simplified.png' ) 
 
-    oPyflowline.plot( iFlag_title=1 ,sVariable_in='flowline_simplified' , aExtent_in =aExtent_meander, sFilename_output_in = 'flowline_simplified_zoom.png', ) 
+    oPyflowline.plot( sVariable_in='flowline_simplified' , sFilename_output_in = 'flowline_simplified_zoom.png', aExtent_in =aExtent_meander ) 
 
     pass
 aCell = oPyflowline.mesh_generation()
 
 if iFlag_visualization == 1:
-    oPyflowline.plot( iFlag_title=1 ,sVariable_in='mesh', sFilename_output_in = 'mesh.png' ) 
+    oPyflowline.plot( sVariable_in='mesh', sFilename_output_in = 'mesh.png' ) 
     pass
 
 oPyflowline.reconstruct_topological_relationship(aCell)
 
 if iFlag_visualization == 1:
-    oPyflowline.plot( iFlag_title=1, sVariable_in='overlap', sFilename_output_in = 'mesh_w_flowline.png',)
+    oPyflowline.plot(  sVariable_in='overlap', sFilename_output_in = 'mesh_w_flowline.png',)
     pass
+
 oPyflowline.export()
 
 print('Finished')

Diff for: examples/susquehanna/run_simulation_mpas.py

@@ -436,7 +436,7 @@
     "\n",
     "    oPyflowline.plot(sVariable_in = 'flowline_filter' )\n",
     "    #if you provide a filename, a png file will be saved\n",
-    "    oPyflowline.plot(sFilename_in = 'filter_flowline.png', sVariable_in = 'flowline_filter' )\n",
+    "    oPyflowline.plot(sVariable_in = 'flowline_filter', sFilename_in = 'filter_flowline.png' )\n",
     "    pass"
    ]
   },
@@ -517,7 +517,7 @@
    "source": [
     "if iVisualization_method ==2:\n",
     "    aExtent_braided = [-77.3,-76.5, 40.2,41.0]  \n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='flowline_filter' , aExtent_in =aExtent_braided ) "
+    "    oPyflowline.plot( sVariable_in='flowline_filter' , aExtent_in =aExtent_braided ) "
    ]
   },
   {
@@ -617,7 +617,7 @@
     "    pass\n",
     "\n",
     "else: #use the default visualization method, only experimental\n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='flowline_simplified' )   "
+    "    oPyflowline.plot( sVariable_in='flowline_simplified' )   "
    ]
   },
   {
@@ -649,7 +649,7 @@
    "source": [
     "if iVisualization_method == 2:\n",
     "    aExtent_meander = [-76.5,-76.2, 41.6,41.9] \n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='flowline_simplified' , aExtent_in =aExtent_meander ) "
+    "    oPyflowline.plot( sVariable_in='flowline_simplified' , aExtent_in =aExtent_meander ) "
    ]
   },
   {
@@ -672,7 +672,7 @@
    "source": [
     "if iVisualization_method == 2:\n",
     "    aExtent_braided = [-77.3,-76.5, 40.2,41.0] \n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='flowline_simplified' , aExtent_in =aExtent_braided ) "
+    "    oPyflowline.plot( sVariable_in='flowline_simplified' , aExtent_in =aExtent_braided ) "
    ]
   },
   {
@@ -695,7 +695,7 @@
    "source": [
     "if iVisualization_method == 2:\n",
     "    aExtent_confluence = [-77.3,-76.5, 40.2,41.0] \n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='flowline_simplified' , aExtent_in =aExtent_confluence ) "
+    "    oPyflowline.plot( sVariable_in='flowline_simplified' , aExtent_in =aExtent_confluence ) "
    ]
   },
   {
@@ -764,7 +764,7 @@
     "    pass\n",
     "\n",
     "else:\n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='mesh' ) "
+    "    oPyflowline.plot( sVariable_in='mesh' ) "
    ]
   },
   {
@@ -814,7 +814,7 @@
    ],
    "source": [
     "if iVisualization_method == 2:\n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='mesh' ) "
+    "    oPyflowline.plot( sVariable_in='mesh' ) "
    ]
   },
   {
@@ -891,7 +891,7 @@
     "    plt.show()\n",
     "    pass\n",
     "else:\n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='overlap') \n",
+    "    oPyflowline.plot( sVariable_in='overlap') \n",
     "    pass"
    ]
   },
@@ -924,7 +924,7 @@
    "source": [
     "if iVisualization_method == 2:\n",
     "    aExtent_outlet = [-76.0,-76.5, 39.5,40.0] #outlet\n",
-    "    oPyflowline.plot( iFlag_title=1 ,sVariable_in='overlap' , aExtent_in =aExtent_outlet) "
+    "    oPyflowline.plot(sVariable_in='overlap' , aExtent_in =aExtent_outlet) "
    ]
   },
   {

Diff for: mesh.png

@@ -76,7 +76,6 @@ PyFlowline is the only modeling software that provides these unique features:
 3. It can be applied at both high and coarse resolutions; 
 4. It can provide global coverage including Greenland and the Antarctic.
 
-
 Model documentation is hosted at https://pyflowline.readthedocs.io/en/latest/, including a case study for the Susquehanna River Basin in the Mid-Atlantic region of the United States.
 
 # Acknowledgment
@@ -87,10 +86,11 @@ The model described in this repository was supported by the following:
 
 * the Earth System Model Development and Regional and Global Model Analysis program areas of the U.S. Department of Energy, Office of Science, Biological and Environmental Research program as part of the multi-program, collaborative Interdisciplinary Research for Arctic Coastal Environments (InteRFACE) project.
 
+* the Next Generation Ecosystem Experiments-Tropics project, funded by the U.S. Department of Energy, Office of Science, Office of Biological and Environmental Research at Pacific Northwest National Laboratory. 
+
 A portion of this research was performed using PNNL Research Computing at Pacific Northwest National Laboratory. 
 
 PNNL is operated for DOE by Battelle Memorial Institute under contract DE-AC05-76RL01830.
 
-
 # References
 

Diff for: mesh_w_flowline.png

@@ -24,13 +24,19 @@ def plot(self,
     """
 
     if iFlag_type_in is None:
-        iFlag_type_in = 2
+        iFlag_type_in = 2 #polyline based, only flowline
 
     if iFlag_title_in is None:
         iFlag_title_in = 1
 
     if sVariable_in is None:
         sVariable_in = 'flowline_conceptual'
+    else:
+        if sVariable_in == 'mesh': 
+            iFlag_type_in = 3
+        else:
+            if sVariable_in == 'overlap':
+                iFlag_type_in = 4
 
 
     if iFlag_type_in == 1: #point based, such as dam
@@ -87,26 +93,29 @@ def _plot_mesh(self, sFilename_output_in=None, aExtent_in=None, pProjection_map_
 #plot both polygon and polyline
 def _plot_mesh_with_flowline(self,
                              sFilename_output_in=None,
-                             iFlag_title=None,
+                             iFlag_title_in=None,
                              aExtent_in=None,
                              pProjection_map_in = None):
 
     aFiletype_in = list()
     aFilename_in = list()
+    aFlag_color = list()
     aFilename_in.append(self.sFilename_mesh)
-    aFiletype_in.append(1)
+    aFiletype_in.append(3)
+    aFlag_color.append(0)
 
     for pBasin in self.aBasin:
         aFiletype_in.append(2)
         dummy = pBasin.sFilename_flowline_conceptual
         sFilename_json = os.path.join(pBasin.sWorkspace_output_basin, dummy)
         aFilename_in.append(sFilename_json)
+        aFlag_color.append(1)
 
     map_multiple_vector_data(aFiletype_in,
                              aFilename_in,
                              sFilename_output_in=sFilename_output_in,
                              sTitle_in= 'Mesh with flowline',
-                             aFlag_color_in=[0, 1],
+                             aFlag_color_in=aFlag_color,
                              aExtent_in = aExtent_in,
                              pProjection_map_in = pProjection_map_in)
     return
@@ -176,6 +185,7 @@ def basin_plot(self,
                                                          aExtent_in = aExtent_in)
                             return
                         else:
+                            print('Unsupported variable: ', sVariable_in, ' in basin_plot.')
                             pass
                 pass
     else:
@@ -184,7 +194,7 @@ def basin_plot(self,
 
 
     map_vector_polyline_data(sFilename_json,
-                             sFilename_output_in,
+                             sFilename_output_in= sFilename_output_in,
                              iFlag_title_in=iFlag_title_in,
                              iFlag_thickness_in=0  ,
                              sTitle_in=sTitle,

Diff for: notebooks/mpas_example.ipynb

@@ -24,7 +24,7 @@ def _set_format(self, vmin=None, vmax=None):
             self.format = r'$ mathdefault{%s}$' % self.format
 
 def map_vector_polyline_data(sFilename_in,
-                             sFilename_output_in,
+                             sFilename_output_in= None,
                              iFlag_color_in = None,
                              iFlag_label_in = None,
                              iFlag_thickness_in =None,