Getting Started with MAGNET

Last update $Date: 2002/05/07 19:30:53 $

This page explains how you may obtain, build and operate the MAGNET package.

The MAGNET package is available here, in both compressed tar and zip format. This release includes only the Customer Agent components, along with a component that simulates a community of suppliers by producing a set of randomly-generated bids whenever it receives a RFQ.

Setting up your environment

MAGNET is distributed in source form, so you will need some basic development tools to build and run it.

The basic steps in getting a MAGNET development environment up and running are:
  1. Unpack the MAGNET package in a convenient location. You will get a directory called magnet, with the following subdirectories:

    doc
    Documentation, including this page and the license.
    components
    This is where you will find all the Java source code, organized into a set of components that can be configured and combined into multiple systems. Also in this directory is the top-level build script, called "build.xml".
    systems
    Each subdirectory here is an execution environment with instructions and configuration data needed to run a particular configuration of the MAGNET system. See the documentation in the individual system directories for details.
    lib
    Contains a set of jar files needed by MAGNET. These libraries the logging package log4j, and the Scheme extension language JScheme (formerly known as "silk"). Both of these are redistributed under the Apache license. If you want to run the unit tests, you will also have to pick up a copy of junit, unpack it, and place the file junit.jar in this directory. It is distributed under a separate license.
    bin
    Binary tools & utilities. Currently the only item that needs to be here is the linear programming package lp_solve. You will need to download this and build it for your platform. The binary executable needs to be in this bin directory to support the IP solver when running winner-determination search.
    dist
    This is where the .jar files will end up when you build the MAGNET system.

  2. Download and install the tools you'll need to build and run the MAGNET package. At a minimum, you'll need ant version 1.4 or later, and java, version 1.3.1 (jdk1.4 doesn't seem to like our user interface code very well, and some of the unit tests use a deprecated method assert that conflicts with the new keyword in jdk1.4; other than that, everything else works fine under jdk1.4).

  3. Prior to building the system, you'll need to set some environment variables:

       JAVA_HOME=<path to your Java installation>
       MAGNET_HOME=<path to the magnet directory you checked out>
       ANT_HOME=<path to your ant installation>
    

  4. Build the system. If you have ant installed and all the correct environment vars set, all you need to do is cd to the magnet/components directory and type ant. You can also create a local copy of the javadoc with ant doc. This will produce a javadoc hierarchy under doc/api.

  5. Test the system. You can run the unit tests with ant test in the components directory. It's not a very complete set of tests, and one of the tests of the agent timekeeping mechanism sometimes fails because of unanticipated time delays, but otherwise you should see no errors reported, as long as you run the tests in an environment where Java can open windows.

    A good overall system test is to run the GUI. cd to magnet/systems/custGui_Jun2001 and type run. You may see some complaints about missing fonts; you can fix that if you read the java release notes and download an updated font.properties file or something simple like that.

Doing stuff with MAGNET

This release is packaged with two different systems under magnet/systems that allow you to run the components in user-definable scenarios. It is easy to modify these and to create additional system definitions. At a minimum, each system contains at least the following files:

Configuration file
Usually called something like x.props, this file contains property definitions that configure the customer agent and the supplier simulation. The meaning of the various property settings are defined in the experiment-setup document. The name of this file is a required command-line argument for the various main() methods in the MAGNET customer agent.
Log Configuration file
Usually called client.lcf, the name of this file is determined by the value of the LogConfiguration property in the main configuration file. The supplied log configuration files generate two different log files, a results file and an activity trace file. In the trace file, you can generate output at any of 4 levels of detail from each class in the system. You do this by setting the log levels of categories that are named after their respective Java classes. See magnet/systems/custGui_Jun2001/client.lcf for an example.
Task type description files
The TaskTypes property specifies a list of the filenames that will be loaded as properties objects to define the types of tasks that may be used to compose plans and generate bids.
Extension scripts
Scheme scripts may be written to modify the behavior of the system without editing and recompiling the Java packages. The only example of this that is included in this package is the ability to control the problem-size scaling decision for the Simulated Annealing solver. Any command-line arguments after the main configuration file will be interpreted as scripts. On the java side, you run all scripts attached to a "hook" called name with the method edu.umn.magnet.util.silk.SilkHook.runHook(name, thing). On the Scheme side, you attach a Scheme function to a hook with the function (add-hook hook-name function-name).
Run script
Usually called run or run.sh, this is just a simple shell script that takes care of getting the classpath right and feeding the config file into a selected agent entry point.

Once you have your desired system definition set up, you usually run it by switching to its directory and issuing the run command that you have defined. As the system runs, it will generate output in any log files that are created by your log configuration file.


Copyright: © 2002 by the Regents of the University of Minnesota
Department of Computer Science and Engineering. All rights reserved.
The University of Minnesota is an equal opportunity educator and employer.
Revision: $Id: setup.html,v 1.1.2.3 2002/05/07 19:30:53 jcollins Exp $