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

Revision 1159, 325.6 kB (checked in by dietmarw, 2 months ago)

fixes #100 (in maintenance/3.0) by changing the annotation to a vendor specific annotation

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