Running auctions via the command-line interface

The command-line program pma takes a complete specification of an auction (given via command-line parameters and CSV files), runs the auction and outputs the results (as CSV files and HTML pages containing graphs). This section explains how to run the program and interpret the output. It assumes that you are comfortable running programs via the command line.

Recall that a CSV (comma-separated value) file is essentially a table of data written in plain text format separated by commas and line breaks; it can be produced by spreadsheet programs such as Microsoft Excel. In this section, CSV files are represented as tables of data, with a source link in the caption that provides the original file.

Note that it is outside the scope of the package to specify how bid data ends up on the computer running the program. For a real-world auction, bidders could perhaps be asked to submit their bids to the auctioneer in a CSV file using a secure mechanism such as PGP-signed email, and the auctioneer could then run the pma program on the CSV files with a pre-determined set of parameters.

Usage example

To run a simple auction, first make sure that the pma executable is installed and on your PATH (see Installation). Save the files basic-bids.csv and supply.csv to a directory your local disk, then run the following command from the same directory:

pma lp --supply-file supply.csv --bids-file basic-bids.csv

This will run an auction and print the results to standard output. The following subsections describe the available command-line options and the format of the CSV files in detail.

Command-line parameters

The pma program supports sub-commands for the different kinds of auction:

  • pma lp runs a standard Product-Mix Auction using the linear programming based solver (described below);
  • pma bc runs a custom solver for auctions with budget-constrained bids (see Budget constraints);
  • pma dot-bids runs a custom solver for auctions with positive and negative dot-bids (see Positive and negative dot-bids);
  • pma json invokes the machine-readable interface (see JSON interface).

Use --help to see a brief summary of command-line parameters supported by the program.

The minimum information that must be specified to run an auction is a supply of goods (using --supply-file) and a list of bids (using --bids-file). These files must be formatted as described below in Input format for supply and Input format for bids.

--help

Displays brief help on using the command-line program.

--supply-file CSV-FILE

Specify the file containing the supply curve information.

--bids-file CSV-FILE

Specify a file containing bids.

The --bids-file option may be used multiple times, in case each bidder has submitted bids in a separate file.

Input format for bids

Bids are entered in CSV files with one bid per row. The columns of the CSV file depend on which variations are in use. The default is for basic bids, but generalised or asymmetric bids may be specified using options:

--generalised-bids

Read the input bids as generalised (with max quantity columns for each good).

--asymmetric-bids

Read the input bids as asymmetric (with trade-off columns for each good).

For the basic auction (without the --generalised-bids or --asymmetric-bids options), the bids CSV file must have three fixed columns:

  • A string label that uniquely identifies each bidder.
  • A string label that identifies the individual bid.
  • A bid quantity (as a positive integer).

These must be followed by one price column for each good in the auction. Prices must be integers, or may be omitted, in which case a value of 0 will be assumed.

The CSV file must have a header row, but the text of the headers will be ignored (so in particular, it is not correct to permute the order of columns).

--bids-file basic example (source)
Bidder Bid Quantity Price for good 1 Price for good 2
A 1 5 120 75
B 1 1 100  
B 2 10 0 200

In this example, bidder A has bid for a maximum of 5 units at a price of up to 120 for good 1 or 75 for good 2, and bidder B has submitted two bids.

The association of bids with bidders does not affect the running of the basic auction, but makes a difference to the presentation of the output, and is relevant when additional constraints are in use (see Additional constraint options below).

Generalised bids

If the --generalised-bids option is in use, each price column must be preceded by a maximum quantity column for the corresponding good. Each maximum quantity must be a nonnegative integer, or may be omitted, in which case a value of 0 will be assumed.

As with basic bids, the third column must contain a limit on the quantity across all the goods.

For example:

--bids-file example with generalised bids (source)
Bidder Bid Overall quantity Max quantity for good 1 Price for good 1 Max quantity for good 2 Price for good 2
A 1 5 5 120 3 75
B 1 1 1 100    
B 2 12 10 0 5 200

In this example, bidder A has bid for a maximum of 5 units, consisting of up to 5 units of good 1 at a price of 120 or up to 3 units of good 2 at a price of 75.

Asymmetric bids

If the --asymmetric-bids option is in use, each (maximum quantity column and) price column must be preceded by a trade-off column for the corresponding good. This must be a positive integer.

For example:

--bids-file example with asymmetric bids (source)
Bidder Bid Overall quantity Trade-off for good 1 Price for good 1 Trade-off for good 2 Price for good 2
A 1 6 2 120 3 75
B 1 1 1 100    
B 2 12 1 0 3 200

