edit netcdf tutorial

Author: mjreno

.docs/Notebooks/mf6_netcdf01_tutorial.py

@@ -7,24 +7,27 @@
 #       extension: .py
 #       format_name: light
 #       format_version: '1.5'
-#       jupytext_version: 1.16.4
+#       jupytext_version: 1.17.2
 #   kernelspec:
 #     display_name: Python 3 (ipykernel)
 #     language: python
 #     name: python3
 # ---
 
-# # MODFLOW 6: Generate MODFLOW 6 NetCDF input from existing FloPy sim
+# # MODFLOW 6: MODFLOW 6 NetCDF inputs from FloPy simulation
 #
-# ## NetCDF tutorial 1: MODFLOW 6 structured input file
+# ## Write MODFLOW 6 NetCDF simulation
 #
-# This tutorial shows how to generate a MODFLOW 6 NetCDF file from
-# an existing FloPy simulation. Two methods will be demonstrated that
-# generate a simulation with package data stored in a model NetCDF
-# file. The first method is non-interactive- FloPy will generate the
-# file with a modified `write_simulation()` call.  The second method
-# is interactive, which provides an oppurtinity to modify the dataset
-# before it is written to NetCDF.
+# This tutorial demonstrates how to generate a MODFLOW 6 NetCDF file
+# from an existing FloPy simulation. Two variations will be shown.
+# In the first, FloPy will generate the file with a modified
+# `write_simulation()` call.  The second method is more interactive,
+# providing an opputinity to modify the dataset before it is written
+# to NetCDF.
+#
+# Support for generating a MODFLOW 6 NetCDF input without a defined
+# FloPy mf6 model or package instances is briefly discussed at the
+# end of the tutorial.
 #
 # For more information on supported MODFLOW 6 NetCDF formats see:
 # [MODFLOW NetCDF Format](https://github.com/MODFLOW-ORG/modflow6/wiki/MODFLOW-NetCDF-Format).
@@ -93,11 +96,15 @@
 
 # ## Load and run baseline simulation
 #
-# For the purposes of this tutorial, the specifics of this simulation
+# For the purposes of this tutorial, the specifics of the simulation
 # other than it is a candidate for NetCDF input are not a focus. It
 # is a NetCDF input candidate because it defines a supported model type
 # (`GWF6`) with a structured discretization and packages that support
 # NetCDF input parameters.
+#
+# More information about package NetCDF support in MODFLOW 6 can be
+# found in the `MODFLOW 6 - Description of Input and Output` (`mf6io.pdf`),
+# also available at the nightly build repository linked above.
 
 # load and run the non-netcdf simulation
 sim = flopy.mf6.MFSimulation.load(sim_ws=data_path / sim_name)
@@ -108,11 +115,11 @@
 
 # ## Create NetCDF based simulation method 1
 #
-# This is the most straightforward way to create a NetCDF simulation
-# from the loaded ascii input simulation. Simply define the `netcdf`
-# argument to `write_simulation()` to be either `structured` or
-# `layered`, depending on the desired format of the generated NetCDF
-# file.
+# The most straightforward way to create a NetCDF simulation
+# from the loaded simulation is to provide a `netcdf` argument
+# to `write_simulation()` and define it to be either `structured`
+# or `layered`, depending on the desired format of the generated
+# NetCDF file.
 #
 # The name of the created file can be specified by first setting the
 # model `name_file.nc_filerecord` attribute to the desired name. If
@@ -129,9 +136,9 @@
 
 # ## Run MODFLOW 6 simulation with NetCDF input
 #
-# The simulation generated by this tutorial should be runnable by
-# Extended MODFLOW 6, available from the nightly-build repository
-# (linked above).
+# The simulation generated by this tutorial should run with the
+# Extended MODFLOW 6 executable, available from the nightly-build
+# repository (linked above).
 
 # success, buff = sim.run_simulation(silent=True, report=True)
 # assert success, pformat(buff)
@@ -148,29 +155,31 @@
 
 # ## Run MODFLOW 6 simulation with NetCDF input
 #
-# The simulation generated by this tutorial should be runnable by
-# Extended MODFLOW 6, available from the nightly-build repository
-# (linked above).
+# The simulation generated by this tutorial should run with the
+# Extended MODFLOW 6 executable, available from the nightly-build
+# repository (linked above).
 
 # success, buff = sim.run_simulation(silent=True, report=True)
 # assert success, pformat(buff)
 
 # ## Create NetCDF based simulation method 2
 #
+# In this method we will set the FloPy `netcdf` argument to `nofile`
+# when `write_simulation()` is called. As such, FloPy will not generate
+# the NetCDF file automatically. We will manage the NetCDF file
+# generation ourselves in method 2.
+#
 # Reset the simulation path and set the `GWF` name file `nc_filerecord`
 # attribute to the name of the intended input NetCDF file. Display
 # the resultant name file changes.
 #
 # When we write the updated simulation, all packages that support NetCDF
-# input parameters will be converted. We will therefore need to create a
+# input parameters will be written such that NetCDF parameters expect the
+# data source to be a NetCDF file. We will therefore need to create a
 # NetCDF input file containing arrays for the `DIS`, `NPF`, `IC`, `STO`,
