XMLlab-1.4 software getting started guide

Stéphane Mottelet

André Pauss

iode Conseil (www.iode-conseil.com)

XMLlab is a project financed by the regional pole STEF of Picardie and the UNIT consortium.


Table of contents

1. Introduction
2. Installing the software
1. Installing Scilab 3.1.1
1.1. Windows 9X/NT/2000/XP
1.2. Mac OS X.3
1.3. Linux
2. Installing XMLlab-1.4
2.1. Windows 9X/NT/2000/XP
2.2. Mac OS X.3 and Linux
2.3. Uninstalling XMLlab-1.4
2.4. XMLlab-1.4 Installation test through a simulation exemple
2.5. Uninstalling XMLlab-1.4
3. Using the software
1. Physical description of the simulation
2. Logic of the description in XML of the simulation
2.1. General description of the simulation
2.2. Simulation Parameters
2.3. Simulation mathematicals models
2.4. Simulation results display
3. Simulation enrichment  example
3.1. Creation of the pointelement allowing to settle θ 0
3.2. Addition of the segment representing the forcing curve point0
3.3.  Addition of the point0 visualization
3.4. Simulation new version test

List of figures

2.1. Parameters example of a pendulum simulation
2.2. Visualization of the pendulum simulation result
3.1. The pendulum
3.2. Parameters menu entries of the Pendulum simulation
3.3. Resolution parameters data entry
3.4. Visualization of the pendulum simulation result
3.5. Interactive modification of the θ 0 parameter

List of equations

3.1. Real equation of the pendulum movement
3.2. Linearized equation of the pendulum movement

Chapter 1. Introduction

XMLlab is a toll, developed by Stéphane Mottelet and André Pauss at the Université de Technologie de Compiègne, allowing to generate simulations automatically. The description of a simulation is based on XML and includes the following elements:

  • the mathematical models of objects (time dependant or not) describing the simulation,

  • the description of physical parameters description involved in these models,

  • the IHM allowing to act on these physical parameters and to visualize simulation.

The Scilab software is used to calculate and visualize in real time the result of generated simulation, the IHM allowing to regulate the parameters of these one being delegated to Tcl/Tk.

