feat: update the grammar of diffpy macro

docs/source/diffpy-macro.rst

@@ -7,7 +7,7 @@ Diffpy macro files can be executed using the ``runmacro`` application.
 
 .. code-block:: bash
 
-    diffpy-app runmacro <macro_file.dp-in>
+    diffpy-app runmacro <macro_file>
 
 To follow the example,
 
@@ -30,105 +30,89 @@ To follow the example,
 How to write macro
 ~~~~~~~~~~~~~~~~~~
 
+A macro file is a list of calls to the methods of the refinement session,
+one call per line or spread over several lines. Arguments are written as
+``name=value``. Supported values are numbers, quoted strings, ``True``,
+``False``, ``None``, lists ``[...]``, and dictionaries ``{"key": value}``.
+Everything after ``#`` is a comment. Calls are executed in order, and the
+macro is rejected before running if any method name is unknown.
+
 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:
+1. Load the profile and set the calculation range.
 
 .. code-block:: text
 
-    load structure G1 from "path/to/structure.cif"
-    load profile exp_ni from "path/to/profile.gr"
+    add_profile_from_file(
+        profile_name="ni_profile", profile_path="path/to/profile.gr"
+    )
+    set_profile_calculation_range(
+        profile_name="ni_profile", xmin=1.5, xmax=20, dx=0.01
+    )
+    update_profile_meta(profile_name="ni_profile", meta={"qmin": 0.1})
 
-``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.
+``ni_profile`` is the identifier used in the macro to refer to the profile.
+The profile file is a ``.gr`` file containing the experimental data.
+``xmin``, ``xmax`` and ``dx`` set the range and step size of the calculation,
+and ``qmin`` in the profile meta sets the minimum Q used in the refinement.
 
-2. (Optional) Declare the space group of the structure.
+2. Create the PDF model from the structure file.
 
 .. code-block:: text
 
-    set G1 spacegroup as Fm-3m
+    add_pdf_model(
+        model_name="pdf", structure_file_path="path/to/structure.cif", finite=False
+    )
+    constrain_pdf_model_space_group_symmetry(
+        model_name="pdf", space_group="Fm-3m"
+    )
 
-``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.
+The structure file is a ``.cif`` file representing the atomic arrangement in
+your sample. The space group symmetry ``Fm-3m`` is preserved during the
+refinement.
 
-3. (Optional) Set the calculation parameters for the refinement.
+3. Set the initial values of the variables.
 
 .. code-block:: text
 
-    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
+    set_variables_value(
+        name_value_dict={
+            "pdf.phase.lattice.a": 3.52,
+            "pdf.scale": 0.4,
+            "pdf.phase.Ni0.Uiso": 0.005,
+            "pdf.delta2": 2,
+            "pdf.qdamp": 0.04,
+            "pdf.qbroad": 0.02,
+        }
+    )
 
-``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.
+Variable names follow the format ``model_name.parameter``. Parameters of the
+structure are under ``model_name.phase``, for example
+``pdf.phase.Ni0.Uiso`` is the Uiso parameter of the atom ``Ni0``.
 
-
-4. Create the refinement equation.
+4. Run the refinement.
 
 .. 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.
+    solve(
+        profile_names=["ni_profile"],
+        model_names=["pdf"],
+        variable_names=[
+            "pdf.phase.lattice.a",
+            "pdf.scale",
+            "pdf.phase.Ni0.Uiso",
+            "pdf.delta2",
+            "pdf.qdamp",
+            "pdf.qbroad",
+        ],
+    )
+
+Only the variables listed in ``variable_names`` are refined.
 
 .. 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.
+
+    All commands from in a macro file are also tools inside
+    ``cmi-agentic-ui`` MCP server as they are essentially wrappers around the
+    same underlying methods. Please refer to :doc:`diffpy-agent`
+    for more information.

news/macro.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Update the grammar of macro to be compatible with cmi-agentic-ui.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>