[issue-230] Adding saturation power in the NTMS IDS

[imbeauf]

Closes #230

---

📚 Documentation preview 📚: https://imas-data-dictionary--231.org.readthedocs.build/en/231/

[github-actions]

Diff of generated Data Dictionary XML file

[imbeauf]

@aksinghh , @simpla-fusion , @yegakjh , @qsthayashi , @SimonPinches could you review this PR please ?

[imbeauf]

@yegakjh , @SimonPinches , could you review this PR, please ?

[SimonPinches]

Definitions need improving.

[SimonPinches]

This sounds a bit too vague to me. Stabilizing a mode could be interpretated as stopping it growing (growthrate --> 0) which is not the same as removing it by replacing the missing current inside the island. If it's really a removal of the island that's meant here then I would expect this to be a definition of the amount of current that needs to be driven inside the island to stabilise it, e.g. with ECCD.

[MireilleSchneider]

I agree that the definition was not explicit enough, especially because the stabilisation power is defined wrt to a specific criteria, so we need, in addition, another placeholder for this criteria. In our simulations, we have a multiplicative safety margin applied to the linear interpolation power evaluated by the NTM model, i.e. we define a factor >1 which means that we ask for more than what is needed for marginal stabilization, in order to actually suppress the island. I would suggest to add suppression_factor next to power_saturation, and I would rename power_staturation. My proposal:

power_stabilization_request = requested power for stabilization of this tearing mode, computed from the modified Rutherford equation. This value represents the instantaneous power requirement to drive sufficient localized current at the rational surface to suppress island growth or maintain steady-state width. This quantity serves as the setpoint input for real-time EC power and mirror steering controllers in NTM stabilization feedback loops.

power_request_safety_margin = multiplicative safety margin applied to the theoretically-calculated stabilization power requirement for this mode. Typical values range from 1.0 (no margin) to 1.5 (50% margin). Values > 1.0 request additional power beyond the physics-model minimum to ensure robust stabilization under uncertain conditions.

[imbeauf]

Ok, I implement your two new definitions in the next commit. I have just reworked the signal names to limit the number of suffixes.

[SimonPinches]

This still doesn't quite make sense to me. The modified Rutherford equation describes the evolution of the island width, W. We can define the condition for stabilisation, dW/dT <= 0 which translates to deltaprime_boostrap <= detalprime_ECCD. But the ECCD term depends on the current density driven, not directly the power. Converting to power requires current drive efficiency, deposition width, alignment with O-point, modulation effects, etc. If we just store power, how will we know what was assumed for all these things, or even which launcher this is applicable for.

[MireilleSchneider]

If we specify the criteria chosen for stabilization power, then we know what was assume for the power needed to stabilize the island. The code is able to give the stabilization power, I don't plan to use the generated current drive instead, just for the pleasure of it, especially because the controller needs the stabilization power, not the ECCD, this is not justified to ask for the ECCD to be provided instead, such that the needed power to stabilize power is calculated by an extra code outside the NTM model. If NTM models are able to deliver the stabilization power, then the associated quantity should be in the ntms IDS. If you disagree with this variable to be added, we will end up with a workflow where I continue to use the wrong placeholder for the power (right now I use 'phase'). And ultimately, I won't use IMAS anymore if I am not able to get a structure compliant with the needs of the codes and workflows. And if we need to argue that much for the addition of a new variable, this is not efficient for a smooth evolution of the Data Dictionary, and next time I will think twice before asking, but I want to work in a clean way, and to use the right placeholder for the stabilization power.

[olivhoenen]

I understand power_stabilitzation as being an output from the NTM model, but I do not get the need for power_stabilitzation_margin: if the model wants a margin, it can apply this factor directly in the power_stabilitzation. I'll approve this PR but we need to remove this margin field.