<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"	"docbook/dtd/4.1/docbook.dtd" [<!ENTITY orocos "<acronym>Orocos</acronym>">]><article><articleinfo>  <title>    Decoupling in complex software systems  </title>  <author>    <firstname>Herman</firstname>    <surname>Bruyninckx</surname>    <affiliation>      <address>        Herman.Bruyninckx@mech.kuleuven.ac.be      </address>    </affiliation>  </author> <copyright>  <year>2003</year>  <holder>Herman Bruyninckx &mdash;Permission is granted to copy, distribute and/or modify this documentunder the terms of the GNU General Public License(<ulink url="http://www.fsf.org/copyleft/gpl.html">http://www.fsf.org/copyleft/gpl.html</ulink>), where the <emphasis>source code</emphasis> of the document is the <ulink url="decoupling.xml">XML file</ulink>.</holder> </copyright> <abstract> <para> <emphasis role="strong">Abstract</emphasis> </para> <para>This document describes the role of the concept&ldquo;decoupling&rdquo; in the design process of a complex softwaresystem such as robot control. </para> </abstract> <revhistory>  <revision>    <revnumber>0.01</revnumber>    <date>June 28, 2003</date>    <authorinitials>HB</authorinitials>    <revremark>First stand-alone version. Started from section inkinematics and dynamics document.</revremark>   </revision>  <revision>    <revnumber>0.02</revnumber>    <date>July 1, 2003</date>    <authorinitials>HB</authorinitials>    <revremark>Explained &ldquo;semantic decoupling&rdquo; in moredetail.</revremark>   </revision>  <revision>    <revnumber>0.03</revnumber>    <date>July 1, 2003</date>    <authorinitials>HB</authorinitials>    <revremark>Reworked the material on symbolic, physical andmathematical properties.</revremark>   </revision> </revhistory></articleinfo><section id="overview"><title> Overview and motivation</title><para>The software design of the &orocos; project is driven by the desire<emphasis role="strong">to decouple</emphasis> the complex robot control software problem intolibraries of the &ldquo;right size&rdquo;, that can be developed byindependent programmers. That means that thefunctionalities in the various libraries can be implemented withouthaving to know anything about the implementation in the otherlibraries. Of course, the libraries can (and should) know each other's<emphasis role="strong">programming interfaces</emphasis>.It is immediately clear that the trade-off to be optimized is that of&ldquo;implementation efficiency&rdquo; versus &ldquo;programmingcomplexity&rdquo;: knowing theimplementation details of a set of related functionality givesopportunities for optimization, but quickly leads to a network ofimplementation interdependencies that is too complex for one singleprogrammer to understand and to maintain, let alone to extend.</para><para>So, finding this right-sized decoupling in a complex software systemshould be a major aim of its designers, since it is key to thesoftware's flexibility and maintainability.  In addition, anappropriate decoupling also improves user-friendliness: when buildingtheir application, users have to know and understand only thosemodules that they need for their task, instead of having&ldquo;to cut away&rdquo; the functionality that they don't need. Orto fill their programs with<emphasis>&ldquo;feature not implemented&rdquo;</emphasis> messages.</para><para>The text distinguishes between the following complementary forms ofdecoupling:<itemizedlist><listitem><para><link linkend="semantic-decoupling">Semantic decoupling</link>:to separate the different<emphasis>meanings and physical properties</emphasis> of the encodedconcepts in groups that &ldquo;belong together&rdquo; in allapplications.</para></listitem><listitem><para><link linkend="inter-connection-decoupling">Inter-connectiondecoupling</link>:to separate the properties of individual<emphasis>objects</emphasis> from the properties ofthe <emphasis>systems</emphasis> that can be built by inter-connectingthese individual objects.</para></listitem><listitem><para><link linkend="library-decoupling">Library structure decoupling</link>:to choose the appropriate granularity for the code libraries.</para></listitem><listitem><para><link linkend="object-component-decoupling">Object-componentdecoupling</link>:to separate the <emphasis>implementation</emphasis> of softwarefunctionality (which is done in &ldquo;objects&rdquo;) from the<emphasis>usage</emphasis> of this functionality in a distributed anddynamically reconfigurable software system (which is provided by&ldquo;components&rdquo;).</para></listitem></itemizedlist></para></section><section id="semantic-decoupling"><title>Semantic decoupling (Symbolic, Physical and Mathematicalproperties)</title><para>Designers of a complex software system should try hard to group thefunctionality of the system in<emphasis>semantically consistent</emphasis> modules:<itemizedlist><listitem><para>All the method calls in a module belong together&ldquo;in a natural way&rdquo;.</para></listitem><listitem><para>The interfaces of semantically appropriately decoupled modules arevery easy to understand (or document) for someone familiar with thefield.</para></listitem><listitem><para>In principle, one single person suffices to completely design,implement and document the class.</para></listitem><listitem><para>Breaking the module into smaller modules would lead to inefficienciesand &ldquo;exposure&rdquo; of the module's internals: implementationsin one module would need to know about the implementation of methodsin the other module.</para></listitem></itemizedlist>This might sound as plain common sense, but in practice, mostdesigners group functionalities together according to their<emphasis>application</emphasis> needs, and not according to theirsemantics.</para><para>In the context of robotics and machine tools, many areas are alreadysufficiently mature such that semantically consistent modules arestraightforward to recognize. Kinematics is one such area; <ulink url="http://www.orocos.org/documentation/kindyn-doc.html">one</ulink>of the other design documents describes the &ldquo;internal&rdquo; and&ldquo;external&rdquo; kinematic interfaces, i.e., on the one hand theinterfaces that deal with the joint space properties of mechanicalstructures (Jacobian matrices, singularities, redundancy resolution,efficient kinematics calculations, etc.), and on the other hand theinterfaces that deal with Cartesian motion planning and modelling.Objects that <emphasis>naturally</emphasis> show up in the context ofthe &ldquo;internal&rdquo; kinematics and dynamics are: robots,frames, velocities, forces, motor torques, singularities.</para><para>But the above-mentioned semantic decoupling can (should!) even bebrought a step further. In the end, control computers do operations onthe <emphasis>numbers</emphasis> that <emphasis>represent</emphasis>these objects, so most existing implementations provide onlymathematical representations (&ldquo;coordinates&rdquo;) of allobjects. But these mathematical representations are an incompleterepresentation of the properties of the kinematic objects: designersof a complex software system should recognize the<emphasis><link linkend="symbolic-term">symbolic</link></emphasis>,<emphasis><link linkend="physical-term">physical</link></emphasis> and<emphasis><link linkend="mathematical-term">mathematical</link></emphasis> properties of their object classes:<itemizedlist><listitem><para><anchor id="symbolic-term"><emphasis role="strong">Symbolic</emphasis> properties encode<emphasis role="strong">relationships</emphasis> or<emphasis role="strong">connections</emphasis> between objects fromdifferent classes. For example:<itemizedlist><listitem><para>Two robot links are connected by means of jointsof a certain <emphasis>type</emphasis>: revolute, prismatic, Cardan, planarcontact, etc. Both the fact that the links are connection, and thetype of the connection, are examples of symbolic information.</para></listitem><listitem><para>The six numbers that represent a robot'send-effector velocity are expressed with respect to the robot's baseframe, and in a particular set of physical units. Again, these areexamples of connection and type information.</para></listitem><listitem><para>a <emphasis>point</emphasis> in space often represents a location on a rigidbody, and hence is constrained to move together with that body. Thistopological constraint is symbolic information.</para></listitem><listitem><para>A <emphasis>line</emphasis> can be defined in several ways: theconnection between two points, the intersection between planes, thenormal on a plane, etc.  Again, this information constrains theinterpretation of the line's coordinates, and issymbolic information.</para></listitem></itemizedlist></para></listitem><listitem><para><anchor id="physical-term"><emphasis role="strong">Physical</emphasis> propertiesencode the <emphasis role="strong">real-world properties</emphasis>of an object, in a<emphasis role="strong">coordinate-independent</emphasis> way.So, physical class libraries provide the<emphasis role="strong">names of the method calls</emphasis>that correspond to the operations with physical sense.Experience has shown that the mixing up of coordinate properties(e.g., &ldquo;addition is possible&rdquo;) with physical properties(&ldquo;addition is devoid of any physical meaning&rdquo;) often leadsto inconsistent software modules, and/or to incompatibilites whenintegrating two or more of these software modules.For example:<itemizedlist><listitem><para>It is physically meaningful to add twoinstantaneous six-dimensional forces on a rigid body, but not to taketheir &ldquo;Euclidean vector in-product&rdquo;.</para></listitem><listitem><para>It is physicallymeaningful to define <emphasis>the</emphasis> relative velocity of twobodies, but not to add two such relative velocities if both areencoded with different numeric velocity representations.</para></listitem><listitem><para>It is physically meaningless <emphasis>to add</emphasis> two points ortwo lines together, even though nothing prevents this action on thenumeric coordinate representations of the two points or lines. </para></listitem><listitem><para>It is meaningful to discuss some properties of the instantaneouscenter-of-mass of a mechanical system, without having to rely oncoordinates.</para></listitem></itemizedlist>The same real-world system will often be described by<emphasis role="strong">more than one physical model</emphasis>,depending on the level of detail or computational efficiency one wantsto achieve. For example, very often simple&ldquo;lumped-parameter&rdquo; kinematics models of robots suffice,but sometimes one needs &ldquo;infinite-dimensional&rdquo; models,e.g., to represent flexibilities of robot links.The information about what physical model is used is of