Deploy docs to main by GitHub Actions triggered by 51750cc

manual/main/en/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 743768690e909675b3addeeddd4f68be
+tags: 645f666f9bcd5a90fca523b33c5a78b7

manual/main/en/html/_sources/index.rst.txt

@@ -0,0 +1,20 @@
+.. HTP-tools documentation master file, created by
+   sphinx-quickstart on Fri Jun 30 11:02:31 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Moller Users Guide
+=====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   moller/index
+
+.. Indices and tables
+.. ==================
+
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`

manual/main/en/html/_sources/moller/about/index.rst.txt

@@ -0,0 +1,72 @@
+****************************************************************
+Introduction
+****************************************************************
+
+What is moller?
+----------------------------------------------------------------
+
+In recent years, the use of machine learning for predicting material properties and designing substances (known as materials informatics) has gained considerable attention.
+The accuracy of machine learning depends heavily on the preparation of appropriate training data.
+Therefore, the development of tools and environments for the rapid generation of training data is expected to contribute significantly to the advancement of research in materials informatics.
+
+moller is provided as part of the HTP-Tools package, designed to support high-throughput computations.
+It is a tool for generating batch job scripts for supercomputers and clusters, allowing parallel execution of programs under a series of computational conditions, such as parameter parallelism.
+Currently, it supports the supercomputers ohtaka (using the slurm job scheduler) and kugui (using the PBS job scheduler) provided by the Institute for Solid State Physics, University of Tokyo.
+
+License
+----------------------------------------------------------------
+
+The distribution of the program package and the source codes for moller follow GNU General Public License version 3 (GPL v3) or later.
+
+Contributors
+----------------------------------------------------------------
+
+This software was developed by the following contributors.
+
+-  ver.1.0-beta (Released on 2023/12/28)
+
+   -  Developers
+
+      -  Kazuyoshi Yoshimi (The Instutite for Solid State Physics, The University of Tokyo)
+
+      -  Tatsumi Aoyama (The Instutite for Solid State Physics, The University of Tokyo)
+
+      -  Yuichi Motoyama (The Instutite for Solid State Physics, The University of Tokyo)
+
+      -  Masahiro Fukuda (The Instutite for Solid State Physics, The University of Tokyo)
+
+      -  Tetsuya Fukushima (The National Institute of Advanced Industrial Science and Technology (AIST))
+
+      -  Kota Ido (The Instutite for Solid State Physics, The University of Tokyo)
+
+      -  Shusuke Kasamatsu (Yamagata University)
+
+      -  Takashi Koretsune (Tohoku University)
+
+   -  Project Corrdinator
+
+      -  Taisuke Ozaki (The Instutite for Solid State Physics, The University of Tokyo)
+
+
+Copyright
+----------------------------------------------------------------
+
+.. only:: html
+
+  |copy| *2023- The University of Tokyo. All rights reserved.*
+
+  .. |copy| unicode:: 0xA9 .. copyright sign
+
+.. only:: latex
+
+  :math:`\copyright` *2023- The University of Tokyo. All rights reserved.*
+
+This software was developed with the support of "Project for advancement of software usability in materials science" of The Institute for Solid State Physics, The University of Tokyo.
+
+Operating environment
+----------------------------------------------------------------
+
+moller was tested on the following platforms:
+
+- Ubuntu Linux + python3
+

manual/main/en/html/_sources/moller/appendix/index.rst.txt

@@ -0,0 +1,8 @@
+================================================================
+Extension guide
+================================================================
+
+How to extend ``moller`` for other systems
+----------------------------------------------------------------
+
+(TBA)

manual/main/en/html/_sources/moller/basic-usage.rst.txt

@@ -0,0 +1,150 @@
+Installation and basic usage
+================================================================
+
+**Prerequisite**
+
+  Comprehensive calculation utility ``moller`` included in HTP-tools requires the following programs and libraries:
+
+  - Python 3.x
+  - ruamel.yaml module
+  - tabulate module
+  - GNU Parallel (It must be installed on servers or compute nodes on which the job script is executed.)
+
+**Official pages**
+
+  - `GitHub repository <https://github.com/issp-center-dev/Moller>`_
+
+**Downloads**
+
+  moller can be downloaded by the following command with git:
+
+  .. code-block:: bash
+
+    $ git clone https://github.com/issp-center-dev/Moller.git
+
+**Installation**
+
+  Once the source files are obtained, you can install moller by running the following command. The required libraries will also be installed automatically at the same time.
+
+  .. code-block:: bash
+
+     $ cd ./Moller
+     $ python3 -m pip install .
+
+  The executable files ``moller`` and ``moller_status`` will be installed.
+
+**Directory structure**
+
+  ::
+
+     .
+     |-- LICENSE
+     |-- README.md
+     |-- pyproject.toml
+     |-- docs/
+     |   |-- ja/
+     |   |-- en/
+     |   |-- tutorial/
+     |-- src/
+     |   |-- moller/
+     |       |-- __init__.py
+     |       |-- main.py
+     |       |-- platform/
+     |       |   |-- __init__.py
+     |	     |   |-- base.py
+     |	     |   |-- base_slurm.py
+     |	     |   |-- base_pbs.py
+     |	     |   |-- base_default.py
+     |	     |   |-- ohtaka.py
+     |	     |   |-- kugui.py
+     |	     |   |-- pbs.py
+     |	     |   |-- default.py
+     |	     |   |-- function.py
+     |	     |   |-- utils.py
+     |	     |-- moller_status.py
+     |-- sample/
+
+**Basic usage**
+
+  ``moller`` is a tool to generate batch job scripts for supercomputers in which programs are run in parallel for a set of execution conditions using concurrent execution features.
+
+  #. Prepare job description file
+
+      First, you need to create a job description file in YAML format that describes the tasks to be executed on supercomputers. The details of the format will be given in File Format section of the manual.
+
+  #. Run command
+
+      Run moller program with the job description file, and a batch job script will be generated.
+
+      .. code-block:: bash
+
+          $ moller -o job.sh input.yaml
+
+  #. Run batch jobs
+
+      Transfer the generated batch job scripts to the supercomputer.
+      Prepare a directory for each parameter set, and create a list of the directory names in a file ``list.dat``.
+      Note that the list contains the relative paths to the directory where the batch job is executed, or the absolute paths.
+
+      Once the list file is ready, you may submit a batch job. The actual command depends on the system.
+
+      - In case of ISSP system B (ohtaka)
+
+        In ohtaka, slurm is used for the job scheduling system. In order to submit a batch job, a command ``sbatch`` is invoked with the job script as an argument. Parameters can be passed to the script as additional arguments; the name of list file is specified as a parameter.
+
+        .. code-block:: bash
+
+            $ sbatch job.sh list.dat
+
+        If the list file is not specified, ``list.dat`` is used by default.
+
+      - In case of ISSP system C (kugui)
+
+        In kugui, PBS is used for the job scheduling system. In order to submit a batch job, a command ``qsub`` is invoked with the job script. There is no way to pass parameters to the script, and thus the name of the list file is fixed to ``list.dat``.
+
+        .. code-block:: bash
+
+            $ qsub job.sh
+
+  #. Check the status of the calculation
+
+      After the job finishes, you may run the following command
+
+      .. code-block:: bash
+
+          $ moller_status input.yaml list.dat
+
+      to obtain a report whether the calculation for each parameter set has been completed successfully.
+
+
+  #. Retry/resume job
+
+        In case the job is terminated during the execution, the job may be resumed by submitting the batch job again with the same list file.
+        The yet unexecuted jobs (as well as the unfinished jobs) will be run.
+
+
+        - In case of ISSP system B (ohtaka)
+
+        .. code-block:: bash
+
+          $ sbatch job.sh list.dat
+
+        To retry the failed tasks, the batch job is submitted with ``--retry`` command line option.
+
+        .. code-block:: bash
+
+          $ sbatch job.sh --retry list.dat
+
+        - In case of ISSP system C (kugui)
+
+        For kugui, to retry the failed tasks, the batch job script should be edited so that ``retry=0`` is changed to be ``retry=1``.
+
+        .. code-block:: bash
+
+          $ qsub job.sh
+
+        Then, the batch job is submitted as above.
+
+**References**
+
+[1] `O. Tange, GNU Parallel - The command-Line Power Tool, ;login: The USENIX Magazine, February 2011:42-47. <https://www.usenix.org/publications/login/february-2011-volume-36-number-1/gnu-parallel-command-line-power-tool>`_

