docs: add tutorial about how to use diffpy.batchpdfsuite

Author: Yuchen Xiao

.pre-commit-config.yaml

@@ -20,6 +20,7 @@ repos:
       - id: check-merge-conflict
       - id: check-toml
       - id: check-added-large-files
+        exclude: ^docs/examples/example\.zip$
   - repo: https://github.com/psf/black
     rev: 26.3.1
     hooks:
@@ -58,9 +59,10 @@ repos:
         additional_dependencies:
           - "prettier@^3.2.4"
         types: [yaml, markdown, json]
-  # ruff - An extremely fast Python linter and code formatter, written in Rust.
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.12
+  # docformatter - PEP 257 compliant docstring formatter
+  - repo: https://github.com/PyCQA/docformatter
+    rev: v1.7.8
     hooks:
-      - id: ruff-check
-        args: [--fix, --config=pyproject.toml]
+      - id: docformatter
+        additional_dependencies: [tomli]
+        args: [--in-place, --config, ./pyproject.toml]

cookiecutter.json

@@ -1,8 +1,8 @@
 {
   "author_names": "Yuchen Xiao, Simon Billinge",
   "author_emails": "yx2924@columbia.edu, sbillinge@ucsb.edu",
-  "maintainer_names": "Yuchen Xiao, Simon Billinge",
-  "maintainer_emails": "yx2924@columbia.edu, sbillinge@ucsb.edu",
+  "maintainer_names": "Simon Billinge",
+  "maintainer_emails": "sbillinge@ucsb.edu",
   "maintainer_github_usernames": "sbillinge",
   "contributors": "Yuchen Xiao and members of the diffpy.batchpdfsuite community",
   "license_holders": "contributors to the diffpy.batchpdfsuite community",

docs/examples/example.zip

@@ -8,72 +8,117 @@
 Getting started
 ================
 
-Here are some example templates provided to help you get started with writing your documentation. You can use these templates to create your own documentation.
+``diffpy.batchpdfsuite`` is a GUI for batch refinements of multiple PDF
+datasets. It is built on top of the
+`diffpy.srfit <https://github.com/diffpy/diffpy.srfit>`_ and
+`diffpy.apps <https://github.com/diffpy/diffpy.apps>`_ libraries.
 
-Reuse ``.rst`` files across multiple pages
-------------------------------------------
+This tutorial will guide you through the interface and usage of ``diffpy.batchpdfsuite``.
+For installation, please refer to the `README <https://github.com/diffpy/diffpy.batchpdfsuite#installation>`_
 
-Here is how you can reuse a reusable block of ``.rst`` files across multiple pages:
 
-.. include:: snippets/example-table.rst
+``diffpy.batchpdfsuite`` Interface
+----------------------------------
 
-.. warning::
+Here is the main interface of ``diffpy.batchpdfsuite``.
 
-    Ensure that the ``.rst`` file you are including is not too long. If it is too long, it may be better to split it into multiple files and include them separately.
+.. image:: img/bpdfsuite_gui.png
+   :width: 100%
+   :align: center
 
-Refer to a specific section in the documentation
-------------------------------------------------
+- *a* - **Settings**: To be implemented in the future for user settings.
+- *b* - **Log**: The panel containing the runtime output during the refinement process.
+- *c* - **Help**: To be implemented in the future for help and documentation.
+- *d* - **Experiment Data Panel**: The panel to load and display the loaded experiment data profile.
+- *e* - **Structure Data Panel**: The panel to load and display the structure file to be used for refinement.
+- *f* - **Control Panel**: The panel to control the refinement process.
+- *g* - **Task Panel**: The panel to view the status of the refinement tasks. Each task is created automatically when the corresponding experiment data is loaded.
+
+
+A Walkthrough Example
+----------------------
+
+Download the example data from  :download:`here <../examples/example.zip>`
+
+1. Unzip the downloaded file.
+2. Launch the ``diffpy.batchpdfsuite`` GUI.
+
+.. code-block:: bash
+
+    bpdfsuite
+
+
+3. Load the experiment data by clicking **Select Folder** in the **Experiment Data Panel** and choosing the ``data`` folder in the unzipped example data.
+
+Besides the experiment data profile, the refinement tasks will also be generated automatically.
+
+
+.. image:: img/bpdfsuite_gui_folder_selected.png
+   :width: 100%
+   :align: center
 
-You can use the ``ref`` tag to refer to a specific section in the documentation. For example, you can refer to the section below using the ``:ref:`` tag as shown :ref:`here <attach-image>`.
 
 .. note::
 
-    Please check the raw ``.rst`` file of this page to see the exact use of the ``:ref:`` tag.
+    The **Watch** option allows ``diffpy.batchpdfsuite`` to monitor the
+    selected folder in real time and create new refinement tasks automatically
+    when new experiment data is added to the folder. For simplicity, we will
+    not use this option in this tutorial.
 
-Embed your code snippets in the documentation
----------------------------------------------
+4. Load the structure file by clicking **Select File** in the **Structure Data Panel** and choosing ``refinement/Ni.cif``
 
-Here is how you can write a block of code in the documentation. You can use the ``code-block`` directive to write a block of code in the documentation. For example, you can write a block of code as shown below:
+To load the structure file, you need to set the name for the structure file to be
+referenced in the refinement process and then click **Add File**. You can also
+accepts the default name and click **Add File** directly.
 
-.. code-block:: bash
+5. Load the refinement settings. You can either
+    - Set **Type** to be ``Code`` and load the file ``refinement/template_2.py``. Or
+    - Set **Type** to be ``Macro`` and load the file ``refinement/single-phase.dp-in``
+
+.. note::
+
+    To learn how to write the Python script for ``diffpy.batchpdfsuite``, please
+    find the available parameters during the refinement process in the ``refinement/template_2.py``
+    file, and write the script according to your needs.
 
-    # Create a new environment, without build dependencies (pure Python package)
-    conda create -n <package_name>-env python=3.14 \
-        --file requirements/tests.txt \
-        --file requirements/conda.txt
+    To learn how to write the Diffpy macro file for ``diffpy.batchpdfsuite``, please
+    refer to the ``diffpy.apps``
+    `documentation <https://www.diffpy.org/diffpy.apps/getting-started.html#how-to-write-macro>`_
 
-    # Create a new environment, with build dependencies (non-pure Python package)
-    conda create -n <package_name>-env python=3.14 \
-        --file requirements/tests.txt \
-        --file requirements/conda.txt \
-        --file requirements/build.txt
 
-    # Activate the environment
-    conda activate <package_name>_env
+5. Check the ``Sequential`` option in the **Control Panel**.
 
-    # Install your package locally
-    # `--no-deps` to NOT install packages again from `requirements.pip.txt`
-    pip install -e . --no-deps
+.. note::
 
-    # Run pytest locally
-    pytest
+    The ``Sequential`` option allows the parameters in the following tasks to take
+    their previous task's refined values as their initial values.
+
+
+6. Set the sorting regex to be ``(\d+)(?=K)`` and click **Apply** in the **Task Panel**.
+
+Sequential refinement requires the tasks to be sorted in a specific order, i.e. for
+temperature-dependent refinement, the tasks should be sorted in ascending/descending order of temperature.
+
+.. note::
 
-    # ... run example tutorials
+    The sorting regex ``(\d+)(?=K)`` is used to extract the temperature value
+    from the experiment data file name. ``\d`` means any numeric digit,
+    and ``+`` means the previous character, ``\d`` in this case, should be repeated one or more times.
+    The ``(?=K)`` ensures that the previous matched group, ``(\d+)`` in this case,
+    must be followed by the character ``K``.
 
-.. _attach-image:
+    To learn more about regex, please refer to the `Python regex documentation <https://docs.python.org/3/library/re.html>`_
 
-Attach an image to the documentation
-------------------------------------
 
-Here is how you attach an image to the documentation. The ``/docs/source/img/scikit-package-logo-text.png`` example image is provided in the template.
+7. Select the tasks you want to begin the process and click **Start** in the **Control Panel**.
 
-.. image:: ./img/scikit-package-logo-text.png
-    :alt: codecov-in-pr-comment
-    :width: 400px
-    :align: center
+.. image:: img/bpdfsuite_gui_before_start.png
+   :width: 100%
+   :align: center
 
+8. Click the **Log** Icon to view the runtime output during the refinement process.
 
-Other useful directives
------------------------
+9. Double click the finished tasks in the **Task Panel** to view the refined results.
 
-Here is how you can do menu selection  :menuselection:`Admin --> Settings` and display labels for buttons like :guilabel:`Privacy level`.
+10. (Optional) Click **Save to** in the **Task Panel** to save the result in another place. By default, they are
+stored in ``fit_results`` under the experiment data folder.