Improve icon and documentation of ElectroMagneticConverter

[AHaumer]

Refers to #3218:
improve icon (reference arrows) and documentation (include a hint about right-hand screw rule) of ElectroMagneticConverter

[christiankral]

Ampere's law relates the terms magnetomotive force and magnetic voltage. This is a similar situation as with the relation of the electromotive force and the electric voltage in Kirchhoff's law. With these terms the two laws are:

• Ampere's law: F = sum(V_m): The sum of all magnetomotive forces counted with the correct sign in a reference direction is equal to the sum of all magnetic voltages counted in the same reference direction
• Kirchhoff's law: E = sum(v): The sum of all electromotive forces counted with the correct sign in a reference direction is equal to the sum of all electric voltages counted in the same reference direction

Modelica can neither treat magnetomotive nor electromotive forces directly in interconnected equivalent circuits. Instead the two laws are applied in a different way:

• Ampere's law: sum(V_m) = 0: The sum of all magnetic voltages counted with the correct sign in a reference direction is equal to zero
• Kirchhoff's law: sum(v) = 0: The sum of all electric voltages counted with the correct sign in a reference direction is equal to zero

Therefore each magnetomotive and electromotive is converted into an equivalent magnetic and electric voltage, respectively. In a magnetic circuit the electromotive force N * I is modeled as a magnetic voltage source V_mF oriented from plus to minus in the figure above.

Therefore, there exists a

• right-hand assignment between the magnetomotive force F (thumb) and the current I (fingers) -- which is true but not implemented in Modelica --, but a
• left-hand assignment between the magnetic voltage of the source, V_mF (thumb) and the current I (fingers) -- which is implemented in Modelica.

[beutlich]

Here's a visual diff from SimulationX:

Before the change:

After the change:

[HansOlsson]

The new blue arrow from the screenshot above looks odd to me (and is easy to miss). Do we have any references showing such diagrams?

[DrMartinKuhn]

I have doubts about the documentation using the term "Kirchhoffs laws". The Kirchhoffs laws are well known from the voltage and current laws, not like they are used here. Even if there exist quotations like this it may confuse the users (see what appears if you google "modelica kirchhoff").

[AHaumer]

@HansOlsson
The old arrows are misleading: The blue arrow shows voltage, and voltage stems from derivative of flux. The orange icon shows magnetic potential difference. The direction of flux resp. derivative of flux depends on the rest of the magnetic circuit.
The "new" arrows show corresponding values: the current (blue arrow) drives a magnetic potential difference (the orange arrow). The other two arrows (induced voltage and magnetic flux) are omitted.
We could enlarge the blue arrow (current) a little bit ...

[AHaumer]

@DrMartinKuhn
In fact in most domains Modelica follows Kirchhoff's laws (except stream variables):
The sum of potential differences in a closed loop is zero.
The sum of flow variables in a node is zero.
Of course this is true for magnetism, too:
Potential difference = magnetic potential difference
Flow variable = magnetic flux
And yes, in teaching and in some textbooks we use magnetic equivalent circuits and follow Kirchoff's laws. We also talk about magnetic conductance and magnetic resistance. Unfortunately, ferromagnetic materials show a nonlinear magnetic resistance resp. conductance due to saturation.
As a summary: The term "Kirchhoff's laws" is correct and should support understanding of magentic circuits.

[DrMartinKuhn]

@DrMartinKuhn
In fact in most domains Modelica follows Kirchhoff's laws (except stream variables):
The sum of potential differences in a closed loop is zero.
The sum of flow variables in a node is zero.
Of course this is true for magnetism, too:
Potential difference = magnetic potential difference
Flow variable = magnetic flux
And yes, in teaching and in some textbooks we use magnetic equivalent circuits and follow Kirchoff's laws. We also talk about magnetic conductance and magnetic resistance. Unfortunately, ferromagnetic materials show a nonlinear magnetic resistance resp. conductance due to saturation.
As a summary: The term "Kirchhoff's laws" is correct and should support understanding of magentic circuits.

Sorry, I still have my problems with the inter-domain E=sum(v). Six lines below there is 0=sum(v) without visual change of variables.

[HansOlsson]

@HansOlsson
The old arrows are misleading: The blue arrow shows voltage, and voltage stems from derivative of flux. The orange icon shows magnetic potential difference. The direction of flux resp. derivative of flux depends on the rest of the magnetic circuit.
The "new" arrows show corresponding values: the current (blue arrow) drives a magnetic potential difference (the orange arrow). The other two arrows (induced voltage and magnetic flux) are omitted.
We could enlarge the blue arrow (current) a little bit ...

My main concern was that we shouldn't try to invent some new graphical representation for this, but reuse what others do. To me there are two related issues with the design:

• The arrow is not easy to see, as it is shown in a busy section of the icon. Could it be moved to top-line of the icon instead? (I.e. horizontal arrow pointing right below the text "converter".)
• Having the blue line before the windings to me gives the impression that the current is input, i.e. a model with intended causality. (Similarly as electrical current sources have the arrow at the output indicating that current is an output of the sources.)

An alternative (used for transformers in many places - including Modelica.Electrical as I recall) is to not have arrows at all.

[dietmarw]

