Running auctions via the web app

The web app provides a convenient interface for running simple auctions, primarily for demonstration purposes. All auction data (supply information, bids and other parameters) is provided by a single user through their web browser. They can then press a button to see the results of the auction immediately, both in tabular and graphical forms. Auction data and results are not stored by the server.

Accessing the web app

The web app is available at http://pma.nuff.ox.ac.uk:3000/. Alternatively, follow the Installation instructions to install the software locally. Once the pma-server program is installed and running, open http://localhost:3000/ in your web browser.

You can select an input mode for the web app using the drop-down menu. The “Basic” and “Full-featured” options give different ways to enter bid data for standard LP auctions. The “Budget constrained” and “+/- dot bids” options allow entering Budget constraints and Positive and negative dot-bids respectively. Note that changing the selected input mode will reset the form and clear any data that has been entered.

The fields of the “Auction input” form are discussed in the corresponding sections below. When you have entered data for the auction you would like to run, press the “Run auction” button to send the data to the server. Once the server responds with the results, they will be displayed in the “Auction output” section, in both graphical and tabular forms. See Interpreting graphical auction results for more details on the graphs that may be displayed. If an error occurs, it will be displayed in the “Auction output” region instead.

Press the “Cancel” button if you wish to abort running an auction because it is taking too long.

Press the “Save” button to download an encoded representation of the auction data in JSON (JavaScript Object Notation). You can later press the “Upload” button and select a file to open, clearing any data that was previously entered and changing the input mode if necessary.

Press the “Download (Input and Results)” button to download a .zip file containing the input data (and output data, provided you have run the auction). This is formatted in CSV files suitable for use with the CLI (see Running auctions via the command-line interface). The downloaded .zip archive contains a .json file that can be extracted and loaded back into the web interface. See Integration between the web app and CLI for more details.

Supply specification in the web app

See Supply for general background on a supply specification.

The “Supply Ordering” drop-down menu allows you to choose whether the supply curves should be interpreted horizontally (all goods are independent) or vertically (goods are priced relative to the previous good, and quantities for earlier goods include the amount supplied to later goods). (This option applies only to LP auctions, not budget-constrained or dot-bids auctions, which are implicitly horizontal.)

The number of goods in the auction is determined by the number of supply curves in the “Supply curves for each good” section. You can add and remove supply curves using the “+ Supply curve for good” and “X Supply curve for good” buttons. For each supply curve you can add and remove steps using the corresponding buttons. There must be at least one supply curve, and all supply curves must have at least one step.

For dot-bids auctions, only a single supply quantity and reserve price can be entered (as if the supply curve had only one step).

Bids in the web app

See Bids for general background on bidders and bids.

The “Bidders” section contains a list of bidders in the auction, each of which contains a collection of bids. (If a single bidder is entered, the results are presented as if each bid came from a separate bidder.) There must be at least one bidder, and all bidders must have at least one bid. The format for entering bids depends on the choice of input format.

In the “Basic” input format, a tabular representation of bids is shown, and only simple paired bids can be entered. The first column contains the quantity (number of units requested). Subsequent columns contain the bid prices on each good, ordered from left to right. There will be one column for each good in the supply.

In the “Full-featured” input format, a more complex representation of bids is shown, allowing asymmetric and generalised bids to be entered. The “Overall bid quantity” field gives the maximum number of units requested by the entire bid. This is followed by a table of “Bid values”, which specify a good, trade-off (for asymmetric bids), maximum quantity for this good (for generalised bids) and a bid price. The trade-off should be 1 for symmetric bids, and the number of units should be the overall bid quantity for non-generalised bids. Each bid must include at least one bid value.

In the “Budget constrained” input format, only a simple table of bids is used, analogous to the “Basic” format for a single bidder, but with the first column containing the bid’s budget instead of a quantity.

In the “+/- dot bids” input format, multiple bidders may be provided as in the “Basic” format. The quantity must be an integer, which may be positive or negative.

TQSS in the web app

See Total Quantity Supply Schedule.

The “TQSS” section of the form allows a Total Quantity Supply Schedule to be specified, for the “Basic” and “Full featured” input modes. The “TQSS enabled” drop-down menu must be set to show the other fields.

The “Price normalisation and scaling” drop-down determines whether absolute or normalised prices are used, and the approach used to scale the auction. For horizontal auctions, the available choices are:

For vertical auctions, only the “Absolute - scale supply” choice is available. Other combinations of the command-line options are not exposed in the web app, because they are experimental or not supported.

When absolute prices are in use:

  • The “Price measure” drop-down determines the measure on which the TQSS prices are calculated. It gives a choice of “Average price of goods” (corresponding to --mean-tqss) or “Price of specified good” (corresponding to --single-good-tqss). In the latter case, the good in question can be selected using the drop-down “Good” menu.
  • The auction size will be controlled by scaling the supply curves, as with the --supply-scale-lambda option. In the vertical case, the value of the λ parameter (between 0 and 1) can be given in the “Supply scale lambda” box. In the horizontal case, this parameter will always be 0.
  • The “TQSS steps” table contains a list of steps, as in the CSV file accompanying --tqss-file. The first step in the table is filled in automatically to have width corresponding to the auction size and price zero, and it cannot be changed.

