doc: add general refinement documentation

docs/source/data/gaussian.dat

@@ -0,0 +1,100 @@
+-1.000000000000000000e+00 6.099574639740833470e-01
+-9.797979797979797789e-01 6.276253850862326678e-01
+-9.595959595959595578e-01 6.382533688526754734e-01
+-9.393939393939394478e-01 6.463119503895119466e-01
+-9.191919191919192267e-01 6.625023453657580275e-01
+-8.989898989898990056e-01 6.716750225091157045e-01
+-8.787878787878787845e-01 6.810961227572535082e-01
+-8.585858585858585634e-01 6.999871244019877370e-01
+-8.383838383838383423e-01 7.102111150835840325e-01
+-8.181818181818181213e-01 7.159138173782333414e-01
+-7.979797979797980112e-01 7.351311336660734108e-01
+-7.777777777777777901e-01 7.486121194244007571e-01
+-7.575757575757575690e-01 7.560255968327483922e-01
+-7.373737373737373479e-01 7.640044601211921638e-01
+-7.171717171717171269e-01 7.762894250652822015e-01
+-6.969696969696970168e-01 7.916663833585100285e-01
+-6.767676767676766847e-01 8.023015848686114726e-01
+-6.565656565656565746e-01 8.121549711306964570e-01
+-6.363636363636363535e-01 8.230927895560998797e-01
+-6.161616161616161325e-01 8.336940904860526969e-01
+-5.959595959595959114e-01 8.375676201947187538e-01
+-5.757575757575756903e-01 8.568515867256109031e-01
+-5.555555555555555802e-01 8.602480477243152901e-01
+-5.353535353535352481e-01 8.671272660897340057e-01
+-5.151515151515151381e-01 8.771109644618668710e-01
+-4.949494949494949170e-01 8.886481710261484590e-01
+-4.747474747474746959e-01 9.001541498110632311e-01
+-4.545454545454544748e-01 9.108769634932843973e-01
+-4.343434343434342537e-01 9.199826733390495948e-01
+-4.141414141414141437e-01 9.205269115667137347e-01
+-3.939393939393939226e-01 9.304118427630815313e-01
+-3.737373737373737015e-01 9.328088038054735964e-01
+-3.535353535353534804e-01 9.433036481825238795e-01
+-3.333333333333332593e-01 9.479571368728224590e-01
+-3.131313131313130382e-01 9.597705594042117427e-01
+-2.929292929292928171e-01 9.614290661132198768e-01
+-2.727272727272727071e-01 9.732201167841751932e-01
+-2.525252525252524860e-01 9.771924632625255125e-01
+-2.323232323232322649e-01 9.810298880087413576e-01
+-2.121212121212120438e-01 9.786829424619650775e-01
+-1.919191919191918227e-01 9.829111557328955584e-01
+-1.717171717171716017e-01 9.857044373699865858e-01
+-1.515151515151514916e-01 9.912146489946945804e-01
+-1.313131313131312705e-01 9.951441868149180081e-01
+-1.111111111111110494e-01 9.947786629643901035e-01
+-9.090909090909082835e-02 1.000753405941688490e+00
+-7.070707070707060726e-02 1.005632298563663873e+00
+-5.050505050505038618e-02 1.007866124364622751e+00
+-3.030303030303027612e-02 1.009203265211984224e+00
+-1.010101010101005503e-02 1.009153536711514088e+00
+1.010101010101016605e-02 1.004557564302135608e+00
+3.030303030303049816e-02 1.000346326373114270e+00
+5.050505050505060822e-02 1.006842226792272976e+00
+7.070707070707071829e-02 1.005942665429630400e+00
+9.090909090909105039e-02 1.002012212643738964e+00
+1.111111111111111605e-01 9.949645449530896135e-01
+1.313131313131314926e-01 1.001050124186687373e+00
+1.515151515151516026e-01 9.969159784343447628e-01
+1.717171717171717127e-01 9.902943822297211041e-01
+1.919191919191920448e-01 9.834382391284974823e-01
+2.121212121212121549e-01 9.798293090768575020e-01
+2.323232323232324870e-01 9.741096401619604439e-01
+2.525252525252525970e-01 9.697578472705100650e-01
+2.727272727272729291e-01 9.667310754859448352e-01
+2.929292929292930392e-01 9.631592046527157613e-01
+3.131313131313131493e-01 9.611051139524560138e-01
+3.333333333333334814e-01 9.531563730704377679e-01
+3.535353535353535914e-01 9.419441502013623513e-01
+3.737373737373739235e-01 9.411739739797071458e-01
+3.939393939393940336e-01 9.290933414116692157e-01
+4.141414141414143657e-01 9.269867199265433566e-01
+4.343434343434344758e-01 9.126314855656040281e-01
+4.545454545454545858e-01 9.075948055372592416e-01
+4.747474747474749179e-01 9.002840009167660806e-01
+4.949494949494950280e-01 8.876963776444766197e-01
+5.151515151515153601e-01 8.839376471130950819e-01
+5.353535353535354702e-01 8.704566608554854534e-01
+5.555555555555555802e-01 8.612428644036342895e-01
+5.757575757575759123e-01 8.492334053477742506e-01
+5.959595959595960224e-01 8.421461766571680663e-01
+6.161616161616163545e-01 8.344264666163453414e-01
+6.363636363636364646e-01 8.203136877361665302e-01
+6.565656565656567967e-01 8.095056219094340921e-01
+6.767676767676769067e-01 8.007585017076819245e-01
+6.969696969696970168e-01 7.881764294454121078e-01
+7.171717171717173489e-01 7.827779381766528655e-01
+7.373737373737374590e-01 7.714985534309917181e-01
+7.575757575757577911e-01 7.557341625805511498e-01
+7.777777777777779011e-01 7.459129014290789561e-01
+7.979797979797982332e-01 7.303552610429090430e-01
+8.181818181818183433e-01 7.158397527134905403e-01
+8.383838383838384534e-01 7.132766692866724378e-01
+8.585858585858587855e-01 7.013115052901616187e-01
+8.787878787878788955e-01 6.818871262137480294e-01
+8.989898989898992276e-01 6.687902887859044077e-01
+9.191919191919193377e-01 6.607940490813217771e-01
+9.393939393939394478e-01 6.485705416439250248e-01
+9.595959595959597799e-01 6.334819364170275469e-01
+9.797979797979798899e-01 6.240772966257169818e-01
+1.000000000000000000e+00 6.128767105179692143e-01

