Initial values for polyphase inductor currents etc.

[ceraolo]

Good modelica models have initial values defined, otherwise the results can be depending on the used tool and the assumptions it makes on those inital values.

When creating electric circuits, the most common state variables whose initial values are to be set are capacitor voltages and inductor currents. Modelica.Electrical.Analog.Basic capacitors allow setting initial voltages, and inductors intial currents.

Unfortunately the same does not occur with Modelica.Electrical.Polyphase capacitors and inductors.
Maybe one can set initial values for a polyphase inductor through modifiers, but this, if possible, is tricky. Personally, I could not find a way, at least in a three-wire circuit for which only two of the three currents must be set.

It seems to me that polyphase inductors and capacitors, and the other polyphase components having state variables, should have a way to set initial values from their masks, similar to their single phase counterparts.

[casella]

@AHaumer, @christiankral what do you think?

[AHaumer]

Lets investigate the polyphase inductor, the capacitor can be treated analogous.
The number of phases m can be choosen by the user. We have available the currents i[m] through the component.
You have situations in which you are allowed to define all m initial currents (star-point connected), but if the star-point is not connected the sum of the m currents is zero and you are allowed to define only m-1 initial currents.
How do you handle that? You can set only all m initial values at once. @ceraolo please give me a suggestion.
You have to consider not only the trivial case where the m or m-1 currents are initialized to be zero,
maybe you want to initialize them with m or m-1 different initial values.
Even if we try to motivate the tool to present an initialization menu:
Dymola 2024x doesn't do that, OM 1.23.1 does so.
But you can only initialize all m currents together (yes with different initial values) but either all of them fixed=true or all of them fixed=false. How do you handle the condition star-point not connected?
@HansOlsson Do you have a suggestion from the language point-of-view?
IMHO the only way to handle that is to write initial equations:
`model Inductor

extends Modelica.Electrical.Polyphase.Basic.Inductor(i(start=zeros(m)));

initial equation

//i[m] = zeros(m);

i[1:m-1]=zeros(m-1);

end Inductor;`

[ceraolo]

Lets investigate the polyphase inductor, the capacitor can be treated analogous. The number of phases m can be choosen by the user. We have available the currents i[m] through the component. You have situations in which you are allowed to define all m initial currents (star-point connected), but if the star-point is not connected the sum of the m currents is zero and you are allowed to define only m-1 initial currents. How do you handle that? You can set only all m initial values at once. @ceraolo please give me a suggestion.

What I propose is to give users the possibility to set initial currents, possibly using a way such as the obtainable flexibility is lower than having individual Electrical.Analog inductors.
So we can give up:

1. allowing for a m-phase m-wire system users to choose which of the m initial currents are set (one must be left unset, since it will be set by the software as the opposite of the sum of all the currents that are set). Therefore, I agree to your proposal of leaving unset the last m-th current in this case
2. allowing users to decide whether the initial values are all fixed or not: individual choice not possible).

So, in a three-phase system the user will be allowed to set a vector of 3 or two currents. In the first case it is expected that current can flow through neutral (i.e. we have a 3-phase, 4-wire system), and therefore for t=0 the three currents are independent states. In the second case, the code should automatically set the third current to the opposite of the sum of the two set currents.

Obviously the user can mistakenly fix m currents for a m-wire m-phase system (e.g. 3 currents for a three-wire three-phase system), resulting in an overdimensioned initial system of equations. This is what already occurs if the user implements the same three-phase system with Analog.Basic components.
I mean, I would leave as modeler responsibility (not a tool responsibility at the time of evaluating user input) to decide how many (m or m-1) inductor currents need to be initilalised, depending on the system architecture (whether there is the physical possibility of non-zero neutral current or not). In case of user mistake, tools will intervene at compiling time, finding that the initial system of equations is overdetermined.

To summarise. The GUI would propt the user for a vector of intial currents and a unique flag for these values being fixed=true or not.
The number of current values the tool is expected to receive (I mean, the size of the provided vector of initial currents) will be m or m-1. In case it is m-1 it will assume i[m]=sum(i[k], k in 1:m-1).

[AHaumer]

In MSL we try to keep the models as general as possible without restricting the freedom of usage.
I still doubt that we can cover all possible cases without restriction and without confusing the user:

• m wires, no neutral: We have to initialize m-1 currents
• m wires, separate neutral: We have to initialize m currents
• m+1 wires, the last one is the neutral: We have to initialize m currents

In the first case (m wires, no neutral) I wouldn't initialize one (may be the last) current to -sum(all other initial currents), this easily leads to numerical problems. We have to leave this up to the tool.

Specifying an array of initial currents i0[m-1] or i0[m] looks clumsy compared to the initialization menu presented automatically due to the alias variable.

We should also take care of the following facts:

