2. Paramètres

Les paramètres de la simulation, si elle en possède, sont définis au sein d'une unique balise <parameters>...</parameters>, celle-ci étant découpée en plusieurs sections, chacune d'elle permettant de grouper logiquement un ensemble de paramètres, et donnant lieu à une entrée différente du menu Paramètres de la simulation. Une section au moins doit être définie.

Le choix d'une entrée provoque alors l'affichage des paramètres correspondant. Voici la structure de la définition des paramètres :

  une fois au plus :
  <parameters widget="plain|notebook">

    une ou plusieurs fois :
    <section hidden="no" label="id_section">
                           -> id_section est réservé à un usage futur

      aucune ou plusieurs fois :
      <title lang="french|english|german|spanish">
        titre de la section (et du sous-menu ou de l'onglet correspondant)
        cf. explication de l'attribut widget de la balise parameters ci-dessous
      </title>

      aucune ou plusieurs fois :
      <notes lang="french|english|german|spanish">
        une ou plusieurs fois :
        <p>note sur la section</p>
      </notes>

      une ou plusieurs fois :
      <scalar|matrix|point|group>... balises détaillées plus loin
        OU
      une ou plusieurs fois :
      <subsection|database>... balises détaillées plus loin

    </section>

  </parameters>

L'utilisation de la forme <parameters widget="notebook"> entraîne une présentation de l'IHM de la fenêtre à base d'onglets (seul demeure le menu Fichier), plutôt qu'à base de menus et sous-menus pour accéder aux différentes sections de paramètres, à la sauvegarde des résultats de la simulation, ainsi qu'aux notes concernant XMLlab et à celles concernant la simulation. Ceci est illustré par la figure suivante :

Figure 6.1. Présentation de l'IHM à base d'onglets

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

2.1. Balise subsection

Elle permet, à l'intérieur d'une section, de grouper logiquement un ensemble de paramètres, les paramètres de chaque sous-section étant alors rassemblés visuellement dans la fenêtre de saisie. La structure de cette balise est la suivante :

      <subsection hidden="no" label="id_sous-section"
                  tearoff="yes|no" explication de cet attribut ci-dessous
      >

        aucune ou plusieurs fois :
        <title lang="french|english|german|spanish">
          titre de la sous-section (et du cadre entourant ses paramètres)
          cf. exemple ci-dessous
        </title>

        aucune ou plusieurs fois :
        <notes lang="french|english|german|spanish">
          une ou plusieurs fois :
          <p>note sur la section</p>
        </notes>

        une ou plusieurs fois :
        <scalar|matrix|point|group>... balises détaillées plus loin

    </subsection>

Voici un exemple d'IHM correspondant à une section découpée en deux sous-sections Coefficients de la droite et Données de l'utilisateur, dont l'attribut tearoff a été positionné à yes : un clic sur l'icône entraîne alors l'affichage de la sous-section correspondante dans une fenêtre séparée.

Figure 6.2. Exemple d'utilisation de sous-sections

Exemple d'utilisation de sous-sections

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

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

2.2. Balise database

Elle permet de définir un ensemble de jeux de valeurs d’expérimentation pour un ensemble de paramètres scalaires ou matriciels, chaque jeu de valeurs étant nommé. Le fichier Acid-equilibria/Acid_base_titration.xml fourni dans le sous-répertoire examples du répertoire d'installation de XMLlab illustre sont utilisation : il s'agit d'une simulation de titrage acido-basique en milieu aqueux et la figure ci-dessous montre le jeu de valeurs de paramètres Acide citrique, parmi un ensemble de jeux de valeurs dont le choix est effectué via une liste déroulante.

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

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

Il est également possible de spécifier que l'ensemble des jeux de valeurs est modifiable (via l'attribut editable de la balise database), les modifications possibles étant alors les suivantes (la simulation est relancée après chaque modification) :

  • Ajout d'un jeu de valeurs : sélectionner l'entrée Défini par l'utilisateur : la renommer avec le nom de ce nouveau jeu, remplir les valeurs des paramètres correspondants, puis cliquer sur l'icône pour enregistrer l'ajout dans le fichier XML.

  • Suppression d'un jeu de valeur : sélectionner l'entrée à supprimer, et cliquer sur l'icône pour enregistrer la suppression dans le fichier XML.

  • Modification de l'entrée sélectionnée initialement : la sélectionner, et cliquer sur l'icône pour enregistrer la modification dans le fichier XML.

