XMLlab-1.4 Software reference manual

Stéphane Mottelet

André Pauss

iode Conseil (www.iode-conseil.com)

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


Table of contents

1. Introduction
2. Kinetics of prey predation by predators
. Mathematical description of the simulation
2. Logics of the description in XML of the simulation
2.1. General description
2.2. Parameters
2.2.1. Kinetic parameters
2.2.2.  Initial oncentrations
2.2.3. Simulation time
2.3. Mathematical Models
2.3.1. Definition of the integration variable time and its discretization interval [ 0, final _ time ]
2.3.2. Definition of the differential equations
2.3.3. Definition of the phase picture Prey against Predator
2.4. Results display
2.5. Saving simulation results
2.5.1. Saving simulation results
3. Simulation of monoacides titration
1. Chemical description of the simulation
1.1. Calculation principle
1.2. Characteristics of the analyte and titrant species
1.3.  Partition coefficients
1.4. Titration data
1.5. Equations
1.5.1. Electric charge of the medium calculation
1.5.2. Partition coefficients calculation
2. Logics of the description in XML of the simulation
2.1. General description
2.2. Parameters
2.2.1. Analyte choice
2.2.2. Titrant choice
2.2.3. Titration  parameters
2.2.4. Experimental data
2.3. Mathematical models
2.3.1. Definition of the titrant concentration
2.3.2. pH calculation using the dichotomic method
2.3.3. Definition of the experimental data curve
2.4. Results display
2.5. Session and results simulation saving
2.5.1. Saving and downloading the session
2.5.2. Saving the results of the simulation
4. Finite elements: simulation of the Poisson's equation
1. Physical description of the simulation
2. Logics of the description in XML of the simulation
2.1. General description
2.2. Parameters
2.2.1. Discretization parameters
2.3. Mathematical Models
2.3.1. Definition of the variable thetain and of its interval of discretization [0, 2π]
2.3.2. Definition of the variable thetaout and of its interval of discretization [0, 2π]
2.3.3.  Definition of the domaine Ω
2.3.4. Definition of the stationary partial derivatives
2.4. Results display
5. Simulation of Earth-Moon system
1. Physical description of the simulation
2. Logics of the simulation description in XML
2.1. General description
2.2. Parameters
2.2.1. System parameters
2.2.2. Solving parameters
2.3. Mathematical models
2.3.1. Definition of the variable t and of its discretization interval [0, T]
2.3.2. Definition of the differential equations
2.3.3. Definition of the parametric curve giving the trajectory of the earth
2.3.4. Definition of the parametric curve giving the trajectory of the moon
2.4. Results display
6.  Reference of the elements participating in the description of a simulation
1. General description
1.1 File and simulation headings
1.2. Notes about the simulation
2. Parameters
2.1. Subsection Tag
2.2. Database Tag
2.3. Group Tag
2.4. Scalar Tag
2.5. Matrix Tag
2.6. Point Tag
2.7. Record Tag
3. Actions
4. Script or mathematical models
4.1. Script
4.2. Mathematical models
4.2.1. Defdomain1d and refdomain1d Tags
4.2.2. Defdomain2d and refdomain2d Tags
4.2.3. Ode Tag
4.2.4. Implicitfunction Tag
4.2.5. Stationary-pde Tag
4.2.6. Nonparametriccurve2d Tag
4.2.7. Parametriccurve2d Tag
4.2.8. Parametriccurve3d Tag
4.2.9. Nonparametricsurface Tag
4.2.10. Parametricsurface Tag
4.2.11. Polyline Tag
5. Results display
5.1.  Systems of axes
5.1.1. Axis2d Tag
5.1.2. Axis3d Tag
5.2. Curves and surfaces
5.2.1. Drawcurve2d Tag
5.2.2. Drawcurve3d Tag
5.2.3. Drawsurface Tag
5.2.4. Drawpoints Tag
6. Saving simulation results
7. XMLlab command and menus line
1. Command line
2. XMLlab simulation menu
2.1. File Menu
2.2. Actions Menu
2.3. Parameters Menu
2.4. XMLlab Menu
3. Scilab XMLlab Menu

List of figures

2.1. Parameter entry menu for the kinetics of prey predation by predator simulation
2.2. Kinetic parameters data entry
2.3. Initial concentrations data entry
2.4. Simulation time data entry
2.5. Results curves
3.1. Parameters entry menu of a mono acid titration simulation
3.2. Analyte choice
3.3. Titrant choice
3.4. Titration parameter data entry
3.5. Experimental data entry
3.6. Results curves
3.7. Saving simulation results  
4.1. Domaine Ω
4.2.  Parameter menu entries of thePoisson's equation simulation
4.3. Results curves
5.1. Earth-Moon system trajectories
5.2. Trajectories of Earth-Moon system in the reference mark related to the centre of gravity
5.3. Parameters menu entries of the Earth-Moon system simulation
5.4. System parameters data entry
5.5. Solving parameters data entry
5.6. Earth and moon trajectories
6.1. IHM presentation based on tags  
6.2. Subsection utilization exemple
6.3. Exemple of a subsection displayed in a separate window
6.4. Parameters data entry for the species to be titrated
6.5. Group Tag example
6.6. Data entry of experimental data  
6.7. Actions menu example

Chapter 1. Introduction

This handbook supposes the reading of the document XMLlab Getting started guide which describes the installation and presents XMLlab software use. It aims at :

  • Prolonging this document by continuing the illustration of the description logic of a simulation in XML, and this through the step by step design of four simulation examples, the accent being each time put on the new types of the elements introduced.

  • Describing completely all the elements that can participate in the simulation description.

Let us remind that the simulation description is based on the tag language XML and contains the following elements :

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

  • the physical parameters description intervening in these models,

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

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

Chapter 2. Kinetics of prey predation by predators

This example corresponds to Predation/prey-predator.xml file of the sub-directory examples of the XMLlab installation directory.

1. Mathematical description of the simulation

It consists of bringing together a set of preys and a set of predators, each having a rate of reproduction and mortality, the predators arresting preys at a given rate.

Let us consider the following parameters intervening in the simulation :

  • r : Growth rate of preys without predator,

  • k : Mortality of prey, without predator,

  • a : Predation rate of prey, per number of predator,

  • b : Growth rate of predators, per number of eaten prey,

  • q : Mortality of predators, without prey.

The following equations of Lotka-Voltera govern then the evolution with time of the number of prey (prey) and of the number of predators (predator) :