One additional problem in the icon (old and new) is the direction of the V_m arrow. It follows the German VZS (Verbraucherzählpfeilsystem) where voltage arrows always point from + to - but this convention confuses international users (especially in a non-German library) where the PSC (Passive Sign Convention) system defines voltage arrows always pointing towards +. Many international books don't use voltage arrows at all and simply indicate + and - which might be the safest bet.

[DrMartinKuhn]

Considering the comments of Hans and Dietmar I propose to delete all arrows. For the proposed documentation, I have the feeling it does not improve the understanding but it is contradictory in some parts. Furthermore it tries to introduce a left or right hand system - while there was never defined any coiling direction in the original component and in the end it is all about definition since we transfer a 2D system to 1D. Therefore I propose to leave the old documentation and extend it by
"By definition, an electrical current into positive pin p effects a positive magnetomotive force V_m between magnetic port_p and port_n. This may cause a flux Φ out of port_p in a closed reluctance circuit. Coils with opposite winding direction can easily be considered by swapping the connection to their magnetic ports."

[christiankral]

Considering the comments of Hans and Dietmar I propose to delete all arrows.

I agree to remove all arrows.

[christiankral]

As of the icon, some suggestions and thoughts:

1. The reason for the symbol within the orange circle is to associate the magnetomotive force with the Greek letter Theta

which is a purely German thing. As the magnetic voltage caused by the electric currents is a magnetic voltage source it may make sense to indicate it as a magnetic voltage source.

2. Does the dotted line really improve the icon?

[AHaumer]

Ok @christiankral is correct: We have a definition of positive directions of voltage, current, mmf resp. magnetic potential difference and flux - there's no need for arrows.
I'd omit the "H" (theta) as well as the dotted line, but I'd draw the orange line through the orange circle (it is a source of magnetic potential difference, compare with electric voltage source).
@DrMartinKuhn
We have two cases for Kirchhoff's voltage law:
If der(flux) is not present, we have the "original" law sum(v)=0.
But in case der(flux) is present, we can change this to sum(v)=E where E represents induced electromotive force.

[HansOlsson]

Would it be possible to also add the sources of the images besides the PNG? Preferable in SVG (there is a nice tex text inkscape extension that lets you embed editable LaTeX code). I guess they are done in Ipe which is a nice but not so known tool.

Since the images contain text this becomes more important when we want to support modelica/ModelicaSpecification#302

[beutlich]

Since the images contain text this becomes more important when we want to support modelica/ModelicaSpecification#302

Hm, it's only letters, right? I do not think that we need to translate images in first place.

Might be rather related to modelica/ModelicaSpecification#546.

[AHaumer]

How do we proceed with that PR?

[dietmarw]

Independent on any SVG support it would still be nice to have the sources of the images in the repository. Could you add them?

[christiankral]

Independent on any SVG support it would still be nice to have the sources of the images in the repository. Could you add them?

@dietmarw The currently used image and the source IPE file are stored at https://gitlab.com/christiankral/ModelicaImages/tree/master/ModelicaImages/Magnetic/FluxTubes/Basic/ElectroMagneticConverter

Shall we copy the IPE file to the folder Modelica/Resources/Images/Magnetic/FluxTubes/Basic/ where the PNG file is stored?

[dietmarw]

@christiankral Yes having the source files in the same location and same name (except the extension of course) makes it easy to find and edit at a later point in time.

[beutlich]

Should we add them as export-ignore in .gitattributes? This should then also hold for other source files like:

• Modelica/Resources/Documentation/Clocked/Modelica_Synchronous.pptx
• Modelica/Resources/Documentation/Fluid/Stream-Connectors-Overview-Rationale.ppt
• Modelica/Resources/Documentation/Mechanics/Figure_PlanarLoopAnalytic.ppt

[dietmarw]

Yes, that might be a good idea. @christiankral I suggest you add the IPE sources in .ipe xml format since then we can just globally exclude those files from export (for the release).

[AHaumer]

@beutlich Hope these ppt are avialable as pdf, too.

[beutlich]

@beutlich Hope these ppt are avialable as pdf, too.

Yes, there are Modelica/Resources/Documentation/Clocked/Modelica_Synchronous.pdf and Modelica/Resources/Documentation/Fluid/Stream-Connectors-Overview-Rationale.pdf. File Modelica/Resources/Documentation/Mechanics/Figure_PlanarLoopAnalytic.ppt is only used to draw the figures, thus there is no PDF required here.

[beutlich]

Please be aware, that I rebased the PR branch and resolved the merge conflict.

[HansOlsson]

Hm, it's only letters, right? I do not think that we need to translate images in first place.

The Ampere's Law image contains texts - not just single letters; and that raises the issue of translation.

[dietmarw]

I've added the image source files to the export-ignore list. As for the translation since the image is part of the documentation than a documentation in a different language would simply have to come up with a different image if needed. In my eyes no need to hold off this PR because of that.

[HansOlsson]

As for the translation since the image is part of the documentation than a documentation in a different language would simply have to come up with a different image if needed. In my eyes no need to hold off this PR because of that.

I agree with the conclusion. It was just that it implies that when translating we also need to consider this - e.g., allow different images for different languages, or revisit that part of the PR.