Adding another API style

[simonbowly]

Meta issue: discussion so far seems to have unearthed two possible usage patterns.

Using dataframe columns as a namespace

This was the original design and is what the documentation and examples focuses on. In this mode, we expect all data relating to a given index to reside in one dataframe (e.g. sparse pairwise index for an assignment problem, with data for costs and limits). It then seems natural to create new variables as additional columns so that they live with relevant data which can be used when building constraints.

Using python variables as a namespace

In this mode, various series of vars and data exist separately as different python variables. To create constraints, the user needs to align them as dataframes before using the accessors. In this situation, convenience functions which create constraints from aligned series are a better pattern.

Relevant discussions on other issues:

• https://github.com/Gurobi/gurobipy-pandas/issues/39
• https://github.com/Gurobi/gurobipy-pandas/issues/42

[simonbowly]

For the initial release we plan to focus on the first approach, encouraging users to keep their data and variables which naturally fit the same index aligned in the same dataframe.

[Dr-Irv]

You can solve the alignment problem in the second style as follows (using incorrect syntax):

pd_add_vars(model, pd.DataFrame | pd.Index | pd.Series, lb, ub, vtype, name=None)
accessor.pd_add_constrs(model, pd.DataFrame | pd.Index | pd.Series, lhs, sense, rhs, *, name)

In other words, if you make pd_add_vars() and pd_add_constrs as top level functions, and include a required parameter of a DataFrame or Index or Series, everything becomes quite clean, and you get type checking on these 2 important functions.

[simonbowly]

Top level functions are added, what's left is to add a page of documentation for each style to show pros/cons (typing support, data/variable separation, method chaining, maintaining series alignment)

[simonbowly]

There are example of both styles in the docs. For reference:

• Project-team allocation shows creating all variables as series using the free functions
• L1 norm regression shows building all variables and constraints in the method chaining style using accessors

[Dr-Irv]

There are example of both styles in the docs

OK, but earlier you wrote this:

what's left is to add a page of documentation for each style to show pros/cons (typing support, data/variable separation, method chaining, maintaining series alignment)

Does that exist? If not, do you have an issue to track it?

[simonbowly]

Yes, there is a section in the reference covering typing, and the usage page covers both styles. If you feel something is missing, feel free to raise an issue or PR.

[Dr-Irv]

Yes, there is a section in the reference covering typing, and the usage page covers both styles. If you feel something is missing, feel free to raise an issue or PR.

Took a look, and I think what you have is good for now. It will be interesting to see how people react to this new package.