class StateSelection "State Selection"
extends Modelica.Icons.Information;
annotation (Documentation(info = "<html>\n<p>\nOnly a few components of the Translational library use the der(..) operator\nand are therefore candidates to have states. Most important, component <a href=\"modelica://Modelica.Mechanics.Translational.Components.Mass\">Mass</a>\ndefines the absolute position and the absolute velocity of this\ncomponent as candidate for states. In the \"Advanced\" menu the built-in StateSelect\nenumeration can be set to define the priority to use these variables as states.\nWithout further action, in most cases a tool will select these variables as states.\n</p>\n\n<p>\nFor positioning drive trains where the goal is to position a load, the absolute positions of the components are bounded,\nand the issue discussed below is not present.\n</p>\n\n<p>\nFor drive trains where the goal is to control the velocity of a load,\nthe absolute positions of the components are quickly increasing\nduring operation. This is critical, because then the step size control of time\nintegrators might then no longer work appropriately:\n</p>\n\n<p>\nIntegrators with step size control adjust their time step size automatically\nto meet user defined error bounds (\"tolerances\").\nTypically the local error estimate EST_i is compared with a mixed bound for absolute and relative errors.\n</p>\n\n<pre>\n EST_i ≤ abstol_i + reltol_i*|x_i|\n</pre>\n\n<p>\nHere, abstol_i and reltol_i denote the bounds for the absolute and relative error of state variable x_i, respectively. This mixed error bound is used since it is more robust than a pure relative error based error bound if the nominal value x_i is (very) close to 0.\nIn a Modelica simulation model, typically the same relative tolerance reltol is used for all\nstates and the absolute tolerances are computed using the relative tolerance and the\nnominal values of the states:\n</p>\n\n<pre>\n reltol_i = reltol\n abstol_i = reltol*x_i(nominal)*0.01\n</pre>\n\n<p>\nThis error control fails if the state variable x_i grows without bounds (such as for a\ndrive train), since then the allowed error\nalso grows without bounds. The effect is that the error control on this variable is practically\nswitched off. The correct way to handle this would be to set reltol_i = 0 on such a state\nvariable and only use an absolute tolerance for the step size control.\n</p>\n\n<p>\nCurrently, in Modelica there is no possibility to provide this information.\nIn order to reduce this effect, it is advisable to not use absolute angles, but\nrelative angles as states. A user can define relative variables as states\nexplicitly with component\n<a href=\"modelica://Modelica.Mechanics.Translational.Components.RelativeStates\">RelativeStates</a>.\nFurthermore, all compliant components, such as\n<a href=\"modelica://Modelica.Mechanics.Translational.Components.SpringDamper\">SpringDamper</a> are\ndefining the relative position and the relative velocity as preferred states.\nTherefore, a tool will select in most cases relative positions as states.\n</p>\n\n<p>\nThe relative positions of compliant components are usually small.\nWithout further action, the error control would not work properly on variables\nthat are so small (so often switching the error control off). The remedy is to define\nexplicitly a nominal value on the relative angle. This definition is provided in the\n\"Advanced\" menu of the compliant components with parameter \"s_nominal\".\nThe default value is 1e-4 m, to be in the order of a compliant deformation of a\ndrive.\n</p>\n</html>"));
end StateSelection;