PLEASE NOTE: CAMUS is actually compiled from the same codebase as CASS, as they 
have a great deal of code in common.  The difference is the #define MULTI_UNIT,
which is found in defines.h.  To find out about the CAMUS file format, see
the enclosed .TXT file.

----------


CASS Public Release 1.0 Documentation
(c) 1999 Kevin Leyton-Brown, Stanford University
kevinlb@robotics.stanford.edu
==============================================================================

1. Overview

CASS (Combinatorial Auction Structured Search) is an algorithm for the optimal
determination of winners in a combinatorial auction.  Given a set of bids on
bundles of goods, CASS finds a subset of bids that has maximal revenue 
while allocating each good no more than once.  (Note that CASS does not
handle the case of divisible goods--that is, goods such as network bandwidth
that can be allocated fractionally.)  CASS performs a highly-optimized branch-
and-bound search with preprocessing, heuristics for partitioning and ordering, 
dynamic child selection, caching and propagation of cache values.  Experiments 
have also suggested that CASS has good anytime performance--i.e., that 
intermediate solutions tend to be close to the optimal solution.  This release 
does not output intermediate solutions: please email me if you are interested 
in this feature.  For more information on how CASS works, please email me, or 
see our paper: "Taming the Computational Complexity of Combinatorial Auctions: 
Optimal and Approximate Approaches" from the proceedings of IJCAII 1999, also 
available from my homepage at http://robotics.stanford.edu/~kevinlb.

CASS is run from the command line, with various options specified as 
parameters.  A list of these parameters is given in section 2.  CASS can
run in two modes.  In the first mode random bids are generated by an internal 
call to our makebids program and parameterized by CASS's command-line options.
The second mode reads in a series of user-created text files.  The file format
used for these input files is explained in section 3.  A text file with the 
same name as the input file but with the suffix ".win" is created to list the
bid numbers of the winning bids.  If parameters are omitted, they revert to
their default values.

CASS times itself while running, to facilitate performance analysis.  This
timing is high-resolution, but it is implemented as a comparison between 
the system clock at start and end times, and so is of course affected by other 
system activity.  Each time a new "best" allocation is discovered, its
revenue is output to the screen.  In addition, a progress meter is displayed
throughout the search.  Note, though, that this indicates the percentage of
the search space explored, rather than the estimated percentage of time spent.
Because pruning is more effective with better "best" allocations, and because 
our heuristics organize the search structure with the most promising bids early 
in the search space, a majority of the search time tends to be spent exploring 
the first 5-10% of the tree.

2.  Command-Line Options

This screen may be viewed by typing "cass" with no parameters.  This will also
show accurate default values--they may have changed since the production of
this readme file.

------------------------------------------------------------------------------

Usage: cass [parameters]

General Parameters:
 -n number of auctions                  (default 1)
 -i input file name (.txt is appended)  (default "data")
 -c cache size (bytes)                  (default 4000000)

Bid Generation Parameters:
 -m use MakeBids to generate data files - file must be in the same dir as CASS
    If this flag is absent, CASS reads data from the specified input file
    and all bid generation flags are ignored.
 -g number of goods                     (default 40)
 -b number of bids                      (default 1000)
 -f distribution (1:Exponential 2:Linear 3:Binomial 4: Sandholm Random,
    5: Sand. Uniform, 6: Sand. Decay)   (default 1)
 -p distribution parameter              (default 5.000000)
 -s random seed                         (default 1234567890)
 -a average of prices                   (default 1000)
 -d deviation of prices                 (default 50)

Log File Parameters:
 -! force creating log file             (default present)
 -@ append to log file                  (default absent)

------------------------------------------------------------------------------

3. Input File Format

The following sample input file demonstrates the acceptable format.  In this 
release dummy goods are not supported.  Therefore, an error message will be 
given if the line "dummy 0" does not appear in an input file.

------------------------------------------------------------------------------

% comments follow percentage symbols
% blank lines are ignored
% files are not case-sensitive
% [CR]'s are optional, all whitespace is ignored

goods 15
dummy 10
bids 800

% bidnum, price, goodnum, goodnum, ..., goodnum, #

0	2075	2	6	8	#
1	3000	1	2	5	7	13	#
2	520		4	#
  .
  .
  .

% implicitly, all goods numbered 15 or above (in this example) are dummies
% note that all counting starts from zero
% bidnum's do not need to be sequential between 0..799, just unique.
%	however, negative bid numbers are reserved for internal use
% prices are integers.  Fixed point may be used to represent fractional prices
%	(as in the above example--{$20.75, $30, $5.20} )

------------------------------------------------------------------------------

                                                     revised December 24, 1999