IDAES Examples Standards

Introduction

The IDAES examples repository contains Jupyter Notebooks and associated Python code to demonstrate and teach the capabilities of the IDAES core. This page lays out standards for contributing, maintaining, and deprecating example notebooks.

Lifecycle of an example

Like all things, examples have a lifecycle of Creation → Maintenance → End-of-life.

Creation

Examples may be created for an existing feature -- something already merged into the IDAES master branch -- or for a feature being developed. In either case, the procedure for creating the example is to create a PR, add the example, get tests to pass, and get the content reviewed before merging.

In the case where the associated code is in a PR, you can work on the example in parallel by changing the idaes-pse dependency in the pyproject.toml file to point at the URL for your PR. This will need to be changed back to its original value before the example can be merged in. In this case, you should also make sure that the two PRs (the one in idaes-pse and the one in examples) reference each other in the first section of the PR conversations, so it is easy to track this dependency.

Maintenance

Once an example is merged into the main branch, it is expected to continue to pass tests even as the IDAES codebase changes. If an example starts failing tests there are three options:

• If somebody is willing to fix it in the current release cycle, they should open a PR and include it in the release board.
• If somebody is willing to fix it by the next release cycle, they should open a PR that moves the example to a holding area (mechanics specified elsewhere). This is a temporary condition. It will not be included in documentation or tests, but the code will remain in the examples repo for the current release.
• If nobody volunteers to fix it before the freeze date for the next release cycle, it will be moved to an 'archive' area where it is no longer distributed as part of IDAES. This also applies to 'held' examples from the previous release cycle that are not yet working and reviewed.

End-of-life

As described in the Maintenance section above, examples will move to an archive area (different repository) when they are not working and there is no maintainer (or possibly other reasons). They may stay in this area for a long time, but there is no guarantee of preservation. It is expected that periodically the archive will be cleaned up and outdated material removed. Anyone interested in long-term preservation of an example should handle this themselves.

Content standards

This section provides an overview of the expected contents and placement of examples in the examples repository. For details on how to create and test your example, see README-developer.md in that repository.

Where to put a new notebook

Use the following to decide where to put any new Jupyter notebook:

1. Will it be included in the online docs?
   Yes: Put under notebooks/docs
   No: Go to 2
2. Will it be actively maintained to handle any changes in IDAES core?
   Yes: Put under notebooks/active
   No: Do not put it in this repo. Put it in the archive area of the publications repo.

All these directories have their own subdirectories for grouping similar notebooks. Place the new notebook in an appropriate subdirectory.

Where to put supporting data and code

Data files and images should go in the same directory as the notebook.

Python modules should go under an appropriate subpackage under idaes_examples/mod, e.g., idaes_examples/mod/methanol/methanol_ideal_vapor.py. Note that mod is a Python package (unlike notebooks), and new directories should have the usual __init__.py file.

Contents of a notebook

Every notebook has this general structure:

1st cell: Copyright header. See copyright headers section in the developer README for details.

2nd cell: Markdown cell with:

• '# Title of notebook'
• 'Author(s): {name}, [{name}, ...]'
• Description of notebook purpose and content

Remaining cells: Code and descriptive markdown.

• For the markdown cells, please use markdown headings and subheadings (i.e. using '##', '###', etc.), as these will be transformed into a navigation sidebar in the documentation. Skipping over a level of headings (e.g. from '#' to '###') will cause a warning when building the documentation, so please don't do that just to create bold text (use Markdown's '**' or in a pinch HTML tags instead).
• For code cells, use cell tags to indicate testing, tutorial exercises and solutions, and for skipping cells during automated builds. See the Jupyter Notebook cell tags section of the developer README for more information.
• For most code cells, you should provide documentation in markdown before the cell of what it is doing, but also feel free to include inline comments to make reading the code easier.
• You don't need to put all the Python code in the notebook. Boilerplate and/or supporting code should be packaged into a Python module, put in the idaes_examples/mod package and imported, e.g.: from idaes_examples.mod.my_subpackage import my_module

Reviewing notebooks

Just like code in idaes-pse, the examples need to pass tests and get approved by reviewers before they can be merged. The developer README has instructions on how to run tests on your machine. Tests will also be run in Github CI on every commit to a PR. Once a notebook passes tests, it still needs to pass review criteria:

• Does it have the required content (see previous section)?
• Is the spelling, grammar, etc. correct and are the descriptions clear?
• If it is in the documentation section, does it look "good" once rendered? e.g., are the formulas and diagrams showing up? To check this, you can click on the link next to the ReadTheDocs task in the tests run in the PR -- this will take you to a preview of the documentation.

With approving reviews, the notebook can be merged into the repository!