class ParameterDefaults "Parameter defaults"
extends Modelica.Icons.Information;
annotation (Documentation(info = "<html>\n\n<p>\nIn this section the convention is summarized how default parameters are\nhandled in the Modelica Standard Library (since version 3.0).\n</p>\n\n<p>\nMany models in this library have parameter declarations to define\nconstants of a model that might be changed before simulation starts.\nExample:\n</p>\n\n<blockquote>\n<pre>\n<strong>model</strong> SpringDamper\n<strong>parameter</strong> Real c(final unit=\"N.m/rad\") = 1e5 \"Spring constant\";\n<strong>parameter</strong> Real d(final unit=\"N.m.s/rad\") = 0 \"Damping constant\";\n<strong>parameter</strong> Modelica.SIunits.Angle phi_rel0 = 0 \"Unstretched spring angle\";\n...\n<strong>end</strong> SpringDamper;\n</pre>\n</blockquote>\n\n<p>\nIn Modelica it is possible to define a default value of a parameter in\nthe parameter declaration. In the example above, this is performed for\nall parameters. Providing default values for all parameters can lead to\nerrors that are difficult to detect, since a modeler may have forgotten\nto provide a meaningful value (the model simulates but gives wrong\nresults due to wrong parameter values). In general the following basic\nsituations are present:\n</p>\n\n<ol>\n<li> The parameter value could be anything (e.g., a spring constant or\n a resistance value) and therefore the user should provide a value in\n all cases. A Modelica translator should warn, if no value is provided.\n</li>\n\n<li> The parameter value is not changed in > 95 % of the cases\n (e.g., initialization or visualization parameters, or parameter phi_rel0\n in the example above). In this case a default parameter value should be\n provided, in order that the model or function can be conveniently\n used by a modeler.\n</li>\n\n<li> A modeler would like to quickly utilize a model, e.g.,\n <ul>\n <li> to automatically check that the model still translates and/or simulates\n (after some changes in the library),</li>\n <li> to make a quick demo of a library by drag-and-drop of components,</li>\n <li> to implement a simple test model in order to get a better understanding\n of the desired component.</li>\n </ul>\n In all these cases, it would be not practical, if the modeler would\n have to provide explicit values for all parameters first.\n </li>\n</ol>\n\n<p>\nTo handle the conflicting goals of (1) and (3), the Modelica Standard Library\nuses two approaches to define default parameters, as demonstrated with the\nfollowing example:\n</p>\n\n<blockquote>\n<pre>\n<strong>model</strong> SpringDamper\n<strong>parameter</strong> Real c(final unit=\"N.m/rad\" , start=1e5) \"Spring constant\";\n<strong>parameter</strong> Real d(final unit=\"N.m.s/rad\", start= 0) \"Damping constant\";\n<strong>parameter</strong> Modelica.SIunits.Angle phi_rel0 = 0 \"Unstretched spring angle\";\n...\n<strong>end</strong> SpringDamper;\n\nSpringDamper sp1; // warning for \"c\" and \"d\"\nSpringDamper sp2(c=1e4, d=0); // fine, no warning\n</pre>\n</blockquote>\n\n<p>\nBoth definition forms, using a \"start\" value (for \"c\" and \"d\") and providing\na declaration equation (for \"phi_rel0\"), are valid Modelica and define the value\nof the parameter. By convention, it is expected that Modelica translators will\ntrigger a warning message for parameters that are <strong>not</strong> defined by a declaration\nequation, by a modifier equation or in an initial equation/algorithm section.\nA Modelica translator might have options to change this behavior, especially,\nthat no messages are printed in such cases and/or that an error is triggered\ninstead of a warning.\n</p>\n\n</html>"));
end ParameterDefaults;