{ d prey d t = r . prey k . prey a . prey . predator d predator d t = b . prey . predator q . predator

2. Logics of the description in XML of the simulation

We will show how this simulation is translated into a XML file that the XMLlab tool will use to generate a simulation executed by Scilab. The XML file will be shown in its textual form.

2.1. General description

The heading lines of the XML file always allows to associate to it the XMLlab DTD, the following simulation heading lines allowing to specify its title, its author, the keywords related to it, as well as an image (here the equations governing the simulation) displayed permanently at the bottom of the window of the parameters adjustment.

<?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">
<simulation>
  <header>
    <title lang="french">Cinétique de prédation de proies par des prédateurs</title>

    <title lang="english">Kinetics of prey predation by predators</title>

    <author>Pauss André, Mottelet Stéphane, UTC</author>

    <keywords>simulation, scilab, xml, Lotka-Voltera</keywords>

    <image href="Lotka-Voltera.gif" />
  </header>
  ...

The lines defining multilingual notes come then. They are displayed during the selection of the menu entry XMLlab->About this simulation :

  <notes lang="french">
    <p>Cette simulation a pour objet d'illustrer l'équation de Lotka-Voltera qui décrit la dynamique des populations de proies et de prédateurs</p>
  </notes>

  <notes lang="english">
    <p>This simulation aims to illustrate the kinetics of prey predation by predators, with the Lotka-Voltera expression</p>
  </notes>

2.2. Parameters

The simulation parameters are grouped in several sections, each section giving place to a different entry of the simulation parameter menu, as shown in the following figure :

Figure 2.1. Parameter entry menu for the kinetics of prey predation by predator simulation

Entrées du menu Paramètres de la simulation de cinétique de prédation de proies par des prédateurs

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

  <parameters>
    <section>
      <title lang="french">Paramètres cinétiques</title>
      <title lang="english">Kinetic parameters</title>
      ...
    </section>
    <section>
      <title lang="french">Concentrations initiales</title>
      <title lang="english">Initial concentrations</title>
      ...
    </section>
    <section>
      <title lang="french">Temps de simulation</title>
      <title lang="english">Simulation duration</title>
      ...
    </section>
  </parameters>

We now will describe in detail the declaration of the parameters of each section, whose corresponding lines appear after the multilingual <title> tag in question :

2.2.1. Kinetic parameters

The data entry of the Lotka-Voltera equation parameters is realized in the window illustrated by the following figure :

Figure 2.2. Kinetic parameters data entry

Saisie des paramètres cinétiques

This section contains the following parameters:

  • Growth rate r of preys without predator (j-1) :

          <scalar increment="0.1" label="r" max="10" min="0.5"
                  unit="d-1" widget="slider">
            <name lang="french">
              Vitesse de reproduction des proies sans prédateurs, r (jour-1)
            </name>
            <name lang="english">
              Growth rate of preys without predator, r (day-1)
            </name>
            <value>2</value>
          </scalar>
  • Mortality k of prey, without predator (j-1) :

          <scalar increment="0.01" label="k" max="3" min="0.0001"
                  unit="d-1" widget="slider">
            <name lang="french">
              Mortalité des proies, sans prédateur, k (jour-1)
            </name>
            <name lang="english">
              Mortality of prey, without predator, k (day-1)
            </name>
            <value>0.01</value>
          </scalar>
  • Predation rate a of prey, per number of predator (prédator-1 . j-1) :

          <scalar increment="0.001" label="a" max="0.01" min="0.001"
                  unit="" widget="slider">
            <name lang="french">
              Vitesse de capture des proies par prédateurs, a (prédateur-1 jour-1)
            </name>
            <name lang="english">
              Predation rate of prey, per number of predator, a (predator-1 day-1)
            </name>
            <value>0.001</value>
          </scalar>
  • Growth rate b of predation, per number of eaten prey (prey-1 . j-1) :

          <scalar increment="0.0005" label="b" max="0.01" min="0.001"
                  unit="" widget="slider">
            <name lang="french">
              Vitesse de reproduction des prédateurs, par nombre de proies capturées, b (proie-1 jour-1)
            </name>
            <name lang="english">
              Growth rate of predators, per number of eaten prey, b (prey-1 day-1)
            </name>
            <value>0.002</value>
          </scalar>
  • Mortality q of predator, without prey (j-1) :

          <scalar increment="0.5" label="q" max="20" min="0.5"
                  unit="d-1" widget="slider">
            <name lang="french">
              Mortalité des prédateurs, sans proie, q (jour-1)
            </name>
            <name lang="english">
              Mortality of predators, without prey, q (day-1)
            </name>
            <value>10</value>
          </scalar>

2.2.2. Initial oncentrations

The data entry of the initial concentrations of preys and predators per square kilometers is made in the window illustrated by the following figure:

Figure 2.3. Initial concentrations data entry

Saisie des concentrations initiales

This section contains the following parameters :

  • Initial concentration Prey0 of prey (per km2) :

          <scalar increment="1000" label="Prey0" max="10000" min="0"
                  unit="" widget="slider">
            <name lang="french">
              Concentration initiale en proie (par km2)
            </name>
            <name lang="english">
              Initial concentration of prey (per square km)
            </name>
            <value>5000</value>
          </scalar>
  • Initial concentration Predator0 of predator (par km2) :

          <scalar increment="50" label="Predator0" max="1000" min="1"
                  unit="" widget="slider">
            <name lang="french">
              Concentration initiale en prédateur (par km2)
            </name>
            <name lang="english">
              Initial concentration of predator (per square km)
            </name>
            <value>100</value>
          </scalar>

2.2.3. Simulation Time

Simulation time entry is done in the window illustrated by the following figure :

Figure 2.4. Siimulation time entry

Saisie du temps de simulation

This section contains the only following parameter :

  • Final time final_time (j) :

          <scalar increment="1" label="final_time" max="200" min="0.001"
                  unit="d" widget="slider">
            <name lang="french">Temps final (jour)</name>
            <name lang="english">Final time (day)</name>
            <value>10</value>
          </scalar>

2.3. Mathematical Models

This section - that follows the tag </parameters> - allows to define the equations to be solved, the curves to calculate, as well as the window of values (1D or 2D) that certain variables can take. These different definitions are framed by the following tags :

  <compute>
  ...
  </compute>

Concerning our simulation of the kinetics of prey predation by predators, the following elements are defined :

2.3.2. Definition of the differential equations

Definition of the element ode (ordinary differential equation) grouping together the reference to the integration variable time and to its domain of variation, as well as the definition of the states Prey and Predator, with its derivative and its initial value for each one of them:

    <ode label="predation">
      <refdomain1d ref="time" />

      <states>
        <state label="Prey">
          <name lang="french">Concentration en proie (km-2)</name>
          <name lang="french">Prey concentration (km-2)</name>
          <derivative>(r*Prey) - (k*Prey) - (a*Prey*Predator)</derivative>
          <initialcondition>Prey0</initialcondition>
        </state>

        <state label="Predator">
          <name lang="french">Concentration en prédateur (km-2)</name>
          <name lang="french">Predator concentration (km-2)</name>
          <derivative>(b*Prey*Predator) - (q*Predator)</derivative>
          <initialcondition>Predator0</initialcondition>
        </state>
      </states>

    </ode>

2.3.3. Definition of the phase picture Prey against Predator

It consists of parametric curve x = Prey(t), y = Predator(t) that allows to see the joint evolution of the number of preys and the number of predators :

    <parametriccurve2d label="Prey_vs_predator">
      <name lang="french">Portrait de phase</name>
      <name lang="english">Phase picture</name>

      <x1>
        <value>Prey</value>
      </x1>

      <x2>
        <value>Predator</value>
      </x2>

    </parametriccurve2d>

2.4. Results display

This section - wich follows the tag </compute> - allows to define the different graphic windows, a set of corresponding axes system (windows can then be divided horizontally or vertically) as well as the curves that must be respectively displayed in each system of axis. These different definitions are framed by the following tags :

  <display>
  ...
  </display>

In our case, a single window is vertically divided into two systems of Cartesian axes containing the following curves :

  • Concentrations in preys and predators per km2 with respect to the time.

  • Phase picture of Prey against Predator.

Figure 2.5. Results curves

Courbes résultats

The corresponding code is as follows, the previously defined logical curves appearing in reference in the definition of the curves to display :

  • Curve Prey of the evolution of the concentration of preys and curve Predator of the predators,

  • Phase picture : Prey_vs_predator.

  <display>
    <window splity="2">
      <title lang="french">Résultats</title>
      <title lang="english">Results</title>

      <axis2d>
        <drawcurve2d color="red" ref="Prey" thickness="2" />
        <drawcurve2d color="green" ref="Predator" thickness="2" />
      </axis2d>

      <axis2d>
        <drawcurve2d ref="Prey_vs_predator" />
      </axis2d>

    </window>
  </display>

2.5. Saving simulation results

2.5.1. Saving simulation results

It is accessible via the menu entry File->Save the results of the simulation for this simulation, thanks to the following lines specifying the default file of saving, as well as the list of the parameters and the results to save :

  <save>
    <file format="csv" href="essai.csv"
          labels="r k a b q time Prey Predator" />
  </save>

Here is the appearance of an example of CSV file obtained , the tag name of each parameter or result preceding its value :

"Growth rate of preys without predator, r (jour-1) : ",2.000000,
"Mortality of prey, without predator, k (jour-1) : ",0.001000,
"Predation rate of prey, per number of predator, a (prédateur-1 jour-1) : ",0.005000,
"Growth rate of predators, per number of eaten prey,
 b (proie-1 jour-1) : ",0.002000,
"Temps : ",0.000000,0.010010,...,10.000000,
"Prey concentratione (km-2) : ",5000.000000,5096.003572,...,3358.727460,
"Predator concentration (km-2) : ",100.000000,100.095849,...,144.851043,

Chapter 3. Simulation of monoacides titration

This exemple corresponds to the Acid-equilibria/Simple_acid_alkali_titrat.xml file of the sub-directory examples of the XMLlab installation directory .

1. Chemical description of the simulation

1.1. Calculation principle

The pH of the medium containing the analyte is calculated for an increasing concentration of the titrant, pH can be plotted as function of the concentration volume by titrant added (it is supposed that during titration there is no variation of volume), as well as the coefficients of partition of the analyte according to the concentration by titrant added.

The pH of the medium is calculated in a dichotomic way by cancelling the electric charge of the medium. The equation of electroneutrality states indeed that the positive and negative charges in balance aqueous media. The positive charges come from the ions H 3 O + and possibly from certain forms of the analyte and/or the titrant, the negative charges come from the ions OH - and possibly from certain forms of the analyte and/or the titrant. The equations below show that the concentrations in ions OH - and the concentrations of the forms of the analyte and titrant can be expressed as a function of the concentrations in ions H 3 O + and such as constants of acidity or initial concentrations. In other words, the calculation of the pH consists of determining the right concentration in ion H 3 O + that satisfies the equation of electroneutrality. For memory the pH is equal to -log 10 [ H 3 O + ] . The dichotomic method allows to solve this problem by considering that :

  • the pH to be determined is limited in aqueous medium between 0 and 14,

  • if pH imposed for calculation is lower than the «true» pH , the charge of the medium is positive,

  • if pH imposed for calculation is higher than the «true » pH, the charge of the medium is negative,

  • the two proposals above permits to write a convergence condition of the imposed pH for calculation towards the « true » pH according to the equations below :

    if charge < 0 , then pH iteration_n+1   =  pH iteration_n  -  ( 14 * 0 .5 n )
    if charge > 0 , then pH iteration_n+1   =  pH iteration_n  +  ( 14 * 0 .5 n )
  • 15 iterations of calculation according to above expressions are sufficient to obtain a pH with an accuracy of 0.005 units of pH.

1.2. Characteristics of the analyte and titrant species

In this simple example, acids having only one function of acidity, titrated by bases having also only one function of acidity are considered . The user chooses among some acids and bases whose constants of acidity are already introduced (value at 25°C) :

Name p K a
Hydrochloric acid -7
Dichloroethanoic acid 1.29
Ethanoic acid 4.756
Methanoic acid 3.74
Salicylic acid 2.75
Ammonium hydroxide 9.24
Sodium hydroxide 14.8

1.3. Partition coefficients

The partition coefficients of the various forms of the analyte vary as a function of pH of the solution and values of the constant of acidity. They are expressed in the equations below by the symbol α 0 and α 1 . The coefficient α 1 corresponds to the acid, that is to say the protonic form, while the coefficient α 0 relates to the conjugate base, that is to say the anionic form. Considering unspecified acid HA giving the conjugate base A- :

α 1   =   [ HA ] [ HA ]  +  [ A - ] α 0   =   [ A - ] [ HA ]  +  [ A - ]
Exemples
  Hydrochloric acid (HCl) Sodium hydroxide (NaOH)
α 1 [ HCl ] [ HCl ]  +  [ Cl - ] [ Na + ] [ Na + ]  +  [ NaOH ]
α 0 [ Cl - ] [ HCl ]  +  [ Cl - ] [ NaOH ] [ Na + ]  +  [ NaOH ]

1.4. Titration data

In addition to the choice of the analyte and titrant, parameters below are to be fixed.

Parameters Label in the XML file
Analyte concentration c_analyte
Number of intermediate values for calculation simulation_steps

The concentration of the titrant varies by default from 0 to one and a half of the concentration of the analyte in order to visualize correctely the jump of pH at the equivalent point.

1.5. Equations

1.5.1.  Electric charge of the medium calculation

charge  =   [ H 3 O + ]  -   1  10 -14 [ H 3 O + ]  -  charge_analyte  +  charge_titrant
charge_analyte  =  c_analyte *  α 0 _analyte 
charge_titrant  =  c_titrant *  α 1 _titrant

1.5.2. Partition coefficients calculation

α 1 _analyte  =   [ H 3 O + ]  K a _ analyte +  [ H 3 O + ] α 0 _analyte  =   K a _ analyte  K a _ analyte +  [ H 3 O + ]
α 1 _titrant  =   [ H 3 O + ]  K a _ titrant +  [ H 3 O + ] α 0 _titrant  =   K a _ titrant  K a _ titrant +  [ H 3 O + ]

2.  Logics of the description in XML of the simulation

We will show how this simulation is translated into a XML file that the XMLlab tool will use to generate a simulation executed by Scilab. The XML file will be shown in its textual form. Only elements of simulation not yet treated in the document Getting started XMLlab will be particularly detailed.

2.1. General description

The heading lines of the XML file always allow to associate to it the DTD of XMLlab, the following heading lines of simulation allowing to specify its title, its author, the date and the keywords related to it, show that the attribute of a title tag permits to internationalize the IHM of the simulation. It is also the case for all the tags of the wording intended to be displayed montrent que l'attribut lang d'une balise de titre permet d'internationaliser l'IHM de la simulation. It is the same for all the tags including textual contents to be displayed.

<?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">
<simulation>
  <header>
    <title lang="french">Simulation de titrage de monoacides</title>

    <title lang="english">Simulation of a single acid titration</title>

    <author>Pauss André, Guillot Ivan, Mottelet Stéphane</author>

    <date>June 2005</date>

    <keywords>simulation,scilab,xml</keywords>
  </header>
  ...

2.2. Parameters

The simulation parameters are grouped in several sections, each section giving place to a different entry of the Parameter menu of the simulation as showns in the following figure :

Figure 3.1. Parameters entry menu of a mono acid titration simulation

Entrées du menu Paramètres de la simulation de titrage de monoacides

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

  <parameters>
    <section>
      <title lang="french">Choix de l'espèce à titrer</title>
      <title lang="english">Choice of the analyte</title>
      ...
    </section>
    <section>
      <title lang="french">Choix du titrant</title>
      <title lang="english">Choice of the titrant</title>
      ...
    </section>
    <section>
      <title lang="french">Paramètres du titrage</title>
      <title lang="english">Parameters of the titration</title>
      ...
    </section>
    <section>
      <title lang="french">Points expérimentaux</title>
      <title lang="english">Experimental data</title>
      ...
    </section>
  </parameters>

We now will describe in detail the declaration of the parameters of each section, whose corresponding lines appear after the multilingual <title> tags in question:

2.2.1. Analyte Choice

This choice is done in the window illustrated by the following figure :

Figure 3.2. Analyte choice

Choix de l'espèce à titrer

Actually, it consists of a database containing scalar parameters (here only one, the pKa) for each analyte. For each one of them, a parameter values set is named. For instance, the figure above presents the value set of Hydrochloric acid parameters .

It is also possible to specify that all the value sets can be modified (cf. Section 2.2, « Database tag » for the details of the database tag).

The following lines show the structure of the definition of this whole value sets :

      <database>

        <scalar ... label="database_tag" ...>
          ... definition of the first and sole parameter
        </scalar>

        <record>
          <name lang="english">Hydrochloric acid</name>
          ... definition of the first value set  
          ... for all parameters
        </record>
        ...
        ...
        <record>
          <name lang="english">Salicylic acid</name>
          ... definition of the last value set  
          ... for all parameters
        </record>

      </database>

Let us now examine this structure a little more in detail :

  • Definition of all the parameters by specifying for each of them the label identifying it, its name, the widget used for its entry (entry by defaut : text field), as well as its range of validity and its step of variation, useful for example if the widget chosen is a slider (slider). Here, the only parameter pKa_analyte is not modifiable for a given set of values:

            ...
            <scalar increment="0.1" label="pKa_analyte"
                    max="20" min="-10" state="disabled">
              <name lang="french">pKa</name>
              <name lang="english">pKa</name>
              <value>4</value>
            </scalar>
            ...
  • Definition of the whole set of the values for these parameters, with for each one of them its multilingual name and the corresponding value for each defined parameter :

            ...
            <record>
              <name lang="french">Acide chlorhydrique</name>
              <name lang="english">Hydrochloric acid</name>
              <scalar-value ref="pKa_analyte">-7</scalar-value>
            </record>
    
            <record>
              <name lang="english">Dichloroethanoic acid</name>
              ...
            </record>
    
            <record>
              <name lang="english">Ethanoic acid</name>
              ...
            </record>
    
            <record>
              <name lang="english">Methanoic acid</name>
              ...
            </record>
    
            <record>
              <name lang="english">Salicylic acid</name>
              ...
            </record>
            ...

2.2.2. Titrant Choice

This choice is done in the window illustrated by the following figure :

Figure 3.3. Titrant choice

Choix du titrant

Once againt, it consists of a database containing a scalar parameter for each titrant.

The structure of the definition of this whole value sets is the same one as previously :

  • Definition of the parameters set :

          <database>
    
            <scalar increment="0.1" label="pKa_titrant"
                    max="14" min="0" state="disabled">
              <name lang="french">pKa</name>
              <name lang="english">pKa</name>
              <value>14</value>
            </scalar>
  • Definition of the whole value sets for these parameters :

            <record>
              <name lang="french">Hydroxyde de sodium</name>
              <name lang="english">Sodium hydroxide</name>
              <scalar-value ref="pKa_titrant">14.8</scalar-value>
            </record>
    
            <record>
              <name lang="english">Ammonium hydroxide</name>
              ...
            </record>
    
          </database>

2.2.3. Titration  parameters

Their entry is done in the window illustrated by the following figure :

Figure 3.4. Titration parameter data entry

Saisie des paramètres du titrage

It consists of entering the initial concentration of the analyte and the numbers intermediate values used for the calculation :

      <scalar increment="0.000001" label="c_analyte"
              max="1" min="0.000001" unit="mol / L">
        <name lang="french">Concentration de l'espèce à titrer (mol/L)</name>
        <name lang="english">Initial concentration of the analyte (mol/L)</name>
        <value>0.01</value>
      </scalar>

      <scalar increment="10" label="simulation_steps"
              max="1000" min="10" widget="slider">
        <name lang="french">Nombre de valeurs intermédiaires pour le calcul</name>
        <name lang="english">Number of values for the simulation</name>
        <value>100</value>
      </scalar>

2.2.4. Experimental data

Their entering is done in the window illustrated by the following figure :

Figure 3.5. Experimental data entry

Saisie des points expérimentaux

It is a matricial-type parameter, whose lines correspond to experimental data (64 maximum) here, and whose the two columns correspond respectively to the abscissa and to the ordinate. It can be saved using the icon in a text file having the extension .dat, downloaded from the same file .dat via the icon , or reseted via the icon .

The part of the XML code corresponding to the definition of this matrix is the following one:

      <matrix clear="yes" cols="2" label="user_curve_mat"
              load="yes" rows="64" save="yes"
              striprow="yes">
        <name/>
        <col>
          <name lang="french">Abscisses</name>
          <name lang="english">X-axis</name>
          <value>0</value>
        </col>
        <col>
          <name lang="french">Ordonnées</name>
          <name lang="english">Y-axis</name>
          <value/>
        </col>
      </matrix>

2.3. Mathematical models

This section - that follows the tag </parameters> - allows to define the equations to be solved, the curves to calculate, as well as the fields of the values (1D or 2D) that certain variables should take. These different definitions are framed by the following tags:

  <compute>
  ...
  </compute>

Concerning our simulation of the mono acid titration, the following elements are defined :

2.3.1. Definition of the titrant concentration

It is the definition of the domain of the discrete values taken by the variable c_titrant during the titration, the number of these values being fixed by the variable simulation_steps (cf. § Section 2.2.3, « Parameters of the titration ») :

    <defdomain1d label="c_titrant">
      <name lang="french">Concentration du titrant</name>
      <name lang="english">Titrant concentration</name>

      <interval discretization="linear" steps="simulation_steps">
        <initialvalue>0</initialvalue>
        <finalvalue>1.5 * c_analyte</finalvalue>
      </interval>
    </defdomain1d>

It should be precised that the variable c_titrant can also be considered as a vector of all the values taken in its range. It can be involved in the calculations to be realized as a vector.

2.3.2. pH calculation using the dichotomic method

It consists of using an implicit function defining an application between c_titrant and the pH variable that we try to calculate, through an equation of the form f(c_titrant, pH) = 0 : at each value of c_titrant (cf. § Section 2.3.1, « Definition of the titrant concentration »), The equation admits a unique ph solution.

The following lines represent the structure of the definition of the implicit function ph that also includes :

  • the definition of intermediate variables of calculation used to calculate the values taken by the equation,

  • A list of output curves, whose abscissas and ordinates are for each one of them c_titrant and one function of calculated variable, respectively.

    <implicitfunction label="ph" method="dichotomic">

      definition of the implicit function variable :
      <refdomain1d ref="c_titrant"/>

      <unknowns>
        definition of the sole unknown pH, where the boundaries 
        and the initial value are precised for each solving of the equation :
        <unknown label="pH">
          <name>pH</name>
          <guess>7</guess>
          <lowerbound>0</lowerbound>
          <upperbound>14</upperbound>
        </unknown>
      </unknowns>

      <equations>

        definition of our sole equation, preceeded by the definition
        of intermediary calculus variables :
        <variable label="Ka_analyte">...</variable>
        ...
        <variable label="titrant_load">...</variable>

        definition of the equation for which the cancelation allows to calculate  
        pH for each value of c_titrant :
        <equation>H - (1e-14)./H - analyte_load + titrant_load</equation>

      </equations>

      <outputs>
        ... definition of the curves function of c_titrant
      </outputs>

    </implicitfunction>

Here is now the detail of the intermediate variables of calculation. It should be noted that certain variables are vectors (as seen for the variable c_titrant), which permits to optimize the calculation of the curves of titration by Scilab.

For this reason, certain particular Scilab operator must be specified (v, v1 and v2 are vector, k an scalar) :

  • operator .* :

    • v1 .* v2 = vector resulting from the products two to two of each element of v1 and v2.

    • k .* v = v .* k = vector resulting from the products of each element of v with k.

  • operator ./ :

    • v1 ./ v2 = vector resulting from the divisions two to two of each element of v1 and v2.

    • k ./ v = vector resulting from the divisions of k by each one of elements of v.

    • v ./ k = vector resulting from the divisions of each one of the elements of v by k.

  • operator .^ : follow the same logic as the operator ./.

  • operator + and - :

    • v + k = k + v = vector resulting from the sum of each element of v with k.

    • v - k = vector resulting from the subtractions of each element of v with k.

    • k - v = vector resulting from the subtraction of k with each one of the elements of v.

These operators are used in our case, certain manipulated variables being vectors (calculation of the pH, the coefficients of partitions, analyte, titrand and media charges), whereas other variables are positive scalars. The table below allows to distinguish the two types of variables in the following code :

Scalars Vectors
c_analyte alpha0-1_analyte et alpha0-1_titrant
Ka_analyte et Ka_titrant charge_analyte et charge_titrant
pKa_analyte et pKa_titrant charge
simulation_steps c_titrant
  H : [H3O+]
user_curve_mat
        <variable label="Ka_analyte">10^(-pKa_analyte)</variable>
        <variable label="Ka_titrant">10^(-pKa_titrant)</variable>
        <variable label="H">10.^(-pH)</variable>        
        <variable label="alpha1_analyte">H./(H + Ka_analyte)</variable>
        <variable label="alpha0_analyte">Ka_analyte./(H + Ka_analyte)</variable>
        <variable label="charge_analyte">c_analyte.*alpha0_analyte</variable>
        <variable label="alpha1_titrant">H./(H + Ka_titrant)</variable>
        <variable label="alpha0_titrant">Ka_titrant./(H + Ka_titrant)</variable>
        <variable label="charge_titrant">c_titrant.*alpha1_titrant</variable>

Here is now the detail of the curves function of c_titrant that are defined :

        <output label="alpha1">
          <name>HA</name>
          <value>alpha1_analyte</value>
        </output>

        <output label="alpha0">
          <name>A-</name>
          <value>alpha0_analyte</value>
        </output>

2.3.3. Definition of the experimental data curve

It is a pseudo parametric curve, whose X-coordinates and ordinates are given by the columns of the user_curve_mat matrix described in § Section 2.2.4, « Experimental data » :

    <parametriccurve2d label="user_curve">
      <name lang="french">Points expérimentaux</name>
      <name lang="english">Experimental data</name>
      <x1>
        <name/>
        <value>user_curve_mat(:,1)</value>
                 -> first column of user_curve_mat
      </x1>
      <x2>
        <name/>
        <value>user_curve_mat(:,2)</value>
                 -> second column of user_curve_mat
      </x2>
    </parametriccurve2d>

2.4. Results display

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

  <display>
  ...
  </display>

In our case, only one window is vertically divided into two systems of cartesian axis containing the following curves :

  • pH calculated and pH experimentally mesured, as a function of the concentration of titrant,

  • coefficients of partition of the various protonic forms of the analyte, as a function of the concentration of titrant : HA and A-,

Figure 3.6. Results curves

Courbes résultats

The corresponding code is as follows, logical curves previously defined appearing in reference in the definition of the curves to display :

  • implicit function pH and curve of the experimental data user_curve,

  • curve of the coefficients of partition of the different protonic forms of the analyte : alpha0-1,

  <display>
    <window splity="2">
      <title lang="french">pH</title>
      <title lang="english">pH</title>

      <axis2d xmax="1.5*c_analyte" xmin="0" ymax="14" ymin="0">
        <drawcurve2d color="blue" ref="pH" thickness="2" />
        <drawcurve2d color="red" marker="plus"
                     ref="user_curve" thickness="1" />
      </axis2d>

      <axis2d xmax="1.5*c_analyte" xmin="0" ymax="1" ymin="0">
        <drawcurve2d color="red" ref="alpha1" thickness="2" />
        <drawcurve2d color="green" ref="alpha0" thickness="2" />
      </axis2d>
    </window>
  </display>

2.5. Session and results simulation saving

2.5.1. Saving and downloading the session

The saving session, it's available for all the simulation from the menu entry File->Save the session, consists of saving the whole parameters of the simulation in a file, under the form of a code file Tcl whose execution will later allow to restore their values, this through the entry of the menu "load a session". Here is an example of such a file for our simulation:

set  {$}
set pKa_analyte {-7}
set  {$}
set pKa_titrant {14.8}
set c_analyte {0.01}
set simulation_steps {100}
array set user_curve_mat {
  39,0 39 40,0 40 5,0 5 23,0 23 5,1 0.008 5,2 2.8 61,0 61 44,0 44 9,0 9 27,
  0 27 11,0 11 48,0 48 32,0 32 15,0 15 53,0 53 36,0 36 2,0 2 19,0 19 20,
  0 20 2,1 0.002 2,2 2.4 57,0 57 41,0 41 6,0 6 24,0 24 6,1 0.010 6,2 8 62,
  0 62 45,0 45 28,0 28 12,0 12 50,0 50 49,0 49 33,0 33 16,0 16 54,0 54 37,
  0 37 3,0 3 21,0 21 3,1 0.004 3,2 2.6 58,0 58 42,0 42 7,0 7 25,0 25 7,
  1 0.012 active Abscisses 7,2 11.4 63,0 63 46,0 46 29,0 29 30,0 30 13,
  0 13 51,0 51 34,0 34 17,0 17 0,1 Abscisses 0,2 Ordonnées 55,0 55 38,
  0 38 4,0 4 22,0 22 4,1 0.006 4,2 2.7 60,0 60 59,0 59 43,0 43 8,0 8 26,
  0 26 8,1 0.014 10,0 10 8,2 11.7 64,0 64 47,0 47 31,0 31 14,0 14 52,
  0 52 35,0 35 1,0 1 18,0 18 1,1 0 1,2 2.2 56,0 56
}

2.5.2. Saving simulation results

It is accessible from the entry menu File->Saving simulation results as soon as it was defined via the tag save in the XML file of the simulation. The choice of the default file of saving and its format, as well as the list of the parameters and the results to be saved is determined by the following lines :

  <save>
    <file format="csv" href="essai.csv"
          labels="pKa_analyte c_analyte pKa_titrant c_titrant pH" />
  </save>

The following window allow to choose the name of the file which will be saved here with the format CSV :

Figure 3.7. Saving simulation results  

Sauvegarde des résultats de la simulation

Here is the appearance of an example of a file obtained, the tag name of each parameter or result preceeding its value:

"pKa : ",-7.000000,
"Analyte concentration (mol/L) : ",0.010000,
"pKa : ",14.800000,
"Titrant concentration : ",0.000000,0.000152,...,0.015000,
"pH : ",2.000006,2.006628,...,11.697931,

Chapter 4. Finite elements: simulation of the Poisson's equation

This exemple corresponds to the file Physics/pde.xml of the sub-directory examples of the XMLlab installation directory .

1. Physical description of the simulation

The purpose of the Poisson's equation is to simulate an electric potential. It is a particular case of the following Laplace equation :

div ( D u ) + c u = f , ( x , y ) Ω

with two types of boundary conditions :

  • robin : ( D u ) . n + σ i u = ξ i , ( x , y ) Γ i ,

  • dirichlet : u = g i , ( x , y ) Γ i .

knowing that the domain Ω have a boundary Γ = Γ0 ∪ Γ1 ∪ ... Γi ∪ ... Γn.

The example that we propose to treat corresponds to the following domain Ω which has as a boudery Γ = Γ0 ∪ Γ1 ∪ Γ2.

Figure 4.1. Domaine Ω

Domaine Ω
Γ 0 : { x = cos ( θ ) y = sin ( θ ) θ [ 0,2 π ]
Γ 1 : { x = 0.4 + 0.2 cos ( θ ) y = 0.2 sin ( θ ) θ [ 0,2 π ]
Γ 2 : { x = 0.4 + 0.25 cos ( θ ) y = 0.25 sin ( θ ) θ [ 0,2 π ]

The convention being that the interior of the domain is always on the left of curve when the parameter increases (here θ). There are them two holes. We will discretize Γ0 with 2n points and Γ1, Γ2 with n points.

The Poisson's equation concerning our simulation is finally as follows :

div ( D u ) = 0, ( x , y ) Ω

with D = ( 10 0 0 d ) and, for boundary conditions :

{ u = 0, ( x , y ) Γ 0 u = a , ( x , y ) Γ 1 u = b , ( x , y ) Γ 2

2. Logics of the description in XML of the simulation

We will show how this simulation is translated into an XML file that the XMLlab tool will use to generate a simulation executed by Scilab. The XML file will be shown in its textual form. Once again, only the elements of the simulation that have not been treated previously will be particularly detailed.

2.1. General description

The heading lines of the XML file always allow to associate to it the DTD of XMLlab, the following heading lines of simulation allowing to specify its title, its author as well as the keywords related to it..

<?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">
<simulation>
  <header>
    <title lang="french">Simulation de l'équation de Poisson</title>
    <title lang="english">Simulation of the Poisson equation</title>

    <author email="stephane.mottelet@utc.fr">Stéphane Mottelet</author>
    <date>03/2004</date>

    <keywords lang="french">equation aux dérivées partielles, condensateur,
    éléments finis</keywords>
    <keywords lang="english">partial differential equation, condensator,
    finite elements </keywords>
  </header>
  ...

Lines defining multilingual notes, are then introduced and displayed when selecting the entry of the menu XMLlab->About this simulation :

  <notes lang="french">
    <p>Cette simulation a pour but de montrer les possibilités de XMLlab en
    termes de simulation d'équations aux dérivées partielles elliptiques.</p>
    <p>On s'intéresse ici à un exemple simple où le bord extérieur du domaine
    est mis à la masse, et où on impose deux tensions différentes sur les deux
    frontières intérieures.</p>
  </notes>

  <notes lang="english">
    <p>This simulation aims to show how XMLlab is able to deal with partial
    differential equations.</p>
    <p>Play with the sliders to change the mesh and see how the voltage on the
    inner electrodes influences the whole distribution.</p>
  </notes>

2.2. Parameters

The parameters of this simulation contain only one section, leading to a single entry of the Parameter menu of the simulation as showns in the following figure:

Figure 4.2. Parameter menu entries of the Poisson's equation simulation Results curves

Entrées du menu Paramètres de la simulation de l'équation de Poisson

The following lines introduce and name the single section of parameters :

  <parameters>
    <section>
      <title lang="french">Paramètres de discrétisation</title>
      <title lang="english">Discretization parameters</title>
      ...
    </section>
  </parameters>

We will now describe in detail the declaration of the parameters of this section, whose corresponding lines appear after the multilingual <title> tag :

2.2.1. Discretization parameters

Their data entry is done in the previously seen window.

This section contains the following parameters :

  • Number n of points on the boundaries :

          <scalar increment="1" label="n" max="25" min="10">
            <name lang="french">Nombre de points sur les frontières</name>
            <name lang="english">Number of points on the boundary</name>
            <notes lang="french">
              <p>Ne pas dépasser n=20 si vous voulez garder</p>
              <p>une animation fluide.</p>
            </notes>
            <notes lang="english">
              <p>Don't use more than n=20 points if you</p>
              <p>want to keep a smooth animation.</p>
            </notes>
            <value>10</value>
          </scalar>
  • Voltage b on the left electrode, tuned with a slider that can be automatically animated :

          <scalar increment="0.01" label="b" max="1" min="-1" widget="animate">
            <name lang="french">Tension sur l'électrode gauche</name>
            <name lang="english">Voltage on the left electrode</name>
            <value>0</value>
          </scalar>

    The user can make the value of the parameter vary continuously between the defined limits and according to the specified incrementation step :

    The 4 buttons located beside the slider allows respectively :

    • to start the animation until to the final value of the parameter,

    • to start it from the initial value when the final value is reached,

    • to start it in the opposite direction toward the initial value when the final value is reached,

    • to put the animation in pause .

  • Voltage a on the right electrode, tuned with a slider :

          <scalar increment="0.01" label="a" max="1" min="-1" widget="slider">
            <name lang="french">Tension sur l'électrode droite</name>
            <name lang="english">Voltage on the right electrode</name>
            <value>1</value>
          </scalar>
  • Conductivity coefficient d in the y direction, tuned with a slider :

          <scalar increment="10" label="d" max="200" min="10" widget="slider">
            <name lang="french">Coefficient de conductivité en y</name>
            <name lang="english">Conductivity coefficient in the y direction</name>
            <value>10</value>
          </scalar>

2.3. Mathematical Models

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

  <compute>
  ...
  </compute>

Concerning our simulation of the Poisson's equation, the following elements are defined :

2.3.1. Definition of the variable thetain and of its interval of discretization [0, 2π]

This variable is used to discretize Γ1 and Γ2 with n points :

    <defdomain1d label="thetain">
      <interval discretization="linear" steps="n">
        <initialvalue>0</initialvalue>
        <finalvalue>2*%pi</finalvalue>
      </interval>
    </defdomain1d>

We also illustrates the possibility of using Scilab constants , here %pi.

2.3.2. Definition of the variable thetaoutand its interval of discretization [0, 2π]

This variable is used to discretize Γ0 with 2n points :

    <defdomain1d label="thetaout">
      <interval discretization="linear" steps="2*n">
        <initialvalue>0</initialvalue>
        <finalvalue>2*%pi</finalvalue>
      </interval>
    </defdomain1d>

2.3.3. Definition of the domaine Ω

Its boundary is Γ = Γ0 ∪ Γ1 ∪ Γ2. Its definition (tag defdomain2d) is composed of the description of its boundaries Γ0, Γ1 and Γ2, each of them being described by a 2D parametric curve (tag parametriccurve2d) depending on the variables thetain and thetaout, the tag refdomain1d indicating the variable (domain1d) in dependance :

    <defdomain2d dependencies="n" label="omega">
      <border>
        <parametriccurve2d label="gamma_0">
          <refdomain1d ref="thetaout"/>
          <x1>
            <value>cos(thetaout)</value>
          </x1>
          <x2>
            <value>sin(thetaout)</value>
          </x2>
        </parametriccurve2d>
        <parametriccurve2d label="gamma_1">
          <refdomain1d ref="thetain"/>
          <x1>
            <value>0.4+0.2*cos(thetain)</value>
          </x1>
          <x2>
            <value>0.2*sin(-thetain)</value>
          </x2>
        </parametriccurve2d>
        <parametriccurve2d label="gamma_2">
          <refdomain1d ref="thetain"/>
          <x1>
            <value>-0.4+0.25*cos(thetain)</value>
          </x1>
          <x2>
            <value>0.25*sin(-thetain)</value>
          </x2>
        </parametriccurve2d>
      </border>
    </defdomain2d>

The attribute dependencies="n" allows to indicate that the triangulation of the domain, which is an expensive operation, must only be done when it changes, thus when n changes of value.

2.3.4. Definition of the stationary partial derivatives

It is contained in the following code, the correspondences being as follows :

  • the matrix D (that must be a constant) corresponds to the contents of the diffusion tag,

  • the function c(x, y) to the proportional tag,

  • f(x, y) to the source tag,

  • for the boundary conditions :

    • σ(x, y) and ξ(x, y) corresponds to the sigma and xi tags, absent of this example,

    • g(x, y) to the dirichlet tag

    <stationary-pde label="pde1">
      <refdomain2d ref="omega"/>
      <pdestate label="u">
        <name lang="french">Tension</name>
        <name lang="english">Voltage</name>
        <inside dependencies="n d">
          <diffusion>[10 0;0 d]</diffusion>
          <proportional>0</proportional>
          <source>0</source>
        </inside>
        <boundary>
          <condition bdy="gamma_0">
            <dirichlet>0</dirichlet>
          </condition>
          <condition bdy="gamma_1">
            <dirichlet>a</dirichlet>
          </condition>
          <condition bdy="gamma_2">
            <dirichlet>b</dirichlet>
          </condition>
        </boundary>
      </pdestate>
    </stationary-pde>

Here also, we use the attribute dependencies of the inside tag to calculate only what is necessary when the parameters change. Thus, the assembly of the problem in the domain is redone only if n or d changes, allowing to vary the boundary conditions without doing aganin large useless calculations.

2.4. Result display

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

  <display>
  ...
  </display>

In our case, only one window is divided horizontally into two systems of axes containing different representations of the surface u(x,y), (x,y) ∈ Ω :

  • One flat representation in 2D (x,y), the variations of u being illustrated by color variations.

  • One representation in isometric 3D of the surface with wires.

Figure 4.3.  Results curves

Courbes résultats

The corresponding code is as follows, the previously defined logical curves appearing in reference in the definition of the curves to be displayed :

  • One flat representation of u in 2D : the attributes cmin and cmax of the axis2d tag indicate the range of variation of u,

  • One representation in 3D of the surface : the attribute mode="wireframe" indicate that a representation with iron wire is desired,

  <display background="blue">
    <window colormap="hot" splitx="2">
      <title lang="french">Résultats</title>
      <title lang="english">Results</title>

      <axis2d cmax="1" cmin="-1" colorbar="on" iso="yes">
        <drawsurface ref="u" shading="interp"/>
      </axis2d>

      <axis3d xmin="-1" xmax="1" ymin="-1" ymax="1" zmin="-1" zmax="1">
        <drawsurface mode="wireframe" ref="u"/>
      </axis3d>

    </window>
  </display>

Chapter 5. Simulation of Earth-Moon system

This exemple, that will be described completely, corresponds to the file Physics/gravitation.xml of the sub-directory examples of the XMLlab installation directory

1. Physical description of the simulation

The purpose is to simulate the movement of two or several bodies subjected to their mutual gravitational attractions.

In the case of two bodies, the problem was analytically resolved, and it is well known that the trajectories obtained are conics having for hearth the system gravity centre composed of these two bodies. The problem of three bodies has always escaped the mechanics, because it is not possible any more to find an analytical solution (for more than three bodies either, of course). The problems with more than two bodies were very quickly considered because we very fast realized that the trajectories of planets around the sun are not those envisaged by the simplified theory consisting in considering as many problems with two bodies than there are planets in orbit: the planets are influenced mutually, in a weak way compared to the force of gravitation exerted by the Sun, but sufficiently so that the long-term trajectories are modified.

it was thus necessary very quickly to know how to calculate with precision these trajectories to constitute what is called ephemeris, ie real tables where we can read the position of various celestial bodies for future dates. The positions of these bodies verify differential equations, and the techniques of approximation are the same ones that those used for the simulation of the pendulum (cf. document Getting started XMLlab).

We quickly will describe how to implement the simulation of a problem at two bodies. Initially, some recalls are necessary: let us consider two spherical bodies of centers u1 = (x1, y1) and u2 = (x2, y2), and of respective masses m1 and m2. The gravitational force exerted by body 2 on body 1 is equal to

F 21 = G m 1 m 2 u 2 u 1 3 ( u 2 u 1 ) ,

where G is the constant of universal gravitation. The gravitational force exerted by body 1 on body 2 is equal to its opposite, that is to say

F12 = −F21.

If we wish to simulate the movement of these two bodies according to an initial position and speed configuration, we must write the dynamic equations, which gives

u ˙ 1 = v 1 , u ˙ 2 = v 2

if speeds are noted, v1, v2 and

{ v ˙ 1 = G m 2 ( u 2 u 1 ) u 2 u 1 3 , v ˙ 2 = + G m 1 ( u 2 u 1 ) u 2 u 1 3 ,

Here body 1 is the Earth and body 2 the Moon.

m1 = 5,975e24 ; m2 = 7,35e22 ; G = 6,67e-11 ; The average distance Earth-Moon is dTL = 3, 84402e8 m and the rotation period is about T = 27,55 days. We thus choose as initial positions

u 1 ( 0 ) = ( 0, 0 ) , u 2 ( 0 ) = ( d T L , 0 ) ,

and as initial speeds

v 1 ( 0 ) = ( 0, 0 ) , v 2 ( 0 ) = ( 0, 2 π T d T L ) .

Figure 5.1.  Earth-Moon system trajectories

Trajectoires du système Terre-Lune

Figure 5.2. Trajectories of Earth-Moon system in the reference mark related to the centre of gravity

Trajectoires du système Terre-Lune dans le repère lié au centre de gravité

The Figure 5.1, « Earth-Moon system trajectories» shows the two trajectories obtained (the trajectory of the Earth will be easily recognized), that can seem odd but it should not be forgotten that it is necessary to be reduced to the centre of gravity to see there more clearly. It only takes to calculate the position of the centre of gravity at every moment and to withdraw its coordinates from those of the Moon and the Earth. This gives Figure 5.2, « Trajectories of Earth-Moon system in the reference mark retated to the center of gravity », which is more familiar. It will be noted that Earth undergoes in an obvious way the influence of the Moon.

2. Logics of the simulation description in XML

We will show how this simulation is translated into an XML file that the XMLlab tool will use to generate a simulation executed by Scilab. The XML file will be shown in its textual form. This example will be treated in a similar way than the preceding example.

2.1. General description

The heading lines of the XML file always allow to associate to it the DTD of XMLlab, the heading lines of simulation which follow allowing to specify its title, its author, the keywords related to it.

<?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">
<simulation>
  <header>
    <title>Système Terre-Lune</title>
    <author>Please set author's name</author>
    <keywords>simulation,scilab,xml</keywords>
  </header>
  ...

2.2. Parameters

The simulation parameters are grouped in several sections, each section giving place to a different entry of the Parameter menu of the simulation as showns in the following figure:

Figure 5.3. Parameters menu entries of the Earth-Moon system simulation System parameters data entry Solving parameters data entry Earth and moon trajectories

Entrées du menu Paramètres de la simulation du système Terre-Lune

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

  <parameters>
    <section>
      <title>System parameters</title>
      ...
    </section>
    <section>
      <title>Solving parameters</title>
      ...
    </section>
  </parameters>

We now will describe in detail the declaration of the parameters of each section, whose corresponding lines appear after the multilingual <title> tag in question :

2.2.1. System parameters

Their data entry is done in the window illustrated by the following figure :

Figure 5.4. System parameters data entry

Saisie des paramètres du système

This section contains the following parameters:

  • Initial moon speed vL0 :

          <scalar label="vL0" unit="ms^-1">
            <name>Initial moon speed</name>
            <value>2*%pi/(27.55*24*3600)*3.84402e8</value>
          </scalar>
  • Earth mass mT / 1e24 :

          <scalar label="mT" unit="m" widget="slider"
                  min="4" max="5.975" increment="0.01">
            <name>Earth mass (1e24)</name>
            <value>5.975</value>
          </scalar>
  • Moon mass mL / 1e24 :

          <scalar label="mL" unit="m" widget="slider"
                  min="0.0735" max="5.975" increment="0.01">
            <name>Moon mass (1e24)</name>
            <value>0.0735</value>
          </scalar>
  • Attack angle theta between the moon-earth vector and the moon initial speed vector (theta determines the direction of v2(0)) :

          <scalar label="theta" unit="deg" widget="slider"
                  min="1" max="179" increment="1">
            <name>Attack angle</name>
            <value>90</value>
          </scalar>

2.2.2. Solving parameters

Their data entry is done in the window illustrated by the following figure :

Figure 5.5. Solving parameters data entry

Saisie des paramètres de résolution

This section contains the following parameters :

  • Final jf time (days) : it is the duration of simulation, the value suggested being the moon period of rotation T around the earth. jf is used to calculate the upper limit of the discretization interval involved in the resolution of the differential equation giving the moon and earth moves :

          <scalar label="jf" unit="d">
            <name>Final time (jours)</name>
            <value>27.55</value>
          </scalar>

2.3. Mathematical models

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

  <compute>
  ...
  </compute>

Concerning our simulation of celestial mechanics, the following elements are defined:

2.3.1. Definition of the variable t and of its discretization interval [0, T]

It is the integration variable used for the solution of our differential equation, the discretization interval being cut out in 1000 steps :

    <defdomain1d label="t" unit="s">
      <name>Time</name>
      <discretization interval="linear" steps="1000">
        <initialvalue>0</initialvalue>
        <finalvalue>jf*24*3600</finalvalue>
      </interval>
    </defdomain1d>

2.3.2. Definition of the differential equations

Definition of the ode element (ordinary differential equation) grouping together :

  • the reference to the integration variable t and to its domain of variation,

  • the definition of the states xT and vT (earth position and speed) on the one hand, xL and vL (moon position and speed) on the other hand, with for each one of them its derivative and its initial value; it should be noted that each one of these states is a vector having two components x and y (size="2"),

  • the exit xG giving the position of the gravity centre of the Earth-Moon system.

    <ode label="terre_lune">
      <refdomain1d ref="t"/>

      <states>
        <variable label="r3">norm(xT-xL)^3</variable>

        <state label="xT" size="2">
          <name>Earth position</name>
          <derivative>vT</derivative>
          <initialcondition>[0;0]</initialcondition>
        </state>

        <state label="vT" size="2">
          <name>Earth speed</name>
          <derivative>6.67e-11*mL*1e24*(xL-xT)/r3</derivative>
          <initialcondition>[0;0]</initialcondition>
        </state>

        <state label="xL" size="2">
          <name>Moon position</name>
          <derivative>vL</derivative>
          <initialcondition>[3.84402e8;0]</initialcondition>
        </state>

        <state label="vL" size="2">
          <name>Moon speed</name>
          <derivative>6.67e-11*mT*1e24*(xT-xL)/r3</derivative>
          <initialcondition>
            vL0*[cos(%pi*theta/180);sin(%pi*theta/180)]
          </initialcondition>
        </state>
      </states>

      <outputs>
        <output label="xG">
          <name>Gravity centre</name>
          <value>(xL*mL+xT*mT)/(mL+mT)</value>
        </output>
      </outputs>
    </ode>

2.3.3. Definition of the parametric curve giving the trajectory of the earth

It consists in the earth position relative to the centre of gravity of the Earth-Moon system :

    <parametriccurve2d label="traj_terre">
      <name>Earth</name>
      <refdomain1d ref="t"/>
      <x1>
        <value>xT(:,1)-xG(:,1)</value>
      </x1>
      <x2>
        <value>xT(:,2)-xG(:,2)</value>
      </x2>
    </parametriccurve2d>

2.3.4.Definition of the parametric curve giving the trajectory of the moon

It consists in the moon position relative to the centre of gravity of the Earth-Moon system :

    <parametriccurve2d label="traj_lune">
      <name>Moon</name>
      <refdomain1d ref="t"/>
      <x1>
        <value>xL(:,1)-xG(:,1)</value>
      </x1>
      <x2>
        <value>xL(:,2)-xG(:,2)</value>
      </x2>
    </parametriccurve2d>

2.4. Results display

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

  <display>
  ...
  </display>

In our case, only one window contains a system of cartesian axis containing the curves of the earth and the moon trajectories:

Figure 5.6. Earth and moon trajectories

Trajectoires de la terre et de la lune

The corresponding code is as follows, the logical curves previously definited appearing in reference in the definition of the curves to display :

  <display>
    <window>
      <title>System orbits</title>
      <axis2d position="initial" iso="yes"
              xmin="-5e8" ymin="-5e8" xmax="5e8" ymax="5e8">
        <drawcurve2d ref="moon_traj"/>
        <drawcurve2d ref="earth_traj" color="green"/>
      </axis2d>
    </window>
  </display>

Chapter 6. Reference of the elements participating in the description of a simulation

We are going to detail exhaustively all the XML tags that can participate to the description of a simulation. They can be classified into four main categories:

  • heading, titles and multilingual notes , image (displaying for example the equations governing the simulation),

  • parameters: scalars, matrices, points 2D-3D (possibly constrained), definition of sets of values of experimentation for a group of scalar or matric parameters, regroupings of parameters in sections,

  • calculation elements: domain 1D-2D, different curves and surfaces 2D-3D (parametric or not), differential equations defined by a list of states and exits, implicit systems of functions, equations with stationary partial derivatives, inclusion of Scilab mini-scripts,

  • display elements of the simulation results : windows, curves "continues" 2D cartesian or polar", curves 2D of points, 2D-3D surfaces and 3D curves.

The following conventions are used in the description of XML tags :

  • Attributes in bold are obligatorily present, the values in bold cannot be modified,

  • Texts in italic bordeaux specify the use of the tags

  • Opening tags are preceded if necessary by an indication in italic bordeaux on their possible number of occurences

  • Concerning the values of attributes or of body of tag :

    • A free value is represented by a text in italic describing this value,

    • A value forced in a set of possible values is represented as follows.

      "default_value|value_2|...|value_n"
  • <tag_1|tag_2|...|tag_n>

    indicates an alternative between several possible tags at this place,

  • <tag_1>...
      OR
    <tag_2>...

    also indicates an alternative, here between two tags,

  • the values of the attributes label must obligatorily be correct Scilab variable identifiers: start with an alphabetical character (not accentuated) or with '_', and be followed by alphanumeric characters or with '_'. It is to note that most of the softwares allowing to edit an XML file do this check.

For an introduction to the XML tag language, the following site can be consulted : http://www.infomaniak.ch/support/details_categorie.php?iCodeCategorie=7

1. General description

It includes a heading of the simulation and the possible associated notes.

1.1. File and simulation headings

The heading lines of the XML file allows to associate it to the DTD of XMLlab:

<?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 heading lines of the simulation that allows to specify the title, the author, the version, the date, the keywords that are related to it, as well as an image (for example equations governing the simulation) displayed permanently at the bottom of the parameters tuning window..

<simulation version="1.4" label="id_simulation">
  -> id_simulation will allow in the futur to identify the simulation to dialogue with others Tk applications, but not currently used

  once and only once :
  <header>

    one or several times :
    <title lang="french|english|german|spanish">
      Simulation title in a given language 
    </title>

    maximum once:
    <author email="author email">
      Simulation authors
    </author>

    maximum once :
    <version>Simulation version</version>

    maximum once:
    <date>Simulation date</date>

    none or several times :
    <keywords lang="french|english|german|spanish">
      Simulation keywords
    </keywords>

    maximum once :
    <image href="Image file path" />

  </header>
  ...

1.2. Notes about the simulation

Lines defining multilingual notes can eventually be added, which are displayed during the selection of the menu entry XMLlab->About this simulation :

  none or several times :
  <notes lang="french|english|german|spanish">
none or several times :
    <p>Simulation notes</p>
  </notes>

2. Parameters

The simulation parameters, if it has some, are defined within a single tag <parameters>...</parameters>, this one being divided into several sections, each of them allowing to group logically a set of parameters, and giving place to a different entry of the menu Parameters of the simulation. One section at least must be defined

The choice of an entry causes then the display of the corresponding parameters. Here is the structure of the definition of the parameters:

  maximum once :
  <parameters widget="plain|notebook">

    one or several times :
    <section hidden="no" label="id_section">
                           -> id_section is reserved for a futur use 

      none or several times :
      <title lang="french|english|german|spanish">
        section title (and of the submenu or corresponding tabs)
        cf. attribute widget explanation of parameters tag follows 
      </title>

      none or several times :
      <notes lang="french|english|german|spanish">
        one or several times :
        <p>section note</p>
      </notes>

      one or several times :
      <scalar|matrix|point|group>... tags to be detailed further  
        OR
      one or several times :
      <subsection|database>... tags to be detailed further

    </section>

  </parameters>

The use of the form <parameters widget="notebook"> leads to a presentation of the IHM of the window based on tabs (only the menu File remains) rather than based on menus and submenus to reach the different sections of parameters, to the saving) of the simulation results, as well as the notes concerning XMLlab and the ones concerning the simulation. This is illustrated by the following figure:

Figure 6.1. IHM presentation based on tags  

Présentation de l'IHM à base d'onglets

2.1. Subsection Tag

It allows, inside a section, to group logically a set of parameters, the parameters of each subsection being then gathered visually in the data entry window. The structure of this tag is as follows:

      <subsection hidden="no" label="id_sous-section"
                  tearoff="yes|no" explanation of this attribute follows
      >

        none or several times :
        <title lang="french|english|german|spanish">
          subsection title (and the framework surrounding its parameters)
          cf. exemple below
        </title>

        none or several times :
        <notes lang="french|english|german|spanish">
          one or several times :
          <p>section note</p>
        </notes>

        one or several times :
        <scalar|matrix|point|group>... tags to be detailed further

    </subsection>

Here is an example of a IHM corresponding to a section separated into two subsections. Coefficients of the right and Data of the user whose attribute tearoff was located at yes : one click on the icon involve then the display of the corresponding subsection in a separate window.

Figure 6.2. Subsection utilization exemple

Exemple d'utilisation de sous-sections

Figure 6.3. Exemple of a subsection displayed in a separate window

Exemple d'une sous-section affichée dans une fenêtre séparée

2.2. Database Tag

It allows to define a set of experimentation values for a set of scalar or matric parameters, each value sets being named. The file Acid-equilibria/Acid_base_titration.xml provided in the subdirectory examples of the XMLlab installation repertory illustrates its use: it consists of a simulation of titration in aqueous media and the figure below shows the set of parameters values for citric Acid among a group of sets of values whose choice is carried out via a scrolling list.

Figure 6.4. Parameters data entry for the species to be titrated

Saisie des paramètres de l'espèce à titrer

It is also possible to specify that the group of the sets of values is modifiable (via the attribute editable of the database tag), the possible modifications being then the following ones (simulation is started again after each modification) :

  • Addition of a set of values: select the entry Defined by the user: rename it with the name of this new set, fill the values of the corresponding parameters, and click on the icon to save the change in the XML file.

  • Removal of a set of values: select the entry to be removed, and click on the icon to save the deletion in the XML file.

  • Modification of the entry selected initially : select it, and click on the icon to save the modification in the XML file.

Here is the structure of the definition of a group of sets of values :

      <database editable="yes|no"
                tearoff="yes|no" cf. Section 2.1, « Subsection tag»
                label="id_database" -> reserved for a futur use
      >

        none or several times :
        <title lang="french|english|german|spanish">
          title of the all set values 
         (and the framework surrounding its parameters)
        </title>

Definition of all parameters of each values set :
        one or several times :
        <scalar|matrix|group>... tags to be detailed further

Definition of all values set with for each one of them the corresponding parameter value  :
        none or several times :
        <record>
          ... cf. Section 2.7, « Record tag »
        </record>

      </database>

Concerning the group sub-tag of the database tag, it is necessary to specify that it cannot, in this case, contain a point tag.

2.3. Group Tag

It allows to logically group a set of parameters inside a section or a sub-section, the parameters in question appearing on the same line. The following figure presents an example concerning the same section of parameters illustrated by Figure 3.4, « Data entry of the titration parameter », and for which subsections were replaced by groups:

Figure 6.5. Group Tag example

Exemple d'utilisation de la balise group

Here is the structure of the definition of a parameters group :

      <group>

        none or several times :
        <title lang="french|english|german|spanish">
          Title of parameters group
        </title>

Definition of all paramameters group :
        one or several times :
        <scalar|matrix|point>... tags to be detailed further

      </group>

2.4. Scalar Tag

It consist of the definition of a scalar parameter, whose value is possibly forced by boundaries, as well as the widget used for its data entry :

      <scalar label="id_scalaire" unit="scalar unit"
              widget="entry|slider|hidden|animate"
              state="disabled|normal"
                -> disabled makes insensible the widget,
                   preventing the parameter data entry 

              The two following attributes are at present useful only if widget="slider|animate", but they will be useful in a futur use
              in a widget entry to do a verification in the data entry.
              min="scalar minimun" max="scalar maximum"
                -> define the potential boundaries 
                   the scalar minimun and maximun 

              increment="scalar increment step "
                -> used when the scalar increases or decreases of one step :
                   - widget="animate" : during the animation
                   - widget="slider"  : during a slider left or right click
              period="scalar period (default value 10)"
                -> Number of milliseconds between each parameter value variation during an animation

              scale="scalar scale (default value 1)"
                -> It is the factor between the data entry value and 
                   the scalar value attributed
      >

        one or several times :
        <name lang="french|english|german|spanish">
          parameter name as displayed in the data entry zone 
        </name>

Notes for the sole purpose of comments on the scalar parameter:
        none or several times :
        <notes lang="french|english|german|spanish">
          one or several times :
          <p>scalar parameter notes</p>
        </notes>

        once and only once :
        <value>
          parameter initial value
        </value>

      </scalar>

Here are examples of representations for the different possible values of the attribute widget :

  • entry :

  • slider :

  • hidden : this attribute indicates that there is no representation associated with this parameter. It is a parameter for an internal use of the simulation, such as for example a physical or a chemical constant.

  • animate : it allows the user to make the parameter value vary continuously between its defined boundaries, and according to the specified incrementation step. Thus, the representation below results from the following code :

          <scalar label="iv" widget="animate"
                  min="0" max="500" increment="1" period="40">
            <name>Instant of visualization</name>
            <value>1</value>
          </scalar>

    The 4 buttons located beside the slider allows respectively :

    • to start the animation up to the end value of the parameter,

    • to start it by restarting from the initial value when the final value is reached,

    • to start it by restarting in opposite direction toward the initial value when the final value is reached,

    • to put the animation in pause.

2.5. Matrix Tag

It consists of the definition of a matrix parameter, whose value can eventually be saved or loaded from a file, and whose either the line titles, or the columns titles are defined :

      <matrix label="id_matrice"
              rows="number of lines" cols="number of columns"

              The two next attributes respectively indicates that the
              empty or null lines and/or columns located at the matrix ends
              must be deleted.
              striprow="yes|no"
              stripcol="yes|no"

              The three next attributes indicates if the download icon, save icon and clear icon,
              must be respectively displayed (cf. example bellow).
              load="yes|no"
              save="yes|no"
              clear="yes|no"

              widget="hidden|normal"
                -> indicate if the data entry acquisition widget is visible or not
      >

        one or several times :
        <name lang="french|english|german|spanish">
          Parameter name as displayed above of the data entry matrix 
        </name>

Notes for the sole purpose of comments on the matrix parameter :
        none or several times :
        <notes lang="french|english|german|spanish">
          one or several times :
          <p>scalar parameter note</p>
        </notes>

Definition of the columns or the lines titles and defaut values :
        none or several times :
        <col>
          none or several times :
          <name lang="french|english|german|spanish">
            title of this column
          </name>
          once and only once :
          <value>
            initial value of this column elements
          </value>
        </col>
          OR
        none or several times :
        <row>
          none or several times :
          <name lang="french|english|german|spanish">
            title of this line
          </name>
          once and only once :
          <value>
            initial value of this line elements
          </value>
        </row>

      </matrix>

Here is an example of data entry window of a 64x2 matrix parameter, the lines corresponding to experimental data, and both columns corresponding respectively to their abscissa and to their ordinate :

Figure 6.6. Data entry of experimental data  

Saisie des points expérimentaux

It can be saved using the icon (save="yes") in a text file having the extension .dat, downloaded from the same file .dat via the icon (load="yes"), or reseted via the icon (clear="yes").

The part of the XML code corresponding to the definition of this matrix is the following :

      <matrix clear="yes" cols="2" label="user_curve_mat"
              load="yes" rows="64" save="yes"
              stripcol="no" striprow="yes" widget="normal">
        <name/>
        <col>
          <name lang="french">Abscisses (volumes de titrant)</name>
          <name lang="english">X data (titrant volumes)</name>
          <value>0</value>
        </col>
        <col>
          <name lang="french">Ordonnées (pH)</name>
          <name lang="english">Y data (pH values)</name>
          <value/>
        </col>
      </matrix>

It can be besides made reference to a matrix elements (let us suppose label="mat") in the other parts of the simulation XML code in several manners (it is about the Scilab syntax) :

  • mat(i,j) : row i and column j element,

  • mat(i,:) : ith row matrix (last row if i = $),

  • mat(:,j) : jth column matrix (last column if j = $),

2.6. Point Tag

It allows to define a 2D or 3D point respecting eventually possibly constraints, each one being expressed by the reference to a curve to which it is constraint to belong and/or a set of inequalities that its coordinates must respect. It can comprise any explicit interface data entry, because its graphic representation can also be manipulable, providing that it is included in a system of axis via the drawpoints tag (cf. § Section 5.2.4, « Drawpoints Tag ») :

      <point label="id_point"
             widget="entry|hidden"
               -> Indicate if coordinates input fields must be present in the zone of the parameters data entry
             state="disabled|normal"
               -> disabled makes the input data zone disabled
      >

        none or several times :
        <name lang="french|english|german|spanish">
          parameter name as displayed in the coordinates data entry zone  nom du paramètre tel qu'affiché en regard
          des champs de saisie des coordonnées
        </name>

        once and only once :
        <x1 label="id_X_data_unit" unit="X data unit">
          none or several times :
          <name lang="french|english|german|spanish">
            X data name (not used at present)
          </name>
          once and only once :
          <value>
            X data initial value 
          </value>
        </x1>

        once and only once :
        <x2 label="id_X_data_unit" unit="Y data unit">
          none or several times :
          <name lang="french|english|german|spanish">
            Y data name (not used at present)
          </name>
          once and only once :
          <value>
            Y data initial value 
          </value>
        </x2>

        maximum once :
        <x3 label="id_Z" unit="Z data unit">
          none or several times :
          <name lang="french|english|german|spanish">
            Z data name (not used at present)
          </name>
          once and only once :
          <value>
            Z data initial value
          </value>
        </x3>

The constraints are used only to validate the point movements by the user, 
but not when a parameter on which they depend is modified :
        maximum once :
        <constraints label="id_contraints">
          none or several times :
          <inequality>
            inequality related to x1 and/or x2 and/or x3
            (These being identified by their label),
            as well as on potentially all the parameters of the simulation, 
            it is an expression which must be <= 0
          </inequality>
          maximum once :
          <curve ref="curve reference label" />
                   -> (cf. Section 4.2, « Mathematical Models »)
        </constraints>

        maximum once :
        <refconstraints ref="another constraint reference label" />
                          -> that the point must respect

      </point>

Paragraph § 3 of the document Getting started XMLlab includes an example of the point tag use.

2.7. Record Tag

It consists of defining a set of experimentation values for a set of scalar or matrix parameters defined by a parent tag database (cf. Section 2.2, «Database Tag »). A values set is named and refers to each one of these parameters by its label to assign it a value :

        <record>

          one or several times :
          <name lang="french|english|german|spanish">
            value set name as displayed in the value sets scrolling list  
          </name>

        one or several times :
        {
          <scalar-value ref="label of one of the parameters">
            value of this parameter for this value set
          </scalar-value>
            OR
          <matrix-value ref="label of one of the parameters ">
Values definition, columns, lines :
            none or several times :
            <col>
              once and only once :
              <value>
                element values of this column
                separated by spaces or commas
              </value>
            </col>
              OUR
            none or several times :
            <row>
              once and only once :
              <value>
                element values of this line
                separated by spaces or commas
              </value>
            </row>
          </matrix-value>
        }

        </record>

3. Actions

They allows to define a set of Scilab mini-scripts (one per action) executable via a menu entry, the purpose of each script being to update some parameters of the simulation. They allow to perform some calculations that cannot be described and supported by the mathematical models of XMLlab (cf. Section 4.2, « Mathematical Models »).

The following figure illustrates this mechanism: a set of actions named Identification was defined, which comprises the single action Linear Régression , whose purpose is to calculate the least squares line corresponding to the points entered by the user:

Figure 6.7. Actions menu example

Exemple de menu Actions

Here is the structure of the actions tag that, if it is present, must appear immediately after the definition of the simulation parameters (parameters tag) :

  maximum once :
  <actions>

    one or several times :
    <title lang="french|english|german|spanish">
      title of the actions set
        -> corresponds to the menu title added
    </title>

    one or several times :
    <action update="parameter list labels">
              -> It is a parameter which the value is update by the action;
                 the list separator is the space

      one or several times :
      <title lang="french|english|german|spanish">
        action title
          -> corresponds to the sub-menu title added
      </title>

      once and only once :
      <script href="script file path to be executed ">
        Scilab code to be executed
          -> being able to make involved any simulation parameter ;
             ignore if href attribut is present
      </script>

    </action>

  </actions>

4. Script or mathematical models

The next part in the simulation XML file is composed whether of a Scilab script (script tag), or whether of a definition of the mathematical models governing the simulation, this last case being the one that sticks best on the XMLlab philosophy.

4.1. Script

It consists of a Scilab script , that handles the simulation execution, the defined parameters being accessible as Scilab matrix variables (1x1 for scalars) :

  once and only once :
  <script href="script file path to be executed">
    cScilab code to be executed
      -> being able to make involved any simulation parameter ;
         ignore if href attribut is present
  </script>

4.2. Mathematical models

This section - that follows the tag </parameters> - allows to define the equations to be solved, the curves to calculate, as well as the range of values (1D or 2D) that certain variables must take. Here is the structure of the parameter definition:

  once and only once :
  <compute>

    none or several times :
    <defdomain1d | 
     defdomain2d | 
     ode | 
     implicitfunction |
     stationary-pde |
     nonparametriccurve2d | 
     parametriccurve2d | 
     parametriccurve3d | 
     nonparametricsurface |
     parametricsurface |
     polyline>... tag detailed in the following paragraphs 

  </compute>

4.2.1. Defdomain1d and refdomain1d Tags

  • Defdomain1d : it is the definition of a domain of values in one dimension, therefore an interval, that indicates the set of the discrete values taken by a variable (for example a integration variable). The interval is cut out linearly or logarithmically in a given number of steps:

        <defdomain1d label="id_domaine1d" unit="unité de la variable">
    
          none or several times :
          <name lang="french|english|german|spanish">
            variable name as displayed in the simulation save file 
          </name>
    
          once and only once :
          <interval discretization="linear|log"
                    steps="number of steps (default number 100)">
    
            <initialvalue>
              initial value 
            </initialvalue>
    
            <finalvalue>
              final valeu
            </finalvalue>
    
          </interval>
    
        </defdomain1d>
  • Refdomain1d Tag : It is the reference to a domain of values in one dimension defined by a defdomain1d tag, that allows for example, in the definition of a integration calculation, to define the values taken by the integration variable :

          <refdomain1d ref="ref_id_domaine1d">
          </refdomain1d>

4.2.2. Defdomain2d and refdomain2d Tags

  • Defdomain2d : it is the definition of a domain of values in two dimensions that indicates all the discreet values taken by a variable 2D. It can freely be defined by two different manners :

    • by a rectangle tag including two intervals, each of them being defined on the spot or by reference,

    • by a border tag, including the definition of one or several parametric 2D curves specifying the 2D domain boundary.

        <defdomain2d label="id_domaine2d"
                     dependencies="param_list_label">
                       -> the list separator is the space ;
                          that indicate that this calculation element depends  
                          only on the listed parameters, that avoid useless recalculations,
                          namely the triangulation of the domain if this one 
                          is defined via a <border> tag
    
          none or several times :
          <name lang="french|english|german|spanish">
            2D domain name as displayed in the simulation save file
          </name>
    
          once and only once :
          <rectangle>
            First values interval definition (cf. § Section 4.2.1, « Defdomain1d and
              refdomain1d Tags») :
            <defdomain1d>...
              OR
            <refdomain1d>...
            Second values interval definition :
            <defdomain1d>...
              OR
            <refdomain1d>...     
          </rectangle>
            OR
          <border>
            one or several times :
            <parametriccurve2d>... cf Section 4.2.7, « Parametriccurve2d Tag »
          </border>
    
        </defdomain2d>
  • Refdomain2d Tag : It is the reference to a values domain in two dimensions defined by adefdomain2d tag :

          <refdomain2d ref="ref_id_domaine2d">
          </refdomain2d>

4.2.3. Ode Tag

It allows to define a system of differential equations (ordinary differential equation) :

    <ode label="id_ode"
         dependencies="param_list_label">
           -> the list separator is the space ;
              that indicate that this calculation element depends  
              only on the listed parameters, that avoid useless recalculations
      ...
    </ode>

It gathers the following elements :

  • the domain of variation of the integration variable:

          once and only once :
          (cf. § Section 4.2.1, « Defdomain1d and
              refdomain1d Tag »)
          <defdomain1d>...
            OR
          <refdomain1d>...
  • the definition of the states, that are the functions involved in the different equations, with for each one of them, its derivative and its value at the initial time; intermediate variables of calculation can be defined to simplify the states formulas writing:

          once and only once :
          <states>
    
            none or several times :
            <variable label="stat_variable_id">
              Intermediate variable calculation formula  
            </variable>
    
            one or several times :
            <state label="stat_id"
                   size="1|2"
                     -> 1 : scalar, 2 : 2 components vector 
                   unit="stat_unit">
    
              one or several times :
              <name lang="french|english|german|spanish">
                state name as displayed in the simulation save file
              </name>
    
              once and only once :
              <derivative>
                state derivative 
              </derivative>
    
              once and only once :
              <initialcondition>
                state value at initial condition
              </initialcondition>
    
            </state>
    
          </states>
  • eventually a list of outputs depending potentially on the states, intermediate variables of calculation that can there too be defined to simplify the outputs formulas writing :

          maximum once :
          <outputs>
    
            one or several times :
            <output label="output_id"
                    unit="output_unit">
    
              one or several times :
              <name lang="french|english|german|spanish">
                output name as displayed in the simulation save file
              </name>
    
              none or several times :
              <variable label="inter_variable_id">
                intermediate variable calculation formula
              </variable>
    
              once and only once :
              <value>
                output calculation formula
              </value>
    
            </output>
    
          </outputs>

For examples of the ode tag, use refer to the following simulations:

4.2.4. Implicitfunction Tag

It is supposed that we have an equation f( x , y ) = 0. If for each value of x , this equation admits a single solution in y , the application that associates x to y is called implicit function ( of y as a function of x ). Exemple : whether the equation f( x , y ) = x 2 + y 2 - 1 = 0. For each value of x of the interval [0,1], the equation admits a unique solution y = 1 x 2 . However, it is not possible in general to express y as a function of x .

The role of the implicit function tag is actually to define a system of implicit functions :

    <implicitfunction label="implicit_function_id"
                      method="newton|dichotomic"
                        -> method used for the equation resolutions in each value of the variable in dependence
                           méthode utilisée pour la résolution des équations  en chaque valeur de la variable en dépendance
    >
      ...
    </implicitfunction>

It gathers the following elements:

  • the domain of variation of the variable on which depends the implicit function :

          once and only once :
          (cf. § Section 4.2.1, « Defdomain1d and
              refdomain1d Tag»)
          <defdomain1d>...
            OR
          <refdomain1d>...     
  • la définition des variables dont on recherche les valeurs pour chaque valeur de la variable précédente, en précisant pour chacune d'elle une valeur de départ pour sa recherche et éventuellement une borne inférieure et/ou une borne inférieure qu'elle doit respecter :

          once and only once :
          <unknowns>
            one or several times :
            <unknown label="unknown_id">
    
              one or several times :
              <name lang="french|english|german|spanish">
                unknown name as displayed in the simulation save file
              </name>
    
              once and only once :
              <guess>
                search start value 
              </guess>
    
              maximum once :
              <lowerbound>
                possible lower boundary to be respected 
              </lowerbound>
    
              maximum once :
              <upperbound>
                possible upper boundary to be respected
              </upperbound>
    
            </unknown>
          </unknowns>
  • The equations defining the system of implicit functions, as well as eventually intermediate variables facilitating their writing :

          once and only once :
          <equations>
    
            none or several times :
            <variable label="intermediate_variable_id">
              intermediate variable calculation formula
            </variable>
    
            one or several times :
            <equation>
              formula that must be worth 0
            </equation>
    
          </equations>
  • Eventually a list of ouputs variablesdepending potentially on intermediate variables and on the variable on which implicit functions depend:

          maximum once :
          <outputs>
    
            one or several times :
            <output label="output_id"
                    unit="output_unit">
    
              one or several times :
              <name lang="french|english|german|spanish">
                outputs name as displayed in the simulation save file
              </name>
    
              none or several times :
              <variable label="intermediate_variable_id">
                intermediate variable calculation formula
              </variable>
    
              once and only once :
              <value>
                output calculation formula
              </value>
    
            </output>
    
          </outputs>

For an example of implicit function tag use, refer to the acido-basic simulation of titration in aqueous medium, § Section 2.3.2, «  pH calculation using the dichotomic method ».

4.2.5. Stationary-pde Tag

It aims at describing the following Laplace equation:

div ( D u ) + c u = f , ( x , y ) Ω

with two types of boundary conditions :

  • robin : ( D u ) . n + σ i u = ξ i , ( x , y ) Γ i ,

  • dirichlet : u = g i , ( x , y ) Γ i .

knowing that the domain Ω have as boundary Γ = Γ0 ∪ Γ1 ∪ ... Γi ∪ ... Γn.

This tag has the following aspect, knowing that the definition of the 2d domain corresponding to Ω to which it refers, must include the definitions of Γ0, Γ1, ... Γi, ... Γn via a border tag containing a parametriccurve2d tag for each Γi. The convention being that the interior of the domain is always on the left curve when its parameter increases, which allows to build domains containing holes :

    <stationary-pde label="stationary_pde_id">

      once and only once :
      <refdomain2d ref="domaine2d_ref_id">...(cf. § Section 4.2.2, « Defdomain2d and
          refdomain2d Tag»)

      once and only once :
      <pdestate label="variable_u_id">

        one or several times :
        <name lang="french|english|german|spanish">
          variable name as displayed in the simulation save file
        </name>

        <inside>...equation definition

        <boundary>...boundary conditions definition 

      </pdestate>

    </stationary-pde>

Here is the detail of the elements concerning the equation and the boundary conditions :

  • Definition of the stationary partial derivatives in u, with the following correspondences :

    • the matrix D (that must be a constant) corresponds to the content of the diffusion tag,

    • the function c(x, y) to the proportional tag,

    • f(x, y) to the source tag.

            once and only once :
            <inside dependencies="param_list_label">
                      -> the list separator is the space ;
                         that indicate that this calculation element depends  
                         only on the listed parameters, that avoid useless recalculations,
                         here the assembly problem in the domain
    
              <diffusion>
                matrix D  -> must be a constant
              </diffusion>
    
              <proportional>
                function c(x,y)
              </proportional>
    
              <source>
                function f(x,y)
              </source>
    
            </inside>
  • the definition of the boundary conditions with the following correspondences, given that it is possible that there are fewer definite conditions than of Γi : an absence of condition on a piece of the edge of Ω corresponds to a homogeneous Neuman condition (the normal derivative of the state is equal to zero):

    • σi(x, y) et ξi(x, y) corresponds to sigma and xi tags,

    • gi(x, y) to the dirichlet tag.

            maximum once :
            <boundary dependencies="param_list_label">
                        -> the list separator is the space ;
                           that indicate that this calculation element depends  
                           only on the listed parameters, that avoid useless recalculations,
                           here the boundary condition assembly
    
              one or several times :
              <condition bdy="2D_domain_element_label">
                           -> it is one of the labels identifying one  
                              parametric curves defined in 
                              defdomain2d tag referred by 2ddomain_ref_id ;
                              it is indicated thus on which boundary 
                              element <i> concerns the condition
    
                once and only once :
                <robin>
                  <xi>
                    function ξ(x,y)
                  </xi>
                  <sigma>
                    function σ(x,y)
                  </sigma>
                </robin>
                  OR
                <dirichlet>
                  function g(x,y)
                </dirichlet>
    
              </condition>
    
            </boundary>

Caution: when the coefficients are functions, one must absolutely use x and y to handle the X-coordinate and the ordinate (whatever the labels used in the parametriccurve2d in the border).

For an example of stationary-pde tag use, refers to simulation via finite elements of the Poisson's equation, § Section 2.3.4, « Definition of the stationary partial derivatives ».

4.2.6. Nonparametriccurve2d Tag

It deals with a curve defined by a function y = f(x). It contains the domain of variation of x and the definition of f :

    <nonparametriccurve2d label="curve_id">

      none or several times :
      <name lang="french|english|german|spanish">
        possible curve name as displayed in its plot (cf. § Section 5.2.1, « Drawcurve2d Tag»)
      </name>

X definition :
      once and only once :
      (cf. § Section 4.2.1, « Defdomain1d and
          refdomain1d Tag»)
      <defdomain1d>...
        OR
      <refdomain1d>...

Y definition y = f(x) :
      once and only once :
      <x2 label="Y_data_id" unit="Y data unit">
        none or several times :
        <name lang="french|english|german|spanish">
          Y data name (not used at present)
        </name>
        once and only once :
        <value>
          f(x)
        </value>
      </x2>

    </nonparametriccurve2d>

For an example of nonparametriccurve2d Tag use, refer to the file Math/tangente.xml in the subdirectory examples of the XMLlab installation directory .

4.2.7. Parametriccurve2d Tag

It consists of a parametric curve x = f(t), y = g(t). It contains the domain of variation of t and the definitions of f and g :

    <parametriccurve2d label="curve_id">

      none or several times :
      <name lang="french|english|german|spanish">
        possible curve name as displayed in its plot (cf. § Section 5.2.1, « Drawcurve2d Tag»)
      </name>

T definition :
      once and only once :
      (cf. § Section 4.2.1, « Defdomain1d and
          refdomain1d Tag»)
      <defdomain1d>...
        OR
      <refdomain1d>...

X definition x = f(t) :
      once and only once :
      <x1 label="X_data_id" unit="X data unit">
        none or several times :
        <name lang="french|english|german|spanish">
          X data name (not used at present)
        </name>
        once and only once :
        <value>
          f(t)
        </value>
      </x1>

Y definition  y = g(t) :
      once and only once :
      <x2 label="Y_data_id" unit="Y data unit">
        none or several times :
        <name lang="french|english|german|spanish">
          Y data name (not used at present)
        </name>
        once and only once :
        <value>
          g(t)
        </value>
      </x2>

    </parametriccurve2d>

For example of parametriccurve2d tag use, refers to the following simulations :

4.2.8. Parametriccurve3d Tag

It consists of a parametric curve x = f(t), y = g(t), z = h(t). It contains the domain of variation of t and the definitions of f, g and h :

    <parametriccurve3d label="curve_id">

      none or several times :
      <name lang="french|english|german|spanish">
        possible curve name as displayed in its plot (cf. § Section 5.2.3, « Drawsurface Tag »)
      </name>

      none or several times :
      (cf. § Section 4.2.1, « Defdomain1d and
          refdomain1d Tag »)
      <defdomain1d>...
        OR
      <refdomain1d>...

      once and only once :
      <x1 label="X_data_id" unit="X data unit">
        none or several times :
        <name lang="french|english|german|spanish">
          X data name  (not used at present)
        </name>
        once and only once :
        <value>
          f(t)
        </value>
      </x1>

      once and only once :
      <x2 label="Y_data_id" unit="Y data unit">
        none or several times :
        <name lang="french|english|german|spanish">
          Y data name (not used at present)
        </name>
         once and only once :
        <value>
          g(t)
        </value>
      </x2>

      once and only once :
      <x3 label=" z_id" unit="z unit">
        none or several times :
        <name lang="french|english|german|spanish">
          z name (not used at present)
        </name>
        once and only once :
        <value>
          h(t)
        </value>
      </x3>

    </parametriccurve3d>

For an exemple of parametriccurve3d tag use , refers to the file Math/helice.xml in the subdirectory examples of the XMLlab installation directory .

4.2.9. Nonparametricsurface Tag

It deals with a non parametric surface z = h(x, y). Its contains the 2D domain of the variation of (x, y) and the definition of h :

    <nonparametricsurface label="surface_id">

      none or several times :
      <name lang="french|english|german|spanish">
        possible curve name as displayed in its plot (cf. § Section 5.2.3, « Balise drawsurface »)
      </name>

      once and only once :
      (cf. § Section 4.2.2, « Defdomain2d and
          refdomain2d Tag»)
      <defdomain2d>...
        OR
      <refdomain2d>...

      once and only once :
      <x3 label=" z_id" unit="z unit">
        none or several times :
        <name lang="french|english|german|spanish">
          z name (not used at present)
        </name>
        once and only once :
        <value>
          h(x,y)
            -> X and y being labels identifying the x and y coordinates 
               of 2D domaine points, namely as this one contains one :
               - <rectangle> : x and y are the 2 domains 1D labels
                               defined or in reference,
               - <border>    : x and y are the <x1> and <x2> tags labels of
                               <parametriccurve2d> defining the 2D domain.
        </value>
      </x3>

    </nonparametricsurface>

For an exemple of nonparametricsurface tag use, refers to the Math/gauss.xml file in the subdirectory examples of the XMLlab installation directory .

4.2.10. Parametricsurface Tag

It deals wtih a parametric surface x = f(θ, φ), y = g(θ, φ), z = h(θ, φ). Its contains the 2D domain of variation of (θ, φ) and the definition of f, g and h :

    <nonparametricsurface label="id_surface">

      none or several times :
      <name lang="french|english|german|spanish">
        possible curve name as displayed in its plot (cf. § Section 5.2.3, « Balise drawsurface »)
      </name>

      once and only once :
      (cf. § Section 4.2.2, « Defdomain2d and
          refdomain2d Tag»)
      <defdomain2d>...
        OR
      <refdomain2d>...

      once and only once :
      <x1 label="X_data_id" unit="X data unit">
        none or several times :
        <name lang="french|english|german|spanish">
          X data name (not used at present)
        </name>
        once and only once :
        <value>
          f(θ,φ)
        </value>
      </x1>

      once and only once :
      <x2 label="Y_data_id" unit="Y data unit">
        none or several times :
        <name lang="french|english|german|spanish">
          Y data name  (not used at present)
        </name>
        once and only once :
        <value>
          g(θ,φ)
        </value>
      </x2>

      once and only once :
      <x3 label="z_id" unit="z unit">
        none or several times :
        <name lang="french|english|german|spanish">
          z name  (not used at present)
        </name>
        once and only once :
        <value>
          h(θ,φ)
        </value>
      </x3>

    </nonparametricsurface>

For an exemple of the parametricsurface tag use, refers to the file Math/sphere.xml in the subdirectory examples of the XMLlab installation directory.

4.2.11. Polyline Tag

It deals with a 2D or 3D multiline curve defined by a set of points (vertex tag) of segments composing it :

    <polyline label="id_courbe">

      none or several times :
      <name lang="french|english|german|spanish">
        possible curve name as displayed in its plot (cf. § Section 5.2.1, «Drawcurve2d Tag»)
      </name>

      one or several times :
      <vertex x1="x" x2="y" x3="z">

        none or several times :
        <name lang="french|english|german|spanish">
          possible curve name as displayed in its plot
        </name>

      </vertex>

    </polyline>

For an exemple of the polyline tag use, refers tothe file Math/gauss.xml provided in the subdirectory examples of the XMLlab installation directory.

5. Results display

This section - that follows the </compute> Tag - is optional and allows to define the different graphic windows, a set of system of axes for each one of them (windows can then be divided horizontally or vertically to contain them) as well as the curves that must be respectively displayed in each system of axis. Here is the structure of the graphic windows definition :

  maximum once :
  <display background="white|black|blue">
             -> name of the background color curves displayed in all windows, 
                a grey frame surrounding curves

    one or several times :
    <window dependencies="param_label_list"
              -> The list separator is the space ;
                 that indicate that this window contents depends  
                 only on the listed parameters, that avoid useless recalculations
            splitx="1|2|3"
              -> indicate that the window is horizontally divided  
                 into as many axis systems
            splity="1|2|3"
              -> indicate that the window is vertically divided
                 into as many axis systems
            colormap="gray|hot|copper|cool|bone|jet|red|green|blue"
              -> color pallet to use for the window
    >

      none or several times :
      <title lang="french|english|german|spanish">
        possible window title
      </title>

      one or several times :
      <axis2d |
       axis3d>... detailed tag in the following paragraphs 

    </window>

  </display>

5.1. Systems of axes

5.1.1. Axis2d Tag

It consists of a 2D axes system contained in a window or a part of a window, and for which we define:

  • its type: Cartesian or polar,

  • the positioning of the axes,

  • eventually the extrema of abscissas and ordinates that are otherwise calculated automatically,

  • if a surface (via a drawsurface tag) is included in the 2D axes system, the variations of z are illustrated by variations of colors (the attributes cmin and cmax indicating then the range of variation of z) and a corresponding legend can be associated,

  • the identity or not of the scales of abscissas and ordinates,

  • the curves to be displayed.

      <axis2d type="cartesian|polar"
              position="left|right|center|origin"
                -> - "left" or "right" : puts the y axis at left or at right
                   - "center" : always puts the axes crossing in the center of the graphic window 
                   - "origin" : puts the axis crossing if possible at (0,0)
              xmin="x_min" xmax="x_max"
              ymin="y_min" ymax="y_max"
              iso="yes|no"
                -> indicate if, whatever is the system of axis size  
                   (via the recutting of the window which contains it),
                   the scales of X, and Y are identical
              cmin="z_min" cmax="z_max"
              colorbar="on|off|top|left|right|bot"
                -> position of the possible legend "color(z)"  
                   ("on" is equivalent to "left")
      >

        one or several times :
        <drawcurve2d |
         drawsurface |
         drawpoints>... cf. § Section 5.2, « Curves and surfaces »

      </axis2d>

For examples of the axis2d tag use, refers to the following simulations :

5.1.2. Axis3d Tag

It deals whith a 3D system of axes contained in a window or a part of window, and for which we define :

  • eventually the extrema of abscissas, ordinates and the z taht are otherwise calculated automatically,

  • the values of the elevation and the azimuth that indicate the point of view of the observer of the 3D axes system,

  • the identity or not of the scales of abscissas, ordinates and of the z,

  • the variations of z or of the illumination (if mode="light" in a drawsurface tag included) are illustrated by colors variations (the attributes cmin and cmax then indicating the variation range of z - the minimum and the maximum of z being used in their absence - or of the illumination) and a corresponding legend can be associated,

  • the surfaces to be displayed.

      <axis3d xmin="x_min" xmax="x_max"
              ymin="y_min" ymax="y_max"
              zmin="z_min" zmax="z_max"
              elevation="3D view elevation (default number 45)" -> in degree
              azimuth="3D view azimuth (default number -45)"    -> in degree
              iso="yes|no"
                -> indicate if, whatever is the system of axis size  
                   (via the recutting of the window which contains it),
                   the scales of X, Y and Z are identical 
              cmin="min_z_or_illumination" cmax="max_z_or_illumination"
              colorbar="off|top|left|right|bot"
                -> position of the possible legend 
                   "color (Z or illumination)"   
      >

        one or several times :
        <drawsurface |
         drawcurve3d>... cf. § Section 5.2, « Curves and surfaces »

      </axis3d>

For examples of axis3d tag use, refers to the simulation via finite elements of the Poisson's equation, § Section 2.4, « Results display ».

5.2. Curves and surfaces

5.2.1. Drawcurve2d Tag

It consists of a 2D curve displayed in a 2D system of axes, and for which we defines :

  • the reference to the label of the curve to be drawn,

  • graphic properties of the layout: color, type and line thickness, possible marker of the curve points.

        <drawcurve2d ref="curve label to draw"
                       -> could be the label of one of the following tags :
                          - <state> of one <ode>
                          - <unknown> of one <implicitfunction>
                          - <nonparametriccurve2d>
                          - <parametriccurve2d>
                          - <polyline>
                     color="auto|blue|green|red|cyan|magenta|black|yellow"
                       -> "auto" : colors follow a cycle from a curve 
                          to the other one among the curves of the same <axis2d>
                          (there are two possible cycles as the  
                           <window> background is rather "clear" or "dark")
                     linetype="solid|dashed|dashdot|none"
                       -> - "solid" : continuous line
                          - "dashed" : dashed line
                          - "dashdot" : alternation of points and lines
                          - "none" : has sense only if marker is defined:
                                     there is even in that case a line
                                     which connects points, except if linetype="none"
                     thickness="1|2|3|4|5"  -> line thickness
                     marker="point|circle|trefoil|plus|star|diamond|
                             filled-diamond|triangle-up|triangle-down"
                       -> point, circle, trefoil, plus sign, star, 
                          diamond, filled diamond, triangle point in top, 
                          triangle points in bottom
        />

For examples of the drawcurve2d tag use , refers to the following simulations:

5.2.2. Drawcurve3d Tag

It deals with 3D curves displayed in a 3D system of axes, and for which we define:

  • the reference to the label of the curve to be drawn,

  • graphic properties of the layout: color, type and line thickness, possible marker of the curve points.

        <drawcurve3d ref="curve label to draw"
                       -> could be the label of one of the following tags :
                          - <state> of one <ode>o
                          - <pdestate> of one <stationary-pde>
                          - <parametriccurve3d>
                          - <polyline>
                     color="auto|blue|green|red|cyan|magenta|black|yellow"
                       -> "auto" : colors follow a cycle from a curve 
                          to the other one among the curves of the same <axis2d>
                          (there are two possible cycles as the  
                           <window> background is rather "clear" or "dark")
                     linetype="solid|dashed|dashdot|none"
                       -> - "solid" : continuous line
                          - "dashed" : dashed line
                          - "dashdot" : alternation of points and lines
                          - "none" : has sense only if marker is defined:
                                     there is even in that case a line
                                     which connects points, except if linetype="none"
 
                     thickness="1|2|3|4|5"  -> line thickness
                     marker="point|circle|trefoil|plus|star|diamond|
                             filled-diamond|triangle-up|triangle-down"
                       -> point, circle, trefoil, plus sign, star, 
                          diamond, filled diamond, triangle point in top, 
                          triangle points in bottom
        />

For examples of the drawcurve3d tag use, refers to the file Math/helice.xml located in the subdirectory examples of the installation directory of XMLlab.

5.2.3. Drawsurface Tag

It consists a displayed surface in a 2D or 3D axes system, and for which we defines :

  • the reference to thelabel of the curve to be drawn,

  • graphic properties of the layout: mode of representation of surface and the type of shade obtained.

        <drawsurface ref="surface label to draw"
                       -> could be the label of one of the following tags :
                          - <pdestate> of one <stationary-pde>
                          - <parametriccurve3d>
                          - <nonparametricsurface>
                          - <parametricsurface>
                          - <polyline>
                     mode="level|light|wireframe"
                       -> - level : surface filled, color aiming 
                                    towards the black when Z decreases,
                          - light : surface filled, shade calculated 
                                    in function to a source of light,
                          - wireframe : wire representation.
                     shading="flat|interp|faceted"
                       -> shadow depiction, only taken into account 
                          if mode <> "wireframe" :
                          - flat : plain on each facet,
                          - interp : continue, by interpolation on each facet,
                          - faceted : flat + white wire around each facet in superpositionf
                     hidden="off"  -> not used at present
        />

For examples of the drawsurface tag use, refers to the simulation via finite elements of the Poisson's equation, § Section 2.4, « Results display ».

5.2.4. Drawpoints Tag

It deals with a list of 2D or 3D points displayed in a 2D or 3D system of axes, each point being illustrated by a cross accompanied by its co-ordinates :

        <drawpoints ref="points_labels_list"
                      -> list, separated by spaces,
                         <point> labels to draw
        />

Moreover, the position of each 2D point listed is manipulable from the constraints defined on it remain respected : click on the cross, the coordinates of the point is displayed then in a different color. Move then the cursor to modify its position. All the calculations resulting from the modification of this parameter are then realized in real time and curves in dependence are displayed again. Once obtained the wished value, click again the cross to fix its position.

For examples of the drawpoints tag use, refers to the simulation of the pendulum in the document Getting started XMLlab.

6. Save the simulation results

This section - which follows the </display> tag - is optional. It allows to define a set of parameters and of simulation results which can be saved via the entry of menu File->Save the simulation results :

  <save>

    one or several times :
    <file href="save file"
            -> name initially proposed during the saving demand
          format="csv|scilab"
            -> file format : CSV or Scilab
          labels="labels_list"
            -> list, separated by spaces, parameters labels and results to save
    />

  </save>

For examples of CSV file obtained, refers to the simulation of kinetics of prey predation by predators, § Section 2.4, « Results display ».

Chapter 7. XMLlab command and menu lines

1. Command line

Since the line of command Unix or Scilab, take place in the directory containing the XML file and tape the following command:

xmllab -run nom_simulation.xml

2.  XMLlab simulation menu

2.1. File Menu

It contains the following entries :

  • Execute : Today, the modification of a simulation parameter automatically lead to the recalculation of the mathematical models and the displayed curves. It will nevertheless be possible in a near future to make this recalculation manual for some parameters; in the case where the time necessary to do it would be too important. This menu entry will allow to start this recalculation manually.

  • Save the session : saves in a file all the simulation parameters of the simulation, under a code Tcl file type.

  • Load a session : restores the values of all the parameters, via the execution of a Tcl code file previously saved.

  • Save the simulation results: this entry, that is present only if the simulation contains a section <save>...</save> (cf. § Section 6, « Save the results of the simulation »), saves all the parameters and the simulation results that are specified.

  • Quit : quits the simulation.

2.2. Actions Menu

This menu is present only if the simulation contains a section <actions>...</actions> (cf. § Section 3, « Actions ») that defines then a set of Scilab mini-scripts (one per action) executable via an entry of this menu, the purpose of every script being to update certain parameters of the simulation.

2.3. Parameters Menu

It contains one entry per sections of simulation parameters defined (cf. § Section 2, « Parameters »).

2.4. XMLlab Menu

It contains the following entries :

  • About XMLlab : indicates the precise version of the XMLlab software and the addresses of their authors.

  • About this simulation : displays notes relating to the simulation (cf. § Section 1.2, « Simulation notes »).

3. Scilab XMLlab menu

It contains the following entries :

  • Execute a simulation : proposes to select a simulation in the file tree structure (by positioning initially in the examples sub-directory of the XMLlab installation directory) and executes it.

  • Edit a simulation :propose to select a simulation in the file tree structure and runs its edition in the SciPad of Scilab editor. This one is extended by XMLlab and contains the supplementary XMLlab menu allowing to validate (entry of menu Validate) and to execute (entry of menu Run) the edited simulation.

  • Demos XMLlab : displays a list of simulation categories, the choice of a list causing the display of the list of the corresponding simulations, the choice of a simulation causing its execution.

  • Help : displays the manpage of XMLlab.

  • About XMLlab : indicates the precise version of the XMLlab software, the addresses of their authors, and its licence type.

  • Uninstalling XMLlab : uninstalls XMLlab.