Voici la structure de la définition d'un ensemble de jeux de valeurs :

      <database editable="yes|no"
                tearoff="yes|no" cf. Section 2.1, « Balise subsection »
                label="id_database" -> réservé à un usage futur
      >

        aucune ou plusieurs fois :
        <title lang="french|english|german|spanish">
          titre de l'ensemble de jeux de valeurs
         (et du cadre entourant ses paramètres)
        </title>

Définition de l'ensemble des paramètres de chaque jeu de valeurs :
        une ou plusieurs fois :
        <scalar|matrix|group>... balises détaillées plus loin

Définition de l'ensemble des jeux de valeurs, avec pour chacun d'eux
la valeur correspondante pour chacun des paramètres :
        aucune ou plusieurs fois :
        <record>
          ... cf. Section 2.7, « Balise record »
        </record>

      </database>

Concernant la sous-balise group de la balise database, il faut préciser qu'elle ne peut dans ce cas contenir à son tour une balise point.

2.3. Balise group

Elle permet de grouper logiquement un ensemble de paramètres à l'intérieur d'une section ou d'une sous-section, les paramètres en question apparaissant sur une même ligne. La figure suivante présente un exemple d'utilisation concernant la même section de paramètres illustrée par la Figure 3.4, « Saisie des paramètres du titrage », et pour laquelle les sous-sections ont été remplacées par des groupes :

Figure 6.5. Exemple d'utilisation de la balise group

Exemple d'utilisation de la balise group

Voici la structure de la définition d'un groupe de paramètres :

      <group>

        aucune ou plusieurs fois :
        <title lang="french|english|german|spanish">
          titre du groupe de paramètres
        </title>

Définition de l'ensemble des paramètres du groupe :
        une ou plusieurs fois :
        <scalar|matrix|point>... balises détaillées plus loin

      </group>

2.4. Balise scalar

Il s'agit de la définition d'un paramètre scalaire, dont la valeur est éventuellement contrainte par des bornes, ainsi que du widget utilisé pour sa saisie :

      <scalar label="id_scalaire" unit="unité du scalaire"
              widget="entry|slider|hidden|animate"
              state="disabled|normal"
                -> disabled rend insensible le widget,
                   empêchant ainsi la saisie du paramètre

              Les deux attributs suivants ne servent actuellement que
              si widget="slider|animate", mais ils serviront dans un usage futur
              à effectuer une vérification de la saisie dans un widget entry.
              min="min du scalaire" max="max du scalaire"
                -> définissent les éventuelles bornes
                   min et max du scalaire

              increment="pas d'incrément du scalaire"
                -> utilisé lorsque le scalaire augmente ou diminue d'un pas :
                   - widget="animate" : lors de l'animation
                   - widget="slider"  : lors d'un clic à gauche ou à droite
                                        de la glissière
              period="période du scalaire (10 par défaut)"
                -> nombre de millisecondes entre chaque variation de la valeur
                   du paramètre lors d'une animation

              scale="échelle du scalaire (1 par défaut)"
                -> il s'agit du facteur entre la valeur saisie et
                   la valeur alors attribuée au scalaire
      >

        une ou plusieurs fois :
        <name lang="french|english|german|spanish">
          nom du paramètre tel qu'affiché devant sa zone de saisie
        </name>

Notes à seules fins de commentaire sur le paramètre scalaire :
        aucune ou plusieurs fois :
        <notes lang="french|english|german|spanish">
          une ou plusieurs fois :
          <p>note sur le paramètre scalaire</p>
        </notes>

        une et une seule fois :
        <value>
          valeur initiale du paramètre
        </value>

      </scalar>

