root/branches/maintenance/2.2.2/Modelica/Media/package.mo

Revision 1114, 325.6 kB (checked in by otter, 7 months ago)

Media.Interfaces.PartialSimpleMedium: Missing functions added (pressure, temperature, density, specificEnthalpy)
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1within Modelica;
2package Media "Library of media property models"
3extends Modelica.Icons.Library;
4import SI = Modelica.SIunits;
5
6
7annotation (
8  version="1.0",
9  versionDate="2005-03-01",
10  preferedView="info",
11  Documentation(info="<HTML>
12<p>
13This library contains <a href=\"Modelica://Modelica.Media.Interfaces\">interface</a> 
14definitions for media and the following <b>property</b> models for
15single and multiple substance fluids with one and multiple phases:
16</p>
17<ul>
18<li> <a href=\"Modelica://Modelica.Media.IdealGases\">Ideal gases:</a><br>
19     1241 high precision gas models based on the
20     NASA Glenn coefficients, plus ideal gas mixture models based
21     on the same data.</li>
22<li> <a href=\"Modelica://Modelica.Media.Water\">Water models:</a><br>
23     ConstantPropertyLiquidWater, WaterIF97 (high precision
24     water model according to the IAPWS/IF97 standard)</li>
25<li> <a href=\"Modelica://Modelica.Media.Air\">Air models:</a><br>
26     SimpleAir, DryAirNasa, and MoistAir</li>
27<li> <a href=\"Modelica://Modelica.Media.Incompressible\">
28     Incompressible media:</a><br>
29     TableBased incompressible fluid models (properties are defined by tables rho(T),
30     HeatCapacity_cp(T), etc.)</li>
31<li> <a href=\"Modelica://Modelica.Media.CompressibleLiquids\">
32     Compressible liquids:</a><br> 
33     Simple liquid models with linear compressibility</li>
34</ul>
35<p>
36The following parts are useful, when newly starting with this library:
37<ul>
38<li> <a href=\"Modelica://Modelica.Media.UsersGuide\">Modelica.Media.UsersGuide</a>.</li>
39<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage\">Modelica.Media.UsersGuide.MediumUsage</a> 
40     describes how to use a medium model in a component model.</li>
41<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumDefinition\">
42     Modelica.Media.UsersGuide.MediumDefinition</a> 
43     describes how a new fluid medium model has to be implemented.</li>
44<li> <a href=\"Modelica://Modelica.Media.UsersGuide.ReleaseNotes\">Modelica.Media.UsersGuide.ReleaseNotes</a>
45     summarizes the changes of the library releases.</li>
46<li> <a href=\"Modelica://Modelica.Media.Examples\">Modelica.Media.Examples</a>
47     contains examples that demonstrate the usage of this library.</li>
48</ul>
49<p>
50Copyright &copy; 1998-2007, Modelica Association.
51</p>
52<p>
53<i>This Modelica package is <b>free</b> software; it can be redistributed and/or modified
54under the terms of the <b>Modelica license</b>, see the license conditions
55and the accompanying <b>disclaimer</b> 
56<a href=\"Modelica://Modelica.UsersGuide.ModelicaLicense\">here</a>.</i>
57</p><br>
58</HTML>"),
59  conversion(from(version="0.795", script=
60          "../ConvertFromModelica.Media_0.795.mos")));
61
62
63package UsersGuide "User's Guide of Media Library" 
64 
65  annotation (DocumentationClass=true, Documentation(info="<HTML>
66<p>
67Library <b>Modelica.Media</b> is a <b>free</b> Modelica package providing
68a standardized interface to fluid media models and specific
69media models based on this interface.
70A fluid medium model defines <b>algebraic</b> equations
71for the intensive thermodynamic variables used in the <b>mass</b>
72and <b>energy</b> balance of component models. Optionally, additional
73medium properties can be computed such as dynamic viscosity or thermal
74conductivity. Medium models are defined for <b>single</b> and
75<b>multiple substance</b> fluids with <b>one</b> and
76<b>multiple phases</b>.
77</p>
78<p>
79A large part of the library provides specific medium models
80that can be directly utilized. This library can be used in
81all types of Modelica fluid libraries that may have different connectors
82and design philosophies. It is particularily utilized
83in the Modelica_Fluid library (the Modelica_Fluid library is currently
84under development to provide 1D thermo-fluid flow components for
85single and multiple substance flow with one and multiple phases).
86The Modelica.Media library has the following
87main features:
88</p>
89<ul>
90<li> Balance equations and media model equations
91     are decoupled.
92     This means that the used medium model does usually not have an
93     influence on how the balance equations are formulated.
94     For example, the same balance equations are used for media
95     that use pressure and temperature, or pressure and specific
96     enthalpy as independent variables, as well as for
97     incompressible and compressible media models.
98     A Modelica tool will have enough information to
99     generate as efficient code as a traditional
100     (coupled) definition. This feature is described in more
101     detail in section
102     <a href=\"Modelica://Modelica.Media.UsersGuide.MediumDefinition.StaticStateSelection\">Static State Selection</a>.</li>
103<li> Optional variables, such as dynamic viscosity, are only computed if
104     needed in the corresponding component.</li>
105<li> The independent variables of a medium model do not
106     influence the definition of a fluid connector port.
107     Especially, the media models are implemented in such a way
108     that a connector may have the minimum number of independent
109     medium variables in a connector and still get the same
110     efficiency as if all medium variables are passed by the
111     connector from one component to the next one (the latter
112     approach has the restriction that a fluid port can only
113     connect two components and not more). Note, the Modelica_Fluid
114     library uses the first approach, i.e., having a set of
115     independent medium variables in a connector.</li>
116<li> The medium models are implemented with regards to
117     efficient dynamic simulation. For example, two phase
118     medium models trigger state events at phase boundaries
119     (because the medium variables are not differentiable
120     at this point).</li>
121</ul>
122<p>
123This User's Guide has the following main parts:
124</p>
125<ul>
126<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage\">Medium usage</a> 
127     describes how to use a medium model from
128     this library in a component model.</li>
129<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumDefinition\">Medium definition</a> 
130     describes how a new fluid medium
131     model has to be implemented.</li>
132<li> <a href=\"Modelica://Modelica.Media.UsersGuide.ReleaseNotes\">ReleaseNotes</a>
133     summarizes the changes of the library releases.</li>
134<li><a href=\"Modelica://Modelica.Media.UsersGuide.Contact\">Contact</a> 
135    provides information about the authors of the library as well as
136    acknowledgements.</li>
137</ul>
138</HTML>"));
139 
140  package MediumUsage "Medium usage" 
141   
142    annotation (DocumentationClass=true, Documentation(info="<HTML>
143<p>
144Content:
145</p>
146<ol>
147<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage.BasicUsage\">
148      Basic usage of medium model</a></li>
149<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage.BalanceVolume\">
150      Medium model for a balance volume</a></li>
151<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage.ShortPipe\">
152      Medium model for a pressure loss</a></li>
153<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage.OptionalProperties\">
154     Optional medium properties</a></li>
155<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage.Constants\">
156     Constants provided by medium model</a></li>
157<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage.TwoPhase\">
158     Two-phase media</a></li>
159<li> <a href=\"Modelica://Modelica.Media.UsersGuide.MediumUsage.Initialization\">
160     Initialization</a></li>
161</ol>
162 
163<p>
164A good demonstration how to use the media from Modelica.Media is
165given in package Modelica.Media.Examples.Tests. Under
166<a href=\"Modelica://Modelica.Media.Examples.Tests.Components\">
167Tests.Components</a> the most basic components of a Fluid library
168are defined. Under Tests.MediaTestModels these basic components are used to test
169all media models with some very simple piping networks.
170</p>
171 
172</HTML>"));
173   
174    class BasicUsage "Basic usage" 
175     
176      annotation (Documentation(info="<HTML>
177<h4>Basic usage of medium model</h4>
178<p>
179Media models in Modelica.Media are provided by packages, inheriting from the
180partial package Modelica.Media.Interfaces.PartialMedium. Every package defines:
181<ul>
182<li> Medium <b>constants</b> (such as the number of chemical substances,
183     molecular data, critical properties, etc.).
184<li> A BaseProperties <b>model</b>, to compute the basic thermodynamic
185     properties of the fluid;
186<li> <b>setState_XXX</b> functions to compute the thermodynamic state record from
187     different input arguments (such as density, temperature, and composition which
188     would be setState_dTX);
189<li> <b>Functions</b> to compute additional properties (such as saturation
190     properties, viscosity, thermal conductivity, etc.).
191</ul>
192There are - as stated above - two different basic ways of using the Media library which
193will be described in more details in the following section. One way is to use the model BaseProperties.
194Every instance of BaseProperties for any medium model provides <b>3+nXi
195equations</b> for the following <b>5+nXi variables</b> that are declared in
196the medium model (nXi is the number of independent mass fractions, see
197explanation below):
198</p>
199<table border=1 cellspacing=0 cellpadding=2>
200  <tr><td valign=\"top\"><b>Variable</b></td>
201      <td valign=\"top\"><b>Unit</b></td>
202      <td valign=\"top\"><b>Description</b></td></tr>
203  <tr><td valign=\"top\">T</td>
204      <td valign=\"top\">K</td>
205      <td valign=\"top\">temperature</td></tr>
206  <tr><td valign=\"top\">p</td>
207      <td valign=\"top\">Pa</td>
208      <td valign=\"top\">absolute pressure</td></tr>
209  <tr><td valign=\"top\">d</td>
210      <td valign=\"top\">kg/m^3</td>
211      <td valign=\"top\">density</td></tr>
212  <tr><td valign=\"top\">u</td>
213      <td valign=\"top\">J/kg</td>
214      <td valign=\"top\">specific internal energy</td></tr>
215  <tr><td valign=\"top\">h</td>
216      <td valign=\"top\">J/kg</td>
217      <td valign=\"top\">specific enthalpy (h = u + p/d)</td></tr>
218  <tr><td valign=\"top\">Xi[nXi]</td>
219      <td valign=\"top\">kg/kg</td>
220      <td valign=\"top\">independent mass fractions m_i/m</td></tr>
221  <tr><td valign=\"top\">X[nX]</td>
222      <td valign=\"top\">kg/kg</td>
223      <td valign=\"top\">All mass fractions m_i/m. X is defined in BaseProperties by:<br>
224          X = <b>if</b> reducedX <b>then</b> vector([Xi; 1-<b>sum</b>(Xi)])
225          <b>else</b> Xi </td></tr>
226</table>
227<p>
228<b>Two</b> variables out of p, d, h, or u, as well as the
229<b>mass fractions</b> Xi are the <b>independent</b> variables and the
230medium model basically provides equations to compute
231the remaining variables, including the full mass fraction vector X
232(more details to Xi and X are given further below).
233</p>
234<p>
235In a component, the most basic usage of a medium model is as follows
236</p>
237<pre>
238  <b>model</b> Pump
239    <b>replaceable package</b> Medium = Modelica.Media.Interfaces.PartialMedium
240                         \"Medium model\" <b>annotation</b> (choicesAllMatching = <b>true</b>);
241    Medium.BaseProperties medium_a \"Medium properties at location a (e.g. port_a)\";
242    // Use medium variables (medium_a.p, medium_a.T, medium_a.h, ...)
243     ...
244  <b>end</b> Pump;
245</pre>
246<p>
247The second way is to use the setState_XXX functions to compute the thermodynamic state
248record from which all other thermodynamic state variables can be computed (see
249<a href=\"Modelica://Modelica.Media.UsersGuide.MediumDefinition.BasicDefinition\">
250Basic definition of medium</a> for further details on ThermodynamicState). The setState_XXX functions
251accept either X or Xi (see explanation below) and will decide internally which of these two compositions
252is provided by the user. The four fundamental setState_XXX functions are provided in PartialMedium
253</p>
254<table border=1 cellspacing=0 cellpadding=2>
255  <tr><td valign=\"top\"><b>Function</b></td>
256      <td valign=\"top\"><b>Description</b></td>
257      <td valign=\"top\"><b>Short-form for<br>single component medium</b></td></tr>
258  <tr><td valign=\"top\">setState_dTX</td>
259      <td valign=\"top\">computes ThermodynamicState from density, temperature, and composition X or Xi</td>
260      <td valign=\"top\">setState_dT</td></tr>
261  <tr><td valign=\"top\">setState_phX</td>
262      <td valign=\"top\">computes ThermodynamicState from pressure, specific enthalpy, and composition X or Xi</td>
263      <td valign=\"top\">setState_ph</td></tr>
264  <tr><td valign=\"top\">setState_psX</td>
265      <td valign=\"top\">computes ThermodynamicState from pressure, specific entropy, and composition X or Xi</td>
266      <td valign=\"top\">setState_ps</td></tr>
267  <tr><td valign=\"top\">setState_pTX</td>
268      <td valign=\"top\">computes ThermodynamicState from pressure, temperature, and composition X or Xi</td>
269      <td valign=\"top\">setState_pT</td></tr>
270</table> 
271<p>
272The simple example that explained the basic usage of BaseProperties would then become
273<pre>
274  <b>model</b> Pump
275    <b>replaceable package</b> Medium = Modelica.Media.Interfaces.PartialMedium
276                         \"Medium model\" <b>annotation</b> (choicesAllMatching = <b>true</b>);
277    Medium.ThermodynamicState state_a \"Thermodynamic state record at location a (e.g. port_a)\";
278    // Compute medium variables from thermodynamic state record (pressure(state_a), temperature(state_a),
279    // specificEnthalpy(state_a), ...)
280    ...
281  <b>end</b> Pump;
282</pre>
283<p>
284All media models are directly or indirectly a subpackage of package
285Modelica.Media.Interfaces.PartialMedium. Therefore,
286a medium model in a component should inherit from this
287partial package. Via the annotation \"choicesAllMatching = true\" it
288is defined that the tool should display a selection box with
289all loaded packages that inherit from PartialMedium. An example
290is given in the next figure:
291</p>
292<IMG SRC=\"../Images/Media/UsersGuide/mediumMenu.png\" ALT=\"medium selection menu\">
293<p>
294A selected medium model leads, e.g., to the following equation:
295</p>
296<pre>
297  Pump pump(<b>redeclare package</b> Medium = Modelica.Media.Water.SimpleLiquidWater);
298</pre>
299<p>
300Usually, a medium model is associated with the variables of a
301fluid connector. Therefore, equations have to be defined in a model
302that relate the variables in the connector with the variables
303in the medium model:
304</p>
305<pre>
306  <b>model</b> Pump
307    <b>replaceable package</b> Medium = Modelica.Media.Interfaces.PartialMedium
308                         \"Medium model\" <b>annotation</b> (choicesAllMatching = <b>true</b>);
309    Medium.BaseProperties medium_a \"Medium properties of port_a\";
310    // definition of the fluid port port_a
311     ...
312  <b>equation</b>
313    medium.p = port_a.p;
314    medium.h = port_a.h;
315    medium.Xi = port_a.Xi;
316     ...
317  <b>end</b> Pump;
318</pre>
319in the case of using BaseProperties or
320<pre>
321  <b>model</b> Pump
322    <b>replaceable package</b> Medium = Modelica.Media.Interfaces.PartialMedium
323                         \"Medium model\" <b>annotation</b> (choicesAllMatching = <b>true</b>);
324    Medium.ThermodynamicState state_a \"Thermodynamic state record of medium at port_a\";
325    // definition of the fluid port port_a
326     ...
327  <b>equation</b>
328    state_a = Medium.setState_phX(port_a.p, port_a.h, port_a.Xi) // if port_a contains the variables
329                                                                 // p, h, and Xi
330     ...
331  <b>end</b> Pump;
332</pre>
333in the case of using ThermodynamicState.
334<p>
335If a component model shall treat both single and multiple
336substance fluids, equations for the mass fractions have to be
337present (above: medium.Xi = port_a.Xi) in the model. According
338to the Modelica semantics, the equations of the mass fractions
339are ignored, if the dimension of Xi is zero, i.e., for a single-component
340medium. Note, by specific techniques sketched in section
341\"Medium definition\", the independent variables in the medium model
342need not to be the same as the variables in the connector and still
343get the same efficiency, as if the same variables would be used.
344</p>
345 
346<p>
347If a fluid consists of a single
348substance, <b>nXi = 0</b> and the vector of mass fractions Xi is not
349present. If a fluid consists of nS substances,
350the medium model may define the number of independent
351mass fractions <b>nXi</b> to be <b>nS</b>, <b>nS-1</b>, or zero.
352In all cases, balance equations for nXi substances have to be
353given in the corresponding component (see discussion below).
354Note, that if nXi = nS, the constraint \"sum(Xi)=1\" between the mass
355fractions is <b>not</b> present in the model; in that case, it is necessary to
356provide consistent start values for Xi such that sum(Xi) = 1.
357</p>
358 
359<p>
360The reason for this definition of Xi is that a fluid component library
361can be implemented by using only the independent mass fractions Xi and
362then via the medium it is defined how Xi is interpreted:
363</p>
364 
365<ul>
366<li> If Xi = nS, then the constraint equation sum(X) = 1 is neglected
367     during simulation. By making sure that the initial conditions of X
368     fulfill this constraint, it can usually be guaranteed that small
369     errors in sum(X) = 1 remain small although this constraint equation is
370     not explicitly used during the simulation. This approach is usually useful
371     if components of the mixture can become very small. If such a small
372     quantity is computed via the equation 1 - sum(X[1:nX-1]), there might
373     be large numerical errors and it is better to compute it via
374     the corresponding balance equation.</li>
375<li> If Xi = nS-1, then the true independent mass fractions are used
376     in the fluid component and the last component of X is computed via
377     X[nX] = 1 - sum(Xi). This is useful for, e.g., MoistAir, where the
378     number of states should be as small as possible without introducing
379     numerical problems.</li>
380<li> If Xi = 0, then the reference value of composition reference_X is
381     assumed. This case is useful to avoid composition states in all
382     the cases when the composition will always be constant, e.g. with
383     circuits having fixed composition sources.
384</ul>
385 
386<p>
387The full vector of mass fractions <b>X[nX]</b> is computed in
388PartialMedium.BaseProperties based on Xi, reference_X, and the information whether Xi = nS or nS-1. For single-substance media, nX = 0, so there's also no X vector. For multiple-substance media, nX = nS, and X always contains the full vector of mass fractions. In order to reduce confusion for the user of a fluid component library, \"Xi\" has the annotation \"Hide=true\", meaning, that this variable is not shown in the plot window. Only X is shown in the plot window and this vector always contains all mass fractions.
389</p>
390</HTML>"));
391    end BasicUsage;
392   
393    class BalanceVolume "Balance volume" 
394     
395      annotation (Documentation(info="<HTML>
396<p>
397Fluid libraries usually have balance volume components with one fluid connector
398port that fulfill the mass and energy balance and on a different grid components that
399fulfill the momentum balance. A balance volume component, called junction
400volume below, should be primarily implemented in the following way
401(see also the implementation in
402<a href=\"Modelica://Modelica.Media.Examples.Tests.Components.PortVolume\">
403Modelica.Media.Examples.Tests.Components.PortVolume</a>):
404</p>
405<pre>
406  <b>model</b> JunctionVolume
407    <b>import</b> SI=Modelica.SIunits;
408    <b>import</b> Modelica.Media.Examples.Tests.Components.FluidPort_a;
409 
410    <b>parameter</b> SI.Volume V = 1e-6 \"Fixed size of junction volume\";
411    <b>replaceable package</b> Medium = Modelica.Media.Interfaces.PartialMedium
412                           \"Medium model\" <b>annotation</b> (choicesAllMatching = <b>true</b>);
413 
414    FluidPort_a port(<b>redeclare package</b> Medium = Medium);
415    Medium.BaseProperties medium(preferredMediumStates = <b>true</b>);
416 
417    SI.Energy U               \"Internal energy of junction volume\";
418    SI.Mass   M               \"Mass of junction volume\";
419    SI.Mass   MX[Medium.nXi] \"Independent substance masses of junction volume\";
420  <b>equation</b>
421    medium.p   = port.p;
422    medium.h   = port.h;
423    medium.Xi = port.Xi;
424 
425    M  = V*medium.d;                  // mass of JunctionVolume
426    MX = M*medium.Xi;                // mass fractions in JunctionVolume
427    U  = M*medium.u;                  // internal energy in JunctionVolume
428 
429    <b>der</b>(M)  = port.m_flow;    // mass balance
430    <b>der</b>(MX) = port.mX_flow;   // substance mass balance
431    <b>der</b>(U)  = port.H_flow;    // energy balance
432  <b>end</b> JunctionVolume;
433</pre>
434<p>
435Assume the Modelica.Media.Air.SimpleAir medium model is used with
436the JunctionVolume model above. This medium model uses pressure p
437and temperature T as independent variables. If the flag
438\"preferredMediumStates\" is set to <b>true</b> in the declaration
439of \"medium\", then the independent variables of this medium model
440get the attribute \"stateSelect = StateSelect.prefer\", i.e., the
441Modelica translator should use these variables as states, if this
442is possible. Basically, this means that
443constraints between the
444potential states p,T and the potential states U,M are present.
445A Modelica tool will therefore <b>automatically</b>
446differentiate medium equations and will use the following
447equations for code generation (note the equations related to X are
448removed, because SimpleAir consists of a single substance only):
449</p>
450<pre>
451    M  = V*medium.d;
452    U  = M*medium.u;
453 
454    // balance equations
455    <b>der</b>(M)  = port.m_flow;
456    <b>der</b>(U)  = port.H_flow;
457 
458    // abbreviations introduced to get simpler terms
459    p = medium.p;
460    T = medium.T;
461    d = medium.d;
462    u = medium.u;
463    h = medium.h;
464 
465    // medium equations
466    d = fd(p,T);
467    h = fh(p,T);
468    u = h - p/d;
469 
470    // equations derived <b>automatically</b> by a Modelica tool due to index reduction
471    <b>der</b>(U) = <b>der</b>(M)*u + M*<b>der</b>(u);
472    <b>der</b>(M) = V*<b>der</b>(d);
473    <b>der</b>(u) = <b>der</b>(h) - <b>der</b>(p)/d - p/<b>der</b>(d);
474    <b>der</b>(d) = <b>der</b>(fd,p)*<b>der</b>(p) + <b>der</b>(fd,T)*<b>der</b>(T);
475    <b>der</b>(h) = <b>der</b>(fh,p)*<b>der</b>(p) + <b>der</b>(fd,T)*<b>der</b>(T);
476</pre>
477<p>
478Note, that \"der(y,x)\" is an operator that characterizes
479in the example above the partial derivative of y with respect to x
480(this operator will be included in one of the next Modelica language
481releases).
482All media models in this library are written in such a way that
483at least the partial derivatives of the medium variables with
484respect to the independent variables are provided, either because
485the equations are directly given (= symbolic differentiation is possible)
486or because the derivative of the corresponding function (such as fd above)
487is provided. A Modelica tool will transform the equations above
488in differential equations with p and T as states, i.e., will
489generate equations to compute <b>der</b>(p) and <b>der</b>(T) as function of p and T.
490</p>
491 
492<p>
493Note, when preferredMediumStates = <b>false</b>, no differentiation
494will take place and the Modelica translator will use the variables
495appearing differentiated as states, i.e., M and U. This has the
496disadvantage that for many media non-linear systems of equations are
497present to compute the intrinsic properties p, d, T, u, h from
498M and U.
499</p>
500</HTML>"));
501    end BalanceVolume;
502   
503    class ShortPipe "Short pipe" 
504     
505      annotation (Documentation(info="<HTML>
506<p>
507Fluid libraries have components with two ports that store
508neither mass nor energy and fulfill the
509momentum equation between their two ports, e.g., a short pipe. In most
510cases this means that an equation is present relating the pressure
511drop between the two ports and the mass flow rate from one to the
512other port. Since no mass or energy is stored, no differential
513equations for thermodynamic variables are present. A component model of this type
514has therefore usually the following structure
515(see also the implementation in
516<a href=\"Modelica://Modelica.Media.Examples.Tests.Components.ShortPipe\">
517Modelica.Media.Examples.Tests.Components.ShortPipe</a>):
518</p>
519<pre>
520  <b>model</b> ShortPipe
521    <b>import</b> SI=Modelica.SIunits;
522    <b>import</b> Modelica.Media.Examples.Tests.Components;
523 
524    // parameters defining the pressure drop equation
525 
526    <b>replaceable package</b> Medium = Modelica.Media.Interfaces.PartialMedium
527                           \"Medium model\" <b>annotation</b> (choicesAllMatching = <b>true</b>);
528 
529    Component.FluidPort_a port_a (<b>redeclare package</b> Medium = Medium);
530    Component.FluidPort_b port_b (<b>redeclare package</b> Medium = Medium);
531 
532    SI.Pressure dp = port_a.p - port_b.p \"Pressure drop\";
533    Medium.BaseProperties medium_a \"Medium properties in port_a\";
534    Medium.BasePropreties medium_b \"Medium properties in port_b\";
535  <b>equation</b>
536    // define media models of the ports
537    medium_a.p   = port_a.p;
538    medium_a.h   = port_a.h;
539    medium_a.Xi = port_a.Xi;
540 
541    medium_b.p   = port_b.p;
542    medium_b.h   = port_b.h;
543    medium_b.Xi = port_b.Xi;
544 
545    // Handle reverse and zero flow (semiLinear is a built-in Modelica operator)
546    port_a.H_flow   = <b>semiLinear</b>(port_a.m_flow, port_a.h, port_b.h);
547    port_a.mXi_flow = <b>semiLinear</b>(port_a.m_flow, port_a.Xi, port_b.Xi);
548 
549    // Energy, mass and substance mass balance
550    port_a.H_flow + port_b.H_flow = 0;
551    port_a.m_flow + port_b.m_flow = 0;
552    port_a.mXi_flow + port_b.mXi_flow = zeros(Medium.nXi);
553 
554    // Provide equation: port_a.m_flow = f(dp)
555  <b>end</b> ShortPipe;
556</pre>
557 
558<p>
559The <b>semiLinear</b>(..) operator is basically defined as:
560</p>
561<pre>
562    semiLinear(m_flow, ha, hb) = if m_flow &ge; 0 then m_flow*ha else m_flow*hb;
563</pre>
564 
565<p>
566that is, it computes the enthalpy flow rate either from the port_a or
567from the port_b properties, depending on flow direction. The exact
568details of this operator are given in
569<a href=\"Modelica://ModelicaReference.Operators.SemiLinear\">
570ModelicaReference.Operators.SemiLinear</a>. Especially, rules
571are defined in the Modelica specification that m_flow = 0 can be treated
572in a \"meaningful way\". Especially, if n fluid components (such as pipes)
573are connected together and the fluid connector from above is used,
574a linear system of equations appear between
575medium1.h, medium2.h, medium3.h, ..., port1.h, port2.h, port3.h, ...,
576port1.H_flow, port2.H_flow, port3.H_flow, .... The rules for the
577semiLinear(..) operator allow the following solution of this
578linear system of equations:
579</p>
580 
581<ul>
582<li> n = 2 (two components are connected):<br>
583     The linear system of equations can be analytically solved
584     with the result
585     <pre>
586     medium1.h = medium2.h = port1.h = port2.h
587     0 = port1.H_flow + port2.H_flow
588     </pre>
589     Therefore, no problems with zero mass flow rate are present.</li>
590 
591<li> n &gt; 2 (more than two components are connected together):<br>
592     The linear system of equations is solved numerically during simulation.
593     For m_flow = 0, the linear system becomes singular and has an
594     infinite number of solutions. The simulator could use the solution t
595     that is closest to the solution in the previous time step
596     (\"least squares solution\"). Physically, the solution is determined
597     by diffusion which is usually neglected. If diffusion is included,
598     the linear system is regular.</li>
599</ul>
600     
601</HTML>"));
602    end ShortPipe;
603   
604    class OptionalProperties "Optional properties" 
605     
606      annotation (Documentation(info="<HTML>
607<p>
608In some cases additional medium properties are needed.
609A component that needs these optional properties has to call
610one of the functions listed in the following table. They are
611defined as partial functions within package
612<a href=\"Modelica://Modelica.Media.Interfaces.PartialMedium\">PartialMedium</a>,
613and then (optionally) implemented in actual medium packages.
614If a component calls such an optional function and the
615medium package does not provide a new implementation for this
616function, an error message is printed at translation time,
617since the function is \"partial\", i.e., incomplete.
618The argument of all functions is the <b>state</b> record,
619automatically defined by the BaseProperties model or specifically computed using the
620setState_XXX functions, which contains the
621minimum number of thermodynamic variables needed to compute all the additional
622properties. In the table it is assumed that there is a declaration of the
623form:
624</p>
625<pre>
626   <b>replaceable package</b> Medium = Modelica.Media.Interfaces.PartialMedium;
627   Medium.ThermodynamicState state;
628</pre>
629<table border=1 cellspacing=0 cellpadding=2>
630  <tr><td valign=\"top\"><b>Function call</b></td>
631      <td valign=\"top\"><b>Unit</b></td>
632      <td valign=\"top\"><b>Description</b></td></tr>
633  <tr><td valign=\"top\">Medium.dynamicViscosity(state)</b></td>
634      <td valign=\"top\">Pa.s</td>
635      <td valign=\"top\">dynamic viscosity</td></tr>
636  <tr><td valign=\"top\">Medium.thermalConductivity(state)</td>
637      <td valign=\"top\">W/(m.K)</td>
638      <td valign=\"top\">thermal conductivity</td></tr>
639  <tr><td valign=\"top\">Medium.prandtlNumber(state)</td>
640      <td valign=\"top\">1</td>
641      <td valign=\"top\">Prandtl number</td></tr>
642  <tr><td valign=\"top\">Medium.specificEntropy(state)</td>
643      <td valign=\"top\">J/(kg.K)</td>
644      <td valign=\"top\">specific entropy</td></tr>
645  <tr><td valign=\"top\">Medium.specificHeatCapacityCp(state)</td>
646      <td valign=\"top\">J/(kg.K)</td>
647      <td valign=\"top\">specific heat capacity at constant pressure</td></tr>
648  <tr><td valign=\"top\">Medium.specificHeatCapacityCv(state)</td>
649      <td valign=\"top\">J/(kg.K)</td>
650      <td valign=\"top\">specific heat capacity at constant density</td></tr>
651  <tr><td valign=\"top\">Medium.isentropicExponent(state)</td>
652      <td valign=\"top\">1</td>
653      <td valign=\"top\">isentropic exponent</td></tr>
654  <tr><td valign=\"top\">Medium.isentropicEnthatlpy(pressure, state)</td>
655      <td valign=\"top\">J/kg</td>
656      <td valign=\"top\">isentropic enthalpy</td></tr>
657  <tr><td valign=\"top\">Medium.velocityOfSound(state)</td>
658      <td valign=\"top\">m/s</td>
659      <td valign=\"top\">velocity of sound</td></tr>
660  <tr><td valign=\"top\">Medium.isobaricExpansionCoefficient(state)</td>
661      <td valign=\"top\">1/K</td>
662      <td valign=\"top\">isobaric expansion coefficient</td></tr>
663  <tr><td valign=\"top\">Medium.isothermalCompressibility(state)</td>
664      <td valign=\"top\">1/Pa</td>
665      <td valign=\"top\">isothermal compressibility</td></tr>
666  <tr><td valign=\"top\">Medium.density_derp_h(state)</td>
667      <td valign=\"top\">kg/(m3.Pa)</td>
668      <td valign=\"top\">derivative of density by pressure at constant enthalpy</td></tr>
669  <tr><td valign=\"top\">Medium.density_derh_p(state)</td>
670      <td valign=\"top\">kg2/(m3.J)</td>
671      <td valign=\"top\">derivative of density by enthalpy at constant pressure</td></tr>
672  <tr><td valign=\"top\">Medium.density_derp_T(state)</td>
673      <td valign=\"top\">kg/(m3.Pa)</td>
674      <td valign=\"top\">derivative of density by pressure at constant temperature</td></tr>
675  <tr><td valign=\"top\">Medium.density_derT_p(state)</td>
676      <td valign=\"top\">kg/(m3.K)</td>
677      <td valign=\"top\">derivative of density by temperature at constant pressure</td></tr>
678  <tr><td valign=\"top\">Medium.density_derX(state)</td>
679      <td valign=\"top\">kg/m3</td>
680      <td valign=\"top\">derivative of density by mass fraction</td></tr>
681  <tr><td valign=\"top\">Medium.molarMass(state)</td>
682      <td valign=\"top\">kg/mol</td>
683      <td valign=\"top\">molar mass</td></tr>
684</table>
685<p>
686There are also some short forms provided for user convenience that allow the computation of certain
687thermodynamic state variables without using the ThermodynamicState record explicitly. Those short forms
688are for example useful to compute consistent start values in the initial equation section. Let's
689consider the function temperature_phX(p,h,X) as an exmaple. This function computes the temperature
690from pressure, specific enthalpy, and composition X (or Xi) and is a short form for writing
691</p>
692<pre>
693  temperature(setState_phX(p,h,X))
694</pre>
695<p>
696The following functions are predefined in PartialMedium (other functions can be added in the actual
697medium implementation package if they are useful)
698</p>
699<table border=1 cellspacing=0 cellpadding=2>
700  <tr><td valign=\"top\">Medium.specificEnthalpy_pTX(p,T,X)</td>
701      <td valign=\"top\">J/kg</td>
702      <td valign=\"top\">Specific enthalpy at p, T, X </td></tr>
703  <tr><td valign=\"top\">Medium.temperature_phX(p,h,X)</td>
704      <td valign=\"top\">K</td>
705      <td valign=\"top\">Temperature at p, h, X</td></tr>
706  <tr><td valign=\"top\">Medium.density_phX(p,h,X)</td>
707      <td valign=\"top\">kg/m³</td>
708      <td valign=\"top\">Density at p, h, X</td></tr>
709  <tr><td valign=\"top\">Medium.temperature_psX(p,s,X)</td>
710      <td valign=\"top\">K</td>
711      <td valign=\"top\">Temperature at p, s, X</td></tr>
712  <tr><td valign=\"top\">Medium.specificEnthalpy_psX(p,s,X)</td>
713      <td valign=\"top\">J/(kg.K)</td>
714      <td valign=\"top\">Specific entropy at p, s, X</td></tr>
715</table>
716<p>
717Assume for example that the dynamic viscosity eta is needed in
718the pressure drop equation of a short pipe. Then, the
719model of a short pipe has to be changed to:
720</p>
721<pre>
722  <b>model</b> ShortPipe
723      ...
724    Medium.BaseProperties medium_a \"Medium properties in port_a\";
725    Medium.BaseProperties medium_b \"Medium properties in port_b\";
726      ...
727    Medium.DynamicViscosity eta;
728      ...
729    eta = <b>if</b> port_a.m_flow &gt; 0 <b>then</b>
730               Medium.dynamicViscosity(medium_a.state)
731          <b>else</b>
732               Medium.dynamicViscosity(medium_b.state);
733    // use eta in the pressure drop equation: port_a.m_flow = f(dp, eta)
734  <b>end</b> ShortPipe;
735</pre>
736 
737<p>
738Note, \"Medium.DynamicViscosity\" is a type defined in Modelica.Interfaces.PartialMedium
739as
740</p>
741 
742<pre>
743  <b>import</b> SI = Modelica.SIunits;
744  <b>type</b> DynamicViscosity = SI.DynamicViscosity (
745                                     min=0,
746                                     max=1.e8,
747                                     nominal=1.e-3,
748                                     start=1.e-3);
749</pre>
750 
751<p>
752Every medium model may modify the attributes, to provide, e.g.,
753min, max, nominal, and start values adapted to the medium.
754Also, other types, such as AbsolutePressure, Density, MassFlowRate,
755etc. are defined in PartialMedium. Whenever possible, these medium
756specific types should be used in a model in order that medium information,
757e.g., about nominal or start values, are automatically utilized.
758</p>
759 
760</pre>
761 
762</HTML>"));
763    end OptionalProperties;
764   
765    class Constants "Constants" 
766     
767      annotation (Documentation(info="<HTML>
768<p>
769Every medium model provides the following <b>constants</b>. For example,
770if a medium is declared as:
771</p>
772<pre>
773   <b>replaceable package</b> Medium = Modelica.Media.Interfaces.PartialMedium;
774</pre>
775<p>
776then constants \"Medium.mediumName\", \"Medium.nX\", etc. are defined:
777</p>
778<table border=1 cellspacing=0 cellpadding=2>
779  <tr><td valign=\"top\"><b>Type</b></td>
780      <td valign=\"top\"><b>Name</b></td>
781      <td valign=\"top\"><b>Description</b></td></tr>
782  <tr><td valign=\"top\">String</td><td valign=\"top\">mediumName</td>
783      <td valign=\"top\">Unique name of the medium (is usually used to check whether
784          the media in different components connected together
785          are the same, by providing Medium.mediumName as quantity
786          attribute of the mass flow rate in the connector)</td></tr>
787  <tr><td valign=\"top\">String</td><td valign=\"top\">substanceNames[nS]</td>
788      <td valign=\"top\">Names of the substances that make up the medium.
789          If only one substance is present, substanceNames = {mediumName}.</td></tr>
790  <tr><td valign=\"top\">String</td><td valign=\"top\">extraPropertiesNames[nC]</td>
791      <td valign=\"top\">Names of the extra transported substances, outside of mass and
792          energy balances.</td></tr>
793  <tr><td valign=\"top\">Boolean</td><td valign=\"top\">singleState</td>
794      <td valign=\"top\">= <b>true</b>, if u and d are not a function of pressure, and thus only
795          a function of a single thermal variable (temperature or enthalpy) and
796          of Xi for a multiple substance medium. Usually, this flag is
797          <b>true</b> for incompressible media. It is used in a model to determine
798          whether 1+nXi (singleState=<b>true</b>) or 2+nXi (singleState=<b>false</b>)
799          initial conditions have to be provided for a volume element that
80