API Library Reference

The current models are implemented under ormm.mathprog, ormm.network, and ormm.markov. MathProg contains factory methods to implement problem classes and other useful functions for solution analysis. Markov contains functions to perform markov analysis on discrete state and time processes, as well as printing those results nicely. Network contains models and methods for the transportation problem and the shortest path tree problem.

ORMM MathProg

blending([linear])	Factory method returning Pyomo Abstract/Concrete Model for the Blending Problem
resource_allocation([linear, mult_res, …])	Factory method returning Pyomo Abstract/Concrete Model for the Resource Allocation Problem.
scheduling(prob_class[, linear])	Calls factory methods for different scheduling problems.
print_sol(instance[, money_obj])	Print the solution to the solved instance.
sensitivity_analysis(instance)	Return dataframe containing sensitivity analysis

ormm.mathprog.blending(linear=True, **kwargs)

Factory method returning Pyomo Abstract/Concrete Model for the Blending Problem

Parameters

• linear (bool, optional) – Determines whether decision variables will be Reals (True) or Integer (False).

• **kwargs – Passed into Pyomo Abstract Model’s create_instance to return Pyomo Concrete Model instead.

Notes

The Blending Problem optimizes the mixing of ingredients to satisfy restrictions while minimizing cost.

\[ \begin{align}\begin{aligned}\text{Min} \sum_{i \in I} C_iX_i\\\text{s.t.} \enspace L_p \leq \sum_{i \in I} N_{i,p}X_i \leq U_p \quad \forall p \in P\\\sum_{i \in I} X_i = 1\\X_i \geq 0 \quad \forall i \in I\end{aligned}\end{align} \]

Examples

Creating a concrete model from data params & solving instance.

>>> import pyomo.environ as pyo
>>> instance = blending("my_params.dat") # AMPL data file
>>> opt = pyo.SolverFactory("glpk")
>>> results = opt.solve(instance)

ormm.mathprog.resource_allocation(linear=True, mult_res=False, max_activity=True, **kwargs)

Factory method returning Pyomo Abstract/Concrete Model for the Resource Allocation Problem.

Parameters

• linear (bool, optional) – Determines whether decision variables will be Reals (True) or Integer (False).

• mult_res (bool, optional) – Determines whether there are multiple of each resource or not.

• max_activity (bool, optional) – Determines whether there is an upper limit on the decision variables.

• **kwargs – Passed into Pyomo Abstract Model’s create_instance to return Pyomo Concrete Model instead.

Notes

The Resource Allocation Problem optimizes using scarce resources for valued activities.

\[ \begin{align}\begin{aligned}\text{Max} \sum_{a \in A} V_aX_a\\\text{s.t.} \sum_{a \in A} N_{r,a}X_a \leq M_r \quad \forall r \in R\\0 \leq X_a \leq M_a \quad \forall a \in A\end{aligned}\end{align} \]

Examples

Creating a concrete model from data params & solving instance.

