doc/parts/extensions/Applications-Blockdraw-bondgraph.sxml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="formats/html.xsl"?>
   3
   4 <!-- This file is part of Shapes.                                           -->
   5 <!--                                                                        -->
   6 <!-- Shapes is free software: you can redistribute it and/or modify         -->
   7 <!-- it under the terms of the GNU General Public License as published by   -->
   8 <!-- the Free Software Foundation, either version 3 of the License, or      -->
   9 <!-- any later version.                                                     -->
  10 <!--                                                                        -->
  11 <!-- Shapes is distributed in the hope that it will be useful,              -->
  12 <!-- but WITHOUT ANY WARRANTY; without even the implied warranty of         -->
  13 <!-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          -->
  14 <!-- GNU General Public License for more details.                           -->
  15 <!--                                                                        -->
  16 <!-- You should have received a copy of the GNU General Public License      -->
  17 <!-- along with Shapes.  If not, see <http://www.gnu.org/licenses/>.        -->
  18 <!--                                                                        -->
  19 <!-- Copyright 2008, 2014, 2015 Henrik Tidefelt                             -->
  20
  21
  22 <book>
  23   <namespace>..Applications..Blockdraw</namespace>
  24   <extension>bondgraph</extension>
  25   <description>
  26     <p>Application-specific functions for bond graphs.</p>
  27   </description>
  28   <needs>
  29     <extension name="blockdraw" />
  30     <extension path="..Shapes..Layout/shiftoff" />
  31     <extension path="..Shapes..Layout/basic-layout" />
  32     <extension path="..Shapes..Graphics/arrowheads" />
  33   </needs>
  34
  35   <title><self /></title>
  36   <meta-selflink><self-href /></meta-selflink>
  37   <up-link><parent-namespace /></up-link>
  38   <base href=<!--#expand-next-string-->"$(BASE)" />
  39   <examples-home href=<!--#expand-next-string-->"$(EXAMPLES)" />
  40   <shapes-version number=<!--#expand-next-string-->"$(SHAPES_VERSION)" />
  41   <external>
  42     <!--#include virtual="^/toc.xml" -->
  43   </external>
  44
  45   <top>
  46     <alphabetical-index/>
  47     <p>A <em>bond graph</em> is graphical representation of a dynamic model in one of several analogous physical domains.  What they look like is best explained by an example.</p>
  48 <example-with-output title="Bond graph example" internal-id="bondgraph:intro">
  49 <image pdf="showcase/bonddemo_3.pdf" jpg="showcase/bonddemo_70%.jpg" />
  50 <source file="showcase/bonddemo.shape">
  51 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)showcase/bonddemo.shape" -->]]>
  52 </source>
  53 <caption>
  54   <p>A typical application of the <extension name="bondgraph" /> extension.</p>
  55 </caption>
  56 </example-with-output>
  57
  58     <p>Unlike the blocks typically used with <extension name="blockdraw" />, the corresponding elements here, the junctions, do not have a visible border and their bounding boxes are not used.  Instead, a circle of radius <dynamic name="smallblockr" />, centered at the junction's origin, defines where bonds connect with the junction.  The extension also helps with other tasks, such as drawing the unusual arrowheads and putting the effort and flow labels on the correct side of the bond.</p>
  59   </top>
  60
  61         <section id="extensions/bondgraph/junctions">
  62                 <title>Junctions</title>
  63                 <body>
  64 <example-with-output title="Junctions" internal-id="bondgraph:junctions">
  65 <image pdf="doc/bondgraph-junctions_3.pdf" jpg="doc/bondgraph-junctions_70%.jpg" />
  66 <source file="doc/bondgraph-junctions.shape">
  67 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/bondgraph-junctions.shape" -->]]>
  68 </source>
  69 <caption>
  70         <p>Four types of junctions, clarifying the meaning of the direction parameter for transformers and gyrators.</p>
  71 </caption>
  72 </example-with-output>
  73
  74                         <system-binding name="pjunction">
  75                                 <simple-value>
  76                                         <type><named-type name="Drawable" /></type>
  77                                         <description>
  78                                                 <p>A parallel (type 0) junction.</p>
  79                                         </description>
  80                                         <see-also>
  81                                                 <value name="sjunction" />
  82                                                 <value name="tfjunction" />
  83                                                 <value name="gyjunction" />
  84                                                 <value name="junction" />
  85                                         </see-also>
  86                                 </simple-value>
  87                         </system-binding>
  88
  89                         <system-binding name="sjunction">
  90                                 <simple-value>
  91                                         <type><named-type name="Drawable" /></type>
  92                                         <description>
  93                                                 <p>A serial (type 1) junction.</p>
  94                                         </description>
  95                                         <see-also>
  96                                                 <value name="pjunction" />
  97                                                 <value name="tfjunction" />
  98                                                 <value name="gyjunction" />
  99                                                 <value name="junction" />
 100                                         </see-also>
 101                                 </simple-value>
 102                         </system-binding>
 103
 104                         <system-binding name="tfjunction">
 105                                 <function>
 106                                         <case>
 107                                                 <arguments>
 108                                                         <arg identifier="arrowdir">
 109                                                                 <type><named-type name="Float" /></type>
 110                                                         </arg>
 111                                                         <arg identifier="lbl">
 112                                                                 <type><named-type name="Drawable" /></type>
 113                                                         </arg>
 114                                                 </arguments>
 115                                                 <result>
 116                                                         <type><named-type name="Drawable" /></type>
 117                                                 </result>
 118                                                 <description>
 119                                                         <p>Constructs a transformer junction.</p>
 120                                                         <p>The <arg name="arrowdir" /> value should be one of the constants for non-diagonal directions defined by <extension path="..Shapes..Layout/shiftoff" />, and tells the direction in which the arrow by the transformer is pointing (that is, not in which direction the arrow is located relative to the transformer).  The label <arg name="lbl" /> is placed outside the arrow.</p>
 121                                                 </description>
 122                                                 <see-also>
 123                                                         <value name="pjunction" />
 124                                                         <value name="sjunction" />
 125                                                         <value name="gyjunction" />
 126                                                         <value name="junctionlbl" />
 127                                                 </see-also>
 128                                         </case>
 129                                 </function>
 130                         </system-binding>
 131
 132                         <system-binding name="gyjunction">
 133                                 <function>
 134                                         <case>
 135                                                 <arguments>
 136                                                         <arg identifier="arrowdir">
 137                                                                 <type><named-type name="Float" /></type>
 138                                                         </arg>
 139                                                         <arg identifier="lbl">
 140                                                                 <type><named-type name="Drawable" /></type>
 141                                                         </arg>
 142                                                 </arguments>
 143                                                 <result>
 144                                                         <type><named-type name="Drawable" /></type>
 145                                                 </result>
 146                                                 <description>
 147                                                         <p>Constructs a gyrator junction.</p>
 148                                                         <p>This is almost like <value name="tfjunction" />, but the symbol is different, and the little arrow is never drawn; <arg name="arrowdir" /> is only used to control the position of <arg name="lbl" /> relative to the gyrator.</p>
 149                                                 </description>
 150                                                 <see-also>
 151                                                         <value name="pjunction" />
 152                                                         <value name="sjunction" />
 153                                                         <value name="tfjunction" />
 154                                                         <value name="junctionlbl" />
 155                                                 </see-also>
 156                                         </case>
 157                                 </function>
 158                         </system-binding>
 159
 160                         <system-binding name="junction">
 161                                 <function>
 162                                         <case>
 163                                                 <arguments>
 164                                                         <arg identifier="txt">
 165                                                                 <type><named-type name="Drawable" /></type>
 166                                                         </arg>
 167                                                 </arguments>
 168                                                 <result>
 169                                                         <type><named-type name="Drawable" /></type>
 170                                                 </result>
 171                                                 <description>
 172                                                         <p>This function is low-level and should not be used directly in standard applications.</p>
 173                                                         <p>Centers the argument at the origin, and sets a suitable bounding box.</p>
 174                                                 </description>
 175                                                 <see-also><value name="pjunction" /> <value name="sjunction" /> <value name="junctionlbl" /></see-also>
 176                                         </case>
 177                                 </function>
 178                         </system-binding>
 179
 180                         <system-binding name="junctionlbl">
 181                                 <function>
 182                                         <case>
 183                                                 <arguments>
 184                                                         <arg identifier="txt">
 185                                                                 <type><named-type name="Drawable" /></type>
 186                                                         </arg>
 187                                                         <arg identifier="arrowdir">
 188                                                                 <type><named-type name="Float" /></type>
 189                                                         </arg>
 190                                                         <arg identifier="lbl">
 191                                                                 <type><named-type name="Drawable" /></type>
 192                                                         </arg>
 193                                                         <arg identifier="doArrow">
 194                                                                 <type><named-type name="Boolean" /></type>
 195                                                         </arg>
 196                                                 </arguments>
 197                                                 <result>
 198                                                         <type><named-type name="Drawable" /></type>
 199                                                 </result>
 200                                                 <description>
 201                                                         <p>This function is low-level and should not be used directly in standard applications.</p>
 202                                                         <p>Extends <value name="junction" /> by also adding a label, and possibly a small arrow between the junction mark and the label.</p>
 203                                                         <p>The <arg name="arrowdir" /> value should be one of the constants for non-diagonal directions defined by <extension path="..Shapes..Layout/shiftoff" />.</p>
 204                                                 </description>
 205                                                 <see-also><value name="tfjunction" /> <value name="gyjunction" /></see-also>
 206                                         </case>
 207                                 </function>
 208                         </system-binding>
 209
 210                 </body>
 211         </section>
 212
 213         <section id="extensions/bondgraph/terminals">
 214                 <title>Terminals</title>
 215                 <body>
 216 <example-with-output title="Terminals" internal-id="bondgraph:terminals">
 217 <image pdf="doc/bondgraph-termbonds_3.pdf" jpg="doc/bondgraph-termbonds_70%.jpg" />
 218 <source file="doc/bondgraph-termbonds.shape">
 219 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/bondgraph-termbonds.shape" -->]]>
 220 </source>
 221 <caption>
 222         <p>Terminals with bonds.  The terminal, positioned at the plus mark, is connected with the serial junction.  The non-pure fuctions <value name="terminalto" /> and <value name="terminalfrom" /> will add the terminal label to a <named-statetype name="Group" /> state and return the path for the bond.  The path is then stroked with an arrowhead to indicate its extent and direction.</p>
 223 </caption>
 224 </example-with-output>
 225
 226                         <system-binding name="terminalfrom">
 227                                 <function>
 228                                         <case>
 229                                                 <arguments>
 230                                                         <state identifier="dst">
 231                                                                 <type><named-statetype name="Group" /></type>
 232                                                         </state>
 233                                                         <arg identifier="oldBlock">
 234                                                                 <type><named-type name="Drawable" /></type>
 235                                                         </arg>
 236                                                         <arg identifier="pos">
 237                                                                 <type><named-type name="Coords" /></type>
 238                                                         </arg>
 239                                                         <arg identifier="newBlock">
 240                                                                 <type><named-type name="Drawable" /></type>
 241                                                         </arg>
 242                                                 </arguments>
 243                                                 <result>
 244                                                         <type><named-type name="Path" /></type>
 245                                                 </result>
 246                                                 <description>
 247                                                         <p>Places <arg name="newBlock" /> near <arg name="pos" /> in such a position that it can be beautifully connected to <arg name="oldBlock" />, and adds it to <state-arg name="dst" /> as a side effect.</p>
 248                                                         <p>The <arg name="newBlock" /> will typically be just a label, while <arg name="oldBlock" /> is an existing junction.</p>
 249                                                         <p>The result is a path for the bond <em>from</em> <arg name="oldBlock" /> to <arg name="newBlock" />.</p>
 250                                                 </description>
 251                                                 <see-also><value name="putblockTerminal" /> <value name="bgconnect" /></see-also>
 252                                         </case>
 253                                 </function>
 254                         </system-binding>
 255
 256                         <system-binding name="terminalto">
 257                                 <function>
 258                                         <case>
 259                                                 <arguments>
 260                                                         <state identifier="dst">
 261                                                                 <type><named-statetype name="Group" /></type>
 262                                                         </state>
 263                                                         <arg identifier="oldBlock">
 264                                                                 <type><named-type name="Drawable" /></type>
 265                                                         </arg>
 266                                                         <arg identifier="pos">
 267                                                                 <type><named-type name="Coords" /></type>
 268                                                         </arg>
 269                                                         <arg identifier="newBlock">
 270                                                                 <type><named-type name="Drawable" /></type>
 271                                                         </arg>
 272                                                 </arguments>
 273                                                 <result>
 274                                                         <type><named-type name="Path" /></type>
 275                                                 </result>
 276                                                 <description>
 277                                                         <p>Places <arg name="newBlock" /> near <arg name="pos" /> in such a position that it can be beautifully connected to <arg name="oldBlock" />, and adds it to <state-arg name="dst" /> as a side effect.</p>
 278                                                         <p>The <arg name="newBlock" /> will typically be just a label, while <arg name="oldBlock" /> is an existing junction.</p>
 279                                                         <p>The result is a path for the bond <em>to</em> <arg name="oldBlock" /> from <arg name="newBlock" />.</p>
 280                                                 </description>
 281                                                 <see-also><value name="putblockTerminal" /> <value name="bgconnect" /></see-also>
 282                                         </case>
 283                                 </function>
 284                         </system-binding>
 285
 286                         <system-binding name="putblockTerminal">
 287                                 <function>
 288                                         <case>
 289                                                 <arguments>
 290                                                         <arg identifier="newBlock">
 291                                                                 <type><named-type name="Drawable" /></type>
 292                                                         </arg>
 293                                                         <arg identifier="pos">
 294                                                                 <type><named-type name="Coords" /></type>
 295                                                         </arg>
 296                                                         <arg identifier="oldBlock">
 297                                                                 <type><named-type name="Drawable" /></type>
 298                                                         </arg>
 299                                                 </arguments>
 300                                                 <result>
 301                                                         <type><named-type name="Drawable" /></type>
 302                                                 </result>
 303                                                 <description>
 304                                                         <p>This function is low-level and should not be used directly in standard applications.</p>
 305                                                         <p>Places <arg name="newBlock" /> near <arg name="pos" /> in such a position that it can be beautifully connected to <arg name="oldBlock" />.</p>
 306                                                 </description>
 307                                                 <see-also><value name="terminalto" /> <value name="terminalfrom" /></see-also>
 308                                         </case>
 309                                 </function>
 310                         </system-binding>
 311                 </body>
 312         </section>
 313
 314         <section id="extensions/bondgraph/bonds">
 315                 <title>Bonds</title>
 316                 <body>
 317 <example-with-output title="Painting bonds" internal-id="bondgraph:bonds">
 318 <image pdf="doc/bondgraph-bonds_3.pdf" jpg="doc/bondgraph-bonds_70%.jpg" />
 319 <source file="doc/bondgraph-bonds.shape">
 320 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/bondgraph-bonds.shape" -->]]>
 321 </source>
 322 <caption>
 323         <p>Various means to paint a bond path.  In the top row, the extent and direction of the path is indicated using a standard stroke with an arrowhead.  The second row shows how <value name="bondgraphArrow" /> may be used to produce arrowheads suited for bond graph bonds, but note that direct use of these arrowheads is considered low-level, and the user should use the convenience function illustrated in the last row instead.</p>
 324 </caption>
 325 </example-with-output>
 326
 327                         <system-binding name="bgconnect">
 328                                 <function>
 329                                         <case>
 330                                                 <arguments>
 331                                                         <arg identifier="pica">
 332                                                                 <type><named-type name="Drawable" /></type>
 333                                                         </arg>
 334                                                         <arg identifier="picb">
 335                                                                 <type><named-type name="Drawable" /></type>
 336                                                         </arg>
 337                                                 </arguments>
 338                                                 <result>
 339                                                         <type><named-type name="Path" /></type>
 340                                                 </result>
 341                                                 <dynamic-references><dynamic name="smallblockr" /></dynamic-references>
 342                                                 <description>
 343                                                         <p>Constructs the path that shall be used for drawing the bond between junctions.</p>
 344                                                         <p>If terminal points are involved, the convenience functions <value name="terminalto" /> or <value name="terminalfrom" /> may produce the path instead.</p>
 345                                                 </description>
 346                                         </case>
 347                                 </function>
 348                         </system-binding>
 349
 350                         <system-binding name="ubond">
 351                                 <function>
 352                                         <case>
 353                                                 <arguments>
 354                                                         <arg identifier="p">
 355                                                                 <type><named-type name="Path" /></type>
 356                                                         </arg>
 357                                                 </arguments>
 358                                                 <result>
 359                                                         <type><named-type name="Drawable" /></type>
 360                                                 </result>
 361                                                 <dynamic-references><dynamic name="connectionlw" /></dynamic-references>
 362                                                 <description>
 363                                                         <p>Draws a bond along the path <arg name="p" />, with <em>undetermined</em> causality (that is, without a causality mark).</p>
 364                                                         <p>The size of the arrowhead may be changed using <dynvar extension="bondgraph" name="bgArrowWidth" />, see <dynvar extension="bondgraph" name="bondgraphArrow" />.</p>
 365                                                 </description>
 366                                         </case>
 367                                 </function>
 368                         </system-binding>
 369
 370                         <system-binding name="hbond">
 371                                 <function>
 372                                         <case>
 373                                                 <arguments>
 374                                                         <arg identifier="p">
 375                                                                 <type><named-type name="Path" /></type>
 376                                                         </arg>
 377                                                 </arguments>
 378                                                 <result>
 379                                                         <type><named-type name="Drawable" /></type>
 380                                                 </result>
 381                                                 <dynamic-references><dynamic name="connectionlw" /></dynamic-references>
 382                                                 <description>
 383                                                         <p>Draws a bond along the path <arg name="p" />, placing a causality mark at the <em>head</em> of the path.</p>
 384                                                         <p>The size of the arrowhead may be changed using <dynvar extension="bondgraph" name="bgArrowWidth" />, see <dynvar extension="bondgraph" name="bondgraphArrow" />.</p>
 385                                                 </description>
 386                                         </case>
 387                                 </function>
 388                         </system-binding>
 389
 390                         <system-binding name="tbond">
 391                                 <function>
 392                                         <case>
 393                                                 <arguments>
 394                                                         <arg identifier="p">
 395                                                                 <type><named-type name="Path" /></type>
 396                                                         </arg>
 397                                                 </arguments>
 398                                                 <result>
 399                                                         <type><named-type name="Drawable" /></type>
 400                                                 </result>
 401                                                 <dynamic-references><dynamic name="connectionlw" /></dynamic-references>
 402                                                 <description>
 403                                                         <p>Draws a bond along the path <arg name="p" />, placing a causality mark at the <em>tail</em> of the path.</p>
 404                                                         <p>The size of the arrowhead may be changed using <dynvar extension="bondgraph" name="bgArrowWidth" />, see <dynvar extension="bondgraph" name="bondgraphArrow" />.</p>
 405                                                 </description>
 406                                         </case>
 407                                 </function>
 408                         </system-binding>
 409
 410                         <dynamic-variable name="bgArrowWidth">
 411                                 <type><named-type name="Length" /></type>
 412                                 <default><physical><scalar>4</scalar><unit>bp</unit></physical></default>
 413                                 <description>
 414                                         <p>The width of the half arrowhead used for bonds.</p>
 415                                 </description>
 416                                 <see-also><value name="bondgraphArrow" /></see-also>
 417                         </dynamic-variable>
 418
 419                         <system-binding name="bondgraphArrow">
 420                                 <function>
 421                                         <case>
 422                                                 <arguments>
 423                                                         <arg identifier="p">
 424                                                                 <type><named-type name="Path" /></type>
 425                                                         </arg>
 426                                                         <arg identifier="doHook">
 427                                                                 <type><named-type name="Boolean" /></type>
 428                                                                 <default><const-false /></default>
 429                                                         </arg>
 430                                                         <arg identifier="doCausal">
 431                                                                 <type><named-type name="Boolean" /></type>
 432                                                                 <default><const-false /></default>
 433                                                         </arg>
 434                                                         <arg identifier="ahAngle">
 435                                                                 <type><named-type name="Float" /></type>
 436                                                                 <default><eq>30°</eq></default>
 437                                                         </arg>
 438                                                         <arg identifier="fillAsStrokeing">
 439                                                                 <type><named-type name="Boolean" /></type>
 440                                                                 <default><eq><const-true /></eq></default>
 441                                                         </arg>
 442                                                 </arguments>
 443                                                 <result>
 444                                                         <type>
 445                                                                 <structure-type>
 446                                                                         <field name="picture"><type><named-type name="Drawable" /></type></field>
 447                                                                         <field name="cut"><type><named-type name="Length" /></type></field>
 448                                                                 </structure-type>
 449                                                         </type>
 450                                                 </result>
 451                                                 <dynamic-references>Whole graphics state and <dynvar extension="bondgraph" name="bgArrowWidth" /></dynamic-references>
 452                                                 <description>
 453                                                         <p>This function is low-level and should not be used directly in standard applications.</p>
 454                                                         <p>Arrowhead for bond graph junctions.  All arguments but <arg name="doHook" /> and <arg name="doCausal" /> have the same meaning as for <value namespace="..Shapes..Graphics" name="MetaPostArrow" />.</p>
 455                                                         <p>When <arg name="doHook" />, the half arrowhead is produced, and when <arg name="doCausal" />, the causality mark is produced.  This is like two different kinds of arrowheads combined in one function.</p>
 456                                                 </description>
 457                                                 <see-also><value name="hbond" /> <value name="tbond" /></see-also>
 458                                         </case>
 459                                 </function>
 460                         </system-binding>
 461
 462                 </body>
 463         </section>
 464
 465         <section id="extensions/bondgraph/labels">
 466                 <title>Effort and flow labels</title>
 467                 <body>
 468 <example-with-output title="Positioning labels" internal-id="bondgraph:labels">
 469 <image pdf="doc/bondgraph-labels_3.pdf" jpg="doc/bondgraph-labels_70%.jpg" />
 470 <source file="doc/bondgraph-labels.shape">
 471 <![CDATA[<!--#include depth="0" virtual="$(BUILDDIR)$(EXAMPLES)doc/bondgraph-labels.shape" -->]]>
 472 </source>
 473 <caption>
 474         <p>Positioning effort and flow labels on the correct side of a bond, as defined by the side of the asymmetric arrowhead.</p>
 475 </caption>
 476 </example-with-output>
 477
 478                         <system-binding name="flowlabel">
 479                                 <function>
 480                                         <case>
 481                                                 <arguments>
 482                                                         <arg identifier="p">
 483                                                                 <type><named-type name="Path" /></type>
 484                                                         </arg>
 485                                                         <arg identifier="lbl">
 486                                                                 <type><named-type name="Drawable" /></type>
 487                                                         </arg>
 488                                                 </arguments>
 489                                                 <result>
 490                                                         <type><named-type name="Drawable" /></type>
 491                                                 </result>
 492                                                 <description>
 493                                                         <p>Places <arg name="lbl" /> on the flow side of the bond along <arg name="p" />.</p>
 494                                                 </description>
 495                                         </case>
 496                                 </function>
 497                         </system-binding>
 498
 499                         <system-binding name="effortlabel">
 500                                 <function>
 501                                         <case>
 502                                                 <arguments>
 503                                                         <arg identifier="p">
 504                                                                 <type><named-type name="Path" /></type>
 505                                                         </arg>
 506                                                         <arg identifier="lbl">
 507                                                                 <type><named-type name="Drawable" /></type>
 508                                                         </arg>
 509                                                 </arguments>
 510                                                 <result>
 511                                                         <type><named-type name="Drawable" /></type>
 512                                                 </result>
 513                                                 <description>
 514                                                         <p>Places <arg name="lbl" /> on the effort side of the bond along <arg name="p" />.</p>
 515                                                 </description>
 516                                         </case>
 517                                 </function>
 518                         </system-binding>
 519                 </body>
 520         </section>
 521
 522 </book>