YAML Contest Configuration - pc2ccs/pc2v9 GitHub Wiki

Configuring a contest normally involves a series of steps:

• Creating accounts for teams, judges, administrators, scoreboards, etc.
• Defining the programming languages supported (allowed) in the contest.
• Defining the contest problems.
• Configuring additional settings such as the contest name, start-time, duration, judging methods, etc.

As described in the PC2v9 Contest Administrator's Guide (available in the doc folder in every PC² download), PC² can be configured either interactively via the Administrator's Configure Contest screen, or by using YAML files. Typically, configuration via YAML is done by loading one or more YAML configuration files, which can either be done using the --load option when starting the PC² server or via the Import Config tab on the PC² Admin.

YAML configuration files are normally stored in a CLICS Contest Data Package (CDP). A typical CDP includes a folder named config containing a YAML file named contest.yaml which holds overall contest configuration data. The CDP config folder also contains one subfolder for each contest problem; each contest problem subfolder contains a file named problem.yaml containing configuration details for that specific problem.

Note: the organization and format of YAML configuration files for PC² is based on the CLICS Contest Control System Requirements Specification for input files. In particular, that specification provides for multiple different YAML files, including contest.yaml, system.yaml, problemset.yaml, and problem.yaml. PC² supports separating YAML configuration into these separate files, along with an additional YAML file system.p2.yaml containing PC²-specific configuration values. However, PC² also supports merging the contents of all YAML configuration information into just two types of files: contest.yaml and one problem.yaml file for each problem.

YAML files consist of entries called mappings. One form of YAML mapping consists of lines containing colon-separated key:value pairs. For example, a contest.yaml file might contain the following lines:

name: ICPC 2022 World Finals
short-name: 2022 Finals
start-time: 2022-06-01T10:00:00Z-08
duration: 5:00:00
scoreboard-freeze-length: 1:00:00
penalty-time: 20

This specifies that the name of the contest is "ICPC 2022 World Finals", that an acceptable "short name" for the contest (used for example where display space is limited) is "2022 Finals", that the contest starts on June 1st, 2022 at 10am Pacific Standard Time (GMT-8), that the contest lasts five hours, that the scoreboard will be frozen with one hour remaining in the contest, and that the penalty for an incorrect submission is 20 points (minutes). When PC² loads a YAML file containing these entries it will set the corresponding PC² attributes to match the specified values.

Another form of YAML mapping is a list mapping, which consists of a keyword followed by a colon and then a list of items, with each new item indented on a new line and starting with a dash. Whitespace (but not including tab characters) is used to indicate nested (indented) structure. For example, a contest.yaml file might include the following list mapping:

languages:
  - name: Java
    active: true

  - name: Perl
    active: false

  - name: GNU C++
    active: true

This specifies that there are three languages defined in the contest: Java, Perl, and C++, but that only Java and C++ are "active" (languages which are not active will not be displayed).

As another list example, the following YAML mapping specifies that there are two problems in the contest: one designated by the letter 'A', with short name "hello", balloon color "red", and balloon RGB value hex "FF0000"; the other designated by the letter 'B', with short name "sumit", balloon color "yellow", and balloon RGB value hex "FFFF00":

problemset:
  - letter: A
    short-name: hello
    color: red
    rgb: "#FF0000"

  - letter: B
    short-name: sumit
    color: yellow
    rgb: "#FFFF00"

