Plot axis scale

[henrikt-ma]

The Figure annotation is currently lacking support for specification of axis scale. Plotting with other axes than linear is a feature that probably exists in all tools, and there should be a standardized way of specifying what kind of axis scale to use.

Initiating this PR in draft state to reflect that it is expected that the PR will need to be iterated for a while until we reach agreement on the design.

[casella]

For plots that have time on the X axis, the only case that comes to my mind where log for the Y axis could be useful is to display dB levels of sound pressure. Not something we simulate often in Modelica.

On the other hand, having x/y plots where both axes are logarithmic could be interesting in a number of cases, so I am in favour of having this possibility.

I'm not sure we should get so much into the details, MLS is 338 pages already...

[henrikt-ma]

For plots that have time on the X axis, the only case that comes to my mind where log for the Y axis could be useful is to display dB levels of sound pressure. Not something we simulate often in Modelica.

It was expected that the inclusion of dB in this PR would cause reactions, but I prefer having a discussion about it now rather than realizing in the future that all tool vendors ended up defining their own vendor-specific decibel axis scale just because it was missed in the standard.

A tool with frequency analysis post-processing will be using plots with frequency on the x-axis, and where a decibel axis is a natural choice for the y-axis. While a frequency domain plot isn't something we can currently express in a standard Figure-annotation, it is not unlikely that tools will come up with something vendor-specific to express this.

I'm not sure, but it might even be possible to define some sort of frequency sweep experiment where one puts the (time-varying) frequency of a sinusoidal source on the x-axis, and some sort of instantaneous signal power estimate on the y-axis. In that case, a decibel axis may be useful even in a tool that only supports figures that can be expressed with standard annotations (no tool-specific frequency analysis needed).

[HansOlsson]

Having the possibility to set a logarithmic scale is sometimes important, but it's not clear if we need to consider a more general case. As for decibel it's somewhat complicated - the Bode-plot is a famous example of actually plotting decibel (10*log10(y) on the y-axis), but it seems more natural to compute that number in the model instead.

[henrikt-ma]

Having the possibility to set a logarithmic scale is sometimes important, but it's not clear if we need to consider a more general case. As for decibel it's somewhat complicated - the Bode-plot is a famous example of actually plotting decibel (10*log10(y) on the y-axis), but it seems more natural to compute that number in the model instead.

To be a Bode plot should have the actual system gain on the y-axis, so that if I extract a value at a certain frequency I get abs(G(i ω)), and not some function of this computed in the model to compensate for the lack for the proper axis scale setting. I might also be interested in switching between a decibel scale and a plain log scale. Also, if we think of Modelica time domain simulations, there's probably not even a place in the model where the decibel conversion can be expressed.

[casella]

BTW, don't forget there are two different decibel scales. For power, dB is defined as 10*log10(W_out/W_in), but for amplitude it is defined as 20*log10(V_out/V_in) 😅

In other terms, a system that has an amplitude gain of 100 (i.e. the output voltage amplitude is 100 times larger than the input voltage amplitude) has a gain of 40 dB, not 20 dB. Which means that the output power is actually 10^4 times larger than the input power.

I'm not sure if this concerns the present ticket, or is rather an upstream issue that the solver should handle.

[HansOlsson]

BTW, don't forget there are two different decibel scales. For power, dB is defined as 10*log10(W_out/W_in), but for amplitude it is defined as 20*log10(V_out/V_in) 😅

In other terms, a system that has an amplitude gain of 100 (i.e. the output voltage amplitude is 100 times larger than the input voltage amplitude) has a gain of 40 dB, not 20 dB. Which means that the output power is actually 10^4 times larger than the input power.

I'm not sure if this concerns the present ticket, or is rather an upstream issue that the solver should handle.

I would say that there are so many caveats with using decibel (the hinted power vs. amplitude, adding reference value for power/voltage, and the common dB(A) which includes A-filtering) that I would not be comfortable with adding it.

[henrikt-ma]

BTW, don't forget there are two different decibel scales. For power, dB is defined as 10*log10(W_out/W_in), but for amplitude it is defined as 20*log10(V_out/V_in) 😅

This has not been forgotten: the scaling factor is a mandatory parameter of the dB scale. This is also why the text recommends that the choice of factor is made visible. Having this as standardized axis scales can thereby avoid confusion that could easily result from domain-specific library implementations where the choice between dB_10 and dB_20 isn't made clear.

[henrikt-ma]

I would say that there are so many caveats with using decibel (the hinted power vs. amplitude, adding reference value for power/voltage, and the common dB(A) which includes A-filtering) that I would not be comfortable with adding it.