Voici des exemples de représentations pour les différentes valeurs possibles de l'attribut widget :

  • entry :

  • slider :

  • hidden : cet attribut indique qu'il n'y a aucune représentation associée à ce paramètre. Il s'agit donc d'un paramètre pour un usage interne à la simulation, comme par exemple une constante physique ou chimique.

  • animate : il permet à l'utilisateur de faire varier en continu la valeur du paramètre entre ses bornes définies, et selon le pas d'incrément spécifié. Ainsi, la représentation ci-après est issue du code qui suit :

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

    Les 4 boutons situés en regard de la glissière permette respectivement de :

    • démarrer l'animation jusqu'à la valeur finale du paramètre,

    • de la démarrer en repartant depuis la valeur initiale quand la valeur finale est atteinte,

    • de la démarrer en repartant en sens inverse vers la valeur initiale quand la valeur finale est atteinte,

    • de mettre en pause l'animation.

2.5. Balise matrix

Il s'agit de la définition d'un paramètre matriciel, dont la valeur peut éventuellement être sauvegardée ou chargée depuis un fichier, et dont soit les titres de lignes, soit les titres de colonnes sont définis :

      <matrix label="id_matrice"
              rows="nb de lignes" cols="nb de colonnes"

              Les 2 attributs suivants indiquent respectivement que les
              lignes et/ou colonnes vides ou nulles situées en fin de matrice
              doivent être supprimées.
              striprow="yes|no"
              stripcol="yes|no"

              Les 3 attributs suivants indiquent si les icônes de chargement,
              de sauvegarde et de mise à blanc de la matrice doivent
              respectivement apparaître (cf. exemple ci-après).
              load="yes|no"
              save="yes|no"
              clear="yes|no"

              widget="hidden|normal"
                -> indique si le widget de saisie est visible ou pas
      >

        une ou plusieurs fois :
        <name lang="french|english|german|spanish">
          nom du paramètre tel qu'affiché au-dessus de la matrice de saisie
        </name>

Notes à seules fins de commentaire sur le paramètre matriciel :
        aucune ou plusieurs fois :
        <notes lang="french|english|german|spanish">
          une ou plusieurs fois :
          <p>note sur le paramètre scalaire</p>
        </notes>

Définition des titres et valeurs par défaut des colonnes ou des lignes :
        aucune ou plusieurs fois :
        <col>
          aucune ou plusieurs fois :
          <name lang="french|english|german|spanish">
            titre de cette colonne
          </name>
          une et une seule fois :
          <value>
            valeur initiale des éléments de cette colonne
          </value>
        </col>
          OU
        aucune ou plusieurs fois :
        <row>
          aucune ou plusieurs fois :
          <name lang="french|english|german|spanish">
            titre de cette ligne
          </name>
          une et une seule fois :
          <value>
            valeur initiale des éléments de cette ligne
          </value>
        </row>

      </matrix>

Voici un exemple de fenêtre de saisie d'un paramètre matriciel 64x2, les lignes correspondant à des points expérimentaux, les deux colonnes correspondant respectivement à leur abscisse et à leur ordonnée :

Figure 6.6. Saisie des points expérimentaux

Saisie des points expérimentaux

Elle peut être sauvegardée via l'icône (save="yes") dans un fichier texte portant l'extension .dat, chargée depuis un même fichier .dat via l'icône (load="yes"), ou réinitialisée à blanc via l'icône (clear="yes").

La portion de code XML correspondant à la définition de cette matrice est la suivante :

      <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>

Il peut en outre être fait référence aux éléments d'une matrice (supposons label="mat") dans d'autres portions du code XML d'une simulation de plusieurs manières (il s'agit de la syntaxe Scilab) :

  • mat(i,j) : élément à la ligne i et à la colonne j,

  • mat(i,:) : ième ligne de la matrice (dernière ligne si i = $),

  • mat(:,j) : jème colonne de la matrice (dernière colonne si j = $),

2.6. Balise point

