gana

A barebones mathematical programming package

Functions

inf(function)	Minimize the function
sigma(variable[, over, position])	Summation without recursion, also allows better printing
sup(function)	Maximize the function

Classes

I(*members[, size, start, mutable, tag, ...])	Set of index elements (X).
P(*index[, _, mutable, tag, ltx, name])	Ordered set of parameters.
Prg([name, tol, canonical, tag])	A mathematical program.
T(*index[, _, tag, mutable, ltx, name])	Ordered set of parametric variables (theta).
V(*index[, itg, nn, bnr, mutable, tag, ltx, ...])	Ordered set of variables (Var).

class V(*index: I, itg: bool = False, nn: bool = True, bnr: bool = False, mutable: bool = False, tag: str = '', ltx: str = '', name: str = '')

Bases: _E

Ordered set of variables (Var).

Parameters:

• index (I or tuple[I], optional) – Indices. Defaults to None.

• itg (bool, optional) – If the variable set is integer. Defaults to False.

• nn (bool, optional) – If the variable set is non-negative. Defaults to True.

• bnr (bool, optional) – If the variable set is binary. Defaults to False.

• mutable (bool, optional) – If the variable set is mutable. Defaults to False.

• tag (str) – Tag/details

• ltx (str) – LaTeX representation of the variable set.

Variables:

• index (I) – Index of the variable set (product of all indices)

• map (dict[I, V]) – Index to variable mapping

• _ (list[V]) – List of variables in the set

• itg (bool) – Integer variable set flag

• nn (bool) – Non-negative variable set flag

• bnr (bool) – Binary variable set flag

• mutable (bool) – Mutable variable set flag

• tag (str) – Tag/details

• name (str) – Name, set by the program

• n (int) – Number id, set by the program

• args (dict[str, bool]) – Arguments for making similar variable sets

• ltx (str) – LaTeX representation of the variable set

Raises:

• ValueError – If variable is binary and not non-negative

• ValueError – Multiplication by tuple or list of tuples

• ValueError – Division by None, tuple, or list of tuples

• ZeroDivisionError – Division by zero

• ValueError – Division of something by a variable

• ValueError – Raising variable to a power, except 0 or 1

property matrix: dict

Matrix Representation

property args: dict[str, str | bool]

Return the arguments of the variable set

property A: list[list[float]]

Generate a diagonal matrix representation of the variable set

property features_in: list[C | O]

Constraints and objectives that this variable set is part of

make_function() → F

Make a function

Returns:

Function representing the variable set

Return type:

F

copy() → V

Returns a copy of the variable set

Returns:

Copy of the variable set

Return type:

V

birth_variables(mutating: bool = False, n_start: int = 0)

Births a variable at every index in the index set

Parameters:

• mutating (bool, optional) – If the variable set is being mutated. Defaults to False.

• n_start (int, optional) – The starting number for positioning the variables. Defaults to 0.

output(n_sol: int = 0, aslist: bool = False, asdict: bool = False, compare=False) → list[float] | dict[tuple[I, ...], float] | None

Solution

Parameters:

• n_sol (int, optional) – Solution number. Defaults to 0.

• aslist (bool, optional) – Returns values taken as list. Defaults to False.

• asdict (bool, optional) – Returns values taken as dictionary. Defaults to False.

• compare (bool, optional) – Displays a comparison of the solutions across multiple objectives. Defaults to False.

Returns:

Solution values

Return type:

list[float] | dict[tuple[I, …], float] | None

f_eval(*values: float | int, n_sol: int = 0, n_cr: int = 0) → float

Evaluates the variable value as a function of parametric variables

Parameters:

• values (float | int) – values of the parametric variables

• n_sol (int, optional) – Solution number. Defaults to 0.

• n_cr (int, optional) – Critical region number. Defaults to 0.

Returns:

evaluated value

Return type:

float

eval(*theta_vals: float, n_sol: int = 0) → float | None

Evaluates the variable value as a function of parametric variables

Parameters:

• theta_vals (float) – values of the parametric variables

• n_sol (int, optional) – solution number. Defaults to 0.

• roundoff (int, optional) – round off the evaluated value. Defaults to 4.

