The JAS-mine platform‎ > ‎Documentation‎ > ‎Tutorials‎ > ‎

The structure of a JAS-mine project

In the JAS-mine architecture, agents are organized and managed by components called managers. As already mentioned, there are three types of managers in this architecture: Model, Collector and Observer. Models serve to build artificial agents and objects, and to plan the time structure of events. Collectors are managers that build data structures and routines to calculate (aggregate) statistics dynamically, and that build the objects used for data persistence.  The definition of a Collector’s schedule specifies the frequency of statistics updating and agent sampling, and consequent storage in the output database. Observers are managers that serve to build graphical widget objects that indicate the state of the simulation in real time, and define the frequency with which to update these objects.

JAS-mine allows multiple Models (and multiple Collectors and Observers) to run simultaneously, since they share the same scheduler.  This allows for the creation of complex structures where agents of different Models can interact. Each Model is implemented in a separate Java class that creates the objects and plans the schedule of events for that Model. Model classes require the implementation of the SimulationManager interface, which implies the specification of a buildObjects method to build objects and agents, and a buildSchedule method for planning the simulation events. Analogously, Collector classes  must implement the CollectorManager interface, and Observer classes must implement the ObserverManager interface.

When a new JAS-mine project is created using the JAS-mine plugin for Eclipse IDE, several packages are created:
  • data: a package containing the classes that describe the structure of coefficients, parameters and agent population tables contained in the database to be loaded by the ORM. When using Excel files to specify input data, no specific classes need to be included in this package.
  • model: a package containing the classes that specify the model structure; in particular, it contains the Model manager class(es) and the class(es) of agents that populate the simulation.
  • model.enums: a subpackage containing the definition of the enumerations used (if any). Enumerations specify a set of predefined values that a property can assume. These values might be categorical (strings, e.g. sex), quantitative (discrete numbers, e.g. age) or even objects with their set of characteristics and properties (e.g. a predefined set of banks to which a firm can be linked). The ORM detects that a value is an enumeration when the property is declared with the annotation @Enumerated (see below). Through enumerations the ORM automatically manages reading/writing operations in both text and numerical format.
  •  experiment: a package containing the classes that deal with running the simulation experiment(s); it contains, in particular, the Start class where the main method and the type of the experiment (interactive vs. batch mode, single run vs. multiple runs) are defined.  The package might also contain one or more Collector and/or Observer manager classes for online statistics collection and display, and a MultiRun class that manages repeated runs for parameter exploration.
  • algorithms: a package containing classes that implement algorithms for determining events and applying processes to the agents. These implementations, in a cooperative effort of users, are potential candidates to extend the set of standard functions included in the JAS-mine libraries.

In addition to sources (stored in 
the src folder), the project also contains two folders for data input-output. The input folder contains data and parameters in MS Excel or H2 embedded formats. The output folder contains the output of different simulation experiments and is initially empty. At the beginning of each run, JAS-mine creates a sub-folder that is labelled automatically with an appropriate time stamp, so as to uniquely identify the experiment (e.g. 20141218151116, for experiments initiated on the 18th December 2014, at 16 seconds after 3.11pm). The subfolder contains a copy of all the input files and an empty output database, with the same structure of the input database as defined by the annotations added to the model classes. Coherence between the input database (if any), the output database and the classes representing the agents in the simulation (known as entity classes) is guaranteed by the ORM.
    By default, JAS-mine executes the simulations in embedded mode: the databases are modified directly by the JDBC driver included in JAS-mine. The standard database uses a H2 database engine. Other databases supporting embedding can be used, such as Microsoft Access, Hypersonic SQL, Apache Derby, etc.

    Two additional folders are created, labelled target and lib, with technical content of no immediate interest to the modeller. The root folder also contains a pom (project object model) file, which contains information on the JAS-mine version used for the project. Apache Maven, an open source software project management and comprehension tool uses this information to manage all the project's build, reporting and documentation. In particular, by specifying in the pom file the desired release for each library used (including the JAS-mine libraries), Maven automatically downloads the relevant libraries from the appropriate repositories. This implies that each JAS-mine project has its own copy of all the libraries used, ensuring that the project is self-contained and that it keeps working exactly as intended even when new versions of the libraries are released (and even if backward compatibility is not respected). 

     Folder namecontains 
     inputdata and parameters
     output initially empty
     src all Java classes
     targetcompiled classes, JARs, etc. 
     libs    external libraries (if any)

    Table: the JAS-mine file structure