This module is used for interfacing an external model as
a block in a Pyomo model.
An ExternalGreyBoxModel is a model that does not
provide constraints explicitly as algebraic expressions, but
instead provides a set of methods that can compute the residuals
of the constraints (or outputs) and their derivatives.
This allows one to interface external codes (e.g., compiled
external models) with a Pyomo model.
- Note: To solve a Pyomo model that contains these external models
we have a specialized interface built on PyNumero that provides
an interface to the CyIpopt solver.
constraints: c(x) = 0
outputs: y = c(x)
- To use this interface:
Create a class that is derived from ExternalGreyBoxModel and
implement the necessary methods. This derived class must provide
a list of names for: the inputs to your model, the equality constraints
(or residuals) that need to be converged, and any outputs that
are computed from your model. It will also need to provide methods to
compute the residuals, outputs, and the jacobian of these with respect to
the inputs. Implement the methods to evaluate hessians if applicable.
See the documentation on ExternalGreyBoxModel for more details.
Create a Pyomo model and make use of the ExternalGreyBoxBlock
to produce a Pyomo modeling component that represents your
external model. This block is a Pyomo component, and when you
call set_external_model() and provide an instance of your derived
ExternalGreyBoxModel, it will automatically create pyomo variables to
represent the inputs and the outputs from the external model. You
can implement a callback to modify the Pyomo block after it is
constructed. This also provides a mechanism to initialize variables,
etc.
Create a PyomoGreyBoxNLP and provide it with the Pyomo model
that contains the ExternalGreyBoxBlocks. This class presents
an NLP interface (i.e., the PyNumero NLP abstract class), and
can be used with any solver that makes use of this interface
(e.g., the CyIpopt solver interface provided in PyNumero)
See pyomo/contrib/pynumero/examples/external_grey_box for examples
of the use of this interface.