Since dB(A) has a distinct notation, I don't see any risk of confusion. I also think that the definition of dB(A) or dB(C) seem to lack the generality that would motivate including them in the specification.

When it comes to the plain dB_10 and dB_20 i think that we must weigh the pros against the cons. I know that it is considered a con that decibel scales are complicated due to the choice between dB_10 and dB_20, but one needs to also see the problems it may cause to omit these well-established scale from the standard and thereby require tools to handle these in tool-specific ways using vendor-annotations instead. For me, the benefit of avoiding tool-specific solutions to this need is a stronger argument than that it is complicated to make the right choice of dB_10 or dB_20.

That said, I can also see that it wouldn't be a big deal delaying the standardization of dB scales until there is a standard for plotting simulation results in the frequency domain. I mean, it isn't a problem for the portability of figures as long as the vendor-specific axis scales are only used in vendor-specific plots. Further, if frequency domain plots made it into the standard in the future, it would probably not be a big problem for a tool to change representation of the decibel axis scales as part of adapting its frequency domain plots to the standard.

[henrikt-ma]

Just as I was ready to give up hope that there would be sufficient interest in Bode plots being taken seriously by the standard, the following example from the MSL was brought to my attention: Modelica.Electrical.QuasiStatic.SinglePhase.Examples.SeriesBode. It contains an instance of Modelica.ComplexBlocks.ComplexMath.Bode. It shows that the frequency sweep idea isn't merely hypothetical, and a Figure-annotation with properly set up logarithmic frequency axis, decibel gain axis, and linear degree phase axis would be a huge enhancement of the example.

Having a dB axis unit would also remedy the problem that the kind of decibel scale is currently expressed in the block via the dB constant, which cannot be used to tailor the axis tick labels. At best, some abuse of the Axis.label or the Figure.caption could be used to make the reader aware of the current decibel factor (this wouldn't even work in System Modeler, where constants are omitted from simulation results). Making the constant final would alleviate the problem somewhat, but a reader who isn't used to Bode plots may still be confused or unsure about what is meant by just "dB".

[HansOlsson]

I looked up K. J. Åström's "Reglerteori" (meaning "Control Theory" for non-Swedes) and there the terms discussed for Bode-plots were decibel (meaning 20log10 - no discussion about of different ones), decilog (10log10 - which allegedly became popular in the 1950s and then died out a few decades later), and Neper (natural logarithm).

However, all the graphs just used log10(y) on the axis; as the important part are how it bends and where the magnitude is 1 (where log10, decilog, decibel, nautral logarithm are all zero).

Similarly in Modelica_LinearSystems2 decibel just means 20*log10, but the default is to just use magnitudes.

[HansOlsson]

That said, I can also see that it wouldn't be a big deal delaying the standardization of dB scales until there is a standard for plotting simulation results in the frequency domain.

I agree that it may be simplest.

[henrikt-ma]

The dB axis scale has now been removed from the proposal due to poor interest-to-controversy ratio. Marking as ready for review as the dB was the only part that caused reactions so far.

[HansOlsson]

seems ok for me.

[DagBruck]

I do not disagree with the proposal as such, but there is one thing I would like to ask about.

The PR proposes the attribute Integer bas(min=2) with a default value of 10. Is there really a need in Modelica for any other base than 10? Note that we have eliminated the natural logarithm, so what other base would be used? Maybe base 2, but is that meaningfully used by Modeica models, it smacks of computer science?

[henrikt-ma]

I do not disagree with the proposal as such, but there is one thing I would like to ask about.

The PR proposes the attribute Integer bas(min=2) with a default value of 10. Is there really a need in Modelica for any other base than 10? Note that we have eliminated the natural logarithm, so what other base would be used? Maybe base 2, but is that meaningfully used by Modeica models, it smacks of computer science?

This was discussed at the last phone meeting. Uses of other bases that I am aware of have to to with information, and it isn't obvious to me that uses would be restricted to computer science in such a way that making relevant Modelica models would be excluded. By including the base in the standard, we avoid that tools invent different tool-specific solutions. Further, if a tool ignores the base, it won't break things badly; you'd still get a logarithmic plot, but with a different labeling of the axis.

Would it ease your mind if a non-normative paragraph was introduced, explaining the mild consequences of failing to support base?

[DagBruck]

Would it ease your mind if a non-normative paragraph was introduced, explaining the mild consequences of failing to support base?

Not much, but I don't see this as a blocking point in any case. My lucky number is 3, and I can see this as a potential revival of base-3 logarithms. So be my guest.