Getting started

0. Installing Java JDK

To use JAS-mine, the first thing you need is to install Java JDK. You can download the last version for your operating system from the Java website. Then, follow the installation instructions with default options.

1. Installing Eclipse

Even if you do not technically need Eclipse to write and run simulations in JAS-mine, we strongly suggest that you use it. Eclipse is a powerful environment for software development. It provides many tools and facilities for creating and managing projects, writing code, debugging and running programs. You will learn a lot by studying the tutorials available on the Eclipse website. However, you do not need to be an expert Eclipse user to create your own JAS-mine simulation.

To install Eclipse, go to the Eclipse website and download the Eclipse version that is correct for your system (JAS-mine has been tested on Eclipse versions Neon, Mars and Luna, but does not work on version Kepler). After download has completed, just unzip Eclipse anywhere on your computer. To start Eclipse, simply double click on the application icon. You will be asked a location for your workspace. Just select one default folder: you will be able to select different folders for your projects when you will create them.

 

Open Eclipse. The first thing you’ll see is the welcome screen:

 

From the welcome screen you can access the Eclipse tutorials, and other supporting material. Close it; you will be able to visualize it at any time by going to the Help/Welcome menu.

Eclipse now looks like this:

 

2. Installing the JAS-mine plugin for Eclipse

The integration of JAS-mine in Eclipse is achieved by a plugin. The JAS-mine plugin gives you a template for new JAS-mine projects. When you create a new JAS-mine project, the complete package structure, and the Model, Collector, Observer, Start, MultiRun and Agent classes are automatically created, with all the required properties and methods. This gives you a skeleton, which greatly simplifies model development and let you focus on the behavioral specification of the model, rather than on the technical details of the simulation. You can run the skeleton model, and the simulation will start. Empty input and output databases will be created, with the correct table structure. The simulation will run, but will do nothing. Your task is to make it interesting by specifying the appropriate agents’ behaviour.


See below for several ways to install the plugin within the Eclipse IDE.

2.1 Drag and Drop

The simplest way to install the JAS-mine plugin is to drag and drop the button below into a running Eclipse workspace:

Drag to your running Eclipse* workspace. *Requires Eclipse Marketplace Client

After a few seconds 'JAS-mine' or 'JAS-mine_Plugin' should appear in the list.  Ensure the box next to the JAS-mine option is ticked and click the 'Confirm' button on the bottom of the window. Accept the license agreement, and complete the installation.  As is common in many Eclipse plugins, you will be prompted with a warning that you are installing unsigned content, see the screenshot below.  Continue without fear by clicking on the 'OK' button.


Restart Eclipse when prompted, and you will be ready for creating your first JAS-mine project!  Eclipse stores projects in workspaces, so if you want to create your project in a folder different from the default workspace, you have first to create a new workspace when prompted on starting Eclipse.  (Another method is to go to the File/Switch Workspace menu, and then select a new Workspace.  Eclipse will close and re-open with the new workspace loaded).

2.2 Using the Eclipse Marketplace

From the Help tab within Eclipse IDE, select the 'Eclipse Marketplace' menu.  Search for JAS-mine, and you will find the 'JAS-mine Plugin for Eclipse IDE' plugin, as seen below:




Click the 'Install' button, and after a few seconds 'JAS-mine' or 'JAS-mine_Plugin' should appear in the list.  Ensure the box next to the JAS-mine option is ticked and click the 'Confirm' button on the bottom of the window. Accept the license agreement, and complete the installation.  As is common in many Eclipse plugins, you will be prompted with a warning that you are installing unsigned content.  Continue without fear by clicking on the 'OK' button.


Restart Eclipse when prompted, and you will be ready for creating your first JAS-mine project!  Eclipse stores projects in workspaces, so if you want to create your project in a folder different from the default workspace, you have first to create a new workspace when prompted on starting Eclipse.  (Another method is to go to the File/Switch Workspace menu, and then select a new Workspace.  Eclipse will close and re-open with the new workspace loaded).

2.3 Using the Install New Software menu

From the Help tab within Eclipse IDE, select the 'Install New Software' menu, and provide the JAS-mine plugin site: https://raw.githubusercontent.com/jasmineRepo/plugin/master/JASmine_UpdateSite/site.xml


After a few seconds, 'JAS-mine' or 'JAS-mine_Plugin' should appear in the list.  Tick the box next to the JAS-mine option and click the 'Next' button on the bottom of the window. Accept the license agreement, and complete the installation.  As is common in many Eclipse plugins, you will be prompted with a warning that you are installing unsigned content.  Continue without fear by clicking on the 'OK' button.


Restart Eclipse when prompted, and you will be ready for creating your first JAS-mine project!  Eclipse stores projects in workspaces, so if you want to create your project in a folder different from the default workspace, you have first to create a new workspace when prompted on starting Eclipse.  (Another method is to go to the File/Switch Workspace menu, and then select a new Workspace.  Eclipse will close and re-open with the new workspace loaded).

 

