root/trunk/Modelica/package.mo

Revision 1170, 187.4 kB (checked in by otter, 2 weeks ago)

Bugs in MultiBody.Sensors corrected (reported by Johan Andreasson and by Jakub Tobolar):
- AbsoluteSensor/AbsoluteVelocity: differentiated vectors not in the world frame

but in the resolveInFrame frame.

- RelativeSensor

If resolveInFrame <> frame_resolve and resolveInFrameAfterDifferentiation = frame_resolve,
a translation error occured, since frame_resolve was not enabled in this situation.

- RelativeVelocity

The velocity has been computed by differentiating in the resolveInFrame frame.
This has been corrected, by first transforming the relative position in to frame_a,
differentiating here and then transforming into resolveInFrame

- TransformRelativeVector

The transformation was wrong, since the parameters frame_r_in and frame_r_out have
not been propagated to the submodel that performs the transformation

- The release notes have been updated.
  • 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.1 development)"
3extends Icons.Library;
4
5
6annotation (
7  preferredView="info",
8  version="3.0.1 development",
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 (__Dymola_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_1_development "Version 3.0.1 (development)"
630
631      annotation (Documentation(info="<html>
632
633<p><br>
634The following <b style=\"color:blue\">new components</b> have been added
635to <b style=\"color:blue\">existing</b> libraries:
636</p>
637
638<table border=\"1\" cellspacing=0 cellpadding=2 style=\"border-collapse:collapse;\">
639  <tr><td colspan=\"2\"><b>Mechanics.Translational.Components.Examples.</b></td></tr>
640  <tr><td valign=\"top\">Brake</td>
641      <td valign=\"top\"> Demonstrates the usage of the translational brake component.</td> </tr>
642</table>
643
644
645<p><br>
646The following <b style=\"color:blue\">existing components</b>
647have been <b style=\"color:blue\">changed</b> (in a
648<b style=\"color:blue\">backward compatible</b> way):
649</p>
650 
651<table border=\"1\" cellspacing=0 cellpadding=2 style=\"border-collapse:collapse;\">
652  <tr><td colspan=\"2\"><b>Mechanics.Translational.Components.Examples.</b></td></tr>
653  <tr><td valign=\"top\"> Friction </td>
654      <td valign=\"top\"> Added a third variant, where friction is modelled with
655                        the SupportFriction component.</td> </tr>
656</table>
657
658
659<p><br>
660The following <b style=\"color:red\">critical errors</b> have been fixed (i.e. errors
661that can lead to wrong simulation results):
662</p>
663 
664<table border=\"1\" cellspacing=0 cellpadding=2 style=\"border-collapse:collapse;\">
665  <tr><td colspan=\"2\"><b>Mechanics.MultiBody.Forces</b></td></tr>
666  <tr><td valign=\"top\"> WorldTorque </td>
667      <td valign=\"top\"> Parameter \"ResolveInFrame\" was not propagated and therefore
668                        always the default (resolved in world frame) was used, independently
669                        of the setting of this parameter. </td> 
670  </tr>
671  <tr><td valign=\"top\"> WorldForceAndTorque </td>
672      <td valign=\"top\"> Parameter \"ResolveInFrame\" was not propagated and therefore
673                        always the default (resolved in world frame) was used, independently
674                        of the setting of this parameter.<br>
675                        Furthermore, internally WorldTorque was used instead of
676                        Internal.BasicWorldTorque and therefore the visualization of
677                        worldTorque was performed twice. </td> 
678  </tr>
679  <tr><td colspan=\"2\"><b>Mechanics.MultiBody.Sensors</b></td></tr>
680  <tr><td valign=\"top\"> AbsoluteSensor </td>
681      <td valign=\"top\"> Velocity, acceleration and angular acceleration were computed
682                          by differentiating in the resolveInFrame frame. This has been corrected, by
683                          first transforming the vectors in to the world frame, differentiating here
684                          and then transforming into resolveInFrame. The parameter in the Advanced menue
685                          resolveInFrameAfterDifferentiation is then superfluous and was removed . </td> 
686  </tr>
687  <tr><td valign=\"top\"> AbsoluteVelocity </td>
688      <td valign=\"top\"> The velocity was computed
689                          by differentiating in the resolveInFrame frame. This has been corrected, by
690                          first transforming the velocity in to the world frame, differentiating here
691                          and then transforming into resolveInFrame </td> 
692  </tr>
693  <tr><td valign=\"top\"> RelativeSensor </td>
694      <td valign=\"top\"> If resolveInFrame &lt;&gt; frame_resolve and
695                           resolveInFrameAfterDifferentiation = frame_resolve, a translation
696                        error occured, since frame_resolve was not enabled in this situation.
697                        This has been corrected.</td> 
698  </tr>
699  <tr><td valign=\"top\"> RelativeVelocity </td>
700      <td valign=\"top\"> The velocity has have been computed
701                          by differentiating in the resolveInFrame frame. This has been corrected, by
702                          first transforming the relative position in to frame_a, differentiating here
703                          and then transforming into resolveInFrame </td> 
704  </tr>
705  <tr><td valign=\"top\"> TransformRelativeVector </td>
706      <td valign=\"top\"> The transformation was wrong, since the parameters frame_r_in and frame_r_out
707                        have not been propagated to the submodel that performs the transformation.
708                        This has been corrected. </td> 
709  </tr>
710  <tr><td colspan=\"2\"><b>Mechanics.Translational.Components.</b></td></tr>
711  <tr><td valign=\"top\"> SupportFriction<br>
712                        Brake </td>
713      <td valign=\"top\"> The sign of the friction force was wrong and therefore friction accelerated
714                        instead of decelerated. This was fixed. </td> 
715  </tr>
716</table>
717 
718 
719<p><br>
720The following <b style=\"color:red\">uncritical errors</b> have been fixed (i.e. errors
721that do <b style=\"color:red\">not</b> lead to wrong simulation results, but, e.g.,
722units are wrong or errors in documentation):
723</p>
724 
725<table border=\"1\" cellspacing=0 cellpadding=2 style=\"border-collapse:collapse;\">
726  <tr><td colspan=\"2\"><b>Blocks.Math.</b></td></tr>
727  <tr><td valign=\"top\"> InverseBlockConstraint </td>
728      <td valign=\"top\"> Changed annotation preserveAspectRatio from true to false.</td> 
729  </tr>
730
731  <tr><td colspan=\"2\"><b>Blocks.Sources.</b></td></tr>
732  <tr><td valign=\"top\"> RealExpression<br>
733                        IntegerExpression<br>
734                        BooleanExpression </td>
735      <td valign=\"top\"> Changed annotation preserveAspectRatio from true to false.</td> 
736  </tr>
737
738  <tr><td colspan=\"2\"><b>Electrical.Analog.Basic.</b></td></tr>
739  <tr><td valign=\"top\"> SaturatingInductor</td>
740      <td valign=\"top\"> Replaced non-standard \"arctan\" by \"atan\" function.</td> 
741  </tr>
742
743  <tr><td colspan=\"2\"><b>Mechanics.Rotational.Interfaces.</b></td></tr>
744  <tr><td valign=\"top\"> PartialFriction </td>
745      <td valign=\"top\"> Corrected and simplified parameterized curve description.
746                        The previous formulation could lead to an inconsistent mixed system
747                        of equations if peak > 1 and then an additional event iteration
748                        was needed to find the solution. The change therefore enhances
749                        efficiency in some situations. </td> 
750  </tr>
751  <tr><td colspan=\"2\"><b>Mechanics.Translational.Interfaces.</b></td></tr>
752  <tr><td valign=\"top\"> PartialFriction </td>
753      <td valign=\"top\"> Corrected and simplified parameterized curve description.
754                        The previous formulation could lead to an inconsistent mixed system
755                        of equations if peak > 1 and then an additional event iteration
756                        was needed to find the solution. The change therefore enhances
757