docs: tutorial section updated

issp-center-dev · Feb 27, 2024 · ac35ec2 · ac35ec2
1 parent 8bb89b4
commit ac35ec2
Show file tree

Hide file tree

Showing 6 changed files with 105 additions and 6 deletions.
diff --git a/docs/en/source/moller/command/index.rst b/docs/en/source/moller/command/index.rst
@@ -57,7 +57,7 @@ DESCRIPTION:
 
   - ``list_file``
 
-    specifies the file that contains list of job directories. If this file is not specified, the list will be obtained from the logfile of the batch job ``log_{task}.dat``.
+    specifies the file that contains list of job directories. If this file is not specified, the list will be obtained from the logfile of the batch job ``stat_{task}.dat``.
 
   - ``-o``, ``--output`` ``output_file``
 
@@ -91,5 +91,5 @@ DESCRIPTION:
 
 FILES:
 
-  When the programs are executed concurrently using the job script generated by ``moller``, the status of the tasks are written in log files ``log_{task}.dat``. ``moller_status`` reads these log files and makes a summary.
+  When the programs are executed concurrently using the job script generated by ``moller``, the status of the tasks are written in log files ``stat_{task}.dat``. ``moller_status`` reads these log files and makes a summary.
 
diff --git a/docs/en/source/moller/tutorial/basic.rst b/docs/en/source/moller/tutorial/basic.rst
@@ -78,7 +78,7 @@ A list of jobs is to be created. ``moller`` is designed so that each job is exec
 
 .. code-block:: bash
 
-  $ /usr/bin/ls -1d > list.dat
+  $ /usr/bin/ls -1d * > list.dat
 
 In this tutorial, an utility script ``make_inputs.sh`` is enclosed which generates datasets and a list file.
 
@@ -128,3 +128,34 @@ An example of the output is shown below:
 
 where "o" corresponds to a task that has been completed successfully, "x" corresponds to a failed task, "-" corresponds to a skipped task because the previous task has been terminated with errors, and "." corresponds to a task yet unexecuted.
 In the above example, the all tasks have been completed successfully.
+
+
+Rerun failed tasks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a task fails, the subsequent tasks within the job will not be executed.
+The following is an example of job status in which each task fails by 10% change.
+
+.. literalinclude:: ../../../../tutorial/moller/reference/status_failed.txt
+
+There, the jobs of dataset_0003 and dataset_0004 failed at task1, and the subsequent task2 and task3 were not executed. The other jobs were successful at task1, and proceeded to task2.
+In this way, each job is executed independently of other jobs.
+
+Users can rerun the failed tasks by submitting the batch job with the retry option.
+For SLURM job scheduler (e.g. used in ISSP system B), resubmit the job as follows:
+
+.. code-block:: bash
+
+  $ sbatch job.sh --retry list.dat
+
+For PBS job scheduler (e.g. used in ISSP system C), edit the job script so that the line ``retry=0`` is replaced by ``retry=1``, and resubmit the job.
+
+.. literalinclude:: ../../../../tutorial/moller/reference/status_retry.txt
+
+The tasks that have failed will be executed in the second run.
+In the above example, the task1 for dataset_0003 was successful, but the task2 failed.
+For dataset_0004, task1, task2, and task3 were successfully executed.
+For the jobs of datasets whose tasks have already finished successfully, the second run will not do anything.
+
+N.B. the list file must not be modified on the rerun. The jobs are managed according to the order of entries in the list file, and therefore, if the order is changed, the jobs will not be executed properly.
+
diff --git a/docs/ja/source/moller/command/index.rst b/docs/ja/source/moller/command/index.rst
@@ -58,7 +58,7 @@ moller_status
 
   - list_file
 
-    ジョブのリストを格納したファイルを指定します。指定がない場合は、バッチジョブから出力されるログファイル log_{task}.dat から収集します。
+    ジョブのリストを格納したファイルを指定します。指定がない場合は、バッチジョブから出力されるログファイル stat_{task}.dat から収集します。
 
   - -o, --output output_file
 
@@ -92,5 +92,5 @@ moller_status
 
 ファイル:
 
-  mollerで生成したジョブスクリプトを用いてプログラムを並列実行すると、実行状況がログファイル log_{task}.dat に出力されます。moller_status はこのファイルを集計し、読みやすい形式に整形します。
+  mollerで生成したジョブスクリプトを用いてプログラムを並列実行すると、実行状況がログファイル stat_{task}.dat に出力されます。moller_status はこのファイルを集計し、読みやすい形式に整形します。
 
diff --git a/docs/ja/source/moller/tutorial/basic.rst b/docs/ja/source/moller/tutorial/basic.rst
@@ -72,7 +72,7 @@ jobsセクションでは、タスクの処理内容を記述します。ジョ
 
 .. code-block:: bash
 
