Package 'kwb.ucode'

Title: Interface to Auto-Calibration Software UCODE
Description: Functions enabling to write UCODE input files and to run UCODE.
Authors: Hauke Sonnenberg [aut, cre] (ORCID: <https://orcid.org/0000-0001-9134-2871>), Michael Rustler [ctb] (ORCID: <https://orcid.org/0000-0003-0647-7726>), OPTIWELLS-2 [fnd], Kompetenzzentrum Wasser Berlin gGmbH (KWB) [cph]
Maintainer: Hauke Sonnenberg <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-05-31 08:30:19 UTC
Source: https://github.com/KWB-R/kwb.ucode

Help Index

History HTML for calibration progress visualisation

Description

History HTML for calibration progress visualisation

Usage

htmlForCalibrationHistory(n, current = "ucCurrent.html")

Arguments

n

number of plots
current

default: "ucCurrent.html"

Main HTML for calibration progress visualisation

Description

Main HTML for calibration progress visualisation

Usage

htmlForCalibrationPage(
  htmlHist = "ucHistory.html",
  htmlCurr = "ucCurrent.html"
)

Arguments

htmlHist

default: "ucHistory.html"
htmlCurr

default: "ucCurrent.html"

Content HTML for calibration progress visualisation

Description

Content HTML for calibration progress visualisation

Usage

htmlForCalibrationState(refresh = 1)

Arguments

refresh

refresh time in seconds

Configure UCODE run

Description

Configure UCODE run

Usage

ucConf(
  general = ucConfGeneral(),
  parameters = ucDefaultConfParameters(),
  weights = ucDefaultConfWeights()
)

Arguments

general

configuration of control parameters as retrieved by ucConfGeneral.
parameters

data.frame with each row representing a parameter configuration as e.g. retrieved by ucConfParameter. For possible parameter names see ucSetPlaceholder
weights

Matrix of weights as e.g. retrieved by ucDefaultConfWeights. Matix of weights is used when calculating overall fitness. Row names = names of fitness indicators out of the set of c("ME", "MAE", "MSE", "RMSE", "NRMSE", "PBIAS", "RSR", "rSD", "NSE", "mNSE", "rNSE", "d", "md", "rd", "cp", "r", "R2", "bR2", "KGE, "VE"). Column names = well names ("PW" = pumping well, observation wells named as in parameter setting). See example.

See Also

ucPrepCalib

ucConf Model Command Lines

Description

lines for input block Model_Command_Lines

Usage

ucConf_Model_Command_Lines(bfile)

Arguments

bfile

name of batch file to be invoked by UCODE

Configuration of Model Input Files

Description

Lines for input block Model_Input_Files

Usage

ucConf_Model_Input_Files()

Configuration of Model Output Files

Description

Lines for input block Model_Output_Files

Usage

ucConf_Model_Output_Files()

Configuration of Observation Data

Description

Lines for input block Observation_Data

Usage

ucConf_Observation_Data(weights)

Arguments

weights

Matix of weights used when calculating overall fitness. Row names = names of fitness indicators out of the set of c("ME", "MAE", "MSE", "RMSE", "NRMSE", "PBIAS", "RSR", "rSD", "NSE", "mNSE", "rNSE", "d", "md", "rd", "cp", "r", "R2", "bR2", "KGE, "VE"). Column names = well names ("PW" = pumping well, observation wells named as in parameter setting). For an example see ucConf

Configuration of Parameter Data

Description

Lines for input block Parameter_Data

Usage

ucConf_Parameter_Data(confParameters)

Arguments

confParameters

data frame representing table as required in Parameter_Data block of UCODE input file. , for example see ucDefaultConfParameters

ucConf Reg GN Controls

Description

lines for input block UCODE_Control_Data

Usage

ucConf_Reg_GN_Controls(maxIter)

Arguments

maxIter

Maximum number of parameter-estimation iterations allowed before stopping

ucConf UCODE Control Data

Description

lines for input block UCODE_Control_Data

Usage

ucConf_UCODE_Control_Data()

General settings in UCODE configuration

Description

General settings in UCODE configuration

Usage

ucConfGeneral(gof.digits = 5, maxIter = 100)

Arguments

gof.digits

Number of digits to be used in goodness of fit values. Default: 5
maxIter

Maximum number of parameter-estimation iterations allowed before stopping

See Also

ucConf

Create parameter for UCODE configuration

Description

Create parameter for UCODE configuration

Usage

ucConfParameter(
  paramname,
  startvalue = 1e+38,
  lowerValue = -1e+38,
  upperValue = 1e+38,
  lowerConstraint = 0,
  upperConstraint = 1,
  constrain = "yes",
  adjustable = "yes",
  maxChange = 2,
  perturbAmt = 0.5
)

Arguments

paramname

Parameter name (up to 12 characters; not case sensitive) - a character string that is used in a template file or in an equation of a derived parameter in the Derived_Parameters input block. Each parameter name needs to be unique and can not be the same as any parameter name defined in the Derived_Parameter input block. For possible parameter names see ucSetPlaceholder
startvalue

Starting parameter value. Default=A huge real number. The huge real number is obtained for the computer being used and commonly is about 1e38.
lowerValue

Smallest reasonable value for this parameter. Default= -(Huge real number). In absolute value, commonly about -1e38.
upperValue

Largest reasonable value for this parameter. Default= +(Huge real number). Commonly about +1e38.
lowerConstraint

Lower limit of considered parameter values. Default (HS): 0
upperConstraint

Upper limit of considered parameter values. Default (HS): 1
constrain

yes: constrain parameter values using LowerConstraint and UpperConstraint. Default (HS): yes.
adjustable

yes: change this value as needed depending on the purpose of the UCODE_2005 run defined in the UCODE_Control_Data input file. no: leave the value of this parameter unchanged. Default (HS): "yes".
maxChange

Maximum fractional parameter change allowed between parameter iterations. Default=2.0.
perturbAmt

Fractional amount of parameter value to perturb to calculate sensitivity. Commonly 0.01 to 0.10. Default (HS): 0.5. See discussion in Chapter 3.

Value

data.frame containing all argument values with column names equalling function argument names

See Also

ucConf, ucDefaultConfParameters

Examples

# Use rbind to create a data.frame containing parameter information as
  # required by ucConf:
  cpara <- rbind(
    ucConfParameter(paramname = "HKR", startvalue = 2e-5, 
                    lowerConstraint = 1e-5, upperConstraint = 1e-1,
                    maxChange = 1, perturbAmt = 0.5, 
                    constrain = "yes", adjustable = "yes"),
    ucConfParameter(paramname = "HKZ", startvalue = 2e-7, 
                    lowerConstraint = 1e-7, upperConstraint = 1e-3,
                    maxChange = 1, perturbAmt = 0.5,
                    constrain = "yes", adjustable = "yes"))  
  
  # set this parameter setting in default UCODE configuration
  ucConf(parameters = cpara)

Default parameter definition for UCODE configuration

Description

Default parameter definition for UCODE configuration

Usage

ucDefaultConfParameters()

Value

data.frame with each row representing a model parameter

See Also

ucConfParameter, ucConf

Default weight matrix

Description

Weights are given for each pair of well name (pumping well PW or observation wells) and name of goodness of fit (gof)-function.

Usage

ucDefaultConfWeights(
  wells = wtConfiguredWellnames(wtDefaultConfiguration()),
  gofs = c("RMSE", "NSE", "mNSE")
)

Arguments

wells

well names, default: wtConfiguredWellnames(wtDefaultConfiguration())
gofs

default: c("RMSE", "NSE", "mNSE")

Value

Matrix of weights used when calculating overall fitness. Row names = names of fitness indicators out of the set of c("ME", "MAE", "MSE", "RMSE", "NRMSE", "PBIAS", "RSR", "rSD", "NSE", "mNSE", "rNSE", "d", "md", "rd", "cp", "r", "R2", "bR2", "KGE, "VE"). Column names = well names ("PW" = pumping well, observation wells named as in parameter setting).

See Also

ucConf

Input File Lines

Description

Lines for UCODE main input file

Usage

ucInpFileLines(uconf, command)

Arguments

uconf

UCODE configuration as retrieved by ucConf
command

name of batch file that is invoked by UCODE with each iteration

Plot WTAQ results to png file

Description

Plot WTAQ results to png file

Usage

ucPlotPng(fname, wtaqResult, i)

Arguments

fname

fname
wtaqResult

wtaqResult
i

i

Value

????

Plot UCODE summary file

Description

Plot UCODE summary file

Usage

ucPlotSummary(sfile)

Arguments

sfile

path to summary file

Value

???

Prepare calibration of WTAQ-model by creation of needed input and control files

Description

All input files needed to run a UCODE calibration of a WTAQ model are created in the directory tdir. By default (open.tdir = TRUE) this directory is opened in the Windows explorer. You can use the created batch file runParallelUCode.bat to start the UCODE calibration.

Usage

ucPrepCalib(
  wtaqConfiguration = wtDefaultConfiguration(),
  uconf = ucConf(),
  tdir = tempdir(),
  open.tdir = TRUE,
  wtaq = system.file("extdata", "wtaq.2.1.exe", package = "kwb.wtaq"),
  ucode = system.file("extdata", "ucode_2005.exe", package = "kwb.wtaq")
)

Arguments

wtaqConfiguration

WTAQ configuration as retrieved by wtConfigure
uconf

UCode configuration as retrieved by ucConf
tdir

target directory in which all input and control files are to be created. Default: temporary directory of current R Session. Attention! This temporary directory will be emptied after the R session has finished!
open.tdir

if TRUE, the target directory will be opened in the Windows Explorer in order to allow inspecting the created files
wtaq

full path to WTAQ executable
ucode

full path to UCODE executable

See Also

ucConf, ucRunParallel

Examples

# Define WTAQ configuration...
# Here: just load the configuration of WTAQ's Sample problem 2
wtaqConfiguration <- kwb.wtaq::wtConfigurationExample2()
  
# Define parameters
p <- rbind(
  ucConfParameter(
    "HKR", 
    startvalue = 2e-5, 
    lowerConstraint = 1e-5, 
    upperConstraint = 1e-1,
    maxChange = 1, 
    perturbAmt = 0.5
  ),
  ucConfParameter(
    "HKZ", 
    startvalue = 2e-7, 
    lowerConstraint = 1e-7, 
    upperConstraint = 1e-3,
    maxChange = 1, 
    perturbAmt = 0.5
  )
)  
  
# Define weights
#
# The following weight matrix w gives a weight of 1 to the root mean square
# error (RMSE) and the Nash-Sutcliffe-Efficiency (NSE) between simulated
# and observed values at the pumping well ("PW") and to the NSE between
# simulated and observed values at the observation well "PS1".
#
# well -> PW PS1
w <- matrix(c( 1,  1,  # RMSE  <- GOF
              1,  1), # NSE
           nrow = 2, byrow = TRUE,
           dimnames = list(c("RMSE", "NSE"), c("PW", "PS1")))

# Create UCODE configuration
uconf <- ucConf(general = ucConfGeneral(maxIter = 100),
               parameters = p, weights = w)

# Create all input files needed to run the UCODE calibration of WTAQ
# sample problem 2
tdir <- ucPrepCalib(wtaqConfiguration = wtaqConfiguration, uconf = uconf)

# Run loop waiting for input files provided by UCODE (remove the comment
# character in the following line!)
#ucRunParallel(tdir, uconf = uconf)

# Now, run runParallelUCode.bat in the target directory...

Read UCODE summary file

Description

Read UCODE summary file

Usage

ucReadSummary(sfile)

Arguments

sfile

path to summary file

Value

data frame, ordered by ITER

Run main calibration loop

Description

Run main calibration loop

Usage

ucRunParallel(
  uconf = ucConf(),
  tdir = tempdir(),
  wtaq = system.file("extdata", "wtaq.2.1.exe", package = "kwb.wtaq"),
  FUN = NULL
)

Arguments

uconf

UCode configuration as retrieved by ucConf
tdir

tdir
wtaq

wtaq
FUN

function that is invoked each time before WTAQ is run

Value

???

See Also

ucPrepCalib

Set placeholder in WTAQ parameter setting

Description

Set placeholder for parameter value in WTAQ parameter setting

Usage

ucSetPlaceholder(parname, wtaqConfiguration, pchar = "@")

Arguments

parname

Parameter name. Must be one of the aquifer parameters "bb", "hkr", "hkz", "ss", "sy" (for description see wtConfigureAquifer) or one of the drainage parameters "acc", "akk", "amm", "axmm" (for description see wtConfigureDrainage; parameter "alpha" currently not supported) or one of the pumpwell parameters "qq", "rw", "rc", "zpd", "zpl", "sw" (for description see wtConfigurePumpwell) or one of the observation well parameters "r_i", "z1_i", "z2_i", "zp_i", "rp_i", "xll_i" (for description see wtConfigureObservationWell) where "i" is the number of the observation well according to the list index in the "obswell" section of the parameter setting.
wtaqConfiguration

WTAQ parameter setting as created by means of wtConfigure
pchar

character to be used as the very first and very last character of the placeholder. Default: “@”

Value

Parameter setting in which a parameter value is replaced by an appropriate placeholder

See Also

ucConfParameter, ucConf

Compose Table Data

Description

Creates lines to be put in TABLE-data block of UCODE input file representing data in given data frame

Usage

ucTable(dat)

Arguments

dat

data frame

Test run of batch file

Description

Test run of batch file

Usage

ucTestBatchWtaq(bfile, wtaqConfiguration)

Arguments

bfile

path to batch file
wtaqConfiguration

WTAQ configuration

Write WTAQ arguments file

Description

Write WTAQ arguments file

Usage

ucWriteArgs(afile)

Arguments

afile

path to file containing arguments

Write batch file invoking UCODE

Description

Write batch file invoking UCODE

Usage

ucWriteBatchUcode(
  bfile,
  ucode = system.file("extdata", "ucode_2005.exe", package = "kwb.wtaq"),
  waitForInput = TRUE,
  inpfile = "ucode.in"
)

Arguments

bfile

full path to batch file
ucode

full path to UCODE executable file
waitForInput

if TRUE, "pause" is added to the batch file
inpfile

name of ucode input file

Write batch file invoked by UCODE, running first WTAQ and second the R script doing the goodness of fit evaluation

Description

Write batch file invoked by UCODE, running first WTAQ and second the R script doing the goodness of fit evaluation

Usage

ucWriteBatchWtaq(bfile, wtaq, verbose, waitForInput = FALSE)

Arguments

bfile

path to batch file
wtaq

path to WTAQ executable
verbose

if TRUE, the output is not discarded
waitForInput

if TRUE, "pause" is added to the batch file

Write batch file invoked by UCODE, which is just waiting until WTAQ has finished and goodness of fit is available

Description

Write batch file invoked by UCODE, which is just waiting until WTAQ has finished and goodness of fit is available

Usage

ucWriteBatchWtaqParallel(bfile, recheckAfterMs = 10)

Arguments

bfile

path to batchfile
recheckAfterMs

time to wait for file, in milliseconds

Write R script evaluating goodness of fit from WTAQ output file

Description

Write R script evaluating goodness of fit from WTAQ output file

Usage

ucWriteEvalGofR(rfile, uconf)

Arguments

rfile

path to R script file to be generated
uconf

UCODE configuration

Write UCODE instruction file, describing how to read goodness of fit values from wtaq.gof

Description

Write UCODE instruction file, describing how to read goodness of fit values from wtaq.gof

Usage

ucWriteInstruction(ifile, wtaqConfiguration, uconf)

Arguments

ifile

path to instruction file
wtaqConfiguration

WTAW configuration
uconf

UCODE configuration

Write UCODE main input file

Description

Write UCODE main input file

Usage

ucWriteMainInput(ufile, uconf, command)

Arguments

ufile

path to UCODE input file
uconf

UCODE configuration
command

name of batch file that is invoked by UCODE with each iteration

Write WTAQ input template file

Description

Write WTAQ input template file

Usage

ucWriteTemplate(tfile, wtaqConfiguration, uconf, pchar = "@")

Arguments

tfile

path to template file
wtaqConfiguration

WTAQ configuration
uconf

UCODE configuration
pchar

character indicating a placeholder

Evaluate goodness of fit for WTAQ result

Description

Evaluate goodness of fit for WTAQ result

Usage

uwGofEval(res, logtimes = FALSE, gofs = names(uwGofTargetValue()), ...)

Arguments

res

either character string representing full path to WTAQ result plot file or data.frame containing the content of the WTAQ result plot file.
logtimes

if TRUE, time steps are supposed to be logarithmic, i.e. it is assumed that the result plot file is in “matrix form”.
gofs

vector of names of fitness functions, evaluated by gof. Default: c("ME", "MAE", "MSE", "RMSE", "NRMSE", "PBIAS", "RSR", "rSD", "NSE", "mNSE", "rNSE", "d", "md", "rd", "cp", "r", "R2", "bR2", "KGE", "VE")
...

arguments passed to gof() function, e.g. digits: decimal places used for rounding the goodness-of-fit indexes.

Value

Evaluation matrix

Names of available GOF functions

Description

Names of available Goodness of fit (GOF) functions

Usage

uwGofNames()

Target values for different GOF functions

Description

Target values for different GOF functions, i.e. values that GOF functions return if observed and calculated timeseries are identical

Usage

uwGofTargetValue(gofs = uwGofNames())

Arguments

gofs

names of GOF functions of which target values are to be returned