[JOSS review] Documentation of process target rate

[nick-gorman]

The documentation is unclear as how setting the rate at which a process consumes resources works. Specifically, when you set an upper and lower bound on the rate I assume there is some penalty to make the solver try and hit the target value, but this isn't stated. Also, if this what's going on, what is the penalty rate being used?

openjournals/joss-reviews#4460

[kcerva]

Hi @nick-gorman. I think this is a misunderstanding of how the model works. The rates at which processes consume resources are defined by the user (e.g., as kg materials/MW). Upper and lower bounds of these rates (or material intensities) can be given too. There is no "penalty" per se defined in the model (i.e., this is not a linear optimisation defined with a penalty function). The way it works, is just the usual way where an objective function is defined. The function represents the target of the solver, but the values of the process runs can vary anywhere within the specified upper and lower bounds to minimise/maximise the target function. The exact value specified in this case is just the result if no bounds were set. Please see here for documentation on the objective function.

We have also included error messages for when problems are overconstrained or unbounded so the user can make the required changes. Please see more here.

Hope this answers your question.

[nick-gorman]

Does this mean that the target value is redundant if an upper and lower bound are provided? If so, maybe the docs should state this?

[kcerva]

No, the target value is used in the optimisation for sure, and the upper and lower bound are optional and can be used to find some sort of uncertainty range.

[nick-gorman]

Do you think the meaning of these inputs and what they do needs to be better documentation? Honestly, I'm still unsure.

If the target values are still used in the optimization, even when the upper and lower bound are provided, how does that work considering what you said before "the values of the process runs can vary anywhere within the specified upper and lower bounds to minimise/maximise the target function". How is the target value being used?

[kcerva]

We have documented the option to use the bounds or not in the model in the Measure section e.g. .run() with the boolean for using bounds. We have also used bounds in one of the examples that we provided so users can get familiar with the model here.

Not sure how else to address the confusion, but I have a feeling there is still a misunderstanding on how the upper and lower bounds are used. I should stress that they help get some sort of uncertainty range for users and their use involves solving the optimisation at the specified bounds.

Hope that helped more.

[nick-gorman]

ok, now I think I understand it "their use involves solving the optimisation at the specified bounds", that make sense. Is this documented somewhere?

[kcerva]

Yes, there is documentation in the Processes section. See the example code in particular, which is even more explicit. Then, the Measure section complements this by giving options of when/how to "turn on/off" the bounds.

[nick-gorman]

OK, I guess I was just trying to communicate that for me as a new user those pieces of documentation didn't really communicate what as going on clearly. All good.