Returns:

evaluated value

Return type:

float | None

property ltx: str

LaTeX representation

property index_ltx: str

LaTeX representation of the index

latex() → str

LaTeX representation :returns: LaTeX representation of the variable set :rtype: str

show(descriptive: bool = False)

Display the variables

Parameters:

descriptive (bool, optional) – Print members of the index set

mps() → str

Name in MPS file

Returns:

Name in MPS file

Return type:

str

lp() → str

LP representation

Returns:

LP representation

Return type:

str

property longname: str

Long name

report() → V

Return a reporting binary variable

Returns:

Reporting binary variable

Return type:

V

line(font_size: float = 16, fig_size: tuple[float, float] = (12, 6), linewidth: float = 0.7, color: str = 'blue', grid_alpha: float = 0.3, usetex: bool = True, str_idx_lim: int = 10)

Plot the variable set

Parameters:

• font_size (float, optional) – Font size for the plot. Defaults to 16.

• fig_size (tuple[float, float], optional) – Size of the figure. Defaults to (12, 6).

• linewidth (float, optional) – Width of the line in the plot. Defaults to 0.7.

• color (str, optional) – Color of the line in the plot. Defaults to ‘blue’.

• grid_alpha (float, optional) – Transparency of the grid lines. Defaults to 0.3.

• usetex (bool, optional) – Use LaTeX for text rendering. Defaults to True.

• str_idx_lim (int, optional) – Limit for string indices display. Defaults to 10.

bar(font_size: float = 16, fig_size: tuple[float, float] = (12, 6), linewidth: float = 0.7, color: str = 'blue', grid_alpha: float = 0.3, usetex: bool = True, str_idx_lim: int = 10)

Plot the variable set

Parameters:

• font_size (float, optional) – Font size for the plot. Defaults to 16.

• fig_size (tuple[float, float], optional) – Size of the figure. Defaults to (12, 6).

• linewidth (float, optional) – Width of the line in the plot. Defaults to 0.7.

• color (str, optional) – Color of the line in the plot. Defaults to ‘blue’.

• grid_alpha (float, optional) – Transparency of the grid lines. Defaults to 0.3.

• usetex (bool, optional) – Use LaTeX for text rendering. Defaults to True.

• str_idx_lim (int, optional) – Limit for string indices display. Defaults to 10.

class P(*index: I, _: list[float] | float | None = None, mutable: bool = False, tag: str = '', ltx: str = '', name: str = '')

Bases: _E

Ordered set of parameters.

Does not support inf or nan values.

Parameters:

• index (tuple[I], optional) – Indices of the parameter set.

• _ (list[int | float], optional) – List of parameters. All values are converted to float.

• mutable (bool, optional) – If the parameter set is mutable.

• tag (str, optional) – Tag/details

Variables:

• index (I) – Index of the parameter set

• _ (list[int | float]) – List of parameters (converted to float)

• mutable (bool) – If the parameter set is mutable

• tag (str) – Tag/details

• name (str) – Name, set by the program

• n (int) – Number id, set by the program

• map (dict[X | Idx, Var]) – Index to parameter mapping

• case (PCase) – Special case of the parameter set

Raises:

• ValueError – If != operator is used with any type other than P

• ValueError – If the parameter values and the length of indices do not match

property args: dict[str, str | bool]

Return the arguments of the parameter set

property A: list[list[float]]

Generate a diagonal matrix representation of the variable set

property ltx: str

LaTeX representation

property index_ltx: str

LaTeX representation of the index

latex() → str

LaTeX representation

Returns:

LaTeX representation of the parameter set

Return type:

str

show(descriptive: bool = False)

Display the variables

Args:

descriptive (bool, optional): If True, shows all parameters. Defaults to False.

line(font_size: float = 16, fig_size: tuple[float, float] = (12, 6), linewidth: float = 0.7, color: str = 'blue', grid_alpha: float = 0.3, usetex: bool = True, str_idx_lim: int = 10)

Plot the parameter set

Parameters:

• font_size (float, optional) – Font size for the plot. Defaults to 16.

