class AnalyticLoopHandling "Analytic loop handling"
extends Modelica.Icons.Information;
annotation (Documentation(info = "<html>\n<p>\nIt is well known that the non-linear\nalgebraic equations of most mechanical loops in technical devices can be\nsolved analytically. It is, however, difficult to perform this fully\nautomatically and therefore none of the commercial, general purpose multi-body\nprograms, such as MSC ADAMS, LMS DADS, SIMPACK, have this feature.\nThese programs solve loop structures with pure numerical methods. Multi-body\nprograms that are designed for real-time simulation of the dynamics of\nspecific vehicles, such as ve-DYNA, usually contain manual implementations\nof a particular multi-body system (the vehicle) where the occurring loops are\neither analytically solved, if this is possible, or are treated by table\nlook-up where the tables are constructed in a pre-processing phase. Without\nthese features the required real-time capability would be difficult to\nachieve.\n</p>\n<p>\nIn a series of papers and dissertations\nProf. Hiller and his group in Duisburg, Germany,\nhave developed systematic methods to handle mechanical\nloops analytically, see also\n<a href=\"modelica://Modelica.Mechanics.MultiBody.UsersGuide.Literature\">MultiBody.UsersGuide.Literature</a>.\nThe \"characteristic pair of joints\" method\nbasically cuts a loop at two joints and uses geometric\ninvariants to reduce the number of algebraic\nequations, often down to one equation that can be solved analytically. Also\nseveral multi-body codes have been developed that are based on this method,\ne.g., MOBILE. Besides the very desired feature to solve non-linear\nalgebraic equations analytically, i.e., efficiently and in a robust way, there\nare several drawbacks: It is difficult to apply this method automatically.\nEven if this would be possible in a good way, there is always the problem that\nit cannot be guaranteed that the statically selected states lead to no\nsingularity during simulation. Therefore, the \"characteristic pair of joints\"\nmethod is usually manually applied which requires know-how and experience.\n</p>\n<p>\nIn the MultiBody library, the \"characteristic pair of\njoints\" method is supported in a restricted form such that it can be applied\nalso by non-specialists. The idea is to provide aggregations of joints in package\n<a href=\"modelica://Modelica.Mechanics.MultiBody.Joints.Assemblies\">\nMultiBody.Joints.Assemblies</a>\nas one object that either have <strong>6</strong> degrees of freedom or\n<strong>3</strong> degrees of freedom (for usage in planar loops).\n</p>\n<p>\nAs an example, a variant of the four bar mechanism is given in\nthe figure below.\n</p>\n\n<blockquote>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/FourbarAnalytic2.png\">\n</blockquote>\n\n<p>\nHere, the mechanism is modeled with six revolute\njoints and one prismatic joint.\nIn the figure below, the five revolute joints\nand the prismatic joint are collected together in an assembly object\ncalled \"jointSSP\" from\n<a href=\"modelica://Modelica.Mechanics.MultiBody.Joints.Assemblies.JointSSP\">\nMultiBody.Joints.Assemblies.JointSSP</a>.\n</p>\n\n<blockquote>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/FourbarAnalytic1.png\">\n</blockquote>\n\n<p>\nThe JointSSP joint aggregation has a frame at the\nouter spherical joint (frame_a) and a frame at\nthe prismatic joint (frame_b). JointSSP, as all other objects from the\nJoints.Assemblies package, has the property, that the <strong>generalized\ncoordinates, and all other frames\ndefined in the assembly, can be calculated given the movement of frame_a and\nof frame_b</strong>. This is performed by <strong>analytically</strong> solving non-linear\nsystems of equations.\n<!-- (details are given in section xxx). -->\nFrom a\nstructural point of view, the equations in an assembly object are written in\nthe form\n</p>\n<blockquote>\n <strong>q</strong> = <strong>\n f</strong><sub>1</sub>(<strong>r</strong><sup>a</sup>, <strong>R</strong><sup>a</sup>, <strong>r</strong><sup>b</sup>,\n <strong>R</strong><sup>b</sup>)\n</blockquote>\n<p>\nwhere <strong>r</strong><sup>a</sup>, <strong>R</strong><sup>a</sup>,\n<strong>r</strong><sup>b</sup>, <strong>R</strong><sup>b</sup> are the variables defining the\nposition and orientation of the frame_a and frame_b, respectively, and\n<strong>q</strong> are the generalized positional coordinates inside the\nassembly, e.g., the angle of a revolute joint. Given angle\n<span style=\"font-family:Symbol\">j</span> of revolute joint j1 from the four\nbar mechanism, frame_a and frame_b of the assembly object can be computed by a\nforward recursion\n</p>\n<blockquote>\n(<strong>r</strong><sup>a</sup>,\n<strong>R</strong><sup>a</sup>, <strong>r</strong><sup>b</sup>, <strong>R</strong><sup>b</sup>) = <strong>f</strong>(<span style=\"font-family:Symbol\">j)</span>\n</blockquote>\n<p>\nSince this is a structural property, the\nsymbolic algorithms can automatically select <span style=\"font-family:Symbol\">\nj</span> and its derivative as states and then all positional variables can be\ncomputed in a forwards sequence. It is now understandable that a Modelica\ntranslator can\ntransform the equations of the four bar mechanism to a recursive sequence of\nstatements that has no non-linear algebraic loops anymore (remember,\nthe previous \"straightforward\" solution with 6 revolute joints and 1\nprismatic joint has a nonlinear system of equations of order 5).\n</p>\n<p>\nThe aggregated joint\nobjects consist of a combination of either a revolute or prismatic joint and\nof a rod that has either two spherical joints at its two ends or a spherical\nand a universal joint, respectively. For all combinations, analytic solutions\ncan be determined. For planar loops, combinations of 1, 2 or 3 revolute joints\nwith parallel axes and of 2 or 1 prismatic joint with axes that are orthogonal\nto the revolute joints can be treated analytically. The currently supported\ncombinations are listed in the table below.\n</p>\n<div align=\"left\">\n <table border=\"1\" cellspacing=\"0\" cellpadding=\"0\">\n <tr>\n <td colspan=\"2\"> <strong>3-dimensional Loops:</strong></td>\n </tr>\n <tr>\n <td>JointSSR</td>\n <td>Spherical - Spherical - Revolute</td>\n </tr>\n <tr>\n <td>JointSSP</td>\n <td>Spherical - Spherical - Prismatic</td>\n </tr>\n <tr>\n <td>JointUSR</td>\n <td>Universal - Spherical - Revolute</td>\n </tr>\n <tr>\n <td>JointUSP</td>\n <td>Universal - Spherical - Prismatic</td>\n </tr>\n <tr>\n <td>JointUPS</td>\n <td>Universal - Prismatic - Spherical</td>\n </tr>\n <tr>\n <td colspan=\"2\"><strong>Planar Loops:</strong></td>\n </tr>\n <tr>\n <td>JointRRR</td>\n <td>Revolute - Revolute - Revolute</td>\n </tr>\n <tr>\n <td>JointRRP</td>\n <td>Revolute - Revolute - Prismatic</td>\n </tr>\n</table>\n</div>\n<p>\nOn first view this seems to be quite restrictive. However, mechanical devices are usually built up with rods connected by spherical joints on each end,\nand additionally with revolute and prismatic joints.\nTherefore, the combinations of the above table occur frequently.\nThe universal joint is usually not present in actual devices but is used\n(a) if two JointXXX components can be connected such that a revolute\nand a universal joint together form a spherical joint\nand (b) if the orientation of the connecting rod between two\nspherical joints is needed, e.g., since a body shall be attached.\nIn this case one of the spherical joints might be replaced by a\nuniversal joint. This approximation is fine as long as the mass\nand inertia of the rod is not significant.\n</p>\n<p>\nLet us discuss item (a) in more detail: The\nMacPherson suspension in the next figure has three frame connectors.\n</p>\n\n<blockquote>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/MacPherson1.png\">\n</blockquote>\n\n<p>\nThe lower left one (frameChassis) is fixed to the vehicle chassis. The\nupper left one (frameSteering) is driven by the steering mechanism, i.e. the\nmovement of both frames are given. The frame connector on the right (frameWheel)\ndrives the wheel. The three frames are connected by a mechanism consisting\nessentially of two rods with spherical joints on both ends. These are built up\nby a jointUPS and a jointSSR assemblies.\nAs can be seen, the universal joint from the jointUPS\nassembly is connected to the revolute joint of the jointSSR assembly.\nTherefore, we have 3 revolute joints connected together at one point and if\nthe axes of rotations are chosen appropriately, this describes a spherical\njoint. In other words, the two connected assemblies define the desired two\nrods with spherical joints on each ends.\n</p>\n<p>\nThe movement of the chassis, frameChassis, is computed\noutside of the suspension model. When the generalized coordinates of revolute joint\n\"jointArm\" (lower left part in figure) are used as states, then frame_a and\nframe_b of the jointUPS joint can be calculated. After the non-linear loop\nwith jointUPS is (analytically) solved, all frames on this assembly are\nknown, especially,\nthe one connected to frame_b of the jointSSR assembly. Since frame_a of\njointSSR is connected to frameSteering which is computed from the steering\nmechanism, again the two required frame movements of the jointSSR assembly are\ncalculated. This in turn means that also all other frames on the jointSSR\nassembly can be computed, especially, the one connected to frameWheel that drives\nthe wheel. From this analysis it is clear that a tool is able to solve these\ncoupled loops analytically.\n</p>\n<p>\nAnother example is the model of the V6 engine,\nsee next figure for an animation view and the original definition\nof one cylinder with elementary joints.\n</p>\n\n<blockquote>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/EngineV6_3.png\" width=\"303\" height=\"136\">\n</blockquote>\n\n<blockquote>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/EngineV6_2.png\">\n</blockquote>\n\n<p>\nHere, it is sufficient to rewrite the basic cylinder model\nby replacing the joints with a JointRRP object that has two\nrevolute and one prismatic joint, as can be seen in next figure.\n</p>\n\n<blockquote>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/EngineV6_4.png\">\n</blockquote>\n\n<p>\nSince 6\ncylinders are connected together, 6 coupled loops with 6 JointRRP objects are\npresent. This model is available as\n<a href=\"modelica://Modelica.Mechanics.MultiBody.Examples.Loops.EngineV6_analytic\">\nMultiBody.Examples.Loops.EngineV6_analytic</a>.\n</p>\n<p>\nThe composition diagram of the connected 6 cylinders is\nshown in the next figure\n</p>\n\n<blockquote>\n<img src=\"modelica://Modelica/Resources/Images/Mechanics/MultiBody/UsersGuide/Tutorial/LoopStructures/EngineV6_1.png\">\n</blockquote>\n<p>\nIt can be seen that the revolute joint\nof the crank shaft (joint \"bearing\" in left part of figure) might be\nselected as degree of freedom. Then, the 4 connector frames of all cylinders\ncan be computed. As a result, the computations of the cylinders are decoupled\nfrom each other. Within one cylinder\nthe position of frame_a and frame_b of the jointRRP assembly\ncan be computed and therefore the generalized coordinates of the two revolute\nand the prismatic joint in the jointRRP object can be determined. Considering this\nanalysis, it is not surprising that a Modelica translator\nis able to transform the DAE\nequations into a sequential evaluation without any non-linear loop.\nCompare this nice result with the model using only elementary joints\nthat leads to a DAE with 6 algebraic loops and 5 non-linear equations per\nloop. Additionally, a linear system of equations of order 43 is present.\nThe simulation time is about 5 times faster with the analytic loop handling.\n</p>\n</html>"));
end AnalyticLoopHandling;