「TPS」：修訂間差異

出自TFcisWiki
跳至導覽 跳至搜尋
 
（未顯示同一使用者於中間所作的 42 次修訂）
行 1： 行 1：
TPS（Task Preparation System）是一套可以方便產生題目測試資料以及題本的工具，關於 TPS 可以參考以下的 Github Repo：
TPS（Task Preparation System）是一套可以方便產生題目測試資料以及題本的工具，關於 TPS 可以參考以下的 GitHub Repo：
* TPS Example：https://github.com/TNFSH-Programming-Contest/TPS-example
* TPS Example：https://github.com/TNFSH-Programming-Contest/TPS-example
* IOI 2017 TPS：https://github.com/ioi-2017/tps
* IOI 2017 TPS：https://github.com/ioi-2017/tps


{{Memo|本頁面主要使用 TNFSH-Programming-Contest/cms-environment-testing-problem<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem</ref> 的 pB<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB</ref> 作為範本。|}}
== 使用方式 ==

[[File:Icon tools.svg|20px]] 以下有此標誌的說明需要 CMS 系統管理員操作，出題者可忽略此說明。
[[File:Icon tools.svg|20px]] 以下有此標誌的說明需要 CMS 系統管理員操作，出題者可忽略此說明。


{{reflist-talk}}
=== 建立Github Repo ===

# 進入[https://github.com/TNFSH-Programming-Contest/tps-starter/generate tps-starter]。
== 資料夾結構 ==
=== 根目錄 ===
==== .github/workflows ====
GitHub 自動化流程設定檔。

==== pX ====
pA、pB 等{{slink||題目資料夾}}。

==== .problems.json ====
記錄{{slink||題目資料夾}}列表，供 GitHub Actions {{slink||自動建置}}使用，通常不應手動修改。

==== Makefile ====
[[File:Icon tools.svg|20px]] 匯入 CMS 的指令

==== README.md ====
主要在 GitHub 頁面上提供常用連結。

==== cover.tex ====
題本封面。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/cover.tex

==== template.tex ====
題本內文模板，通常無需修改。

=== 題目資料夾 ===
==== attachments ====
放在此處的所有檔案將會上傳到 CMS 上，供參賽者在題目敘述頁的「附件」，通常僅會在 pA 的附件放置{{slink||合併題本}}。

[[File:Crystal Clear action run.png|20px]] 本目錄內容通常由程式自動產生。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pA/attachments

==== gen ====
放置{{slink||產測資}}相關的所有檔案。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/gen