• fig_size (tuple[float, float], optional) – Size of the figure. Defaults to (12, 6).

• linewidth (float, optional) – Width of the line in the plot. Defaults to 0.7.

• color (str, optional) – Color of the line in the plot. Defaults to ‘blue’.

• grid_alpha (float, optional) – Transparency of the grid lines. Defaults to 0.3.

• usetex (bool, optional) – Use LaTeX for text rendering. Defaults to True.

• str_idx_lim (int, optional) – Limit for string indices display. Defaults to 10.

bar(font_size: float = 16, fig_size: tuple[float, float] = (12, 6), linewidth: float = 0.7, color: str = 'blue', grid_alpha: float = 0.3, usetex: bool = True, str_idx_lim: int = 10)

Plot the parameter set

Parameters:

• font_size (float, optional) – Font size for the plot. Defaults to 16.

• fig_size (tuple[float, float], optional) – Size of the figure. Defaults to (12, 6).

• linewidth (float, optional) – Width of the line in the plot. Defaults to 0.7.

• color (str, optional) – Color of the line in the plot. Defaults to ‘blue’.

• grid_alpha (float, optional) – Transparency of the grid lines. Defaults to 0.3.

• usetex (bool, optional) – Use LaTeX for text rendering. Defaults to True.

• str_idx_lim (int, optional) – Limit for string indices display. Defaults to 10.

class I(*members: str | int, size: int = None, start: int = 0, mutable: bool = False, tag: str = None, ltx: str = None, dummy: bool = False)

Bases: object

Set of index elements (X).

Parameters:

• members (str | int, optional) – Members of the Index set.

• size (int, optional) – Size of the Index set, creates an ordered set if given.

• mutable (bool, optional) – If the Index set is mutable. Defaults to False.

• tag (str, optional) – Tag/details. Defaults to None.

• dummy (bool, optional) – If the Index set is a dummy set, elements are created immediately. Defaults to False.

Variables:

• _ (list[X]) – Elements of the index set

• tag (str) – Tag/details

• ordered (bool) – Ordered set, True if size is given

• name (str) – Name, set by the program

• n (int) – Number id, set by the program

• ltx (str) – LaTeX representation

Raises:

• ValueError – If both members and size are given

• ValueError – If indices of elements (P, V) are not compatible

• ValueError – If index set is not ordered and step is given

Example

p = Program()
p.s1 = I('a', 'b', 'c')
p.s2 = I('a', 'd', 'e', 'f')

# Intersection
p.s1 & p.s2
# I('a')

# Union
p.s1 | p.s2
# I('a', 'b', 'c', 'd', 'e', 'f')

# Symmetric difference
p.s1 ^ p.s2
# I('b', 'c', 'd', 'e', 'f')

# Difference
p.s1 - p.s2
# I('b', 'c')

birth_elements()

Create elements for the index set

step(n: int) → list[Self]

Step up or down the index set

Parameters:

n (int) – Step size

Returns:

New index set stepped up or down

Return type:

I

property ltx: str

LaTeX representation

latex(descriptive: bool = True, int_not: bool = False, dots_limit: int = 5) → str

LaTeX representation

Parameters:

• descriptive (bool, optional) – print members of the index set

• int_not (bool, optional) – Whether to display the set in integer notation.

• ddot_limit (int, optional) – Maximum size over which … is used to represent members.

Returns:

LaTeX representation of the index set

Return type:

str

show(descriptive: bool = True, int_not: bool = False, dots_limit: int = 5)

Display the set

Parameters:

descriptive (bool, optional) – Print members of the index set

mps(pos: int) → str

MPS representation

Parameters:

pos (int) – Position of the member in the set

Returns:

MPS representation of the member at position pos

Return type:

str

lp(pos: int) → str

LP representation

Parameters:

pos (int) – Position of the member in the set

birth_index(name: str, members: list[Self]) → Self

Updates the parent, sets new positions and mutable/ordered attributes

Parameters:

• name (str) – Name of the new index set

• members (list[I]) – Members of the new index set

Returns:

New index set

Return type:

I

class T(*index: I, _: list[tuple[float]] | tuple[float] | None = None, tag: str | None = None, mutable: bool = False, ltx: str | None = None, name: str = '')

