Figure annotations in all Modelica.Electrical.Machines.Examples.*

[AHaumer]

As decided in MAP-Lib monthly meeting 2026-09-08.

[henrikt-ma]

It's very nice that this is finally happening!

I would prefer that we set the style now that each figure shall have a caption. I'd rather have a smaller number of models with nice figures, than figures without caption in every model. I would guess that asking an AI to create captions based on existing model documentation and plotted variables would get it mostly right, especially if combined with MSL figure style guidelines to follow.

A style guide should probably also say something about the use of curve legends, and give recommendations regarding (that is, against) variables of incompatible units in the same plot. Requiring that each figure an identifier from start could also be a good idea so that any figure can be referenced from start.

To keep the process simple, I suggest that the figure style guidelines are developed as part of this PR, so that we can iterate on the figures until we are satisfied with the guidelines (assuming that the figures are kept up-to-date with the guidelines).

I believe this file is where the guidelines would belong: https://github.com/modelica/ModelicaStandardLibrary/blob/master/Modelica/UsersGuide/Conventions.mo

[AHaumer]

@henrikt-ma thanks for your feedback, I have some questions:

• The identifiers given automatically look somehow clumsy to me. Can I give just a meaningful name?
• Is it better to have more plots in the same figure or more figures (avoid trajectories with different units in the same plot)?
• Should the axis get defined (maybe with omitted min and max) and should the unit be included (e.g. time [s])?
• Do you mean that we should define legends (if we have more than one trajectory in the same plot)?
• How can I define the placement of the legend?

Developing guidelines is a good idea. I would appreciate a PR prepared by you.
I plan to update this PR according to the the guidelines, therefore setting to "draft" for now.

[AHaumer]

Well, after some tests: More plots in the same figure results in too small plots. Treplaced by more figures.
@henrikt-ma I've enclosed an example - what do you think?
IMC_DOL.zip

      figures = {
        Figure(
          title = "IMC DOL: RMS Line Current",
          identifier = "IMC_DOL_1",
          preferred = true,
          plots = {
            Plot(
              curves = {
                Curve(x = time, y = currentQuasiRMSSensor.I)},
              x = Axis(label="time", unit="s"),
              y = Axis(label="RMS Line Current", unit="A"))},
          caption = "Fig. 1 Induction machine started direct on line"),
        Figure(
          title = "IMC DOL: Electromagnetic Torque",
          identifier = "IMC_DOL_2",
          preferred = true,
          plots = {
            Plot(
              curves = {
                Curve(x = time, y = aimc.tauElectrical)},
              x = Axis(label="time", unit="s"),
              y = Axis(label="Electromagnetic Torque", unit="N.m"))},
          caption = "Fig. 2 Induction machine started direct on line"),
        Figure(
          title = "IMC DOL: Rotor Speed",
          identifier = "IMC_DOL_3",
          preferred = true,
          plots = {
            Plot(
              curves = {
                Curve(x = time, y = aimc.wMechanical)},
              x = Axis(label="time", unit="s"),
              y = Axis(label="Rotor speed", unit="rpm"))},
          caption = "Fig. 3 Induction machine started direct on line")}

[HansOlsson]

Well, after some tests: More plots in the same figure results in too small plots. Treplaced by more figures.

I agree that having multiple curves in different units in the same plot is not ideal, but I view it as a trade-off and for this case I preferred having all of them in one plot as before - in particular since:

• You more quickly get an overview of everything, instead of having to select multiple figures
• You see how changes in one curves are coordinated with changes in other curves
• You want to zoom in on the time-axis to see what happens, which seems odd for multiple windows (for sub-windows it seems more logical)

However, for other examples like Modelica.Electrical.Machines.Examples.ControlledDCDrives.CurrentControlledDCPM it might help to have different figures - as you currently only plot the control signals, and not the actual thing you control (speed for load).

We might also consider having non-preferred-figures.

Basically we currently have the following options for these signals:

• One figure with one plot with multiple curves in different units (with issues; even if the values have similar magnitudes in the default unit it because complicated if we want to change the unit)
• One sub-plot per unit, with the disadvantage that the sub-plots become too small (especially if there are three or more)
• Multiple figures - with the issues I listed

None are ideal, so I could see the following future possibilities:

• Support more than one plot axis in a plot; e.g., Dymola has the possibility to have two vertical axis (with different units) for one plot - we could work on standardizing something along those lines
• Some way of having sub-plots that aren't too small
• Plot other variables to avoid the issue? (assuming they exist)

[AHaumer]

@henrikt-ma @HansOlsson
After trying a little bit I think:

• It's better to have multiple figures with the drawback that one figure would provide a better overview, but:
• Having multiple plots in the same figure results in plots with to small height
• I strongly prefer to see the unit together with the axis label
• I tend to use a legend only if I show multiple variables (with the same unit) in the same plot.
  My 2 most used layouts are shown in the test enclosed.
  FigureTest.zip
  Hopefully our discussions lead to an agreement, then I'd update this PR and make it ready for review.

[DagBruck]

I can just add that I'm all in favor of adding figure annotations in MSL, and at least one for each example should have preferred=true, so you get some meaning output after simulation.

@AHaumer we have improved Dymola a little with regards to captions, they are now displayed as a heading at the top of the plot, above the legend. Today you find it by pressing the "?" button in the title bar.

[henrikt-ma]

• Support more than one plot axis in a plot; e.g., Dymola has the possibility to have two vertical axis (with different units) for one plot - we could work on standardizing something along those lines

We have this feature in System Modeler too, and I wouldn't be surprised if there are even more tools with this feature. Given that the feature exists in two or more tools, I agree that standardizing it would be good.

Edit: Here's the PR for adding this to the specification: modelica/ModelicaSpecification#3938

[henrikt-ma]

• The identifiers given automatically look somehow clumsy to me. Can I give just a meaningful name?

Yes, no problem.

• Is it better to have more plots in the same figure or more figures (avoid trajectories with different units in the same plot)?

As others have already suggested, having several figures with one one being a preferred one seems like a good compromise when there are many things to show that would otherwise lead to variables with incompatible units being placed on the same y-axes.

• Should the axis get defined (maybe with omitted min and max) and should the unit be included (e.g. time [s])?

I recommend relying on default behavior unless you have good reasons to take explicit control.

• Do you mean that we should define legends (if we have more than one trajectory in the same plot)?

I don't know what to recommend, but I recommend having some sort of recommendation.

• How can I define the placement of the legend?

You shouldn't; it's up to the tool.

Developing guidelines is a good idea. I would appreciate a PR prepared by you. I plan to update this PR according to the the guidelines, therefore setting to "draft" for now.

Sure, we can do it this way.

[henrikt-ma]

Developing guidelines is a good idea. I would appreciate a PR prepared by you. I plan to update this PR according to the the guidelines, therefore setting to "draft" for now.

Sure, we can do it this way.

Done: #4813