From 57b3a23e49b339b0a9255714d184043273e1d777 Mon Sep 17 00:00:00 2001 From: Pavel Kunyavskiy Date: Sun, 19 Jan 2025 10:51:45 +0100 Subject: [PATCH] Added scoreboard_rules to contest_endpoint. This change address issue #150. It allows describing some small modifications to how the scoreboard is calculated, so downstream clients can do it consistently themselves if needed. --- Contest_API.md | 89 +++++++++++++++++++++++++++++++++++++++++--------- readme.md | 2 ++ 2 files changed, 76 insertions(+), 15 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index 123a0a3..2e1cd82 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -746,21 +746,21 @@ The following endpoints are associated with contest: Properties of contest objects: -| Name | Type | Description -| :--------------------------- | :-------------- | :---------- -| id | ID | Identifier of the current contest. -| name | string | Short display name of the contest. -| formal\_name | string ? | Full name of the contest. Defaults to value of `name`. -| start\_time | TIME ? | The scheduled start time of the contest, may be `null` if the start time is unknown or the countdown is paused. -| countdown\_pause\_time | RELTIME ? | The amount of time left when the countdown to the contest start was paused, if the contest countdown is paused, otherwise `null`. -| duration | RELTIME | Length of the contest. -| scoreboard\_freeze\_duration | RELTIME ? | How long the scoreboard is frozen before the end of the contest. Defaults to `0:00:00`. -| scoreboard\_thaw\_time | TIME ? | The scheduled thaw time of the contest, may be `null` if the thaw time is unknown or not set. -| scoreboard\_type | string | What type of scoreboard is used for the contest. Must be either `pass-fail` or `score`. -| penalty\_time | RELTIME | Penalty time for a wrong submission. Only relevant if scoreboard\_type is `pass-fail`. -| banner | array of FILE ? | Banner for this contest, intended to be an image with a large aspect ratio around 8:1. Only allowed mime types are image/\*. -| logo | array of FILE ? | Logo for this contest, intended to be an image with aspect ratio near 1:1. Only allowed mime types are image/\*. -| location | LOCATION ? | Location where the contest is held. +| Name | Type | Description +| :--------------------------- |:--------------------------| :---------- +| id | ID | Identifier of the current contest. +| name | string | Short display name of the contest. +| formal\_name | string ? | Full name of the contest. Defaults to value of `name`. +| start\_time | TIME ? | The scheduled start time of the contest, may be `null` if the start time is unknown or the countdown is paused. +| countdown\_pause\_time | RELTIME ? | The amount of time left when the countdown to the contest start was paused, if the contest countdown is paused, otherwise `null`. +| duration | RELTIME | Length of the contest. +| scoreboard\_freeze\_duration | RELTIME ? | How long the scoreboard is frozen before the end of the contest. Defaults to `0:00:00`. +| scoreboard\_thaw\_time | TIME ? | The scheduled thaw time of the contest, may be `null` if the thaw time is unknown or not set. +| scoreboard\_type | string | What type of scoreboard is used for the contest. Must be either `pass-fail` or `score`. +| scoreboard\_rules | Scoreboard Rules object ? | Describes how scoreboard is calculated. +| banner | array of FILE ? | Banner for this contest, intended to be an image with a large aspect ratio around 8:1. Only allowed mime types are image/\*. +| logo | array of FILE ? | Logo for this contest, intended to be an image with aspect ratio near 1:1. Only allowed mime types are image/\*. +| location | LOCATION ? | Location where the contest is held. The typical use of `countdown_pause_time` is when a contest director wishes to pause the countdown to the start of a contest. For example, this may occur because of technical issues or to make an announcement. When the contest countdown is paused, the value of `countdown_pause_time` should be set to the expected time remaining before the start of the contest after the pause is lifted. @@ -770,6 +770,65 @@ The `countdown_pause_time` may be changed to indicate the approximate delay unti Countdown is resumed by setting a new `start_time` and resetting `countdown_pause_time` to `null`. +In most cases downstream clients should use `/scoreboard` endpoint to get standings. If for some reason, it's not suitable, one +can use `scoreboard_rules` property to ensure that calculated scoreboard would be the same, or at least report potential +diverges. Scoreboard rule object must have a `string` property named `kind` and any additional properties, describing settings. +CCS should use one of the objects described in the [known scoring rules](#known-scoreboard-rules) section, when possible. + +#### Known scoreboard rules + +##### ICPC scoreboard rules + +`ICPC` kind is set of scoreboard calculation rules, where each problem is either solved or not, teams +are sorted based on number of solved problems, and penalty time as a tiebreaker. Can be used only with `pass-fail` +`scoreboard_type`. + +| Name | Type | Description +|:--------------------------------------|:---------| :---- +| kind | string | Should be eqaul to ICPC +| penalty\_time\_per\_wrong\_submission | RELTIME | Penalty time team gets for a wrong submission on a problem solved after that. Defaults to `00:20:00`. +| penalty\_mode | string | One of values: `sum`, `last`, `ignore`. Defaults to `sum` +| penalty\_precision | RELTIME | Precision of penatly calculation. Typically 1 minute or 1 second. Defatuls to `00:01:00`. +| penalty\_rounding | string | One of values: `down`, `up`, `closest`. Defaults to `down`. +| penalty\_rounding\_point | string | One of values: `each_submission`, `total`. Defaults to `each_submission`. + +`penalty_mode` describes how times of submissions results in final penalty: +* `sum` means that penalty time is the sum of submission times +* `last` means that penalty time is the time of the last submission +* `ignore` means that times are not used in penalty calculation, only wrong attempts matter. +* Additional values can be used, if none of the above fits, they should be interpreted in the same way as unknown rule kinds. + +`penalty_rounding` describes how submission times are rounded. +`down/up/closet` means, that each penalty time is rounded down/up/to the closest multiple of `penalty_precision` correspondingly. + +`penalty_rounding_point` describes at which moment of penalty calculation rounding happens. +* `each_submission` means, that each submission time are first rounded according to `penalty_rounding` rules, and then total penalty is computed according to `penalty_mode` rules +* `total` means, that penalty is first calculated according to `penalty_mode` rules as precise as given in `/submission` endpoint, and in the end total penalty is rounded according to `penalty_rounding` rules. + +The default values correspond to most classic ICPC rules, used on ICPC World Finals. Other values can be provided to describe different rules +deviations known to be used in the wild. + +##### IOI scoreboard rules + +`IOI` kind is set of scoreboard calculation rules, where on each problem you get some score, and +your rank is defined with total score for all problems, potentially using some time-based tie-break. +Can be used + +| Name | Type | Description +|:--------------------------------------|:----------| :---- +| kind | string | Should be eqaul to IOI +| use\_time\_tiebreak | boolean | If time tiebreak is used, or teams with same score just divide a rank. Defaults to `false` +| penalty\_time\_per\_wrong\_submission | RELTIME ? | Penalty time team gets for a wrong submission on a problem solved after that. Defaults to `00:00:00`. +| penalty\_mode | string ? | One of values: `sum`, `last`, `ignore`. Defaults to `last` +| penalty\_precision | RELTIME ? | Precision of penatly calculation. Typically 1 minute or 1 second. Defatuls to `00:00:01`. +| penalty\_rounding | string ? | One of values: `down`, `up`, `closest`. Defaults to `closest`. +| penalty\_rounding\_point | string ? | One of values: `each_submission`, `total`. Defaults to `total`. + +Penalty time properties have the same meaning as in ICPC rules above, except having different defaults. +They are only useful in case if `use_time_tiebreak` is true. + +The default values correspond to most classic IOI rules, used in most of the IOI school competitions. + #### Modifying contests Clients with the `contest_start` [capability](#capabilities) have the ability to diff --git a/readme.md b/readme.md index f2c12f0..29b5c58 100644 --- a/readme.md +++ b/readme.md @@ -32,6 +32,8 @@ These are the main changes made since the `2023-06` version: - Changed type of time related properties in scoreboard endpoint from `integer` to `RELTIME`. - Added `current` to judgements endpoint. - Added `country_subdivision` and `country_subdivision_flag` to organizations endpoint. +- Added `scoreboard_rules` instead of `penalty_time` to contests endpoint. + ## References