README file Author: Anthony Sulistio (September 2007) Directory Structure of GridSim Toolkit -------------------------------------- $GRIDSIM/ -- the current GridSim directory (top level) classes/ -- The GridSim class files doc/ -- GridSim and SimJava API Documentation eduni/ gridsim/ examples/ -- GridSim examples, see examples/README.txt for details jars/ -- jar archives source/ -- The GridSim Java source code gridsim/*.java gridsim/auction/*.java -- framework for the auction model gridsim/datagrid/*.java -- framework for the Data Grids model gridsim/filter/*.java -- filters incoming events gridsim/index/*.java -- framework for the Grid Info Service model gridsim/net/*.java -- framework for the network model gridsim/resFailure/*.java -- framework for the resource failure model gridsim/util/*.java -- includes some statistics classes. GridSim APIs and examples are also available on the GridSim website. If you are looking for applications or programs built on top of GridSim, such as gridbroker or Visual Modeler, they can be found below: http://www.gridbus.org/gridsim/release.html Software Requirements : Java version 1.4.2 or newer --------------------- GridSim has been tested and ran on Sun's Java version 1.4.2 or newer. Older versions of Java are not compatible. If you have non-Sun Java version, such as gcj or J++, they may not be compatible. You also need to install Ant to compile GridSim (explained in more details later). Installation and Running GridSim Toolkit ---------------------------------------- There is no special program to install GridSim. You just need to unzip the GridSim file to install. If you want to remove GridSim, then remove the whole $GRIDSIM directory. NOTE: You do not need to compile GridSim source code. The JAR file is provided to compile and to run GridSim applications. Description of the following jar files: * gridsim.jar -- contains both GridSim and SimJava v2.0 class files * simjava2.jar -- contains SimJava v2.0 class files only To compile and run GridSim applications, do the following step: 1) Go the directory where the GridSim's Example1 reside In Unix or Linux: cd $GRIDSIM/examples/Example01 In Windows: cd %GRIDSIM%\examples\Example01 2) Compile the Java source file In Unix or Linux: javac -classpath $GRIDSIM/jars/gridsim.jar:. Example1.java In Windows: javac -classpath %GRIDSIM%\jars\gridsim.jar;. Example1.java 3) Running the Java class file In Unix or Linux: java -classpath $GRIDSIM/jars/gridsim.jar:. Example1 In Windows: java -classpath %GRIDSIM%\jars\gridsim.jar;. Example1 NOTE: * $GRIDSIM or %GRIDSIM% is the location of the GridSim Toolkit package. * If you are using Java IDEs, such as Eclipse, JBuilder and JCreator, their instructions (with screenshots) are found on the GridSim website. * Running GridSim of this version requires a lot of memory since there are many objects to be created. Therefore, it is recommended to have at least 512MB RAM or increase JVM heap size when running Java for large simulation experiments. For example: java -Xmx300m -classpath $GRIDSIM/jars/gridsim.jar:. Example1 (max. heap size is 300MB). Learning GridSim ---------------- To understand on how to use GridSim, please go through the examples provided in the $GRIDSIM/examples/ directory. Example 1 - 6 are mainly for beginners, whereas the rest describes more complex GridSim functionalities. The same examples are also hosted in the GridSim website. At the moment, GridSim has two allocation policies or scheduling algorithms, i.e. First Come First Service (as described in SpaceShared.java) and Round Robin (as described in TimeShared.java). If you are interested in writing a new scheduling algorithm of a resource, then look closely on $GRIDSIM/examples/Example08/ directory. We are certainly welcomed new additions of allocation policies into GridSim. Compiling GridSim : Using Ant ----------------- This release contains a simple buildfile for compiling GridSim classes. You need to have ant installed (http://ant.apache.org/). Ant can be used in both Windows and Unix/Linux environment. Usage: * type 'ant' to compile all gridsim source files and put them into classes/ directory * type 'ant makejar' to compile the source files (if necessary) and to create a new jar file called "new_gridsim.jar" into jars/ directory. The "new_gridsim.jar" however only contains GridSim classes not SimJava2. NOTE: * You need to set up PATH for ant in Windows and/or Unix. * rule for javadoc is not included yet. Use javadoc.sh script on Unix instead. Alternatively, the GridSim API can be found below: http://www.gridbus.org/gridsim/doc/ Contacting Us : subscribe to Mailing Lists at SourceForge.net ------------- Please read FAQ, examples, API and other documents in the GridSim website before contacting us. GridSim mailing lists can be found below: http://sourceforge.net/projects/gridsim/ then click on the "Mailing Lists" tab. Please subscribe to the following mailing lists: gridsim-users (at) lists.sourceforge.net - for any queries and feedbacks gridsim-developers (at) lists.sourceforge.net - for contributing to GridSim Contributors are always needed to improve and maintain GridSim. Another option is to integrate your work/project into future GridSim releases. If you want to contribute, advertise yourself to us. Benefits of your contributions: - you help future Grid researchers and students like you and us; - you can proudly write your contributions in the resume or CV; - you gain knowledge and skills in using SVN version control, Java, and OO; and - more importantly, you are dealing with a real software engineering development and working with collaborators or developers from other parts of the world (at the moment, they are from "down under"). You can not get this kind of unique experience by doing it yourself or in university assignments or projects. NOTE: * If you experience some problems when compiling/running GridSim, write a detailed email. The more information you provide, the better we analyze your problem. Hence, the sooner we can reply. * Please send your questions to these mailing lists so that other people can read and reply them. * We have hectic schedules, so do not expect an instant reply. Bugs Reporting -------------- If you found any bugs, please report them to: http://sourceforge.net/projects/gridsim/ then click on the "Tracker" tab. To prevent any false reports, it is recommended that you email us first on gridsim-developers (at) lists.sourceforge.net to identify whether the problem is caused by bugs in the GridSim code or something else, such as using Java version 1.3. Please be specific when you report a bug. We need information such as GridSim version number, Java version number, detailed descriptions, snippets of the (buggy) code and any exception errors. A 'nobody' report in the tracker will probably be ignored. Requesting New Features ----------------------- If you decide to implement any new features, we will try our best to help you with directions on where to start and how to design and implement without breaking the existing design and code respectively. Acknowledgement --------------- For their outstanding contributions to GridSim : * Agustin Caminero from The University of Castilla La Mancha, Spain for his work on the gridsim.resFailure package. * Uros Cibej from The University of Ljubljana, Slovenia for providing build.xml file and instruction on how to use ant. In addition, he worked on the gridsim.datagrid package. * Gokul Poduval from National University of Singapore for his work on the gridsim.net package. * Marcos Dias de Assuncao from Grids Lab, The University of Melbourne, Australia for his work on the gridsim.auction package We also thank the following people for finding bugs in GridSim : Gokul Poduval, Uros Cibej, Agustin Caminero, Sai Rahul Reddy, Jakub Milkiewicz, Mads Mbuso Sibeko, Felipe Ramos.