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?

@jsiirola This function is a superset of the already existing compute_FIM_full_factorial() method. So, I am not sure if I should keep it under the same name since the "full" in the method name can be misleading. It can use a full factorial (changing all the decision variables) and a fractional factorial (changing some of the decision variables). This method basically analyzes the sensitivity.

@adowling2, @slilonfe5, @snarasi2, @sscini Can we name it something like compute_sensitivity_at_design_points()? Or similar to the one @jsiirola suggested, compute_FIM_from_factorial_sampling?

@smondal13 If sensitivity is what you are doing, I think compute_sensitivity_at_design_points is better.

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.

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.

Made the FIM metrics consistent in both compute_FIM_full_factorial() and compute_FIM_factorial(). Added design variable name error checking.

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?

Good point. We now support square DataFrame input and have added explicit label checks: row labels must be unique, column labels must be unique, and row/column labels must match in the same order. If any of those fail, we raise a ValueError with a specific message.

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?

This ternary block returns a pd DataFrame if var_name is passed; otherwise, it returns a numpy array.

…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-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.

Added the error message inside the logger warning.

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.

I have repaced the print with sys.stdout

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.

I have removed the strict type checks,

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

…ance error handling. Update related tests for consistency.

…d for improved design space handling

…prove output formatting and add validation for design mode arguments in compute_FIM_factorial.

…grid

…e unique row and column labels, and match between them. Add corresponding unit tests for validation.

smondal13 · 2025-07-17T13:27:26Z

+        rel_change: list = None,
+        n_designs: int = 5,
+        method="sequential",
+        df_settings=(True, None, None, 500),


Should I use this tuple? I was reluctant to use 4 different arguments for the pd df setting / configuration

smondal13 · 2025-09-24T16:27:40Z

+        rel_change: list = None,
+        n_design_points: int = None,
+        method="sequential",
+        return_df=True,


Since the method is printing the df depending on this flag, not returning it, does it make more sense to use show_df instead of return_df?

smondal13 · 2026-03-17T13:35:00Z

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


This ternary block returns a pd DataFrame if var_name is passed; otherwise, it returns a numpy array.

smondal13 · 2026-05-19T01:03:37Z

+            factorial_points = snake_traversal_grid_sampling(*design_values)
+        elif scheme_enum == SensitivityInitialization.nested_for_loop:
+            factorial_points = product(*design_values)
+


Great suggestion, and I implemented that split: traversal generation now lives in a dedicated helper (_materialize_factorial_points).
Current tests already cover traversal behavior through the public API (including invalid scheme errors and explicit nested-for-loop ordering on a 2x2 grid).

smondal13 · 2026-05-19T01:26:45Z

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


Good point. We now support square DataFrame input and have added explicit label checks: row labels must be unique, column labels must be unique, and row/column labels must match in the same order. If any of those fail, we raise a ValueError with a specific message.

smondal13 · 2026-05-19T01:38:11Z


        return self.fim_factorial_results

+    def compute_FIM_factorial(


@jsiirola Thanks for the suggestion. I agree and have refactored this in the latest update.

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

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 15 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

Replace check_matrix with assert_symmetric_positive_definite and enh…

3724c15

…ance error handling. Update related tests for consistency.

Add FactorialDesignMode enum and refactor compute_FIM_factorial metho…

49fef05

…d for improved design space handling

Refactor factorial computation and enhance tests for design modes: Im…

1d8b66d

…prove output formatting and add validation for design mode arguments in compute_FIM_factorial.

Add test for compute_FIM_factorial with nested for loop order on 2x2 …

1ea2b4d

…grid

Merge branch 'main' into sensitivity-initialization

5d5374e

Enhance compute_correlation_matrix to validate DataFrame input: ensur…

28e658d

…e unique row and column labels, and match between them. Add corresponding unit tests for validation.

smondal13 commented May 19, 2026

View reviewed changes

smondal13 added 2 commits May 18, 2026 21:42

Run black

6c40b0a

Merge branch 'main' into sensitivity-initialization

bb8cdd6

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


		return self.factorial_results

		# TODO: Overhaul plotting functions to not use strings

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!

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!

Uh oh!

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!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smondal13 commented Jun 23, 2025 •

edited

Loading

smondal13 Jul 1, 2025 •

edited

Loading

smondal13 commented Jul 1, 2025 •

edited

Loading