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”, “fixCost”, and “operatingCost”.
linepath_dataDataFrame: DataFrame with information on the line routes/paths. It must include “linename”, “edgeSource”, and “edgeTarget”.
frequency: List: List with possible frequencies: How often the line can be operated in the considered time horizon.
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.

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 Result(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, **kwargs)

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.

Returns

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

maximum_weighted_independent_set(graph, weights, **kwargs)

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.

Returns

Result: 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