API Reference

Bipartite Matching

The following mods can be imported from gurobi_optimods.bipartite_matching:

maximum_bipartite_matching(graph, nodes1, nodes2, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve a maximum cardinality bipartite matching problem on the given graph.

Parameters:
graphspmatrix or Graph or DataFrame

A graph, specified either as a scipy.sparse adjacency matrix, networkx graph, or pandas dataframe.

nodes1ndarray or str

Nodes in the first bipartite set. If graph is a scipy sparse matrix, nodes1 must be a numpy array. If graph is a pandas dataframe, nodes1 must be a column name. If graph is a networkx graph, nodes1 must be a list.

nodes2ndarray or str

Nodes in the second bipartite set. If graph is a scipy sparse matrix, nodes2 must be a numpy array. If graph is a pandas dataframe, nodes2 must be a column name. If graph is a networkx graph, nodes2 must be a list.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
spmatrix or Graph or DataFrame

A subgraph of the original graph (with the same data type) specifying the maximum matching

Line Optimization in Public Transportation Networks

The following mods can be imported from gurobi_optimods.line_optimization:

line_optimization(node_data, edge_data, line_data, linepath_data, demand_data, frequencies, shortest_paths=True, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve the line planning problem.

Parameters:
node_dataDataFrame

DataFrame with information on the nodes/stations. The frame must include “source”.

edge_dataDataFrame

DataFrame with edges / connections between stations and associated attributes. The frame must include “source”, “target”, and “time”

demand_dataDataFrame

DataFrame with node/station demand information. It must include “source”, “target”, and “demand”. The demand value must be non-negative.

line_dataDataFrame

DataFrame with general line information. It must include “linename”, “capacity”, “fix_cost”, and “operating_cost”.

linepath_dataDataFrame

DataFrame with information on the line routes/paths. It must include “linename”, “edge_source”, and “edge_target”.

frequency: List

List with possible frequencies: How often the line can be operated in the considered time horizon.

shortest_pathsbool

Parameter to choose the strategy. Default value is true and strategy 1 is used, i.e., passengers travel along shortest paths. Set to False if all possible paths are allowed. In that case, a multi-objective approach is used to first minimize line operating cost and then minimize passengers travel time.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
tuple
  • Cost of the optimal line concept (line frequency)

  • list of line-frequency tuples (optimal line concept)

Maximum Flow

The following mods can be imported from gurobi_optimods.max_flow:

max_flow(graph, source, sink, **kwargs)

Solve the maximum flow problem for a given graph.

Parameters:
graphspmatrix or Graph or DataFrame

A graph, specified either as a scipy.sparse adjacency matrix, networkx graph, or pandas dataframe. These contain the capacity for each edge. In the networkx (pandas dataframe) case, we expect the edge attribute (column name) capacity. Please see the example in the documentation.

sourceint or str

The source (or origin) node for the maximum flow.

sinkint or str

The sink (or destination) node for the maximum flow.

Returns:
flow: float

Maximum feasible flow through the network.

subgraph: spmatrix or Graph or DataFrame

A subgraph of the original graph specifying the flow.

Metro Map: Computing an Octilinear Graph Representation

The following mods can be imported from gurobi_optimods.metromap:

metromap(graph, linepath_data=None, include_planarity=True, penalty_edge_directions=1, penalty_line_bends=1, penalty_distance=1, improve_lp=True, *, verbose=True, logfile=None, time_limit=None, solver_params=None)
Compute a metromap drawing, i.e., an octilinear network representation

considering the origin geographical data if available given as geographic position of the nodes

Parameters:
graphGraph

networkx graph with node attribute ‘pos’ being a tuple of x- and y-coordinate

linepath_dataDataFrame

DataFrame with information on the line routes/paths. It must include “linename”, “edge_source”, and “edge_target”. This data frame could also be empty

include_planaritybool

parameter to turn off the consideration of planarity constraints

penalty_edge_directionsfloat

weight for original direction part in the objective, default is 1

penalty_line_bendsfloat

weight for line-bend part in the objective, default is 1

penalty_distancefloat

weight for distance part in the objective, default is 1

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
tuple
  • networkx graph with node property pos_oct representing the x and y coordinates of the octilinear representation

  • Python dict for direction for each edge (needed for plotting)

Minimum Cost Flow

The following mods can be imported from gurobi_optimods.min_cost_flow:

min_cost_flow_networkx(G, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve the minimum cost flow problem for a given graph.

Parameters:
GDiGraph

Graph with edge attributes capacity and cost, as well as node attributes demand.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
tuple

Cost of the minimum cost flow (float), a subgraph of the original graph specifying the flow

min_cost_flow_pandas(arc_data, demand_data, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve the minimum cost flow problem for a given graph.

The inputs adhere to the following structure:

arc_data = pd.DataFrame(
    [
        {"from": 0, "to": 1, "capacity": 16, "cost": 0}, {"from": 1,
        "to": 2, "capacity": 10, "cost": 0},
    ]
).set_index(["from", "to"])

demand_data = pd.DataFrame(
    [{"node": 0, "demand": -1}, {"node": 2, "demand": 1}]
).set_index("node")
Parameters:
arc_dataDataFrame

DataFrame with graph and respective attributes. These must include "from", "to" nodes used as index as well as "capacity", and "cost" columns.

demand_dataDataFrame

DataFrame with node demand information. These must include indexed by "node", and include the "demand" column. This value can be positive (requesting flow) or negative (supplying flow).

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
tuple

Cost of the minimum cost flow (float), dictionary indexed by edges with non-zero flow in the solution (Series)

min_cost_flow_scipy(G, capacities, costs, demands, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve the minimum cost flow problem for a given graph.

Parameters:
Gspmatrix

Adjacency matrix of the graph.

capacitiesspmatrix

Matrix containing capacities for each edge.

costsspmatrix

Matrix containing costs for each edge.

demandsndarray

Array containing the demand for each node.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
tuple

Cost of the minimum cost flow (float), dictionary indexed by edges with non-zero flow in the solution (spmatrix)

Minimum Cut

The following mods can be imported from gurobi_optimods.min_cut:

class MinCutResult(cut_value, partition, cutset)

Solution to a Minimum-cut problem.

Attributes:
cut: float

Cut value of the minimum cut.

partition: tuple with sets

Partition of size 2 with cut sets.

cutset: set of tuple

Cutset with edges.

min_cut(graph, source, sink, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve the minimum cut problem for a given graph.

Parameters:
graphspmatrix or Graph or DataFrame

A graph, specified either as a scipy.sparse adjacency matrix, networkx graph, or pandas dataframe. These contain the capacity for each edge. In the networkx (pandas dataframe) case, we expect the edge attribute (column name) capacity. Please see the example in the documentation.

sourceint or str

The source (or origin) node for the cutset.

sinkint or str

The sink (or destination) node for the cutset.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
min_cut_result: MinCutResult

A dataclass containing the cut value, and set of nodes and edges in the minimum cut.

Maximum Weighted Independent Set/Clique

The following mods can be imported from gurobi_optimods.mwis:

class MWISResult(x, f)

Data class representing the maximum weighted independent set (clique) and its weight

Attributes:
xndarray

The maximum weighted independent set (clique) array

ffloat

The total weight of the maximum weighted independent set (clique)

maximum_weighted_clique(graph, weights, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Find a set of fully connected vertices with maximum weighted sum.

Parameters:
graphspmatrix or Graph or DataFrame

A graph, specified as a scipy.sparse upper triangular adjacency matrix with zero diagonals, a networkx graph, or a pandas dataframe. The pandas dataframe must include edge information in two columns named as "node1" and "node2".

weightsndarray of DataFrame

Vertex weights. If graph is a scipy.sparse matrix or a networkx graph, weights must be a numpy array. If graph is a pandas dataframe graph, weights must be a dataframe too. The weights dataframe must include the weight information in a column named "weights" and must be indexed by vertex number.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
MWISResult

A data class representing the maximum weighted clique array and its weight.

maximum_weighted_independent_set(graph, weights, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Find a set of mutually non-adjacent vertices with maximum weighted sum.

Parameters:
graphspmatrix or Graph or DataFrame

A graph, specified as a scipy.sparse upper triangular adjacency matrix with zero diagonals, a networkx graph, or a pandas dataframe. The pandas dataframe must include edge information in two columns named as "node1" and "node2".

weightsndarray or DataFrame

Vertex weights. If graph is a scipy.sparse matrix or a networkx graph, weights must be a numpy array. If graph is a pandas dataframe graph, weights must be a dataframe too. The weights dataframe must include the weight information in a column named "weights" and must be indexed by vertex number.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
MWISResult

A data class representing the maximum weighted independent set array and its weight.

Optimal Power Flow

The following mods can be imported from gurobi_optimods.opf:

compute_violations(case, voltages, polar=False, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Constructs an OPF model from given case data and computes a violation dictionary out of given voltage values.

If a voltage solution is present, e.g., from an external computation, this function can be used to check whether the given voltage solution is indeed feasible for the AC optimization model. Usually, if the violations are not too big, one can use the voltage solution for further calculations.

Returns a violation dictionary following MATPOWER notation which holds all case data and additional violation fields. The additional fields are

  • violation["bus"][i]["Vmviol"] for voltage magnitude violation at bus i

  • violation["bus"][i]["Pviol"] for real injection violation at bus i

  • violation["bus"][i]["Qviol"] for reactive injection violation at bus i

  • violation["branch"][i]["limitviol"] for limit violation at branch i

The violation dictionary can be used to generate a violations figure with the generate_opf_violations_figure function

Parameters:
casedict

Dictionary holding case data

voltagesdict

Dictionary holding bus input voltage data

polar: bool, optional

If True, use polar formulation when checking violations, defaults to False

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
dict

Case dictionary following MATPOWER notation with additional violations fields

read_case_matpower(file_path)

Read in a MATPOWER case file.

The file must contain a MATPOWER version 2 ‘mpc’ struct.

Parameters:
file_pathdict

Path to .mat file

Returns:
dict

Case dictionary following MATPOWER notation

solution_plot(case, coords, solution)

Reads the given case and returns a plotly figure object. Ideally the solution has been computed by the solve_opf function

Parameters:
casedict

Dictionary holding case data

coordsdict

Dictionary holding bus coordinates

solution: dict

Dictionary holding solution data following the MATPOWER notation as returned by the solve_opf function

Returns:
plotly.graph_objects.Figure

A plotly figure object displaying the solution. The plot can be displaged by calling figure.show().

solve_opf(case, opftype='AC', branch_switching=False, min_active_branches=0.9, use_mip_start=False, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Constructs an OPF model from given data and solves it with Gurobi. Returns a result dictionary following MATPOWER notation. The additional and possibly altered fields are

  • result["success"] 1 if at least one feasible solution has been found, 0 otherwise

  • result["et"] time spent for optimization

  • result["f"] solution objective value

  • result["bus"][i]["Vm"] for voltage magnitude value at bus i

  • result["bus"][i]["Va"] for voltage angle value at bus i

  • result["bus"][i]["mu"] for shadow prices of balance constraints at bus i (only available for DC without branchswitching)

  • result["gen"][i]["Pg"] for real power injection at generator i

  • result["gen"][i]["Qg"] for reactive power injection at generator i

  • result["branch"][i]["Pf"] for real power injected into “from” end of branch at branch i

  • result["branch"][i]["Pt"] for real power injected into “to” end of branch at branch i

  • result["branch"][i]["Qf"] for reactive power injected into “from” end of branch at branch i (AC only)

  • result["branch"][i]["Qt"] for reactive power injected into “from” end of branch at branch i (AC only)

  • result["branch"][i]["switching"] states whether a branch i is turned on or off in the final solution

Parameters:
casedict

Dictionary holding case data

opftypestr

Desired OPF model type. One of AC, ACrelax, or DC

branch_switchingbool, optional

If set to True, enables branch switching.

min_active_branchesfloat, optional

Defines the minimum number of branches that must be turned on when branch switching is active, i.e. the minimum number of turned on branches is equal to numbranches * min_active_branches. Has no effect if branchswitching is set to False.

use_mip_startbool, optional

(Advanced) If set to True, try various MIP starts for branch switching models. Has no effect if branchswitching is set to False. For DC models, this setting is ignored, and the mip start is always used.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
dict

Case dictionary following MATPOWER notation with additional result fields

violation_plot(case, coords, violations)

Reads the given case and returns a plotly figure object of provided violations. Ideally the violations have been computed by the compute_violations function

Parameters:
casedict

Dictionary holding case data

coordsdict

Dictionary holding bus coordinates

violationsdict

Dictionary holding case data following the MATPOWER notation with additional violations fields as returned by the compute_violations function

Returns:
plotly.graph_objects.Figure

A plotly figure object highlighting violations in the solution. The plot can be displaged by calling figure.show().

Mean-Variance Portfolio

The following mods can be imported from gurobi_optimods.portfolio:

class MeanVariancePortfolio(mu, cov_matrix=None, cov_factors=None)

Optimal mean-variance portfolio solver.

Instantiate an object of MeanVariancePortfolio for given covariance matrix and return vector. Use MeanVariancePortfolio.efficient_portfolio() to solve for efficient portfolios with given parameters.

Parameters:
mu1-d ndarray

Vector of expected returns for each asset

cov_matrix2-d ndarray

Covariance matrix \(\Sigma\)

cov_factorstuple of ndarray

Covariance factors that constitute \(\Sigma = B K B^T + diag(d)\).

  • cov_factors[0]: (n, k) ndarray \(B\)

  • cov_factors[1]: (k, k) ndarray \(K\), SPD

  • cov_factors[2]: (n,) ndarray \(d\), nonnegative

Raises:
LinAlgError

If the matrix K is not positive definite

efficient_portfolio(gamma, max_trades=None, max_positions=None, fees_buy=None, fees_sell=None, costs_buy=None, costs_sell=None, min_long=None, min_short=None, max_total_short=0.0, initial_holdings=None, rf_return=None, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Compute efficient portfolio for given parameters

Parameters:
gammafloat >= 0

Risk aversion cofficient for balancing risk and return; the resulting objective functions is \(\mu^T x - 0.5 \gamma x^T \Sigma x\)

max_tradesint >= 0, optional

Upper limit on the number of trades

max_positionsint >= 0, optional

Upper limit on the number of open positions

fees_buyfloat or ndarray >= 0, optional

Fixed-charge fee for each buy transaction, relative to total portfolio value

fees_sellfloat or ndarray >= 0, optional

Fixed-charge fee for each sell transaction, relative to total portfolio value

costs_buyfloat or ndarray >= 0, optional

Variable transaction costs for each buy transaction, relative to trade value

costs_sellfloat or ndarray >= 0, optional

Variable transaction costs for each sell transaction, relative to trade value

min_longfloat >= 0, optional

Lower bound on the volume on a traded long position, relative to total portfolio value

min_shortfloat >= 0, optional

Lower bound on the volume on a traded short position, relative to total portfolio value

max_total_shortfloat >= 0, optional

Maximum total short positions, relative to total investment.

initial_holdings1-d ndarray, optional

Initial portfolio holdings (sum needs to be <= 1)

rf_returnfloat, optional

Include a risk-free asset having return rate rf_return.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
mvp_resultPortfolioResult

A dataclass containing the efficient portfolio, along with auxiliary information:

  • mvp_result.x: The portfolio vector \(x\)

  • mvp_result.risk: The estimated risk \(x^T \Sigma x\) of the portfolio

  • mvp_result.return: The estimated return \(\mu^T x\) of the portfolio

  • mvp.x_rf relative investment in the risk-free asset. Present only if rf_return was non-None on input

Some combinations of requested portfolio features may rule out all possible portfolios. In this corner case the value None is returned.

Notes

Refer to Enforcing more portfolio features for a detailed discussion of all parameters.

class PortfolioResult(x, ret, risk, x_rf=None)

Data class representing computed portfolios.

Attributes:
x1-d ndarray

The vector of relative investments into each asset

retfloat

The (estimated) return of the portfolio

riskfloat

The (estimated) risk of the portfolio

x_rffloat, optional

The relative investment into the risk-free asset. Equals to None if no risk-free return rate was specified upon input

Quadratic Unconstrained Binary Optimization (QUBO)

The following mods can be imported from gurobi_optimods.qubo:

class QuboResult(solution, objective_value)

Solution to a QUBO problem.

Attributes:
solutionndarray

0/1 array of variable values in the solution

objective_valuefloat

The objective function value for this solution

solve_qubo(coeff_matrix, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve a quadratic unconstrained binary optimization (QUBO) problem, i.e., minimize quadratic function \(x'Qx\) defined by coefficient matrix \(Q\) over a binary decision variable vector \(x\)

Parameters:
coeff_matrixspmatrix

Quadratic coefficient matrix

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
QuboResult

A dataclass containing a 0/1 solution array and its objective value

Regression

The following mods can be imported from gurobi_optimods.regression:

class LADRegression

Least absolute deviations (L1-norm) regressor

fit(X_train, y_train, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Fit the model to training data.

Parameters:
X_trainndarray

Training set feature values

y_trainndarray

Training set output values

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Sharpe Ratio

The following mods can be imported from gurobi_optimods.sharpe_ratio:

class SharpeRatioResult(x, sharpe_ratio, ret, risk)

Data class representing the portfolio that maximizes the Sharpe ratio.

Attributes:
xndarray or Series

The relative portfolio allocations \(x\)

sharpe_ratiofloat

The Sharpe ratio of the portfolio

retfloat

The estimated return \(\mu^T x\) of the portfolio

riskfloat

The estimated risk \(x^T \Sigma x\) of the portfolio

max_sharpe_ratio(cov_matrix, mu, rf_rate=0, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve the problem of finding a portfolio that maximizes the Sharpe ratio.

Parameters:
cov_matrixndarray or DataFrame

2D positive-semidefinite variance-covariance matrix \(\Sigma\)

mundarray or Series

Expected return rates \(\mu\)

rf_ratefloat >= 0, optional

Non-negative risk-free rate of return (defaults to 0)

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
resultSharpeRatioResult

A data class representing the portfolio that maximizes the Sharpe ratio:

  • result.x: The relative portfolio allocations \(x\)

  • result.sharpe_ratio: The Sharpe ratio of the portfolio

  • result.ret: The estimated return \(\mu^T x\) of the portfolio

  • result.risk: The estimated risk \(x^T \Sigma x\) of the portfolio

Workforce Scheduling

The following mods can be imported from gurobi_optimods.workforce:

solve_workforce_scheduling(availability, shift_requirements, worker_limits, preferences=None, rolling_limits=False, *, verbose=True, logfile=None, time_limit=None, solver_params=None)

Solve a workforce scheduling model.

Parameters:
availabilityDataFrame

Dataframe with columns ‘Worker’ and ‘Shift’ defining all allowable worker-shift combinations. The ‘Preference’ column optionally assigns a preference value to the given combination.

shift_requirementsDataFrame

Dataframe with columns ‘Shift’ and ‘Required’ specifying the number of staff required for every shift.

worker_limitsDataFrame

Dataframe with columns ‘Worker’, ‘MinShifts’, and ‘MaxShifts’ specifying the maximum and minimum number of shifts each worker may be assigned in the schedule.

preferencesstr, optional

The name of a column in the availability dataframe containing preference values. If provided, the mod returns a schedule which maximises the sum of preference values of assigned shifts.

rolling_limitsbool

Whether to enforce worker shift limits on a rolling window basis. If True, worker_limits must contain an additional ‘Window’ column specifying the rolling window for each worker.

verbosebool, optional

verbose=False suppresses all console output

logfilestr, optional

Write all mod output to the given file path

time_limitfloat

Solver time limit in seconds (default no limit)

solver_paramsdict, optional

Gurobi parameters to be passed to the solver

Returns:
DataFrame

Shift assignments as a subset of the availability dataframe

Raises:
ValueError

If a feasible set of shift assignments cannot be constructed from the input data