manual/main/en/html/_sources/moller/command/index.rst.txt

@@ -0,0 +1,95 @@
+Command reference
+================================================================
+
+moller
+----------------------------------------------------------------
+
+  Generate a batch job script for comprehensive calculation
+
+SYNOPSIS:
+
+  .. code-block:: bash
+
+    moller [-o job_script] input_yaml
+
+DESCRIPTION:
+
+  This program reads a job description file specified by input_yaml, and generates a batch job script. It takes the following command line options.
+
+  - ``-o``, ``--output`` ``job_script``
+
+    specifies output file name. This option supersedes the output_file parameter in the job description file. If no output file is specified, the result is written to the standard output.
+
+  - ``-h``
+
+    displays help and exits.
+
+moller_status
+----------------------------------------------------------------
+
+  Reports the status of comprehensive calculation jobs
+
+SYNOPSIS:
+
+  .. code-block:: bash
+
+    moller_status [-h] [--text|--csv|--html] [--ok|--failed|--skipped|--collapsed|--yet] [-o output_file] input_yaml [list_file]
+
+DESCRIPTION:
+
+  This program summarizes the status of tasks in jobs that are executed through the job scripts generated by moller, and outputs a report. The tasks are obtained from the job description file specified by ``input_yaml``. The list of jobs is read from the file specified by ``list_file``. If it is not provided, the job list is extracted from the log files.
+  The format of the output is specified by a command line option. The default is the text format. The output file is specified by the ``-o`` or ``--output`` option. If it is not specified, the output is written to the standard output.
+
+  - output formats
+
+    specifies the format of the output by one of the following options. If more than one option are specified, the program terminates with error. The default is the text format.
+
+    - ``--text``
+      displays in text format.
+    - ``--csv``
+      displays in CSV (comma-separated values) format.
+    - ``--html``
+      displays in HTML format.
+
+  - ``input_yaml``
+
+    specifies the job description file for ``moller``.
+
+  - ``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``.
+
+  - ``-o``, ``--output`` ``output_file``
+
+    specifies the output file name. If it is omitted, the result is written to the standard output.
+
+  - filter options
+
+    specifies the status of jobs to be displayed by one of the following options. All jobs are displayed by default.
+
+    - ``--ok``
+      displays only jobs whose tasks are all completed successfully.
+
+    - ``--failed``
+      displays jobs, any of whose tasks are failed with errors, skipped, or not performed.
+
+    - ``--skipped``
+      displays jobs, any of whose tasks are skipped.
+
+    - ``--yet``
+      displays jobs, any of whose tasks are not yet performed.
+
+    - ``--collapsed``
+      displays jobs, any of whose tasks are failed with errors.
+
+    - ``--all``
+      displays all jobs. (default)
+
+  - ``-h``
+
+    displays help and exits.
+
+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.
+