dpest.utils.svd#

dpest.utils.svd.svd(pst_path, svdmode=None, maxsing=None, eigthresh=None, eigwrite=None)[source]#

Adds or updates the Singular Value Decomposition (SVD) section in a PEST control (.pst) file.

This function post-processes an existing PEST control file (.PST) to configure the * singular value decomposition section, following the recommendations of the PEST manual (Doherty 2015). It can be used to enable or disable SVD, or to adjust the truncation behavior through maxsing and eigthresh.

When SVD is enabled (SVDMODE = 1), this function will remove any existing * lsqr section to avoid confusion and ensure that only SVD is active in the control file.

Required Arguments:#

  • pst_path (str):

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

Optional Arguments:#

  • svdmode (int, optional):

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

  • maxsing (int, optional):

    Maximum number of singular values to retain (must be > 0). If not provided, the behavior is:

    • If an SVD section already exists, use the existing MAXSING value.

    • If no SVD section exists, automatically set MAXSING equal to the number of adjustable parameters in the PST file.

  • eigthresh (float, optional):

    Eigenvalue ratio threshold at which singular value truncation occurs, with constraint 0 <= eigthresh < 1. If not provided, the behavior is:

    • If an SVD section already exists, use the existing EIGTHRESH value.

    • If no SVD section exists, default to 5e-7.

  • eigwrite (int, optional):

    SVD output file control flag (0 = write only singular values, 1 = write singular values and eigenvectors) to the case.svd file. If not provided, the behavior is:

    • If an SVD section already exists, use the existing EIGWRITE value.

    • If no SVD section exists, default to 0.

Returns:#

  • None

The function updates the PEST control file (.PST) in place. It will either modify an existing * singular value decomposition section or insert a new one. If SVD is enabled, any existing LSQR section is removed.

Examples:#

  1. Adding an SVD Section Using Recommended Defaults:

    from dpest.utils import svd

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

    This example adds an SVD section using: svdmode = 1, maxsing = npar (number of adjustable parameters), eigthresh = 5e-7, eigwrite = 0, and removes any existing * lsqr section.

  2. Customizing SVD Parameters in an Existing PEST Control File:

    from dpest.utils import svd

svd(
    pst_path  = "PEST_CONTROL.pst",
    maxsing   = 500,
    eigthresh = 1e-4,
    eigwrite  = 1
)

    This example updates the specified SVD parameters (MAXSING, EIGTHRESH, and EIGWRITE) while preserving the existing or default value of SVDMODE. If SVD is enabled (SVDMODE = 1), any LSQR section is removed so only SVD remains active.

  3. Disabling SVD While Keeping Other Settings:

    from dpest.utils import svd

svd(
    pst_path = "PEST_CONTROL.pst",
    svdmode  = 0
)

    This example disables SVD (SVDMODE = 0) while keeping current or default values for MAXSING, EIGTHRESH, and EIGWRITE. Any LSQR section is left unchanged because SVD is not being activated.

On this page

This Page