==== gen/manual ====
{{See also|#手產測資檔}}

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/gen/manual

==== gen/data ====
{{See also|#產測資指令}}

==== scripts ====
[[File:Crystal Clear action run.png|20px]] 本目錄保存 TPS scripts，不需修改。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/scripts

==== solution ====
{{See also|#標程}}

==== statement ====
題本相關檔案，包含原始碼、圖片、{{slink||建置題本}}產生的 PDF。

==== statement/index.md ====
{{See also|#題目敘述}}

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/statement/index.md

==== tests ====
{{slink||產測資}}後的檔案會存放於此，參見{{slink||建置測資}}。

[[File:Crystal Clear action run.png|20px]] 本目錄內容由程式自動產生，不應手動編輯。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/tests

==== validator ====
{{See also|#驗測資程式}}

==== problem.json ====
題目的相關設定，參見{{slink||競賽名稱|題目名稱|題目英文名稱|題目編號|記憶體限制|時間限制}}。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/problem.json

==== solutions-check.txt ====
所有標程的執行結果報告。

[[File:Crystal Clear action run.png|20px]] 本檔案由程式自動產生，不應手動編輯。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/solutions-check.txt

==== solutions.json ====
列出所有{{slink||標程}}及其 verdict，標記為 model_solution 的標程會用於{{slink||產測資}}。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/solutions.json

==== subtasks.json ====
列出所有的{{slink||子任務}}，及每個子任務所使用的{{slink||驗測資程式}}。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/subtasks.json

== 準備GitHub Repo ==
=== 建立GitHub Repo ===
# 進入 tps-starter。<ref>https://github.com/TNFSH-Programming-Contest/tps-starter</ref>
# 點擊 Use this template。<ref>直接連結：https://github.com/TNFSH-Programming-Contest/tps-starter/generate</ref>
# 填寫Repo資訊
# 填寫Repo資訊
#* Repository name 填入競賽英文名，例如「{{#time:Y}}NHSPC-TNFSH-Preliminary」。
#* Repository name 填入競賽英文名，例如「cms-environment-testing-problem」。
#* Description 填入競賽中文名，例如「{{#expr:{{#time:Y}}-1911}}學年度資訊學科能力競賽臺南一中校內初選」。
#* Description 填入競賽中文名，例如「CMS環境測試題目通用版」。
#* [[File:OOjs UI icon alert-destructive.svg|20px]] '''注意：'''可見度必須選擇 '''Private'''。
#* [[File:OOjs UI icon alert-destructive.svg|20px]] '''注意：'''可見度必須選擇 '''Private'''。
#* 點擊 Create repository from template。
#* 點擊 Create repository from template。
# （可選）若要將 GitHub Repo 更新傳送到 Discord，請參考 [https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks Intro to Webhooks – Discord] 操作。


{{reflist-talk}}
=== 建立新題目 ===

# 進入由 tps-starter 建立的 Github repo。
=== 建立題目資料夾 ===
此操作在每個競賽通常僅需執行 1 次。
# 進入由 tps-starter 建立的 GitHub repo。
# 點擊 Actions。
# 點擊 Actions。
# 在 Workflows 段落，點擊 New problem。
# 在 Workflows 段落，點擊 New problem。<ref>參考連結：https://github.com/TNFSH-Programming-Contest/TPS-example/actions/workflows/new-problem.yml</ref>
# 點擊 Run workflow，在 Folder name to create 輸入要建立的資料夾名稱。
# 點擊 Run workflow，在 How many problems in this contest? 輸入要建立的題目數量。
#* 如果已有 3 題，要再新增 1 題，直接輸入 4 即可，已建立的目錄會直接被略過。
#* 資料夾名稱僅供命題人員識別用，不會顯示給參賽者。如果已排定題目順序，可用[[#題目編號|「pA、pB...」命名]]，亦可用題目的[[#題目英文名稱|英文簡稱]]。
# 點擊藍色 Run workflow 按鈕。
# 點擊藍色 Run workflow 按鈕。
# 等待約 1 分鐘。
# 等待題目資料夾建立完成，約 1 分鐘。

{{reflist-talk}}

=== 刪除題目資料夾 ===
雖然這通常不會發生，但如果誤建過多題目等情況，需要刪除題目資料夾時，請務必完成以下所有操作：
# 刪除{{slink||題目資料夾}}。
# 從{{slink||.problems.json}}刪除題目編號。
# 從{{slink||Makefile}}刪除對應題目的匯入指令。
# 從{{slink||README.md}}刪除對應題目的連結。


== 準備TPS資料 ==
=== 競賽名稱 ===
=== 競賽名稱 ===
競賽名稱使用於：
競賽名稱使用於：
行 29： 行 142：
# 題本內文各頁的左上角。
# 題本內文各頁的左上角。


需寫入於：（範例為「CMS環境測試題目通用版 v1.1」）
需寫入於：
# {{slink||cover.tex}}。
# [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/e3baed3f28e5d855f0a208492a7211a84b037878/cover.tex#L16 cover.tex]。
# 各題目 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pA/problem.json problem.json] 的 contest_name 欄位。
# 各題目{{slink||problem.json}}的 contest_name 欄位。
# [[File:Icon tools.svg|20px]] CMS 管理系統的 Description 欄位。
# [[File:Icon tools.svg|20px]] CMS 管理系統的 Description 欄位。


=== 題目名稱 ===
=== 題目名稱 ===
題目名稱使用於：
題目名稱（problem title）使用於：
# CMS 競賽概況的題目列表。
# CMS 題目敘述頁面。
# CMS 題目敘述頁面。
# 題目標題（第一頁第一行）。
# 題目標題（第一頁第一行）。
# 該題目各頁右上角。
# 該題目各頁右上角。


需寫入於 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pA/problem.json problem.json] 的 title 欄位。
需寫入於{{slink||problem.json}}的 title 欄位，範例為「Piñata」。


=== 題目英文名稱 ===
=== 題目英文名稱 ===
題目英文名稱應足以讓所有命題人員識別個別題目即可，通常取自於中文題目名稱，並盡量僅使用一個英文詞，首字大寫，若需要兩個英文詞以上，則使用[[zhwiki:駝峰式大小寫|PascalCase]]。使用於：
題目英文名稱（problem name）應足以讓所有命題人員識別個別題目即可，通常取自於中文題目名稱，並盡量僅使用一個英文詞，首字大寫，若需要兩個英文詞以上，則使用[[zhwiki:駝峰式大小寫|PascalCase]]。使用於：
# CMS 參賽介面題目列表。
# CMS 競賽概況的題目列表。
# CMS 題目敘述。
# CMS 題目敘述。
# CMS 系統內部用來識別題目的 [[zhwiki:主鍵|Primary key]]。
# CMS 系統內部用來識別題目的 [[zhwiki:主鍵|Primary key]]。
#* [[File:Icon tools.svg|20px]] 由於同一 CMS 系統上的名稱無法重複，若與其他競賽題目衝突<ref>https://github.com/cms-dev/cms/issues/765</ref>，建議加上競賽名稱的英文縮寫作為前綴（例如「2022P-」）。
#* [[File:Icon tools.svg|20px]] 由於同一 CMS 系統上的名稱無法重複，若與其他競賽題目衝突<ref>https://github.com/cms-dev/cms/issues/765</ref>，建議加上競賽名稱的英文縮寫作為前綴（例如「2022P-」）。
# 可能作為 Github repo 內的題目資料夾名稱。
# 可能作為 GitHub repo 內的題目資料夾名稱。


需寫入於 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pA/problem.json problem.json] 的 name 欄位。
需寫入於{{slink||problem.json}}的 name 欄位，範例為「Pinata」。

{{reflist-talk}}


=== 題目編號 ===
=== 題目編號 ===
題目編號為 A, B, C... 的流水號，在決定題目順序後才會確定，使用於：
題目編號（problem label）為 A, B, C... 的流水號，在決定題目順序後才會確定，使用於：（範例為「B」）
# CMS 競賽概況的題目列表。
# 題目標題（第一頁第一行）。
# 題目標題（第一頁第一行）。
# 該題目各頁右上角。
# 該題目各頁右上角。
行 59： 行 176：


=== 記憶體限制 ===
=== 記憶體限制 ===
需寫入於 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pA/problem.json problem.json] 的 memory_limit 欄位，單位為MB。
需寫入於{{slink||problem.json}}的 memory_limit 欄位，單位為MB，範例為「512」MB。


=== 時間限制 ===
=== 時間限制 ===
需寫入於 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pA/problem.json problem.json] 的 time_limit 欄位，單位為秒。
需寫入於{{slink||problem.json}}的 time_limit 欄位，單位為秒，範例為「1.0」秒。


=== 標程 ===
=== 標程 ===
AC code（官方解法、標程等）需放置在 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pA/solution solution] 資料夾內，檔名無限制。同時將該檔名寫入 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pA/solutions.json solutions.json] ，格式請參照範本，verdict 必須標記為 model_solution。
AC code（又稱官方解法、標程等）需放置在{{slink||solution}}資料夾內，檔名無限制。同時將該檔名寫入{{slink||solutions.json}}，格式請參照範本，verdict 必須標記為 model_solution，範例檔名為「ac.cpp」<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/solution/ac.cpp</ref>。


其他 AC code 亦按照前述方式操作，verdict 必須標記為 correct。
其他 AC code 亦按照前述方式操作，verdict 必須標記為 correct。


其他類型的錯誤解法亦按照前述方式操作，verdict 標記方式請參考[https://github.com/ioi-2017/tps/tree/master/docs#solutionsjson 官方說明]及 [https://github.com/TNFSH-Programming-Contest/tps-task-templates/blob/93cff7e64a43f57450b26568194432e7b662be38/default/scripts/internal/invoke.py#L18 tps script]。
其他類型的錯誤解法亦按照前述方式操作，verdict 標記方式請參考官方說明<ref>https://github.com/ioi-2017/tps/tree/master/docs#solutionsjson</ref>及 tps script<ref>https://github.com/TNFSH-Programming-Contest/tps-task-templates/blob/93cff7e64a43f57450b26568194432e7b662be38/default/scripts/internal/invoke.py#L18</ref>。

{{reflist-talk}}


=== 產測資 ===
=== 產測資 ===
行 75： 行 194：


==== 手產測資檔 ====
==== 手產測資檔 ====
{{Memo|'''最佳實踐：'''僅在範例測資和 [[:zhwiki:en:Edge case|edge case]] 使用手產測資檔，其他使用產測程式。|}}
{{Memo|'''最佳實踐：'''
# 僅在 [[:zhwiki:en:Edge case|edge case]] 使用手產測資檔，其他使用產測程式。
手產測資檔應放置在 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/gen/manual gen/manual] 資料夾內，檔名無限制，但建議副檔名為 .in。
# 範例測資亦可隨機產生，若想要手動指定，亦可使用手產測資檔。
|}}

手產測資檔應放置在{{slink||gen/manual}}資料夾內，檔名無限制，但建議副檔名為 .in。

本範例有 2 個範例測資，其中一個使用手產測資檔 sample-01.in<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/gen/manual/sample-01.in</ref>，另一個為隨機測資。

{{reflist-talk}}


==== 產測資程式 ====
==== 產測資程式 ====
{{Memo|'''重要：'''產測資程式必須
{{Memo|'''重要：'''產測資程式必須
# 使用命令列參數讀入測資組及測資點，參見 [https://en.cppreference.com/w/cpp/language/main_function cppreference]、[https://stackoverflow.com/questions/3024197/what-does-int-argc-char-argv-mean stackoverflow]。
# 使用命令列參數讀入測資組及測資點<ref>[https://en.cppreference.com/w/cpp/language/main_function Main function - cppreference.com]</ref><ref>[https://stackoverflow.com/questions/3024197/what-does-int-argc-char-argv-mean c++ - What does int argc, char *argv&#x5B;&#x5D; mean? - Stack Overflow]</ref>。
# 使用[[zhwiki:stdout|標準輸出（stdout）]]，不可直接寫入檔案。
# 使用[[zhwiki:stdout|標準輸出（stdout）]]，不可直接寫入檔案。
# 執行一次僅輸出一筆測資。
# 執行一次僅輸出一筆測資。
# 使用 [https://codeforces.com/testlib testlib.h] 等設定亂數種子的方式，使得每次產生的測資都是相同的。
# 使用 testlib.h<ref>[https://codeforces.com/blog/entry/18291 Generators with testlib.h]</ref> 等設定亂數種子的方式，使得每次產生的測資都是相同的。
|notice}}
|inline:notice}}


產測資程式應放置在 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/gen gen] 資料夾內，檔名無限制。‎
產測資程式（generator）應放置在{{slink||gen}}資料夾內，檔名無限制。‎


以下說明請配合範例檔案 gen/gen.cpp<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/gen/gen.cpp</ref>。
假設以下程式碼編譯成檔名為 gen 的執行檔（在 Windows 上的 gen.exe），那麼可以在命令列使用：

* <code>gen pos 10</code> 隨機產生一個 1 ~ 10 之間的數字
使用 <syntaxhighlight lang="c++" inline>#include "testlib.h"</syntaxhighlight> 引入 testlib 函式庫。
* <code>gen pos 20</code> 隨機產生一個 1 ~ 20 之間的數字

* <code>gen neg 10</code> 隨機產生一個 -10 ~ -1 之間的數字
main 函數務必寫成 <syntaxhighlight lang="c++" inline>int main(int argc, char* argv[])</syntaxhighlight> 來接收命令列參數。
* <code>gen neg 20</code> 隨機產生一個 -20 ~ -1 之間的數字

<syntaxhighlight lang="c++" line>
在 main 函數的第一行使用 <syntaxhighlight lang="c++" inline>registerGen(argc, argv, 1);</syntaxhighlight> 將命令列參數作為亂數種子。
#include <bits/stdc++.h>

#include "testlib.h"
命令列參數會保存在 <syntaxhighlight lang="c++" inline>argv</syntaxhighlight> 內，可將其保存在 string 內： <syntaxhighlight lang="c++" inline>string task = argv[1];</syntaxhighlight>，或是使用 atoi<ref>https://en.cppreference.com/w/cpp/string/byte/atoi</ref> 等函數轉換為整數。例如範例中第一個參數用來判斷是第幾組測資，將其轉換為 <syntaxhighlight lang="c++" inline>int taskN</syntaxhighlight> 用於判斷。若為第一筆測資，測資範圍則為 87，若為其他測資，測資範圍則為 10^9。
using namespace std;

int main(int argc, char* argv[]) {
使用 <syntaxhighlight lang="c++" inline>rnd.next(-maxN, maxN)</syntaxhighlight> 來隨機產生範圍在 -maxN 到 maxN 之間的整數，保存在變數上用於之後輸出。
registerGen(argc, argv, 1);

string task = argv[1];
最後將產生的測資輸出。
int range = atoi(argv[2]);

if (task == "pos") {
{{Memo}} 由於 cout 中執行順序屬未定義行為，請勿將多個 rnd.next 合併在一個 cout 中使用，請分開 cout 或事先保存在變數上。
cout << rnd.next(1, range) << endl;
{| class="wikitable"
} else {
|-
cout << rnd.next(-range, -1) << endl;
| <syntaxhighlight lang="c++">
}
cout << rnd.next (1, n) << endl;
return 0;
}‎</syntaxhighlight>
</syntaxhighlight>
| {{Y}}
;程式碼說明
|-
* Line 5：將整個命名列參數註冊為亂數種子，照抄即可。
| <syntaxhighlight lang="c++">
* Line 6：可以將 argv 儲存在 string 變數，之後可用來判斷。
cout << rnd.next (1, n) << " " << rnd.next (1, n) << endl;
* Line 7：如果有需要轉成整數或其他型態，可以使用 atoi 等函數轉型。
</syntaxhighlight>
* Line 8：判斷測資點。
| {{N}} 未定義行為
* Line 9：隨機產生 1 ~ range 之間的數字。
|-
* Line 11：隨機產生 -range ~ -1 之間的數字。
| <syntaxhighlight lang="c++">
cout << rnd.next (1, n) << " ";
cout << rnd.next (1, n) << endl;
</syntaxhighlight>
| {{Y}}
|-
| <syntaxhighlight lang="c++">
int a = rnd.next (1, n), b = rnd.next (1, n);
cout << a << " " << b << endl;
</syntaxhighlight>
| {{Y}}
|}

完成產測資程式後，編譯成檔名為 gen 的執行檔（在 Windows 上的 gen.exe），在命令列使用：
* <code>gen 1</code> 會隨機產生 4 個 -87 ~ 87 之間的數字（格式參見題目敘述）
* <code>gen 2</code> 會隨機產生 4 個 -10^9 ~ 10^9 之間的數字

{{reflist-talk}}


==== 產測資指令 ====
==== 產測資指令 ====
產測資指令應放置在 [https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/gen/data gen/data]。‎
產測資指令應放置在{{slink||gen/data}}，以下說明請配合範例。‎


每一個測資點以 @subtask 接測資點代號為開頭，這個測資點代號亦會使用在[[#子任務配分]]。
每一個測資點以 @subtask 接測資點代號為開頭，這個測資點代號亦會使用在{{slink||子任務}}。


接下來每個測資點可以有多筆測資，每筆測資可以使用手產測資檔，也可使用產測資程式。
接下來每個測資點可以有多筆測資，每筆測資可以使用手產測資檔，也可使用產測資程式。
* 使用手產測資檔則為 manual 接續放在 gen/manual 資料夾內的測資檔名。
* 使用手產測資檔則為 manual 接續放在{{slink||gen/manual}}資料夾內的測資檔名。
* 使用產測資程式則為呼叫在命令列中的指令。
* 使用產測資程式則為呼叫在命令列中的指令。


範例中第一行為 @subtask samples 為範例測資（samples 為固定名稱不可更改），包含一個手動測資檔 sample-01.in<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/gen/manual/sample-01.in</ref>。
<syntaxhighlight lang="text" line>
{{Memo|'''重要：'''將範例測資作為配分為 0 的第一筆測資點，名稱為 samples。|}}
@subtask samples
manual example-1.in


範例中除了範例測資外，共有 2 個測資點，名稱分別為 small 跟 all。兩個測資點都包含 5 筆自動測資。
@subtask positive
gen pos 20 test1-1
gen pos 20 test1-2


{{Memo}} 如果呼叫產測程式，但在指令中輸入了兩行一模一樣的內容，那麼這兩個測資就會相同（在設定亂數種子的情況下）。
@subtask negative

gen neg 30 test2-1
{| class="wikitable"
gen neg 30 test2-2
|-
| <syntaxhighlight lang="text">
@subtask small
gen 1
gen 1
gen 1
</syntaxhighlight>
| {{N}} 會產生 3 筆相同測資
|-
| <syntaxhighlight lang="text">
@subtask small
gen 1 1
gen 1 2
gen 1 3
</syntaxhighlight>
| {{Y}}
|-
| <syntaxhighlight lang="text">
@subtask small
gen 1 pewfw
gen 1 qrewx
gen 1 xckxk
</syntaxhighlight>
</syntaxhighlight>
| {{Y}}
|}


如果呼叫產測程式，但在指令中輸入了兩行一模一樣的內容，那麼這兩個測資就會相同（在設定亂數種子的情況下），因此通常會在後面放上隨機文字作為亂數種子的一部分，亦可透過更換亂數種子來重新產生測資，隨機文字可使用 [https://www.random.org/strings/ Random String Generator] 產生。
因此通常會在後面放上隨機文字作為亂數種子的一部分，亦可透過更換亂數種子來重新產生測資，隨機文字可使用線上工具<ref>例如 [https://www.random.org/strings/ Random String Generator]</ref>產生。


{{Memo|'''小技巧：'''
{{Memo|'''小技巧：'''
行 145： 行 311：
# 若需要 edge case，使用手產測資檔。
# 若需要 edge case，使用手產測資檔。
|}}
|}}

{{reflist-talk}}


=== 驗測資程式 ===
=== 驗測資程式 ===
{{Quote
| 如果你寫了一個程式解題的問題，並準備好了測試資料，那麼你將可能會遇到一個恐怖的經驗：測試資料是無效的！（即測試資料並未符合題目所規定的限制），例如超過了範圍上限、你的圖實際上沒有連通、或是你的圖不是一棵樹……你很可能會有這種經驗，就算是有經驗的出題者也可能有時會出錯（知名案例像是 ACM ICPC World final 2007）。
| 翻譯自 [https://codeforces.com/blog/entry/18426 Codeforces 上對於 Validator 的引言]。
}}
{{Memo|'''最佳實踐：'''撰寫驗測資程式來自動檢查測資範圍及其他條件是否有符合題目的規定，避免測資範圍錯誤。|}}
{{Memo|'''最佳實踐：'''撰寫驗測資程式來自動檢查測資範圍及其他條件是否有符合題目的規定，避免測資範圍錯誤。|}}


驗測資程式（validator）應該放置在{{slink||validator}}資料夾內，檔名無限制，並將檔名寫入{{slink||subtasks.json}}的 global_validators 或 subtasks 的 validators。
{{Quote|1=If you have written some programming problems, and have prepared test cases, you will probably experience the terrible feeling that some test cases may be invalid (meaning it does not agree with the constraints in problem statement): upper bound can be violated, your graph not satisfied connectivity requirements or is not at tree... It is reasonable to feel that way. Even experienced problem setters make mistakes sometimes (for example, in the prestigious ACM ICPC World final 2007).
|2=[https://codeforces.com/blog/entry/18426 Codeforces 上對於 Validator 的引言]。}}


本範例包含 2 個 validator。
=== 子任務配分 ===

validator.cpp <ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/validator/validator.cpp</ref> 用來驗證所有測資的範圍是否在 -10^9 ~ 10^9 內，故在{{slink||subtasks.json}}中設為 global_validators。

validator-small.cpp<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/validator/validator-small.cpp</ref> 僅用來測試第 2 筆測資（index = 1）範圍是否在 -87 ~ 87，在{{slink||subtasks.json}}中設定為測資 small 的 validators。

除了檢查範圍以外，readInt 等函數會回傳其數值，可以保存到變數上作進一步檢查，例如檢查陣列數值皆相異，檢查是否是圖、樹或其他資料結構。

更多資訊請參見 Codeforces 上的說明<ref>[https://codeforces.com/blog/entry/18426 Validators with testlib.h - Codeforces]</ref>。

{{Memo|'''小提示：'''驗測資程式僅檢查與解法無關的輸入資料限制，檢查是否 TLE、得部分分數屬於{{slink||標程}}的範圍。|}}

{{reflist-talk}}

=== 子任務 ===
子任務（subtask）設定於{{slink||subtasks.json}}，包含各子任務的配分、文字描述、{{slink||驗測資程式}}。以下說明請參考範例。

subtasks.json 最外層包含兩個 key：
* global_validators：在所有測資使用的{{slink||驗測資程式}}。
* subtasks：包含所有測資點。

subtasks 是一個 key-value pairs，key 與{{slink||產測資指令}}中設定的相同。value 包含以下 key-value pairs：
* index：流水號，出現在題本內的順序，從 0 開始；samples 必為 0。
* score：子任務分數；samples 必為 0。
* text：子任務描述，使用在題目描述內。
* validators：僅在該子任務使用的{{slink||驗測資程式}}。

{{reflist-talk}}


=== 題目敘述 ===
=== 題目敘述 ===
題目敘述（statement）的檔案放置於{{slink||statement/index.md}}。使用 [[zhwiki:Markdown|Markdown]] 及 [[zhwiki:XeTeX|XeTeX]] 語法。

結構由上到下依序為：
# {{slink||題目圖片}}
# {{slink||題目本文}}
# 輸入（說明），參見{{slink||輸入及輸出說明}}
# 輸出（說明），參見{{slink||輸入及輸出說明}}
# {{slink||輸入限制}}
# {{slink||子任務}}說明
# 範例輸入，參見{{slink||範例輸入及輸出}}
# 範例輸出，參見{{slink||範例輸入及輸出}}
# {{slink||提示}}

==== 題目圖片 ====
參見{{slink|題目敘述故事|插圖}}。

==== 題目本文 ====
參見[[題目敘述故事]]。

==== 輸入及輸出說明 ====
輸入輸出說明必須明確說明參賽者要遵守的格式。

應該以一行敘述測資中的一行所代表的資料，例如：
* 第一行有 1 個整數，代表接下來的測資數量。
* 第一行有 2 個整數，代表初始座標。

如果需要在其他地方（輸入說明的其他行、輸入限制、題目本文等）提到該變數，應賦予變數代號，例如：
* 第一行有 2 個整數 <math>V, E</math>，<math>V</math> 代表點的數量，<math>E</math> 代表邊的數量。
* 第一行有 1 個整數 <math>N</math>，代表有 <math>N</math> 個人。...（換行）...接下來有 <math>N</math> 行，每一行有 1 個整數代表該人的分數。
{{Memo|'''注意：'''同一個變數代號必須在該題目的任何地方皆相同，大小寫也必須相同。|}}

==== 輸入限制 ====
輸入限制用來告知參賽者測資的數值範圍限制，
{| class="wikitable"
|-
! 原始碼 !! 顯示結果
|-
| <syntaxhighlight lang="markdown">
- $1 \leq N \leq 100$
- $1 \leq M \leq N$
- $Y - X$ 必定為 2 個倍數
- 若 $A = 1$，則 $B > 0$
</syntaxhighlight>
|
* <math>1 \leq N \leq 100</math>
* <math>1 \leq M \leq N</math>
* <math>Y - X</math> 必定為 2 個倍數
* 若 <math>A = 1</math>，則 <math>B > 0</math>
|}

==== 子任務說明 ====
參見{{slink||子任務}}的操作，即會自動顯示於題本中。

==== 範例輸入及輸出 ====
範例輸入輸出必須與{{slink||產測資}}中設定的範例測資相同。

{{TOJ side box
|628|B. 國中會考分
}}
如果有多筆範例測資，標題應改命名為「範例輸入1、範例輸出1、範例輸入2、範例輸出2」等。
{{clear}}

{{TOJ side box
|631|E. 蓋歐格（單個範例附說明）
|632|F. 最小生成數（多個範例，僅有 1 個範例有說明）
|637|D. 本田小狼（有圖片的範例說明）
}}
如果有需要說明測資，可加上「範例說明」章節，詳細說明範例測資中的意義，亦可附圖說明。

{| class="wikitable"
|-
| style="vertical-align: top" |
* 範例輸入
* 範例輸出
| style="vertical-align: top" |
* 範例輸入1
* 範例輸出1
* 範例輸入2
* 範例輸出2
| style="vertical-align: top" |
* 範例輸入1
* 範例輸出1
* 範例說明1
* 範例輸入2
* 範例輸出2
|}

==== 提示 ====
{{TOJ side box
|335|F. 參訪者們
|509|C. Puyo
}}
如有需要，可以提供一些額外提示。如果內容為解題必須的，不應撰寫於提示，應寫於本文中。
{{clear}}

{{TOJ side box
|330|A. Piñata
|331|B. 尼莫西妮
|473|A. 好哈快捷鍵
}}
亦可撰寫與解題毫無幫助，但與題目故事相關的小知識。
{{clear}}

== [[zhwiki:組建自動化|自動建置]] ==
tps-starter<ref>https://github.com/TNFSH-Programming-Contest/tps-starter</ref> 使用了 GitHub Actions<ref>https://github.com/features/actions</ref>，對於建置題本和測資提供了簡易介面來執行構建，並包含自動建置、自動化測試等功能。

{{reflist-talk}}

=== 建置題本 ===
若要將題本編譯成 PDF，按照以下步驟操作：
# 進入 GitHub repo。
# 點擊 Actions。
# 在 Workflows 段落，點擊 Build pdf。<ref>參考連結：https://github.com/TNFSH-Programming-Contest/TPS-example/actions/workflows/build-pdf.yml</ref>
# 點擊 Run workflow，在 Problem labels to build 輸入{{slink||題目編號}}，例如「B」。
# 點擊藍色 Run workflow 按鈕。
# 等待 PDF 題本建置完成，約 2 分鐘。
# 可在對應題目的 statement/index.pdf 找到建置的 PDF。<ref>參考連結：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/statement/index.pdf</ref>

{{reflist-talk}}

=== 自動建置題本 ===
若題本已定稿，可開啟自動建置功能，之後對於相關檔案的修改都會觸發自動建置。刪除 statement/DISABLE_AUTO_BUILD<ref>https://github.com/TNFSH-Programming-Contest/tps-task-templates/blob/main/default/statement/DISABLE_AUTO_BUILD</ref> 即可開啟自動建置題本。

修改以下檔案將會觸發自動建置：
* scripts/statement.sh<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/scripts/statement.sh</ref>
* statement/*.jpg<ref>例如：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/statement/cover.jpg</ref>
* statement/index.md<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/statement/index.md</ref>
* template.tex<ref>https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/template.tex</ref>
* {{slink||cover.tex}}僅會構建 pA 的題本
* {{slink||problem.json}}的
** contest_name：{{slink||競賽名稱}}
** problem_label：{{slink||題目編號}}
** name：{{slink||題目英文名稱}}
** title：{{slink||題目名稱}}
** memory_limit：{{slink||記憶體限制}}
** time_limit：{{slink||時間限制}}
* {{slink||subtasks.json}}的 index、score、text ，參見{{slink||子任務}}。

{{reflist-talk}}

=== 合併題本 ===
在所有題目的題本皆完成，才進行合併題本，參考{{slink||建置題本}}的操作，在第 4 步驟的 Problem labels to build 輸入「+」，即會合併題本輸出於 pA/attachments/problems.pdf。<ref>參考連結：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pA/attachments/problems.pdf</ref>

{{reflist-talk}}

=== 建置測資 ===
若要自動產生測資 input、output、進行標程比較：
# 進入 GitHub repo。
# 點擊 Actions。
# 在 Workflows 段落，點擊 Build tests。<ref>參考連結：https://github.com/TNFSH-Programming-Contest/TPS-example/actions/workflows/build-tests.yml</ref>
# 點擊 Run workflow。
#* 若修改了{{slink||產測資}}程式，在 Problem labels to build inputs 輸入{{slink||題目編號}}，例如「B」，其他欄位不需重複輸入題號。將會自動建置輸入及輸出，若測資有變動，亦會自動測試標程。
#* 若僅修改了{{slink||標程}}，導致僅有輸出會變動，在 Problem labels to build outputs 輸入{{slink||題目編號}}，其他欄位不需重複輸入題號。將會自動建置輸出，若測資有變動，亦會自動測試標程。
#* 若僅要重新執行標程測試，在 Problem labels to run solutions 輸入{{slink||題目編號}}。
# 點擊藍色 Run workflow 按鈕。
# 等待測資建置完成。
# 可在對應題目的{{slink||tests}}資料夾找到建置的測資。標程測試則在{{slink||solutions-check.txt}}。

{{reflist-talk}}

=== 自動建置測資 ===
若產測資程式和標程皆已定稿，可開啟自動建置功能，之後對於相關檔案的修改都會觸發自動建置。刪除 gen/DISABLE_AUTO_BUILD<ref>https://github.com/TNFSH-Programming-Contest/tps-task-templates/blob/main/default/gen/DISABLE_AUTO_BUILD</ref> 即可開啟自動建置測資。

修改以下檔案將會觸發自動建置 input：
* {{slink||gen}}內的所有檔案

修改以下檔案將會觸發自動建置 output：
* 在{{slink||solutions.json}}內設定的 model_solution 對應檔案。請注意：若變更 model_solution 的目標檔案可能不會觸發自動建置。

修改以下檔案將會觸發自動建置 solutions：
* {{slink||solution}}內的所有檔案
* {{slink||solutions.json}}

{{reflist-talk}}

=== 跳過自動建置 ===
若已經啟用自動建置，但想在特定一筆 Commit 跳過自動建置，請在 Commit message 加上 <code>[no ci]</code>，例如：
<syntaxhighlight lang="text">pA Add wa.cpp

Add WA solution without swap
[no ci]
</syntaxhighlight>


完整說明參見 [https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs Skipping workflow runs - GitHub Docs]。
== 註解 ==
<references/>

於 2022年8月31日 (三) 11:23 的最新修訂

TPS（Task Preparation System）是一套可以方便產生題目測試資料以及題本的工具，關於 TPS 可以參考以下的 GitHub Repo：

本頁面主要使用 TNFSH-Programming-Contest/cms-environment-testing-problem[1] 的 pB[2] 作為範本。

Icon tools.svg 以下有此標誌的說明需要 CMS 系統管理員操作，出題者可忽略此說明。

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem
  2. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB

資料夾結構

根目錄

.github/workflows

GitHub 自動化流程設定檔。

pX

pA、pB 等§ 題目資料夾。

.problems.json

記錄§ 題目資料夾列表，供 GitHub Actions § 自動建置使用，通常不應手動修改。

Makefile

Icon tools.svg 匯入 CMS 的指令

README.md

主要在 GitHub 頁面上提供常用連結。

cover.tex

題本封面。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/cover.tex

template.tex

題本內文模板，通常無需修改。

題目資料夾

attachments

放在此處的所有檔案將會上傳到 CMS 上，供參賽者在題目敘述頁的「附件」，通常僅會在 pA 的附件放置§ 合併題本。

Crystal Clear action run.png 本目錄內容通常由程式自動產生。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pA/attachments

gen

放置§ 產測資相關的所有檔案。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/gen

gen/manual

參見： § 手產測資檔

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/gen/manual

gen/data

參見： § 產測資指令

scripts

Crystal Clear action run.png 本目錄保存 TPS scripts，不需修改。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/scripts

solution

參見： § 標程

statement

題本相關檔案，包含原始碼、圖片、§ 建置題本產生的 PDF。

statement/index.md

參見： § 題目敘述

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/statement/index.md

tests

§ 產測資後的檔案會存放於此，參見§ 建置測資。

Crystal Clear action run.png 本目錄內容由程式自動產生，不應手動編輯。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/tests

validator

參見： § 驗測資程式

problem.json

題目的相關設定，參見§§ 競賽名稱、​題目名稱、​題目英文名稱、​題目編號、​記憶體限制​和時間限制。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/problem.json

solutions-check.txt

所有標程的執行結果報告。

Crystal Clear action run.png 本檔案由程式自動產生，不應手動編輯。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/solutions-check.txt

solutions.json

列出所有§ 標程及其 verdict，標記為 model_solution 的標程會用於§ 產測資。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/solutions.json

subtasks.json

列出所有的§ 子任務，及每個子任務所使用的§ 驗測資程式。

範例：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/subtasks.json

準備GitHub Repo

建立GitHub Repo

  1. 進入 tps-starter。[1]
  2. 點擊 Use this template。[2]
  3. 填寫Repo資訊
    • Repository name 填入競賽英文名，例如「cms-environment-testing-problem」。
    • Description 填入競賽中文名，例如「CMS環境測試題目通用版」。
    • OOjs UI icon alert-destructive.svg 注意：可見度必須選擇 Private。
    • 點擊 Create repository from template。
  4. （可選）若要將 GitHub Repo 更新傳送到 Discord，請參考 Intro to Webhooks – Discord 操作。

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/tps-starter
  2. ↑ 直接連結：https://github.com/TNFSH-Programming-Contest/tps-starter/generate

建立題目資料夾

此操作在每個競賽通常僅需執行 1 次。

  1. 進入由 tps-starter 建立的 GitHub repo。
  2. 點擊 Actions。
  3. 在 Workflows 段落，點擊 New problem。[1]
  4. 點擊 Run workflow，在 How many problems in this contest? 輸入要建立的題目數量。
    • 如果已有 3 題，要再新增 1 題，直接輸入 4 即可，已建立的目錄會直接被略過。
  5. 點擊藍色 Run workflow 按鈕。
  6. 等待題目資料夾建立完成，約 1 分鐘。

參考資料

  1. ↑ 參考連結：https://github.com/TNFSH-Programming-Contest/TPS-example/actions/workflows/new-problem.yml

刪除題目資料夾

雖然這通常不會發生，但如果誤建過多題目等情況，需要刪除題目資料夾時，請務必完成以下所有操作：

  1. 刪除§ 題目資料夾。
  2. 從§ .problems.json刪除題目編號。
  3. 從§ Makefile刪除對應題目的匯入指令。
  4. 從§ README.md刪除對應題目的連結。

準備TPS資料

競賽名稱

競賽名稱使用於：

  1. CMS 參賽介面左上角。
  2. 題本封面第一行。
  3. 題本內文各頁的左上角。

需寫入於：（範例為「CMS環境測試題目通用版 v1.1」）

  1. § cover.tex。
  2. 各題目§ problem.json的 contest_name 欄位。
  3. Icon tools.svg CMS 管理系統的 Description 欄位。

題目名稱

題目名稱（problem title）使用於：

  1. CMS 競賽概況的題目列表。
  2. CMS 題目敘述頁面。
  3. 題目標題（第一頁第一行）。
  4. 該題目各頁右上角。

需寫入於§ problem.json的 title 欄位，範例為「Piñata」。

題目英文名稱

題目英文名稱（problem name）應足以讓所有命題人員識別個別題目即可，通常取自於中文題目名稱，並盡量僅使用一個英文詞，首字大寫，若需要兩個英文詞以上，則使用PascalCase。使用於：

  1. CMS 競賽概況的題目列表。
  2. CMS 題目敘述。
  3. CMS 系統內部用來識別題目的 Primary key。
    • Icon tools.svg 由於同一 CMS 系統上的名稱無法重複，若與其他競賽題目衝突[1]，建議加上競賽名稱的英文縮寫作為前綴（例如「2022P-」）。
  4. 可能作為 GitHub repo 內的題目資料夾名稱。

需寫入於§ problem.json的 name 欄位，範例為「Pinata」。

參考資料

  1. ↑ https://github.com/cms-dev/cms/issues/765

題目編號

題目編號（problem label）為 A, B, C... 的流水號，在決定題目順序後才會確定，使用於：（範例為「B」）

  1. CMS 競賽概況的題目列表。
  2. 題目標題（第一頁第一行）。
  3. 該題目各頁右上角。
  4. 該題目各頁頁碼處。

記憶體限制

需寫入於§ problem.json的 memory_limit 欄位，單位為MB，範例為「512」MB。

時間限制

需寫入於§ problem.json的 time_limit 欄位，單位為秒，範例為「1.0」秒。

標程

AC code（又稱官方解法、標程等）需放置在§ solution資料夾內，檔名無限制。同時將該檔名寫入§ solutions.json，格式請參照範本，verdict 必須標記為 model_solution，範例檔名為「ac.cpp」[1]。

其他 AC code 亦按照前述方式操作，verdict 必須標記為 correct。

其他類型的錯誤解法亦按照前述方式操作，verdict 標記方式請參考官方說明[2]及 tps script[3]。

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/tree/main/pB/solution/ac.cpp
  2. ↑ https://github.com/ioi-2017/tps/tree/master/docs#solutionsjson
  3. ↑ https://github.com/TNFSH-Programming-Contest/tps-task-templates/blob/93cff7e64a43f57450b26568194432e7b662be38/default/scripts/internal/invoke.py#L18

產測資

TPS 產測資方式與 Codeforces polygon 相同。測資可以使用手產測資檔案，亦可由程式亂數產生，亦可混合兩者。

手產測資檔

最佳實踐：
  1. 僅在 edge case 使用手產測資檔，其他使用產測程式。
  2. 範例測資亦可隨機產生，若想要手動指定，亦可使用手產測資檔。

手產測資檔應放置在§ gen/manual資料夾內，檔名無限制，但建議副檔名為 .in。

本範例有 2 個範例測資，其中一個使用手產測資檔 sample-01.in[1]，另一個為隨機測資。

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/gen/manual/sample-01.in

產測資程式

重要：產測資程式必須
  1. 使用命令列參數讀入測資組及測資點[1][2]。
  2. 使用標準輸出（stdout），不可直接寫入檔案。
  3. 執行一次僅輸出一筆測資。
  4. 使用 testlib.h[3] 等設定亂數種子的方式，使得每次產生的測資都是相同的。

產測資程式（generator）應放置在§ gen資料夾內，檔名無限制。‎

以下說明請配合範例檔案 gen/gen.cpp[4]。

使用 #include "testlib.h" 引入 testlib 函式庫。

main 函數務必寫成 int main(int argc, char* argv[]) 來接收命令列參數。

在 main 函數的第一行使用 registerGen(argc, argv, 1); 將命令列參數作為亂數種子。

命令列參數會保存在 argv 內，可將其保存在 string 內： string task = argv[1];，或是使用 atoi[5] 等函數轉換為整數。例如範例中第一個參數用來判斷是第幾組測資，將其轉換為 int taskN 用於判斷。若為第一筆測資，測資範圍則為 87，若為其他測資，測資範圍則為 10^9。

使用 rnd.next(-maxN, maxN) 來隨機產生範圍在 -maxN 到 maxN 之間的整數，保存在變數上用於之後輸出。

最後將產生的測資輸出。

注意 注意： 由於 cout 中執行順序屬未定義行為，請勿將多個 rnd.next 合併在一個 cout 中使用，請分開 cout 或事先保存在變數上。 

cout << rnd.next (1, n) << endl;

cout << rnd.next (1, n) << " " << rnd.next (1, n) << endl;
未定義行為 
cout << rnd.next (1, n) << " ";
cout << rnd.next (1, n) << endl;

int a = rnd.next (1, n), b = rnd.next (1, n);
cout << a << " " << b << endl;

完成產測資程式後，編譯成檔名為 gen 的執行檔（在 Windows 上的 gen.exe），在命令列使用：

  • gen 1 會隨機產生 4 個 -87 ~ 87 之間的數字（格式參見題目敘述）
  • gen 2 會隨機產生 4 個 -10^9 ~ 10^9 之間的數字

參考資料

  1. ↑ Main function - cppreference.com
  2. ↑ c++ - What does int argc, char *argv[] mean? - Stack Overflow
  3. ↑ Generators with testlib.h
  4. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/gen/gen.cpp
  5. ↑ https://en.cppreference.com/w/cpp/string/byte/atoi

產測資指令

產測資指令應放置在§ gen/data，以下說明請配合範例。‎

每一個測資點以 @subtask 接測資點代號為開頭，這個測資點代號亦會使用在§ 子任務。

接下來每個測資點可以有多筆測資，每筆測資可以使用手產測資檔，也可使用產測資程式。

  • 使用手產測資檔則為 manual 接續放在§ gen/manual資料夾內的測資檔名。
  • 使用產測資程式則為呼叫在命令列中的指令。

範例中第一行為 @subtask samples 為範例測資（samples 為固定名稱不可更改），包含一個手動測資檔 sample-01.in[1]。

重要：將範例測資作為配分為 0 的第一筆測資點，名稱為 samples。

範例中除了範例測資外，共有 2 個測資點，名稱分別為 small 跟 all。兩個測資點都包含 5 筆自動測資。

注意 注意： 如果呼叫產測程式，但在指令中輸入了兩行一模一樣的內容，那麼這兩個測資就會相同（在設定亂數種子的情況下）。 

@subtask small
gen 1
gen 1
gen 1
會產生 3 筆相同測資 
@subtask small
gen 1 1
gen 1 2
gen 1 3

@subtask small
gen 1 pewfw
gen 1 qrewx
gen 1 xckxk

因此通常會在後面放上隨機文字作為亂數種子的一部分，亦可透過更換亂數種子來重新產生測資，隨機文字可使用線上工具[2]產生。

小技巧：
  1. 透過命令列參數直接控制測資範圍，就不需要在產測資程式碼內判斷測資點。
  2. 發現不良的測資時，透過修改命令列參數的隨機文字來得到一筆新的隨機測資。
  3. 若需要 edge case，使用手產測資檔。

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/gen/manual/sample-01.in
  2. ↑ 例如 Random String Generator

驗測資程式

如果你寫了一個程式解題的問題，並準備好了測試資料，那麼你將可能會遇到一個恐怖的經驗：測試資料是無效的！（即測試資料並未符合題目所規定的限制），例如超過了範圍上限、你的圖實際上沒有連通、或是你的圖不是一棵樹……你很可能會有這種經驗，就算是有經驗的出題者也可能有時會出錯（知名案例像是 ACM ICPC World final 2007）。

——翻譯自 Codeforces 上對於 Validator 的引言。
最佳實踐：撰寫驗測資程式來自動檢查測資範圍及其他條件是否有符合題目的規定，避免測資範圍錯誤。

驗測資程式（validator）應該放置在§ validator資料夾內，檔名無限制，並將檔名寫入§ subtasks.json的 global_validators 或 subtasks 的 validators。

本範例包含 2 個 validator。

validator.cpp [1] 用來驗證所有測資的範圍是否在 -10^9 ~ 10^9 內，故在§ subtasks.json中設為 global_validators。

validator-small.cpp[2] 僅用來測試第 2 筆測資（index = 1）範圍是否在 -87 ~ 87，在§ subtasks.json中設定為測資 small 的 validators。

除了檢查範圍以外，readInt 等函數會回傳其數值，可以保存到變數上作進一步檢查，例如檢查陣列數值皆相異，檢查是否是圖、樹或其他資料結構。

更多資訊請參見 Codeforces 上的說明[3]。

小提示：驗測資程式僅檢查與解法無關的輸入資料限制，檢查是否 TLE、得部分分數屬於§ 標程的範圍。

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/validator/validator.cpp
  2. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/validator/validator-small.cpp
  3. ↑ Validators with testlib.h - Codeforces

子任務

子任務（subtask）設定於§ subtasks.json，包含各子任務的配分、文字描述、§ 驗測資程式。以下說明請參考範例。

subtasks.json 最外層包含兩個 key：

  • global_validators：在所有測資使用的§ 驗測資程式。
  • subtasks：包含所有測資點。

subtasks 是一個 key-value pairs，key 與§ 產測資指令中設定的相同。value 包含以下 key-value pairs：

  • index：流水號，出現在題本內的順序，從 0 開始；samples 必為 0。
  • score：子任務分數；samples 必為 0。
  • text：子任務描述，使用在題目描述內。
  • validators：僅在該子任務使用的§ 驗測資程式。

參考資料

題目敘述

題目敘述（statement）的檔案放置於§ statement/index.md。使用 Markdown 及 XeTeX 語法。

結構由上到下依序為：

  1. § 題目圖片
  2. § 題目本文
  3. 輸入（說明），參見§ 輸入及輸出說明
  4. 輸出（說明），參見§ 輸入及輸出說明
  5. § 輸入限制
  6. § 子任務說明
  7. 範例輸入，參見§ 範例輸入及輸出
  8. 範例輸出，參見§ 範例輸入及輸出
  9. § 提示

題目圖片

參見題目敘述故事 § 插圖。

題目本文

參見題目敘述故事。

輸入及輸出說明

輸入輸出說明必須明確說明參賽者要遵守的格式。

應該以一行敘述測資中的一行所代表的資料，例如：

  • 第一行有 1 個整數，代表接下來的測資數量。
  • 第一行有 2 個整數，代表初始座標。

如果需要在其他地方（輸入說明的其他行、輸入限制、題目本文等）提到該變數，應賦予變數代號，例如：

  • 第一行有 2 個整數 ， 代表點的數量， 代表邊的數量。
  • 第一行有 1 個整數 ，代表有 個人。...（換行）...接下來有 行，每一行有 1 個整數代表該人的分數。
注意：同一個變數代號必須在該題目的任何地方皆相同，大小寫也必須相同。

輸入限制

輸入限制用來告知參賽者測資的數值範圍限制，

原始碼 顯示結果 
- $1 \leq N \leq 100$
- $1 \leq M \leq N$
- $Y - X$ 必定為 2 個倍數
- 若 $A = 1$，則 $B > 0$
  • 必定為 2 個倍數
  • 若 ，則

子任務說明

參見§ 子任務的操作，即會自動顯示於題本中。

範例輸入及輸出

範例輸入輸出必須與§ 產測資中設定的範例測資相同。

可參考 TOJ 的題目
  • 628 ─ B. 國中會考分

如果有多筆範例測資，標題應改命名為「範例輸入1、範例輸出1、範例輸入2、範例輸出2」等。

可參考 TOJ 的題目
  • 631 ─ E. 蓋歐格（單個範例附說明）
  • 632 ─ F. 最小生成數（多個範例，僅有 1 個範例有說明）
  • 637 ─ D. 本田小狼（有圖片的範例說明）

如果有需要說明測資，可加上「範例說明」章節，詳細說明範例測資中的意義，亦可附圖說明。

  • 範例輸入
  • 範例輸出
  • 範例輸入1
  • 範例輸出1
  • 範例輸入2
  • 範例輸出2
  • 範例輸入1
  • 範例輸出1
  • 範例說明1
  • 範例輸入2
  • 範例輸出2

提示

可參考 TOJ 的題目
  • 335 ─ F. 參訪者們
  • 509 ─ C. Puyo

如有需要，可以提供一些額外提示。如果內容為解題必須的，不應撰寫於提示，應寫於本文中。

可參考 TOJ 的題目
  • 330 ─ A. Piñata
  • 331 ─ B. 尼莫西妮
  • 473 ─ A. 好哈快捷鍵

亦可撰寫與解題毫無幫助，但與題目故事相關的小知識。

自動建置

tps-starter[1] 使用了 GitHub Actions[2]，對於建置題本和測資提供了簡易介面來執行構建，並包含自動建置、自動化測試等功能。

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/tps-starter
  2. ↑ https://github.com/features/actions

建置題本

若要將題本編譯成 PDF，按照以下步驟操作：

  1. 進入 GitHub repo。
  2. 點擊 Actions。
  3. 在 Workflows 段落，點擊 Build pdf。[1]
  4. 點擊 Run workflow，在 Problem labels to build 輸入§ 題目編號，例如「B」。
  5. 點擊藍色 Run workflow 按鈕。
  6. 等待 PDF 題本建置完成，約 2 分鐘。
  7. 可在對應題目的 statement/index.pdf 找到建置的 PDF。[2]

參考資料

  1. ↑ 參考連結：https://github.com/TNFSH-Programming-Contest/TPS-example/actions/workflows/build-pdf.yml
  2. ↑ 參考連結：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/statement/index.pdf

自動建置題本

若題本已定稿，可開啟自動建置功能，之後對於相關檔案的修改都會觸發自動建置。刪除 statement/DISABLE_AUTO_BUILD[1] 即可開啟自動建置題本。

修改以下檔案將會觸發自動建置：

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/tps-task-templates/blob/main/default/statement/DISABLE_AUTO_BUILD
  2. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/scripts/statement.sh
  3. ↑ 例如：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/statement/cover.jpg
  4. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pB/statement/index.md
  5. ↑ https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/template.tex

合併題本

在所有題目的題本皆完成，才進行合併題本，參考§ 建置題本的操作，在第 4 步驟的 Problem labels to build 輸入「+」，即會合併題本輸出於 pA/attachments/problems.pdf。[1]

參考資料

  1. ↑ 參考連結：https://github.com/TNFSH-Programming-Contest/cms-environment-testing-problem/blob/main/pA/attachments/problems.pdf

建置測資

若要自動產生測資 input、output、進行標程比較：

  1. 進入 GitHub repo。
  2. 點擊 Actions。
  3. 在 Workflows 段落，點擊 Build tests。[1]
  4. 點擊 Run workflow。
    • 若修改了§ 產測資程式，在 Problem labels to build inputs 輸入§ 題目編號，例如「B」，其他欄位不需重複輸入題號。將會自動建置輸入及輸出，若測資有變動，亦會自動測試標程。
    • 若僅修改了§ 標程，導致僅有輸出會變動，在 Problem labels to build outputs 輸入§ 題目編號，其他欄位不需重複輸入題號。將會自動建置輸出，若測資有變動，亦會自動測試標程。
    • 若僅要重新執行標程測試，在 Problem labels to run solutions 輸入§ 題目編號。
  5. 點擊藍色 Run workflow 按鈕。
  6. 等待測資建置完成。
  7. 可在對應題目的§ tests資料夾找到建置的測資。標程測試則在§ solutions-check.txt。

參考資料

  1. ↑ 參考連結：https://github.com/TNFSH-Programming-Contest/TPS-example/actions/workflows/build-tests.yml

自動建置測資

若產測資程式和標程皆已定稿，可開啟自動建置功能，之後對於相關檔案的修改都會觸發自動建置。刪除 gen/DISABLE_AUTO_BUILD[1] 即可開啟自動建置測資。

修改以下檔案將會觸發自動建置 input：

修改以下檔案將會觸發自動建置 output：

  • 在§ solutions.json內設定的 model_solution 對應檔案。請注意：若變更 model_solution 的目標檔案可能不會觸發自動建置。

修改以下檔案將會觸發自動建置 solutions：

參考資料

  1. ↑ https://github.com/TNFSH-Programming-Contest/tps-task-templates/blob/main/default/gen/DISABLE_AUTO_BUILD

跳過自動建置

若已經啟用自動建置，但想在特定一筆 Commit 跳過自動建置，請在 Commit message 加上 [no ci]，例如： 

pA Add wa.cpp

Add WA solution without swap
[no ci]

完整說明參見 Skipping workflow runs - GitHub Docs。

取自「https://wiki.tfcis.org/index.php?title=TPS&oldid=410」