[WIP] Nested decomp

[cristianallara]

Fixes # .

Summary/Motivation:

Changes proposed in this PR:

Legal Acknowledgement

By contributing to this software project, I 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.

[codecov-io]

Codecov Report

Merging #389 into master will increase coverage by 1.55%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #389      +/-   ##
==========================================
+ Coverage    64.7%   66.25%   +1.55%     
==========================================
  Files         442      487      +45     
  Lines       61511    63170    +1659     
==========================================
+ Hits        39799    41853    +2054     
+ Misses      21712    21317     -395

Impacted Files	Coverage Δ
pyomo/pysp/scenariotree/preprocessor.py	61.06% <0%> (-9.88%)	⬇️
pyomo/util/modeling.py	90.9% <0%> (-9.1%)	⬇️
pyomo/solvers/plugins/solvers/IPOPT.py	89.18% <0%> (-2.4%)	⬇️
pyomo/solvers/plugins/solvers/CONOPT.py	48.27% <0%> (-2.33%)	⬇️
pyomo/core/base/misc.py	79.03% <0%> (-1.56%)	⬇️
pyomo/gdp/util.py	79.31% <0%> (-1.18%)	⬇️
...ers/plugins/solvers/direct_or_persistent_solver.py	43.6% <0%> (-1.01%)	⬇️
pyomo/core/base/config.py	65.75% <0%> (-0.92%)	⬇️
pyomo/solvers/plugins/solvers/SCIPAMPL.py	25.3% <0%> (-0.63%)	⬇️
pyomo/pysp/scenariotree/manager_solver.py	90.42% <0%> (-0.62%)	⬇️
... and 105 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 3dadc65...6b26e5e. Read the comment docs.

[whart222]

@jsiirola I seem to recall discussing with you that this example would sit better as a contrib package. Do you recall?

[carldlaird]

Not sure if you discussed this with John or not, but I agree. I asked for this to be moved from core Pyomo to examples, however, this was before contrib really existed. I think we should add an examples directory to contrib, and put this there.

We have asked Cristiana to move this already (and she did), so let's make sure we know where we want it before asking again (or move it ourselves).

[whart222]

Do we really want a pyomo.contrib.examples sub-package? I hadn't thought of that, and I'm inclined to use a simpler directory structure.

[carldlaird]

Everything should be made as simple as possible, but no simpler.

[mrmundt]

This has been added to the Archived design discussions wiki; will close for now.