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

Revision 1150, 183.1 kB (checked in by otter, 7 weeks ago)

#93 fixed: arctan replaced by atan and updated release notes
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1within ;
2package Modelica "Modelica Standard Library (Version 3.0)"
3extends Icons.Library;
4
5
6annotation (
7  preferredView="info",
8  version="3.0",
9  versionBuild="$Rev$",
10  versionDate="$Date::                            $",
11  conversion(
12    from(version="2.1", script="Scripts/ConvertModelica_from_2.2.2_to_3.0.mos"),
13    from(version="2.2", script="Scripts/ConvertModelica_from_2.2.2_to_3.0.mos"),
14    from(version="2.2.1", script="Scripts/ConvertModelica_from_2.2.2_to_3.0.mos"),
15    from(version="2.2.2", script="Scripts/ConvertModelica_from_2.2.2_to_3.0.mos")),
16  Settings(NewStateSelection=true),
17  Documentation(info="<HTML>
18<p>
19Package <b>Modelica</b> is a <b>standardized</b> and <b>free</b> package
20that is developed together with the Modelica language from the
21Modelica Association, see
22<a href=\"http://www.Modelica.org\">http://www.Modelica.org</a>.
23It is also called <b>Modelica Standard Library</b>.
24It provides model components in many domains that are based on
25standardized interface definitions. Some typical examples are shown
26in the next figure:
27</p>
28 
29<p>
30<img src=\"../Images/UsersGuide/ModelicaLibraries.png\">
31</p>
32 
33<p>
34For an introduction, have especially a look at:
35</p>
36<ul>
37<li> <a href=\"Modelica://Modelica.UsersGuide.Overview\">Overview</a>
38     provides an overview of the Modelica Standard Library
39     inside the <a href=\"Modelica://Modelica.UsersGuide\">User's Guide</a>.</li>
40<li><a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes\">Release Notes</a>
41    summarizes the changes of new versions of this package.</li>
42<li> <a href=\"Modelica://Modelica.UsersGuide.Contact\">Contact</a>
43     lists the contributors of the Modelica Standard Library.</li>
44<li> <a href=\"../help/Documentation/ModelicaStandardLibrary.pdf\">ModelicaStandardLibrary.pdf</a>
45     is the complete documentation of the library in pdf format.
46<li> The <b>Examples</b> packages in the various libraries, demonstrate
47     how to use the components of the corresponding sublibrary.</li>
48</ul>
49
50<p>
51This version of the Modelica Standard Library consists of
52</p>
53<ul>
54<li> <b>777</b> models and blocks, and</li>
55<li> <b>549</b> functions
56</ul>
57<p>
58that are directly usable (= number of public, non-partial classes).
59</p>
60
61<p>
62Copyright &copy; 1998-2008, Modelica Association.
63</p>
64<p>
65<i>This Modelica package is <b>free</b> software; it can be redistributed and/or modified
66under the terms of the <b>Modelica license</b>, see the license conditions
67and the accompanying <b>disclaimer</b> 
68<a href=\"Modelica://Modelica.UsersGuide.ModelicaLicense\">here</a>.</i>
69</p>
70</HTML>
71"));
72
73
74package UsersGuide "User's Guide of Modelica library"
75
76  annotation (DocumentationClass=true, Documentation(info="<html>
77<p>
78Package <b>Modelica</b> is a <b>standardized</b> and <b>pre-defined</b> package
79that is developed together with the Modelica language from the
80Modelica Association, see
81<a href=\"http://www.Modelica.org\">http://www.Modelica.org</a>.
82It is also called <b>Modelica Standard Library</b>.
83It provides constants, types, connectors, partial models and model
84components in various disciplines.
85</p>
86<p>
87This is a short <b>User's Guide</b> for
88the overall library. Some of the main sublibraries have their own
89User's Guides that can be accessed by the following links:
90</p>
91
92<table border=1 cellspacing=0 cellpadding=2>
93<tr><td valign=\"top\"><a href=\"Modelica://Modelica.Electrical.Digital.UsersGuide\">Digital</a>
94    </td>
95      <td valign=\"top\">Library for digital electrical components based on the VHDL standard
96         (2-,3-,4-,9-valued logic)</td>
97  </tr>
98  <tr><td valign=\"top\"><a href=\"Modelica://Modelica.Mechanics.MultiBody.UsersGuide\">MultiBody</a>
99             </td>
100      <td valign=\"top\">Library to model 3-dimensional mechanical systems</td>
101  </tr>
102
103  <tr><td valign=\"top\"><a href=\"Modelica://Modelica.Mechanics.Rotational.UsersGuide\">Rotational</a>
104             </td>
105      <td valign=\"top\">Library to model 1-dimensional mechanical systems</td>
106  </tr>
107
108  <tr><td valign=\"top\"><a href=\"Modelica://Modelica.Media.UsersGuide\">Media</a>
109             </td>
110      <td valign=\"top\">Property models of media</td>
111  </tr>
112  <tr><td valign=\"top\"><a href=\"Modelica://Modelica.SIunits.UsersGuide\">SIunits</a> </td>
113      <td valign=\"top\">Type definitions based on SI units according to ISO 31-1992</td>
114  </tr>
115
116  <tr><td valign=\"top\"><a href=\"Modelica://Modelica.StateGraph.UsersGuide\">StateGraph</a>
117             </td>
118      <td valign=\"top\">Library to model discrete event and reactive systems by hierarchical state machines</td>
119  </tr>
120
121
122  <tr><td valign=\"top\"><a href=\"Modelica://Modelica.Utilities.UsersGuide\">Utilities</a>
123             </td>
124      <td valign=\"top\">Utility functions especially for scripting (Files, Streams, Strings, System)</td>
125  </tr>
126</table>
127
128</html>"));
129
130  class Overview "Overview of Modelica Library"
131
132    annotation (Documentation(info="<html>
133<p>
134The Modelica Standard Library consists of the following
135main sub-libraries:
136</p>
137
138<table border=1 cellspacing=0 cellpadding=2>
139<tr><th>Library Components</th> <th>Description</th></tr>
140
141<tr><td valign=\"top\"> 
142    <img src=\"../Images/UsersGuide/Lib-Electrical.png\">
143    </td>
144    <td valign=\"top\">
145    <a href=\"Modelica://Modelica.Electrical.Analog\">Analog</a><br>
146    Analog electric and electronic components, such as <br> 
147    resistor, capacitor, transformers, diodes, transistors,<br>
148    transmission lines, switches, sources, sensors.
149    </td>
150</tr>
151
152<tr><td valign=\"top\"> 
153    <img src=\"../Images/UsersGuide/Lib-Digital.png\">
154    </td>
155    <td valign=\"top\">
156    <a href=\"Modelica://Modelica.Electrical.Digital\">Digital</a><br>
157    Digital electrical components based on the VHDL standard, <br>
158    like basic logic blocks with 9-value logic, delays, gates, <br>
159    sources, converters between 2-, 3-, 4-, and 9-valued logic.
160    </td>
161</tr>
162
163<tr><td valign=\"top\"> 
164    <img src=\"../Images/UsersGuide/Lib-Machines.png\">
165    </td>
166    <td valign=\"top\">
167    <a href=\"Modelica://Modelica.Electrical.Machines\">Machines</a><br>
168    Electrical asynchronous-, synchronous-, and DC-machines<br>
169    (motors and generators) as well as 3-phase transformers.
170    </td>
171</tr>
172
173<tr><td valign=\"top\"> 
174    <img src=\"../Images/UsersGuide/Lib-Translational.png\">
175    </td>
176    <td valign=\"top\">
177    <a href=\"Modelica://Modelica.Mechanics.Translational\">Translational</a><br>
178    1-dim. mechanical, translational systems, e.g.,  <br>
179    sliding mass, mass with stops, spring, damper.
180    </td>
181</tr>
182
183<tr><td valign=\"top\"> 
184    <img src=\"../Images/UsersGuide/Lib-Rotational.png\">
185    </td>
186    <td valign=\"top\">
187    <a href=\"Modelica://Modelica.Mechanics.Rotational\">Rotational</a><br>
188    1-dim. mechanical, rotational systems, e.g., inertias, gears, <br>
189    planetary gears, convenient definition of speed/torque dependent friction<br>
190    (clutches, brakes, bearings, ..)
191    </td>
192</tr>
193
194<tr><td valign=\"top\"> 
195    <img src=\"../Images/UsersGuide/Lib-MultiBody1.png\"><br>
196    <img src=\"../Images/UsersGuide/Lib-MultiBody2.png\">
197    </td>
198    <td valign=\"top\">
199    <a href=\"Modelica://Modelica.Mechanics.MultiBody\">MultiBody</a><br>
200    3-dim. mechanical systems consisting of joints, bodies, force and <br>
201    sensor elements. Joints can be driven by drive trains defined by<br>
202    1-dim. mechanical system library (Rotational).<br>
203    Every component has a default animation.<br>
204    Components can be arbitrarily connected together.
205    </td>
206</tr>
207
208<tr><td valign=\"top\"> 
209    <img src=\"../Images/UsersGuide/Lib-Media.png\">
210    </td>
211    <td valign=\"top\">
212    <a href=\"Modelica://Modelica.Media\">Media</a><br>
213    Large media library providing models and functions<br>
214    to compute media properties, such as h = h(p,T), d = d(p,T),<br>
215    for the following media:
216    <ul>
217    <li> 1240 gases and mixtures between these gases.</li>
218    <li> incompressible, table based liquids (h = h(T), etc.).</li>
219    <li> compressible liquids</li>
220    <li> dry and moist air</li>
221    <li> high precision model for water (IF97).</li>
222    </ul>
223    </td>
224</tr>
225
226<tr><td valign=\"top\"> 
227    <img src=\"../Images/UsersGuide/Lib-Thermal.png\">
228    </td>
229    <td valign=\"top\">
230    <a href=\"Modelica://Modelica.Thermal.FluidHeatFlow\">FluidHeatFlow</a>,
231    <a href=\"Modelica://Modelica.Thermal.HeatTransfer\">HeatTransfer</a><br>
232    Simple thermo-fluid pipe flow, especially to model cooling of machines <br>
233    with air or water (pipes, pumps, valves, ambient, sensors, sources) and<br>
234    lumped heat transfer with heat capacitors, thermal conductors, convection,<br>
235    body radiation, sources and sensors.
236    </td>
237</tr>
238
239<tr><td valign=\"top\"> 
240    <img src=\"../Images/UsersGuide/Lib-Blocks1.png\"><br>
241    <img src=\"../Images/UsersGuide/Lib-Blocks2.png\">
242    </td>
243    <td valign=\"top\">
244    <a href=\"Modelica://Modelica.Blocks\">Blocks</a><br>
245    Input/output blocks to model block diagrams and logical networks, e.g.,<br>
246    integerator, PI, PID, transfer function, linear state space system,<br>
247    sampler, unit delay, discrete transfer function, and/or blocks,<br>
248    timer, hysteresis, nonlinear and routing blocks, sources, tables.
249    </td>
250</tr>
251
252<tr><td valign=\"top\"> 
253    <img src=\"../Images/UsersGuide/Lib-StateGraph.png\">
254    </td>
255    <td valign=\"top\">
256    <a href=\"Modelica://Modelica.StateGraph\">StateGraph</a><br>
257    Hierarchical state machines with a similar modeling power as Statecharts. <br>
258    Modelica is used as synchronous action language, i.e. deterministic <br>
259    behavior is guaranteed
260    </td>
261</tr>
262
263
264<tr><td valign=\"top\"> 
265    <pre>
266    A = [1,2,3;
267         3,4,5;
268         2,1,4];
269    b = {10,22,12};
270    x = Matrices.solve(A,b);
271    Matrices.eigenValues(A);
272    </pre>
273    </td>
274    <td valign=\"top\">
275    <a href=\"Modelica://Modelica.Math\">Math</a>,
276    <a href=\"Modelica://Modelica.Utilities\">Utilities</a><br>
277    Functions operating on vectors and matrices, such as for solving <br>
278    linear systems, eigen and singular values etc.,  and <br>
279    functions operating on strings, streams, files, e.g., <br>
280    to copy and remove a file or sort a vector of strings.
281    </td>
282</tr>
283
284</table>
285
286</html>
287"));
288  end Overview;
289
290  class Connectors "Connectors"
291
292    annotation (Documentation(info="<html>
293
294<p>
295The Modelica standard library defines the most important
296<b>elementary connectors</b> in various domains. If any possible,
297a user should utilize these connectors in order that components
298from the Modelica Standard Library and from other libraries
299can be combined without problems. The following elementary
300connectors are defined (potential variables are connector variables
301without the flow attribute, flow variables are connector variables
302that have the flow attribute):
303</p>
304 
305<table border=1 cellspacing=0 cellpadding=1>
306  <tr><td valign=\"top\"><b>domain</b></td>
307      <td valign=\"top\"><b>pot. variables</b></td>
308      <td valign=\"top\"><b>flow variables</b></td>
309      <td valign=\"top\"><b>connector definition</b></td>
310      <td valign=\"top\"><b>icons</b></td></tr>
311 
312  <tr><td valign=\"top\"><b>electrical<br>analog</b></td>
313      <td valign=\"top\">electrical potential</td>
314      <td valign=\"top\">electrical current</td>
315      <td valign=\"top\"><a href=\"Modelica://Modelica.Electrical.Analog.Interfaces\">Modelica.Electrical.Analog.Interfaces</a>
316           <br>Pin, PositivePin, NegativePin</td>
317      <td valign=\"top\"><img src=\"../Images/UsersGuide/ElectricalPins.png\"></td></tr>
318
319  <tr><td valign=\"top\"><b>electrical<br>multi-phase</b></td>
320      <td colspan=\"2\">vector of electrical pins</td>
321      <td valign=\"top\"><a href=\"Modelica://Modelica.Electrical.MultiPhase.Interfaces\">Modelica.Electrical.MultiPhase.Interfaces</a>
322           <br>Plug, PositivePlug, NegativePlug</td>
323      <td valign=\"top\"><img src=\"../Images/UsersGuide/ElectricalPlugs.png\"></td></tr>
324 
325  <tr><td valign=\"top\"><b>electrical <br>sphace phasor</b></td>
326      <td valign=\"top\">2 electrical potentials</td>
327      <td valign=\"top\">2 electrical currents</td>
328      <td valign=\"top\"><a href=\"Modelica://Modelica.Electrical.Machines.Interfaces\">Modelica.Electrical.Machines.Interfaces</a>
329           <br>SpacePhasor</td>
330      <td valign=\"top\"><img src=\"../Images/UsersGuide/SpacePhasor.png\"></td></tr>
331 
332  <tr><td valign=\"top\"><b>electrical <br>digital</b></td>
333      <td valign=\"top\">Integer (1..9)</td>
334      <td valign=\"top\">---</td>
335      <td valign=\"top\"><a href=\"Modelica://Modelica.Electrical.Digital.Interfaces\">Modelica.Electrical.Digital.Interfaces</a>
336           <br>DigitalSignal, DigitalInput, DigitalOutput</td>
337      <td valign=\"top\"><img src=\"../Images/UsersGuide/Digital.png\"></td></tr>
338 
339  <tr><td valign=\"top\"><b>translational</b></td>
340      <td valign=\"top\">distance</td>
341      <td valign=\"top\">cut-force</td>
342      <td valign=\"top\"><a href=\"Modelica://Modelica.Mechanics.Translational.Interfaces\">Modelica.Mechanics.Translational.Interfaces</a>
343           <br>Flange_a, Flange_b</td>
344      <td valign=\"top\"><img src=\"../Images/UsersGuide/TranslationalFlanges.png\"></td></tr>
345 
346  <tr><td valign=\"top\"><b>rotational</b></td>
347      <td valign=\"top\">angle</td>
348      <td valign=\"top\">cut-torque</td>
349      <td valign=\"top\"><a href=\"Modelica://Modelica.Mechanics.Rotational.Interfaces\">Modelica.Mechanics.Rotational.Interfaces</a>
350           <br>Flange_a, Flange_b</td>
351      <td valign=\"top\"><img src=\"../Images/UsersGuide/RotationalFlanges.png\"></td></tr>
352
353  <tr><td valign=\"top\"><b>3-dim.<br>mechanics</b></td>
354      <td valign=\"top\">position vector<br>
355          orientation object</td>
356      <td valign=\"top\">cut-force vector<br>
357          cut-torque vector</td>
358      <td valign=\"top\"><a href=\"Modelica://Modelica.Mechanics.MultiBody.Interfaces\">Modelica.Mechanics.MultiBody.Interfaces</a>
359           <br>Frame, Frame_a, Frame_b, Frame_resolve</td>
360      <td valign=\"top\"><img src=\"../Images/UsersGuide/MultiBodyFrames.png\"></td></tr>
361
362  <tr><td valign=\"top\"><b>simple<br>fluid flow</b></td>
363      <td valign=\"top\">pressure<br>
364          specific enthalpy</td>
365      <td valign=\"top\">mass flow rate<br>
366          enthalpy flow rate</td>
367      <td valign=\"top\"><a href=\"Modelica://Modelica.Thermal.FluidHeatFlow.Interfaces\">Modelica.Thermal.FluidHeatFlow.Interfaces</a>
368           <br>FlowPort, FlowPort_a, FlowPort_b</td>
369      <td valign=\"top\"><img src=\"../Images/UsersGuide/FluidHeatFlowPorts.png\"></td></tr>
370
371  <tr><td valign=\"top\"><b>heat<br>transfer</b></td>
372      <td valign=\"top\">temperature</td>
373      <td valign=\"top\">heat flow rate</td>
374      <td valign=\"top\"><a href=\"Modelica://Modelica.Thermal.HeatTransfer.Interfaces\">Modelica.Thermal.HeatTransfer.Interfaces</a>
375           <br>HeatPort, HeatPort_a, HeatPort_b</td>
376      <td valign=\"top\"><img src=\"../Images/UsersGuide/ThermalHeatPorts.png\"></td></tr>
377 
378  <tr><td valign=\"top\"><b>block<br>diagram</b></td>
379      <td valign=\"top\">Real variable<br>
380          Integer variable<br>
381          Boolean variable</td>
382      <td valign=\"top\">---</td>
383      <td valign=\"top\"><a href=\"Modelica://Modelica.Blocks.Interfaces\">Modelica.Blocks.Interfaces</a>
384           <br>RealSignal, RealInput, RealOutput<br>
385               IntegerSignal, IntegerInput, IntegerOutput<br>
386               BooleanSignal, BooleanInput, BooleanOutput</td>
387      <td valign=\"top\"><img src=\"../Images/UsersGuide/Signals.png\"></tr>
388
389  <tr><td valign=\"top\"><b>state<br>machine</b></td>
390      <td valign=\"top\">Boolean variables<br>
391          (occupied, set, <br>
392           available, reset)</td>
393      <td valign=\"top\">---</td>
394      <td valign=\"top\"><a href=\"Modelica://Modelica.StateGraph.Interfaces\">Modelica.StateGraph.Interfaces</a>
395           <br>Step_in, Step_out, Transition_in, Transition_out</td>
396      <td valign=\"top\"><img src=\"../Images/UsersGuide/StateGraphPorts.png\"></td></tr>
397
398  <tr><td colspan=\"5\">&nbsp;<br><b>Connectors from libraries that will be included in one of
399                                   the next releases of package Modelica</b></td></tr>
400
401  <tr><td valign=\"top\"><b>thermo<br>fluid flow</b></td>
402      <td valign=\"top\">pressure<br>
403          specific enthalpy<br>
404          mass fractions</td>
405      <td valign=\"top\">mass flow rate<br>
406          enthalpy flow rate<br>
407          subst. mass flow rates</td>
408      <td valign=\"top\">Modelica_Fluid.Interfaces
409           <br>FluidPort, FluidPort_a, FluidPort_b</td>
410      <td valign=\"top\"><img src=\"../Images/UsersGuide/FluidPorts.png\"></td></tr>
411
412  <tr><td valign=\"top\"><b>magnetic</b></td>
413      <td valign=\"top\">magnetic potential</td>
414      <td valign=\"top\">magnetic flux</td>
415      <td valign=\"top\">Magnetic.Interfaces
416           <br>MagneticPort, PositiveMagneticPort, <br>NegativeMagneticPort</td>
417      <td valign=\"top\"><img src=\"../Images/UsersGuide/MagneticPorts.png\"></td></tr>
418
419
420  <tr><td colspan=\"5\">&nbsp;<br><b>Connectors from other libraries</b></td></tr>
421
422  <tr><td valign=\"top\"><b>hydraulic</b></td>
423      <td valign=\"top\">pressure</td>
424      <td valign=\"top\">volume flow rate</td>
425      <td valign=\"top\">HyLibLight.Interfaces
426           <br>Port_A, Port_b</td>
427      <td valign=\"top\"><img src=\"../Images/UsersGuide/HydraulicPorts.png\"></td></tr>
428
429  <tr><td valign=\"top\"><b>pneumatic</b></td>
430      <td valign=\"top\">pressure</td>
431      <td valign=\"top\">mass flow rate</td>
432      <td valign=\"top\">PneuLibLight.Interfaces
433           <br>Port_1, Port_2</td>
434      <td valign=\"top\"><img src=\"../Images/UsersGuide/PneumaticPorts.png\"></td></tr>
435</table>
436
437<p>
438In all domains, usually 2 connectors are defined. The variable declarations
439are <b>identical</b>, only the icons are different in order that it is easy
440to distinguish connectors of the same domain that are attached at the same
441component.
442</p>
443
444<p>
445Modelica supports also hierarchical connectors, in a similar way as hierarchical models.
446As a result, it is, e.g., possible, to collect elementary connectors together.
447For example, an electrical plug consisting of two electrical pins can be defined as:
448</p>
449
450<pre>   <b>connector</b> Plug
451      <b>import</b> Modelica.Electrical.Analog.Interfaces;
452      Interfaces.PositivePin phase;
453      Interfaces.NegativePin ground;
454   <b>end</b> Plug;
455</pre>
456
457<p>
458With one connect(..) equation, either two plugs can be connected
459(and therefore implicitly also the phase and ground pins) or a
460Pin connector can be directly connected to the phase or ground of
461a Plug connector, such as \"connect(resistor.p, plug.phase)\".
462</p>
463
464
465</html>
466"));
467  end Connectors;
468
469  class Conventions "Conventions"
470
471    annotation (Documentation(info="<html>
472
473<p>
474Note, in the html documentation of any Modelica library,
475the headings \"h1, h2, h3\" should not be used,
476because they are utilized from the automatically generated documentation/headings.
477Additional headings in the html documentation should start with \"h4\".
478</p>
479
480<p>
481In the Modelica package the following conventions are used:
482</p>
483<ol>
484<li> Class and instance names are written in upper and lower case
485     letters, e.g., \"ElectricCurrent\". An underscore is only used
486     at the end of a name to characterize a lower or upper index,
487     e.g., \"pin_a\".<br>&nbsp;</li>
488
489<li> <b>Class names</b> start always with an upper case letter.<br>&nbsp;</li>
490
491<li> <b>Instance names</b>, i.e., names of component instances and
492     of variables (with the exception of constants),
493     start usually with a lower case letter with only
494     a few exceptions if this is common sense
495     (such as \"T\" for a temperature variable).<br>&nbsp;</li>
496
497<li> <b>Constant names</b>, i.e., names of variables declared with the
498     \"constant\" prefix, follow the usual naming conventions
499     (= upper and lower case letters) and start usually with an
500     upper case letter, e.g. UniformGravity, SteadyState.<br>&nbsp;<li>
501
502<li> The two connectors of a domain that have identical declarations
503     and different icons are usually distinguished by \"_a\", \"_b\"
504     or \"_p\", \"_n\", e.g., Flange_a/Flange_b, HeatPort_a, HeatPort_b.<br>&nbsp;</li>
505
506<li> The <b>instance name</b> of a component is always displayed in its icon
507     (= text string \"%name\") in <b>blue color</b>. A connector class has the instance
508     name definition in the diagram layer and not in the icon layer.
509     <b>Parameter</b> values, e.g., resistance, mass, gear ratio, are displayed
510     in the icon in <b>black color</b> in a smaller font size as the instance name.
511    <br>&nbsp;<li>
512
513<li> A main package has usually the following subpackages:
514     <ul>
515     <li><b>UsersGuide</b> containing an overall description of the library
516         and how to use it.</li> 
517     <li><b>Examples</b> containing models demonstrating the
518         usage of the library.</li> 
519     <li><b>Interfaces</b> containing connectors and partial
520         models.</li> 
521     <li><b>Types</b> containing type, enumeration and choice
522         definitions.</li>
523     </ul>
524     </li>
525</ol>
526
527</html>
528"));
529  end Conventions;
530
531  class ParameterDefaults "Parameter defaults"
532
533    annotation (Documentation(info="<html>
534
535<p>
536In this section the convention is summarized how default parameters are
537handled in the Modelica Standard Library (since version 3.0).
538</p>
539
540<p>
541Many models in this library have parameter declarations to define
542constants of a model that might be changed before simulation starts.
543Example:
544</p>
545
546<blockquote>
547<pre>
548<b>model</b> SpringDamper
549   <b>parameter</b> Real c(final unit=\"N.m/rad\")    = 1e5 \"Spring constant\";
550   <b>parameter</b> Real d(final unit=\"N.m.s/rad\")  = 0   \"Damping constant\";
551   <b>parameter</b> Modelica.SIunits.Angle phi_rel0 = 0   \"Unstretched spring angle\";
552   ...
553<b>end</b> SpringDamper;
554</pre>
555</blockquote>
556
557<p>
558In Modelica it is possible to define a default value of a parameter in
559the parameter declaration. In the example above, this is performed for
560all parameters. Providing default values for all parameters can lead to
561errors that are difficult to detect, since a modeler may have forgotten
562to provide a meaningful value (the model simulates but gives wrong
563results due to wrong parameter values). In general the following basic
564situations are present:
565</p>
566
567<ol>
568<li> The parameter value could be anything (e.g., a spring constant or
569     a resistance value) and therefore the user should provide a value in
570     all cases. A Modelica translator should warn, if no value is provided.
571     <br><br></li>
572
573<li> The parameter value is not changed in &gt; 95 % of the cases
574     (e.g. initialization or visualization parameters, or parameter phi_rel0
575     in the example above). In this case a default parameter value should be
576     provided, in order that the model or function can be conveniently
577     used by a modeler.
578     <br><br></li>
579
580<li> A modeler would like to quickly utilize a model, e.g.,
581     <ul>
582     <li> to automatically check that the model still translates and/or simulates
583          (after some changes in the library),</li>
584     <li> to make a quick demo of a library by drag-and-drop of components,</li>
585     <li> to implement a simple test model in order to get a better understanding
586          of the desired component.</li>
587     </ul>
588     In all these cases, it would be not practical, if the modeler would
589     have to provide explicit values for all parameters first.
590     </li>
591</ol>
592
593<p>
594To handle the conflicting goals of (1) and (3), the Modelica Standard Library
595uses two approaches to define default parameters, as demonstrated with the
596following example:
597</p>
598
599<blockquote>
600<pre>
601<b>model</b> SpringDamper
602   <b>parameter</b> Real c(final unit=\"N.m/rad\"  , start=1e5) \"Spring constant\";
603   <b>parameter</b> Real d(final unit=\"N.m.s/rad\", start=  0) \"Damping constant\";
604   <b>parameter</b> Modelica.SIunits.Angle phi_rel0 = 0       \"Unstretched spring angle\";
605   ...
606<b>end</b> SpringDamper;
607
608SpringDamper sp1;              // warning for \"c\" and \"d\"
609SpringDamper sp2(c=1e4, d=0);  // fine, no warning
610</pre>
611</blockquote>
612
613<p>
614Both definition forms, using a \"start\" value (for \"c\" and \"d\") and providing
615a declaration equation (for \"phi_rel0\"), are valid Modelica and define the value
616of the parameter. By convention, it is expected that Modelica translators will
617trigger a warning message for parameters that are <b>not</b> defined by a declaration
618equation, by a modifier equation or in an initial equation/algorithm section.
619A Modelica translator might have options to change this behavior, especially,
620that no messages are printed in such cases and/or that an error is triggered
621instead of a warning.
622</p>
623
624</html>
625"));
626  end ParameterDefaults;
627
628  package ReleaseNotes "Release notes"
629  class Version_3_0_BugFixes "Version 3.0 with bug fixes"
630
631      annotation (Documentation(info="<html>
632
633<p>
634In this section bug fixes are summarized that have been incorporated
635since the release of version 3.0.
636</p>
637
638<p><br>
639The following <b style=\"color:red\">critical errors</b> have been fixed (i.e. errors
640that can lead to wrong simulation results):
641</p>
642 
643<table border=\"1\" cellspacing=0 cellpadding=2 style=\"border-collapse:collapse;\">
644  <tr><td colspan=\"2\"><b>Mechanics.MultiBody.Forces</b></td></tr>
645  <tr><td valign=\"top\"> WorldTorque </td>
646      <td valign=\"top\"> Parameter \"ResolveInFrame\" was not propagated and therefore
647                        always the default (resolved in world frame) was used, independently
648                        of the setting of this parameter. </td> 
649  </tr>
650  <tr><td valign=\"top\"> WorldForceAndTorque </td>
651      <td valign=\"top\"> Parameter \"ResolveInFrame\" was not propagated and therefore
652                        always the default (resolved in world frame) was used, independently
653                        of the setting of this parameter.<br>
654                        Furthermore, internally WorldTorque was used instead of
655                        Internal.BasicWorldTorque and therefore the visualization of
656                        worldTorque was performed twice. </td> 
657  </tr>
658  <tr><td colspan=\"2\"><b>Mechanics.Translational.Components.</b></td></tr>
659  <tr><td valign=\"top\"> SupportFriction<br>
660                        Brake </td>
661      <td valign=\"top\"> The sign of the friction force was wrong and therefore friction accelerated
662                        instead of decelerated. This was fixed. In order to test the changes,
663                        Translational.Examples.Friction was enhanced to use also the SupportFriction
664                        component and a new example Translational.Examples.Brake was introduced. </td> 
665  </tr>
666
667</table>
668 
669 
670<p><br>
671The following <b style=\"color:red\">uncritical errors</b> have been fixed (i.e. errors
672that do <b style=\"color:red\">not</b> lead to wrong simulation results, but, e.g.,
673units are wrong or errors in documentation):
674</p>
675 
676<table border=\"1\" cellspacing=0 cellpadding=2 style=\"border-collapse:collapse;\">
677  <tr><td colspan=\"2\"><b>Blocks.Math.</b></td></tr>
678  <tr><td valign=\"top\"> InverseBlockConstraint </td>
679      <td valign=\"top\"> Changed annotation preserveAspectRatio from true to false.</td> 
680  </tr>
681
682  <tr><td colspan=\"2\"><b>Blocks.Sources.</b></td></tr>
683  <tr><td valign=\"top\"> RealExpression<br>
684                        IntegerExpression<br>
685                        BooleanExpression </td>
686      <td valign=\"top\"> Changed annotation preserveAspectRatio from true to false.</td> 
687  </tr>
688
689  <tr><td colspan=\"2\"><b>Electrical.Analog.Basic.</b></td></tr>
690  <tr><td valign=\"top\"> SaturatingInductor</td>
691      <td valign=\"top\"> Replaced non-standard \"arctan\" by \"atan\" function.</td> 
692  </tr>
693
694  <tr><td colspan=\"2\"><b>Media.Interfaces.PartialSimpleMedium</b></td></tr>
695  <tr><td valign=\"top\"> pressure<br> 
696                        temperature<br>
697                        density<br>
698                        specificEnthalpy </td>
699      <td valign=\"top\"> Missing functions added.</td> 
700  </tr>
701</table>
702                                               
703</html>"));
704  end Version_3_0_BugFixes;
705
706    annotation (Documentation(info="<html>
707
708<p>
709This section summarizes the changes that have been performed
710on the Modelica standard library.
711</p>
712
713<ul>
714<li> <a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes.Version_3_0\">Version 3.0</a> (Jan., 2008)</li>
715<li> <a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes.Version_2_2_2\">Version 2.2.2</a> (Aug. 31, 2007)</li>
716<li> <a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes.Version_2_2_1\">Version 2.2.1</a> (March 24, 2006)</li>
717<li> <a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes.Version_2_2\">Version 2.2</a> (April 6, 2005)</li>
718<li> <a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes.Version_2_1\">Version 2.1</a> (Nov. 11, 2004)</li>
719<li> <a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes.Version_1_6\">Version 1.6</a> (June 21, 2004)</li>
720<li> <a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes.Version_1_5\">Version 1.5</a> (Dec. 16, 2002)</li>
721<li> <a href=\"Modelica://Modelica.UsersGuide.ReleaseNotes.Version_1_4\">Version 1.4</a> (June 28, 2001
722     and previous versions)</li>
723</ul>
724
725<p>
726Maintenance of the Modelica Standard Library is performed with
727three branches on the subversion server of the Modelica Association:
728</p>
729
730<h4>Released branch</h4>
731<p>
732Example: \"Modelica/tags/V2_2_1/Modelica\"
733</p>
734
735<p>
736This branch contains the released Modelica versions (e.g. version 2.2.1),
737where all available test cases and compatibility checks with other Modelica
738libraries have been performed on the respective release. This version is
739usually shipped with a Modelica modelling and simulation environment and
740utilized by a Modelica user.
741</p>
742
743<h4>Development branch</h4>
744<p>
745Example: \"Modelica/trunk/Modelica\"
746</p>
747
748<p>
749This branch contains the actual development version, i.e., all bug fixes
750and new features based on the last Modelica release.
751New features should have been tested before including them.
752However, the exhaustive tests for a new version are (usually) not performed.
753This version is usually only be used by the developers of the
754Modelica Standard Library and is not utilized by Modelica users.
755</p>
756
757
758<h4>Maintenance branch</h4>
759<p>
760Example: \"Modelica/branches/maintenance/2.2.1/Modelica\"
761</p>
762
763<p>
764This branch contains the released Modelica version (e.g. version 2.2.1)
765where all bug fixes since this release date are included (up to a  new release,
766when becoming available; i.e., after a new release, the previous maintenance
767versions are no longer changed).
768These bug fixes might be not yet tested with all test cases or with
769other Modelica libraries. The goal is that a vendor may take this version at
770any time for a new release of its software, in order to incorporate the latest
771bug fixes, without changing the version number of the Modelica Standard Library.
772</p>
773
774<p>
775Incorporation of bug fixes (subversion \"commit\") shall be performed in the following way:
776</p>
777
778<ul>
779<li> One person is fixing the bug and another person is checking whether the
780     fix is fine.</li>
781<li> It is up to the library developer, whether he opens a new branch for
782     testing and then merges it with the \"head\" maintenance branch or not.</li>
783<li> Every change to the maintenance branch has to be done at the development
784     branch (see above) as well.</li>
785<li> Every change to the maintenance branch requires introducing a
786     description of the bug fix under
787     Modelica.UsersGuide.ReleaseNotes.&lt;release-number&gt;_bugFixes.</li>
788<li> Every change to the maintenance branch requires changing the date
789    Â