In this example, bidder A has bid for up to 6/2 units of good 1 at per-unit price 120, or up to 6/3 units of good 2 at per-unit price 75.

When both the --generalised-bids and --asymmetric-bids options are in use, the trade-off column comes first, as shown in this example:

--bids-file example with generalised asymmetric bids (source)
Bidder Bid Overall quantity Trade-off for good 1 Max quantity for good 1 Price for good 1 Trade-off for good 2 Max quantity for good 2 Price for good 2
A 1 6 2 4 120 1 3 75
B 1 1 1 1 100      
B 2 12 1 12 0 3 6 200

In this example, bidder A has bid for a maximum of 6 units divided by the relevant trade-off value, consisting of up to 4/2 units of good 1 at price 120, or up to 3/1 units of good 2 at price 75. If the auction determines prices of 100 for good 1 and 10 for good 2, the bid will receive all 3 units of good 2, then the overall maximum limits the number of good 1 units received to 3/2.

Input format for supply

See the Supply subsection for discussion of supply curves in general. The supply ordering can be chosen using command-line options:

--horizontal-supply

Interpret supply curves as forming a “horizontal” supply, where each good is priced relative to selling nothing.

--vertical-supply

Interpret supply curves as forming a “vertical” supply, where each good is priced relative to the preceding good.

--tabular-supply ROWS

Make a tabular supply with the given number of goods per column (using a ragged final column if there are not enough goods). Using 1 good per column gives a horizontal supply, and using a number larger than the number of goods gives a vertical supply.

--tabular-supply-with-base ROWS

Make a tabular supply with the first good below every column, and the given number of goods per column (using a ragged final column if there are not enough goods). Using a number larger than the number of goods gives a vertical supply.

The --supply-file option can be used to provide a CSV file from which supply curve data is taken. The first two columns contain the quantity (width of step) and price (height of step) for the first good, and so on for subsequent goods.

--supply-file example (source)
Quantity of good 1 Price for good 1 Quantity of good 2 Price for good 2
4 0 6 10
2 5 0 0

In this example, 4 units are available of good 1 with no reserve price, and a further 2 units are available provided a reserve price of 5 is met. Only 6 units of good 2 are available and with a reserve price of 10 (above the price of good 1, assuming --vertical-supply is used).

Note that it is permissible to have a step width of 0, in which case the step will be ignored, and that step widths (quantities) are not cumulative.

Input format for TQSS

See the Total Quantity Supply Schedule subsection for an explanation of the general idea of a TQSS. In order to use a TQSS, the --tqss-file option must be specified giving the TQSS supply function as a CSV file.

--tqss-file CSV-FILE

Name of file in which the TQSS function specification can be found.

The CSV file describing the TQSS function must contain two columns, giving step widths and prices respectively.

--tqss-file example (source)
Step width Mean price
5 0
1 80
1 112
0.5 140
0.5 160
1 200

TQSS prices may be absolute (see TQSS with absolute prices) or normalised (see TQSS with normalised prices):

--absolute-prices

Use absolute prices in the definition of the TQSS (this is the default). Further options may be used as documented below.

--normalised-prices

Use normalised prices in the definition of the TQSS. The --horizontal-supply option must be used. Further options are not available.

Options for TQSS with absolute prices

The following options are available only when the --absolute-prices option is used (or neither option is specified, in which case absolute prices will be used by default).

The default is for the TQSS to be based on the mean price of all goods (option --mean-tqss), but the --single-good-tqss option may be used to choose a single good instead. (Note that the text in the header row of the CSV file is not relevant.)

--single-good-tqss GOOD

Make a TQSS based on the price of a single good.

--mean-tqss

Make a TQSS based on the mean price of all the goods.

There are two possible approaches to varying the size of the auction during TQSS solving: adding a total quantity constraint to the linear program, or scaling the supply curves. The --supply-constraint option causes a total quantity constraint to be used. Alternatively, the --supply-scale-lambda option causes the supply curves to be scaled (with the parameter λ, which must be specified, controlling the proportion of scaling for non-base goods).

--supply-constraint

Rather than scaling the supply during TQSS solving, add a total quantity constraint to the linear program.

--supply-scale-lambda RATIO

Parameter to control scaling during TQSS solving. Base goods will be scaled in proportion to the new total size. Subsequent goods will be scaled depending on the given parameter lambda, which must be in the interval [0,1] (0 scales all goods in proportion to the new total size; 1 does not scale goods other than the base goods).

