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
+    W504  # line break after binary operator
-    W605  # invalid escape sequence
 
 statistics = True

flopy/mf6/data/mfstructure.py

@@ -1037,10 +1037,24 @@ class MFDataItemStructure(object):
                     self.description = " ".join(arr_line[1:])
 
                 # clean self.description
-                self.description = self.description.replace("``", '"')
+                replace_pairs = [
-                self.description = self.description.replace("''", '"')
+                    ("``", '"'),  # 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 @@ class MFDataItemStructure(object):
                         + "`"
                         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
+          character values shown in table in mf6io.pdf. Ftype may be entered in
-          entered in any combination of uppercase and lowercase.
+          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
+          cell 1 and cell 2 if IHC > 0, or it is the area perpendicular to flow
-          to flow of the vertical connection between cell 1 and cell 2 if IHC =
+          of the vertical connection between cell 1 and cell 2 if IHC = 0.
-          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)
+                  the lake. RATE only applies to active (IBOUND > 0) lakes. A
-                  lakes. A specified RATE is only applied if COUTTYPE for the
+                  specified RATE is only applied if COUTTYPE for the OUTLETNO
-                  OUTLETNO is SPECIFIED. If the Options block includes a
+                  is SPECIFIED. If the Options block includes a TIMESERIESFILE
-                  TIMESERIESFILE entry (see the "Time-Variable Input" section),
+                  entry (see the "Time-Variable Input" section), values can be
-                  values can be obtained from a time series by entering the
+                  obtained from a time series by entering the time-series name
-                  time-series name in place of a numeric value. By default, the
+                  in place of a numeric value. By default, the RATE for each
-                  RATE for each SPECIFIED lake outlet is zero.
+                  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.
+                  applies to active (IBOUND > 0) multi-aquifer wells. If the
-                  If the Options block includes a TIMESERIESFILE entry (see the
+                  Options block includes a TIMESERIESFILE entry (see the "Time-
-                  "Time-Variable Input" section), values can be obtained from a
+                  Variable Input" section), values can be obtained from a time
-                  time series by entering the time-series name in place of a
+                  series by entering the time-series name in place of a numeric
-                  numeric value. By default, the RATE for each multi-aquifer
+                  value. By default, the RATE for each multi-aquifer well is
-                  well is zero.
+                  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
+                  extraction wells (RATE < 0) or injection wells (RATE > 0).
-                  :math:`>` 0). HEAD\_LIMIT can be deactivated by specifying
+                  HEAD_LIMIT can be deactivated by specifying the text string
-                  the text string `OFF'. The HEAD\_LIMIT option is based on the
+                  'OFF'. The HEAD_LIMIT option is based on the HEAD_LIMIT
-                  HEAD\_LIMIT functionality available in the
+                  functionality available in the MNW2 (Konikow et al., 2009)
-                  MNW2~\citep{konikow2009} package for MODFLOW-2005. The
+                  package for MODFLOW-2005. The HEAD_LIMIT option has been
-                  HEAD\_LIMIT option has been included to facilitate backward
+                  included to facilitate backward compatibility with previous
-                  compatibility with previous versions of MODFLOW but use of
+                  versions of MODFLOW but use of the RATE_SCALING option
-                  the RATE\_SCALING option instead of the HEAD\_LIMIT option is
+                  instead of the HEAD_LIMIT option is recommended. By default,
-                  recommended. By default, HEAD\_LIMIT is `OFF'.
+                  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
+          character values shown in table in mf6io.pdf. Ftype may be entered in
-          entered in any combination of uppercase and lowercase.
+          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
+          >0 means saturated thickness varies with computed head when head is
-          head is below the cell top; :math:`<`0 means saturated thickness
+          below the cell top; <0 means saturated thickness varies with computed
-          varies with computed head unless the THICKSTRT option is in effect.
+          head unless the THICKSTRT option is in effect. When THICKSTRT is in
-          When THICKSTRT is in effect, a negative value of icelltype indicates
+          effect, a negative value of icelltype indicates that saturated
-          that saturated thickness will be computed as STRT-BOT and held
+          thickness will be computed as STRT-BOT and held constant.
-          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)
+          hydraulic conductivity axis. All included cells (IDOMAIN > 0) must
-          must have a K value greater than zero.
+          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
+          All included cells (IDOMAIN > 0) must have a K22 value greater than
-          greater than zero.
+          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
+          All included cells (IDOMAIN > 0) must have a K33 value greater than
-          greater than zero.
+          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
+          If WETDRY < 0, only a cell below a dry cell can cause the cell to
-          cell to become wet. If WETDRY :math:`>` 0, the cell below a dry cell
+          become wet. If WETDRY > 0, the cell below a dry cell and horizontally
-          and horizontally adjacent cells can cause a cell to become wet. If
+          adjacent cells can cause a cell to become wet. If WETDRY is 0, the
-          WETDRY is 0, the cell cannot be wetted. The absolute value of WETDRY
+          cell cannot be wetted. The absolute value of WETDRY is the wetting
-          is the wetting threshold. When the sum of BOT and the absolute value
+          threshold. When the sum of BOT and the absolute value of WETDRY at a
-          of WETDRY at a dry cell is equaled or exceeded by the head at an
+          dry cell is equaled or exceeded by the head at an adjacent cell, the
-          adjacent cell, the cell is wetted. WETDRY must be specified if
+          cell is wetted. WETDRY must be specified if "REWET" is specified in
-          "REWET" is specified in the OPTIONS block. If "REWET" is not
+          the OPTIONS block. If "REWET" is not specified in the options block,
-          specified in the options block, then WETDRY can be entered, and
+          then WETDRY can be entered, and memory will be allocated for it, even
-          memory will be allocated for it, even though it is not used.
+          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
+          confined storage is used. >0 indicates confined storage is used when
-          used when head is above cell top and a mixed formulation of
+          head is above cell top and a mixed formulation of unconfined and
-          unconfined and confined storage is used when head is below cell top.
+          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 SIMULATE_ET and UNSAT_ETAE are specified in the OPTIONS block. If
-          If the Options block includes a TIMESERIESFILE entry (see the "Time-
+          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

flopy/mf6/modflow/mfgwt.py

@@ -46,8 +46,8 @@ class ModflowGwt(mfmodel.MFModel):
           Output Control.
     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
+          character values shown in table in mf6io.pdf. Ftype may be entered in
-          entered in any combination of uppercase and lowercase.
+          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/mfgwtnam.py

@@ -39,8 +39,8 @@ class ModflowGwtnam(mfpackage.MFPackage):
           Output Control.
     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
+          character values shown in table in mf6io.pdf. Ftype may be entered in
-          entered in any combination of uppercase and lowercase.
+          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/mfims.py

@@ -201,8 +201,8 @@ class ModflowIms(mfpackage.MFPackage):
           residual increases, while a low value serves to control step size
           more severely. The value usually ranges from 1.0 to 10:math:`^6`; a
           value of 10:math:`^4` works well for most problems but lower values
-          like 1.1 may be required for harder problems. BACKTRACKING\_TOLERANCE
+          like 1.1 may be required for harder problems. BACKTRACKING_TOLERANCE
-          only needs to be specified if BACKTRACKING\_NUMBER is greater than
+          only needs to be specified if BACKTRACKING_NUMBER is greater than
           zero.
     backtracking_reduction_factor : double
         * backtracking_reduction_factor (double) real value defining the
@@ -254,32 +254,32 @@ class ModflowIms(mfpackage.MFPackage):
           tolerance for convergence of the IMS linear solver and specific flow
           residual criteria used. This value represents the maximum allowable
           residual at any single node. Value is in units of length cubed per
-          time, and must be consistent with mf length and time units. Usually a
+          time, and must be consistent with MODFLOW 6 length and time units.
-          value of :math:`1.0 \\times 10^{-1}` is sufficient for the flow-
+          Usually a value of :math:`1.0 \\times 10^{-1}` is sufficient for the
-          residual criteria when meters and seconds are the defined \mf length
+          flow-residual criteria when meters and seconds are the defined
-          and time.
+          MODFLOW 6 length and time.
         * rclose_option (string) an optional keyword that defines the specific
           flow residual criterion used. STRICT--an optional keyword that is
           used to specify that INNER_RCLOSE represents a infinity-Norm
           (absolute convergence criteria) and that the dependent-variable (for
           example, head) and flow convergence criteria must be met on the first
           inner iteration (this criteria is equivalent to the criteria used by
-          the MODFLOW-2005 PCG package~citep{hill1990preconditioned}).
+          the MODFLOW-2005 PCG package (Hill, 1990)). L2NORM_RCLOSE--an
-          L2NORM_RCLOSE--an optional keyword that is used to specify that
+          optional keyword that is used to specify that INNER_RCLOSE represents
-          INNER_RCLOSE represents a L-2 Norm closure criteria instead of a
+          a L-2 Norm closure criteria instead of a infinity-Norm (absolute
-          infinity-Norm (absolute convergence criteria). When L2NORM_RCLOSE is
+          convergence criteria). When L2NORM_RCLOSE is specified, a reasonable
-          specified, a reasonable initial INNER_RCLOSE value is 0.1 times the
+          initial INNER_RCLOSE value is 0.1 times the number of active cells
-          number of active cells when meters and seconds are the defined mf
+          when meters and seconds are the defined MODFLOW 6 length and time.
-          length and time. RELATIVE_RCLOSE--an optional keyword that is used to
+          RELATIVE_RCLOSE--an optional keyword that is used to specify that
-          specify that INNER_RCLOSE represents a relative L-2 Norm reduction
+          INNER_RCLOSE represents a relative L-2 Norm reduction closure
-          closure criteria instead of a infinity-Norm (absolute convergence
+          criteria instead of a infinity-Norm (absolute convergence criteria).
-          criteria). When RELATIVE_RCLOSE is specified, a reasonable initial
+          When RELATIVE_RCLOSE is specified, a reasonable initial INNER_RCLOSE
-          INNER_RCLOSE value is :math:`1.0 \\times 10^{-4}` and convergence is
+          value is :math:`1.0 \\times 10^{-4}` and convergence is achieved for
-          achieved for a given inner (linear) iteration when :math:`\\Delta h
+          a given inner (linear) iteration when :math:`\\Delta h \\le`
-          \\le` INNER_DVCLOSE and the current L-2 Norm is :math:`\\le` the
+          INNER_DVCLOSE and the current L-2 Norm is :math:`\\le` the product of
-          product of the RELATIVE\_RCLOSE and the initial L-2 Norm for the
+          the RELATIVE_RCLOSE and the initial L-2 Norm for the current inner
-          current inner (linear) iteration. If RCLOSE\_OPTION is not specified,
+          (linear) iteration. If RCLOSE_OPTION is not specified, an absolute
-          an absolute residual (infinity-norm) criterion is used.
+          residual (infinity-norm) criterion is used.
     linear_acceleration : string
         * linear_acceleration (string) a keyword that defines the linear
           acceleration method used by the default IMS linear solvers. CG -
@@ -312,7 +312,7 @@ class ModflowIms(mfpackage.MFPackage):
           defines the drop tolerance used to drop preconditioner terms based on
           the magnitude of matrix entries in the ILUT and MILUT
           preconditioners. A value of :math:`10^{-4}` works well for most
-          problems. By default, PRECONDITIONER\_DROP\_TOLERANCE is zero and the
+          problems. By default, PRECONDITIONER_DROP_TOLERANCE is zero and the
           zero-fill incomplete LU factorization preconditioners (ILU(0) and
           MILU(0)) are used.
     number_orthogonalizations : integer