Dimensional analysis with math functions flags a warning

I'm getting a warning when I run with dimensional analysis.

_ Cannot perform dimensional analysis for rule 'rule_13' because of the function 'exp' in the rule. It is recommended that input and output arguments to functions be dimensionless to ensure correct results._

In my model, the argument to the exp referred to is dimensionless, and the entire rule is dimensionally consistent if I assume that the exp function has no dimension (that is, dimensionless). Is there any way to tell Simbiology "Hey, check my input arguments, and assume that the output is dimensionless", so that the warning will go away?

Put another way, even if I did get a warning like the following, it would be more useful (provided that the warning was true)

Rule 13 includes an exp() function. Dimensional analysis has checked the input argument and the rule itslf. The units of the argument to exp() is dimensionless. The rule is dimensionally consistent, assuming that the exp function is dimensionless.

I have a lot of functions in my model with exp, erf, and other functions that trigger this warning. DA would be most helpful if it did check the argument and the rule (under the assumption that the offending function is dimensioneless.

Or does DA already do this?

Thanks.

Answer 1

[Arthur Goldsipe]

The short answer is that SimBiology does not currently confirm that the inputs to exp are dimensionless, but I agree that this would be a very useful enhancement.

This warning is meant to convey two important pieces of information:

1. SimBiology is not doing any dimensional analysis on the input arguments to the function (exp in this case).
2. It's safest to write function calls with dimensionless inputs, because SimBiology does not make guarantees about what units will be used when an input is not dimensionless and you enable unit conversion.

Let me talk a little more about point #2. Consider a case where the input to a function is a parameter for which you've set the units to millimeter. SimBiology might actually pass in the value of the parameter in meter. If that seems surprising, consider what units SimBiology should use if the input argument was the sum of two parameters, one with units of meter and another with units of millimeter. So, during a simulation, SimBiology converts all lengths to the same unit, if you enable unit conversion.

You might wonder why SimBiology doesn't check that the inputs to your function are dimensionless. Well, in the general case, we don't know whether the inputs to a function are expected to be dimensionless or not. In the case of exp, you and I know the inputs should be dimensionless. But it does get a little tricky, because MATLAB allows you to define your own version of exp that shadows the builtin exp and expects the input argument to have a particular unit. I can't imagine why anyone would actually do this with exp. Practically speaking, I think it would be better for our users if SimBiology did "proper" dimensional analysis on common mathematical functions like exp and erf. This is something that has been on my radar, but I'll make sure to add your comments to our database of enhancement requests.

[Jim Bosley]

Thanks once again, Arthur. Useful comments.

I initially said "Rest assured that my input arguments are dimensionless" but your point about the units that Matlab may used (I may write something in millimoles, and the function may see moles) will have me double checking everything.

I'm assuming that exp, erf (and CSDerf and CSDmod for that matter) arguments must be dimensionless. Not sure how really rigorously one can apply the Buckingham π theorem in a QSP model.

Forced_glucose, on the other hand must have units. In the future, it might be nice to be able to assign units to functional outputs.

[Walter Roberson]

Simscape offers value() to convert to a given unit and then strip off the unit marker so that the result can be passed to a mathematical function; units can then be attached again by using the {EXPRESSION, UNITS} syntax. See https://www.mathworks.com/help/physmod/simscape/lang/defining-component-equations.html

However, I do not see any equivalent in Simbiology?

I do see the ability to configure a species as being 'dimensionless', but I do not see any way to strip off a dimension, and one cannot, for example, convert 'mole' to 'dimensionless' .

I also notice that in Simscape that the unit is attached to the (sub-) expression, so one can take an object and change representation within an expression without affecting the state of the object. However I see that in Simbiology that the units appear to be part of the object, and that the only way to change representation is to do a units conversion that changes the state of the object.

As a programmer, I have to say that I find the Simscape way of doing things more natural. Figuring out the first time that the {} syntax was what was needed to re-attach units did take some investigation, but it made sense when I found the above link.

[Jim Bosley]

Walter, thanks. In Simbiology, what I'm doing is using native MATLAB functions, like erf and mod, in rate laws. Simbiology is strongly typed, with all species and parameters having units (at least, the should have, as this contributes to avoiding your model being "write once, read never"). WRT species, there are further constraints on what dimensions can be used (species must be an amount of something, or a concentration of something, where I think something is a molar or mass type). The rate laws don't seem to have explicit dimensions, but they must construct dimensions from the rate law.

The warning message is basically "you used erf* in a rate law, and so we're not checking dimensions for the law, but you really should ensure that your argument to erf* is dimensionless, and that the rate law makes sense if erf* itself has no dimensions".

The point is, one shouldn't use

rate = rate_coeff*erf(gluc_conc)

with gluc_conc in mmol, and rate_coeff in mmol/minute (for example) but rather

rate = rate_coef * erf(gluc_conc/base_gluc_conc)

with base_gluc_conc in the same units as gluc_conc.

There is another issue, if you use .m file functions in your model. For example, I've implemented forcing functions in one SB model. If I switch a couple of rules (g_ODE to inactive, g_forced to active), my model uses a glucose concentration that is generated by a spline function instead of the ODE generated values. So there's a repeat assignment rule

glucose_used = glucose_forced(t);

and glucose_forced.m is a Matlab function that obtains the glucose data needed, and fits it to a spline and spits it back out as a function of t. It would be nice if I could assign a mmol/liter dimension to that.

If MATLAB/Simbiology assumed all native functions* were dimensionless, and insisted that all functional arguments were dimensionless, that would make Dimensional Analysis easier. Being able to put dimensions on an .m file would be preferable than assuming the .m file output is dimensionless, but I suppose one could use a unit "dimension assigner variable, ala

glucose_used = unit_gluc_conc * glucose_forced(t);

where unit_gluc_conc has value 1 and units of millimole/liter.

In the past year, I've used Pathway Designer, FORTRAN (for a PDE model), MATLAB, Octave, Python, Julia, Simulink, and Simbiology to write QSP models. Simscape was designed (or is at least touted as) a good environment for physical system simulation. Simbiology was designed to address QSP and other biological systems modeling task. And specifically, it does have a built-in nonlinear mixed effect fitting package. Right now, I have about a 50 state QSP model I'm developing for one client, and a couple of ~10 state model semiphysiological popPK model for another.

I'm pointing out that learning another system, like Simscape, is probably not in the cards for me right now. But are others using Simscape for bio- and QSP models?

*could be any function - erf, sin, mod, spline....

[Jim Bosley]

Right now I get 14 warnings saying (for example) "cannot perform analysis for rule "rule_9" because of the function 'exp' in the rule. A simulation setting (radio button) that allows one to opt for

"Assume all functions are dimensionless"

Would be nice. It would also allow one to use unit conversions. Also a button to opt for

"Check to ensure that all function arguments are dimensionless"

would also be nice. This would then enforce good coding:

conc = base_conc * exp( - time*time_constant); %

where base_conc and time_constant have the units of conc, and 1/time, respectively.