ExternalPyomoModel

(class from pyomo.contrib.pynumero.interfaces.external_pyomo_model)

class pyomo.contrib.pynumero.interfaces.external_pyomo_model.ExternalPyomoModel(input_vars, external_vars, residual_cons, external_cons, solver_class=None, solver_options=None, timer=None)

Bases: ExternalGreyBoxModel

This is an ExternalGreyBoxModel used to create an external model from existing Pyomo components. Given a system of variables and equations partitioned into “input” and “external” variables and “residual” and “external” equations, this class computes the residual of the “residual equations,” as well as their Jacobian and Hessian, as a function of only the inputs.

Pyomo components:

f(x, y) == 0 # “Residual equations” g(x, y) == 0 # “External equations”, dim(g) == dim(y)

Effective constraint seen by this “external model”:

F(x) == f(x, y(x)) == 0 where y(x) solves g(x, y) == 0

__init__(input_vars, external_vars, residual_cons, external_cons, solver_class=None, solver_options=None, timer=None)

Arguments:

input_vars: list

List of variables sent to this system by the outer solver

external_vars: list

List of variables that are solved for internally by this system

residual_cons: list

List of equality constraints whose residuals are exposed to the outer solver

external_cons: list

List of equality constraints used to solve for the external variables

solver_class: Subclass of ImplicitFunctionSolver

The solver object that is used to converge the system of equations defining the implicit function.

solver_options: dict

Options dict for the ImplicitFunctionSolver

timer: HierarchicalTimer

HierarchicalTimer object to which new timing categories introduced will be attached. If None, a new timer will be created.

Methods

__init__(input_vars, external_vars, ...[, ...])	Arguments: input_vars: list List of variables sent to this system by the outer solver external_vars: list List of variables that are solved for internally by this system residual_cons: list List of equality constraints whose residuals are exposed to the outer solver external_cons: list List of equality constraints used to solve for the external variables solver_class: Subclass of ImplicitFunctionSolver The solver object that is used to converge the system of equations defining the implicit function. solver_options: dict Options dict for the ImplicitFunctionSolver timer: HierarchicalTimer HierarchicalTimer object to which new timing categories introduced will be attached. If None, a new timer will be created.
calculate_external_constraint_multipliers(...)	Calculates the multipliers of the external constraints from the multipliers of the residual constraints (which are provided by the "outer" solver).
calculate_reduced_hessian_lagrangian(hlxx, ...)	Performs the matrix multiplications necessary to get the reduced space Hessian-of-Lagrangian term from the full-space terms.
equality_constraint_names()	Provide the list of string names corresponding to any residuals for this external model.
evaluate_equality_constraints()	Compute the residuals from the model (using the values set in input_values) and return as a numpy array
evaluate_grad_objective([out])	Compute the gradient of the objective from the values set in input_values
evaluate_hessian_equality_constraints()	This method actually evaluates the sum of Hessians times multipliers, i.e. the term in the Hessian of the Lagrangian due to these equality constraints.
evaluate_hessian_external_variables()
evaluate_hessians_of_residuals()	This method computes the Hessian matrix of each equality constraint individually, rather than the sum of Hessians times multipliers.
evaluate_jacobian_equality_constraints()	Compute the derivatives of the residuals with respect to the inputs (using the values set in input_values).
evaluate_jacobian_external_variables()
evaluate_jacobian_outputs()	Compute the derivatives of the outputs with respect to the inputs (using the values set in input_values).
evaluate_objective()	Compute the objective from the values set in input_values
evaluate_outputs()	Compute the outputs from the model (using the values set in input_values) and return as a numpy array
finalize_block_construction(pyomo_block)	Implement this callback to provide any additional specifications to the Pyomo block that is created to represent this external grey box model.
get_equality_constraint_scaling_factors()	Get scaling factors for the equality constraints that are exposed to a solver.
get_full_space_lagrangian_hessians()	Calculates terms of Hessian of full-space Lagrangian due to external and residual constraints.
get_output_constraint_scaling_factors()	This method is called by the solver interface to get desired values for scaling the constraints with output variables.
has_objective()
input_names()	Provide the list of string names to corresponding to the inputs of this external model.
n_equality_constraints()	This method returns the number of equality constraints.
n_inputs()	This method returns the number of inputs.
n_outputs()	This method returns the number of outputs.
output_names()	Provide the list of string names corresponding to the outputs of this external model.
set_equality_constraint_multipliers(...)	Sets multipliers for residual equality constraints seen by the outer solver.
set_equality_constraint_scaling_factors(...)	Set scaling factors for the equality constraints that are exposed to a solver.
set_external_constraint_multipliers(...)
set_input_values(input_values)	This method is called by the solver to set the current values for the input variables.
set_output_constraint_multipliers(...)	This method is called by the solver to set the current values for the multipliers of the output constraints.

