SATS is a universal "Spectrum Auction Test Suite". SATS contains seven value models (some stylized and some realistic) for spectrum auctions. The SATS software provides auction instance generators for each of the value models, i.e., it allows a user to generate an arbitrary number of auction instances for any of the spectrum value models. For four of the models, SATS also contains a MIP formulation for the winner determination problem, which enables users to quickly find the efficient allocation of the auction (and without restriction to a small number of sampled bundles, as occurs in CATS [Leyton-Brown et al., 2000]).
More information about SATS, and the ability to run SATS as a web service, is available at the SATS web page spectrumauctions.org.
SATS was developed in a collaboration between the University of Zurich and Boston University.
The System is described in detail in the following paper:
SATS: A Universal Spectrum Auction Test Suite Michael Weiss, Benjamin Lubin, and Sven Seuken. In Proceedings of the 16th International Conference on Autonomous Agents and Multiagent Systems (AAMAS), São Paulo, Brazil, May 2017. [pdf]
If you use this software for academic purposes, please cite the above in your work. Bibtex for this reference is as follows:
@inproceedings{weiss2017sats,
title={Sats: A universal spectrum auction test suite},
author={Weiss, Michael and Lubin, Benjamin and Seuken, Sven},
booktitle={Proceedings of the 16th Conference on Autonomous Agents and MultiAgent Systems},
address={São Paulo, Brazil},
pages={51--59},
year={2017},
}
The SATS source code consists of three sub-modules:
- Core API: Contains all value models and all features of SATS
- Optimization API: Contains the winner determination solvers
- Command Line Tool: Allows generation of auction instances (i.e., value files) via command line with limited parametrization options
Since v0.6.0, these sub-modules are merged into a single module called sats.
- Java 11 (or later)
You can use the SATS Core API as a library in your own java project. It allows you to access and modify all of sats value models to generate value function instances for your simulations.
The complete sats package is deployed to Maven Central, so including it in your maven project
(or analogously with a gradle project following the gradle syntax) is as easy as
<dependency>
<groupId>org.spectrumauctions</groupId>
<artifactId>sats</artifactId>
<version>x.y.z</version>
</dependency>
(replace x.y.z with the release version you'd like to use)
Alternatively, if you don't use Maven nor Gradle, you can also simply download the newest version's JAR and include it in your project. The JAR is published along with the release.
Code examples can be found in the
org.spectrumauctions.sats.core.examples
package.
To access the SATS Optimization API, you first have to include sats analogously as for the SATS Core API.
The SATS Optimization API is based on the SATS Core API and provides winner determination problem (WDP) solvers.
- When using
maven, include your localcplex.jarin your maven repository by the following command:mvn install:install-file -Dfile=<path-to-cplex-jar> -DgroupId=cplex -DartifactId=cplex -Dversion=12.9 -Dpackaging=jar - Make sure to add your native CPLEX binaries to your
PATH(Windows) /LD_LIBRARY_PATH(Unix) environment variable so sats-opt can find it! This may be done automatically when installing CPLEX. - If you don't provide a
cplex.jar, sats-opt will use LPSolve as a solver, which is considerably less performant.
Code examples can be found in the
org.spectrumauctions.sats.opt.examples
package in the test folder of this repository.
You find the latest version of the sats.jar in the latest release.
java -jar sats.jar --model MRVM --nationalbidders 3 --iterator RANDOM --bidsPerBidder 10
| Option (* = required) | Description |
|---|---|
--model <Model>* |
Chose which model to use to generate your value function. Possible models: BVM, MBVM, SRVM, MRVM, LSVM, GSVM, CATS |
--bidsPerBidder |
The number of atomic XOR bids per bidder to be written to the output file |
--bidspath |
Path to the folder where the bid files should be stored. Default is a folder bidfiles |
--filetype <FileType> |
Decide for a File Type in which the bids are returned. Options are JSON and CATS |
--iterator <BiddingLanguage> |
Define an order in which the atomic bids should be returned. Options are: SIZE_INCREASING, SIZE_DECREASING, RANDOM, BIDDER_SPECIFIC, CATS_SPECIFIC |
--multiplefiles |
Define if a separate file should be created for every bidder |
--mute |
Disables notification about successful creation of files |
--seed <Long> |
Specify the seeds used for the creation of the random instances. If two seeds (e.g. --seed 123 --seed 345) are passed, one is used for the creation of a non-bidder specific parameters (aka. world) and the second one for the bidders. If only one seed is defined, it is used to generate two seeds (for world and bidders) |
--xorq |
if flag is set, the returned bids are XOR-Q (And file format JSON) |
--help |
Gives a list of all possible Options. If used with the --model tag, the options for the specified model are also printed. |
| Option | Description |
|---|---|
--bidders |
The number of bidders |
| Option | Description |
|---|---|
--smallb |
The number of Small Bidders |
--highb |
The number of High Frequency Bidders |
--primaryb |
The number of Primary Bidders |
--secondaryb |
The number of Secondary Bidders |
| Option | Description |
|---|---|
--localbidders |
The number of Local Bidders |
--nationalbidders |
The number of National Bidders |
--regionalbidders |
The number of Regional Bidders |
| Option | Description |
|---|---|
--nationalb |
The number of National Bidders |
--regionalb |
The number of Regional Bidders |
| Option | Description |
|---|---|
--nationalb |
The number of National Bidders |
--regionalb |
The number of Regional Bidders |
| Option | Description |
|---|---|
--bidders |
The number of bidders |
--goods |
The number of goods |
Usage example to get the same output as the CATS Region
If no iterator option is set when choosing the CATS Region model, SATS defaults to the original, CATS-specific iterator.
The same goes for the file type.
In the original CATS, the number of bidders are derived from the requested number of bids. In SATS, the user can specify the number of bidders, which results in a certain number of bids.
So, creating bids the following way in CATS:
cats -d "regions-npv" -bids 120 -goods 256
is the same as creating bids the following way in SATS:
java -jar sats.jar --model CATS --bidders 20 --goods 256
Note that there are slight statistical deviations (e.g. average number of bids per bidder, average bundle size, etc.) if the SATS output is compared to the CATS output. See the corresponding tests for details. Those deviations are very small and probably linked to the differences in the detailed implementations, therefore can be ignored in most cases.
We are grateful for bug reports and other feedback about SATS and are welcoming everyone to contribute to the project, too. If you do have a bug report or have code you want to add to SATS, please follow the following guidelines.
- To report bugs or to propose new features, please open a new issue in this repository's issue tracker.
- To contribute code, please open a pull request to merge into develop. Small bugfixes will be accepted and merged very quickly. For larger contributions, we recommend to discuss and plan the contribution in the issue tracker beforehand.
A list of contributors can be found at https://github.com/spectrumauctions/sats/blob/master/CONTRIBUTORS.md
Copyright by
- Michael Weiss
- Sven Seuken and the University of Zurich
- Ben Lubin and the Boston University
SATS is licenced under AGPL. You find the license in this repository.