Skip to content

Reorganizing ParmEst and Pyomo.DoE Documentation Pages#3904

Open
slilonfe5 wants to merge 18 commits into
Pyomo:mainfrom
slilonfe5:parmest-doe-doc-reorg
Open

Reorganizing ParmEst and Pyomo.DoE Documentation Pages#3904
slilonfe5 wants to merge 18 commits into
Pyomo:mainfrom
slilonfe5:parmest-doe-doc-reorg

Conversation

@slilonfe5
Copy link
Copy Markdown
Member

@slilonfe5 slilonfe5 commented Apr 3, 2026

Fixes # .

Summary/Motivation:

The ParmEst and Pyomo.DoE documentation webpages need a major reorganization ahead of the American Control Conference Workshop in May. This update will enable new/existing users to access recent/forthcoming capabilities in ParmEst and Pyomo.DoE

Changes proposed in this PR:

  • Remove outdated/non-informative pages from the ParmEst and Pyomo.DoE documentation webpages
  • Update documentation files to capture important features/capabilities in ParmEst and Pyomo.DoE as listed below.
    Proposed ParmEst documentation page:
    - Overview
    - Installation Instructions
    - Quick Start Guide
    - Objective Options
    - Uncertainty Quantification
    - Estimability Analysis
    Proposed Pyomo.DoE documentation page:
    - Overview
    - Quick Start Guide
    - Experiment Abstraction
    - Objective Options
    - Multiple Experiments
    - Parameter Uncertainty

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:

  1. I agree my contributions are submitted under the BSD license.
  2. 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.

@slilonfe5 slilonfe5 marked this pull request as ready for review April 7, 2026 16:08
@slilonfe5
Copy link
Copy Markdown
Member Author

slilonfe5 commented Apr 7, 2026

@mrmundt @blnicho @jsiirola @adowling2, This PR is ready for review. As mentioned in the description, we want to reorganize the documentation webpages of ParmEst and Pyomo.DoE into a structure that is informative, capturing the most up-to-date capabilities, ahead of the ACC Pyomo workshop in May. This PR is meant to create background documentation files and structures for @sscini and @smondal13 to quickly update after their PRs get merged.

A major question is whether we should remove the other existing ParmEst documentation pages (e.g., data reconciliation, scenario creation).

Thank you.

@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 8, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.93%. Comparing base (3d3ffae) to head (dbe9f2c).
⚠️ Report is 295 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #3904      +/-   ##
==========================================
- Coverage   89.93%   89.93%   -0.01%     
==========================================
  Files         902      902              
  Lines      106393   106393              
==========================================
- Hits        95683    95680       -3     
- Misses      10710    10713       +3     
Flag Coverage Δ
builders 29.19% <ø> (+<0.01%) ⬆️
default 86.23% <ø> (?)
expensive 35.64% <ø> (?)
linux 87.38% <ø> (-2.04%) ⬇️
linux_other 87.38% <ø> (ø)
oldsolvers 28.10% <ø> (+<0.01%) ⬆️
osx 82.71% <ø> (ø)
win 85.80% <ø> (-0.01%) ⬇️
win_other 85.80% <ø> (-0.01%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@blnicho blnicho self-requested a review May 5, 2026 19:01
@sscini sscini moved this from Development to Ready for design review in ParmEst & Pyomo.DoE Development May 6, 2026
Copy link
Copy Markdown
Member

@jsiirola jsiirola left a comment

Choose a reason for hiding this comment

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

Overall this is pretty straightforward, but I have a number of suggested changes.

Comment thread doc/OnlineDocs/explanation/analysis/doe/overview.rst Outdated
A confidence ellipse is a geometric representation of the uncertainty in parameter
estimates. It is derived from the covariance matrix :math:`\mathbf{V}`.

In order to solve problems of the above, Pyomo.DoE implements the 2-stage stochastic program. Please see Wang and Dowling (2022) for details. No newline at end of file
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Consider adding this citation to reference/bibliography.rst and referencing it here.

Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/abstraction.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/uncertainty.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/parmest/covariance.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/parmest/estimability.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/parmest/objective.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst
Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst Outdated
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After creating the subclass of the ``Experiment`` class, exploratory analysis is
suggested to enumerate the design space to check if the problem is identifiable,
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The discussion of identifiability appears overly binary. A near-singular or approximately zero Fisher Information Matrix is not the only scenario implying practical non-identifiability. Even when the FIM non-singular, a very large condition number may indicate that certain parameter directions are only weakly informed by the data, corresponding to extremely small eigenvalues and unstable parameter estimates (practical identifiability issues). In such cases, uncertainty remains high and estimates may be highly sensitive to noise, limiting the extent to which experimental design alone can improve parameter estimation. Consider distinguishing more clearly between structural identifiability and practical identifiability arising from ill-conditioning of the FIM.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

@snarasi2 This PR is only meant to organize the order of the documentation pages into the format outlined in the summary. The contents in guide.rst and overview.rst (for DoE) are what currently exist in the documentation page. This PR does not make any changes to the contents but establishes a general structure for the ParmEst and Pyomo.DoE documentation webpages, which will be later updated by @sscini, @smondal13, and @snarasi2. I will save these comments for @smondal13 and @snarasi2 to work on them during their future PRs to update the contents of the Pyomo.DoE documentation webpage.

Comment thread doc/OnlineDocs/explanation/analysis/doe/guide.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/overview.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/overview.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/overview.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/doe/overview.rst Outdated
Comment thread doc/OnlineDocs/explanation/analysis/parmest/estimability.rst Outdated
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
slilonfe5 and others added 10 commits May 9, 2026 15:40
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Co-authored-by: John Siirola <jsiirola@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Ready for design review

Development

Successfully merging this pull request may close these issues.

6 participants