docs/source/diffpy-agent.rst

@@ -262,9 +262,10 @@ Please see :ref:`mcp_setup` for instructions.
 Here we assume that you are using ``Claude Code`` Desktop as your agent. If you are
 using a different agent, please replace ``Claude`` in the following steps.
 
-1. Download the :download:`Ni.gr<data/Ni.gr>` and :download:`Ni.cif<data/Ni.cif>`
-files to your working directory.
-
+.. _general_refinement:
+General expression refinement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+1. Download the :download:`gaussian profile<data/gaussian.dat>` to your working directory.
 2. Open ``Claude Code`` Desktop, launch the "Code" tab or select "Cowork" in "Chat or Cowork"
 tab.
 
@@ -277,12 +278,61 @@ tab.
 
     Terminal distributions can usually discover the MCP servers automatically.
 
-
 3. Add the working directory folder to the ``Claude Code`` Desktop.
 
-4. Start your conversation! Explore your preferred way to communicate with the agent.
+4. Interact with the agent to solve tasks.
+
+For example, Mr Neutron had the following conversation to have the agent solved
+a Gaussian refinement task.
+
+.. code-block:: text
+
+    > (Mr Neutron) Make sure you can find `diffpy.apps` MCP server and `gaussian.dat`
+    > (Agent) I find both...
+    > (Mr Neutron) Use diffpy.apps MCP server to create a equation model `Aexp(-(x-u)^2/(2s^2))`
+    > (Agent) I added an equation model called gaussian to the diffpy.apps session...
+        The server lists four parameters for it: A, u, s and x, all with no value yet...
+    > (Mr Neutron) Set the initial values of `A`, `u`, and `s` to be 0.8, 0.2,
+        and 0.8 , and make a plot of the equation model and the profile
+    > (Agent) I set A = 0.8, u = 0.2 and s = 0.8 on the gaussian model and plotted
+        it against the profile from gaussian.dat. To do so, I ...
+
+And the following image is given by ``Claude Code`` Desktop:
+
+.. figure:: img/example_bad_gaussian.png
+    :align: center
+
+    Gaussian plot (before refinement). Generated by Claude Code
+
+The conversation continues with Mr Neutron asking the agent to refine the equation model:
+
+.. code-block:: text
+
+    > (Mr Neutron) Refine the equation model against the profile, and plot the
+    refined equation model and the profile
+    > (Agent) The fit converged and the Gaussian matches the data closely,
+    with Rw = 0.0034. The data looks like a unit Gaussian, A = 1, u = 0, s = 1,
+    plus a little noise.
+
+.. figure:: img/example_good_gaussian.png
+    :align: center
+
+    Gaussian plot (after refinement). Generated by Claude Code
+
+Mr. Neutron is satisfied with the refined Gaussian plot.
+
+.. _pdf_refinement:
+PDF(Pair Distribution Function) refinement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It would be very similar to the :ref:`general_refinement`,
+but copy the following files to your working directory instead.
+
+- :download:`Ni.gr<data/Ni.gr>`
+- :download:`Ni.cif<data/Ni.cif>`
 