• The user should be able to choose the index of the not initialized current.
• The user should be able to choose separately which currents are initialized fixed=true and which current fixed=false: There might be use cases where the user calculates the initial currents with some uncertainty.
• How to you obtain a fixed=false initialization?

I'm not sure whether we don't forget a special case which is not covered by the solution.
What's about polyphase inductors used as subcomponents in transformers, machines, lines, ....
So why not leave it to the user to initialize the currents with initial equations?
The user should know his system and therefore also know how to initialize the whole system.

[ceraolo]

In MSL we try to keep the models as general as possible without restricting the freedom of usage. I still doubt that we can cover all possible cases without restriction and without confusing the user:

I understand this. Two notes:

• the community of users has lived for many years without any possibility to initialize, i.e. the least "generality" possible. Only now an user (me) appeared which noted something lacking
• in the case of Polyphase library there still exist in MSL the option to resort to individual components from Analog.Basic.

So, any "restriction" in Polyphase is not restriction in general since we have individual components from Analog.Basic. Whenever Polyphase usage tends to become tricky, there is for the user this fallback option.

In reality, in the first version of my message I intended to propose a solution that allowed users to choose the wires to which to set initial values (the remaining to be computed by the tool). It was easy-peasy also from the GUI point of view.
Later I thought that it was overkill, for me.

This solution involved the user to input two arrays, one with the currents, the other with the indexes. the array would have m or m-1 elements: the tool will act correspondingly.
It was still user's responsibility to decide whether to select m-sized arrays or m-1.

My position is that there must be a balance between generality and ease of use. That's why I finally resorted to propose that the balance current be always the m-th.

But I'm not against the other way that I myself initially conceived.

[casella]

As a general comment, I think that for consistency reasons, the Polyphase components should be usable as much as possible in the same way as the the regular, single-phase components, that have been around for 20+ years without anybody complaining.

If I double-click on an instance of Modelica.Electrical.Analog.Basic.Inductor with any Modelica tool, I get a parameter dialog with one field for the L parameter and one field where I can change the start attribute from the default value of 0 and I can additional set the fixed attribute.

If I double-click on an instance of Modelica.Electrical.Polyphase.Basic.Inductor, I get fields to set the number of phases and the array of inductances of each phase, but no provisions for initialization. The model is implemented by connecting an array of regular inductors between the two ports, so setting these values manually in the source code is quite tricky, as you need to figure out the implementation first, and then to apply array (or each) modifiers to a subcomponent, e.g.:

