Pyomo. DoE: Sensitivity initialization by smondal13 · Pull Request #3639 · Pyomo/pyomo

smondal13 · 2025-06-23T14:45:35Z

Fixes # .

Summary/Motivation:

Initializing the model to a previously solved point in the design space can help the model converge at another point in the design space for sensitivity analysis
Better error messages in the method can help the user in debugging
Saving the file can be helpful if the model takes a long time to solve or if the user wants it.
The pattern generator in the utils.py file can be used in other cases where it can help with the initialization
Correlation matrix computation functionality will be helpful in computing correlation among the parameters

Changes proposed in this PR:

Added a new method compute_FIM_factorial() in Pyomo.DoE for sensitivity initialization
Added snake_traversal_grid_sampling() and compute_correlation_matrix() in utils.py

Legal Acknowledgement

By contributing to this software project, I have read the contribution guide and agree to the following terms and conditions for my contribution:

I agree my contributions are submitted under the BSD license.
I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

…pected. Now, I need to add cases when some of the design variables are not changed.

…mo into sensitivity-initialization

… use compute_FIM_metrics() method. Added both the nested for loop and change_one_design_at_a_time argument to compute_FIM_factorial() in doe.py. Everything is working fine.

…gn_values` does not need to be in the same order as the `experiment_inputs` as long as the key matches, we are good. Also, if we don't want to change a design variable, just not passing it as a key in the `design_values` dictionary will do the trick. Tested with the `reactor_example.py`

smondal13 · 2025-06-23T14:46:47Z

@adowling2 @djlaky, this draft PR is ready for initial review.

adowling2 · 2025-06-24T10:55:38Z

Does this PR depend on changes in #3575?

adowling2

@smondal13 I left some initial comments.

adowling2 · 2025-06-24T10:57:24Z

@@ -0,0 +1,267 @@
+#  ___________________________________________________________________________


@smondal13 Why are your creating a new utils file instead of updating the current one? There might be a point of confusion regarding branches in git.

This issue is resolved now. merged the utils file from my previous PR # 3525.

adowling2 · 2025-06-24T10:58:40Z


        return self.fim_factorial_results

+    def compute_FIM_factorial(


Was this function already in Pyomo.DoE somewhere else?

No, I created this method. I do not see the same name anywhere else.

@adowling2, we have compute_FIM_full_factorial(). I have not changed that method, rather I have added a new method. Maybe we can show a deprecation warning for compute_FIM_full_factorial()

Yes, a depreciation warning sounds reasonable.

Actually, I am really confused: why did you create a new method in the same file that did effectively the same thing? Does this replace the other method? Is it a superset of the other method? Do we need both?

Also, you might consider renaming this function: I don't know what a FIM factorial is (nor how to compute one). Maybe something like compute_FIM_from_full_factorial_sampling?

adowling2 · 2025-06-24T11:00:22Z

+        # design_map_keys so that design_point can be constructed correctly in the loop.
+        des_ranges = [design_values[k.name] for k in design_map_keys]
+        if change_one_design_at_a_time:
+            factorial_points = generate_snake_zigzag_pattern(*des_ranges)


Let's brainstorm different sensitivity analysis sequences we might use. We can then define an enum.

Also added test for patter generator

…mo into sensitivity-initialization

…updated.py file

…ensitivity-initialization

…f. The code is run by using a simple model.

smondal13 · 2025-07-01T18:18:24Z

@adowling2 , @djlaky, @blnicho This PR is ready for design review.

…mo into sensitivity-initialization

adowling2

Please see my requested changes.

adowling2 · 2026-02-06T18:50:10Z

+        traversal_scheme="snake_traversal",
+        file_name: str = None,
+    ):
+        """Will run a simulation-based factorial exploration of the experimental input


Change "will run" to "performs"

adowling2 · 2026-02-06T18:52:28Z

+        ----------
+        model : DoE model, optional
+            The model to perform the full factorial exploration on. Default: None
+        design_vals : dict,


@mrmundt @blnicho Do you have any suggestions for avoiding string-based names? I know that we want to avoid string-based names, but I do not have any good ideas of how to do that in a way that is convenient for the user.

I'll let @blnicho also chime in but my initial thoughts are:

The best general practice is to accept component objects / references, not names. It is convenient (for users) to optionally accept names and resolve them internally. So if it's possible, support both, with a clear canonical form.

adowling2 · 2026-02-06T18:56:56Z

+
+        return self.factorial_results
+
    # TODO: Overhaul plotting functions to not use strings


Do we still want to overhaul the plotting functions to not use strings? Or do we just want this function to be consistent with our user interface above? In other words, if we use string-based names above, I think it it okay to use string-based names here.

adowling2 · 2026-02-06T18:58:26Z

    def draw_factorial_figure(
        self,
        results=None,
        sensitivity_design_variables=None,


Let's update this user interface to match the function above. It appears that design variables as specified differently in these two functions. Likewise, this function should do design variable name error checking similar to the function above.

adowling2 · 2026-02-06T19:01:25Z

+
+
+def compute_correlation_matrix(
+    covariance_matrix, var_name: list = None, significant_digits=3


Please make the default for significant digits None.

adowling2 · 2026-02-06T19:01:58Z

+    var_name : list, optional
+        List of variable names corresponding to the rows/columns of the covariance matrix.
+    significant_digits : int, optional
+        Number of significant digits to round the correlation matrix to. Default: 3.


Number of significant digits for rounding entries of the correlation matrix. Default: None (no rounding)

adowling2 · 2026-02-06T19:03:28Z

+
+    Parameters
+    ----------
+    covariance_matrix : numpy.ndarray


Can this be a square DataFrame? If yes, what type of error checking should we do on the column and row names?

adowling2 · 2026-02-06T19:04:37Z

+    # Set the index to the variable names if provided,
+    corr_df = (
+        pd.DataFrame(correlation_matrix, index=var_name, columns=var_name)
+        if var_name


What is this logic doing here?

…trix computation

adowling2 · 2026-03-17T17:08:51Z

@smondal13 Were you able to address the comments from my review in early February? If yes, I can re-review. Reply here.

smondal13 · 2026-03-17T18:35:31Z

@smondal13 Were you able to address the comments from my review in early February? If yes, I can re-review. Reply here.

Excluding the string related comments, the comments are addressed. You can probably wait until @blnicho or @mrmundt replies to that.

jsiirola · 2026-05-11T15:50:10Z


        return self.fim_factorial_results

+    def compute_FIM_factorial(


Actually, I am really confused: why did you create a new method in the same file that did effectively the same thing? Does this replace the other method? Is it a superset of the other method? Do we need both?

Also, you might consider renaming this function: I don't know what a FIM factorial is (nor how to compute one). Maybe something like compute_FIM_from_full_factorial_sampling?

jsiirola · 2026-05-11T15:51:02Z

+    Generates a multi-dimensional pattern for an arbitrary number of 1D array-like arguments.
+    This pattern is useful for generating patterns for sensitivity analysis when we want
+    to change one variable at a time. This function uses recursion and acts as a generator.


Please make sure these are wrapped within 88 columns.

jsiirola · 2026-05-11T15:55:02Z



-def check_FIM(FIM):
+def check_matrix(mat):


This should be renamed to indicate what it is checking. Further, it is not checking and returning True/False, it is asserting (see, e.g. the difference between check_optimal_termination and assert_optimal_termination).

Maybe rename to something like assert_matrix_symmetric_positive_definite or assert_symmetric_positive_definite?

jsiirola · 2026-05-11T15:56:20Z


-    # Check if the FIM is positive definite
+    # Check if the matrix is positive definite
    if np.min(evals) < -_SMALL_TOLERANCE_DEFINITENESS:


Should these tolerances be passed as optional arguments that default to the global value if None?

jsiirola · 2026-05-14T15:22:18Z

+                        2,
+                    ),
+                )
+            except:


Bare except: is potentially problematic, as it catching everything including both solver errors and generic programming errors. At a minimum, you should include the exception in the log so that a user can get an idea as to why things failed.

jsiirola · 2026-05-14T15:37:38Z

+            print("\n\n=========Factorial results===========")
+            print("Total points:", total_points)
+            print("Success count:", success_count)
+            print("Failure count:", failure_count)
+            print("\n")
+            print(res_df)


We generally strongly discourage print() within Pyomo. Instead, output should be channeled via loggers or global streams (like sys.stdout) that are easily replaceable.

jsiirola · 2026-05-14T15:38:38Z

+        if not isinstance(fixed_design_variables, dict):
+            raise ValueError("``fixed_design_variables`` must be a dictionary.")
+        if any(not isinstance(name, str) for name in fixed_design_variables.keys()):
+            raise ValueError("Fixed design variable names must be strings.")


This kind of type checking is very "non-Pythonic" and something I would generally discourage. Python encourages duck-typing: as long as the variable behaves like the desired type, then it should be OK.

Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>

…gn_vals input; add tests for component key normalization and error handling

… to abs_step/rel_step and update related logic; add test for factorial step formula using design span

…change to abs_step/rel_step in docstring and test case

…p_change and update related comments for clarity

Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>

…mo into sensitivity-initialization

…ccess and update related functions. Run black

smondal13 added 9 commits June 16, 2025 16:29

added zigzag in utils and compute fim in doe.py

a4a1ade

Merge branch 'Pyomo:main' into sensitivity-initialization

58c3663

The compute_FIM_factorial() using zigzag pattern is now working as ex…

26f8cd3

…pected. Now, I need to add cases when some of the design variables are not changed.

Merge branch 'sensitivity-initialization' of github.com:smondal13/pyo…

4dab155

…mo into sensitivity-initialization

Added utils.py as utils_updated.py from adding_eigen_values branch to…

55bfeae

… use compute_FIM_metrics() method. Added both the nested for loop and change_one_design_at_a_time argument to compute_FIM_factorial() in doe.py. Everything is working fine.

Changed documentation and improved the error message

0eb9791

Merge branch 'Pyomo:main' into sensitivity-initialization

66cdd0c

updated comments

d75e667

adowling2 reviewed Jun 24, 2025

View reviewed changes

smondal13 added 5 commits June 24, 2025 14:40

Added argument checking for generate zigzag pattern.

e5b2e73

Also added test for patter generator

changed the name of the pattern generator

13848fa

Merge branch 'adding_eigen_values' into sensitivity-initialization

bd53282

Merge branch 'Pyomo:main' into sensitivity-initialization

e40c6bc

Merge branch 'sensitivity-initialization' of github.com:smondal13/pyo…

75acdd2

…mo into sensitivity-initialization

smondal13 changed the title ~~Sensitivity initialization in Pyomo. DoE~~ Pyomo. DoE: Sensitivity initialization Jun 25, 2025

Changed the name of the grid sampling function and deleted the utils_…

0c87484

…updated.py file

sscini moved this to Todo in ParmEst & Pyomo.DoE Development Jun 27, 2025

sscini added this to ParmEst & Pyomo.DoE Development Jun 27, 2025

sscini moved this from Todo to Development in ParmEst & Pyomo.DoE Development Jun 27, 2025

sscini mentioned this pull request Jun 27, 2025

Add update_model utility to utils.py for updating suffix values in Pyomo.DoE #3650

Merged

smondal13 added 5 commits June 27, 2025 16:04

Merge remote-tracking branch 'sscini/add-update-model-utility' into s…

7cdba5b

…ensitivity-initialization

added rel_change and abs_change for change in design

6db9e66

added update_suffix function in compute the sensitivity

f12d908

working code. added design vals and also changed the settings of pd d…

fda812e

…f. The code is run by using a simple model.

Merge branch 'Pyomo:main' into sensitivity-initialization

ccfca8c

changed some minor comments and docstrings

043e7de

smondal13 and others added 2 commits October 28, 2025 12:16

Merge branch 'sensitivity-initialization' of github.com:smondal13/pyo…

b27d89d

…mo into sensitivity-initialization

Merge branch 'main' into sensitivity-initialization

964446b

blnicho added this to Pyomo 6.10 Nov 11, 2025

github-project-automation Bot moved this to Todo in Pyomo 6.10 Nov 11, 2025

smondal13 added 2 commits November 24, 2025 11:57

Merge branch 'main' into sensitivity-initialization

39a3d2b

Merge branch 'main' into sensitivity-initialization

8e823e4

mrmundt requested review from adowling2 and mrmundt January 27, 2026 19:49

Merge branch 'main' into sensitivity-initialization

3d58a30

adowling2 suggested changes Feb 6, 2026

View reviewed changes

smondal13 added 7 commits February 6, 2026 16:48

Merge branch 'main' into sensitivity-initialization

87b6c24

Remove TODO and modify docstring.

7386170

Merge branch 'main' into sensitivity-initialization

401e661

Merge branch 'main' into sensitivity-initialization

d7c7028

Refactor DesignOfExperiments documentation and improve correlation ma…

a9e8972

…trix computation

Run black

408f550

Merge branch 'main' into sensitivity-initialization

038539e

Merge branch 'main' into sensitivity-initialization

8da7ce9

jsiirola reviewed May 14, 2026

View reviewed changes

smondal13 and others added 9 commits May 14, 2026 15:37

Merge branch 'main' into sensitivity-initialization

902ac71

Apply suggestions from code review

f865c42

Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>

Enhance DesignOfExperiments API documentation and validation for desi…

6935dca

…gn_vals input; add tests for component key normalization and error handling

Refactor DesignOfExperiments parameters: rename abs_change/rel_change…

b1f776c

… to abs_step/rel_step and update related logic; add test for factorial step formula using design span

Update parameter names in DesignOfExperiments: change abs_change/rel_…

d66e607

…change to abs_step/rel_step in docstring and test case

Update comments in DesignOfExperiments: rename change_in_value to ste…

1dfd9fe

…p_change and update related comments for clarity

Apply delta_stepp suggestion from code review

07728eb

Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>

Merge branch 'sensitivity-initialization' of github.com:smondal13/pyo…

202d21b

…mo into sensitivity-initialization

Refactor FIM metrics handling: Introduce named tuple for structured a…

b76038b

…ccess and update related functions. Run black

		@@ -0,0 +1,267 @@
		# ___________________________________________________________________________


		return self.factorial_results

		# TODO: Overhaul plotting functions to not use strings



		def compute_correlation_matrix(
		covariance_matrix, var_name: list = None, significant_digits=3

Conversation

smondal13 commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fixes # .

Summary/Motivation:

Changes proposed in this PR:

Legal Acknowledgement

Uh oh!

smondal13 commented Jun 23, 2025

Uh oh!

adowling2 commented Jun 24, 2025

Uh oh!

adowling2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smondal13 Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

smondal13 commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adowling2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adowling2 commented Mar 17, 2026

Uh oh!

smondal13 commented Mar 17, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smondal13 commented Jun 23, 2025 •

edited

Loading

smondal13 Jul 1, 2025 •

edited

Loading

smondal13 commented Jul 1, 2025 •

edited

Loading