(sources : http://www.xmllab.org/, http://scilabsoft.inria.fr/, http://wiki.tcl.tk/ and http://www.tcl.tk/)

Chapter 2. Installing the software

1. Installing Scilab 3.1.1

It is an indispensable prerequired to the installation and the use of XMLlab.

1.1. Windows 9X/NT/2000/XP

  • go to the page of Scilab download in the INRIA Web site:

    http://scilabsoft.inria.fr/download/index_download.php?page=release.html.

  • In the frame For Windows 9X/NT/2000/XP platforms, click on the link Scilab-3.1.1 installer for binary version, that starts the downloading of the scilab-3.1.1.exe installation executable (also directly accessible from http://scilabsoft.inria.fr/download/stable/scilab-3.1.1.exe).

  • Double-click on the executable scilab-3.1.1.exe to start the installation :

    • Installation assistant language : keep English and click on OK.

    • Welcome to scilab-3.1.1installation: close all the active applications and then click on Next button >.

    • License agreement : read the license, tick on the box "I accept the terms of the contract" and click on Next button >.

    • Destination file: keep the proposed emplacement or select another one by clicking the browse button ..., and select Next button > (we will suppose in the continuation that the path chosen at this stage is C:\Program Files\scilab-3.1.1).

    • Components to install: don't change the proposed installation configuration (this one requires approximately 80 Mo disk space), and click on Next button >.

    • Selection of the folder at the Start Menu : keep the proposed name, or choose another one, and click on Next button >.

    • Suplementary task : keep the proposed choice (in particular those of the heading association Files:), or make others, and click on Next >.

    • Ready to install: Go through the synthesis of the installation options chosen, and click on Install >.

    • Installation : Wait during the installation process.

    • Informations : Go through and click on Next >.

    • End of the installation of scilab-3.1.1 : choose or not to execute scilab immediately, and click on Finish button .

1.2. Mac OS X.3

This installation requires the installation of fink and of the Apple X11 server:

  • The installation and the use of fink requires a minimal knowledge of the Unix system of Mac OS X , in particular the Terminal utilisation . The fink download page http://fink.sourceforge.net/download/index.php?phpLang=fr explain in detail the procedure of fink downloading.

  • The Apple X11 server can be download from the page http://www.apple.com/downloads/macosx/apple/x11formacosx.html, by clicking on the downloading link. The installation doesn't shows particular difficulties.

Once these two installations are completed, the installation itself of Scilab can begin :

  • Go to page http://www.lmac.utc.fr/~mottelet/Darwin/ and click on the link scilab-gtk_3.1.1_darwin.tgz, wich starts the downloading of the compressed archives scilab-gtk_3.1.1_darwin.tgz (also directly accessible from http://www.lmac.utc.fr/~mottelet/Darwin/scilab-gtk_3.1.1_darwin.tgz).

  • Connect as root in a Terminal window and type the following commands :

    tar xvzf scilab-gtk_3.1.1_darwin.tgz -C /
    fink scanpackages
    apt-get update
    apt-get install scilab-gtk

    The installation of scilab also requires then the automatic downloading and the installation of pre-required software (gnome, gtk...), answer Yes to the confirmation demand of installation of these packages.

  • Also download the file scilab.dmg, that is a self-mounting archive that contains a small Mac OS X application allowing to start Scilab by double clicking on the icon.

1.3. Linux

  • Go to the Scilab downloading page on the INRIA website : http://scilabsoft.inria.fr/download/index_download.php?page=release.html.

  • In the frame For GNU/Linux platforms, click to the link Scilab-3.1.1 binary file version for Linux, that starts the downloading of the compressed archives scilab-3.1.1.bin.linux-i686.tar.gz (also directly accessible from http://scilabsoft.inria.fr/download/stable/scilab-3.1.1.bin.linux-i686.tar.gz).

  • Caution: This binary version having been compiled with libc.so.6 related to libc-2.3.X.so, it could not work on old distributions of GNU/Linux for which libc.so.6 is related to older library libc. If such were to be the case, it would be necessary to download Scilab-3.1.1 source version (http://scilabsoft.inria.fr/download/stable/scilab-3.1.1.src.tar.gz), decompress the archive and follow the procedure of compilation and installation described in the file README_Unix.

  • Decompress the downloaded archive, place yourself in the repertory scilab-3.1.1 obtained and run the installation by typing the following command : make

2. Installing XMLlab-1.4

The first part of the procedure is independant of the installation platform :

  • Go to the XMLlab website : http://xmllab.org/.

  • Click the french version , and then on the link Installation.

The second part is dependant of the relating platform :

2.1. Windows 9X/NT/2000/XP

  • Click on the link XMLlab-1.4-Win32.zip, that starts the downloading of the installation executable XMLlab-1.4-Win32.zip (also directly accessible from http:/xmllab.org/XMLlab-1.4-Win32.zip).

  • Decompress the downloaded archive and move the repertory XMLlab obtained towards its destination of installation rep_xmllab, for example C:\Program Files\XMLlab.

  • Caution: if an older XMLlab version was already installed, it is preferable to uninstall it.

    Start Scilab by double clicking on its icon or from the Start menu . Then choose the file->Exec and select the file builder.sce in the repertory rep_xmllab and click on OK.

    If you don't need to be able to execute your simulation outside of Scilab environement, you can pass directly to the section "Installation test".

  • If you wish to be able to execute the simulations starting from command line DOS, add the following paths to the environment variable Path of the system :

    • rep_xmllab\Windows NT\bin

    • rep_xmllab\Windows NT\lib

    To do so (under Windows NT/2000/XP) :

    • Open the panel System configuration , click on the Advanced tab , and on the Environment Variable button...,

    • In the window opened, select in the zone: variable system , the variable Path line then click on the button Modify...,

    • In the input opened box, position the cursor at the end of the field variable value: and add the paths by separating them by one ";",

    • Click on OK, then again on OK, and a last time on OK.

2.2. Mac OS X.3 and Linux

The beginning of the installation is differentiated according to the platform :

  • Mac OS X.3 :

    • Click on the link XMLlab-1.4-Darwin.tgz, that starts the downloading of the XMLlab-1.4-Darwin.tgz executable installation (also directly accessible from http://xmllab.org/XMLlab-1.4-Darwin.tgz).

    • Decompress the downloaded archive and move the repertory XMLlab obtained towards its installation destination rep_xmllab, for example /Applications/XMLlab.

      Start Scilab by double-clicking on it's icon. Then choose File->File Operations, select the file builder.sce in the repertory rep_xmllab and choose exec in the operations menu and click on OK.

      If you don't need to be able to execute your simulation outside of Scilab environment, you can pass directly to the section "Installation test".

    • If you wish to be able to execute the starting simulations from command line, add the next line to the file .profile being in your user repertory

      export PATH=rep_xmllab/Darwin/bin:$PATH
  • Linux :

    • Click on the link XMLlab-1.4-Linux.tgz, that starts the downloading of the installation executable XMLlab-1.4-Linux.tgz (also directly accessible from http://xmllab.org/XMLlab-1.4-Linux.tgz).

    • Decompress the downloaded archive and move the repertory XMLlab obtained towards its installation destination rep_xmllab, for example /usr/local/XMLlab.

    • Caution: if an older XMLlab version is already installed, it is preferable to uninstall it.

      Enter the following commands in the Unix terminal (replace fr for eng to obtain anenglish installation) :

      cd rep_xmllab
      scilab -l fr -f builder.sce

      If you don't need to be able to execute your simulation outside of Scilab environment, you can pass directly to the section "Installation test".

    • If you wish to be able to execute the simulations starting from command line, add the next line to the file .bash_profile being in your user repertory

      export PATH=rep_xmllab/Linux/bin:$PATH

The lines above describe an installation in the System Repertories, but it is completely possible to choose a repertory belonging to an ordinary user. When it is expected that several users use XMLlab on the same machine, is enough to proceed to the installation only once (by executing the script builder.sce). Then each new user will have to execute the script setup.sce located in the repertory rep_xmllab.

2.3. Uninstalling XMLlab-1.4

To uninstall XMLlab choose the item from the XMLlab menu->Uninstalling XMLlab .

2.4. Installation test of XMLlab-1.4 through a simulation example

  • Start Scilab from the Start menu (Windows) or from its icon (Mac OSX) or from the command line (Linux) : scilab.

  • Select XMLlab->Demos XMLlab, and choose then for an example Physics, and Pendulum.

  • Two windows then appear :

    • A window allowing to settle the pendulum simulation parameters (Parameters->Parameters of a pendulum) and those of the resolution of the differential equations allowing to calculate the angle of the pendulum compared to its equilibrium position, in relation to its length, to the initial angle and to the acceleration of the gravity (Parameter->Resolution Parameters) :

      Figure 2.1. Parameters example of a pendulum simulation

      Paramètres de l'exemple de simulation d'un pendule
    • A window allowing to visualize the evolution, during a given interval of time, of the pendulum angle compared to its vertical position, according to whether this one is exactly calculated by solving the differential equations governing the pendulum behavior (Real solution) or that it is approached by a calculation making the assumption of its smallness (Linearized solution). :

      Figure 2.2. Visualization of the pendulum simulation result

      Visualisation du résultat de la simulation d'un pendule
  • Let us specify that there are other possibilities to run a XMLlab simulation :

    • From Scilab, via the menu XMLlab->Demos XMLlab, following-up the choice of the XML corresponding file.

    • From the Unix or Scilab commande line, position yourself in the repertory containing the XML file and type the following command:

      xmllab -run nom_simulation.xml

2.5. Uninstallating XMLlab-1.4

Run Scilab and select the entry menu XMLlab->Uninstalling XMLlab.

Chapter 3. Using the software

We will now present the bases XMLlab use. To do so, we will study the structure of the pendulum simulation previously seen and extend it, to add it a new functionality allowing to vary the initial angle of the pendulum by acting directly on the Scilab graph.

1. Physical description of the simulation

Figure 3.1. The pendulum

Le pendule

Let us consider the pendulum represented on Figure 3.1, « The pendulum ». This pendulum consists in a mass M considered punctual and a rod length L of negligible weight compared to M. The weight is directed upwards according to a vertical axis. The pendulum movement is a planar movement of rotation center O.

The position of the pendulum compared to its stable equilibrium position is characterized by the angle θ ( t ) , defined positively as indicated on the figure. It is considered that the pendulum is released without intial speed, starting from a position θ 0 .

We apply the fundamental principles of dynamics for the setting constituted by the rod and the mass. To obtain the equation of movement, just write the moment equations, for example in O : the dynamic moment at the point O of the pendulum is equal to the moment in O of external actions on the pendulum. The following equation is obtained : J θ ¨ ( t ) = M g L sin θ ( t ) where J = M L 2 is the moment of inertia of the pendulum at the point O . After simplification, the following differential equation is obtained :

if θ ( t ) is low, we have: sin θ ( t ) θ ( t ) , that enables us to integrate the earlier differential equation. We have then:

2. Logic of the description in XML of the simulation

We will show how this simulation is translated into a XML file that the tool XMLlab will use to generate a simulation executed by Scilab. The XML file will be shown in its textual form, and occasionally also such as it appears at the time of its edition with the software XMLMind XML Editor (xxe, cf. http://www.xmlmind.com/xmleditor/). Such a software allows a good visualization of the structure of a file XML, as its modification is facilitated by the fact that it permanently presents; the totaly of the tags which can be added to each place, as well as the totaly of the attributes of a given tag, with if necessary their various allowed values.

2.1. General description of the simulation

The first two lines of the file allows to associate the DTD of XMLlab to XML file and they are identical for any simulation. They must be modified only at the time of an XMLlab update implying an evolution of the DTD (here in version 1.4).

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE simulation PUBLIC "-//UTC//DTD XMLlab V1.4//FR" "http://www.xmllab.org/dtd/1.4/simulation.dtd">

The following lines make possible to specify the title of simulation, its author, as well as the keywords related to it :

<simulation>
  <header>
    <title>Pendulum</title>
    <author>Please set author's name</author>
    <keywords>simulation,scilab,xml</keywords>
  </header>
  ...
</simulation> 

2.2. Simulation Parameters

The Simulation Parameters can be grouped in several sections, every section giving place to a different entry from the Simulation Parameters menu, as shown in the following figure :

Figure 3.2 Parameters menu entries of the Pendulum simulation

Entrées du menu Paramètres de la simulation du pendule

The choice of an entry then causes, the display of the corresponding parameters in the window . The following lines introduce and name the sections of parameters :

  <parameters>
    <section>
      <title>Pendulum Parameters</title>
      ...
    </section>
    <section>
      <title>Resolution Parameters</title>
      ...
    </section>
  </parameters>

We are now going to describe in detail the statement of the parameters of eacg section, which the corresponding lines appear after the tag <title> in question :

  • Pendulum Parameters : The following lines describe each one of these parameters which their entry is made in the window illustrated by Figure 3.2, « Parameters menu entries of the Pendulum simulation » :

    • Length L of pendulum :

            <scalar label="L"
                    unit="m"
                    widget="entry">
              <name>Length of the pendulum</name>
              <value>1</value>
            </scalar>

      The parameter value is entered via a text field and its initial value is 1. The attribute label is used to refer to this parameter in the continuation (L).

    • Initial angle θ 0 of the pendulum :

            <scalar increment="0.001"
                    label="theta_0"
                    max="3.141"
                    min="0.01"
                    unit="rad"
                    widget="slider">
              <name>Initial angle</name>
              <value>0.1</value>
            </scalar>

      The value of the parameter is adjustable via a slider going from 0.01 to 3.141 and adjustable at near 0.001. It is there refered via the label theta_0.

    • Gravity g :

            <scalar label="g0"
                    unit="ms^-2"
                    widget="entry">
              <name>Gravity</name>
              <value>9.81</value>
            </scalar>

      The parameter value is entered via a text field and its initial value is 9.81. It is there refered via the label g0.

  • Resolution Parameters : The following lines describe each parameter which their entry is made in the window illustrated by the following figure :

    Figure 3.3. Resolution parameters entry

    Saisie des paramètres de résolution
    • Upper limit t f of the interval discretization [ 0, t f ] used for the resolution of the differential equation giving the real pendulum movement (cf. Equation 3.1, « Real equation of the pendulum movement  ») :

            <scalar label="tf"
                    unit="s"
                    widget="entry">
              <name>Final time</name>
              <value>2</value>
            </scalar>

      The parameter value is entered via a text field and its initial value is 2. It is there refered via the label tf.

2.3. Simulation mathematicals models

This section - which follows the tag </parameters> - allows to define the equations to be solved, the curves to be calculated, as well as the fields of values (1d or 2d) that some variables must take. These various definitions are framed by the following tags :

  <compute>
  ...
  </compute>

As regards to our pendulum problem, the following elements are defined :

  • Definition of the variable of integration and its interval of discretization [ 0, t f ] used for the resolution of the differential equation giving the real pendulum movement (cf. Equation 3.1, « Real equation of the pendulum movement ») :

        <defdomain1d label="t"
                     unit="s">
          <name>Temps</name>
          <interval discretization="linear"
                    steps="200">
            <initialvalue>0</initialvalue>
            <finalvalue>tf</finalvalue>
          </interval>
        </defdomain1d>

    It is indicated that the interval [ 0, t f ] is cut out linearly in 200 steps. It is refered to the variable of integration and its field of variation via the label t.

  • Definition of the element ode ( ordinary differential equation ) grouping together the reference to the variable of integration and to its domain of variation, the definition of states θ and θ ˙ , as well as the list of the outputs, the only output being here the function giving the linearized solution φ ( t ) of the value θ :

        <ode label="pendulum">
          <refdomain1d ref="t"/>
          <states>
          ...
          </states>
          <outputs>
          ...
          </outputs>
        </ode>

    Overall picture of the element ode and the element refdomain1d defining the reference to the variable of integration t.

    • states element defining the states θ and θ ˙ :

            <states>
              <state label="theta"
                     unit="rad">
                <name>Real solution</name>
                <derivative>theta_point</derivative>
                <initialcondition>theta_0</initialcondition>
              </state>
              <state label="theta_point"
                     unit="rad">
                <name>angle derived</name>
                <derivative>-g0/L*sin(theta)</derivative>
                <initialcondition>0</initialcondition>
              </state>
            </states>

      The states theta and theta_point are defined, with for each one of them the derived (function of the other states) and the initial value taken for the initial value of the variable of integration t.

    • Outputs elements defining as only output the function giving the linearized solution φ ( t ) :

            <outputs>
              <output label="thetalin">
                <name>Linearized solution</name>
                <value>theta_0*cos(sqrt(g0/L)*t)</value>
              </output>
            </outputs>

      The function of the linearized solution is identified by the label thetalin.

2.4. Simulation results display

This section - which follows the tag </compute> - allows to define the various graphic windows, a set of system of axes for each one of it (windows which can then divide horizontally or vertically to contain them), as well as the curves which must be respectively displayed in each system of axis. These various definitions are framed by the following tags :

  <display>
  ...
  </display>

In our case, a single window includes one system of Cartesian axis containing the curves of the real and the linearized solutions :

  • Definition of the window :

        <window>
          <title>Comparison of both solutions</title>
          <axis2d xmax="tf" xmin="0"
                  ymax="theta_0" ymin="-theta_0">
            <drawcurve2d color="auto"
                         ref="theta" thickness="2" />
            <drawcurve2d color="red"
                         ref="thetalin" thickness="2" />
          </axis2d>
        </window>

    The title of the window is indicated, which includes a system of Cartesian axis 2D, x varying from 0 to t f and y varying from θ 0 to θ 0 . The system of axis defined contains the curve of the real solution (state theta) and that of the linearized solution (output thetalin).

The following curves thus are obtained :

Figure 3.4. Visualization of the pendulum simulation result

Visualisation du résultat de la simulation d'un pendule

3. Simulation enrichment  example

We are now going to develop the pendulum simulation to allow us to make vary θ 0 by acting directly on the point ( 0, θ 0 ) on the Scilab graph.

This element replaces the scalar element defining the parameter theta_0. It is defined by its abscissa and its ordinate as well as the reference to a curve to which it is constrained to belong :

  <parameters>
    <section>
      <title>Parameters of the pendulum</title>
      ...
      <point label="point0"
             widget="hidden">
        <x1 label="zero">
          <value>0</value>
        </x1>
        <x2 label="theta_0">
          <value>0.1</value>
        </x2>
        <constraints>
          <curve ref="segment" />
        </constraints>
      </point>
      ...

The point is identified by the label point0, its abscissa by the label zero (initial value 0), and its ordinate by the label theta_0 (initial value 0.1) which is the parameter which we want to be able to adjust interactively. It does not here contain any interface of explicit seizure, but its graphic representation is manipulable (cf. Section 3.3, « Addition of the visualization of point0 »).

The point is constrained to remain on the curve segment that we now will define.

3.2. Addition of the segment representing the forcing curve point0

This element is added in the section compute and is defined by the coordinates of its two extremities :

  <compute>
    ...
    <polyline label="segment">
      <vertex x1="0" x2="0"></vertex>
      <vertex x1="0" x2="3.141"></vertex>
    </polyline>
    ...

The element polyline is a multiple-line curve defined by all the points (elements vertex) of the segments composing it.

We define here a single segment (named segment) which the ordinates of the points constituent it, represent the possible values for the parameter theta_0. For more information about the segment element, refer to the document XMLlab-1.4 Software Reference Manual, in § Tag polyline of the chapter referring the elements taking part in the simulation description.

3.3. Addition of the point0 visualization

Consists of the addition of a drawpoints element to the system of existing axis :

  <display>
    <window ...>
      <title>Comparison of both solutions</title>
      <axis2d ...>
        <drawcurve2d ...
                     ref="theta" ... />
        <drawcurve2d ...
                     ref="thetalin" ... />
        <drawpoints ref="point0" />
      </axis2d>
    </window>
  </display>

The drawpoints element is defined by the reference to the point element which it represents.

3.4. Simulation new version test

The following figure illustrates the use of the point point0 added to modify θ 0 :

Figure 3.5. Interactive modification of the θ 0 parameter

Modification interactive du paramètre θ 0

The point is represented by a cross situated in the top of the Y axis. To modify the parameter theta_0, click on the cross, the coordinates of point0 (whose the ordinate is theta_0) then displays. Move the cursor above or below the cross, as it is a question of increasing or decreasing theta_0 (curves are real time recalculated). Once the value wished obtained, click again the cross to fix the value of theta_0.