Tutorial BCVTB PluginV2 - muse

Tutorial plug’in BCVTB
1
Sommaire :
I.
II.
Introduction : .................................................................................................................. 3
Ajout d’un nouveau acteur dans BCVTB ...................................................................... 3
1. L’environnement BCVTB .......................................................................................... 3
2. Description d’un acteur de Ptolemy II ....................................................................... 3
III.
Le plug-in MUSE dans BCVTB ................................................................................ 4
1. Principe et réalisation ................................................................................................. 4
2. Composition ............................................................................................................... 5
3. Configuration et pré utilisation .................................................................................. 5
4. Utilisation ................................................................................................................... 6
5. Modification du plug-in ............................................................................................. 8
6. Limitation du plug’in : ............................................................................................... 8
IV.
Simulation d’un exemple : ......................................................................................... 8
2
I. Introduction :
L’objectif de ce plug-in est de pouvoir, de manière automatique et générique, utiliser un
composant MUSE dans l’environnement BCVTB. Il s’agit de développer un nouvel acteur
Ptolemy II (la base du BCVTB) permettant d’importer et de simuler un MUSE dans cet
environnement.
Le développement de ce plug-in a était inspiré de l’import réalisé pour les composants FMU.
L’import de MUSE est plus simple étant donné l’utilisation du même langage de
programmation Java. Donc il n’est pas besoin d’utilisation de JNA (Java Native Acess) pour
assurer le bridge entre le Java et le C comme réalisé pour les FMUs.
Le principe de ce plug-in et son utilisation seront détaillés dans ce document à travers un
exemple simple de Muse « SimpleRoomMuse » qui représente un modèle simple d’une
chambre en reproduisant les équations du modèle « Room » dans l’exemple « PtolemyRoom » du BCVTB
II. Ajout d’un nouveau acteur dans BCVTB
1. L’environnement BCVTB
BCVTB « Buildings Virtual Control Test Bed » (https://simulationresearch.lbl.gov/bcvtb) est
un environnement de co-simulation des outils de simulation énergétique de bâtiment. Il est
basé sur l’environnement Ptolemy II et utilise certaines de ces fonctionnalités.
Réaliser un plug-in dans cet environnement consiste à ajouter un nouvel acteur comme décrit
dans
la
documentation
du
BCVTB
(http://simulationresearch.lbl.gov/bcvtb/releases/1.0.0/doc/manual/ch06s09.xhtml)
et
de
Ptolemy II.
2. Description d’un acteur de Ptolemy II
Comme Ptolemy II est développé en Java, Tout acteur est une classe Java décrite selon une
manière bien défini.
L’acteur est également défini par un fichier XML structuré selon un schéma défini également
et qui appelé MOML file. Ce fichier suit la structure suivante :
L’acteur est composé de
-
Ports : qui sont publics de type TypedIOPort et qui représentent les inputs et les
outputs du modèle :
L’orientation du port est définie lors de sa création par les arguments 3 (actor is an input)
et 4 (actor is an output)
Ptolemy II est basé sur la notion de « token », qui assurent l’échange d’information entre
3
le modèle et l’environnement. Cet échange est assuré part lecture/écriture depuis et vers
un canal de communication.
-
Paramètres : qui sdoivent être déclarés comme suit :
et crées et affecté de cette manière :
-
Un constructeur : pour créer et configurer les ports et les paramètres.
Cette étape peut se faire de manière générique tel est le besoin pour l’utilisation de
MUSE. En effet, cette partie de la classe change selon le MUSE ce qui nécessite une
définition dynamique en fonction de l’introspection du MUSE. Ceci est possible, en
modifiant dynamiquement le MOML file de l’acteur en focntion du MUSE et grâce à la
fonction « MOMLChangeRequest » (modifier la partie model définition):
Afin d’assurer sa simulation efficace par le cœur de Ptolemy, l’acteur doit implémenter
certaines méthodes selon l’action désirée dont principalement ces méthodes qui vont être
implémenté pour l’exploitation du MUSE :
-
-
Preinitialize : préparation de la simulation comme charger le composant MUSE
Initialize : Initialiser la simulation (affecter les valeurs initiales par exemple)
Fire : c’est la méthode principale d’exécution et qui,appelé, à chaque étape de la
simulation assure principalement la récupération des inputs et lla production des
outputs.
Warrup : appelée à la fin de la simulation principalement pour l’affichage des résultats
finaux.
III. Le plug-in MUSE dans BCVTB
1. Principe et réalisation
Le plug-in du MUSE dans BCVTB consiste ainsi à créer un nouveau acteur ayant les mêmes
ports et paramètres et qui permettra l’échange d’information entre le MUSE et PtolemyII pour
permettre sa simulation.
Pour le faire, la première étape consiste à créer un acteur atomique générique
MUSE.actor.MUSEImport. Il s’agit ensuite d’implémenter les méthodes d’action de l’acteur
ptolemy II avec les interfaces correspondantes du MUSE :
- Preinitialize : MuseJarLoader, getMuse et loadFacets.
- Initialize : var.setValue pour l’affectation des paramètres et initialize pour
l’initialisation de la simulation.
- Fire : var.setValue pour l’affectation des inputs, doStep pour l’éxcétion du step,
var.getValue pour la récupération des outputs
4
-
Warrup : terminate pour finir la simulation.
Cette classe définit également un paramètre commun à chaque MUSE et qui est le MUSEFile.
Ce paramètre qui indique le MUSE path sera définit par l’utilisateur lors de l’instanciation de
l’acteur (ENTITY) à travers une fenêtre de communication.
Ceci est réalisé dans le constructeur dans le but de réaliser une introspection préalable du
MUSE avant de spécifier sa représentation graphique qui est unique au MUSE. Suite à cette
introspection, le fichier MOML du MUSE sera définit afin de rendre spécifique au MUSE,
l’acteur générique.
2. Composition
Les éléments développés et nécessaires à l’utilisation du plug-in sont rassemblés dans un
dossier appelé MUSE.
Ce kit est composé de :
- La classe Java de l’acteur MUSE: MUSEImport.java dans MUSE\src\MUSE\actor
- Le fichier MOML de description de l’entité : MUSEImport.xml
- Les librairies du MUSE : nécessaire pour sont exécution dans MUSE\src\util
- Le fichier du build nécessaire à la compilation : build.xml
Ce dossier doit être placé dans le répertoire lib/ ptII du BCVTB.
3. Configuration et pré utilisation
Après installation du BCVTB en suivant les instructions sur le site
(http://simulationresearch.lbl.gov/bcvtb/releases/1.0.0/doc/manual/tit-InstallationUser.xhtml)
et
modification
des
variables
d’environnements
système
(http://simulationresearch.lbl.gov/bcvtb/releases/1.0.0/doc/manual/settingEnvironmentVariabl
es.xhtml), il faut dans un premier temps copier le kit du plug-in MUSE dans BCVTB/lib/PTII.
Il faut ensuite rajouter les librairies nécessaires à l’exécution du MUSE, génériques et
spécifiques au classpath. Elles doivent être ajoutées dans la variable d’environnement
BCVTB_Home dans le fichier systemVariables-windows.properties à la racine du dossier
BCVTB.
Librairies génériques commune à tous les composant MUSE et qui doivent être
obligatoirement rajoutés:
%PTII%\MUSE\src\util\cades.facet.api-3.0.5-SNAPSHOT.jar;
%PTII%\MUSE\src\util\cades.facet.cosimulation.api-3.0.5-SNAPSHOT.jar;
%PTII%\MUSE\src\util\cades.facet.cosimulation.impl-3.0.5-SNAPSHOT.jar;
%PTII%\MUSE\src\util\cades.facet.impl-3.0.5-SNAPSHOT.jar;
%PTII%\MUSE\src\util\cades.muse.api-3.0.5-SNAPSHOT.jar;
%PTII%\MUSE\src\util\cades.muse.impl-3.0.5-SNAPSHOT.jar;
%PTII%\MUSE\src\util\org.eclipse.emf.common_2.8.0.v20120911-0500.jar;
5
%PTII%\MUSE\src\util\org.eclipse.emf.ecore.xmi_2.8.0.v20120911-0500.jar;
%PTII%\MUSE\src\util\org.eclipse.emf.ecore_2.8.1.v20120911-0500.jar;
%PTII%\MUSE\src\util\org.eclipse.osgi_3.8.1.v20120830-144521.jar;
Exemple de librairies spécifiques au composant du logiciel de l’exemple étudié :
SimpleRoomMuseCosim.jar (jar intermédiaire)
4. Utilisation
Pour importer un MUSE dans BCVTB, suivre les étapes suivantes :
– Lancer BCVTB et un nouveau éditeur graphique
– Cliquez sur “Instantiate Entity” dans “Graph”
–
Une fenêtre apparaîtra et où il faut préciser le nom de la calsse d’import du
MUSE « MUSE.actor.MUSEImport ».
–
A l’issue de cette instanciation, il faut préciser le nom du MUSE à importer
6
–
Ainsi le composant MUSE apparaîtra dans l’éditeur avec ces ports de
connexion. On cliquant dessus, on a accès à ces paramètres qu’on peut
modifier leurs valeurs.
–
Il suffit ensuite de connecter les composants à d’autres éléments de la
bibliothèque et lance la simulation
7
5. Modification du plug-in
Pour modifier/améliorer le plu-in réalisé, il suffit de :
- Supprimer le MUSEImport.class dans MUSE\actor
- Modifier la classe java MUSEImport.
- Compiler la nouvelle classe en exécutant la commande « ant all » dans une fenêtre de
commande lancé à la racine du dossier MUSE.
6. Limitation du plug’in :
Etant donné que l’introspection du MUSE et la modification du MOML file en conséquence
sont faite dans le constructeur de MUSEImport.java, ces actions sont répétées à chaque
instanciation de l’acteur. Ceci cause des problèmes lors de la réouverture d’un fichier utilisant
cet acteur : multiple instanciation multiplications des ports et des paramètres.
Ce problème est résolu dans l’import de FMU par le rajout d’une méthode spécifique en
dehors du constructeur permettant d’assurer ces opérations. Ceci nécessite la modification du
cœur de Ptolemy II pour pouvoir traiter cette méthode.
Remarque : L’acteur MUSE peut être rajouté dans les éléments graphiques de la bibliothèque
du PTII en le rajoutant dans le BCVTB configuration file bcvtbLibrary.xml dans
BCVTB\lib\ptII\ptolemy\configs\bcvtb:
Le problème de cette technique est également la double instantiation lors du drag and drop de
l’acteur MUSE.
IV. Simulation d’un exemple :
Après avoir suivre les étapes d’utilisation du plug-in décrite ci-dessous, le muse correspond à
la chambre est connecté aux mêmes sources que la chambre développée dans Ptolemy et sont
toutes les deux simulées dans les mêmes conditions pour obtenir des résultats simulaires
(figure du haut : chambre dans Ptolemy et figure du bas : chambre dans MUSE):
8
9