Solving the TQSS requires searching for the intersection between supply and demand curves, by calculating the demand at a fixed number of auction sizes. A search strategy may optionally be specified, or by default the --combined-search strategy will be used.

Evaluate the TQSS on a range of points across the entire interval (like --linear-search-all). If an exact intersection does not lie on one of these points, perform an additional --binary-search to give a more precise result.

Perform binary search on the interval. (Recommended for the fastest results, where there is a unique solution.)

--linear-search-all

Evaluate the TQSS on a range of points across the entire interval. Choose the point closest to the intersection.

--linear-search-below

Perform linear search from below (terminating when a solution is reached).

In addition, the search step size and lower and upper bounds may be specified. By default, the step size will be chosen so that a fixed number of points are used (except for binary search, where this option is ignored). The default lower bound will be 0 when the --supply-constraint option is used, or the initial auction size (from the supply curves) when the --supply-scale-lambda option is used (as supply curves should normally be scaled upwards but not downwards). The default upper bound will be the quantity given by the final TQSS step (i.e. the upper limit of its domain). Note that with the --supply-scale-lambda option, the upper limit of the TQSS domain must be greater than the initial auction size from the supply curves, otherwise an error will result.

--tqss-step-size UNITS

Step size for TQSS search modes other than binary search.

--tqss-from UNITS

Lower bound of interval for TQSS search.

--tqss-to UNITS

Upper bound of interval for TQSS search.

Additional constraint options

When there are multiple bidders, additional constraints may be imposed on the amounts that they receive in the auction. These may be specified as an absolute maximum (a quantity independent of the size of the auction) or as a fraction of the auction size.

--bidder-absolute-max UNITS

Limit the maximum quantity received by each bidder to an absolute number of units.

--bidder-relative-max RATIO

Limit the maximum quantity received by each bidder to a fraction of the total size of the auction.

Rationing and rounding options

See Rationing and rounding for background on rationing.

--no-rationing

Let the linear programme do what it will do, and don’t do anything about it.

--linear-demand STEPS

Tweak marginal bids to approximate a linear demand around the bid price, then re-run the auction to find adjusted allocations.

--linear-demand-prefer-paired-bids STEPS

Same as --linear-demand but apply the tweaks only to paired bids that are marginal on multiple goods, and subsequently reallocate to treat equally bids that are marginal on single goods.

For the --linear-demand and --linear-demand-prefer-paired-bids options, a positive integer number of steps to use for approximating linear demand may be specified. Increasing this number reduces arbitrariness in the rationing results, but also increases the computational cost of rationing. If the value 0 is used, the program will automatically choose a number of steps sufficiently large to ensure results are accurate to within the precision with which quantities are reported (controlled by --scale-factor). However, this number of steps may be large and hence incur a significant runtime overhead.

The default rationing method is to use --linear-demand-prefer-paired-bids with an automatically-chosen number of steps.

--scale-factor INT

Specifies the precision with which quantity results should be reported, as a number of decimal places. The default is 1 decimal place. Increasing this will increase the number of rationing steps used by default (see Rationing and rounding options) and reduce the magnitude of the tweaks to ensure unique allocations.

Maximisation strategy options

See Maximisation strategies for background on maximisation strategies. The maximisation strategy may be chosen explicitly using one of the following options:

--max-efficiency

Maximise efficiency of auction as a whole

--max-profit

Maximise auctioneer’s profit

If unspecified, the --max-efficiency option is the default.

When the --max-profit option is used, the auctioneer’s profit will be printed to the file specified by --results-file (or to standard output, if a file is not specified).

Output formats

The output data produced by running the auction can be directed to files using the following options, otherwise it will be printed to standard output by default.

--prices-file CSV-FILE

For each good, the price determined by the auction and the total quantity allocated.

--allocs-file CSV-FILE

For each bidder, the quantities of each good it is allocated.

--bid-allocs-file CSV-FILE

For each bid, the quantities of each good it is allocated.

--tqss-points-file CSV-FILE

For each TQSS point, the demand, the price and the supply.

--results-file TXT-FILE

Results of the auction that are not specific to goods or bidders.

The --prices-file option produces a CSV file containing a header column and one column for each good, with rows for the auction price, lowest winning bid price and total number of units allocated. If no units of a good are allocated, the lowest winning bid price is taken to be the (first) reserve price from the supply curve.

--prices-file example (source)
  Good 1 Good 2
Auction price 50 125
Lowest winning bid price 75 150
Allocation 2.4 3.6

