dpest.utils.lsqr#

dpest.utils.lsqr.lsqr(pst_path, lsqrmode=None, lsqr_atol=None, lsqr_btol=None, lsqr_conlim=None, lsqr_itnlim=None, lsqrwrite=None)[source]#

Adds or updates the LSQR section in a PEST control (.pst) file.

The LSQR section configures PEST to use the LSQR algorithm for solving the inverse problem. This is especially useful for large models with many parameters. Default values follow the recommendations from the PEST manual (Doherty 2015) for finite- difference derivatives and least-squares problems.

When LSQR is enabled (LSQRMODE = 1), this function will remove any existing * singular value decomposition section to avoid confusion and ensure that only LSQR is active in the control file.

Required Arguments:#

  • pst_path (str):

    Path to the PEST control file (.PST) to modify.

Optional Arguments:#

  • lsqrmode (int, optional):

    LSQR mode flag (0 = disable LSQR, 1 = enable LSQR). If not provided, the current value in the file is preserved. If no LSQR section exists, the default is 1 (enable LSQR).

  • lsqr_atol (float, optional):

    LSQR algorithm ATOL variable (must be ≥ 0). This is an estimate of the relative error in the data defining the matrix A (equivalent to Q^(1/2) J in PEST). For finite-difference derivatives, a value of 1e-4 generally works well. If not provided:

    • Uses the current value if an LSQR section exists.

    • Otherwise defaults to 1e-4.

  • lsqr_btol (float, optional):

    LSQR algorithm BTOL variable (must be ≥ 0). This is an estimate of the relative error in the data defining the right-hand side vector b. For PEST, a value of 1e-4 generally works well. If not provided:

    • Uses the current value if an LSQR section exists.

    • Otherwise defaults to 1e-4.

  • lsqr_conlim (float, optional):

    LSQR algorithm CONLIM variable (must be ≥ 0). This is an upper limit on the apparent condition number of A. Iterations are terminated if the estimated condition number exceeds this value, to prevent very small singular values from causing unwanted solution growth. The PEST manual suggests values in the range 1000 to 1/relpr; for PEST applications, 1000.0 generally works well. If not provided:

    • Uses the current value if an LSQR section exists.

    • Otherwise defaults to 1000.0.

  • lsqr_itnlim (int, optional):

    LSQR algorithm ITNLIM variable (must be > 0). This is an upper limit on the number of LSQR iterations. In LSQR documentation, suggested values are:

    • itnlim = m/2 for well-conditioned systems with clustered singular values;

    • itnlim = 4*m otherwise,

    where m is the number of columns of A. In the PEST context, m is the number of adjustable parameters. The PEST manual therefore recommends setting LSQR_ITNLIM = 4 * number_of_adjustable_parameters. If not provided:

    • Uses the current value if an LSQR section exists.

    • Otherwise defaults to 4 * npar where npar is read from the PST file.

  • lsqrwrite (int, optional):

    Flag controlling LSQR output file (0 or 1). If set to 1, LSQR output is written to case.lsq; this file can become large. If not desired, set to 0. If not provided:

    • Uses the current value if an LSQR section exists.

    • Otherwise defaults to 0 (no LSQR output file).

Returns:#

  • None

The function updates the PEST control file (.PST) in place, either modifying an existing * lsqr section or inserting a new one. If LSQR is enabled, any existing SVD section is removed.

Examples:#

  1. Adding an LSQR Section Using Recommended Defaults:

    from dpest.utils import lsqr

# PEST_CONTROL.pst already exists (e.g., created by dpest.pst)
lsqr(
    pst_path = "PEST_CONTROL.pst"
)

    This example adds an LSQR section using: lsqrmode = 1, lsqr_atol = 1e-4, lsqr_btol = 1e-4, lsqr_conlim = 1000.0, lsqr_itnlim = 4 * npar, lsqrwrite = 0, and removes any existing * singular value decomposition section.

  2. Updating Specific LSQR Parameters in an Existing PEST Control File:

    from dpest.utils import lsqr

lsqr(
    pst_path   = "PEST_CONTROL.pst",
    lsqr_atol  = 1e-6,
    lsqr_btol  = 1e-6,
    lsqr_conlim= 2000.0,
    lsqr_itnlim= 50
)

    This example updates only the specified LSQR parameters (LSQR_ATOL, LSQR_BTOL, LSQR_CONLIM, and LSQR_ITNLIM) while preserving existing values for other LSQR parameters.

  3. Disabling LSQR Mode While Maintaining Other Settings:

    from dpest.utils import lsqr

lsqr(
    pst_path  = "PEST_CONTROL.pst",
    lsqrmode  = 0
)

    This example disables LSQR mode (LSQRMODE = 0) while keeping other LSQR parameters at their current or default values. Any existing SVD section is left unchanged because LSQR is not being activated.

On this page

This Page