diff --git a/docs/example/runmacro_example.zip b/docs/example/runmacro_example.zip new file mode 100644 index 0000000..44b5f62 Binary files /dev/null and b/docs/example/runmacro_example.zip differ diff --git a/docs/source/api/diffpy.apps.example_package.rst b/docs/source/api/diffpy.apps.example_package.rst deleted file mode 100644 index 6b2f76e..0000000 --- a/docs/source/api/diffpy.apps.example_package.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _example_package documentation: - -|title| -======= - -.. |title| replace:: diffpy.apps.example_package package - -.. automodule:: diffpy.apps.example_package - :members: - :undoc-members: - :show-inheritance: - -|foo| ------ - -.. |foo| replace:: diffpy.apps.example_package.foo module - -.. automodule:: diffpy.apps.example_package.foo - :members: - :undoc-members: - :show-inheritance: - -|bar| ------ - -.. |bar| replace:: diffpy.apps.example_package.bar module - -.. automodule:: diffpy.apps.example_package.foo - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/api/diffpy.apps.rst b/docs/source/api/diffpy.apps.rst deleted file mode 100644 index bd4ee3c..0000000 --- a/docs/source/api/diffpy.apps.rst +++ /dev/null @@ -1,30 +0,0 @@ -:tocdepth: -1 - -|title| -======= - -.. |title| replace:: diffpy.apps package - -.. automodule:: diffpy.apps - :members: - :undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - diffpy.apps.example_package - -Submodules ----------- - -|module| --------- - -.. |module| replace:: diffpy.apps.example_submodule module - -.. automodule:: diffpy.apps.example_submodule - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index 6b62bf8..077bc0e 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/getting-started.rst @@ -8,72 +8,144 @@ 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.apps`` provides user applications to help with tasks using +diffpy packages. This page contains the instructions for all applications +available, including: -Reuse ``.rst`` files across multiple pages ------------------------------------------- +- :ref:`runmacro` -Here is how you can reuse a reusable block of ``.rst`` files across multiple pages: +.. _runmacro: -.. include:: snippets/example-table.rst +Use ``runmacro`` to start refinement with a macro file +------------------------------------------------------ -.. warning:: +The ``runmacro`` application allows users to execute macros written in the +diffpy macro language. - 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. +.. code-block:: bash -Refer to a specific section in the documentation ------------------------------------------------- + diffpy.app runmacro -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 `. +To follow the example, -.. note:: +1. download the example files from :download:`here <../example/runmacro_example.zip>` - Please check the raw ``.rst`` file of this page to see the exact use of the ``:ref:`` tag. +2. extract the downloaded files and navigate to the extracted directory + +.. code-block:: bash -Embed your code snippets in the documentation ---------------------------------------------- + mv /path/to/runmacro runmacro_example.zip working_directory + cd working_directory + unzip runmacro_example.zip -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: +3. run the macro using the ``runmacro`` application .. code-block:: bash - # 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 + diffpy.app runmacro example_macro.dp-in + +How to write macro +~~~~~~~~~~~~~~~~~~ + +Let's still use the Ni example created earlier, but this time we will +write the macro file from scratch. + +1. Prepare the structure and profile file you want to work with. + +.. note:: + + The structure file is a ``.cif`` file representing the atomic arrangement in + your sample, and the profile file is a ``.gr`` file containing the + experimental data. + +Start the macro file with the following two lines: + +.. code-block:: text + + load structure G1 from "path/to/structure.cif" + load profile exp_ni from "path/to/profile.gr" - # 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 +``G1`` and ``exp_ni`` are the identifiers used in the macro to refer to the +structure and profile files, respectively. Quotes ``""`` are must to specify +the file paths. - # Activate the environment - conda activate _env +2. (Optional) Declare the space group of the structure. - # Install your package locally - # `--no-deps` to NOT install packages again from `requirements.pip.txt` - pip install -e . --no-deps +.. code-block:: text - # Run pytest locally - pytest + set G1 spacegroup as Fm-3m - # ... run example tutorials +``G1`` is the identifier for the structure file loaded earlier. Space group +symmetry ``Fm-3m`` is preserved during the refinement. You can also set +it to be ``auto`` to use the one automatically parsed from the structure file. +But if space group is not provided, nor can it be determined from the structure +file, it will be considered as ``P1`` space group. -.. _attach-image: +3. (Optional) Set the calculation parameters for the refinement. -Attach an image to the documentation ------------------------------------- +.. code-block:: text -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. + set exp_ni calculation_range as 0.5 20.0 0.01 # r_min, r_max, r_step + set exp_ni q_range as 0.5 20.0 # q_min, q_max -.. image:: ./img/scikit-package-logo-text.png - :alt: codecov-in-pr-comment - :width: 400px - :align: center +``exp_ni`` is the identifier for the profile file loaded earlier. +``calculation_range`` specifies the range and step size for the calculation, +while ``q_range`` specifies the range of Q values to be used in the refinement. +If calculation parameters are not set, it will use the ones +that are defined in the profile file. -Other useful directives ------------------------ +4. Create the refinement equation. -Here is how you can do menu selection :menuselection:`Admin --> Settings` and display labels for buttons like :guilabel:`Privacy level`. +.. code-block:: text + + create equation variables s0 + set equation as "G1*s0" + +``G1`` is the identifier for the structure file loaded earlier. In the +equation, it represents the PDF data generated from the structure `G1`. +``s0`` is created to count for the scaling factor. + +5. Store the results. + +.. code-block:: text + + save to "output_results.json" + +The results of the refinement will be saved to a file +named ``output_results.json``. + +6. List variables to be refined. + +.. code-block:: text + + variables: + --- + - G1.a: 3.52 + - s0: 0.4 + - G1.Uiso_0: 0.005 + - G1.delta2: 2 + - qdamp: 0.04 + - qbroad: 0.02 + --- + +Only variables listed in this section will be refined during the +execution of the macro, and the variables will also be refined in that order. +Variables with initial values specified here will be used as the +starting point for the refinement. + +.. note:: + The naming of variables follows the format + ``structure_identifier.parameter``, + ``profile_parameter``, or + ``equation_parameter``. + + For parameters belonging to a specific atom in the parameter, + the naming follows the format ``structure_identifier.parameter_atomindex``. + e.g. ``G1.Uiso_0`` here refers to the Uiso parameter of the first atom in + the structure ``G1``. + + For constrained parameters, it will use the first parameter in the + constraint. e.g. Here, lattice parameter ``a=b=c``, + and ``Usio_0=Uiso_i, i=1,2,3``, ``a`` and ``Uiso_0`` are used as the + reference variables. diff --git a/docs/source/index.rst b/docs/source/index.rst index 1f23a40..d83fcef 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/docs/source/snippets/example-table.rst b/docs/source/snippets/example-table.rst deleted file mode 100644 index 7c4c11d..0000000 --- a/docs/source/snippets/example-table.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. list-table:: 5 levels of reusing/sharing code - :widths: 5 15 40 40 - :header-rows: 1 - - * - Level - - Name - - Scope - - How to setup - * - 1 - - ``function`` - - Reuse code in the single file. - - See Level 1 tutorial - * - 2 - - ``module`` - - Reuse code across files. - - See Level 2 tutorial - * - 3 - - ``workspace`` - - Reuse code across project folders. - - ``package create workspace`` - * - 4 - - ``system`` - - Reuse code across any files in the computer. - - ``package create system`` - * - 5 - - ``public`` - - Share code as publicly installable package. - - ``package create public`` diff --git a/news/dsl-instruction.rst b/news/dsl-instruction.rst new file mode 100644 index 0000000..e957887 --- /dev/null +++ b/news/dsl-instruction.rst @@ -0,0 +1,23 @@ +**Added:** + +* No news added: Add instructions to use diffpy.apps runmacro . + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +*