Skip to content

[Pyomo.DoE] update documentation #3812

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
smondal13 wants to merge 37 commits into
base: main
Choose a base branch
from
+230 −77
Open

[Pyomo.DoE] update documentation #3812

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
04fdcf0
Add small changes in `doe.rst` and a new local `.gitignore` script
smondal13 Dec 9, 2025
5f2c58c
Update the `doe.rst` documentation
smondal13 Dec 11, 2025
7fdc3a9
Add new figure and update `doe.rst`
smondal13 Dec 11, 2025
4c04187
Add the new figures and new pseudo A-optimality and a code that is te…
smondal13 Dec 12, 2025
91a6bfc
Merge branch 'Pyomo:main' into doe-update-documentation
smondal13 Jan 7, 2026
ea5e2f1
Merge branch 'Pyomo:main' into doe-update-documentation
smondal13 Jan 9, 2026
ce6e8cc
Fix `ParmEst` to `Parmest` and add `A-optimality`
smondal13 Jan 9, 2026
f832acd
Add `A-optimality`
smondal13 Jan 9, 2026
55af60a
Remove local `gitignore`
smondal13 Jan 9, 2026
ee519c9
Add `literalinclude` instead of copy-pasted code.
smondal13 Jan 12, 2026
4a9f2c8
Add the example as a single block of code instead of multiple blocks …
smondal13 Jan 12, 2026
054f348
Merge branch 'main' into doe-update-documentation
smondal13 Jan 12, 2026
76b21b1
Merge branch 'main' into doe-update-documentation
blnicho Jan 13, 2026
f0f54c5
Merge branch 'main' into doe-update-documentation
smondal13 Jan 29, 2026
ab28e82
Add contribution and minor text correction
smondal13 Feb 6, 2026
04e00f4
Merge branch 'main' into doe-update-documentation
smondal13 Feb 6, 2026
5295971
Add `Sphinx` label for Pyomo.DAE and Pyomo.DoE
smondal13 Feb 6, 2026
cc32352
Merge remote-tracking branch 'refs/remotes/origin/doe-update-document…
smondal13 Feb 6, 2026
3bb025a
Add the workshop flowchart
smondal13 Feb 6, 2026
22b9417
Merge branch 'main' into doe-update-documentation
blnicho Feb 10, 2026
6169d98
Apply suggestions from code review
smondal13 Feb 10, 2026
0c6af72
Merge branch 'main' into doe-update-documentation
smondal13 Feb 10, 2026
fc6a523
Delete unused images and fix image rendering issue.
smondal13 Feb 10, 2026
641ce52
Merge branch 'main' into doe-update-documentation
smondal13 Feb 10, 2026
654f99b
Add clarification and note on confidence ellipse
smondal13 Feb 11, 2026
4d5bb86
Merge branch 'main' into doe-update-documentation
smondal13 Feb 11, 2026
5a99b61
Enlage the workflow
smondal13 Feb 11, 2026
9ba8b4a
Merge branch 'main' into doe-update-documentation
smondal13 Feb 12, 2026
84a9f2d
Merge branch 'Pyomo:main' into doe-update-documentation
smondal13 Feb 17, 2026
b48fd32
Add more arguments in `reactor_example.py`
smondal13 Feb 17, 2026
5cde1a6
Add sudden jump in the sensitivity plot
smondal13 Feb 20, 2026
891fee1
Merge branch 'Pyomo:main' into doe-update-documentation
smondal13 Feb 20, 2026
7b3882d
Update isothermal explanation in `doe.rst` [skip ci]
smondal13 Feb 20, 2026
0d3169c
Merge branch 'main' into doe-update-documentation
smondal13 Feb 23, 2026
0a3cb04
Merge branch 'main' into doe-update-documentation
smondal13 Mar 6, 2026
bfa34dc
Implement Alex's suggestion
smondal13 Mar 6, 2026
7c2fccf
Clarify description of A-optimality in documentation
smondal13 Mar 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed doc/OnlineDocs/explanation/analysis/doe/FIM_sensitivity.png
View file
Open in desktop
Binary file not shown.
279 changes: 211 additions & 68 deletions doc/OnlineDocs/explanation/analysis/doe/doe.rst
View file
Open in desktop

Large diffs are not rendered by default.

Binary file added doc/OnlineDocs/explanation/analysis/doe/example_reactor_compute_FIM_A_opt.png
View file
Open in desktop
Copy link
Member

@blnicho blnicho Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is does the top row of this plot (T=300) look strange? The optimality criteria is positive there but negative everywhere else? The previous plots from this example didn't have this artifact.

Copy link
Contributor Author

@smondal13 smondal13 Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That top row at T=300K represents the worst design in the space. Because we are minimizing the A-optimality criteria, the maximum positive value is highly unfavorable. Physically, this makes perfect sense: the example uses the Arrhenius equation, so at a low temperature like 300K, the reaction rate drops significantly, yielding very little information for the design.

Regarding the difference from older plots: since this is strictly a documentation PR, I haven't modified any underlying model parameters. I simply generated this updated plot using the current state of the codebase. The previous plots in the docs were likely generated using an older version of the model before recent updates to the main branch. I see that the .png file in doe.rst was last changed 1year ago, but the doe/examples/result.json which is used in the example script was changed 7 months ago, and there was a change in control_points. So my understanding is that this or something else was not captured in the stable documentation. Finally, the 'sudden' visual jump at 300K is just a discretization artifact; the transition would look much smoother if we plotted this over a finer temperature grid rather than the current coarse steps.