The --allocs-file option produces a CSV file containing one row for each bidder, with columns for the bidder label and the quantity allocated of each good. Only successful bidders (i.e. those that receive more than zero units) are included in the table.

--allocs-file example (source)
Bidder Quantity of good 1 Quantity of good 2
1 1.0 0.0
2 1.0 0.0
3 0.0 2.0
5 0.4 0.6
6 0.0 1.0

The --bid-allocs-file option produces a CSV file containing one row for each bid, with columns for the bidder label, bid label and the quantity allocated of each good. Frequently the allocation will be zero for all goods except one, but this need not always be the case. Only successful bids (i.e. those that receive more than zero units) are included in the table. This file is not printed to standard output by default, only if it is explicitly requested.

--bid-allocs-file example (source)
Bidder Bid Quantity of good 1 Quantity of good 2 Quantity of good 3
01 1 8.0 0.0 0.0
02 1 10.0 0.0 0.0
03 1 0.0 0.0 20.0
04 1 20.0 0.0 0.0
05 1 0.0 10.0 0.0
06 1 0.0 0.0 20.0
07 1 0.0 20.0 0.0
09 1 0.0 0.0 12.0

The --tqss-points-file option produces a CSV file containing a list of points evaluated when running the TQSS. It has no effect if a TQSS with absolute prices is not in use. The “Demand” column contains the total size of the auction that was run, the “Price” column contains the auction price measure used by the TQSS at that size, and the “Supply” column contains the value of the TQSS function at that price.

--tqss-points-file example (source)
Demand Price Supply
1.1 160.0 8.0
2.1 160.0 8.0
3.0 150.0 7.5
4.1 140.0 7.5
5.0 112.5 7.0
6.0 87.5 6.0

The --results-file option produces a text file containing individual values determined by the auction, where these do not relate to particular goods, bidders or TQSS points. This will include:

  • When a TQSS is in use, the total quantity found by solving the TQSS.
  • When a TQSS with --normalised-prices is in use, the normalised price across all goods.
  • When the --max-profit option is in use, the auctioneer’s profit.

If none of these are applicable, no file will be output, even if the --results-file option is specified.

Graphical output options

The --graphics-file option produces a HTML page containing embedded graphs. These graphs are described further in the section Interpreting graphical auction results. Various options are available to control the generated graphs:

--graphics-file HTML-FILE

Writes a HTML page with graphs to the given file, overwriting it if it exists already.

--demand-curve CURVE

Calculate supply and demand curves of the given type (see Supply and demand for each good for details of available curve types and the default behaviour). This option can be specified multiple times.

--dotsize DOUBLE

Size for the bubbles in the bubble charts (default: 20.0)

Whether to show bid quantities may be selected using one of the following (mutually exclusive) options:

--graph-show-bid-quantity

Show the quantity of each bid next to the bubble (default)

--graph-hide-bid-quantity

Hide the quantity of each bid next to the bubble

How to colour the bids in the graphs may be selected using one of the following (mutually exclusive) options:

--graph-bid-unique-colors

Use a different color for each bid (default)

--graph-bid-simple-colors

Use only three colors for bids (accepted, rationed, rejected)

Miscellaneous user options

--shuffle-bids

Randomly shuffle the bids and additional constraints before running the auction. The bidder/bid labels will be replaced with integer labels in a random order, with bids from different bidders interspersed. If the program may favour arbitrary bids (e.g. because rationing is not in use), this makes it unpredictable which bids will be favoured. One could go further and break large bids into smaller bids to make the bids more homogeneous, but this is not currently implemented.

--preference-order

Preference order for allocating goods (permutation of the good labels in descending order of preference); by default, the highest-index good is most preferred. Goods omitted from the preference permutation will not be tweaked, so to disable price tweaks entirely, pass this flag with no arguments.

Development options

The following options are intended for developers working on the Product-Mix Auction library itself, or integrating it into a larger project.

--debug

Generate debugging log output and write out the linear programmes passed to the LP solver in CPLEX LP format.

Generating test data

Instead of specifying input data as CSV files using the --supply-file or --bids-file options, the --arbitrary-supply or --arbitrary-bids options can be used to generate random test data. These are primarily useful for development and testing purposes. Each of them comes with options to adjust the random data generated:

--arbitrary-supply

Generate an arbitrary supply function

--arbitrary-bids

Generate an arbitrary list of bids

--num-goods INT

Number of goods for random data generation

When the --arbitrary-supply option is in use, either a supply ordering option may be specified explicitly, or the program will arbitrary choose --horizontal-supply or --vertical-supply. In addition, the following options may be used to customize the generated supply curves:

