Pre-compute pathways for fitting

CHANGELOG

@@ -8,6 +8,10 @@ What's new
 
 - Support gamma angle averaging.
 
+**Simulator**
+
+- New instance method for the `Simulator` class -- `.optimize()` -- which pre-computes transition pathways before least-squares minimization. This improves the efficiency of least-squares minimizations.
+
 v0.7.0
 ------
 

docs/introduction/fitting_example.rst

@@ -520,7 +520,15 @@ minimization, and print the
     :context: close-figs
 
     from lmfit import Minimizer
-    minner = Minimizer(sf.LMFIT_min_function, fit_parameters, fcn_args=(sim, processor, sigma))
+    # Optimize fitting by pre-computing transition pathways
+    opt = sim.optimize()
+
+    minner = Minimizer(
+        sf.LMFIT_min_function,
+        fit_parameters,
+        fcn_args=(sim, processor, sigma),
+        fcn_kws={"opt": opt}
+    )
     result = minner.minimize()
     result
 

docs/introduction/isotopomers_example.rst

@@ -215,7 +215,7 @@ spin systems and the list of your two methods, and run the simulations.
 
     sim = Simulator(
         spin_systems = [isotopomer1, isotopomer2, isotopomer3],
-        methods=[method_H, method_C]
+        methods = [method_H, method_C]
     )
     sim.run()
 

fitting_source/1D_fitting/plot_1_31P_Na2PO4_MAS.py

@@ -99,14 +99,6 @@
     experiment=experiment,  # experimental dataset
 )
 
-# A method object queries every spin system for a list of transition pathways that are
-# relevant to the given method. Since the method and the number of spin systems remains
-# unchanged during the least-squares analysis, a one-time query is sufficient. To avoid
-# querying for the transition pathways at every iteration in a least-squares fitting,
-# evaluate the transition pathways once and store it as follows
-for sys in spin_systems:
-    sys.transition_pathways = MAS.get_transition_pathways(sys)
-
 # %%
 # **Step 3:** Create the Simulator object and add the method and spin system objects.
 sim = Simulator(spin_systems=spin_systems, methods=[MAS])
@@ -169,13 +161,28 @@
 print(params.pretty_print(columns=["value", "min", "max", "vary", "expr"]))
 
 # %%
-# **Step 7:** Perform the least-squares minimization. For the user's convenience, we
+# **Step 7:** Perform the least-squares minimization.
+# A method object queries every spin system for a list of transition pathways that are
+# relevant to the given method. Since the method and the number of spin systems remains
+# unchanged during the least-squares analysis, a one-time query is sufficient. To avoid
+# querying for the transition pathways at every iteration in a least-squares fitting,
+# call the :py:mth:~`mrsimulator.Simulator.optimize()` method to pre-compute the
+# pathways.
+#
+# For the user's convenience, we
 # also provide a utility function,
 # :func:`~mrsimulator.utils.spectral_fitting.LMFIT_min_function`, for evaluating the
 # difference vector between the simulation and experiment, based on
-# the parameters update. You may use this function directly as the argument of the
-# LMFIT Minimizer class, as follows,
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+# the parameters update. You may use this function directly to instantiate the
+# LMFIT Minimizer class where `fcn_args` and `fcn_kws` are arguments passed to the
+# function, as follows,
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_1_31p_Na2PO4_static.py

@@ -73,11 +73,6 @@
     experiment=experiment,  # experimental dataset
 )
 
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = static1D.get_transition_pathways(sys)
-
 # %%
 # **Guess Model Spectrum**
 
@@ -122,7 +117,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_2_13C_glycine_960Hz.py

@@ -76,12 +76,6 @@
     spectral_dimensions=spectral_dims,
     experiment=experiment,  # experimental dataset
 )
-
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = MAS.get_transition_pathways(sys)
-
 # %%
 # **Guess Model Spectrum**
 
@@ -126,7 +120,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_2_13C_glycine_multi_spectra_fit.py