Bases: _E

Ordered set of parametric variables (theta).

Parameters:

• index (I) – Index for the theta set.

• _ (list[tuple[float]] | tuple[float]) – Values for the theta set.

• mutable (bool, optional) – If True, the theta set can be modified. Defaults to False.

• tag (str, optional) – Tag for the theta set. Defaults to None.

Variables:

• index (I) – Index of the parametric variable set

• _ (list[int | float]) – List of parametric variables

• mutable (bool) – If the parametric variable set is mutable

• tag (str) – Tag/details

• name (str) – Name, set by the program

• n (int) – Number id, set by the program

• map (dict[X | Idx, Var]) – Index to parameter mapping

property args: dict[str, str | bool]

Return the arguments of the parametric variable set

Returns:

Dictionary of arguments

Return type:

dict

create_map()

Create a map of indices to parameters

birth_thetas(mutating: bool = False, n_start=0)

Births a parametric variable (Theta) at every index in the index set

Parameters:

• mutating (bool, optional) – If the variable set is being mutated. Defaults to False.

• n_start (int, optional) – The starting number for positioning the variables. Defaults to 0.

property CrA

A matric of critical region

property CrB

B matrix of critical region

property ltx: str

LaTeX representation of the parametric variable set

property longname: str

Long name representation

latex() → str

LaTeX representation

show(descriptive: bool = False)

Display the variables

Parameters:

descriptive (bool, optional) – Print members of the index set

class Prg(name: str = 'prog', tol: float = None, canonical: bool = True, tag: str = '')

Bases: object

A mathematical program.

Can be a linear (LP), integer (IP), or mixed-integer (MIP).

Parameters:

• name (str, optional) – Name of the program. Defaults to ‘prog’.

• tol (float, optional) – Tolerance. Defaults to None.

• canonical (bool, optional) – Whether to use canonical form. Defaults to True.

• tag (str, optional) – Tag for the program. Defaults to ‘’.

Variables:

• names (list[str]) – Names of declared sets

• sets (Sets) – Object to hold set objects

• names_idx (list[str]) – Names of the index elements

• indices (list[X]) – Index sets

• variables (list[Var]) – Variable sets

• thetas (list[PVar]) – Parametric variable sets

• functions (list[Func]) – Function sets

• constraints (list[Cons]) – Constraint sets

• objectives (list[Obj]) – Objective sets

Raises:

ValueError – If overwriting a set

name: str = 'prog'

tol: float = None

canonical: bool = True

tag: str = ''

property solution: Solution | Solution

Returns the latest solution of the program

Returns:

Solution object

Return type:

Solution | MPSolution

property formulation: Model | MPLP_Program

Returns the latest formulation of the program

Returns:

Formulation object

Return type:

GPModel | MPLP_Program

add_index(name: str, index: I)

Adds new index to program

Parameters:

• name (str) – name of index

• index (I) – index set to be added

add_indices(index: I, members: list[str] = None)

Adds indices from an index set to the program

Parameters:

• index (I) – Index set who elements are to be added to the program.

• members (list[str], optional) – List of members to be added to the index set.

add_variable(name: str, variable: V)

Adds new variable set to program

Parameters:

• name (str) – name of variable set

• variable (V) – variable set to be added

mutate_variable(variable_ex: V, variable_new: V)

Mutates an existing variable set in the program

Parameters:

• variable_ex (V) – existing variable set to be mutated

• variable_new (V) – incoming variable set to be added

add_parameter(name: str, parameter: P)

Adds new parameter set to program

Parameters:

• name (str) – name of parameter set

• parameter (P) – parameter set to be added

mutate_parameter(parameter_ex: P, parameter_new: P)

Mutates an existing parameter set in the program

Parameters:

• parameter_ex (P) – existing parameter set to be mutated

• parameter_new (P) – incoming parameter set to be added

add_theta(name: str, theta: T)

Adds new theta set to program

Parameters:

• name (str) – name of theta set

• theta (T) – theta set to be added

update_theta(constraint: C)

Updates the theta set and thetas in a constraint

Parameters:

