Hand over
This is some documentation written by CDW with the purpose of providing some insight into the design of the CARMA plug-in tool. It also has some discussion of the points in the architecture that provide access to either the underlying CARMA project, or the Eclipse plug-in UI thread.
The current state of the tool (02.09.15) provides the modeller with an Editor in which they can design a model, a Simulator for running models and collecting data, and some UI tools (Wizards and Views) for creating simulations and viewing results.
The work flow is as follows
- The modeller creates a model in the Editor (ASCII), this is validated and type checked as the modeller writes
- The model is saved as a .carma file
- The model is auto-generated into a .java file
- The .java file uses the CarmaModel Interface. This .java file is class-loaded and this is associated with an ExperimentJob, an ExperimentJob contains everything needed to run a simluation (described later)
- The ExperimentJob provides access to the results from the measures
- The CARMA editor, for the design of CARMA models in the CARMA language, creation of .carma files and their auto-generated .java models
- The CARMA Laboratory Wizard, where ExperimentJobs are created
- The CARMA Laboratory View, where ExperimentJobs are stored (So we don't have to keep using the Wizard)
- The ExperimentJob class, this class extends Job (and can therefore run in its own thread), scheduling an ExperimentJob runs a simulation
- CARMA Results View - this contains a multi-table object that is updated by the completion of a scheduled ExperimentJob
- Now we have access to the measures from the UI thread, we can provide better statistical output.
The CARMA plugin tool is made out of these packages
- xText
- MS (Simulator)
- Eclipse UI
- Stats Packaging (Nebula Visualization Widgets - Eclipse as an example)
The editor is provided by the xText package. The xText package was mostly developed in Italy, but with some influence from Edinburgh, this will be managed in Italy in the future.
The CARMA Laboratory Wizard uses tools from the xText package to access the underlying CARMA resources (described later). The Laboratory View and Results View are standard View classes. The Eclipse UI packages are 'normal' Eclipse plug-in extensions (developed here in Edinburgh).
The Simulator was exclusively developed by ML. However the ExperimentJob was created here in Edinburgh. The ExperimentJob wraps a simulator so that it can be called by UI methods.
The Editor, Wizards and Views are managed by the Eclipse UI thread. A Job thread is scheduled in eu.quanticol.carma.ui.wizards.SimulationWizard using this method:
@Override
public boolean performFinish() {
experiment = new ExperimentJob(this.deadlineAndIterations.getDeadline(),
this.deadlineAndIterations.getSamplings(),
this.deadlineAndIterations.getIterations(),
this.modelAndSystemPage.getSystem(),
this.measuresPage.getMeasures(),
this.modelAndSystemPage.getModel(),
this.modelAndSystemPage.getModelName());
updateView();
experiment.setUser(true);
experiment.schedule();
return true;
}An eu.quanticol.carma.ui.laboratory.ExperimentJob updates the eu.quanticol.carma.ui.views.ExperimentsResultsView using this method. NOTE: The method is asynchronous.
public void updateView(){
ExperimentJob job = this;
Display.getDefault().asyncExec(new Runnable()
{
public void run() {
try {
PlatformUI.getWorkbench().getActiveWorkbenchWindow().getActivePage().showView(ExperimentResultsView.ID);
ExperimentResultsView.update(job);
} catch (PartInitException e) {
e.printStackTrace();
}
}
});
}FYI: I had to use two Composites in the View in order to provide a method of "Refreshing" the View when a new ExperimentJob has completed. Below is the method called in the Experiment Results View. This might be a useful strategy when building your own View.
public static void update(boolean flag){
if(flag)
container.dispose();
GridLayout containerLayout = new GridLayout(2, false);
container = new Composite(ExperimentResultsView.parent, SWT.NONE);
container.setLayout(containerLayout);
results = new ArrayList<ResultViewerWidget>();
if(ExperimentResultsView.measures != null){
for(int i = 0; i < measures.length; i++){
results.add(new ResultViewerWidget(container,
((StatisticSampling<CarmaSystem>) experimentJob.getCollection().get(i)),
experimentJob.getSamples()));
}
}
//refresh with new data
container.layout();
//need to refresh the parent too
parent.layout();
}
- The modeller creates a CARMA model in the editor. This is auto-generated into a CARMAModel.
- The modeller uses the CARMA Laboratory Wizard to create an ExperimentJob
- The ExperimentJob is stored by the Laboratory View
- The ExperimentJob is scheduled by the Wizard, and runs in its own thread
- The ExperimentJob completes, and asynchronously updates the CARMA Results View
- The ExperimentJob can be queried to gain access to the SummaryStatistics.
CARMA uses the xText framework. The writing of CARMA models in the CARMA language, the validation, type checking and code generation is supported by the xtext packages. These packages will in the future be managed in Italy.
xText provides
- an editor (.carma)
- the validator, and type checking
- code generator (.java)
- outline View
- access to models who have CarmaModel as an interface
This package also provides the utility for class loading: eu.quanticol.carma.core.ui.CarmaUiUtil.xtend
A demonstration of this class being used is found in eu.quanticol.carma.ui.wizards.SimulationWizard
CarmaUiUtil util = new CarmaUiUtil();
//..
HashMap<IResource,CarmaModel> models;
//..
this.models = util.getActiveModels();Once the models are loaded, we can call the methods for accessing the Systems and Measures. Each model uses CarmaModel as an interface, therefore the methods can be found in eu.quanticol.carma.simulator.CarmaModel
The simulator was developed by ML. It requires:
- A deadline (the simulation time)
- Number of iterations (number of times we run a simulation)
- Samplings (how many times the simulation is measured by measures)
- Measures (what to measure)
- A model that uses CarmaModel as an interface
The simulator takes advantage of the apache math3 package. The measures are written to SummaryStatistics
The ExperimentResultsView is a good example of the data from the measures being used (described later).
An ExperimentJob is essentially a Runnable. ExperimentJob is a subclass of Job, and is the normal way to start a process in a separate thread from the Eclipse UI thread (because you don't want long tasks running in the UI thread). The simulator is wrapped inside an ExperimentJob, so that a simulation is then run inside its own thread. The results can also be queried from the ExperimentJob
The ExperimentJob also stores a copy of the CarmaModel, and the input from the Laboratory Wizard.
The ExperimentJob was developed for use in the User Interface, and therefore was developed in Edinburgh.
The Experiment Wizard (or eu.quanticol.carma.ui.wizards.SimulationWizard) can create ExperimentJobs. This wizard picks up the model from any open CARMA editor. The Wizard has three nested WizardPages
- SelectModelAndSystemPage for Model and System selection (from the class loaded CarmaModel)
- SelectMeasuresPage for Measure selection
- SetDeadlineAndIterations for deadline, sampling and iteration definition
Upon pressing finish, the ExperimentJob is scheduled.
The LaboratoryView is for the storage of ExperimentJobs. At the time of this writing it is still in development.
All ExperimentJobs make a call to the singular Experiments Result View. They pass themselves as the argument. There are further classes for managing the ExperimentJob and converting the data into something that can be represented as a TableViewer.
Looking at how the ExperimentJob is passed to the Experiment Results View, and then processed, you might get some sense about how to extract the data from the measures. It is suggested that you try to use Nebula Visualization Widgets - Eclipse but this is only a suggestion.
Once you have access to the project via Git, you will find this underlying folder configuration:
- RESOURCES - resources for web pages, images for the wiki
- SIMULATION -
- eu.quanticol.carma.simulator : java classes required to simulate CARMA
- eu.quanticol.ms : the simulator and statistics packages
- TESTS - example .carma models for testing
- UI - eu.quanticol.carma.ui : SimulationWizard, ExperimentsResultView, SimulationLaboratoryView, SaveAsCSVWizard
- UPDATESITE - eu.quanticol.carma.updatesite : See: how to make an update-site
- XTEXT -
- eu.quanticol.carma.core : grammar, validation, type checking (language)
- eu.quanticol.carma.core.sdk : the feature we use to create the entire project
- eu.quanticol.carma.core.tests : validation and code generation tests
- eu.quanticol.carma.core.ui : Outline, Editor, "New CARMA Project...", template for initial Model
- update the version number of each plugin package that has been modified (plugin.xml - the below screenshot shows the plugin.xml for eu.quanticol.carma.core)
- update the version number of the eu.quanticol.carma.core.sdk feature (if you are adding a new plugin, then
include it in the "Plug-ins" page)
- update eu.quanticol.carama.updatesite site.xml: remove the old feature, add the new feature
- Press "Build all"
I'd suggest doing the build itself on a DICE machine. I have found that if it works on DICE it works everywhere else.
The generated update-site needs to be found at /afs/inf.ed.ac.uk/group/project/pepa/carma/web/updatesite.
- copy the updatesite into a folder with this form: "updatesite_date_version" eg :
cp -pr CARMA/UPDATESITE/eu.quanticol.carma.updatesite/* ~/updatesite_020915_1.2/ - move the updatesite to
/afs/inf.ed.ac.uk/group/project/pepa/carma/web/ - remove old softlink
rm updatesite(and old updatesite as well if you need space) - create softlink
ln -s updatesite_date_version updatesite(I use softlinks because it means the switch between versions can be faster, and if we had more space we could keep old versions on the site) - check update-site works from a fresh copy of Eclipse