-  $ /usr/bin/ls -1d > list.dat
+  $ /usr/bin/ls -1d * > list.dat
 
 チュートリアルには、データセットとリストファイルを作成するユーティリティープログラムが付属しています。
 
@@ -115,3 +115,27 @@ mollerで生成したバッチジョブスクリプトをジョブスケジュ
 
 「o」は正常終了したタスク、「x」はエラーになったタスク、「-」は前のタスクがエラーになったためスキップされたタスク、「.」は未実行のタスクを示します。
 今回は全て正常終了していることがわかります。
+
+失敗したタスクを再実行する
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+タスクが失敗した場合、そのジョブ内の後続のタスクは実行されません。以下は、各タスクが 10% の確率で失敗するケースの実行例です。
+
+.. literalinclude:: ../../../../tutorial/moller/reference/status_failed.txt
+
+dataset_0003, dataset_0004 は task1 が失敗し、後続の task2, task3 は実行されていません。その他の dataset は task1 が成功し、次の task2 が実行されています。このように、各ジョブは他のジョブとは独立に実行されます。
+
+失敗したタスクを再実行するには、バッチジョブに retry のオプションをつけて再実行します。
+SLURMジョブスケジューラ (例: 物性研システムB) の場合は次のようにバッチジョブを投入します。
+
+.. code-block:: bash
+
+  $ sbatch job.sh --retry list.dat
+
+PBSジョブスケジューラ (例: 物性研システムC) の場合はジョブスクリプトを編集し、 ``retry=0`` の行を ``retry=1`` に変更して、バッチジョブを再投入します。
+
+.. literalinclude:: ../../../../tutorial/moller/reference/status_retry.txt
+
+エラーになったタスクのみ再実行されます。上記の例では、dataset_0003 は task1 が再実行され正常終了し、次の task2 の実行に失敗しています。dataset_0004 は task1, task2, task3 が正常に実行されています。task3 まで全て正常終了しているデータ・セットに対しては何も実行しません。
+
+なお、再実行の際にリストファイルは変更しないでください。リストファイル内の順番でジョブを管理しているため、変更すると正しく再実行されません。
diff --git a/docs/tutorial/moller/reference/status_failed.txt b/docs/tutorial/moller/reference/status_failed.txt
@@ -0,0 +1,22 @@
+| job          | task1   | task2   | task3   |
+|--------------|---------|---------|---------|
+| dataset_0001 | o       | o       | o       |
+| dataset_0002 | o       | x       | -       |
+| dataset_0003 | x       | -       | -       |
+| dataset_0004 | x       | -       | -       |
+| dataset_0005 | o       | o       | o       |
+| dataset_0006 | o       | o       | o       |
+| dataset_0007 | o       | x       | -       |
+| dataset_0008 | o       | o       | o       |
+| dataset_0009 | o       | o       | x       |
+| dataset_0010 | o       | o       | o       |
+| dataset_0011 | o       | o       | o       |
+| dataset_0012 | o       | o       | o       |
+| dataset_0013 | o       | x       | -       |
+| dataset_0014 | o       | o       | o       |
+| dataset_0015 | o       | o       | o       |
+| dataset_0016 | o       | o       | o       |
+| dataset_0017 | o       | o       | o       |
+| dataset_0018 | o       | o       | o       |
+| dataset_0019 | o       | o       | o       |
+| dataset_0020 | o       | o       | o       |
diff --git a/docs/tutorial/moller/reference/status_retry.txt b/docs/tutorial/moller/reference/status_retry.txt
@@ -0,0 +1,22 @@
+| job          | task1   | task2   | task3   |
+|--------------|---------|---------|---------|
+| dataset_0001 | o       | o       | o       |
+| dataset_0002 | o       | o       | x       |
+| dataset_0003 | o       | x       | -       |
+| dataset_0004 | o       | o       | o       |
+| dataset_0005 | o       | o       | o       |
+| dataset_0006 | o       | o       | o       |
+| dataset_0007 | o       | o       | o       |
+| dataset_0008 | o       | o       | o       |
+| dataset_0009 | o       | o       | o       |
+| dataset_0010 | o       | o       | o       |
+| dataset_0011 | o       | o       | o       |
+| dataset_0012 | o       | o       | o       |
+| dataset_0013 | o       | o       | o       |
+| dataset_0014 | o       | o       | o       |
+| dataset_0015 | o       | o       | o       |
+| dataset_0016 | o       | o       | o       |
+| dataset_0017 | o       | o       | o       |
+| dataset_0018 | o       | o       | o       |
+| dataset_0019 | o       | o       | o       |
+| dataset_0020 | o       | o       | o       |