constraint (C) – constraint with thetas to be updated

mutate_theta(theta_ex: T, theta_new: T)

Mutates an existing theta set in the program

Parameters:

• theta_ex (T) – existing theta set to be mutated

• theta_new (T) – incoming theta set to be added

add_function(name: str, function: F)

Add a function set to the program

Parameters:

• name (str) – name of function

• function (F) – function object

replace_function(function_ex: F, function_new: F)

Replaces an existing function set in the program

Parameters:

• function_ex (F) – existing function set to be mutated

• function_new (F) – new function set to replace the existing one

add_constraint(name: str, constraint: C)

Adds a constraint set to the program

Parameters:

• name (str) – name of constraint

• constraint (C) – constraint object

replace_constraint(constraint_ex: C, constraint_new: C)

Replaces an existing constraint set in the program

Parameters:

• constraint_ex (C) – existing constraint set to be mutated

• constraint_new (C) – new constraint set to replace the existing one

add_objective(objective: O)

Adds an objective set to the program

Parameters:

objective (O) – objective object

property nncons_sets: list[C]

non-negativity constraint sets

property eqcons_sets: list[C]

equality constraint sets

property leqcons_sets: list[C]

less than or equal constraint sets

nncons(n: bool = False) → list[int | C]

non-negativity constraints

eqcons(n: bool = False) → list[int | C]

equality constraints

leqcons(n: bool = False) → list[int | C]

less than or equal constraints

cons(n: bool = False) → list[int | C]

constraints

nnvars(n: bool = False) → list[int | V]

non-negative variables

bnrvars(n: bool = False) → list[int | V]

binary variables

itgvars(n: bool = False) → list[int | V]

integer variables

nonbnritgvars(n: bool = False) → list[int | V]

non-binary and integer variables

cntbnrvars(n: bool = False) → list[int | V]

continuous and binary variables integer variables are excluded

cntvars(n: bool = False) → list[int | V]

continuous variables

renumber()

Renumbers the constraints, just to be sure

property B: list[float]

RHS Parameter vector

property A: list[list[float]]

Matrix of Variable coefficients

property F: list[list[float]]

Matrix of Parameteric Variable coefficients

property C: list[float]

Transpose of the Vector of Objective Coefficients \(C^{T}\)

property P: list[list[int]]

Ordinals of continuous variables \(v \in \mathcal{V}\)

Example

The following constraints:

\[ \begin{align}\begin{aligned}5 \cdot \mathbf{v}_2 - 3 \cdot \mathbf{v}_3 + 15.2 \leq 0\\\mathbf{v}_0 = 1\\-4 \cdot \mathbf{v}_3 + \frac{\mathbf{v}_1}{13} = 0\end{aligned}\end{align} \]

Correspond to:

\[\begin{split}P = \begin{bmatrix} 2 & 3 \\ 0 & \\ 3 & 1 \end{bmatrix}\end{split}\]

property Z: list[list[int]]

Ordinals of parametric variables \(\theta \in \Theta\)

Example

The following constraints:

\[ \begin{align}\begin{aligned}\mathbf{v}_1 - 2 \cdot \theta_1 + 21 \leq 0\\\mathbf{v}_0 - 7.23 \cdot \theta_0 = 0\\\theta_1 - 2 \cdot \mathbf{v}_0 - 31.56\end{aligned}\end{align} \]

Corresponds to:

\[\begin{split}Z = \begin{bmatrix} 1 \\ 0 \\ 1 \end{bmatrix}\end{split}\]

property G: list[list[float]]

Coefficient matrix of inequality (leq) constraints

Example

The following constraints:

\[ \begin{align}\begin{aligned}5 \cdot \mathbf{v}_2 - 3 \cdot \mathbf{v}_3 = 0\\-4 \cdot \mathbf{v}_3 + \frac{\mathbf{v}_1}{13} + 0.55 \leq 0\\3.73 \cdot \mathbf{v}_0 - 2 \cdot \theta_1 + 21 \leq 0\end{aligned}\end{align} \]

property H: list[list[float]]

Coefficient matrix of equality constraints

h = 0

property NN: list[list[float]]