-# and `GHBG` packages. Data will be copied from the package objects into
-# dataset arrays.
-#
-# Flopy will not generate the NetCDF input file when the `netcdf` argument
-# to `write_simulation()` is set to `nofile`. This step is needed, however,
-# to update ascii input with the keywords required to support the model
-# NetCDF file that we will generate.
+# and `GHBG` packages. We will still use FloPy package objects to set the
+# parameter data in the dataset; however an `update_data=False` argument
+# could be passed to the `update_dataset()` call if this was not desired.
 
 # create directory for netcdf sim
 sim.set_sim_path(workspace / "netcdf3")
@@ -205,17 +214,28 @@
 
 # ## Access model NetCDF attributes
 #
-# Access model scoped NetCDF details by storing the dictionary
-# returned from `netcdf_info()`. In particular, we need to set dataset
-# scoped attributes that are stored in the model netcdf info dict.
+# Internally, FloPy generates and uses NetCDF metadata dictionaries
+# to update datasets. Both model and package objects can generate
+# the dictionaries and they contain related but distinct NetCDF
+# details. Model object dictionaries contain file scoped attribute
+# information while package dictionaries are organized by NetCDF
+# variable and contain variable scoped attribute information and
+# details related to creating the variable, including dimensions,
+# shape and data type.
 #
-# First, retrieve and store the netcdf info dictionary and display
+# The dictionaries are available via the `netcdf_info()` call. Their
+# content also varies depending on the desired type of dataset (i.e.
+# `structured` or `layered`). In this step we will access the model
+# NetCDF metadata and use it to update dataset scoped attributes.
+#
+# First, retrieve and store the netcdf metadata dictionary and display
 # its contents. Then, in the following step, update the dataset with
 # the model scoped attributes defined in the dictionary.
 #
-# These 2 operations can also be accomplished by calling `update_dataset()`
-# on the model object. Analogous functions for the package are shown
-# below.
+# These operations can also both be accomplished by calling
+# `update_dataset()` on the model object, albeit without the
+# opportunity to modify the intermediate metadata dictionary.
+# Examples of this approach (with package objects) are shown below.
 
 # get model netcdf info
 nc_info = gwf.netcdf_info()
@@ -227,11 +247,11 @@
 
 # ## Update the dataset with supported `DIS` arrays
 #
-# Add NetCDF supported data arrays in package to dataset. Internally, this call
-# uses a `netcdf_info()` package dictionary to determine candidate variables
-# and relevant information about them. Alternatively, this dictionary can
-# be directly accessed, updated, and passed to the `update_dataset()` function.
-# That workflow will be demonstrated in the `NPF` package update which follows.
+# First, we will show how package NetCDF parameters can be added to the
+# dataset without using the NetCDF metadata dictionary. We will use the
+# metadata dictionary when updating the dataset with NPF parameter data.
+#
+# Add NetCDF supported data arrays in package to dataset.
 
 # update dataset with `DIS` arrays
 dis = gwf.get_package("dis")
@@ -240,9 +260,7 @@
 # ## Access `NPF` package NetCDF attributes
 #
 # Access package scoped NetCDF details by storing the dictionary returned
-# from `netcdf_info()`. We need to set package variable attributes that are
-# stored in the package netcdf info dict, but we also need other information
-# that is relevant to creating the variables themselves.
+# from `netcdf_info()`.
 #
 # The contents of the info dictionary are shown and then, in the following
 # step, the dictionary and the dataset are passed to a helper routine that
@@ -253,12 +271,17 @@
 nc_info = npf.netcdf_info()
 pprint(nc_info)
 
-# ## Update package `netcdf_info` dictionary and dataset
+# ## Update package NetCDF metadata dictionary and dataset
+#
+# Here we update the metadata dictionary and then pass it directly to the
+# `update_dataset()` function which uses it when adding variables to the
+# dataset.
 #
-# Here we replace the default name for the `NPF K` input parameter and add
-# the `standard_name` attribute to it's attribute dictionary.  The dictionary
-# is then passed to the `update_dataset()` function. Note the updated name
-# is used in the subsequent block when updating the array values.
+# We replace the default name for the `NPF K` input parameter and add
+# the `standard_name` attribute to it's attribute dictionary. The
+# dictionary is then passed to the `update_dataset()` function. Note the
+# updated name is used in the subsequent block when updating the array
+# values.
 
 # update dataset with `NPF` arrays
 nc_info["k"]["varname"] = "npf_k_updated"
@@ -302,14 +325,14 @@
 
 # ## Run MODFLOW 6 simulation with NetCDF input
 #
-# The simulation generated by this tutorial should be runnable by
-# Extended MODFLOW 6, available from the nightly-build repository
-# (linked above).
+# The simulation generated by this tutorial should run with the
+# Extended MODFLOW 6 executable, available from the nightly-build
+# repository (linked above).
 
 # success, buff = sim.run_simulation(silent=True, report=True)
 # assert success, pformat(buff)
 
-# ## Method 4: DIY with xarray
+# ## Method 3: DIY with xarray
 #
 # The above method still uses FloPy objects to update the dataset arrays
 # to values consistent with the state of the objects. The `netcdf_info`