Mancoosi Solver Competition Rules

    Version: 0.2.7
    Last-Modified: Wed, 16 Dec 2009 15:37:06 +0100
    Authors:
     Pietro Abate,
     Ralf Treinen,
     Stefano Zacchiroli

Solver bundling

  • Each participating solver must be bundled as a single directory (from now on called "the solver directory").

    • The directory name identifies the solver in the competition, hence the directory name should resemble the legacy solver name as closely as possible.

    • The directory name must be matched by the regular expression [a-z][a-zA-Z0-9-]*, that is it must consist of Latin letters, arabic numerals, and dashes only, and it must start with a lower case letter.

  • Each solver directory must contain an executable of the same name of the solver (from now on called "the solver").

    • Participants willing to have their solvers taking part in different tracks will need to submit one copy of the solver to each track.

  • The solver directory can contain support files and/or sub-directories.

Submission of the solver directory

  • The solver directory, as described above, must be submitted as a single-file archive. Accepted archive formats are: .tar, .tar.gz, .zip .

Execution environment

  • The solver will be executed on a GNU/Linux host, architecture x86, 32 bit.

  • The solver will be executed in a constrained chroot environment containing:

    • A standard POSIX environment. In particular a POSIX-compatible shell, which may be invoked by /bin/sh, will be available, as well as a GNU Bourne-Again SHell (invoked as /bin/bash).

    • A Java Runtime Environment (JRE) 6; the Java application launcher can be invoked as /usr/bin/java.

    • A Python 2.5 environment; the main Python interpreter can be invoked as /usr/bin/python.

    No other libraries, for any programming language, can a priori be assumed to be available in the chroot environment. That means:

    • Solvers prepared using compilers supporting compilation to ELF must be submitted as statically linked ELF binaries. No assumptions can be made on available shared libraries (*.so) in the chroot environment.

    • Solvers written in some (supported) interpreted language must use the usual shebang lines (#!/path/to/interpreter) to invoke their interpreter.

    • Solvers written in Java must be wrapped by shell scripts invoking the Java application launcher as needed.

    • Solvers needing other kind of support in the chroot must make specific arrangements with the competition organizers before the final submission.

  • The solver execution will be additionally constrained by the following limits (as implemented by ulimit):

    • Maximum execution time: 5 minutes
    • Maximum memory (RAM): 1 GB
    • Maximum file system space: 1 GB (including the solver itself)

Solver invocation

  • The solver will be executed from within the solver directory.

  • The solver will be called with 2 command line arguments: cudfin and cudfout, in this order. Both arguments are absolute file systems paths.

    1. cudfin points to a complete CUDF 2.0 document, describing an upgrade scenario. The CUDF document will be encoded as ASCII plain text, not compressed.

      • CUDF 2.0 specifications are available at http://www.mancoosi.org/deliverables/.

      • According to the specifications, the document will consist of an optional preamble stanza, followed by several package stanzas, and ended by a request stanza.

    2. cudfout points to a non-existent file that should be created by the solver to store its result.

  • Solver's standard output can be used to emit informative message about what the solver is doing.

  • If the solver is able to find a solution, then it must:

    1. write to cudfout the solution encoded in CUDF syntax as described in Appendix B of the CUDF 2.0 specification;

    2. exit with an exit code of 0.

  • If the solver is unable to find a solution, then it must:

    1. write to cudfout the string "FAIL" (without quotes), possibly followed by an explanation in subsequent lines (lines are separated by newline characters, ASCII 0x0A);

    2. exit with an exit code of 0.

  • All exit codes other than 0 will be considered as indications of unexpected and exceptional failures not related to the inability to find a solution.

Example

Your solver tool is called Super Solver. It consists of a statically linked executable solver which will need for its execution files aux1 and aux2. The program solver reads the file passed as its only command line argument, writes to standard output, and produces exit codes as required, but has to be called with options -foo and -bar.

You create a directory called super-solver/ containing the following files:

    ./super-solver$ ls -1 -F
    aux1
    aux2
    solver*
    super-solver*

The file super-solver, which according to the above rules is the main entry point to Super Solver, consists of the following two lines:

    #/bin/bash
    ./solver -foo -bar "$@"

You submit the above directory in form of an archive file.

We will extract that archive somewhere in the file hierarchy of the chroot, say at /some/path. This yields a directory /some/path/super-solver containing the above 4 files. In order to run your tool on a CUDF document which is placed at /some/other/path/problem.cudf we will run something like:

    cd /some/path/super-solver && \
      ./super-solver /some/other/path/problem.cudf \
                     /yet/another/path/output.cudf

and look at the resulting exit code.