--arbitrary-supply-min-units INT

Minimum amount of units used to draw random supply steps

--arbitrary-supply-max-units INT

Maximum amount of units used to draw random supply steps

--arbitrary-supply-min-price INT

Minimum price used to draw random supply steps

--arbitrary-supply-max-price INT

Maximum price used to draw random supply steps

--arbitrary-supply-min-steps INT

Minimum number of steps used to draw a random supply

--arbitrary-supply-max-steps INT

Maximum number of steps used to draw a random supply

When the --arbitrary-bids option is in use, the following options may be used to customize the generated bids:

--arbitrary-min-price INT

Minimum price used to draw random bids

--arbitrary-max-price INT

Maximum price used to draw random bids

--arbitrary-bid-min-units INT

Minimum amount of units used to draw random bids

--arbitrary-bid-max-units INT

Maximum amount of units used to draw random bids

--num-bidders INT

Number of bidders to generate

--num-bids INT

Number of bids to generate per bidder

--num-j-paired-bids J INT

Number of j-paired bids to generate per bidder

The --num-bids and --num-j-paired-bids options are cumulative for each bidder. For example, --num-bidders 5 --num-bids 1 --num-j-paired-bids 1 6 --num-j-paired-bids 2 3 would generate 50 bids, with each of the 5 bidders having 1 bid with completely random prices (i.e. an N-paired bid where N is the number of goods in the auction), 6 single bids and 3 paired bids.

To see the generated data, you can use the --dump-bids or --dump-supply options to write the bids or supply to specified files. If desired, the --no-run option can be used to avoid actually running the auction.

--dump-bids CSV-FILE [OUTPUT]

Dump input bids to a CSV file (useful with --arbitrary-bids). Pass - to dump to standard output.

--dump-supply CSV-FILE [OUTPUT]

Dump input supply to a CSV file (useful with --arbitrary-supply). Pass - to dump to standard output.

--no-run

Do not actually run an auction, only read / generate inputs. Useful in combination with --arbitrary-bids, --arbitrary-supply, --dump-bids and/or --dump-supply.

JSON interface

The command-line interface supports the possibility to read and write files in JSON (JavaScript Object Notation) format. This provides a compact single-file representation of auctions, which is convenient for developing programs to communicate with the auction solver.

The JSON objects are described by the Swagger schema generated by the pma-server --swagger-schema option. This schema (or the Haskell source code) should be consulted for precise definitions of the types referenced below.

The following options can be used with the pma lp, pma bc and pma dot-bids commands:

--json-request-file JSON-FILE

Read the auction input (request) from a JSON file. This option can be used in place of all the input options, and allows a JSON file produced by the web application to be executed directly by the CLI. The format of the file must correspond to the chosen command:

  • For pma lp, the format must be one of SimpleAuctionInput, MediumAuctionInput or AuctionInput.
  • For pma bc, the format must be BCAuctionInput.
  • For pma dot-bids, the format must be DBAuctionInput.
--json-request-output-file JSON-FILE

Write the auction input (request) to a JSON file, in the format supported by --json-request-file. This is primarily intended to convert inputs available as CSV files into a format suitable for loading into the web application (if possible).

For pma lp the simplest format consistent with the data will be chosen. Note that some invocations of pma lp may produce auctions that cannot be loaded into the web application, because they use features of the AuctionInput format that cannot be represented in the simpler formats used in the web application (see Web app limitations).

--json-response-file JSON-FILE

Write the auction output (response) as a JSON file. The format will be AuctionOutput, BCAuctionOutput or DBAuctionOutput as appropriate.

In addition to the command-line interface described above, the pma program supports a machine interface based on JSON format. This interface is used by pma-server when it receives a request to run an auction, but may also be useful in other contexts where it is necessary to execute auctions programmatically.

To run an auction using this interface, execute pma json, write the auction specification as a JSON object to standard input, then read the response as a JSON object from standard output. For example, if you have a file request.json representing an auction, entering the command pma json <request.json at the command line will run the auction and print out the results in JSON format. The < operator causes the file to be supplied to the program over standard input.

The auction specification should be a JSON-encoding of one of the ...AuctionInput types, and the result will be a list whose first element is one of the ...AuctionOutput types, corresponding to the --json-request-file and --json-response-file options. These are the formats used by the web app, so it is possible to save a request.json file from the web app and then execute it in the command-line interface using pma json <request.json. See also Integration between the web app and CLI.