Matrix of Variable coefficients for non negative cons

property A_with_NN: list[list[float]]

Matrix of Variable coefficients with non-negative constraints

property B_with_NN: list[float]

RHS Parameter vector with non-negative constraints

property CrA: list[list[float]]

Critical Region A matrix

property CrB: list[float]

Critical Region RHS vector

make_A_df(longname: bool = False) → DataFrame

Create a DataFrame from the A matrix.

Parameters:

longname (bool) – Whether to use long names for variables. Defaults to False.

Returns:

Columns are the variables, rows are the constraints.

Return type:

DataFrame

make_B_df(longname: bool = False) → DataFrame

Create a DataFrame from the B vector.

Parameters:

longname (bool) – Whether to use long names for variables. Defaults to False.

Returns:

Single column DataFrame with the RHS values.

Return type:

DataFrame

make_C_df(longname: bool = False) → DataFrame

Create a DataFrame from the C matrix.

Parameters:

longname (bool) – Whether to use long names for variables. Defaults to False.

Returns:

Single row DataFrame with the objective coefficients.

Return type:

DataFrame

make_df(longname: bool = False) → DataFrame

Create a DataFrame from the model.

Parameters:

longname (bool) – Whether to use long names for variables. Defaults to False.

Returns:

A DataFrame with the A matrix, B vector, and C vector.

Return type:

DataFrame

make_CrA_df(longname: bool = False) → DataFrame

Creates a DataFrame from the Critical Region A matrix.

make_CrB_df(longname: bool = False) → DataFrame

Creates a DataFrame from the Critical Region RHS vector.

make_F_df(longname: bool = False) → DataFrame

Creates a DataFrame from the Theta coefficients matrix.

mps(name: str = None)

MPS File

lp()

LP File

opt(using: str = 'gurobi')

Determine the optimal solution to the program

import_solution(name: str)

Imports a solution from an external file Handles JSON and pickle

Parameters:

name (str) – file name, with extenstion

solve(using: Literal['combinatorial', 'combinatorial_parallel', 'combinatorial_parallel_exp', 'graph', 'graph_exp', 'graph_parallel', 'graph_parallel_exp', 'combinatorial_graph', 'geometric', 'geometric_parallel', 'geometric_parallel_exp'] = 'combinatorial', tol_mat: float = 1e-09, round_off: int = 4)

Solve the multiparametric program

eval(*theta_vals: float, n_sol: int = 0, roundoff: int = 4) → list[float]

Evaluates the variable value as a function of parametric variables

Parameters:

• theta_vals (float) – values of the parametric variables

• n_sol (int, optional) – solution number, defaults to 0

• roundoff (int, optional) – round off the evaluated value, defaults to 4

Returns:

list of values

Return type:

list[float]

Raises:

ValueError – if number of theta values provided does not match number of thetas in the problem

lb(function: V | F)

Finds the lower bound of a variable or function

ub(function: V | F)

Finds the upper bound of a variable or function

obj()

Objective Values

output(n_sol: int = 0, slack: bool = True, compare=False)

Print sol

latex(descriptive: bool = False, categorical: bool = False, category: str = None, as_document: bool = False) → str

Return a LaTeX/Markdown-compatible representation of the mathematical program. - In Markdown mode: uses Markdown headers (##, ###) - In document mode: uses LaTeX section commands

show(descriptive: bool = False, nncons: bool = False, categorical: bool = False, category: str = None)

Pretty Print

draw(variable: V = None, n_sol: int = 0)

Plots the solution for a variable

ppopt() → MPLP_Program

Convert the program to a ppopt.MPLP_Program

gurobi() → Model

Gurobi Model

inf(function: F | V) → O

Minimize the function

Parameters:

function (F) – function to minimize

sup(function: F | V) → O

Maximize the function

Parameters:

function (F) – function to maximize

sigma(variable: V, over: I = None, position: int = None) → F

Summation without recursion, also allows better printing

Parameters:

• variable (V) – variable set

• over (I | None) – over what index

• position (int | None) – position of the index in the variable indices. Defaults to None.

Returns:

summed up function

Return type:

F

Modules

block
operators
sets
shapes
utils
value