This section contains information on how to download the latest release of JAS-mine software and other components necessary to work with it effectively: Java Development Kit (JDK) and Integrated Development Environment (IDE). We recommend Eclipse, but you can use your preferred application. Quick-start guide Follow the steps below to install all necessary software and run your first JAS-mine simulation as quickly as possible: Download Java OpenJDK from the AdoptOpenJDK website and install it with default settings.Download Eclipse from Eclipse website and follow the instructions to install it, selecting “Eclipse IDE for Java Developers” when asked which package to install. Open Eclipse, click Help -> Eclipse Marketplace. Type “JAS-mine” in the search box and install JAS-mine Plugin for Eclipse IDE 4. To create a new JAS-mine project, click File -> New -> Other -> JAS-mine -> New JAS-mine Project. Click Next, and specify the project name, model name, and package name. (You are free to choose any name you like, except for “package”). Your new project should appear in the Package Explorer on the left hand side. Right-click on its name and click Maven -> Update Project -> OK. To run the simulation, assuming your project is named test, click on the arrow next to its name, and open src/main/java -> test.experiment -> testStart.java by double-clicking it. From the top menu, select Run -> Run As -> Java Application. This should open the new window with the interface of the simulation. Click Build Simulation Model (the icon with a cogwheel and a green arrow) and then the bigger green arrow next to it. This should run your first JAS-mine simulation, showing Agents’ wealth and Average wealth over time on the screen. If you use or refer to JAS-mine in a publication, please remember to cite the JAS-mine reference paper. Below, we provide more details about each of the above steps. We also describe some alternative ways of obtaining JAS-mine and working with it that might be of interest to advanced users. 1. Download JAS-mine is free software and is released under the GNU Lesser General Public License. If you use or refer to JAS-mine in a publication, we ask that you cite the JAS-mine reference paper. 1.1 JAS-mine Plugin for Eclipse IDE The JAS-mine Eclipse plugin makes it very simple to create new JAS-mine projects from scratch. Read on to learn how to get started and use the JAS-mine Eclipse plugin. 1.2 Apache Maven We recommend the use of Apache Maven to manage the building of a JAS-mine project and its dependencies. With Maven, you don’t have to download JAS-mine and keep your projects aligned with the newest JAS-mine version you have in your system: Maven does everything for you! Each project you’ll create will point to a specific version of JAS-mine and a copy of the required libraries will be automatically downloaded to your computer. If you want to use a newer version of JAS-mine for one of your projects, you simply specify it in the Maven project’s POM.xml (Project Object Model) file. This way, you might have different projects using different versions of JAS-mine, but you’ll be always sure they work as expected.Maven now comes pre-installed with the latest version of Eclipse (since the Luna release), so there is now no longer a need to install it separately. To use Maven, see this tutorial. 1.3 Demo Models Demo models can be downloaded here. 1.4 JAS-mine .jars and source code If you wish to download the executable .jars without using Maven, you can download them from the Sourceforge website at https://sourceforge.net/projects/jas-mine/files/Libraries/. The source code for JAS-mine is available as repositories on GitHub. The core libraries can be found at https://github.com/jasmineRepo/JAS-mine-core and the GUI libraries are at https://github.com/jasmineRepo/JAS-mine-gui. 2. Installing Java JDK The first thing you need to use JAS-mine is to install a Java JDK. We recommend using open source licensed OpenJDK 13 (latest version) with a HotSpot JVM (Virtual Machine). Pre-built OpenJDK Binaries can be downloaded from the AdoptOpenJDK website and installed with default options using a simple installer. 3. 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 latest available 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, follow the instructions to install Eclipse, choosing “Eclipse IDE for Java Developers”. 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: 4. Installing the JAS-mine plugin for Eclipse See below for several ways to install the plugin within the Eclipse IDE. 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. 4.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: 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). 4.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). 4.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). 5. 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. 5.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. 5.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: 6. 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 “.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).