Open Composerアプリケーション作成マニュアル

1. はじめに

すべてのアプリケーションの保存するためのディレクトリ名を./conf.yml.erbのapps_dirに設定します。ここでは、apps_dir: ./appsとします。
./apps以下にアプリケーション用のディレクトリを作成します。アプリケーション名をtestとした場合、./apps/testを作成します。
アプリケーションの説明ファイルであるmanifest.ymlとWebフォームの設定ファイルであるform.ymlを./apps/testの中に作成します。Embedded Ruby形式で作成する場合は、各ファイル名をmanifest.yml.erbとform.yml.erbにしてください。

1.1. manifest.ymlの設定

アプリケーションの説明を記述します。サンプルは下記の通りです。

name: Gaussian
category: Quantum Chemistry
icon: icon.png
description: |
  [Gaussian](https://gaussian.com) is a general purpose computational chemistry software package.
related_app:
  - OVITO: ovito.png
  - GrADS: bi-airplane-fill
  - ImageJ

name: アプリケーション名（このキーを省略した場合はディレクトリ名が代わりに用いられます）
category：カテゴリ名
icon: アイコンのための画像ファイルへのパス。URL、Bootstrapアイコン、Font Awesomeアイコンが利用可能です。Bootstrapアイコンの場合はicon: bi-airplane-fillのように記述します。Font Awesomeアイコンの場合はicon: fa-solid fa-gearのように記述します
description: アプリケーションの説明
related_app: Open OnDemandに登録されているアプリケーションを指定します。指定されたアプリケーションは履歴ページで表示されます。icon:と同様にアイコン画像などの指定が可能です。画像を指定しない場合、Open OnDemandで用意された画像が代わりに用いられます。

1.2. form.ymlの設定

form.ymlは、form、header、script、check、submitというセクションで構成されています。formとscriptは必須項目ですが、header、check、submitは省略できます。

次の図はform、header、scriptの担当範囲を示しています。formとheaderとscriptからジョブスクリプトが生成されます。headerを省略した場合は./lib/header.yml.erbが代わりに利用されます（ほとんどの場合、headerをform.ymlで定義する必要はないでしょう）。なお、左上のアプリケーションの説明などはmanifest.ymlの担当範囲です。checkはウィジットに設定された値のチェックをジョブの投入前に行います。submitはジョブを投入する際の前処理を定義します。

form.ymlのformとheaderでは下記のウィジットを利用して、ジョブスクリプトを生成します。

numberウィジット：数値の入力欄を表示します。
textウィジット：テキストの入力欄を表示します。
emailウィジット：Emailの入力欄を表示します。
selectウィジット：セレクトボックスを表示します。
multi_selectウィジット：複数の項目を選択できる入力欄を表示します。
radioウィジット：ラジオボタンを表示します。
checkboxウィジット：チェックボックスを表示します。
pathウィジット：Open Composerが動作しているサーバ上のファイルやディレクトリのパスを選択できる入力欄を表示します。

2.1. numberウィジット

数値の入力欄を表示します。下の例のnodesはウィジットの変数名です。labelはラベル、valueは初期値、minは最小値、maxは最大値、stepはステップ幅です。requiredは必須であるかどうかを指定します。helpは入力欄の下に表示されるヘルプメッセージです。ジョブスクリプトにはscriptセクション内の文字列が表示されます。scriptセクション内の#{nodes}は入力した値に置き換えられます。

form:
  nodes:
    widget:   number
    label:    Number of nodes (1 - 128)
    value:    4
    min:      1
    max:      128
    step:     1
    required: false
    help:     The larger the number, the longer the wait time.
    
script: |
  #SBATCH --nodes=#{nodes}

複数の数値の入力欄を表示することもできます。その場合、sizeで入力欄の数を記述し、各項目を配列形式で記述します。scriptセクションの#{time_1}と#{time_2}は、1つ目と2つ目に入力した値に置き換えられます。

form:
  time:
    widget: number
    label:  [ Maximum run time (0 - 24 h), Maximum run time (0 - 59 m) ]
    size:   2
    value:  [  1,  0 ]
    min:    [  0,  0 ]
    max:    [ 24, 59 ]
    step:   [  1,  1 ]
    
script: |
  #SBATCH --time=#{time_1}:#{time_2}:00

labelが配列形式ではない場合、一行の長いラベルを記述することができます。helpも同様です。

form:
  time:
    widget: number
    label:  Maximum run time (0 - 24 h, 0 - 59 m)
    size:   2
    value:  [  1,  0 ]
    min:    [  0,  0 ]
    max:    [ 24, 59 ]
    step:   [  1,  1 ]

ジョブスクリプト中の数値に対してゼロパディングを行いたい場合は関数zeropadding(key, digit)を用います。第1引数はキー、第2引数に数値を指定します。第2引数に指定した桁数に満たない場合、不足分を「0」で埋めます。

form:
  time:
    widget: number
    label:  [ Maximum run time (0 - 24 h), Maximum run time (0 - 59 m) ]
    size:   2
    value:  [  1,  0 ]
    min:    [  0,  0 ]
    max:    [ 24, 59 ]
    step:   [  1,  1 ]
    
script: |
  #SBATCH --time=#{time_1}:#{zeropadding(time_2, 2)}:00

項目ごとのラベルと一行の長いラベルを記述することもできます。配列形式の最初の要素に長いラベルを、2つ目の要素を配列形式で記述ください。

form:
  time:
    widget: number
    label:  [ Maximum run time, [0 - 24 h, 0 - 59 m] ]
    size:   2
    value:  [  1,  0 ]
    min:    [  0,  0 ]
    max:    [ 24, 59 ]
    step:   [  1,  1 ]

ジョブスクリプトのラベル（デフォルトは「Script Content」）を変更したい場合はscriptセクションでlabelを設定します。その場合、ジョブスクリプトはcontentに記述します。

script:
  label: Script Details
  content: |
    #SBATCH --nodes=#{nodes}

checkセクションでは、Rubyスクリプトと関数oc_assert(condition, message)を利用できます。この関数はconditionがfalseの場合、messageを出力して処理を終了します。下記のサンプルでは、24時間よりも大きな値が入力された状態で「Submit」ボタンをクリックすると、エラーメッセージが出力され、ジョブスクリプトの投入は行わないことを意味しています。formの変数を参照する場合は、@マークの後に変数名を記述してください。なお、すべての変数は文字列であることに注意ください。

checkセクションでは、下記の特殊な変数も利用できます。

@OC_APP_NAME: manifest.ymlのnameで定義しているアプリケーション名
@OC_APP_PATH: form.ymlが保存されているアプリケーションのパス（例：/Slurm）
@OC_SCRIPT_LOCATION: ヘッダで定義されているScript location
@OC_CLUSTER_NAME: ヘッダで定義されているCluster name（./conf.yml.erbでclusterが定義されている場合に有効）
@OC_SCRIPT_NAME: ヘッダで定義されているScript Name
@OC_JOB_NAME: ヘッダで定義されているJob Name

form:
  time:
    widget: number
    label:  [ Maximum run time (0 - 24 h), Maximum run time (0 - 59 m) ]
    size:   2
    value:  [  1,  0 ]
    min:    [  0,  0 ]
    max:    [ 24, 59 ]
    step:   [  1,  1 ]

script: |
  #SBATCH --time=#{time_1}:#{time_2}:00
  
check: |
  time_1 = @time_1.to_i
  time_2 = @time_2.to_i
  message = "Exceeded Time"
  oc_assert(time_1 != 24 || time_2 == 0, message)

submitセクションのサンプルは下記の通りです。シェルスクリプトで記述します。formの変数を参照する場合は、scriptセクションと同様に#{...}を利用してください。環境変数OC_SUBMIT_OPTIONSは、ジョブスクリプト投入コマンドに追加のオプションを設定できます。この処理の実行後に、ジョブスクリプトを投入するためのコマンド（例えば、sbatch #{OC_SUBMIT_OPTIONS} -J #{OC_JOB_NAME} #{OC_SCRIPT_NAME}）が実行されます。

submit: |
  #!/bin/bash

  cd #{OC_SCRIPT_LOCATION}
  mv #{OC_SCRIPT_NAME} param.conf
  genjs_ct param.conf > #{OC_SCRIPT_NAME}
  OC_SUBMIT_OPTIONS="-n 1"

2.2. textウィジット

テキストの入力欄を表示します。

form:
  comment:
    widget: text
    value: test
    label: Comment

script: |
  #SBATCH --comment=#{comment}

複数のテキストの入力欄を1行で表示することも可能です。

form:
  option:
    widget: text
    value: [ --comment=, test ]
    label: [ option, argument ]
    size: 2

script: |
  #SBATCH #{option_1}#{option_2}

2.3. emailウィジット

Emailの入力欄を表示します。Textウィジットとほぼ同じですが、「Submit」ボタンをクリックする際にメールアドレスの形式がチェックされます。

form:
  email:
    widget: email
    label:  Email
    
script: |
  #SBATCH --mail-user=#{email}

2.4. selectウィジット

セレクトボックスを表示します。optionsに選択肢を配列形式で記述します。配列の1つ目の要素はセレクトボックスの項目名です。scriptセクションの#{partition}はoptionsの2つ目の要素に置き換えられます。

form:
  partition:
    widget: select
    label: Partition
    value: Large Queue
    options:
      - [ Small Queue, small ]
      - [ Large Queue, large ]
      
script: |
  #SBATCH --partition=#{partition}

optionsの2つ目の要素は配列で記述することも可能です。下記の例では、scriptセクションの#{package_1}と#{package_2}は、配列の第1要素と第2要素に置き換えられます。後述のmulti_selectウィジット、radioウィジット、checkboxウィジットも同様です。

form:
  package:
    widget: select
    label: Select package
    options:
      - [ A, [packageA, a.out] ]
      - [ B, [packageB, b.out] ]

script: |
  module load #{package_1}
  mpiexec #{package_2}

2.5. multi_selectウィジット

複数の項目を選択できる入力欄を表示します。optionsに選択肢を配列形式で記述します。

form:
  load_modules:
    widget: multi_select
    label: Add modules
    value: mpi/mpich-x86_64
    options:
      - [ mpi/mpich-x86_64, mpi/mpich-x86_64 ]
      - [ mpi/openmpi-x86_64, mpi/openmpi-x86_64 ]
      - [ nvhpc/24.3, nvhpc/24.3 ]
      - [ nvhpc/24.5, nvhpc/24.5 ]
      - [ nvhpc/24.7, nvhpc/24.7 ]

script: |
  module load #{load_modules}

例えばmpi/mpich-x86_64とnvhpc/24.7を選択した場合は、ジョブスクリプトは下記のように複数行で表示されます。

module load mpi/mpich-x86_64
module load nvhpc/24.7

1行で表示したい場合は、separatorで区切り文字を設定します。

form:
  load_modules:
    widget: multi_select
    label: Add modules
    value: mpi/mpich-x86_64
    separator: " "
    options:
      - [ mpi/mpich-x86_64, mpi/mpich-x86_64 ]
      - [ mpi/openmpi-x86_64, mpi/openmpi-x86_64 ]
      - [ nvhpc/24.3, nvhpc/24.3 ]
      - [ nvhpc/24.5, nvhpc/24.5 ]
      - [ nvhpc/24.7, nvhpc/24.7 ]
      
script: |
  module load #{load_modules}

選択された項目が、separatorで設定した区切り文字を用いて1行で表示されます。

module load mpi/mpich-x86_64 nvhpc/24.7

valueに複数の初期値を設定する場合は、配列形式で記述します。

form:
  load_modules:
    widget: multi_select
    label: Add modules
    value: [mpi/mpich-x86_64, nvhpc/24.7 ]
    options:
      - [ mpi/mpich-x86_64, mpi/mpich-x86_64 ]
      - [ mpi/openmpi-x86_64, mpi/openmpi-x86_64 ]
      - [ nvhpc/24.3, nvhpc/24.3 ]
      - [ nvhpc/24.5, nvhpc/24.5 ]
      - [ nvhpc/24.7, nvhpc/24.7 ]

2.6. radioウィジット

ラジオボタンを表示します。selectウィジットとほぼ同じですが、direction: horizontalが設定可能です。direction: horizontalを設定すると水平方向にラジオボタンを表示できます。direction: horizontalがない場合は、垂直方向にラジオボタンを表示します。

form:
  jupyter:
    widget: radio
    label: Jupyter
    direction: horizontal
    value: Jupyter Lab
    options:
      - [ Jupyter Lab,      jupyterlab ]
      - [ Jupyter Notebook, jupyter    ]

script: |
  module load #{jupyter}

2.7. checkboxウィジット

チェックボックスを表示します。次のようにrequiredを配列形式で設定した場合、チェックボックスの各項目が必須かどうかを設定します。

form:
  mail_option:
    label: Mail option
    widget: checkbox
    direction: horizontal
    value: [ Fail of job,  When the job is requeued ]
    required: [ true, false, true, false, false ]
    options:
      - [ Beginning of job execution, BEGIN   ]
      - [ End of job execution,       END     ]
      - [ Fail of job,                FAIL    ]
      - [ When the job is requeued,   REQUEUE ]
      - [ All,                        ALL     ]

script: |
  #SBATCH --mail-type=#{mail_option}

次のようにrequiredが配列形式でない場合かつ値がtrueの場合、そのチェックボックスで1つ以上の項目がチェックがされていないとジョブの投入を行うことができない、という設定になります。

form:
  mail_option:
    label: Mail option
    widget: checkbox
    direction: horizontal
    value: [ Fail of job,  When the job is requeued ]
    required: true
    options:
      - [ Beginning of job execution, BEGIN   ]
      - [ End of job execution,       END     ]
      - [ Fail of job,                FAIL    ]
      - [ When the job is requeued,   REQUEUE ]
      - [ All,                        ALL     ]

script: |
  #SBATCH --mail-type=#{mail_option}

multi_selectウィジットと同様にseparatorの設定を行うことや、radioウィジットと同様にdirectionの設定を行うことができます。

2.8. pathウィジット

Open Composerが動作しているサーバ上のファイルやディレクトリのパスを選択できる入力欄を表示します。valueのデフォルトは${HOME}です。show_filesはファイルを表示するかどうかのフラグであり、デフォルトはtrueです。favoritesはショートカットパスを設定できます。

form:
  working_dir:
    widget: path
    label: Working Directory
    value: /work
    show_files: false
    favorites:
      - /fs/ess
      - /fs/scratch

script: |
  cd #{working_dir}

scriptセクション中で利用できる関数としてdirname(FILE_PATH)とbasename(FILE_PATH)を提供しています。ディレクトリ名とファイル名を含むパス名から、dirname()はディレクトリ部分を、basename()はファイル部分だけを返します。

form:
  input_file:
    widget: path
    label: Input file

script: |
  cd #{dirname(input_file)}
  mpiexec ./#{basename(input_file)}

3. Dynamic Form Widget

ウィジットの設定を動的に変更できます。select、radio、checkboxウィジットのoptionで設定します。

3.1. ウィジットの設定

次の例では、node_typeでMediumを選択すると、coresのラベルと最大値はNumber of Cores (1-8)と8になります。

form:
  node_type:
    widget: select
    label: Node Type
    options:
      - [ Small,  small ]
      - [ Medium, medium, set-label-cores: Number of Cores (1-8),  set-max-cores: 8  ]
      - [ Large,  large,  set-label-cores: Number of Cores (1-16), set-max-cores: 16 ]

  cores:
    widget: number
    label: Number of Cores (1-4)
    value: 1
    min: 1
    max: 4
    step: 1

number、text、emailにおいて複数の入力欄を作っていた場合、設定対象の入力欄の指定に_(num)を用います。次の例では、node_typeでGPUを選択すると、timeの1つ目の入力欄のラベルと最大値がMaximum run time hours (0 - 24)と24になります。

form:
  node_type:
    widget: select
    label: Node Type
    options:
      - [ 'Standard', '' ]
      - [ 'GPU',      '', set-label-time_1: Maximum run time (0 - 24h), set-max-time_1: 24 ]

  time:
    widget:  number
    label:   [ Maximum run time (0 - 72 h), Maximum run time (0 - 59 m) ]
    size:    2
    value:   [  1,  0 ]
    max:     [ 72, 59 ]
    min:     [  0,  0 ]
    step:    [  1,  1 ]

select、radio、checkboxの場合、設定対象のオプションの指定に1st element in optionsを用います。次の例では、node_typeでGPUを選択すると、enable_gpuのEnable GPUがチェックされます。

form:
  node_type:
    widget: select
    label: Node Type
    options:
      - [ 'Standard', '' ]
      - [ 'GPU',      '', set-value-enable_gpu: Enable GPU ]

  enable_gpu:
    widget: checkbox
    options:
      - [ Enable GPU, gpu ]

3.2. ウィジットの無効化

ウィジットとオプションを無効化・有効化します。optionsの各配列の第3要素以降に[disable|enable]-(KEY)[-(1st element in options)][_num]を指定します。

次の例ではclusterでFugakuを選択すると、node_typeのGPUのオプションとcuda_verのウィジットが無効化されます。キーを無効化された場合は、そのキーを利用しているscriptセクション中の行も削除されます。

form:
  cluster:
    widget: select
    label:  Cluster system
    options:
      - [ Fugaku,  fugaku, disable-node_type-GPU, disable-cuda_ver ]
      - [ Tsubame, tsubame ]

  node_type:
    widget: select
    label:  Node type
    options:
      - [ Standard, standard ]
      - [ GPU,      gpu      ]

  cuda_ver:
    widget: number
    label: CUDA version
    value: 12
    min: 12
    max: 14

script: |
  module load system/#{node_type}
  module load cuda/#{cuda_ver}

上の例のoptionsは下記のように記述することもできます。この場合、Tsubameを選択したときのみ、node_typeとcuda_verが有効になります。

options:
  - [ Fugaku,  fugaku ]
  - [ Tsubame, tsubame, enable-node_type-GPU, enable-cuda_ver ]

3.3. ウィジットの非表示化

ウィジットを非表示・表示します。optionsの各配列の第3要素以降に[hide|show]-(KEY)を指定します。

次の例では、hide_advanced_optionsをチェックするとcommentが非表示になります。無効化とは異なり、そのキーのウィジットが表示されないだけであり、そのキーを利用しているscriptセクションの行には影響しません。indentはWebフォームの左側にインデントを作成します。数値は1〜5が入力でき、数値が大きくなるほどインデント幅は大きくなります。

form:
  hide_advanced_option:
    widget: checkbox
    options:
      - [ 'Hide advanced option', '', hide-comment ]

  comment:
    widget: text
    label: Comment
    indent: 1

script: |
  #SBATCH --comment=#{comment}

次の例では、show_advanced_optionsをチェックするとcommentが表示されます。

form:
  show_advanced_options:
    widget: checkbox
    options:
      - [ 'Show advanced option', '', show-comment ]

  comment:
    widget: text
    label: Comment
    indent: 1

script: |
  #SBATCH --comment=#{comment}

4. 利用可能な組合せ

各ウィジットと利用可能なオプションとの組合せは下記の表の通りです。optionsのみは必須項目ですが、他の項目は省略可能です。

Widget	label, value, help, required, indent	options (Dynamic Form Widget)	size	separator	direction	min, max, step	show_files, favorites
number	OK		OK			OK
text, email	OK		OK
select	OK	OK (OK)
multi_select	OK	OK		OK
radio	OK	OK (OK)			OK
checkbox	OK	OK (OK)		OK	OK
path	OK						OK

5. ジョブスクリプトの非表示化

ジョブスクリプトを非表示化することができます。特殊な変数SCRIPT_CONTENTとDynamic Form Widgetのhide-とを下記のように組み合せて利用します（ERBを用いるため、ファイル名はform.yml.erbであることに注意ください）。

form:
  script_content:
    widget: checkbox
    value: "Hide script content"
    options:
      - [ "Hide script content", "", hide-<%= SCRIPT_CONTENT %> ]

チェックボックスを表示させずに、ジョブスクリプトを隠したい場合は、そのチェックボックスに対してhide-を設定します。

form:
  script_content:
    widget: checkbox
    value: "Hide script content"
    options:
      - [ "Hide script content", "", hide-<%= SCRIPT_CONTENT %>, hide-script_content ]

headerセクションを定義できます。ただし、lib/headers.yml.erbで定義されているウィジットは必ず同じ名前で定義してください。

下記の例は、定義されているウィジット（_script_locationと_script）に、ジョブスクリプトを隠す新しいウィジットscript_contentを追加しています。./conf.yml.erbでclusterが定義されている場合は、_cluster_nameの定義も必要です。

header:
  _script_location:
    widget:     path
    value:      <%= Dir.home %>
    label:      Script Location
    show_files: false
    required:   true

  _script:
    widget:   text
    size :    2
    label:    [ Script Name, Job Name ]
    value:    [ job.sh, "" ]
    required: [ true, false ]

  script_content:
    widget: checkbox
    value: "Hide script content"
    options:
      - [ "Hide script content", "", hide-<%= SCRIPT_CONTENT %> ]

7. サンプル

アプリケーションのサンプルは下記の通りです。

8. 補足

本ページのサンプルはすべてbashで記述されていますが、他のシェルも利用することができます。ただし、submitセクションだけはbashしか記述できません。
ウィジット名に利用できるのは英数字とアンダースコアのみです。また、数字とアンダースコアを先頭に用いることもできません。アプリケーションを保存するディレクトリ名も同様です。末尾がアンダースコア+数字のウィジット名（例：nodes_1）は、sizeの属性を持つウィジットの値を参照するときに衝突する可能性があるので注意ください。ただし、headerをform.ymlで定義する場合、lib/header.yml.erbで用いられているアンダースコアで始まるウィジット名（_script_locationと_script）は利用可能です。
optionsで2つ目の要素がない場合、1つ目の要素が代わりに用いられます。
scriptセクションにおいて、ある行で利用されている変数が値を持たない場合、その行は表示されません。ただし、その変数の先頭にコロンを付加する（例：#{:nodes}や#{basename(:input_file)}）と、その変数が値を持たなくても行は出力されます。
Open Composerがジョブスクリプトを投入するまでに行われる処理の順番は下記の通りです。
1. アプリケーションページで「Submit」ボタンがクリックされる
2. form.ymlのcheckセクションに記述されたスクリプトを実行（checkセクションがある場合）
3. form.ymlのsubmitセクションに記述されたスクリプトを実行（submitセクションがある場合）
4. ジョブスクリプトが投入される
一般ユーザ権限でOpen Composerの開発を行う場合、Open Composerを開発モードに設定すると便利です。エラーが発生した場合、Webブラウザのその原因が表示されます。./run.rbを下記のように編集してください。
```
#set :environment, :production
set :environment, :development
```