@@ -196,7 +196,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processors, sigmas))
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processors, sigmas),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_2_PASS_cross_sections.py

@@ -76,10 +76,6 @@
     experiment=pass_cross_section,  # also add the measurement to the method.
 )
 
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = PASS.get_transition_pathways(sys)
 
 # %%
 # **Guess Spectrum**
@@ -122,7 +118,13 @@
 
 # %%
 # Run the minimization using LMFIT
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_3_Na2SiO3.py

@@ -104,13 +104,6 @@
     experiment=experiment,  # experimental dataset
 )
 
-# A method object queries every spin system for a list of transition pathways that are
-# relevant for the given method. Since the method and the number of spin systems remain
-# the same during the least-squares fit, a one-time query is sufficient. To avoid
-# querying for the transition pathways at every iteration in a least-squares fitting,
-# evaluate the transition pathways once and store it as follows
-for sys in spin_systems:
-    sys.transition_pathways = MAS_CT.get_transition_pathways(sys)
 
 # %%
 # **Step 3:** Create the Simulator object and add the method and spin system objects.
@@ -177,9 +170,16 @@
 # provide a utility function,
 # :func:`~mrsimulator.utils.spectral_fitting.LMFIT_min_function`, for evaluating the
 # difference vector between the simulation and experiment, based on
-# the parameters update. You may use this function directly as the argument of the
-# LMFIT Minimizer class, as follows,
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+# the parameters update. You may use this function directly to instantiate the
+# LMFIT Minimizer class where `fcn_args` and `fcn_kws` are arguments passed to the
+# function, as follows,
+opt = sim.optimize()
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_4_11B_Quad_NMR.py

@@ -70,11 +70,6 @@
     experiment=experiment,  # add the measurement to the method.
 )
 
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = MAS_CT.get_transition_pathways(sys)
-
 # %%
 # **Guess Model Spectrum**
 
@@ -119,7 +114,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_4_27Al_YAG.py

@@ -83,11 +83,6 @@
     experiment=experiment,  # add the measurement to the method.
 )
 
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = MAS.get_transition_pathways(sys)
-
 # %%
 # **Guess Spectrum**
 
@@ -132,7 +127,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_4_2H_quad.py

@@ -71,10 +71,6 @@
     experiment=experiment,  # experimental dataset
 )
 
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = MAS.get_transition_pathways(sys)
 
 # %%
 # **Guess Model Spectrum**
@@ -120,7 +116,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/1D_fitting/plot_5_119Sn_sideband.py

@@ -88,10 +88,6 @@
     experiment=experiment,  # add the measurement to the method.
 )
 
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = MAS.get_transition_pathways(sys)
 
 # %%
 # **Guess Spectrum**
@@ -155,7 +151,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/2D_fitting/plot_1_LHistidine_PASS.py

@@ -89,11 +89,6 @@
     experiment=mat_dataset,  # add the measurement to the method.
 )
 
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = PASS.get_transition_pathways(sys)
-
 # %%
 # **Guess Spectrum**
 
@@ -137,7 +132,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result
 

fitting_source/2D_fitting/plot_1_Rb2SO4_QMAT.py

@@ -85,11 +85,6 @@
     experiment=qmat_dataset,  # add the measurement to the method.
 )
 
-# Optimize the script by pre-setting the transition pathways for each spin system from
-# the method.
-for sys in spin_systems:
-    sys.transition_pathways = PASS.get_transition_pathways(sys)
-
 # %%
 # **Guess Spectrum**
 
@@ -135,7 +130,13 @@
 
 # %%
 # **Solve the minimizer using LMFIT**
-minner = Minimizer(sf.LMFIT_min_function, params, fcn_args=(sim, processor, sigma))
+opt = sim.optimize()  # Pre-compute transition pathways
+minner = Minimizer(
+    sf.LMFIT_min_function,
+    params,
+    fcn_args=(sim, processor, sigma),
+    fcn_kws={"opt": opt},
+)
 result = minner.minimize()
 result