The "short name" associated with a problem is taken to be the name of the folder beneath the config folder where the problem-specific details for the problem are found. Note also the use of quotes around the balloon RGB color values; the quotes are necessary because the "hexadecimal" indicator (#) will be misinterpreted by the YAML parser if it is not inside a quoted literal.

Each list mapping causes PC² to create a set of PC² attributes -- one attribute for each list item. For example, the languages mapping shown above will create three language definitions in PC² and the problemset mapping will create two problem definitions in PC² (including that it will search for and load a problem.yaml configuration file from the corresponding problem short-name folder and use the values in that file to set the corresponding problem attributes).

The format of YAML configuration files for PC², and in particular the set of recognized YAML keywords, is based on the CLICS Contest Control System Requirements Specification for Contest Control System (CCS) input files. PC² supports (nearly) all of the CLICS YAML keywords, as well as a number of additional PC²-specific keywords.

The following tables list the YAML keywords recognized by PC². Note that the Value field of most keywords can contain PC² Substitution Variables. (Note also that the table formatting may break some keywords into multiple lines; all keywords are single-line character strings with no imbedded spaces.)

The preceding table is currently incomplete (like many projects, the documentation lags behind the code). Some additional keywords which are supported (but not documented in the above table) include keywords to control "Shadow Mode" ( shadow-mode; ccs-url; ccs-login; ccs-password; ccs-last-event-id; ccs-test-mode; team-proxy-accounts); keywords to control the PC2 contest clock ( elapsed; remaining; running); keywords to manage problem data files ( load-data-files); keywords to specify judging parameters ( judgements; accepted-judgement; judging-type); and keywords to manage the Web Team Interface (WTI) configuration ( allow-multiple-team-logins).

Many of the YAML keywords listed above under contest.yaml files can also appear in problem.yaml files (in which case they apply only to the corresponding problem). Among the keywords which can appear in either type of file are computer-judged, load-data-files, manual-review, max-output-size-K, send-prelim-judgement, stop-on-first-failed-test-case, timeout, and validator. The following additional keywords may also appear in a problem.yaml file used to describe an individual contest problem.

Example problem.yaml file:

name: Hello World
max-output-size-K: 128
limits: 
   timeout: 5
   output:  10     #10KB; overrides max-output-size-K, above
validator: 
   validatorProg: pc2.jar edu.csus.ecs.pc2.validator.Validator
   validatorCmd: '{:validator} {:infile} {:outfile} {:ansfile} {:resfile}  -pc2 1 false'
   usingInternal: true
   validatorOption: 1
input: 
   readFromSTDIN: true
groups: 'British Columbia D1, Washington D1, Oregon D1, California D1, Hawaii D1'

Additional information on YAML keywords supported by PC² can be found on our older Wiki pages (although those pages are not maintained and may be out of date); see Contest.yaml, CCS_Enhancements, System.yaml, and System.pc2.yaml.

The following keywords may appear within each accounts item in a list of PC2 accounts to be generated for a contest. The appearance of an accounts list in a contest.yaml file has the same effect as generating the specified accounts using the interactive Generate Accounts feature in the PC2 Admin.

Example:

accounts:
 - account: TEAM
     site: 1
    start: 100
    count: 10
 
 - account: TEAM
     site: 2
    start: 200
    count: 10

- account: JUDGE
     site: 4
    count: 20

 - account: SCOREBOARD
     site: 4
    count: 1

The following keywords may appear within each auto-judging item in a list of PC2 accounts to be used for Auto-Judging. The assignment of Judge accounts in an auto-judging section in a contest.yaml file has the same effect as assigning Auto-Judges in the PC2 Admin.

Example:

auto-judging:
  - account: JUDGE
     site: 1
     number: 2
     letters: A
     enabled: yes

  - account: JUDGE
     number: 4,5,6
     letters: B,C,D

  - account: JUDGE
     site: 2
     number: all
     letters: B,C,D

  - account: JUDGE
     site: 1
     number: 1,3
     letters: F
     enabled: no

The following keywords may appear within each language item in a list of languages:

Language example using CLICS format:

languages:
  - name: C++
    compiler: /usr/bin/g++  
    compiler-args: -O2 -Wall -o a.out -static {files} 

  - name: Java
    compiler: /usr/bin/javac
    compiler-args: -O {files}
    runner: /usr/bin/java
    runner-args: 

Language example using PC² format:

languages:
  - name: 'C++'
    active: true
    compilerCmd: 'g++ -g -O2 -static -std=gnu++11 {:mainfile}'
    exemask: 'a.out'
    execCmd: './a.out'

  - name: 'Java'
    active: true
    compilerCmd: 'javac -encoding UTF-8 -sourcepath . -d . {:mainfile}'
    exemask: '{:basename}.class'
    execCmd: 'java -Xss8m -Xmx1024m {:basename}'
    use-judge-cmd: true
    judge-exec-cmd: '/usr/bin/wrapper_java {:timelimit} {:basename}'

The following keywords may appear within each limits item in a list of limits settings.

Example:

limits:
  timeout: 5
  memory: 1024    # 1MB 
  output: 10      # 10KB

The following keywords may appear within each permissions item in a list of permissions settings for PC2 accounts. The assignment of permissions in a permissions section in a contest.yaml file has the same effect as assigning account permissions in the PC2 Admin "Edit Account" screen.

Example:

permissions:
  - account: TEAM
     number: 69,72, 80-89
     disable: DISPLAY_ON_SCOREBOARD

  - account: FEEDER
     number: 2-4
     enable: SHADOW_PROXY_TEAM, EDIT_RUN

The permissions which can be enabled/disabled are:

ADD_ACCOUNT, ADD_CATEGORY, ADD_GROUPS, ADD_JUDGEMENTS, ADD_LANGUAGE, ADD_NOTIFICATIONS, ADD_PROBLEM, ADD_SETTINGS, ADD_SITE, ALLOWED_TO_AUTO_JUDGE, ALLOWED_TO_FETCH_RUN, ALLOWED_TO_RECONNECT_SERVER, ANSWER_CLARIFICATION, BALLOON_EMAIL, BALLOON_OUTPUT_SHUTOFF, BALLOON_PRINT, CHANGE_PASSWORD, CLONE_PROFILE, DISPLAY_ON_SCOREBOARD, EDIT_ACCOUNT, EDIT_AJ_SETTINGS, EDIT_CATEGORY, EDIT_CLARIFICATION, EDIT_CONTEST_CLOCK, EDIT_EVENT_FEED, EDIT_GROUPS, EDIT_JUDGEMENTS, EDIT_LANGUAGE, EDIT_NOTIFICATIONS, EDIT_PERMISSIONS, EDIT_PLAYBACK, EDIT_PROBLEM, EDIT_RUN, EDIT_SITE, EXECUTE_RUN, EXPORT_PROFILE, EXTRACT_RUNS, FORCE_LOGOFF_CLIENT, FORCE_LOGOFF_SERVER, GENERATE_NEW_CLARIFICATION, GIVE_CLARIFICATION, GIVE_RUN, JUDGE_RUN, LOGIN, REJUDGE_RUN, RESET_CONTEST, RESPECT_EOC_SUPPRESSION, RESPECT_NOTIFY_TEAM_SETTING, SHADOW_PROXY_TEAM, SHUTDOWN_ALL_SERVERS, SHUTDOWN_SERVER, START_CONTEST_CLOCK, START_PLAYBACK, STOP_CONTEST_CLOCK, STOP_PLAYBACK, SUBMIT_CLARIFICATION, SUBMIT_RUN, SWITCH_PROFILE, TAKE_CLARIFICATION, TAKE_RUN, TEST_RUN, VIEW_ALL_JUDGEMENTS, VIEW_CLARIFICATIONS, VIEW_DELETED_RUNS, VIEW_EVENT_FEED, VIEW_PASSWORDS, VIEW_RUN_JUDGEMENT_HISTORIES, VIEW_RUNS, VIEW_SECURITY_ALERTS, VIEW_STANDINGS, VIEW_SUMMARY_ATTEMPTS_GRID.

The "Account Permissions Report" (available on the "Reports" tab in both the PC2 Server and the PC2 Admin) lists all of the current permissions for all accounts, showing both the permission name and a brief description of what that permission allows. The following is a sample (excerpt) from an Account Permissions Report:

** Account Permissions Report

Type: TEAM
  team1 (site 1) 
    1 LOGIN Login
    2 DISPLAY_ON_SCOREBOARD Shown on scoreboard displays
    3 TEST_RUN Test run
    4 VIEW_CLARIFICATIONS View Clarifications
    5 VIEW_RUNS View Runs
    6 SUBMIT_CLARIFICATION Submit a clarification
    7 SUBMIT_RUN Submit a run

The following keywords may appear within each problemset item in a list of problems. The short-name keyword is required; all others are optional.

Problemset example:

problemset:
  - letter:     A
    short-name: hello
    color:      Black
    rgb:        '#000000'

  - letter:     B
    short-name: sumit
    color:      White
    rgb:        '#FFFFFF'

  - letter:     C
    short-name: qanat
    color:      Cherry Red
    rgb:        '#df1328'

  - letter:     D
    short-name: microbus
    color:      Dark blue
    rgb:        '#0967db'

# Example to set FEEDER1 as team proxy (for use when using Shadow feature)
# set feeder1 as proxy
team-proxy-accounts:
  - account: FEEDER
    number: 1

# Shadow settings 
shadow-mode: true

ccs-url: https://open.kattis.com/clics-api/contests/nac22practice4/
ccs-login: INSERT_REMOTE_CCS_ACCOUNT_HERE
ccs-password: INSERT_PASSWORD_HERE
ccs-last-event-id:

# required to allow override of run id and elapsed time
ccs-test-mode: true

The following keywords may appear within each sites item in a list of sites in a multi-site contest:

Example:

sites:
 - number: 1
     name: Site 1
       IP: 203.0.113.0
     port: 50002
 password: siteone

 - number: 2
     name: Hawaii
       IP: 198.51.100.0
     port: 50002

The following keywords may appear within each validator item in a list of validator settings:

Examples:

# select the CLICS validator with the default options
validator:
   use-clics-validator: true

# select the CLICS validator, with the specified options
validator:
   use-clics-validator: true
   validatorCmd: '{:validator} {:infilename} {:ansfilename} {:feedbackdir}'
   validator_flags: case_sensitive space_change_sensitive float_absolute_tolerance 4.0011122 float_relative_tolerance 4.0042354

# select the PC2 "internal validator", specifying option 4: ignore white space on lines
validator:
   use-internal-validator: true
   validatorOption: 4

# for problem 'sumit' this will attempt to load the validator file at sumit/output_validators/customValidatorProgram003
validator: 
    validatorProg: 'customValidatorProgram003'

# for problem 'sumit' this will attempt to load the validator file at sumit/output_validators/try3/customValidatorProgram003
validator: 
    validatorProg: 'sumit/output_validators/try3/customValidatorProgram003'

# for problem 'sumit' this will attempt to load the validator file at /home/ubuntu/current/sumit/output_validators/try3/customValidatorProgram003
validator: 
    validatorProg: '/home/ubuntu/current/sumit/output_validators/try3/customValidatorProgram003'

# for problem 'bells' this will attempt to load a CLCIS-compatible custom validator program named 'validator' from the 'output_validators/bells_validator' folder
validator:
    validatorProg: 'config/bells/output_validators/bells_validator/validator'
    validatorCmd: '{:validator} {:infilename} {:ansfilename} {:feedbackdir} '
    usingInternal: false
    use-internal-validator: false
    use-clics-validator: false
    use-custom-validator: true
    use-clics-custom-validator-interface: true