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:
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.
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).
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>
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.
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 $