Copy link
Member

@blnicho blnicho Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the 'sudden' visual jump at 300K is just a discretization artifact; the transition would look much smoother if we plotted this over a finer temperature grid rather than the current coarse steps.

Could you run a quick test to confirm this? Could you include both 300K and 305K in the heatmap and paste the figure here?

Copy link
Contributor Author

@smondal13 smondal13 Feb 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The plotting function uses np.linspace, so to make the computation quick, I have used the range of temperature from 300K to 350K and used 6 points. I think it will help with the idea that the jump in value is actually not a jump, but a gradual change.

example_reactor_compute_FIM_A_opt example_reactor_compute_FIM_D_opt example_reactor_compute_FIM_E_opt example_reactor_compute_FIM_ME_opt example_reactor_compute_FIM_pseudo_A_opt

Copy link
Contributor Author

@smondal13 smondal13 Feb 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have also added points from 300K -> 305K; this will make it clearer.

example_reactor_compute_FIM_A_opt example_reactor_compute_FIM_D_opt example_reactor_compute_FIM_E_opt example_reactor_compute_FIM_ME_opt example_reactor_compute_FIM_pseudo_A_opt

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/OnlineDocs/explanation/analysis/doe/example_reactor_compute_FIM_D_opt.png
View file
Open in desktop
Copy link
Member

@blnicho blnicho Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment here about the top row. Something seems off in these results.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/OnlineDocs/explanation/analysis/doe/example_reactor_compute_FIM_E_opt.png
View file
Open in desktop
Copy link
Member

@blnicho blnicho Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment here about the top row. Something seems off in these results.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/OnlineDocs/explanation/analysis/doe/example_reactor_compute_FIM_ME_opt.png
View file
Open in desktop
Copy link
Member

@blnicho blnicho Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment here about the top row. Something seems off in these results.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ...nlineDocs/explanation/analysis/doe/example_reactor_compute_FIM_pseudo_A_opt.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed doc/OnlineDocs/explanation/analysis/doe/flowchart.png
View file
Open in desktop
Binary file not shown.
Binary file removed doc/OnlineDocs/explanation/analysis/doe/grid-1.png
View file
Open in desktop
Binary file not shown.
Binary file added doc/OnlineDocs/explanation/analysis/doe/pyomo_workflow_new.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed doc/OnlineDocs/explanation/analysis/doe/uml.png
View file
Open in desktop
Binary file not shown.
2 changes: 2 additions & 0 deletions doc/OnlineDocs/explanation/modeling/dae.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _pyomo.dae:

Dynamic Optimization with pyomo.DAE
===================================

Expand Down
17 changes: 11 additions & 6 deletions pyomo/contrib/doe/examples/reactor_example.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,10 @@
# Example for sensitivity analysis on the reactor experiment
# After sensitivity analysis is done, we perform optimal DoE
def run_reactor_doe(
n_points_for_design=9,
n_points_for_C0: int = 9,
n_points_for_T0: int = 9,
C0_bounds_for_factorial: tuple = (1, 5),
T0_bounds_for_factorial: tuple = (300, 700),
compute_FIM_full_factorial=True,
plot_factorial_results=True,
figure_file_name="example_reactor_compute_FIM",
Expand All @@ -31,8 +34,10 @@ def run_reactor_doe(

Parameters
----------
n_points_for_design : int, optional
number of points to use for the design ranges, by default 9
n_points_for_C0 : int, optional
number of points to use for the C0 design range, by default 9
n_points_for_T0 : int, optional
number of points to use for the T0 design range, by default 9
compute_FIM_full_factorial : bool, optional
whether to compute the full factorial design, by default True
plot_factorial_results : bool, optional
Expand Down Expand Up @@ -90,8 +95,8 @@ def run_reactor_doe(
if compute_FIM_full_factorial:
# Make design ranges to compute the full factorial design
design_ranges = {
"CA[0]": [1, 5, n_points_for_design],
"T[0]": [300, 700, n_points_for_design],
"CA[0]": [*C0_bounds_for_factorial, n_points_for_C0],
"T[0]": [*T0_bounds_for_factorial, n_points_for_T0],
}

# Compute the full factorial design with the sequential FIM calculation
Expand Down Expand Up @@ -155,4 +160,4 @@ def run_reactor_doe(


if __name__ == "__main__":
run_reactor_doe()
run_reactor_doe(figure_file_name=None)
9 changes: 6 additions & 3 deletions pyomo/contrib/doe/tests/test_doe_solve.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -616,7 +616,8 @@ def test_doe_full_factorial(self):
923636.598578955,
]
ff = run_reactor_doe(
n_points_for_design=2,
n_points_for_C0=2,
n_points_for_T0=2,
compute_FIM_full_factorial=False,
plot_factorial_results=False,
run_optimal_doe=False,
Expand Down Expand Up @@ -884,7 +885,8 @@ def cleanup_files():

# Run the reactor example
run_reactor_doe(
n_points_for_design=1,
n_points_for_C0=1,
n_points_for_T0=1,
compute_FIM_full_factorial=True,
plot_factorial_results=True,
figure_file_name=prefix_linear,
Expand All @@ -902,7 +904,8 @@ def cleanup_files():

# Run the reactor example with log scale
run_reactor_doe(
n_points_for_design=1,
n_points_for_C0=1,
n_points_for_T0=1,
compute_FIM_full_factorial=True,
plot_factorial_results=True,
figure_file_name=prefix_log,
Expand Down
Loading