====== Simple API for JADE-based Simulations (SAJaS) ====== Multi-agent systems (MAS) are widely acknowledged as an appropriate modelling paradigm for distributed and decentralized systems, where a (potentially large) number of agents interact in non-trivial ways. Such interactions are often modelled defining high-level interaction protocols. Open MAS typically benefit from a number of infrastructural components that enable agents to discover their peers at run-time. \\ On the other hand, multi-agent-based simulations (MABS) focus on applying MAS to model complex social systems, typically involving a large agent population. \\ Several MAS development frameworks exist, but they are often not appropriate for MABS; and several MABS frameworks exist, albeit sharing little with the former. While open agent-based applications benefit from adopting development and interaction standards, such as those proposed by FIPA, MABS frameworks typically do not support them. The Simple API for JADE-based Simulations (**SAJaS**) is a proposal to bridge the gap between MAS simulation and development. SAJaS enhances MABS frameworks with JADE-based features. While empowering MABS modellers with modelling concepts offered by JADE, SAJaS also promotes a quicker development of simulation models for JADE programmers. In fact, the same implementation can, with minor changes, be used as a large scale simulation or as a distributed JADE system. \\ SAJaS provides, for certain kinds of applications, increased simulation performance, as compared to JADE. A MAS Simulation to Development (**[[MASSim2Dev|MASSim2Dev]]**) tool is SAJaS companion, and allows automatic conversion of a SAJaS-based simulation into a JADE MAS, and vice-versa. ---- ===== Software download ===== {{ :lgplv3-88x31.png?nolink&100|}} SAJaS is made available under LGPL v3. ==== SAJaS ==== In order to use SAJaS, you need the SAJaS library. Additionally, you will also need JADE (at least the //jade.jar// library) and one of Repast 3 or Repast Simphony. For Repast 3, it is enough to include its jar files in your project's build path. Repast Simphony typically comes with its own Eclipse integration, thus you can simply build your Repast Simphony Project in there and add the JADE and SAJaS libraries to the project's build path. JADE, Repast 3 and Repast Simphony are available in their respective websites. SAJaS is available at SourceForge: [[http://sajas.sourceforge.net/|SAJaS v0.92b, 2016-Mar-11]] \\ Includes the SAJaS library, source code and API documentation === Version dependencies === The current version of SAJaS (v0.9b2) is integrated and has been tested with [[http://jade.tilab.com/|JADE]] 4.3.3. SAJaS comes with API interfaces to [[http://repast.sourceforge.net/repast_3/index.html|Repast 3]] and [[http://repast.sourceforge.net/|Repast Simphony]] 2.3.1. ==== MASSim2Dev ==== The same JADE-based implementation can be used to run the MAS in JADE or its equivalent simulation in SAJaS. Minor changes are required, related with [[JADE_SAJaS_dict|redirecting class imports]] from JADE to SAJaS or vice-versa. The [[MASSim2Dev|MASSim2Dev]] tool performs the needed changes automatically. An additional change to take into account is that although the import of the ''jade.core.AID'' class should not, in general, be redirected to ''sajas.core.AID'', any direct instantiation of ''AID'' should be made in the SAJaS' version of this class (which extends JADE's one). Example: import sajas.core.Agent; import jade.core.AID; ... ACLMessage m = new ACLMessage(ACLMessage.REQUEST); m.addReceiver(new sajas.core.AID(name, false); ... ---- ===== How to ===== Developers familiar with JADE should have no problem on making use of SAJaS. In order to run a JADE-based simulation using SAJaS, a very limited amount of knowledge of Repast is needed. The benchmark scenario shown below should enable any developer to start using SAJaS. Of course that in order to take full advantage of the simulation tools provided by Repast a deeper knowledge of this framework is required. As for Repast users, SAJaS makes it possible to develop your multi-agent based simulation using the rich set of MAS facilities featured in JADE. In order to take advantage of such facilities, some knowledge of JADE programming is required. ==== Benchmark scenario ==== A benchmark scenario provides a comparison between running the same MAS in JADE, SAJaS+Repast3 and SAJaS+RepastS. The scenario is described in the paper "SAJaS: Enabling JADE-based Simulations" (see the [[#publications|publications section]]). A quick snapshot of performance comparison included in that paper is displayed here for convenience. In the figure, //n// is a parameter that determines the number of agents in the system. {{ :scenario-time-comparison.png?nolink&300|}} Below you can download the source code for a similar scenario, which is provided for the three frameworks. Note that the actual JADE-based source code is essentially the same, apart from the classes that are being imported (either JADE's or their SAJaS equivalent). The source code for SAJaS+Repast3 is provided in two versions: the second one exploits Repast3 visualization tools, both in terms of agent interaction and data collection. * {{:jade_test.zip|source code in JADE}} * {{:sajas_repast3_test.zip|source code in SAJaS+Repast3}} * {{:sajas_repast3_vis_test.zip|source code in SAJaS+Repast3 extended with visualization features}} * {{:sajas_repasts_test.zip|source code in SAJaS+RepastS}} * {{:sajas_repasts_vis_test.zip|source code in SAJaS+RepastS extended with visualization features (full Eclipse project)}} The classes that are used to run the different MAS/simulation infrastructures are ''JadeServiceConsumerProviderLauncher.java'', ''Repast3ServiceConsumerProviderLauncher.java'' and ''RepastSServiceConsumerProviderLauncher.java'', respectively. ==== Extending Repast Launchers ==== SAJaS includes two base classes for launching Repast's simulation infrastructure and run a JADE-based MAS on it: ''Repast3Launcher'' and ''RepastSLauncher'', for Repast 3 and Repast Simphony, respectively. === Repast 3 === In case of Repast 3, you need to extend ''Repast3Launcher'' and implement the following methods: * ''public String[] getInitParam()'' -- Repast 3 specific, inherited via Repast3Launcher's superclass SimModelImpl * ''public String getName()'' -- Repast 3 specific, inherited via Repast3Launcher's superclass SimModelImpl; used by SAJaS as an ID for the JADE platform * ''protected void launchJADE()'' -- SAJaS specific, used to launch the JADE platform (with SAJaS own classes) If you want to exploit further Repast3-specific tools, you can do as follows. For adding property descriptors (which are used for changing the way custom parameters are shown in the GUI), you must extend the ''setup'' method. When doing so, it is crucial that you start by calling ''super.setup()''. Your method should look as follows: @Override public void setup() { super.setup(); // crucial! // property descriptors // ... } For using data collection/visualization and agent spaces/displays, which typically involve making use of the scheduler, you must extend the ''begin'' method. When doing so, it is crucial that you start by calling ''super.begin()''. Your method should look as follows: @Override public void begin() { super.begin(); // crucial! // display surfaces, spaces, displays, plots, ... // ... } An example of this use is included in the source code for the [[sajas#benchmark_scenario|benchmark scenario]] above. === Repast Simphony === In case of Repast Simphony, you need to extend ''RepastSLauncher'' and implement the following methods: * ''public String getName()'' -- SAJaS specific, used as an ID for the JADE platform * ''protected void launchJADE()'' -- SAJaS specific, used to launch the JADE platform (with SAJaS own classes) If you want to exploit further Repast Simphony-specific tools, you can extend the ''build'' method. When doing so, it is crucial that you call ''super.build()''. Your method should look as follows: @Override public Context build(Context context) { // ... ... super.build(context); // crucial! // ... } ==== Current limitations ==== SAJaS takes a near-full advantage of JADE's features. However, beware of the following issues: * //Handling time//: The current version of SAJaS includes support for timer-based functionality as available in JADE agents, which supports features such as ''TickerBehaviour''s, ''WakerBehaviour''s and the handling of the optional //reply-by// parameter in ACL messages that are used in specific FIPA interaction protocols. However, the usage of these features in SAJaS should be carefully considered and is not encouraged. In fact, given the simulation bias of SAJaS, using milliseconds for specifying timers may have a significant impact on simulation performance. Translating timestamps to simulation ticks is not straightforward, as it depends on the scenario at hands. * //Blocking approaches//: JADE includes a few blocking approaches for agent interaction, namely based on the ''blockingReceive'' and ''doFipaRequestClient'' methods in the ''Agent'' class. These methods block agent execution until a matching message is received or a complete protocol is concluded. Given the single-threaded approach of SAJaS, or more precisely of the simulation frameworks (such as Repast) it may be aligned with, blocking approaches do not work. \\ Another typical usage of blocking approaches in JADE concerns (de)registering and searching the DF (JADE's yellow page service), for which a number of blocking methods are available in the ''DFService'' class. Given their quite common usage, these methods are still available in SAJaS, where they have been reimplemented so that they do not block, while achieving the desired functionality. * //ServiceHelper features//: JADE features that rely on service helpers, such as topic-based communication, are not currently supported by SAJaS, due to their added complexity. * //AMS/DF services//: Although the most typical usages of the DF service (register/deregister/search) are covered in SAJaS, some are not, including modifying a DF registration and searching the AMS (which is seldom useful). * //Mobility between containers//: Mobility-related methods are not supported yet, because SAJaS simplifies the usage of containers. ---- ===== Publications ===== Henrique Lopes Cardoso (2015). “[[http://link.springer.com/chapter/10.1007%2F978-3-319-27543-7_8|SAJaS: Enabling JADE-Based Simulations]]”, Transactions on Computational Collective Intelligence XX, N.T. Nguyen et al. (Eds.), LNCS 9420, pp. 158-178, Springer. DOI: 10.1007/978-3-319-27543-7_8. João P. C. Lopes, Henrique Lopes Cardoso (2015). “From Simulation to Development in MAS: A JADE-based Approach”, in //Proceedings of the 7th International Conference on Agents and Artificial Intelligence (ICAART 2015)//, Vol. 1, pp. 75-86, ISBN: 978-989-758-073-4, Lisbon, Portugal, 10-12 January 2015. João Pedro Camacho Lopes (2014). //From simulation to development in MAS: A JADE-based Approach//, MSc Thesis, MIEIC (FEUP), LIACC, July 2014. ---- ===== Authorship ===== This page has been created and is maintained by [[start|Henrique Lopes Cardoso]]. Any feedback or questions are highly appreciated. --- //[[hlc@fe.up.pt|Henrique Lopes Cardoso]] 2016/10/21 16:32//