Elle permet de définir un point 2D ou 3D respectant éventuellement des contraintes, chacune d'elle s'exprimant par la référence à une courbe à laquelle il est contraint d'appartenir et/ou un ensemble d'inégalités que ses coordonnées doivent respecter. Il peut ne comporter aucune interface de saisie explicite, car sa représentation graphique peut également être manipulable, pour peu qu'il soit inclus dans un système d'axe via la balise drawpoints (cf. § Section 5.2.4, « Balise drawpoints ») :

      <point label="id_point"
             widget="entry|hidden"
               -> indique si des champs de saisie des coordonnées doivent
                  être présents dans la zone de saisie des paramètres
             state="disabled|normal"
               -> disabled rend insensible ces zones de saisie
      >

        aucune ou plusieurs fois :
        <name lang="french|english|german|spanish">
          nom du paramètre tel qu'affiché en regard
          des champs de saisie des coordonnées
        </name>

        une et une seule fois :
        <x1 label="id_abscisse" unit="unité des abscisses">
          aucune ou plusieurs fois :
          <name lang="french|english|german|spanish">
            nom de l'abscisse (pas utilisé actuellement)
          </name>
          une et une seule fois :
          <value>
            valeur initiale de l'abscisse
          </value>
        </x1>

        une et une seule fois :
        <x2 label="id_ordonnée" unit="unité des ordonnées">
          aucune ou plusieurs fois :
          <name lang="french|english|german|spanish">
            nom de l'ordonnée (pas utilisé actuellement)
          </name>
          une et une seule fois :
          <value>
            valeur initiale de l'ordonnée
          </value>
        </x2>

        une fois au plus :
        <x3 label="id_z" unit="unité des z">
          aucune ou plusieurs fois :
          <name lang="french|english|german|spanish">
            nom du z (pas utilisé actuellement)
          </name>
          une et une seule fois :
          <value>
            valeur initiale du z
          </value>
        </x3>

Les contraintes ne sont utilisée que pour valider les déplacements du point par
l'utilisateur, mais pas lorsqu'un paramètre dont elles dépendent est modifié :
        une fois au plus :
        <constraints label="id_contrainte">
          aucune ou plusieurs fois :
          <inequality>
            inégalité pouvant portant sur x1 et/ou x2 et/ou x3
            (ceux-ci étant identifiés par leur label),
            ainsi que sur potentiellement tous les paramètres de la simulation
            il s'agit d'un expression qui doit être <= 0
          </inequality>
          une fois au plus :
          <curve ref="référence au label d'une courbe" />
                   -> (cf. Section 4.2, « Modèles mathématiques »)
        </constraints>

        une fois au plus :
        <refconstraints ref="référence au label d'une autre contrainte" />
                          -> que le point doit respecter

      </point>

Le § 3 du document Prise en main XMLlab comporte un exemple d'utilisation de la balise point.

2.7. Balise record

Elle sert à définir un jeu de valeur d’expérimentation pour un ensemble de paramètres scalaires ou matriciels défini par une balise mère database (cf. Section 2.2, « Balise database »). Un jeu de valeurs est nommé et fait référence à chacun de ces paramètres par son label pour lui attribuer une valeur :

        <record>

          une ou plusieurs fois :
          <name lang="french|english|german|spanish">
            nom du jeu de valeur tel qu'affiché dans
            la liste déroulante des jeux de valeurs
          </name>

        une ou plusieurs fois :
        {
          <scalar-value ref="label d'un des paramètres">
            valeur de ce paramètre pour ce jeu de valeur
          </scalar-value>
            OU
          <matrix-value ref="label d'un des paramètres">
Définition des valeurs, soit des colonnes, soit des lignes :
            aucune ou plusieurs fois :
            <col>
              une et une seule fois :
              <value>
                valeur des éléments de cette colonne
                séparées par des espaces ou des virgules
              </value>
            </col>
              OU
            aucune ou plusieurs fois :
            <row>
              une et une seule fois :
              <value>
                valeur des éléments de cette ligne
                séparées par des espaces ou des virgules
              </value>
            </row>
          </matrix-value>
        }

        </record>