search

Pyomo / pyomo

An object-oriented algebraic modeling language in Python for structured optimization problems.
https://www.pyomo.org
Other
1.95k stars 504 forks source link

Establish conventions for the Pyomo API #3162

Open whart222 opened 5 months ago

whart222 commented 5 months ago

Summary

A formal description of the Pyomo API would help manage technical debt for maintenance of Pyomo.

Rationale

I've been thinking a bit about the Pyomo API as I consider strategies to replace kernels with C/C++ extensions. However, I've noted that Pyomo developers pull logic from deep in Pyomo's directory structure. For example, the identify_variables() function isn't included in pyomo.core, but needs to be pulled from pyomo.core.expr.visitor.

A clearer declaration of the Pyomo API would help manage technical debt in Pyomo. This seems timely given the maturation of pyomo.contrib capabilities, which will be treated as stable functionality in future releases.

Description

SciPy has a nice articulation of their API and associated conventions. I recommend that we consider something similar for Pyomo:

https://docs.scipy.org/doc/scipy/reference/

blnicho commented 5 months ago

@whart222 we should edit this to add a clear set of classes/methods/functions that we're going to consider the "Pyomo API" and add documentation and API tests for. It doesn't have to be perfect or complete in this issue but I think we need a starting point for what we consider the main API and how we will know when this issue is resolved.