class PlanarLoops "Planar loops"
extends Modelica.Icons.Information;
annotation (Documentation(info = "<html>\n<p>\nIn the figure below, the model of a V6 engine is\nshown that has a simple combustion model. It is available as\n<a href=\"modelica://Modelica.Mechanics.MultiBody.Examples.Loops.EngineV6\">\nMultiBody.Examples.Loops.EngineV6</a>.\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/EngineV6_1.png\">\n</p>\n\n<p>\nThe Modelica schematic of one cylinder\nis given in the figure below. Connecting 6 instances of this\ncylinder appropriately together results in the engine schematic displayed\nabove.\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/EngineV6_2.png\">\n</p>\n\n<p>\nIn the next figure the animation of the engine is\nshown. Every cylinder consists essentially of 1 prismatic and 2 revolute\njoints that form a planar loop, since the axes of the two revolute joints are\nparallel to each other and the axis of the prismatic joint is orthogonal to\nthe revolute joint axes. All 6 cylinders together form a coupled set of 6\nloops that have together 1 degree of freedom.\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/EngineV6_3.png\" width=\"303\" height=\"136\">\n</p>\n\n<p>\nAll planar loops, and especially the engine, result in\na DAE (= Differential-Algebraic Equation system)\nthat does not have a unique solution. The reason is that, e.g., the cut\nforces in direction of the axes of the revolute joints cannot be uniquely\ncomputed. Any value fulfills the DAE equations. This is a structural property\nthat is determined by the symbolic algorithms. Since they detect that the DAE is\nstructurally singular, a further processing is not possible. Without\nadditional information it is also impossible that the symbolic algorithms\ncould be enhanced because if the axes of rotations of the revolute joints are\nonly slightly changed such that they are no longer parallel to each other, the\nplanar loop can no longer move and has 0 degrees of freedom. Algorithms based\non pure structural information cannot distinguish these two cases.\n</p>\n<p>\nThe usual remedy is to remove superfluous constraints,\ne.g., along the axis of rotation of <strong>one</strong> revolute joint. Since this is\nnot easy for an inexperienced modeler, the special joint:\n<a href=\"modelica://Modelica.Mechanics.MultiBody.Joints.RevolutePlanarLoopConstraint\">\nRevolutePlanarLoopConstraint</a> is provided that removes these constraints.\nExactly one revolute joint in a every planar loop must be replaced by this\njoint type. In the engine example, this special joint is used for\nthe revolute joint B2 in the cylinder model above. The icon of the joint is\nslightly different to other revolute joints to visualize this case.\n</p>\n<p>\nIf a modeler is not aware of the problems with planar\nloops and models them without special consideration, a Modelica\ntranslator displays an error\nmessage and points out that a planar loop may be the reason and suggests to\nuse the RevolutePlanarLoopConstraint joint.\nThis error message is due to an annotation in\nthe Frame connector.\n</p>\n<pre>\n <strong>connector</strong> Frame\n ...\n <strong>flow</strong> SI.Force f[3] <strong>annotation</strong>(unassignedMessage=\"..\");\n <strong>end</strong> Frame;\n</pre>\n<p>\nIf no assignment can be found for some\nforces in a connector, the \"unassignedMessage\" is displayed. In most cases the\nreason for this is a planar loop or two joints that constrain the same motion.\nBoth cases are discussed in the error message.\n</p>\n<p>\nNote, that the non-linear algebraic equations occurring\nin planar loops can be solved analytically in most cases and therefore it is\nhighly recommended to use the techniques discussed in section\n\"<a href=\"modelica://Modelica.Mechanics.MultiBody.UsersGuide.Tutorial.LoopStructures.AnalyticLoopHandling\">Analytic loop handling</a>\"\nfor such systems.\n</p>\n</html>"));
end PlanarLoops;