3. Creating a new JAS-mine project

Now, to create a new JAS-mine project within the Eclipse IDE, select File/New/Other from the menu. The following window will open:

 

From the list, select 'JAS-mine/New JAS-mine Project'.  The JAS-mine wizard will ask you to enter a project name, a model name, and a package name, and you have the choice of whether to use the default location or specify an alternative.  (Note, that a Java Model Exception will be thrown if you try to use 'package' for the package name - please choose a different name.)  Once you have entered these, you are done.

 

Eclipse has created a new JAS-mine project, with folders, packages and classes:


Eclipse has created the algorithms, data, experiment and model sub-packages.  Four classes have been put in the experiment sub-package: the Collector, the Observer, the Start and the MultiRun class (each class is identified with the model name as a prefix).  They deal with the execution of the artificial experiment. The model sub-package contains the classes that specify the structure of the model: the Model itself, and an Agent class.  Eclipse has also created a folder for the input data files, and a folder for the output database, while the target folder contains the persistence.xml file that specifies which RDBMS to use (h2 is the default).

Eclipse, however, warns you that there are a lot of errors (the red crosses). This is because you have to tell Eclipse where the JAS-mine libraries are. The plugin provides the chassis for a new model, but does not provide the engine, that is the JAS-mine-core and JAS-mine-gui .jars. So, you can proceed in two ways: i) The easy way is to use Maven, a software project management and comprehension tool that takes care of adding a copy of the JAS-mine libraries and other dependencies every time the project is built, taken directly from the JAS-mine GitHub repository,  ii) The more complicated way is to download the JAS-mine libraries manually, and tell Eclipse where they are.  We now explain in turn how these options work.


3.1 Installing the JAS-mine libraries using Maven

The easiest way to install the JAS-mine libraries is to use Maven, which now comes pre-installed in Eclipse IDE.  Maven allows you to specify all the dependencies for your project (these might include other libraries in addition to JAS-mine) in a POM (Project Object Model) xml file. When a new JAS-mine project is created in Eclipse, the POM file is automatically included. The POM file specifies the version of the JAS-mine .jars to use, and can be modified within Eclipse.

In order to get rid of the compilation errors, simply right-click on your project and select 'Maven/Update Project'.  You will see that a new project folder named 'Maven Dependencies' has been created.  Maven has updated the project dependencies (expand the Maven Dependencies list in the Package Explorer; the JAS-mine core library is named JAS-mine-core and the JAS-mine GUI library is named JAS-mine-gui).


More information on Maven is given in the 'Download' section.


3.2 Installing the JAS-mine library manually

An alternative to using Maven is to download the JAS-mine .jars from the JAS-mine Sourceforge website (choose the JAS-mine-core-with-dependencies and JAS-mine-gui-with-dependencies .jars), then copy these files to the 'libs' folder in the Eclipse project (create a 'libs' folder if there isn't one in the project).  Then select both .jar files and right click, select 'Build Path / Add To Build Path':

 


You can check the JAS-mine .jars are on the build path by right-clicking on the project and selecting 'Build Path / Configure Build Path'.   Check the new .jars are there in the Libraries tab.  Note that Eclipse should no longer show any Errors in your project related to missing JAS-mine classes.  You should see the following:



4. Running the simulation

To run the simulation (which in this example is void) right-click on the Start class and Run it as a 'Java Application' (the Start class has the name "<Model Name>Start.java", and can be found in the experiment package which has the name "<Package Name>.experiment"). The JAS-mine GUI console opens. You can inspect the databases by clicking on the 'Tools/Database explorer' menu. Only the INPUT database is present at this stage:


 


Select it and initialize it by pressing the 'Init input database' button. A new page will open in your browser with a GUI to explore the h2 database:


There is only one table, named AGENT, with the three keys ID, SIMULATION_RUN and SIMULATION_TIME, but the table is empty. To come back to JAS-mine, remember to disconnect from the database by clicking on the upper left button. If you do not do it and just close the browser page, you will have to close JAS-mine from the Task manager and start your simulation again, as the JAS-mine console cannot regain control. Now, run the simulation by pressing the Play button in the JAS-mine console, then open the Database explorer again. You will see that there is another database, labelled with a numeric string with year-month-day-hour-min-sec information. This is the output database for the current experiment:




Open it by pressing the Show database button. The output database has the same structure as the input database, but it contains two additional tables: JASMINE_EXPERIMENT, and JASMINE_EXPERIMENT_PARAMETER. You can query the database by writing SQL code in the appropriate window (some tips and examples are given in the space below the window). Tables can be exported in CSV format by typing the following SQL instruction (see the h2 tutorial):

CALL CSVWRITE('FILE_NAME.csv', 'SELECT * FROM TABLE_NAME');

The JASMINE_EXPERIMENT table contains information on the specific simulation run performed, whilst the JASMINE_EXPERIMENT_PARAM table contains information on the GUI parameters of the simulation (in this case, the 'endTime' parameter, which has a value of 20.0 in the default case).