Cette page décrit la création d'une nouvelle applet de simulation, pas à pas.
L'expérience montre qu'il est préférable de bien savoir ce que l'on veut créer avant de se lancer dans le code d'une simulation. Pour cette raison, la création d'une nouvelle simulation avec SimuLab commence par la création d'un fichier décrivant la simulation, sans aucune programmation.
Le fichier étant purement descriptif, il est créé en XML, suivant des règles de langage spécifiques à SimuLab. Le fichier peut contenir:
Les paramètres et les affichages sont obligatoires, puisqu'il serviront à SimuLab pour générer automatiquement l'interface utilisateur de l'applet. La documentation n'est pas obligatoire, mais c'est l'occasion idéale pour créer une documentation sous forme de page web, en accompagnement de l'applet.
Le fichier de documentation doit être créé au format XML avec les règles du langage XML de SimuLab. Comme les fichiers XML sont des fichiers texte, il serait possible de créer ce fichier avec un simple éditeur de texte. Mais il est beaucoup plus facile de faire cela avec un éditeur XML comme Jaxe, qui fournit une interface utilisateur conviviale et qui empêche de faire la moindre erreur par rapport aux règles du langage.
Si Jaxe n'est pas déjà installé, on commence donc en le téléchargeant à partir du site de Jaxe, et en suivant les instructions de ce site pour l'installation.
Il faut ensuite copier les fichiers du dossier config de SimuLab à l'intérieur du dossier config de Jaxe (attention à ne pas copier le dossier lui-même):
... et copier le fichier pluginsjaxe.jar du dossier plugin Jaxe dans le dossier plugins de Jaxe (ce plugin ajoute un éditeur d'équations TeX à Jaxe).
On peut ensuite créer un nouveau fichier XML en lançant Jaxe, en cliquant sur le bouton "Nouveau", et en choisissant APPLET_SIMULAB. On l'enregistrera pour cet exemple sous le nom "projectile_doc.xml"
On peut se référer au guide utilisateur de Jaxe pour apprendre à s'en servir.
Les éléments XML pour les paramètres de la simulation sont insérables dans le document à partir du menu "Applets". On peut aussi utiliser le panneau d'insertion des éléments, à gauche de la fenêtre de Jaxe, pour insérer les éléments (ce panneau n'affiche que les éléments qu'il est possible d'insérer à l'endroit du curseur)
Sous la racine (APPLET_SIMULAB), on insère donc l'élément "Liste des paramètres" (LISTEPARAMS). Les paramètres d'entrée doivent être insérés à l'intérieur de cet élément LISTEPARAMS.
Les attributs de chaque paramètre d'entrée sont les suivants:
Pour Projectile, on définit les attributs ainsi:
type nombre
label v0
titre vitesse initiale
unit m/s
acquisition choix
defaut 12
Après avoir créé l'élément PARAMETRE_ENTREE, il faut ajouter un petit texte de description pour le paramètre, qui sera utilisé par SimuLab comme aide en ligne de la simulation. On ajoute ce texte dans l'élément DESCRIPTION, à l'intérieur de l'élément PARAMETRE_ENTREE. Jaxe affiche l'élément PARAMETRE_ENTREE en orange au lieu de jaune tant que l'élément DESCRIPTION n'a pas été créé, parce-que cet élément est obligatoire.
<DESCRIPTION>
Vitesse initiale du projectile
</DESCRIPTION>
Comme on a choisit la méthode d'acquisition "choix", il faut ajouter les valeurs possibles pour ce paramètre à l'intérieur de l'élément PARAMETRE_ENTREE, avec l'élément VALEURS:
<VALEURS>
<CHOIX valeur="8"/><CHOIX valeur="10"/><CHOIX valeur="12"/><CHOIX valeur="14"/>
</VALEURS>
On fait ensuite la même chose pour le deuxième paramètre, la direction du projectile:
type nombre
label direction
titre angle
unit degres
acquisition champ
defaut 70
Les paramètres de sortie sont les données calculées par l'algorithme de simulation. Les données de sortie dans le cas du projectile sont les coordonnées x et y du projectile, qui vont permettre l'affichage sous forme de graphe.
On ajoute les paramètres de sortie sous l'élément LISTEPARAMS, après le dernier paramètre d'entrée.
Les attributs possibles sont les suivants:
Pour Projectile, on ne définit pas le titre (le titre des axes sera donc juste le label):
<PARAMETRE_SORTIE label="x" type="nombre" unite="m"/>
<PARAMETRE_SORTIE label="y" type="nombre" unite="m"/>
Les options d'affichage définissent la façon dont les paramètres de sortie vont être utilisés pour afficher le résultat.
Les types d'affichage possibles dans SimuLab sont:
Commençons avec un affichage "plotlive". Les attributs de la classe Affichage, qui définit les options d'affichage pour un affichage donné, sont les suivants:
L'élément doit aussi contenir la liste des labels des paramètres de sortie utilisés pour les différents tracés de la sortie graphique, sous forme d'un élément LISTEREFPARAMS à l'intérieur de AFFICHAGE.
pour Projectile, on utilisera simplement:
<AFFICHAGE titre="mouvement du projectile y/x live" type="plotlive">
<LISTEREFPARAMS>
<REFPARAM nom="x"/>
<REFPARAM nom="y"/>
</LISTEREFPARAMS>
</AFFICHAGE>
On notera que l'on peut en fait ajouter plusieurs listes LISTEREFPARAMS. En effet, l'affichage plotlive permet d'afficher simultanément plusieurs courbes avec divers paramètres de sortie. Si l'on voulait afficher à la fois la courbe (x,y) et la courbe (y,x), on utiliserait deux éléments LISTEREFPARAMS:
<LISTEREFPARAMS>
<REFPARAM nom="x"/>
<REFPARAM nom="y"/>
</LISTEREFPARAMS>
<LISTEREFPARAMS>
<REFPARAM nom="y"/>
<REFPARAM nom="x"/>
</LISTEREFPARAMS>
Il est possible de définir des ensembles de valeurs des paramètres d'entrée, afin de présenter des cas intéressants pour la simulation. Cela se fait avec l'élément ENSEMBLE, mais ne sera pas utilisé dans cet exemple.
A la suite de la liste des paramètres, on peut ajouter une documentation pour la simulation. Comme ce n'est pas obligatoire, ce n'est pas décrit ici. Mais on obtient le fichier HTML avec la page web de la documentation en utilisant le menu "Fenêtre HTML" de Jaxe, qui crée un fichier HTML avec le même nom que le fichier XML, au même endroit (mais avec l'extension html).
Une fois la documentation terminée, il faut choisir un nom pour la classe Java de l'applet de simulation, par exemple ici Projectile. Le nom de la classe Java doit commencer par une majuscule.
Pour créer la classe, il suffit de créer un nouveau répertoire, disont Projectile, et de créer dedans un fichier texte appelé Projectile.java. Avec un éditeur de texte, on défini la classe en écrivant:
public class Projectile extends SimuApplet {
}
L'instruction "extends SimuApplet" signifie que la classe Projectile descend de la classe SimuApplet, et hérite de ses méthodes et de ses attributs. On verra plus loin comment les utiliser.
Pour utiliser le package simulab, il faut ajouter au début du fichier (avant public class...):
import simu.*;
A l'intérieur de la classe, il faut maintenant ajouter le constructeur, c'est à dire la méthode appelée quand la classe est créée. On va ajouter dans cette méthode la description des paramètres de la simulation.
public Projectile() {
}
Dans ce constructeur, on fait appel au fichier de documentation XML avec la méthode appletDoc:
public Projectile() {
appletDoc("projectile_doc.xml");
}
Il nous reste à définir le calcul proprement dit. Heureusement, ce n'est pas le plus dur dans cet exemple !
Comme nous avons choisi la méthode d'affichage plotlive, on va devoir définir deux méthodes: une pour initialiser le calcul, initCalculLive, et une pour calculer le nouveau point à chaque itération, calculLive. SimuLab va appeler initCalculLive au départ pour donner les valeurs des paramètres d'entrée, puis calculLive à chaque itération, pour afficher les points au fur et à mesure.
Voyons d'abord l'initialisation:
public void initCalculLive(ListeValeurs in) throws SimuException {
x = 0;
y = 0;
double v0 = in.lireDouble("v0");
double angle = in.lireDouble("direction");
vx = v0 * Math.cos(angle/180*Math.PI);
vy = v0 * Math.sin(angle/180*Math.PI);
}
En entrée de cette méthode, on passe une liste des valeurs des paramètres d'entrée. A partir de la description des paramètres d'entrée, SimuLab va se charger de demander des valeurs à l'utilisateur, et ce sont ces valeurs qui sont passées en paramètres ici, dans l'objet ListeValeurs in. Il doit donc contenir les valeurs de v0 et dir.
Avant de continuer, on peut ajouter quelques variables globales pour la classe Projectile, pour faciliter le calcul. Ajoutons la constante g, l'intervalle de temps entre deux itérations, les coordonnées du projectile x,y et la vitesse du projectile vx,vy. Ces définitions s'écrivent juste après public class Projectile...:
public class Projectile extends SimuApplet {
static final double g = 9.81;
double dt = 0.05;
double x,y;
double vx,vy;
...
On peut maintenant revenir à initCalculLive, et initialiser la position du projectile, avec x=0 et y=0. Ensuite, on lit les valeurs de v0 et de l'angle à partir du tableau in.
On peut ensuite calculer vx et vy comme indiqué dans initCalculLive.
... Reste encore à passer d'un point à l'autre. Cela se fait en implémentant la méthode calculLive, qui renvoit une liste de valeurs: les valeurs des paramètres de sortie, x et y.
public ListeValeurs calculLive() throws SimuException {
if (y < 0)
return null; // fin du calcul
ListeValeurs out = new ListeValeurs();
x += vx * dt;
y += vy * dt;
vy -= g * dt;
out.ajouterDouble("x", x);
out.ajouterDouble("y", y);
return out;
}
On indique à SimuLab que le calcul est terminé en renvoyant null au lieu de la liste des valeurs. Dans Projectile, on s'arrête quand le projectile tombe au sol, c'est à dire y < 0.
Si on laisse les choses comme cela, on peut constater un léger problème pratique sur n'importe quelle machine moderne: le calcul se fait trop vite, et on n'a pas le temps de voir s'afficher le graphe au fur et à mesure ! Pour éviter ce problème, et en fonction de la complexité de l'algorithme, on peut ajouter une pause au niveau de calculLive, pour que le programme nous laisse le temps de voir quelque-chose. On utilise pour cela la méthode dormir(n), qui bloque le programme pendant n millisecondes.
dormir(Math.round(dt*1000)); // pour bloquer le programme pendant dt secondes
La compilation se fait très simplement, mais en n'oubliant pas d'ajouter la librairie SimuLab dans le chemin vers les classes Java.
sous UNIX:
cd Projectile setenv CLASSPATH .:/chemin/vers/SimuLab.jar javac -encoding ISO-8859-1 Projectile.java
(remplacer "ISO-8859-1" par l'encodage de caractères utilisé dans le fichier Java)
On peut aussi utiliser ant pour une compilation plus complexe, et pour s'assurer que le programme compile facilement sous diverses plate-formes. SimuLab lui-même est compilé avec ant. Les fichiers ant_light_config.xml et ant_light.xsd permettent d'éditer des fichiers ant simples avec Jaxe (il suffit de placer ces 2 fichiers dans le dossier config de Jaxe).
Pour finir, il ne reste plus qu'à écrire un fichier HTML qui contient un appel vers l'applet, et les dimensions de l'applet. On peut aussi ajouter quelques instructions ou informations dans ce fichier HTML. La commande à utiliser pour lancer l'applet Projectile est la suivante:
<applet archive="SimuLab.jar" code="Projectile" width="600" height="400">
Pour s'assurer que les utilisateurs qui n'ont pas un navigateur avec Java (peu probable), ou qui ont désactivé Java, voient un message d'erreur, on peut écrire à la place:
<applet archive="SimuLab.jar" code="Projectile" width="600" height="400"> Java n'est pas activé dans votre navigateur. </applet>
Le fichier XML de documentation doit être placé au même endroit que le fichier HTML.
Et voilà ! Nous avons une nouvelle applet de simulation prête à l'emploi sur le web !
L'installation de SimuLab donne d'autres exemples, avec les fichiers associés.