>>> import pyomo.environ as pyo
>>> instance = resource_allocation("my_params.dat) # AMPL data file
>>> opt = pyo.SolverFactory("glpk")
>>> results = opt.solve(instance)

ormm.mathprog.scheduling(prob_class, linear=False, **kwargs)

Calls factory methods for different scheduling problems.

The prob_class parameter allows the user to choose from different types of problem classes, which in turn have different model structures.

The valid choices are:

• employee: A simple employee scheduling problem to minimize the number of workers employed to meet period requirements. Currently assumes that a worker works their periods in a row (determined by ShiftLenth parameter).

• rental: A type of scheduling problem where there are different plans (with different durations & costs), and the goal is to minimize the total cost of the plans purchased while meeting the period requirements (covering constraints).

• py:obj`agg_planning`

  A planning problem where the decision variables

  are how much to produce during each period, to minimize production and holding costs while satisfying demand.

More details on these model classes can be found in the Notes section here, as well as the corresponding section of the Mathematical Programming.

Parameters

• prob_class (str, optional) – Choice of “employee”, “rental”, or “agg_planning” to return different scheduling models.

• linear (bool, optional) – Determines whether decision variables will be Reals (True) or Integer (False).

• **kwargs – Passed into Pyomo Abstract Model’s create_instance to return Pyomo Concrete Model instead.

Raises

TypeError – Raised if invalid argument value is given for prob_class.

Notes

The employee model minimizes workers hired with covering constraints:

\[ \begin{align}\begin{aligned}\text{Min} \sum_{p \in P} X_p\\\text{s.t.} \sum_{p - (L - 1)}^p X_p \geq R_p \quad \forall p \in P\\X_p \geq 0\text{, int} \quad \forall p \in P\end{aligned}\end{align} \]

The rental model minimizes cost of plans purchased with covering constraints:

\[ \begin{align}\begin{aligned}\text{Min} \sum_{a \in A} C_a \sum_{p \in P \, \mid \, (p,a) \in J} X_{(p,a)}\\\text{s.t.} \sum_{j \in J \, \mid \, f} X_j \geq R_p \quad \forall p \in P\\X_j \geq 0\text{, int} \quad \forall j \in J\end{aligned}\end{align} \]

The aggregate planning model minimizes production & holding costs while meeting demand over a number of periods:

\[ \begin{align}\begin{aligned}\text{Min} \sum_{p \in P} C_pX_p &+ hY_p\\\text{s.t.} \enspace Y_{p-1} + X_p - Y_p &= D_p &\forall p \in P\\Y_p &\leq m &\forall p \in P\\Y_{\min(P)-1} &= I_I\\Y_{\max(P)} &= I_F\\X_p, \, Y_p &\geq 0\text{, int} &\forall p \in P\end{aligned}\end{align} \]

ormm.mathprog.print_sol(instance, money_obj=False)

Print the solution to the solved instance.

Parameters

• instance (pyomo.environ.ConcreteModel) – A solved model to retrieve objective & variable values.

• money_obj (bool) – Whether or not the objective is a monetary value (adds $ if True).

Notes

Assumes the objective is retrievable by instance.OBJ()

ormm.mathprog.sensitivity_analysis(instance)

Return dataframe containing sensitivity analysis

Parameters

instance (pyomo.environ.ConcreteModel) – A solved model to retrieve dual suffix.

Returns

Dataframe with sensitivity analysis information.

Return type

pandas.DataFrame

Notes

Assumes the dual suffix is retrievable by instance.dual.

ORMM Markov

analyze_dtmc(P[, states, sim_kwargs, …])	Perform Markov Analysis of discrete time discrete state markov chain (DTMC) process.
analyze_ctmc(states, rate_matrix[, t, d, n, …])	Perform Markov Analysis of continuous time discrete state markov chain (CTMC) process.
print_markov(analysis[, mtype])	Print results of markov analysis.

ormm.markov.analyze_dtmc(P, states=None, sim_kwargs=None, trans_kwargs=None, cost_kwargs=None)

Perform Markov Analysis of discrete time discrete state markov chain (DTMC) process.

Parameters

• P (array-like) – The transition matrix. Must be of shape n x n.

• states (array-like) – Array_like of length n containing the values associated with the states, which must be homogeneous in type. If None, the values default to integers 0 through n-1.

• sim_kwargs (dict) – Dictionary of key word arguments to be passed to the simulation of the markov process. If None, then no simulation will be performed. These include ts_length (length of each simulation) and init (Initial state values).

• trans_kwargs (dict) – Dictionary of options for the transient probability analysis (tsa). If None is passed instead of dict, no tsa will be done. ts_length is the number of time periods to analyze, while init is the initial state probability vector.

• cost_kwargs (dict) – Dictionary of cost parameters for cost analysis. If None, then no cost analysis will be performed. These include state (vector of costs of being in each state), transition (matrix of costs of transitioning from one state to another), and num (number of these processes - total cost multiplied by this, default 1).

Returns

analysis – Dictionary with results of markov analysis

Return type

dict

Raises

ValueError – If sim_kwargs, trans_kwargs, or cost_kwargs is given, but their required arguments are not passed. These are described in the Notes section.

Notes

The required arguments if the kwargs are passed are:

• sim_kwargs: ts_length is required, the length of the sim.

• trans_kwargs: ts_length is required, the number of periods to analyze

• cost_kwargs: state and transition are required, which are the costs of being in any state and the costs of transitioning from one state to another.

ormm.markov.analyze_ctmc(states, rate_matrix, t=None, d=None, n=None, init=None)

Perform Markov Analysis of continuous time discrete state markov chain (CTMC) process.

Parameters

• states (array-like) – Vector-like of length M containing the values associated with the states, which must be homogeneous in type. If None, the values default to integers 0 through M-1.

• rate_matrix (array-like) – matrix of size MxM detailing the stationary probabilities of moving from one state to another.

• t (int) – Integer for the end time period for the transient probability analysis. If this is given, then either d or n must be given, and init must be given as well.

• d (float) – Float for the small delta (amount of time per step) for numerically solving the transient probabilities. Either this or n (number of steps) must be given (one can be inferred from the other and ‘t’).

• n (int) – Integer of the number of steps to take for numerically solving the transient probabilities. Either this or ‘d’ must be given. If both are given and they do not coincide with t (d*n = t), an error will be raised.

• init (array-like) – Vector-like of length n containing the initial state values for the transient probability analyis. This must be given if ‘t’, ‘d’, or ‘n’ is given.

Returns

analysis – Dictionary with results of markov analysis

Return type

dict

Raises

ValueError – If some but not all of the required transient probability analysis arguments are given, or if t, d, and n are given, but their values are invalid (t = n * d).

ormm.markov.print_markov(analysis, mtype='dtmc')

Print results of markov analysis.

Parameters

• analysis (dict) – dictionary returned from markov_analysis() containing cdfs, steady state probs, etc.

• mtype (str) – Type of markov analysis that is being passed. Must be ‘dtmc’ or ‘ctmc’.

Raises

ValueError – If invalid value is passed for ‘mtype’.

ORMM Network

transportation_model(**kwargs)	Factory method for the balanced transportation problem.
Graph([arcs, costs, nodes])	Fully connected network of nodes via arcs with costs.

ormm.network.transportation_model(**kwargs)

Factory method for the balanced transportation problem.

By balanced, we mean that this implementation currently requires the data to have the same number of source nodes as destination nodes. Your data can be easily changed to meet this requirement; see the notes section.

This network flow problem has a set of source nodes and destination nodes, with shipping costs between each of them. There are demands at the destinations, and supply limits at the sources. The objective is to minimize the shipping costs while meeting the demands.

Parameters

**kwargs – Passed into Pyomo Abstract Model’s create_instance to return Pyomo Concrete Model instead.

Returns

Abstract Model with the sets, parameters, decision variables, objective, and constraints for the transportation problem. Returns a Concrete Model instead if any kwargs passed.

Return type

pyomo.environ.AbstractModel or pyomo.environ.ConcreteModel

Notes

This is a bipartite network with m supply nodes and n destination nodes. If not possible to ship from i to j, a large cost M should be passed.

Assumes the feasibility property holds (total supply equals total demand) - then becomes balanced TP. You can modify data so this requirement is satisfied.

Let \(\delta\) be the excess amount (positive). Add a dummy source to the data with index m + 1 if demand > supply.

\(s_{m+1} = \delta\text{ ; }c_{m+1,j}=0 \quad \forall j \in J\)

Add a dummy demand to the data with index n + 1 if supply > demand.

\(d_{n+1} = \delta\text{ ; }c_{i,n+1}=0 \quad \forall i \in I\)

\[ \begin{align}\begin{aligned}\text{Min} \sum_{i \in I}\sum_{j \in J}C_{i,j}X_{i,j}\\\text{s.t. } \sum_{j \in J} X_{i,j} = S_i \quad \forall i \in I\\\sum_{i \in I} X_{i,j} = D_j \quad \forall j \in J\\X_{i,j} \geq 0\text{, int} \quad \forall i \in I\text{, }j \in J\end{aligned}\end{align} \]

class ormm.network.Graph(arcs=None, costs=None, nodes=None)

Fully connected network of nodes via arcs with costs. This class can be used to create graphs (networks), and then solve different network flow models on these graphs such as the transportation model and shortest path model.

Parameters

• arcs (dict, optional) – All possible paths (arcs) from each node. e.g. {‘A’: [‘B’, ‘C’, ‘D’, ‘E’], …}

• costs (dict, optional) – The cost of traveling from one node to another. e.g. {(‘A’, ‘B’): 2, (‘A’, ‘C’): 5, …}

• nodes (set, optional) – A set of all unique nodes in the graph. e.g. {“A”, “B”, “C”, …}