Modelica.Electrical.Polyphase.Basic.Inductor myInductor1(inductor(i(each start = 1, each fixed = true)));
Modelica.Electrical.Polyphase.Basic.Inductor myInductor2(inductor(i(start = {1, 2, 3}, fixed = {true, true, false}));

This goes against the principle of encapsulation, I think one should be able to use the polyphase inductor without the need to understand how it is implemented. In any case, writing that code is tricky and unnecessarily unconfortable for beginners, that would just like to use the GUI without delving into the intricacies of Modelica syntax and lots of silly parentheses 😃.

So, I'd say that we need to provide some infrastructure that allows to set the start and fixed attribute of none, m-1, or m currents easily in the parameter input window of the polyphase inductor. Advanced users could also write initial equations (in that case the fixed attribute should be set to false) but we shouldn't force beginners to do that, if they simply want to set some initial value. Again, writing syntactically correct Modelica code in such cases involving arrays is not entirely trivial.

If we agree on this requirement, I see two ways of implementing it.

1. Using the GUI to set fixed/start attributes

This is the way that requires minimal intervention on the MSL source code. Inside Modelica.Electrical.Polyphase.Basic.Inductor we can define the following alias variable:

  Modelica.Units.SI.Current i[m](start = fill(0, m), fixed = fill({false, m}) = inductor.i;

The GUI will see this variable with start and fixed modifiers and automatically generate the fields in the parameter input window to change them, as it already happens with the single-phase inductor. This is maximally flexible, as the user can provide any combination of start values and decide which phases should be fixed and which should not. Last, but not least, if the default values are kept, then the behaviour is the same that we have now, so it would be backwards compatible.

If this feature is used, fixed = true attributes will generate the corresponding initial equations, while the start attributes set on the three-phase component modifier should have higher priority than the default bindings set in the underlying inductor[3] array, according to the rules of MLS Sec. 8.6.2, so they should be used as guess values in case one wants to write non-trivial initial equations (e.g. steady-state)

2. Definining parameters to set fixed/start attributes

Alternatively, we could define parameters in Modelica.Electrical.Polyphase.Basic.Inductor, such as i_start and i_fixed, then propagate them to the inductor array implementation, e.g.

  Modelica.Units.SI.Current i_start[m] = fill(0, m) annotation(group = "Initialization");
  Boolean i_fixed = fill(false, m) annotation(group = "Initialization");
  ...
  Modelica.Electrical.Analog.Basic.Inductor inductor[m](start = i_start, fixed = i_fixed, L = L);
  ...

In principle we should make the modifiers on the inductor array final, but this would break backwards compatibility if someone actually set the initial values by appling modifers to them, so I'd leave the as non-final.

Decision

I am personally in favour of the first solution, because it needs less code and is more consistent with the single-phase components. But I'd like to hear your opinion.

[AHaumer]

@casella you're right, we should go for your proposal 1. @christiankral what do you think?
Should I prepare a PR?

[christiankral]

Yes, I agree to apply proposal 1.

@AHaumer Please prepare a PR.

[AHaumer]

I'll try. @ceraolo keep in mind:
We have to be sure that - for an important application; inductor with following Y-connection and floating starpoint - we are able to initialize m-1 currents with fixed=true and the last one with fixed_fals.

[AHaumer]

Nice try ;-) but:

• OpenModelica 1.23.1 presents the initialization menu, but you choose the fixed-attribute for all currents together -> bad idea
• Dymola 2024x even doesn't present an initialization menu
  Try it yourself. Sorry, as long as the tool developers don't do their homework I'm not willing to invest time.
  I'm pretty sure other tools have similar drawbacks.
  PolyPhaseInductor.zip

[AHaumer]

Even another try with parameters for initialization:

• OpenModelica presents both the initialization parameters as well as the initialization menu - bad.
• Dymola 2024x presents the initialization parameters ok, but the fixed is really clumsy
  How do other simulators behave? No I'm not going to invest any further time.
  PolyPhaseInductor.zip

[casella]

@AHaumer we shouldn't design the MSL based on the currently implemented GUIs, but rather the other way round: GUIs should properly support user-friendly editing of the MSL Modelica code. Bear in mind that this is for MSL 4.2.0, so there will be time to implement that feature.

[casella]

@AHaumer I downloaded your first PolyPhaseInductor test package, but it doesn't seem to me to be fully implementing my proposal 1. I see the following code:

model Inductor "Ideal linear electrical inductors"
  extends Modelica.Electrical.Polyphase.Interfaces.TwoPlug(i(start=zeros(m)));
...

but it should be

model Inductor "Ideal linear electrical inductors"
  extends Modelica.Electrical.Polyphase.Interfaces.TwoPlug(i(start=zeros(m), fixed = fill(false, m)));
...

right?

[HansOlsson]

An alternative would be:
Modelica.Units.SI.Current i2[m](start=zeros(m)) = i annotation(Dialog(showStartAttribute=true));

(but hopefully with a better name). That should show up as a start-value. Or:

  Modelica.Units.SI.Current i2[m](start=zeros(m))  annotation(Dialog(showStartAttribute=true));
  extends Modelica.Electrical.Polyphase.Interfaces.TwoPlug(final i=i2);

[AHaumer]

@casella your proposal won't make a difference since fixed=false is the default.
@HansOlsson I like your proposal, The only drawback:
The fixed attribute is presented as a checkbox and you are not able to propagate a Boolean variable or formulate an expression in the diagram window. We have to be able to set m-1 currents fixed=true and 1 false.
Could we drop that bothersome checkbox behavior?
@HansOlsson would you please discuss possible solutions in the language group?
@casella That would be the correct way to influence tool developers.
Otherwise I could use special language constructs and hope that tool developers adopt these.
PolyPhaseInductor.zip

[casella]

@casella your proposal won't make a difference since fixed=false is the default.

It would. What OMEdit does is to automatically generate a GUI item to change start and fixed attributes if an explicit modifier exists, unless of course it is final. So the presence of an explicit modifier is taken as a hint that the user may want to change it also via the GUI. I understand Dymola does the same, not sure about other tools.

The showStartAttribute annotation was introduced a long time ago in Modelica 3.2, but as far as I understand it was never introduced in the Modelica.Electrical, probably because the existing heuristic of showing the start attribute if there was an explicit start attribute modifier just worked and nobody bothered.

Note that a start attribute modifier can be introduced upon inheritance, e.g.

ModelicaStandardLibrary/Modelica/Electrical/Analog/Basic/Inductor.mo

Lines 2 to 3 in 8e7876b

	model Inductor "Ideal linear electrical inductor"
	extends Interfaces.OnePort(i(start=0));

while an annotation cannot, which would force us to define a new variable i2 and then add final i = i2, as suggested above by @HansOlsson. No big deal, except that one may wonder why the current that I need to fix is called i2, perhaps it is the square of the current? I find it a bit confusing.

My point is: the start attribute heuristic has been in place for inductors since the dark ages. Why not just using the same pattern for polyphase component? That would be the most straighforward solution to me. It just requires to add modifiers to the extends clause:

model Inductor "Ideal linear electrical inductors"
  extends Modelica.Electrical.Polyphase.Interfaces.TwoPlug(i(start=zeros(m), fixed = fill(false, m)));
...

That is from a library point of view. Regarding tool support, I would say that tools should support both this construct and the showStartAttribute annotation also for arrays. Do we agree on that?

We could also decide to deprecate that practice and mandate the use of the showStartAttribute. To me, that won't be a particuarly good idea, because it would make a lot of existing library unusable (start attribute dialogs disappear), unless you add those attributes. It's ok to deprecate despicable practices, but this one doesn't seem despicable to me. To me, not bothering people with unnecessary non-backwards compatible changes of the language is a golden rule.

[AHaumer]

@casella i2 is just a not very descriptive name for the alias current, in my example i named it iL.

I have no objections against both solutions, either the annotation nor the pressure that all tools have to implement the behavior to present an initialization menu for an array variable if a vector of start values is provided,

The only impediment is the fact that all tools have to avoid presenting "fixed" as a checkbox, otherwise you can't provide fixed=true for m-1 currents and fixed=false for the last one which is necessary in the case of start connection with star-point not connected i.e. sum of all m currents = 0.
It is confusing if you can set the start values in the menu and the fixed attributes you have to set in text layer.
I won't accept that!

[casella]

It is confusing if you can set the start values in the menu and the fixed attributes you have to set in text layer.

Sure. What I mean is, I wont' implement a convoluted solution using separate boolean parameter arrays such as as fixed_start in the library, but rather rely on the GUIs to allow modifying arrays of start and fixed attributes in a nice way.

There is time until the release of 4.2.0 for tool vendors to adapt to this.

@HansOlsson, @adea31, @eshmoylova, @maltelenz, @gkurzbach do you agree?

[HansOlsson]

It is confusing if you can set the start values in the menu and the fixed attributes you have to set in text layer.

Sure. What I mean is, I wont' implement a convoluted solution using separate boolean parameter arrays such as as fixed_start in the library, but rather rely on the GUIs to allow modifying arrays of start and fixed attributes in a nice way.

There is time until the release of 4.2.0 for tool vendors to adapt to this.

@HansOlsson, @adea31, @eshmoylova, @maltelenz, @gkurzbach do you agree?

Yes. The model should be clear and the tools should adapt to that. Whether Dymola will do it for 4.2.0 release I cannot state at this time.

[maltelenz]

I have a hard time following all the rounds in this issue. Do I understand it right that the proposal is to use the case from inductor3 in the most recent test zip file?

  Modelica.Units.SI.Current iL[m](start=zeros(m), fixed = fill(false, m))=i "Inductor currents"
    annotation(Dialog(showStartAttribute=true));

For this case, System Modeler currently shows:

Where you get a nice array editor for the start:

And a slightly less nice expression editor for the fixed:

I'm not sure why we aren't showing the nicer array editor in this case, it seems like a tool issue.

If this is the proposed change, it seems fine.

[AHaumer]

Yes @maltelenz you are right we tend to implement this version.
The problem I see: At least Dymola and OM present a checkbox for the fixed attribute and it is cumbersome to propagate an array of Booleans (you have to switch to text mode, not very intuitive and confusing).



We have to be able to set the fixed attribute differently (not all array elements the same).

[maltelenz]

Thanks @AHaumer for the summary.

It seems you have buy-in from Dymola (@HansOlsson), OM (@casella) and System Modeler (me, and also already reasonably working, even if not perfect) for the tools to adapt to such a change in the library.

[christiankral]

model Inductor "Ideal linear electrical inductors"
  extends Modelica.Electrical.Polyphase.Interfaces.TwoPlug(i(start=zeros(m), fixed = fill(false, m)));
...

That is from a library point of view. Regarding tool support, I would say that tools should support both this construct and the showStartAttribute annotation also for arrays. Do we agree on that?

This is my preference, as we avoid to add an additional redundant variable, which is not needed from a modeling point of view. The tools shall be able to handle such a case.

[AHaumer]

We decided to give it a try: see #4488 for PolyPhase Capacitor and Inductor, tested in an example.
If this works well, the same style of initialization shall be implemented for PolyPhase.Basic.{Capacitor, Inductor, SaturatingInductor, MutualInductor, ZeroInductor, Transformer, VariableCapacitor, VariableInductor}, Modelica.Electrical.Machines., Modelica.Electrical.PowerConverters., Modelica.Magnetic.FundamentalWave.* but this seems to be a lot of work -> later.

[AHaumer]

#4488 is merged, but let's keep this discussion open since the initialization shall get implemented in other models in the same style:
PolyPhase.Basic.{SaturatingInductor, MutualInductor, ZeroInductor, Transformer, VariableCapacitor, VariableInductor}, Modelica.Electrical.Machines., Modelica.Electrical.PowerConverters., Modelica.Magnetic.FundamentalWave.*