Skip to content

feat: Convert the old LaTeX based User's Guide into Modelica documentation #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dietmarw merged 8 commits into from
Feb 16, 2026
Merged

feat: Convert the old LaTeX based User's Guide into Modelica documentation #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
fb8fc6d
Step 1: conversion
dietmarw Feb 11, 2026
c15f11a
Step 2: Update to current status
dietmarw Feb 11, 2026
f98d7c3
Step 3: Merged the converted documentation into the relevant classes
dietmarw Feb 13, 2026
18a16ed
Use upright font for derivative operator
dietmarw Feb 13, 2026
47526b8
White space clean up.
dietmarw Feb 13, 2026
bfcf0d3
Removed LaTeX sources for outdated UsersGuide_v1.0.0.pdf
dietmarw Feb 13, 2026
3eb3ad9
Fix header tag
dietmarw Feb 13, 2026
b3a9f76
It makes more sense to display the info layer
dietmarw Feb 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ simulator.log
**/*.bbl
**/*.blg
**/*.log
**/*.pdf
**/*.synctex.gz
**/*.toc

Expand Down
34 changes: 30 additions & 4 deletions OpenHPL/Controllers/Governor.mo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,10 +126,36 @@ equation
//else
// der(Y_gv) = u / T_g;
//end if;
annotation (
Documentation(info="<html>
<p>This is a simple model of the governor that controls the guide vane
opening in the turbine based on the reference power production.</p>
annotation (preferredView="info", Documentation(info="<html>
<h4>Governor</h4>
<p>
Here, a simple model of the governor that controls the guide vane opening in the turbine based on the reference power
production is described. The block diagram of this governor model is shown in the figure.
</p>

<p align=\"center\">
<img src=\"modelica://OpenHPL/Resources/Images/Governor.png\" alt=\"Governor block diagram\" width=\"600\"/>
</p>
<p><em>Figure: Block Diagram of the governor.</em></p>

<h5>Implementation</h5>
<p>
Using the model in the figure and the standard Modelica blocks, the governor model is encoded in our library as the
<em>Governor</em> unit. This unit has inputs as the reference power production and generator frequency that are implemented
with the standard Modelica <em>RealInput</em> connector. This <em>Governor</em> unit also uses the standard Modelica
<em>RealOutput</em> connectors in order to provide output information about the turbine guide vane opening.
</p>

<h5>Parameters</h5>
<p>
In the <em>Governor</em> unit (note: in the text it mentions <em>SynchGen</em> but this appears to be a typo in the
original document - should be <em>Governor</em>), the user can specify the various time constants of this model (see
figure): pilot servomotor time constant T<sub>p</sub>, primary servomotor integration time T<sub>g</sub>, and transient
droop time constant T<sub>r</sub>. The user should also provide the following parameters: droop value σ, transient droop δ,
and nominal values for the frequency and power generation. The information about the maximum, minimum, and initial guide
vane opening should also be specified.
</p>

<p>The model is taken from <a href=\"modelica://OpenHPL.UsersGuide.References\">[Sharefi2011]</a>.</p>
</html>"));
end Governor;
1 change: 0 additions & 1 deletion OpenHPL/Controllers/package.mo
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
within OpenHPL;
package Controllers "Collection of different controllers"
extends Modelica.Icons.Package;

extends Icons.Governor;

end Controllers;
14 changes: 5 additions & 9 deletions OpenHPL/ElectroMech/BaseClasses/BaseValve.mo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,28 +34,24 @@ equation
Vdot = mdot/data.rho;
dp*(C_v_*max(epsilon, u^alpha))^2 = Vdot*abs(Vdot) "Valve equation for pressure drop";
dp = i.p - o.p "Link the pressure drop to the ports";
annotation ( Documentation(info="<html>
annotation (preferredView="info", Documentation(info="<html>
<p>
This is a partial, simple model of hydraulic valve. &nbsp;</p><p>This model is based on the energy balance of a valve.
</p>
<ul>
<li>Mass flow is equal at innflow and outflow</li>
<li>Mass flow is equal at inflow and outflow</li>
<li>The head loss and pressure difference is proportional to square of velocity</li>
</ul>
<p>
Specifically:
</p>
<pre>
dp*f(opening)=v|v|
</pre>
<p>$$ \\Delta p \\cdot f(\\mathrm{opening}) = \\nu \\cdot | \\nu | $$</p>
<p>
The function f(opening) is expressed as:
</p>
<pre>
(C_v_*max(epsilon, u^alpha))^2
</pre>
<p>$$ f(\\mathrm{opening}) = \\left( C_\\mathrm{v} \\cdot \\mathrm{max}(\\epsilon, u^\\alpha)\\right)^2 $$</p>
<p>
When alpha is 1, this implies a linear relation between closing and head loss.
When \\(\\alpha\\) is 1, this implies a linear relation between closing and head loss.
</p>
<p>The valve capacity can either be specified
directly by the user by specifying <code>C_v</code> or it will be calculated from
Expand Down
49 changes: 40 additions & 9 deletions OpenHPL/ElectroMech/Generators/SimpleGen.mo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,51 @@ model SimpleGen "Model of a simple generator with mechanical connectors"
rotation=270,
origin={0,120})));

annotation (
annotation (preferredView="info",
Documentation(info= "<html>
<h4>Simple model of an ideal generator with friction.</h4>
<h4>Simple Generator Model</h4>
<p>Simple model of an ideal generator with friction based on angular momentum balance.</p>

<p>This model based on the angular momentum balance, which depends on the turbine shaft power,
the friction loss in the unit rotation and the power taken up by the generator.</p>
<p>
The generator can be loaded either:</p>
<h5>Energy Balance</h5>
<p>The kinetic energy stored in the rotating generator is \\(K_a = \\frac{1}{2}J_a\\omega_a^2\\),
where ω<sub>a</sub> is angular velocity and J<sub>a</sub> is moment of inertia.</p>

<p>From energy balance:</p>
<p>$$ \\frac{\\mathrm{d}K_a}{\\mathrm{d}t} = \\dot{W}_s - \\dot{W}_{f,a} - \\dot{W}_g $$</p>
<p>where:</p>
<ul>
<li>Ẇ<sub>s</sub> is turbine shaft power</li>
<li>Ẇ<sub>f,a</sub> is frictional power loss</li>
<li>Ẇ<sub>g</sub> is power taken by generator</li>
</ul>

<h5>Friction</h5>
<p>Frictional power loss (mainly from bearings):</p>
<p>$$ \\dot{W}_{f,a} = \\frac{1}{2}k_{f,b}\\omega_a^2 $$</p>
<p>where k<sub>f,b</sub> is the bearing friction factor.</p>

<h5>Electric Power</h5>
<p>Electric power available on grid:</p>
<p>$$ \\dot{W}_e = \\eta_e \\dot{W}_g $$</p>
<p>where η<sub>e</sub> is electrical efficiency.</p>

<h5>Loading Options</h5>
<p>The generator can be loaded either:</p>
<ul>
<li>via the mechanical shaft connector (e.g., using the
<a href=\"modelica://OpenHPL.ElectroMech.PowerSystem.Grid\">Grid</a> model).
The input <code>Pload</code> should be set to 0 in this case.</li>
<li>via the mechanical shaft connector (e.g., using the <a href=\"modelica://OpenHPL.ElectroMech.PowerSystem.Grid\">Grid</a> model).
Set <code>Pload</code> input to 0 in this case.</li>
<li>or via the input connector <code>Pload</code> specifying the connected electrical load.</li>
</ul>

<h5>Connectors</h5>
<ul>
<li>RealInput: grid power (<code>Pload</code>) and shaft power</li>
<li>RealOutput: angular velocity and frequency</li>
</ul>

<h5>Parameters</h5>
<p>User specifies: moment of inertia, electrical efficiency, bearing friction factor, number of poles, and initial angular velocity.</p>

<p align=\"center\">
<img src=\"modelica://OpenHPL/Resources/Images/simplegen.svg\">
</p>
Expand Down
74 changes: 69 additions & 5 deletions OpenHPL/ElectroMech/Generators/SynchGen.mo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,9 +108,73 @@ equation
der(w) = (Wdot_ts - Pe) / (J * w);
// - W_fa;
//
annotation (
Documentation(info= "<html><p>This is a model of the generator that is connected to the grid.
This model could give some transient results. However, it is better to use generator models from IPSL.</p>
<p>More info about this model can be found in <a href=\"modelica://OpenHPL.UsersGuide.References\">[Sharefi2011]</a>.</p>
</html>"));
annotation (preferredView="info",
Documentation(info= "<html>
<h4>Synchronous Generator Model</h4>
<p>Detailed synchronous generator model connected to the grid, based on d-q decomposition.</p>

<h5>Voltage-Current Relation</h5>
<p>$$ \\left[\\begin{matrix}R_a+R_e & x_q'+x_e\\\\ -x_d'-x_e & R_a+R_e\\end{matrix}\\right]\\left[\\begin{matrix}I_d \\\\ I_q\\end{matrix}\\right]= \\left[\\begin{matrix}E_d'+V_s\\sin\\delta_e \\\\ E_q'-V_s\\cos\\delta_e\\end{matrix}\\right] $$</p>
<p>where:</p>
<ul>
<li>\\(R_a\\) and \\(R_e\\) are phase winding and equivalent network resistances</li>
<li>\\(x_d\\), \\(x_q\\), \\(x_d'\\), \\(x_q'\\) are d-/q-axis normal and transient reactances</li>
<li>\\(x_e\\) is equivalent network reactance</li>
<li>\\(I_d\\), \\(I_q\\) are d-/q-axis currents</li>
<li>\\(E_d'\\), \\(E_q'\\) are d-/q-axis transient voltages</li>
<li>\\(V_s\\) is network RMS voltage</li>
<li>\\(\\delta_e\\) is phase shift angle</li>
</ul>

<h5>Phase Shift Angle Dynamics</h5>
<p>$$ \\frac{\\mathrm{d}\\delta_e}{\\mathrm{d}t} = (\\omega - \\omega_s)\\frac{n_p}{2} $$</p>
<p>where \\(n_p\\) is number of poles, \\(\\omega\\) and \\(\\omega_s\\) are generator and grid angular velocities.</p>

<h5>Swing Equation</h5>
<p>$$ \\frac{\\mathrm{d}\\omega}{\\mathrm{d}t}=\\frac{\\dot{W}_s-P_e}{J\\omega} $$</p>

<h5>Transient Operation</h5>
<p>$$
\\begin{array}{c}
T_{qo}'\\frac{\\mathrm{d}E_d'}{\\mathrm{d}t} =-E_d' + (x_q' - x_q)I_q \\\\
T_{do}'\\frac{\\mathrm{d}E_q'}{\\mathrm{d}t} = -E_q' + (x_d - x_d')I_d + E_f
\\end{array}
$$</p>
<p>where \\(T_{do}'\\) and \\(T_{qo}'\\) are d-/q-axis transient open-circuit time constants.</p>

<h5>Excitation System</h5>
<p>Field voltage dynamics:</p>
<p>$$ \\frac{\\mathrm{d}E_f}{\\mathrm{d}t} = \\frac{-E_f + K_E\\left(V_{tr}-V_t-V_{stab}\\right)}{T_E} $$</p>
<p>where \\(K_E\\) is excitation system gain, \\(T_E\\) is excitation time constant, \\(V_{tr}\\) is voltage reference set point,
and \\(V_t = \\sqrt{\\left(E_d'-R_aI_d-x_q'I_q\\right)^2+\\left(E_q'-R_aI_q+x_d'I_d\\right)^2}\\) is terminal voltage.</p>

<h5>Stabilization</h5>
<p>$$ \\frac{\\mathrm{d}V_{stab}}{\\mathrm{d}t} = \\frac{-V_{stab} + K_F\\frac{\\mathrm{d}E_f}{\\mathrm{d}t}}{T_{FE}} $$</p>
<p>where \\(K_F\\) is stabilizer gain and \\(T_{FE}\\) is stabilizer time constant.</p>

<h5>Output Power</h5>
<p>Active and reactive power:</p>
<p>$$
\\begin{array}{c}
P_e = 3\\left(E_d'I_d+E_q'I_q\\right)\\\\
Q_e = \\sqrt{9V_t^2I_t^2-P_e^2}
\\end{array}
$$</p>
<p>where \\(I_t=\\sqrt{I_d^2+I_q^2}\\) is terminate current.</p>

<h5>Connectors</h5>
<ul>
<li>RealInput: turbine shaft power</li>
<li>RealOutput: angular velocity and frequency</li>
</ul>

<h5>Parameters</h5>
<p>User specifies: nominal active/reactive powers, phase winding resistance, number of poles, network parameters
(equivalent resistance/reactance, RMS voltage, grid angular velocity), d-/q-axis reactances and time constants,
field voltage limits, excitation/stabilizer gains and time constants, moment of inertia, friction factor, and
initialization options.</p>

<p><em>Note: For more advanced modeling, consider using generator models from <a href=\"modelica://OpenIPSL\">OpenIPSL</a>.</em></p>
<p>More details in <a href=\"modelica://OpenHPL.UsersGuide.References\">[Sharefi2011]</a>.</p>
</html>"));
end SynchGen;
2 changes: 1 addition & 1 deletion OpenHPL/ElectroMech/PowerSystem/Grid.mo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ equation
connect(product.y, dP2.u1) annotation (Line(points={{-13.5,67},{-8,67},{-8,33.6},{-12.8,33.6}}, color={0,0,127}));
connect(toHz.u, w_m2pu.y) annotation (Line(points={{5.2,-50},{84,-50},{84,-40},{78.6,-40}}, color={0,0,127}));
connect(toHz.y, dF.u1) annotation (Line(points={{-8.6,-50},{-22,-50}}, color={0,0,127}));
annotation (
annotation (preferredView="info",
Documentation(info="<html>
<h4>Primary control</h4>
<h5>Network Power-Frequency Characteristic</h5>
Expand Down
72 changes: 51 additions & 21 deletions OpenHPL/ElectroMech/Turbines/Francis.mo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,36 +212,66 @@ equation
mdot=i.mdot;

connect(p_out, P_out) annotation (Line(points={{40,90},{40,110}}, color={0,0,127}));
annotation (
annotation (preferredView="info",
Documentation(info="<html>
<p>
This is the Francis turbine model that gives possibilities for proper modelling of the Francis turbine.
</p>
<p>The mechanistic model is based on Euler equations for the Francis turbine.
Besides hydraulic input and output, there are input as the control signal for the valve opening
and also output as the turbine shaft power and input as angular velocity.
</p>
<h4>Francis Turbine Model</h4>

<p>This is the Francis turbine model that gives possibilities for proper modelling of the Francis turbine.
The mechanistic model is based on Euler equations for the Francis turbine.</p>

<p>Besides hydraulic input and output, there are input as the control signal for the valve opening
and also output as the turbine shaft power and input as angular velocity.</p>

<p align=\"center\">
<img src=\"modelica://OpenHPL/Resources/Images/turbinefrancis.svg\">
</p>
<p><em>Figure: Key quantities in the Francis turbine model showing inlet (1) and outlet (2) sections.</em></p>

<h5>Euler Turbine Equations</h5>

<p>The shaft power produced by the turbine is given by:</p>
<p>$$ \\dot{W}_s = \\dot{m}\\omega \\left(R_1\\frac{\\dot{V}}{A_1}\\cot{\\alpha_1} - R_2\\left(\\omega R_2 + \\frac{\\dot{V}}{A_2}\\cot{\\beta_2}\\right)\\right) $$</p>

<p>where ṁ and V̇ are mass and volumetric flow rates, ω is angular velocity, R<sub>1</sub> and R<sub>2</sub>
are inlet and outlet radii, A<sub>1</sub> and A<sub>2</sub> are cross-sectional areas, α<sub>1</sub> is
inlet guide vane angle, and β<sub>2</sub> is outlet blade angle.</p>

<h5>Total Work and Efficiency</h5>

<p>The total work rate is:</p>
<p>$$ \\dot{W}_t = \\dot{W}_s + \\dot{W}_{ft} + \\Delta p_v \\dot{V} $$</p>
<p>where Ẇ<sub>ft</sub> represents various friction losses (shock, whirl, wall friction),
and Δp<sub>v</sub>V̇ accounts for guide vane pressure drop. Turbine efficiency \\(\\eta = \\dot{W}_s / \\dot{W}_t\\).</p>

<h5>Turbine Design Algorithm</h5>

<p>There is also available the runner design algorithm that can define all geometrical
parameters based on the nominal parameters.</p><p>The turbine losses coefficients
(<code>k_ft1</code>, <code>k_ft2</code>, <code>k_ft3</code>) can be also defined automatically.
However, if some dynamic data from real turbine is available it is better to tune
these parameters a bit more and use the defined values as a starting point.
</p>
<p>A model for servo that that runs the guide vane opening is also available.
Furthermore it is possible to automatically generate all need parameters for the servo,
or simply specify them.
</p>
<p>
This mechanistic turbine model does not work really well for low loads (&lt;10% guide vane opening).
parameters based on the nominal parameters (net head, flow rate, power, speed).
The algorithm determines: outlet blade angle β<sub>2</sub>, runner radii R<sub>1</sub> and R<sub>2</sub>,
runner width w<sub>1</sub>, and inlet blade angle β<sub>1</sub>.</p>

<p>The turbine losses coefficients (<code>k_ft1</code>, <code>k_ft2</code>, <code>k_ft3</code>) can be also
defined automatically. However, if some dynamic data from real turbine is available it is better to tune
these parameters a bit more and use the defined values as a starting point.</p>

<h5>Guide Vane Actuation</h5>

<p>A model for servo that runs the guide vane opening is also available. A guide vane opening model relates
actuator position Y to guide vane angle α<sub>1</sub> through geometric relationships. Furthermore it is
possible to automatically generate all needed parameters for the servo, or simply specify them.</p>

<h5>Low Load Performance</h5>

<p>This mechanistic turbine model does not work really well for low loads (&lt;10% guide vane opening).
However there is parameters that could be tuned for low load regimes.
These are <code>u_min</code> and <code>k_ft4</code>.</p>

<h5>More Information</h5>

<p>More info about the mechanistic turbine model can be found in:
<a href=\"modelica://OpenHPL.UsersGuide.References\">[Vytvytskyi2018]</a> and about
the servo (also turbine model) in:
<a href=\"modelica://OpenHPL.UsersGuide.References\">[Vytvytskyi2018]</a> and
<a href=\"modelica://OpenHPL.UsersGuide.References\">[Vytvytskyi2019]</a>.
Additional details about the servo (and turbine model) are in:
<a href=\"modelica://OpenHPL/Resources/Documents/Turbines_model.pdf\">Resources/Documents/Turbines_model.pdf</a>.</p>
</html>"));
end Francis;
55 changes: 45 additions & 10 deletions OpenHPL/ElectroMech/Turbines/Pelton.mo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,18 +56,53 @@ equation
mdot=i.mdot;

connect(p_out, P_out) annotation (Line(points={{40,90},{40,110}}, color={0,0,127}));
annotation (
annotation (preferredView="info",
Documentation(info="<html>
<p>This is a model of the Pelton turbine.
This model is based on the Euler turbine equation.
</p>
<p>
<em>The model has not been tested.</em></p>
<h4>Pelton Turbine Model</h4>
<p>Mechanistic Pelton turbine model based on the Euler turbine equation and impulse turbine principles.</p>

<p align=\"center\">
<img src=\"modelica://OpenHPL/Resources/Images/turbinepelton.svg\">
</p>
<p>More info about the model can be found in:
<a href=\"modelica://OpenHPL/Resources/Documents/Turbines_model.pdf\">Resources/Documents/Turbines_model.pdf</a>
<img src=\"modelica://OpenHPL/Resources/Images/turbinepelton.svg\" alt=\"Pelton turbine\" width=\"600\"/>
</p>
<p><em>Figure: Key concepts of the Pelton turbine.</em></p>

<h5>Shaft Power</h5>
<p>The shaft power \\(\\dot{W}_s\\) produced in the Pelton turbine is:</p>
<p>$$ \\dot{W}_s=\\dot{m}v_R\\left[\\delta(u_\\delta)\\cdot v_1-v_R\\right]\\left(1-k\\cos\\beta\\right) $$</p>
<p>where:</p>
<ul>
<li>\\(\\dot{m}\\) is the mass flow rate through the turbine</li>
<li>\\(v_R = \\omega R\\) is the reference velocity (\\(R\\) = radius of rotor where flow hits the bucket, \\(\\omega\\) = angular velocity constrained by grid frequency)</li>
<li>\\(v_1=\\frac{\\dot{V}}{A_1}\\) is water velocity at position \"1\" (end of nozzle), with \\(\\dot{V}\\) = volumetric flow rate and \\(A_1\\) = cross-sectional area</li>
<li>\\(\\beta\\) is the reflection angle (typically \\(\\beta= 165^{\\circ}\\))</li>
<li>\\(k<1\\) is a friction factor (typically \\(k\\in[0.8, 0.9]\\))</li>
<li>\\(\\delta(u_\\delta)\\) represents deflector mechanism to reduce velocity and avoid over-speed</li>
</ul>

<h5>Total Work and Friction Losses</h5>
<p>Total work rate removed through the turbine:</p>
<p>$$ {\\dot{W}_t} = {\\dot{W}_s+\\dot{W}_{ft}} $$</p>
<p>Friction losses:</p>
<p>$$ \\dot{W}_{ft}=K\\left(1-k\\cos\\beta\\right)\\dot{m}v_R^2 $$</p>
<p>with friction coefficient \\(K=0.25\\).</p>

<h5>Nozzle Pressure Drop</h5>
<p>Pressure drop across the nozzle (positions \"0\" and \"1\"):</p>
<p>$$ \\Delta p_n=\\frac{1}{2}\\rho\\dot{V}\\left[\\dot{V}\\left(\\frac{1}{A_1^2(Y)}-\\frac{1}{A_0^2}\\right)+k_f\\right] $$</p>
<p>where \\(A_0\\) is cross-sectional area at nozzle beginning, \\(A_1(Y)\\) is area at nozzle end (function of needle position Y),
and \\(k_f\\) is the nozzle friction loss coefficient.</p>

<h5>Connectors</h5>
<ul>
<li><a href=\"modelica://OpenHPL.Interfaces.TurbineContacts\">TurbineContacts</a> for connection to waterway and electro-mechanical units</li>
<li>RealInput connector for angular velocity (typically from generator)</li>
</ul>

<h5>Parameters</h5>
<p>User specifies: turbine runner radius, nozzle input diameter, runner bucket angle, friction factors and coefficients,
deflector mechanism coefficient.</p>

<p><em>Note: This model has not been tested.</em></p>
<p>More info in: <a href=\"modelica://OpenHPL/Resources/Documents/Turbines_model.pdf\">Resources/Documents/Turbines_model.pdf</a></p>
</html>"));
end Pelton;
Loading