Member Documentation

calculate_external_constraint_multipliers(resid_multipliers)

Calculates the multipliers of the external constraints from the multipliers of the residual constraints (which are provided by the “outer” solver).

calculate_reduced_hessian_lagrangian(hlxx, hlxy, hlyy)

Performs the matrix multiplications necessary to get the reduced space Hessian-of-Lagrangian term from the full-space terms.

equality_constraint_names()

Provide the list of string names corresponding to any residuals for this external model. These should be in the order corresponding to values returned from evaluate_residuals. Return an empty list if there are no equality constraints.

evaluate_equality_constraints()

Compute the residuals from the model (using the values set in input_values) and return as a numpy array

evaluate_grad_objective(out=None)

Compute the gradient of the objective from the values set in input_values

evaluate_hessian_equality_constraints()

This method actually evaluates the sum of Hessians times multipliers, i.e. the term in the Hessian of the Lagrangian due to these equality constraints.

evaluate_hessians_of_residuals()

This method computes the Hessian matrix of each equality constraint individually, rather than the sum of Hessians times multipliers.

evaluate_jacobian_equality_constraints()

Compute the derivatives of the residuals with respect to the inputs (using the values set in input_values). This should be a scipy matrix with the rows in the order of the residual names and the cols in the order of the input variables.

evaluate_jacobian_outputs()

Compute the derivatives of the outputs with respect to the inputs (using the values set in input_values). This should be a scipy matrix with the rows in the order of the output variables and the cols in the order of the input variables.

evaluate_objective() → float

Compute the objective from the values set in input_values

evaluate_outputs()

Compute the outputs from the model (using the values set in input_values) and return as a numpy array

finalize_block_construction(pyomo_block)

Implement this callback to provide any additional specifications to the Pyomo block that is created to represent this external grey box model.

Note that pyomo_block.inputs and pyomo_block.outputs have been created, and this callback provides an opportunity to set initial values, bounds, etc.

get_equality_constraint_scaling_factors()

Get scaling factors for the equality constraints that are exposed to a solver. These are the “residual equations” in this class.

get_full_space_lagrangian_hessians()

Calculates terms of Hessian of full-space Lagrangian due to external and residual constraints. Note that multipliers are set by set_equality_constraint_multipliers. These matrices are used to calculate the Hessian of the reduced-space Lagrangian.

get_output_constraint_scaling_factors()

This method is called by the solver interface to get desired values for scaling the constraints with output variables. Returning None means that no scaling of the output constraints is desired. Note that, depending on the solver, one may need to set solver options so these factors are used

input_names()

Provide the list of string names to corresponding to the inputs of this external model. These should be returned in the same order that they are to be used in set_input_values.

n_equality_constraints()

This method returns the number of equality constraints. You do not need to overload this method in derived classes.

n_inputs()

This method returns the number of inputs. You do not need to overload this method in derived classes.

n_outputs()

This method returns the number of outputs. You do not need to overload this method in derived classes.

output_names()

Provide the list of string names corresponding to the outputs of this external model. These should be in the order corresponding to values returned from evaluate_outputs. Return an empty list if there are no computed outputs.

set_equality_constraint_multipliers(eq_con_multipliers)

Sets multipliers for residual equality constraints seen by the outer solver.

set_equality_constraint_scaling_factors(scaling_factors)

Set scaling factors for the equality constraints that are exposed to a solver. These are the “residual equations” in this class.

set_input_values(input_values)

This method is called by the solver to set the current values for the input variables. The derived class must cache these if necessary for any subsequent calls to evaluate_outputs or evaluate_derivatives.

set_output_constraint_multipliers(output_con_multiplier_values)

This method is called by the solver to set the current values for the multipliers of the output constraints. The derived class must cache these if necessary for any subsequent calls to evaluate_hessian_outputs