diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7e4eee2..fde58ce 100644 --- a/.pre-commit-config.yaml +++ b/.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] diff --git a/cookiecutter.json b/cookiecutter.json index 9afb8ad..39084bb 100644 --- a/cookiecutter.json +++ b/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", diff --git a/docs/examples/example.zip b/docs/examples/example.zip new file mode 100644 index 0000000..fc81de6 Binary files /dev/null and b/docs/examples/example.zip differ diff --git a/docs/source/api/diffpy.batchpdfsuite.example_package.rst b/docs/source/api/diffpy.batchpdfsuite.example_package.rst deleted file mode 100644 index 01a079a..0000000 --- a/docs/source/api/diffpy.batchpdfsuite.example_package.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _example_package documentation: - -|title| -======= - -.. |title| replace:: diffpy.batchpdfsuite.example_package package - -.. automodule:: diffpy.batchpdfsuite.example_package - :members: - :undoc-members: - :show-inheritance: - -|foo| ------ - -.. |foo| replace:: diffpy.batchpdfsuite.example_package.foo module - -.. automodule:: diffpy.batchpdfsuite.example_package.foo - :members: - :undoc-members: - :show-inheritance: - -|bar| ------ - -.. |bar| replace:: diffpy.batchpdfsuite.example_package.bar module - -.. automodule:: diffpy.batchpdfsuite.example_package.foo - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/diffpy.batchpdfsuite.rst b/docs/source/api/diffpy.batchpdfsuite.rst deleted file mode 100644 index 26113fb..0000000 --- a/docs/source/api/diffpy.batchpdfsuite.rst +++ /dev/null @@ -1,30 +0,0 @@ -:tocdepth: -1 - -|title| -======= - -.. |title| replace:: diffpy.batchpdfsuite package - -.. automodule:: diffpy.batchpdfsuite - :members: - :undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - diffpy.batchpdfsuite.example_package - -Submodules ----------- - -|module| --------- - -.. |module| replace:: diffpy.batchpdfsuite.example_submodule module - -.. automodule:: diffpy.batchpdfsuite.example_submodule - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 6b62bf8..1c16a87 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -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 `_ and +`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 `_ -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 `. .. 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 -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 `_ - # Create a new environment, with build dependencies (non-pure Python package) - conda create -n -env python=3.14 \ - --file requirements/tests.txt \ - --file requirements/conda.txt \ - --file requirements/build.txt - # Activate the environment - conda activate _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 `_ -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. diff --git a/docs/source/img/.placeholder b/docs/source/img/.placeholder deleted file mode 100644 index e69de29..0000000 diff --git a/docs/source/img/bpdfsuite_gui.png b/docs/source/img/bpdfsuite_gui.png new file mode 100644 index 0000000..2173709 Binary files /dev/null and b/docs/source/img/bpdfsuite_gui.png differ diff --git a/docs/source/img/bpdfsuite_gui_before_start.png b/docs/source/img/bpdfsuite_gui_before_start.png new file mode 100644 index 0000000..62f7cf4 Binary files /dev/null and b/docs/source/img/bpdfsuite_gui_before_start.png differ diff --git a/docs/source/img/bpdfsuite_gui_folder_selected.png b/docs/source/img/bpdfsuite_gui_folder_selected.png new file mode 100644 index 0000000..5af1677 Binary files /dev/null and b/docs/source/img/bpdfsuite_gui_folder_selected.png differ diff --git a/docs/source/img/scikit-package-logo-text.png b/docs/source/img/scikit-package-logo-text.png deleted file mode 100644 index 823178d..0000000 Binary files a/docs/source/img/scikit-package-logo-text.png and /dev/null differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 95df8d5..b57340e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,7 +44,6 @@ Table of contents :maxdepth: 2 getting-started - Package API release license diff --git a/news/tutorial.rst b/news/tutorial.rst new file mode 100644 index 0000000..cb951f1 --- /dev/null +++ b/news/tutorial.rst @@ -0,0 +1,23 @@ +**Added:** + +* No news added: Add tutorial about how to use ``diffpy.batchpdfsuite``. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/pyproject.toml b/pyproject.toml index d0ef65f..e8e12a6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,7 +10,6 @@ authors = [ {name='Simon Billinge', email='sbillinge@ucsb.edu'}, ] maintainers = [ - {name='Yuchen Xiao', email='yx2924@columbia.edu'}, {name='Simon Billinge', email='sbillinge@ucsb.edu'}, ] description = "GUI for batch refinements of multiple PDF datasets" diff --git a/src/diffpy/batchpdfsuite/__init__.py b/src/diffpy/batchpdfsuite/__init__.py index e91c7e1..6646487 100644 --- a/src/diffpy/batchpdfsuite/__init__.py +++ b/src/diffpy/batchpdfsuite/__init__.py @@ -12,7 +12,7 @@ # See LICENSE.rst for license information. # ############################################################################## -"""GUI for batch refinements of multiple PDF datasets""" +"""GUI for batch refinements of multiple PDF datasets.""" # package version from diffpy.batchpdfsuite.version import __version__ # noqa