Engineering Design Interface (EDI) Contrib Package

[codykarcher]

Fixes # N/A

Summary/Motivation:

This contrib is a light wrapper on the pyomo API that allows for alternative problem construction

Changes proposed in this PR:

• No major changes to base pyomo
• the .gitignore file has one update
• New documentation added
• New contrib package added

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.

[blnicho]

First batch of comments on the documentation (lots of duplicate comments across different files)

[blnicho]

Suggested change

Coding a black-box model often represents a significant effort, and it is therefore desirable to have the black-box work in many situations. A common case is to have a black-box model with a scalar input variable perform vectorized operations, ie, take in a vector and return a vector. In the more general case, this can be thought of as passing in multiple run-cases as input to the black-box model.

Coding a black-box model often represents a significant effort, and it is therefore desirable to have the black-box work in many situations. A common case is to have a black-box model with a scalar input variable perform vectorized operations, i.e., take in a vector and return a vector. In the more general case, this can be thought of as passing in multiple run-cases as input to the black-box model.

[blnicho]

Suggested change

	EDI installs as a part of the standard pyomo install:
	EDI installs as a part of the standard Pyomo install:

[blnicho]

Suggested change

	EDI also requires packages that are optional in base pyomo:
	EDI also requires packages that are optional in base Pyomo:

[blnicho]

Why did you hard-code the units here instead of reading it from self.outputs['z']?

[blnicho]

I'm not sure what is meant by "improves coverage metrics". Originally I thought this might be EDI-specific terminology but I didn't see it mentioned anywhere else in the documentation.

[blnicho]

Suggested change

	Black-box objectives are not currently supported and are awaiting an update to pyomo (see `this issue <https://github.com/codykarcher/pyomo/issues/5>`_).
	Black-box objectives are not currently supported and are awaiting an update to Pyomo (see `this issue <https://github.com/codykarcher/pyomo/issues/5>`_).

[blnicho]

Suggested change

	The Constraint constructor is a very thin wrapper on pyomo ``Constraint``, and so experienced pyomo users will not see any significant differences from base pyomo.
	The Constraint constructor is a very thin wrapper on Pyomo :py:class:`Constraint <pyomo.environ.Constraint>`, and so experienced Pyomo users will not see any significant differences from base Pyomo.

[blnicho]

I'd recommend including this as a docstring in the code and using the automethod Sphinx command instead of writing this directly in the documentation.

[blnicho]

I'd recommend including this as a docstring in the code and using the automethod Sphinx command instead of writing this directly in the documentation.

[blnicho]

Typo: pyomo.contrib.edi.formulation
(appears multiple times in this file)

[blnicho]

Next batch of comments. I'm still going through the code.

[blnicho]

Suggested change

The EDI constraint constructor is essentially a direct pass through to base pyomo. Constraints will be added to the ``pyomo.ConcreteModel`` in increasing order with key ``constraint_###`` where the the index of the objective appears after the underscore. First constraint is labeled as ``constraint_1``, and constraint names are never padded with zeros. RuntimeConstraints also contribute to this counter.

The EDI constraint constructor is essentially a direct pass through to base Pyomo. Constraints will be added to the ``pyomo.ConcreteModel`` in increasing order with key ``constraint_###`` where the the index of the objective appears after the underscore. First constraint is labeled as ``constraint_1``, and constraint names are never padded with zeros. RuntimeConstraints also contribute to this counter.

[blnicho]

Suggested change

	* Indexed variables must be broken up using either indices or a pyomo rule (see `this issue <https://github.com/codykarcher/pyomo/issues/3>`__)
	* Indexed variables must be broken up using either indices or a Pyomo rule (see `this issue <https://github.com/codykarcher/pyomo/issues/3>`__)

[blnicho]

Suggested change

EDI refers to these types of constraints as ``RuntimeConstraints`` because they are not constructed until they are needed by the solver. A particular subset of Runtime Constraints of interest are Black-Box constraints, that is, constraints which call to an external routine. To the average pyomo and EDI user, ``RuntimeConstraints`` are for all intents and purposes Black-Box constraint, and the distinction is semantic.

EDI refers to these types of constraints as ``RuntimeConstraints`` because they are not constructed until they are needed by the solver. A particular subset of Runtime Constraints of interest are Black-Box constraints, that is, constraints which call to an external routine. To the average Pyomo and EDI user, ``RuntimeConstraints`` are for all intents and purposes Black-Box constraints, and the distinction is semantic.

[blnicho]

Suggested change

	In this context, a *Black-Box* is defined as a routine that performs hidden computation not visible EDI, pyomo, or more generally the optimization algorithm. However, it is **not** assumed that black-boxes are unable to return gradient information. A black-box in this context may be capable of returning arbitrary derivative information.
	In this context, a *Black-Box* is defined as a routine that performs hidden computation not visible EDI, Pyomo, or more generally the optimization algorithm. However, it is **not** assumed that black-boxes are unable to return gradient information. A black-box in this context may be capable of returning arbitrary derivative information.

[blnicho]

Suggested change

	First, we need to create an object which is visible to pyomo/EDI that calls the black-box function. EDI calls this a ``BlackBoxFunctionModel``, and it is a base class that gets inherited into the objects you will create as a user.
	First, we need to create an object which is visible to Pyomo/EDI that calls the black-box function. EDI calls this a ``BlackBoxFunctionModel``, and it is a base class that gets inherited into the objects you will create as a user.

[blnicho]

Suggested change

	There is a ``checkOutputs()`` method that is not supported in the current version. Contact the developers if you desire this functionality, but the following the practices described in this documentation should render the need for this moot.
	There is a ``checkOutputs()`` method that is not supported in the current version. Contact the developers if you desire this functionality, but following the practices described in this documentation should render the need for this moot.

[blnicho]

Why import this if it isn't used in this example?

[blnicho]

Suggested change

	The pyomo EDI interface is developed and maintained by `Cody Karcher <https://github.com/codykarcher>`_
	The Pyomo EDI interface is developed and maintained by `Cody Karcher <https://github.com/codykarcher>`_

[blnicho]

Why are you importing the same class multiple times with different names? I'm guessing it's an effort to provide shorter name aliases to users but I don't think this is a good idea. It obfuscates the real class name and will cause confusion over the differences between them. If the user doesn't want to type the full class name then the user can do their own class aliasing.

[blnicho]

This class isn't described in the documentation