# チュートリアル：コンペに参加する🦎 OptHubにようこそ！このチュートリアルでは，進化計算コンペティションで使用する競技システムOptHubの使い方を学びます．これから実際にシステムを使ってコンペに参加し，例題を解いてみましょう！ **内容（所要時間：30分）** 1. インストールとアカウント登録 2. コンペの内容を確認する 3. 問題を解く 4. 結果を確認する 5. 発展的な内容以下の動画と文章にしたがって実際にプレイしてみましょう． ## 1. インストールとアカウント登録はじめに，コンペティション用クライアントプログラムをインストールし，アカウントを登録します． ### 1.1. ターミナルの起動以降の操作はすべてコマンドラインから行います．皆様の使い慣れたターミナルを起動してください．各OSで利用できるターミナルの例 - Windows - Power Shell - コマンドプロンプト - WSL, WSL2 - Cygwin, MinGW - Mac - iTerm - ターミナル - Linux - xterm - Gnome端末なんとスマートフォンでも参加できます！以下のアプリをストアからインストールし，起動してください． - Android - Termux - iPhone - a-Shell ### 1.2. Pythonのインストールクライアントを動かすにはPythonが必要です．お使いの環境にPythonがインストールされているか確認します． ``` $ python --version ``` Python 2.7以上またはPython 3.5以上がインストールされていれば，本節の以降の作業は不要です．要件を満たすPythonがインストールされていなければ，Pythonのインストールが必要です．WindowsでPower Shellまたはコマンドプロンプトを使用する方は，[Microsoft Store](https://www.microsoft.com/ja-jp/p/python-38/9mssztt1n39l?activetab=pivot:overviewtab)にアクセスして『入手』ボタンを押します．それ以外の方は，お使いのOSのパッケージマネージャからインストールします．インストールできたら，下記のコマンドで適切なバージョンが表示されることを確認してください． ``` $ python --version ``` ### 1.3. クライアントのインストール以下のコマンドでクライアントをインストールします． ``` $ pip install -U opthub-client-cli ``` 正常にインストールできれば，`opt`コマンドが追加されます．以下のコマンドでバージョンが表示されればインストール成功です． ``` $ opt --version ``` ### 1.4. アカウントを登録するアカウントを登録して，クライアントと連携します．クライアントの初回利用時にアカウント登録が要求されますので，試しに以下のコマンドを打ってみましょう． ``` $ opt status ``` 以下のメッセージが表示されるはずです． ``` ====================================================================== To activate Opt with your account: 1. On your browser, go to: https://opthub.us.auth0.com/activate 2. Enter the following code: RCLJ-WDWP 3. Sign up or sign in (if not yet). The code expires in 15 minutes. ====================================================================== Opt is waiting for your activation... ``` Optを使用するには，あなたのアカウントと関連付けて有効化する必要があります．メッセージの通り，ブラウザで下記URLにアクセスします．Optを実行しているマシンとは別のマシンやスマートフォンのブラウザを使ってアクセスしても構いません． [https://opthub.us.auth0.com/activate](https://opthub.us.auth0.com/activate) 以下の画面が表示され，認証コードの入力が求められます． ![](https://i.imgur.com/OFNOhOW.png) コマンドラインに表示されたコードを入力します（コードは人によって異なります）． ![](https://i.imgur.com/6mQYZ2g.png) 以下のようにログイン画面が表示されます．**所属組織のメールアドレス**でサインアップしてください． ==複数アカウントを防ぐため，必ず**所属組織のメールアドレス**を登録してください．GmailやiCloud等のフリーメールではコンペに参加できません．== ![](https://i.imgur.com/48wJoDY.png) 無事Optがあなたのアカウントに関連付けられ，利用できるようになりました． ![](https://i.imgur.com/ivR9PoU.png) コマンドラインに戻ってみましょう． ``` Opt is activated with your account: yourname@example.com. {"users_aggregate": {"aggregate": {"count": 6}}, "problems_aggregate": {"aggregate": {"count": 15}}, "indicators_aggregate": {"aggregate": {"count": 2}}, "competitions_aggregate": {"aggregate": {"count": 5}}, "matches_aggregate": {"aggregate": {"count": 2}}, "environments_aggregate": {"aggregate": {"count": 1}}, "solutions_aggregate": {"aggregate": {"count": 421}}} ``` こちらにもOptが有効化されたとのメッセージが出ています．続いて，先ほど実行したコマンド`opt status`の結果が表示されています．以降は自由にコマンドが使えるようになります． ## 2. コンペティションの内容を確認するさっそくコンペに参加してみましょう．本節はブラウザを使って進めます． 1つのコンペは**1つ以上**の問題から成ります．各ユーザは**すべての**問題を解く必要があります．それぞれの問題は，決められた回数（`budget`といいます）だけ解を送信したら終了です．このページの一番下に，このチュートリアルコンペで解くべき問題のリストがあります．問題リストを新しいタブで開くリストを見れば，このコンペでは **Example-1** と **Example-2** という2つの問題を解く必要があることが分かります． ## 3. 問題を解くではさっそく問題を解いていきます． ### 3.1. クライアントから解を送信するまずは手動で解を送信してみましょう． ``` $ opt submit --match=1 ``` 入力待ちになりました．以下のように入力します． ``` $ opt submit --match=1 [1,2] (Ctrl+D) ``` ==WindowsでPower Shellまたはコマンドプロンプトをお使いの方は`(Ctrl+D)`の代わりに`(Ctrl+Z)`を入力してください。== 解が送信されました．しばらく待っていると，評価値が返ってきます． ``` $ opt submit --match=1 [1,2] (Ctrl+D) {"id": 1, "objective": 5, "constraint": null, "score": 5, "info": null, "evaluation_error": null, "scoring_error": null} ``` 送信された解は，OptHubにて**評価**と**採点**が行われます．評価では，競技で使用されている**問題**によって目的関数値`objective`と制約関数値`constraint`が計算されます．競技**Example-1**では問題**sphere**を使用しているので解`[1,2]`の目的関数値は$f(1,2)=1^2+2^2=5$となります．実際，`objective`の値が`5`となっています．今回の問題は無制約なため，`constraint`は`null`になっています．採点では，競技で使用されている**指標**によってスコア`score`が計算されます．競技**Example-1**の指標は**best**なので，これまでに送信した解の最小目的関数値がスコアとなります．実際，`score`の値が目的関数値`5`と一致しています．もし評価や採点において何らかの追加情報があれば`info`に格納されます．評価でエラーが発生した場合は`evaluation_error`にエラーメッセージが格納されます．採点でエラーが発生した場合は`scoring_error`にエラーメッセージが格納されます．競技の`budget`で指定された回数まで解を採点できます．評価や採点でエラーとなった解は`budget`を消費しません．もう一つ解を送信してみます．今度はパイプを使って解を渡してみましょう． ``` $ echo [2,3] | opt submit --match=1 {"id": 2, "objective": 13, "constraint": null, "score": 5, "info": null, "evaluation_error": null, "scoring_error": null} ``` しばらくすると同様に評価値が返ってきました．`score`は通算の最小目的関数値です．最初に送信した解の目的関数値のほうが小さいので，その値になっています．さらにもう一つ解を送信してみます．今度はファイルを使って解を渡してみましょう． ``` $ echo [1,0] > solution.json $ opt submit --match=1 --solution=solution.json {"id": 3, "objective": 1, "constraint": null, "score": 1, "info": null, "evaluation_error": null, "scoring_error": null} ``` しばらくすると評価値が返ってきました．今回は目的関数の最小値を更新したので，`score`の値も更新されました．解の評価と採点には結構時間がかかりますね．今度は評価・採点を待たずに解を送信してみましょう． ``` $ echo [0,1] | opt submit --match=1 --no-wait ``` 何も表示されずにすぐに処理が戻りました．上記コマンドを続けて実行することで，複数の解を非同期に送信することができます．もう2つ送信してみましょう． ``` $ echo [2,2] | opt submit --match=1 --no-wait $ echo [1,1] | opt submit --match=1 --no-wait ``` 3つの解の評価・採点結果を取得してみましょう．少し待ってから以下のコマンドを実行します．`USER`にはあなたのユーザ名を入力してください． ``` $ opt list solutions --limit 3 --query "_and: [{match_id: {_eq: 1}}, {owner: {name: {_eq: USER}}}]" { "solutions": [ { "id": 4, "owner": { "name": "USER" }, "match_id": 1, "variable": [ 0, 1 ], "objective": 1, "constraint": null, "info": null, "score": 1, "evaluation_error": null, "scoring_error": null, "created_at": "2020-01-01T12:34:56.789012+00:00", "updated_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_started_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_finished_at": "2020-01-01T12:34:56.789012+00:00", "scoring_started_at": "2020-01-01T12:34:56.789012+00:00", "scoring_finished_at": "2020-01-01T12:34:56.789012+00:00" }, { "id": 5, "owner": { "name": "USER" }, "match_id": 1, "variable": [ 2, 2 ], "objective": 4, "constraint": null, "info": null, "score": 1, "evaluation_error": null, "scoring_error": null, "created_at": "2020-01-01T12:34:56.789012+00:00", "updated_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_started_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_finished_at": "2020-01-01T12:34:56.789012+00:00", "scoring_started_at": "2020-01-01T12:34:56.789012+00:00", "scoring_finished_at": "2020-01-01T12:34:56.789012+00:00" }, { "id": 6, "owner": { "name": "USER" }, "match_id": 1, "variable": [ 1, 1 ], "objective": 1, "constraint": null, "info": null, "score": 1, "evaluation_error": null, "scoring_error": null, "created_at": "2020-01-01T12:34:56.789012+00:00", "updated_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_started_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_finished_at": "2020-01-01T12:34:56.789012+00:00", "scoring_started_at": "2020-01-01T12:34:56.789012+00:00", "scoring_finished_at": "2020-01-01T12:34:56.789012+00:00" } ] } ``` 3つの解の評価・採点結果が取得できました．解の評価・採点結果の取得方法については，詳しくは4.2. これまでに送信した解を確認するをご覧ください．これで解を送信する方法が分かりました．このコマンドをプログラム内で実行するようにすれば，最適化ソルバで問題を解くことができます． ### 3.2. 最適化ソルバで問題を解く今度はプログラムを使って解いてみましょう．今回は[CMA-ES](https://ja.wikipedia.org/wiki/CMA-ES)という最適化アルゴリズムを使います．まずはCMA-ESのパッケージをインストールします． ``` $ pip install cma ``` プログラムは以下のように書きます．目的関数の中で`opt submit`を呼び出して解を送信し，評価結果を受信します． ```python # cmaes.py import json from subprocess import check_output import cma import numpy as np def objective(x): if isinstance(x, np.ndarray): x = x.tolist() # To jsonify an ndarray, convert it to a list json_x = json.dumps(x) # Convert a list into a JSON array stdout = check_output( # Run a command and get the output ["opt", "submit", "--match=1"], input=json_x, text=True, ) y = json.loads(stdout) # Convert a JSON string into dict print(y) return y["objective"] # Get the objective value es = cma.CMAEvolutionStrategy([0, 0], 0.5) es.optimize(objective) ``` 終了条件は書いていませんが，解の評価回数が`budget`に達すると`opt submit`がエラーを返すため自動的に終了します．作成した最適化プログラムを実行します． ``` $ python cmaes.py ``` **Example-1**の`budget`は100なので，100回評価すると終了します．もし終了条件に達する前に打ち切りたい場合は`Ctrl+C`を入力してください． ## 4. 結果を確認するこれまでに送信した解やそのスコアを確認してみましょう． ### 4.1. 競技の経過を確認する競技の順位は最後に送信した解のスコアで決まります（ただしエラーになった解は除きます）．どのようにスコアが改善されていったかを眺めてみましょう．競技の経過を確認するには`opt list progress`コマンドを使います． ``` $ opt list progress --query "_and: [{match_id: {_eq: 1}}, {user: {name: {_eq: USER}}}]" > progress.json ``` `--query`オプションにて競技`Example-1`（競技IDは`1`です）の自分（ユーザ名は`USER`とします）の経過のみを取得するように絞り込んでいます．サイズが大きいので，ファイルにリダイレクトしています． ==**注意：**`--query`を指定しないと公開されている全ユーザの全競技の経過を取得します．== ファイルの中身を表示してみます．読みやすいように`python -m json.tool`コマンドで整形しています． ``` $ cat progress.json | python -m json.tool { "progress": [ { "user": { "name": "USER" }, "match": { "id": 1, "competition_id": "tutorial", "name": "Example-1" }, "budget": 100, # 採点できる解の数 "submitted": 102, # これまでに送信した解の数 "evaluating": 0, # 現在評価中の解の数 "evaluated": 102, # これまでに評価した解の数 "scoring": 0, # 現在採点中の解の数 "scored": 100, # これまでに採点した解の数 "scores": [ 25.49, # 1個目の解のスコア null, # エラーとなった解のスコアはnull 17.88, # 2個目の解のスコア ... # 97行省略 0.012, # 100個目の解のスコア（この競技の最終スコア） null ], "created_at": "2020-01-01T12:34:56.789012+00:00", # 1個目の解の送信時刻 "updated_at": "2020-01-02T23:45:67.890123+00:00", # 最後の解の更新時刻 "evaluation_started_at": "2020-01-02T23:45:67.890123+00:00", # 最後の解の評価の開始時刻 "evaluation_finished_at": "2020-01-02T23:45:67.890123+00:00", # 最後の解の評価の終了時刻 "scoring_started_at": "2020-01-02T23:45:67.890123+00:00", # 最後の解の採点の開始時刻 "scoring_finished_at": "2020-01-02T23:45:67.890123+00:00" # 最後の解の採点の終了時刻 } ] } ``` `scores`の最後の有効値`0.012`がこの競技の最終スコアになります．最終スコアが最も小さい人がこの競技の1位となります． ### 4.2. これまでに送信した解を確認する送信した個々の解を眺めてみましょう．解を確認するには`opt list solutions`コマンドを使います． ``` $ opt list solutions --query "_and: [{match_id: {_eq: 1}}, {owner: {name: {_eq: USER}}}]" > solutions.json ``` `--query`オプションにて競技`Example-1`（競技IDは`1`です）の自分（ユーザ名は`USER`とします）の解のみを取得するように絞り込みます．サイズが大きいので，ファイルにリダイレクトしています． ==**注意：**`--query`を指定しないと公開されている全ユーザの全競技の解を取得します．== ファイルの中身を表示します．読みやすいように`python -m json.tool`コマンドで整形しています． ``` $ cat solutions.json | python -m json.tool { "solutions": [ { "id": 1, "owner": { "name": "USER" }, "match_id": 1, "variable": [ 1.54, 2.18 ], "objective": 14.34, "constraint": null, "info": null, "score": 14.34, "evaluation_error": null, "scoring_error": null, "created_at": "2020-01-01T12:34:56.789012+00:00", "updated_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_started_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_finished_at": "2020-01-01T12:34:56.789012+00:00", "scoring_started_at": "2020-01-01T12:34:56.789012+00:00", "scoring_finished_at": "2020-01-01T12:34:56.789012+00:00" }, ... { "id": 102, "owner": { "name": "USER" }, "match_id": 1, "variable": [ 1.54, 2.18 ], "objective": null, "constraint": null, "info": null, "score": null, "evaluation_error": "Out of budget: 101/100", "scoring_error": null, "created_at": "2020-01-01T12:34:56.789012+00:00", "updated_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_started_at": "2020-01-01T12:34:56.789012+00:00", "evaluation_finished_at": "2020-01-01T12:34:56.789012+00:00", "scoring_started_at": null, "scoring_finished_at": null } ] } ``` 配列`solutions`には解が送信した順番に入っています．これを見れば，それぞれの解の目的関数値や制約関数値，スコアなどが分かります． **Example-1**を解き終わったら，**Example-2**についてもステップ2～4を繰り返します．両方の問題を解き終われば本チュートリアルコンペは競技終了です． ### 4.3. （コンペ終了後）他人の解を取得するコンペが終わると全員の解が公開されます．先ほどのコマンドで他のユーザを指定すれば，他人の解を取得することができます．事後分析などにご活用ください． ## 5. 発展的な内容この節の内容は必須ではありません．より高度な機能を使いこなしたいユーザ向けです． ### 5.1. さらにクライアントを使いこなすじつはクライアントにはWebと同等の機能が備わってます．解を送受信するだけでなく，ユーザやコンペの一覧を取得したり，新しいコンペを登録したりもできます．コマンド一覧は以下で確認できます． ``` $ opt --help Usage: opt [OPTIONS] COMMAND [ARGS]... OptHub CLI client. Options: ... Commands: create Create an object. delete Delete an object. list List objects. mode Change the current CLI mode. organize Create a new competition on OptHub. status Show status. submit Submit a solution. update Update an object. ``` `list`はOptHubに登録された様々な情報を一覧するコマンドです． ``` $ opt list Usage: opt list [OPTIONS] COMMAND [ARGS]... List an object. Options: --help Show this message and exit. Commands: competitions List competitions on OptHub. indicators List indicators on OptHub. matches List matches on OptHub. problems List problems on OptHub. progress List progress on OptHub. solutions List solutions on OptHub. users List users on OptHub. ``` ユーザを表示してみます． ``` $ opt list users {"users": [{"name": "admin", "created_at": "2020-06-20T17:02:36.431958+00:00", "updated_at": "2020-06-20T17:02:36.431958+00:00"}, ...]} ``` どのサブコマンドも`--help`で使い方が表示されます．色々と遊んでみてください． ### 5.2. GraphQLで操作する OptHubのWebAPIは[Hasura GraphQL](https://hasura.io/)で実装されています．これを使いこなすと，CLIクライアントよりもさらに柔軟な操作ができます．GraphQLクエリを対話的に編集できるオンラインエディタ[Online GraphiQL](https://graphiql-online.com/)にアクセスして，以下のAPIエンドポイントURLを入力してください． OptHub APIエンドポイント：https://opthub-api.herokuapp.com/v1/graphql GraphQLとオンラインエディタの使い方は[Hasuraのドキュメント](https://hasura.io/learn/graphql/intro-graphql/graphql-queries/)をご覧ください．

Sort by
Match Example-1	Problem sphere	Indicator best	Budget 100	Leaderboard public	Created at 2 years ago	Updated at 5 months ago
Match Example-2	Problem sphere	Indicator best	Budget 1000000	Leaderboard public	Created at 2 years ago	Updated at 5 months ago

Important Dates

Matches