When normalised prices are in use:

  • The “Price measure” and “Supply scale lambda” options are hidden.
  • The auction size will be controlled by adding an extra constraint to the linear program, as with --supply-constraint.
  • The first step in the “TQSS steps” table can be chosen freely.

In the web app, it is not possible to set the TQSS search strategy, lower and upper bounds or step size. A --combined-search with sensible defaults will be used to deliver accurate results and make it possible to plot a suitable graph. This corresponds to the default behaviour for the command-line interface described in Input format for TQSS.

Rationing in the web app

See Rationing and rounding.

The “Rationing and rounding options” section of the form makes it possible to override the standard rationing strategy, or change the precision with which quantities are reported. This may be useful if the standard strategy is too slow, or if more precise results are required. The section is collapsed by default, but can be expanded by clicking the arrow button. These options are available in the “Basic” and “Full-featured” input modes, but not for budget-constrained or +/- dot-bids auctions.

The “Standard” rationing mode corresponds to the --linear-demand-prefer-paired-bids option, and the “Standard without preferring paired bids” mode corresponds to the --linear-demand option. The latter is available only in the “Full-featured” input mode. In either of these cases, a number of steps may be set in the “Rationing step count” box, or the value 0 means a number of steps will be chosen automatically.

The “Disabled” mode (corresponding to the --no-rationing option) does not perform any rationing, so the reported allocations are given directly by the solution to the LP. This solution might not be unique, so the results depend on arbitrary implementation details of the solver.

The “Rounding of allocations” drop-down menu makes it possible to choose the number of decimal places to which allocated quantities are calculated, corresponding to the --scale-factor option. Fewer decimal places may improve performance, in particular when using rationing with the automatic step count, as fewer steps are required to yield sufficiently precise results.

Maximisation strategies in the web app

In the “Basic” input format, the “Maximisation strategy” section of the form (collapsed by default) provides a drop-down menu to choose the objective function. The available options are:

  • Bidders’ surplus + seller’s profit (maximise efficiency)
  • Seller’s profit (maximise profitability)

See Maximisation strategies for more detail on these options. When “Seller’s profit (maximise profitability)” is chosen, the supply ordering must be set to horizontal, and the TQSS must be disabled, otherwise an error will be reported. Moreover, the rationing options will be ignored when this option is used.

The other input formats do not offer a choice of maximisation strategy. The “Full-featured” and “+/- dot bids” formats always maximise efficiency, while the “Budget constrained” format always maximises profitability.

Web app limitations

Not all features of the command-line interface are available in the web application, in order to keep the latter as simple as possible. In particular:

Integration between the web app and CLI

You may wish to set up an auction specification in the web app, then switch to the command-line pma program to actually run the auction (e.g. if bidders are providing their bids via CSV files, or if you wish to gain access to features not supported by the web app). The “Download (Input and Results)” button produces a .zip archive, which can be extracted using a standard tool. This archive includes a complete description of the auction as a collection of CSV files and a batch file run_auction.bat, which contains the command necessary to run the auction using the command-line interface. If you have run the auction using the web interface, the output data will also be included in the ZIP archive.

On Windows, after extracting the archive you can double-click the run_auction.bat file to run the auction locally, without using the command prompt. In this case, it may be useful to edit the batch file (e.g. using Notepad) to add a line containing the word pause by itself; this will make it possible to read any output printed by the program (e.g. error messages).

The ZIP archive contains a file request.json, which is a machine-readable description of the downloaded auction in JSON format, suitable for loading into the web app or passing to the command-line interface (see JSON interface).

If you have an auction specification designed for the command-line interface (i.e. a collection of CSV files and program options) and wish to load it into the web app, the --json-request-output-file option makes it possible to produce a suitable request.json file.

Server command-line options

The server accepts the following command-line options to adjust its behaviour.

--port ARG

Port number on which the server runs (default: 3000)

--timeout ARG

Request timeout in seconds (default: 30)

--pma-binary ARG

Path to pma executable to start for each auction request (default: “pma”)

The following options are likely useful only for developers:

--swagger-schema

Instead of starting the server, print out the Swagger schema used for communication with the frontend

--development

Switch to development mode (ui.html is loaded dynamically)

--debug

Generate verbose debug output every time an auction is run

In addition, it may be useful to set GHC runtime system options. For example, the maximum heap size used by the server can be limited to 256Mb with +RTS -M256M -RTS, or the same limit can be imposed on the individual processes handling requests with --pma-binary "pma +RTS -M256M -RTS".