fix(createpackages): avoid creating invalid escape characters (#1055)

* Fix latex escape characters in description processing with math
* Replace latex characters to plaintext for Python
* Replace several other latex items involving \citep and \ref
  that are specific to mfio.pdf

.flake8

@@ -31,7 +31,6 @@ ignore =
     W293, # blank line contains whitespace
     W391, # blank line at end of file
     W503, # line break before binary operator
-    W504, # line break after binary operator
-    W605  # invalid escape sequence
+    W504  # line break after binary operator
 
 statistics = True

flopy/mf6/data/mfstructure.py

@@ -1037,10 +1037,24 @@ def set_value(self, line, common):
                     self.description = " ".join(arr_line[1:])
 
                 # clean self.description
-                self.description = self.description.replace("``", '"')
-                self.description = self.description.replace("''", '"')
+                replace_pairs = [
+                    ("``", '"'),  # double quotes
+                    ("''", '"'),
+                    ("`", "'"),  # single quotes
+                    ("~", " "),  # non-breaking space
+                    (r"\mf", "MODFLOW 6"),
+                    (r"\citep{konikow2009}", "(Konikow et al., 2009)"),
+                    (r"\citep{hill1990preconditioned}", "(Hill, 1990)"),
+                    (r"\ref{table:ftype}", "in mf6io.pdf"),
+                    (r"\ref{table:gwf-obstypetable}", "in mf6io.pdf"),
+                ]
+                for s1, s2 in replace_pairs:
+                    if s1 in self.description:
+                        self.description = self.description.replace(s1, s2)
 
                 # massage latex equations
+                self.description = self.description.replace("$<$", "<")
+                self.description = self.description.replace("$>$", ">")
                 if "$" in self.description:
                     descsplit = self.description.split("$")
                     mylist = [
@@ -1050,7 +1064,7 @@ def set_value(self, line, common):
                         + "`"
                         for i, j in zip(descsplit[::2], descsplit[1::2])
                     ]
-                    mylist.append(descsplit[-1])
+                    mylist.append(descsplit[-1].replace("\\", ""))
                     self.description = "".join(mylist)
                 else:
                     self.description = self.description.replace("\\", "")

flopy/mf6/modflow/mfgwf.py

@@ -51,8 +51,8 @@ class ModflowGwf(mfmodel.MFModel):
           Newton-Raphson UNDER_RELAXATION is not applied.
     packages : [ftype, fname, pname]
         * ftype (string) is the file type, which must be one of the following
-          character values shown in table~ref{table:ftype}. Ftype may be
-          entered in any combination of uppercase and lowercase.
+          character values shown in table in mf6io.pdf. Ftype may be entered in
+          any combination of uppercase and lowercase.
         * fname (string) is the name of the file containing the package input.
           The path to the file should be included if the file is not located in
           the folder where the program was run.

flopy/mf6/modflow/mfgwfgwf.py

@@ -131,9 +131,8 @@ class ModflowGwfgwf(mfpackage.MFPackage):
         * cl2 (double) is the distance between the center of cell 2 and the its
           shared face with cell 1.
         * hwva (double) is the horizontal width of the flow connection between
-          cell 1 and cell 2 if IHC :math:`>` 0, or it is the area perpendicular
-          to flow of the vertical connection between cell 1 and cell 2 if IHC =
-          0.
+          cell 1 and cell 2 if IHC > 0, or it is the area perpendicular to flow
+          of the vertical connection between cell 1 and cell 2 if IHC = 0.
         * aux (double) represents the values of the auxiliary variables for
           each GWFGWF Exchange. The values of auxiliary variables must be
           present for each exchange. The values must be specified in the order

flopy/mf6/modflow/mfgwflak.py

@@ -353,13 +353,13 @@ class ModflowGwflak(mfpackage.MFPackage):
                 * rate (string) real or character value that defines the
                   extraction rate for the lake outflow. A positive value
                   indicates inflow and a negative value indicates outflow from
-                  the lake. RATE only applies to active (IBOUND :math:`>` 0)
-                  lakes. A specified RATE is only applied if COUTTYPE for the
-                  OUTLETNO is SPECIFIED. If the Options block includes a
-                  TIMESERIESFILE entry (see the "Time-Variable Input" section),
-                  values can be obtained from a time series by entering the
-                  time-series name in place of a numeric value. By default, the
-                  RATE for each SPECIFIED lake outlet is zero.
+                  the lake. RATE only applies to active (IBOUND > 0) lakes. A
+                  specified RATE is only applied if COUTTYPE for the OUTLETNO
+                  is SPECIFIED. If the Options block includes a TIMESERIESFILE
+                  entry (see the "Time-Variable Input" section), values can be
+                  obtained from a time series by entering the time-series name
+                  in place of a numeric value. By default, the RATE for each
+                  SPECIFIED lake outlet is zero.
             invert : [string]
                 * invert (string) real or character value that defines the
                   invert elevation for the lake outlet. A specified INVERT

flopy/mf6/modflow/mfgwfmaw.py

@@ -281,12 +281,12 @@ class ModflowGwfmaw(mfpackage.MFPackage):
                 * rate (double) is the volumetric pumping rate for the multi-
                   aquifer well. A positive value indicates recharge and a
                   negative value indicates discharge (pumping). RATE only
-                  applies to active (IBOUND :math:`>` 0) multi-aquifer wells.
-                  If the Options block includes a TIMESERIESFILE entry (see the
-                  "Time-Variable Input" section), values can be obtained from a
-                  time series by entering the time-series name in place of a
-                  numeric value. By default, the RATE for each multi-aquifer
-                  well is zero.
+                  applies to active (IBOUND > 0) multi-aquifer wells. If the
+                  Options block includes a TIMESERIESFILE entry (see the "Time-
+                  Variable Input" section), values can be obtained from a time
+                  series by entering the time-series name in place of a numeric
+                  value. By default, the RATE for each multi-aquifer well is
+                  zero.
             well_head : [double]
                 * well_head (double) is the head in the multi-aquifer well.
                   WELL_HEAD is only applied to constant head (STATUS is
@@ -300,15 +300,15 @@ class ModflowGwfmaw(mfpackage.MFPackage):
                 * head_limit (string) is the limiting water level (head) in the
                   well, which is the minimum of the well RATE or the well
                   inflow rate from the aquifer. HEAD_LIMIT can be applied to
-                  extraction wells (RATE :math:`<` 0) or injection wells (RATE
-                  :math:`>` 0). HEAD\_LIMIT can be deactivated by specifying
-                  the text string `OFF'. The HEAD\_LIMIT option is based on the
-                  HEAD\_LIMIT functionality available in the
-                  MNW2~\citep{konikow2009} package for MODFLOW-2005. The
-                  HEAD\_LIMIT option has been included to facilitate backward
-                  compatibility with previous versions of MODFLOW but use of
-                  the RATE\_SCALING option instead of the HEAD\_LIMIT option is
-                  recommended. By default, HEAD\_LIMIT is `OFF'.
+                  extraction wells (RATE < 0) or injection wells (RATE > 0).
+                  HEAD_LIMIT can be deactivated by specifying the text string
+                  'OFF'. The HEAD_LIMIT option is based on the HEAD_LIMIT
+                  functionality available in the MNW2 (Konikow et al., 2009)
+                  package for MODFLOW-2005. The HEAD_LIMIT option has been
+                  included to facilitate backward compatibility with previous
+                  versions of MODFLOW but use of the RATE_SCALING option
+                  instead of the HEAD_LIMIT option is recommended. By default,
+                  HEAD_LIMIT is 'OFF'.
             shutoffrecord : [minrate, maxrate]
                 * minrate (double) is the minimum rate that a well must exceed
                   to shutoff a well during a stress period. The well will shut

flopy/mf6/modflow/mfgwfnam.py

@@ -44,8 +44,8 @@ class ModflowGwfnam(mfpackage.MFPackage):
           Newton-Raphson UNDER_RELAXATION is not applied.
     packages : [ftype, fname, pname]
         * ftype (string) is the file type, which must be one of the following
-          character values shown in table~ref{table:ftype}. Ftype may be
-          entered in any combination of uppercase and lowercase.
+          character values shown in table in mf6io.pdf. Ftype may be entered in
+          any combination of uppercase and lowercase.
         * fname (string) is the name of the file containing the package input.
           The path to the file should be included if the file is not located in
           the folder where the program was run.

flopy/mf6/modflow/mfgwfnpf.py

@@ -94,12 +94,11 @@ class ModflowGwfnpf(mfpackage.MFPackage):
     icelltype : [integer]
         * icelltype (integer) flag for each cell that specifies how saturated
           thickness is treated. 0 means saturated thickness is held constant;
-          :math:`>`0 means saturated thickness varies with computed head when
-          head is below the cell top; :math:`<`0 means saturated thickness
-          varies with computed head unless the THICKSTRT option is in effect.
-          When THICKSTRT is in effect, a negative value of icelltype indicates
-          that saturated thickness will be computed as STRT-BOT and held
-          constant.
+          >0 means saturated thickness varies with computed head when head is
+          below the cell top; <0 means saturated thickness varies with computed
+          head unless the THICKSTRT option is in effect. When THICKSTRT is in
+          effect, a negative value of icelltype indicates that saturated
+          thickness will be computed as STRT-BOT and held constant.
     k : [double]
         * k (double) is the hydraulic conductivity. For the common case in
           which the user would like to specify the horizontal hydraulic
@@ -108,8 +107,8 @@ class ModflowGwfnpf(mfpackage.MFPackage):
           assigned as the vertical hydraulic conductivity, and K22 and the
           three rotation angles should not be specified. When more
           sophisticated anisotropy is required, then K corresponds to the K11
-          hydraulic conductivity axis. All included cells (IDOMAIN :math:`>` 0)
-          must have a K value greater than zero.
+          hydraulic conductivity axis. All included cells (IDOMAIN > 0) must
+          have a K value greater than zero.
     k22 : [double]
         * k22 (double) is the hydraulic conductivity of the second ellipsoid
           axis (or the ratio of K22/K if the K22OVERK option is specified); for
@@ -120,15 +119,15 @@ class ModflowGwfnpf(mfpackage.MFPackage):
           conductivity along columns in the y direction. For an unstructured
           DISU grid, the user must assign principal x and y axes and provide
           the angle for each cell face relative to the assigned x direction.
-          All included cells (IDOMAIN :math:`>` 0) must have a K22 value
-          greater than zero.
+          All included cells (IDOMAIN > 0) must have a K22 value greater than
+          zero.
     k33 : [double]
         * k33 (double) is the hydraulic conductivity of the third ellipsoid
           axis (or the ratio of K33/K if the K33OVERK option is specified); for
           an unrotated case, this is the vertical hydraulic conductivity. When
           anisotropy is applied, K33 corresponds to the K33 tensor component.
-          All included cells (IDOMAIN :math:`>` 0) must have a K33 value
-          greater than zero.
+          All included cells (IDOMAIN > 0) must have a K33 value greater than
+          zero.
     angle1 : [double]
         * angle1 (double) is a rotation angle of the hydraulic conductivity
           tensor in degrees. The angle represents the first of three sequential
@@ -172,16 +171,16 @@ class ModflowGwfnpf(mfpackage.MFPackage):
     wetdry : [double]
         * wetdry (double) is a combination of the wetting threshold and a flag
           to indicate which neighboring cells can cause a cell to become wet.
-          If WETDRY :math:`<` 0, only a cell below a dry cell can cause the
-          cell to become wet. If WETDRY :math:`>` 0, the cell below a dry cell
-          and horizontally adjacent cells can cause a cell to become wet. If
-          WETDRY is 0, the cell cannot be wetted. The absolute value of WETDRY
-          is the wetting threshold. When the sum of BOT and the absolute value
-          of WETDRY at a dry cell is equaled or exceeded by the head at an
-          adjacent cell, the cell is wetted. WETDRY must be specified if
-          "REWET" is specified in the OPTIONS block. If "REWET" is not
-          specified in the options block, then WETDRY can be entered, and
-          memory will be allocated for it, even though it is not used.
+          If WETDRY < 0, only a cell below a dry cell can cause the cell to
+          become wet. If WETDRY > 0, the cell below a dry cell and horizontally
+          adjacent cells can cause a cell to become wet. If WETDRY is 0, the
+          cell cannot be wetted. The absolute value of WETDRY is the wetting
+          threshold. When the sum of BOT and the absolute value of WETDRY at a
+          dry cell is equaled or exceeded by the head at an adjacent cell, the
+          cell is wetted. WETDRY must be specified if "REWET" is specified in
+          the OPTIONS block. If "REWET" is not specified in the options block,
+          then WETDRY can be entered, and memory will be allocated for it, even
+          though it is not used.
     filename : String
         File name for this package.
     pname : String

flopy/mf6/modflow/mfgwfsfr.py

@@ -114,11 +114,11 @@ class ModflowGwfsfr(mfpackage.MFPackage):
           working with FloPy and Python. Flopy will automatically subtract one
           when loading index variables and add one when writing index
           variables.
-        * cellid ((integer, ...)) The keyword `NONE' must be specified for
+        * cellid ((integer, ...)) The keyword 'NONE' must be specified for
           reaches that are not connected to an underlying GWF cell. The keyword
-          `NONE' is used for reaches that are in cells that have IDOMAIN values
+          'NONE' is used for reaches that are in cells that have IDOMAIN values
           less than one or are in areas not covered by the GWF model grid.
-          Reach-aquifer flow is not calculated if the keyword `NONE' is
+          Reach-aquifer flow is not calculated if the keyword 'NONE' is
           specified. This argument is an index variable, which means that it
           should be treated as zero-based when working with FloPy and Python.
           Flopy will automatically subtract one when loading index variables
@@ -132,11 +132,11 @@ class ModflowGwfsfr(mfpackage.MFPackage):
         * rtp (double) real value that defines the top elevation of the reach
           streambed.
         * rbth (double) real value that defines the thickness of the reach
-          streambed. RBTH can be any value if CELLID is `NONE'. Otherwise, RBTH
+          streambed. RBTH can be any value if CELLID is 'NONE'. Otherwise, RBTH
           must be greater than zero.
         * rhk (double) real value that defines the hydraulic conductivity of
           the reach streambed. RHK can be any positive value if CELLID is
-          `NONE'. Otherwise, RHK must be greater than zero.
+          'NONE'. Otherwise, RHK must be greater than zero.
         * man (string) real or character value that defines the Manning's
           roughness coefficient for the reach. MAN must be greater than zero.
           If the Options block includes a TIMESERIESFILE entry (see the "Time-
@@ -223,23 +223,23 @@ class ModflowGwfsfr(mfpackage.MFPackage):
           water is available to meet all diversion stipulations, and is used in
           conjunction with the value of FLOW value specified in the
           STRESS_PERIOD_DATA section. Available diversion options include: (1)
-          CPRIOR = `FRACTION', then the amount of the diversion is computed as
+          CPRIOR = 'FRACTION', then the amount of the diversion is computed as
           a fraction of the streamflow leaving reach RNO (:math:`Q_{DS}`); in
           this case, 0.0 :math:`\\le` DIVFLOW :math:`\\le` 1.0. (2) CPRIOR =
-          `EXCESS', a diversion is made only if :math:`Q_{DS}` for reach RNO
+          'EXCESS', a diversion is made only if :math:`Q_{DS}` for reach RNO
           exceeds the value of DIVFLOW. If this occurs, then the quantity of
           water diverted is the excess flow (:math:`Q_{DS} -` DIVFLOW) and
           :math:`Q_{DS}` from reach RNO is set equal to DIVFLOW. This
           represents a flood-control type of diversion, as described by Danskin
-          and Hanson (2002). (3) CPRIOR = `THRESHOLD', then if :math:`Q_{DS}`
+          and Hanson (2002). (3) CPRIOR = 'THRESHOLD', then if :math:`Q_{DS}`
           in reach RNO is less than the specified diversion flow (DIVFLOW), no
           water is diverted from reach RNO. If :math:`Q_{DS}` in reach RNO is
           greater than or equal to (DIVFLOW), (DIVFLOW) is diverted and
           :math:`Q_{DS}` is set to the remainder (:math:`Q_{DS} -` DIVFLOW)).
           This approach assumes that once flow in the stream is sufficiently
-          low, diversions from the stream cease, and is the `priority'
+          low, diversions from the stream cease, and is the 'priority'
           algorithm that originally was programmed into the STR1 Package
-          (Prudic, 1989). (4) CPRIOR = `UPTO' -- if :math:`Q_{DS}` in reach RNO
+          (Prudic, 1989). (4) CPRIOR = 'UPTO' -- if :math:`Q_{DS}` in reach RNO
           is greater than or equal to the specified diversion flow (DIVFLOW),
           :math:`Q_{DS}` is reduced by DIVFLOW. If :math:`Q_{DS}` in reach RNO
           is less than (DIVFLOW), DIVFLOW is set to :math:`Q_{DS}` and there

flopy/mf6/modflow/mfgwfsto.py

@@ -26,9 +26,9 @@ class ModflowGwfsto(mfpackage.MFPackage):
     iconvert : [integer]
         * iconvert (integer) is a flag for each cell that specifies whether or
           not a cell is convertible for the storage calculation. 0 indicates
-          confined storage is used. :math:`>`0 indicates confined storage is
-          used when head is above cell top and a mixed formulation of
-          unconfined and confined storage is used when head is below cell top.
+          confined storage is used. >0 indicates confined storage is used when
+          head is above cell top and a mixed formulation of unconfined and
+          confined storage is used when head is below cell top.
     ss : [double]
         * ss (double) is specific storage (or the storage coefficient if
           STORAGECOEFFICIENT is specified as an option). Specific storage

flopy/mf6/modflow/mfgwfuzf.py

@@ -217,8 +217,8 @@ class ModflowGwfuzf(mfpackage.MFPackage):
           a given volume of soil divided by that volume. Values range from 0 to
           about 3 :math:`cm^{-2}`, depending on the plant community and its
           stage of development. ROOTACT is always specified, but is only used
-          if SIMULATE\_ET and UNSAT\_ETAE are specified in the OPTIONS block.
-          If the Options block includes a TIMESERIESFILE entry (see the "Time-
+          if SIMULATE_ET and UNSAT_ETAE are specified in the OPTIONS block. If
+          the Options block includes a TIMESERIESFILE entry (see the "Time-
           Variable Input" section), values can be obtained from a time series
           by entering the time-series name in place of a numeric value.
         * aux (double) represents the values of the auxiliary variables for