Calibration - adding parameters: When to use set_parameter() and when set_parameter_by_reference()?

[MattBrst]

Question

When performing calibrations, there are two ways of adding parameters to the calibration:

1. cal.set_parameter()
2. cal.set_parameter_by_reference()

Could you explain when to use which function?

My guess would be:

1. Use cal.set_parameter() for aquifer parameters
This function works for kaq, 'c', Saq, Sll values, so: aquifer parameters. Can be found in many examples.

2. Use cal.set_parameter_by_reference() for advanced use cases
The documentation shows examples where this function is used for fitting on:

• skin resistance (Hardinxveld example)
• casing radius of a well (Nevada example)

In discussion #186 @mbakker7 mentioned that the latter function can be used as well for aquifer parameters that are not (yet) available through through the first function. In that discussion loading efficiency values leffaq and leffll were mentioned.

[mbakker7]

The set_parameter function can be used for the specific parameters that are pre-defined in Timflow. As the docstring says, these are currently 'kaq', 'Saq', 'c', 'Sll' or 'kzoverkh'. The set_parameter function has the additional functionality that these parameters can be set equal across inhomogeneities.
The set_parameter_by_reference function can be used to set any parameter that is stored as an array. One or multiple values of the array can be specified, but the user has to know what the name of the parameter is in the code. As such, this requires more knowledge of the code (and is less user-friendly in that sense). This function does not have the functionality that a parameter can be the same across inhomogeneities, because these parameters can be anything, for example the resistance of the river bottom, which is not associated with an inhomogeneity.
I hope this clarifies the current implementation. If you have suggestions how to do this better, of if you have parameters that you want added to the set_parameter function, please let us know (or submit a PR - especially the latter is quite easy to do).