-For example, Mr Neutron follows the steps and started a conversation with the agent:
+For example, Mr Neutron had the following conversation to have the agent solved
+a Ni PDF refinement task.
 
 .. code-block:: text
 

gaussian.dat

@@ -0,0 +1,100 @@
+-1.000000000000000000e+00 6.099574639740833470e-01
+-9.797979797979797789e-01 6.276253850862326678e-01
+-9.595959595959595578e-01 6.382533688526754734e-01
+-9.393939393939394478e-01 6.463119503895119466e-01
+-9.191919191919192267e-01 6.625023453657580275e-01
+-8.989898989898990056e-01 6.716750225091157045e-01
+-8.787878787878787845e-01 6.810961227572535082e-01
+-8.585858585858585634e-01 6.999871244019877370e-01
+-8.383838383838383423e-01 7.102111150835840325e-01
+-8.181818181818181213e-01 7.159138173782333414e-01
+-7.979797979797980112e-01 7.351311336660734108e-01
+-7.777777777777777901e-01 7.486121194244007571e-01
+-7.575757575757575690e-01 7.560255968327483922e-01
+-7.373737373737373479e-01 7.640044601211921638e-01
+-7.171717171717171269e-01 7.762894250652822015e-01
+-6.969696969696970168e-01 7.916663833585100285e-01
+-6.767676767676766847e-01 8.023015848686114726e-01
+-6.565656565656565746e-01 8.121549711306964570e-01
+-6.363636363636363535e-01 8.230927895560998797e-01
+-6.161616161616161325e-01 8.336940904860526969e-01
+-5.959595959595959114e-01 8.375676201947187538e-01
+-5.757575757575756903e-01 8.568515867256109031e-01
+-5.555555555555555802e-01 8.602480477243152901e-01
+-5.353535353535352481e-01 8.671272660897340057e-01
+-5.151515151515151381e-01 8.771109644618668710e-01
+-4.949494949494949170e-01 8.886481710261484590e-01
+-4.747474747474746959e-01 9.001541498110632311e-01
+-4.545454545454544748e-01 9.108769634932843973e-01
+-4.343434343434342537e-01 9.199826733390495948e-01
+-4.141414141414141437e-01 9.205269115667137347e-01
+-3.939393939393939226e-01 9.304118427630815313e-01
+-3.737373737373737015e-01 9.328088038054735964e-01
+-3.535353535353534804e-01 9.433036481825238795e-01
+-3.333333333333332593e-01 9.479571368728224590e-01
+-3.131313131313130382e-01 9.597705594042117427e-01
+-2.929292929292928171e-01 9.614290661132198768e-01
+-2.727272727272727071e-01 9.732201167841751932e-01
+-2.525252525252524860e-01 9.771924632625255125e-01
+-2.323232323232322649e-01 9.810298880087413576e-01
+-2.121212121212120438e-01 9.786829424619650775e-01
+-1.919191919191918227e-01 9.829111557328955584e-01
+-1.717171717171716017e-01 9.857044373699865858e-01
+-1.515151515151514916e-01 9.912146489946945804e-01
+-1.313131313131312705e-01 9.951441868149180081e-01
+-1.111111111111110494e-01 9.947786629643901035e-01
+-9.090909090909082835e-02 1.000753405941688490e+00
+-7.070707070707060726e-02 1.005632298563663873e+00
+-5.050505050505038618e-02 1.007866124364622751e+00
+-3.030303030303027612e-02 1.009203265211984224e+00
+-1.010101010101005503e-02 1.009153536711514088e+00
+1.010101010101016605e-02 1.004557564302135608e+00
+3.030303030303049816e-02 1.000346326373114270e+00
+5.050505050505060822e-02 1.006842226792272976e+00
+7.070707070707071829e-02 1.005942665429630400e+00
+9.090909090909105039e-02 1.002012212643738964e+00
+1.111111111111111605e-01 9.949645449530896135e-01
+1.313131313131314926e-01 1.001050124186687373e+00
+1.515151515151516026e-01 9.969159784343447628e-01
+1.717171717171717127e-01 9.902943822297211041e-01
+1.919191919191920448e-01 9.834382391284974823e-01
+2.121212121212121549e-01 9.798293090768575020e-01
+2.323232323232324870e-01 9.741096401619604439e-01
+2.525252525252525970e-01 9.697578472705100650e-01
+2.727272727272729291e-01 9.667310754859448352e-01
+2.929292929292930392e-01 9.631592046527157613e-01
+3.131313131313131493e-01 9.611051139524560138e-01
+3.333333333333334814e-01 9.531563730704377679e-01
+3.535353535353535914e-01 9.419441502013623513e-01
+3.737373737373739235e-01 9.411739739797071458e-01
+3.939393939393940336e-01 9.290933414116692157e-01
+4.141414141414143657e-01 9.269867199265433566e-01
+4.343434343434344758e-01 9.126314855656040281e-01
+4.545454545454545858e-01 9.075948055372592416e-01
+4.747474747474749179e-01 9.002840009167660806e-01
+4.949494949494950280e-01 8.876963776444766197e-01
+5.151515151515153601e-01 8.839376471130950819e-01
+5.353535353535354702e-01 8.704566608554854534e-01
+5.555555555555555802e-01 8.612428644036342895e-01
+5.757575757575759123e-01 8.492334053477742506e-01
+5.959595959595960224e-01 8.421461766571680663e-01
+6.161616161616163545e-01 8.344264666163453414e-01
+6.363636363636364646e-01 8.203136877361665302e-01
+6.565656565656567967e-01 8.095056219094340921e-01
+6.767676767676769067e-01 8.007585017076819245e-01
+6.969696969696970168e-01 7.881764294454121078e-01
+7.171717171717173489e-01 7.827779381766528655e-01
+7.373737373737374590e-01 7.714985534309917181e-01
+7.575757575757577911e-01 7.557341625805511498e-01
+7.777777777777779011e-01 7.459129014290789561e-01
+7.979797979797982332e-01 7.303552610429090430e-01
+8.181818181818183433e-01 7.158397527134905403e-01
+8.383838383838384534e-01 7.132766692866724378e-01
+8.585858585858587855e-01 7.013115052901616187e-01
+8.787878787878788955e-01 6.818871262137480294e-01
+8.989898989898992276e-01 6.687902887859044077e-01
+9.191919191919193377e-01 6.607940490813217771e-01
+9.393939393939394478e-01 6.485705416439250248e-01
+9.595959595959597799e-01 6.334819364170275469e-01
+9.797979797979798899e-01 6.240772966257169818e-01
+1.000000000000000000e+00 6.128767105179692143e-01

news/general-refinement.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* No news added: Added using the agent for general refinement documentation.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>