OptlangHelper 0.0.3__py3-none-any.whl

optlanghelper/__init__.py

@@ -0,0 +1,15 @@
+# -*- coding: utf-8 -*-
+
+from __future__ import absolute_import
+
+import logging
+
+__author__ = "Andrew Freiburger"
+__email__ = "afreiburger@anl.gov"
+__version__ = "0.0.3"
+
+logger = logging.getLogger(__name__)
+logger.debug("OptlangHelper %s", __version__)
+
+from .optlanghelper import (OptlangHelper, GLPKHelper, CPLEXHelper, GurobiHelper, MatrixHelper,
+                            Bounds, tupVariable, tupConstraint, tupObjective, define_model_auto)

optlanghelper/optlanghelper.py

@@ -0,0 +1,254 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Thu Aug 18 10:26:32 2022
+@author: Andrew Freiburger
+"""
+from collections import namedtuple
+from importlib import import_module
+from optlang import Model
+from typing import Iterable, Union
+import logging
+
+logger = logging.getLogger(__name__)
+
+Bounds = namedtuple("Bounds", ("lb", "ub"), defaults=(0,1000))
+tupVariable = namedtuple("tupVariable", ("name", "bounds", "type"), defaults=("varName", Bounds(), "continuous"))
+tupConstraint = namedtuple("tupConstraint", ("name", "bounds", "expr"), defaults=("consName", Bounds(0,0), None))
+tupObjective = namedtuple("tupObjective", ("name", "expr", "direction"), defaults=("objectiveName", None, "max"))
+
+def isIterable(term):
+    try:
+        iter(term)
+        if type(term) is not str:  return True
+        return False
+    except:  return False
+
+def isnumber(obj):
+    try:  float(obj)  ;  return True
+    except:  return False
+
+def define_term(value):
+    if isnumber(value):
+        return {"type":"Number", "value": value}
+    if isinstance(value, str):
+        return {"type":"Symbol", "name": value}
+    logger.error(f"The {value} of type {type(value)} is not known.")
+
+def get_expression_template(expr):
+    if isinstance(expr, list):
+        return {"type": "Add", "args": []}
+    return {"type": expr["operation"], "args": []}
+
+
+class OptlangHelper:
+    """Bulk construction of an optlang model from tuple/dict descriptions.
+
+    ``interface`` pins the optlang solver interface (``"glpk"``, ``"cplex"``,
+    ``"gurobi"``); when None, optlang's preferred available interface is used
+    (whatever ``from optlang import Model`` resolves to)."""
+
+    interface = None
+
+    @classmethod
+    def _model_cls(cls):
+        if cls.interface is None:
+            return Model
+        try:
+            return import_module(f"optlang.{cls.interface}_interface").Model
+        except Exception as exc:
+            raise ImportError(
+                f"The optlang {cls.interface} interface is unavailable: {exc}") from exc
+
+    @staticmethod
+    def add_variables(var_name:str, var_bounds:(list, tuple), var_type:str="continuous"):
+        assert var_bounds[0] <= var_bounds[1], f"The {var_name} variable lower bound {var_bounds[0]} is greater than the upper bound {var_bounds[1]}.  The lower bound must be less than the upper bound."
+        return {"name": var_name.replace(" ", "_"), "lb": var_bounds[0], "ub": var_bounds[1], "type": var_type}
+
+    @classmethod
+    def add_constraint(cls, cons_name:str, cons_bounds:(list, tuple), cons_expr:dict):
+        assert cons_bounds[0] is None or cons_bounds[1] is None or cons_bounds[0] <= cons_bounds[1], f"The {cons_name} constraint lower bound {cons_bounds[0]} is greater than the upper bound {cons_bounds[1]}.  The lower bound must be less than the upper bound."
+        return {"name": cons_name.replace(" ", "_"),
+                "expression": cls._define_expression(cons_expr),
+                "lb": cons_bounds[0], "ub": cons_bounds[1], "indicator_variable": None, "active_when": 1}
+
+    @classmethod
+    def add_objective(cls, obj_name:str, objective_expr:Union[dict, list], direction:str):
+        if isinstance(objective_expr, list):
+            obj_expr = {"type": "Add", "args": [
+                cls._define_expression(expr) for expr in objective_expr]}
+        elif isinstance(objective_expr, dict):
+            obj_expr = {"type": objective_expr["operation"],
+                        "args": [define_term(term) for term in objective_expr["elements"]]}
+        return {"name": obj_name.replace(" ", "_"), "expression": obj_expr, "direction": direction}
+
+    @classmethod
+    def define_model(cls, model_name, variables, constraints, objective, optlang=False):
+        model = {'name':model_name, 'variables':[], 'constraints':[]}
+        for var in variables:
+            var = list(var)
+            if len(var) == 2:  var.append("continuous")
+            model["variables"].append(cls.add_variables(var[0], var[1], var[2]))
+        for cons in constraints:
+            model["constraints"].append(cls.add_constraint(cons[0], cons[1], cons[2]))
+        model["objective"] = cls.add_objective(objective[0], objective[1], objective[2])
+        if optlang:  return cls._model_cls().from_json(model)
+        return model
+
+    @classmethod
+    def _define_expression(cls, expr:dict):
+        expression = get_expression_template(expr)
+        level1_coef = 0
+        for ele in expr["elements"]:
+            if not isnumber(ele) and not isinstance(ele, str):
+                arguments = []
+                level2_coef = 0
+                for ele2 in ele["elements"]:
+                    if not isnumber(ele2) and not isinstance(ele2, str):
+                        arguments.append(cls._define_expression(ele2))
+                    elif isinstance(ele2, str): arguments.append(define_term(ele2))
+                    else:  level2_coef += float(ele2)
+                expression["args"].append(get_expression_template(ele))
+                if level2_coef != 0:  arguments.append(define_term(level2_coef))
+                expression["args"][-1]["args"] = arguments
+            elif isinstance(ele, str): expression["args"].append(define_term(ele))
+            else:  level1_coef += float(ele)
+        if level1_coef != 0:  expression["args"].append(define_term(level1_coef))
+        return expression
+
+    @staticmethod
+    def dot_product(zipped_to_sum, heuns_coefs=None):
+        # ensure that the lengths are compatible for heun's dot-products
+        if heuns_coefs is not None:
+            coefs = heuns_coefs if isinstance(heuns_coefs, (list, set)) else heuns_coefs.tolist()
+            zipped_length = len(zipped_to_sum); coefs_length = len(coefs)
+            if zipped_length != coefs_length:
+                raise IndexError(f"ERROR: The length of zipped elements {zipped_length}"
+                                 f" is unequal to that of coefficients {coefs_length}")
+
+        elements = []
+        for index, (term1, term2) in enumerate(zipped_to_sum):
+            if heuns_coefs is not None:
+                elements.extend([{"operation": "Mul", "elements": [heuns_coefs[index], term1]},
+                                 {"operation": "Mul", "elements": [heuns_coefs[index], term2]}])
+            else:
+                elements.append({"operation": "Mul", "elements": [term1, term2]})
+        return elements
+
+
+class GLPKHelper(OptlangHelper):
+    interface = "glpk"
+
+class CPLEXHelper(OptlangHelper):
+    interface = "cplex"
+
+class GurobiHelper(OptlangHelper):
+    interface = "gurobi"
+
+
+# --------------------------------------------------------------------------- matrix path
+def _linear_terms(expr, var_index):
+    """Flatten a tuple-format linear expression into ({var_idx: coef}, constant).
+
+    Handles the shapes produced by ``dot_product``/``tupConstraint``: an Add of
+    Mul-dicts, bare variable names, and numeric constants; Muls may hold the
+    coefficient and variable in either order. Nested Adds are recursed."""
+    coefs, const = {}, 0.0
+    elements = expr["elements"] if isinstance(expr, dict) else expr
+    for ele in elements:
+        if isinstance(ele, str):
+            coefs[var_index[ele]] = coefs.get(var_index[ele], 0.0) + 1.0
+        elif isnumber(ele):
+            const += float(ele)
+        elif isinstance(ele, dict) and ele.get("operation") == "Mul":
+            coef, name = 1.0, None
+            for ele2 in ele["elements"]:
+                if isinstance(ele2, str):  name = ele2
+                elif isnumber(ele2):  coef *= float(ele2)
+                else:  raise ValueError(f"Non-linear or nested Mul term is not supported by the matrix path: {ele}")
+            if name is None:  const += coef
+            else:  coefs[var_index[name]] = coefs.get(var_index[name], 0.0) + coef
+        elif isinstance(ele, dict) and ele.get("operation") == "Add":
+            sub_coefs, sub_const = _linear_terms(ele, var_index)
+            const += sub_const
+            for j, c in sub_coefs.items():  coefs[j] = coefs.get(j, 0.0) + c
+        else:
+            raise ValueError(f"Unsupported expression element for the matrix path: {ele}")
+    return coefs, const
+
+
+class MatrixHelper:
+    """CSR/gurobipy construction for very large LPs.
+
+    optlang's per-constraint interfaces scale super-linearly (~n^1.8 measured on
+    Gurobi: 48 s at 1e5 constraints, ~90 min extrapolated at 1.4e6), while
+    gurobipy ingests a CSR matrix in C time (seconds at 1.4e6 constraints).
+    Requires numpy, scipy, and gurobipy (``pip install OptlangHelper[matrix]``).
+    Returns a ``gurobipy.Model`` (``.optimize()``; status 2 == optimal), NOT an
+    optlang model."""
+
+    @staticmethod
+    def define_model(model_name, variables, constraints, objective, verbose=False):
+        import numpy as np
+        from scipy.sparse import coo_matrix
+        import gurobipy as gp
+
+        names, lbs, ubs = [], [], []
+        for var in variables:
+            var = list(var)
+            name = var[0].replace(" ", "_")
+            names.append(name); lbs.append(float(var[1][0])); ubs.append(float(var[1][1]))
+        var_index = {n: j for j, n in enumerate(names)}
+
+        rows_eq, rows_le, rows_ge = [], [], []   # (coefs, rhs)
+        for cons in constraints:
+            _, bounds, expr = cons[0], cons[1], cons[2]
+            coefs, const = _linear_terms(expr, var_index)
+            lb = None if bounds[0] is None else float(bounds[0]) - const
+            ub = None if bounds[1] is None else float(bounds[1]) - const
+            if lb is not None and ub is not None and lb == ub:
+                rows_eq.append((coefs, lb))
+            else:
+                if ub is not None:  rows_le.append((coefs, ub))
+                if lb is not None:  rows_ge.append((coefs, lb))
+
+        env = gp.Env(empty=True); env.setParam("OutputFlag", 1 if verbose else 0); env.start()
+        model = gp.Model(model_name, env=env)
+        x = model.addMVar(len(names), lb=np.array(lbs), ub=np.array(ubs))
+        model._var_names = names
+        model._var_index = var_index
+
+        def add_block(rows, sense):
+            if not rows:  return
+            r, c, v, rhs = [], [], [], []
+            for i, (coefs, b) in enumerate(rows):
+                rhs.append(b)
+                for j, coef in coefs.items():
+                    r.append(i); c.append(j); v.append(coef)
+            S = coo_matrix((v, (r, c)), shape=(len(rows), len(names))).tocsr()
+            model.addMConstr(S, x, sense, np.array(rhs))
+        add_block(rows_eq, "="); add_block(rows_le, "<"); add_block(rows_ge, ">")
+
+        obj_expr = objective[1] if isinstance(objective[1], (list, dict)) else [objective[1]]
+        if isinstance(obj_expr, list):
+            obj_expr = {"elements": obj_expr, "operation": "Add"}
+        ocoefs, oconst = _linear_terms(obj_expr, var_index)
+        lin = gp.LinExpr(oconst)
+        for j, coef in ocoefs.items():  lin += coef * x[j]
+        model.setObjective(lin, gp.GRB.MAXIMIZE if objective[2] in ("max", "maximize") else gp.GRB.MINIMIZE)
+        model._mvar = x
+        return model
+
+
+def define_model_auto(model_name, variables, constraints, objective, limit=300000, helper=None):
+    """Size-aware dispatch: optlang construction up to ``limit`` constraints,
+    CSR/gurobipy (``MatrixHelper``) beyond it.
+
+    Below the limit an OPTLANG model is returned (from ``helper`` or
+    ``OptlangHelper``); above it a GUROBIPY model is returned — both expose
+    ``.optimize()``, but their status/attribute APIs differ, so branch on
+    ``isinstance`` or on ``len(constraints) > limit`` when reading results."""
+    if len(constraints) <= limit:
+        return (helper or OptlangHelper).define_model(model_name, variables, constraints, objective, optlang=True)
+    logger.info(f"{model_name}: {len(constraints)} constraints exceeds limit={limit}; "
+                "building through MatrixHelper (gurobipy CSR)")
+    return MatrixHelper.define_model(model_name, variables, constraints, objective)

optlanghelper-0.0.3.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: OptlangHelper
+Version: 0.0.3
+Summary: Python package for building Linear Programming models that are compatible with Optlang
+Home-page: https://github.com/Freiburgermsu/OptlangHelper
+Author: Andrew Freiburger
+Author-email: afreiburger@anl.gov
+Project-URL: Issues, https://github.com/Freiburgermsu/OptlangHelper/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Natural Language :: English
+Description-Content-Type: text/x-rst
+Requires-Dist: optlang
+Provides-Extra: matrix
+Requires-Dist: numpy; extra == "matrix"
+Requires-Dist: scipy; extra == "matrix"
+Requires-Dist: gurobipy; extra == "matrix"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+
+
+Efficiently creating optimization models
+________________________________________________________________________
+
+|PyPI version| |License|
+
+.. |Supported Python Versions| image:: https://img.shields.io/pypi/pyversions/optlanghelper)
+   :target: https://pypi.org/project/optlanghelper/
+   :alt: Python versions
+
+.. |PyPI version| image:: https://img.shields.io/pypi/v/optlanghelper.svg?logo=PyPI&logoColor=brightgreen
+   :target: https://pypi.org/project/optlanghelper/
+   :alt: PyPI version
+
+.. |Actions Status| image:: https://github.com/freiburgermsu/optlanghelper/workflows/Test%20optlanghelper/badge.svg
+   :target: https://github.com/freiburgermsu/optlanghelper/actions
+   :alt: Actions Status
+
+.. |License| image:: https://img.shields.io/badge/License-MIT-blue.svg
+   :target: https://opensource.org/licenses/MIT
+   :alt: License
+
+.. .. |Downloads| image:: https://pepy.tech/badge/modelseedpy
+..    :target: https://pepy.tech/project/modelseedpy
+..    :alt: Downloads
+
+
+.. note::
+
+   This project is under active development, and may be subject to losing back-compatibility.
+
+----------------------
+Installation
+----------------------
+
+OptlangHelper can be installed via ``pip`` through the ``PyPI`` channel::
+
+ pip install optlanghelper
+
+
+----------------------
+Usage
+----------------------
+
+The OptlangHelper package is a collection of functions that make it easier to build linear programming models using the Optlang package.   This is accomplished through dictionaries of variables, constraints, and an objective that are added to a model at the end of iterating through all conditions.  Since each solver -- such as GLPK, CPLEX, and GUROBI -- differently defines variables and constraints, a separate class (although using the same function design and arguments) is provided for each of these solvers.  This requires the user to correctly select the proper OptlangHelper class that will construct the appropriate model for their solver.
+
+****************
+GLPK
+****************
+
+The GLPK class is used to construct an optlang model for the GLPK solver.  This is the simplest of the solvers and is employed by default for optlang without specification for CPlex or Gurobi.
+
+++++++++++++++++++++++
+Named Tuples
+++++++++++++++++++++++
+
+There are several NamedTuples that are defined in OptlangHelper and assist with defining variables, constraints, and the objective.
+
+``Bounds`` object has attributes of 
+
+- ``lb``, the lower bound of the entity associated with this bound:  default is 0.
+- ``up``, the upper bound of the associated entity:  default is 1000.
+
+
+``tupVariable`` object has attributes of 
+
+- ``name``, the name of the variable represented by this tuple
+- ``bounds``, the lower and upper limit bounds associated with the tuple: (0,1000) is the default
+- ``type``, the variable type: "integer"; "binary"; "continuous" is the default.
+
+
+``tupConstraint`` object has attributes of 
+
+- ``name``, the name of the variable represented by this tuple
+- ``bounds``, the lower and upper limit bounds associated with the tuple: (0,0) is the default
+- ``expr``, the constraint expression: ``None`` is the default.
+
+
+``tupObjective`` object has attributes of 
+
+- ``name``, the name of the variable represented by this tuple
+- ``expr``, the objective expression: ``None`` is the default.
+- ``direction``, the optimization direction: "max" is the default.
+
+All of the above objects are fed into the ``define_model`` function
+
+- ``model_name``, the name of the model
+- ``variables``, the tupVariable objects for the model.
+- ``constraints``, the tupConstraint objects for the model.
+- ``objective``, the tupObjective object for the model.
+- ``optlang``, specifies whether an optlang model is returned (``True``), or the raw dictionary (``False``) by default.
+
+This function calls all of the class functions and returns either the GLPK model as as dictionary or an optlang object.
+
+
+++++++++++++++++++++++
+Example
+++++++++++++++++++++++
+
+ The following blocks define the intended usage of the GLPK class.
+
+
+.. code-block:: python
+
+ from optlanghelper import tupVariable, tupConstraint, tupObjective, define_model
+
+ # define the variables
+ variables = {}
+ for var in vars:
+     variables[var.name] = tupVariable(var.name, Bounds(0, 5), "continuous")
+     variables[var.name+"_bin"] = tupVariable(var.name+"_bin", Bounds(0, 1), "binary")
+
+ # define the constraints
+ constraints = {}
+ for name, content in constraint_info.items():
+    lb, ub = content["low_bound"], content["high_bound"]
+    consExpr = {}
+    ## define the constraint expression
+    for varName, coef in var_info.items():
+        if varName not in consCoefs:  continue
+        coef2 = consCoefs[varName]
+        consExpr[varName].update({"elements": [varName, coef2], "operation": "Mul"})
+    ## create the constraint tuple
+    constraints[nutrient] = tupConstraint(name=nutrient, bounds=Bounds(lb, ub), expr={"elements": list(consExpr.values()), "operation": "Add"})
+
+ for varName in var_info.keys():
+    constraints[varName+"_bin"] = tupConstraint(varName+"_bin", bounds=Bounds(0,None),
+                                             expr={
+                                                 "elements": [
+                                                     variables[varName].bounds.ub,
+                                                     {"elements": [-1, variables[varName].name,], "operation": "Mul"},
+                                                     {"elements": [-variables[varName].bounds.ub, variables[varName+"_bin"].name], "operation": "Mul"}],
+                                                "operation": "Add"})
+
+ # define the objective
+ objective = tupObjective("< optimization name>", [], "min")
+ for varName, coef in var_info.items():
+     objective.expr.append({
+         "elements": [
+             {"elements": [variables[varName].name, coef],
+             "operation": "Mul"}],
+         "operation": "Add"
+     })
+
+ # create an optlang model from all of the variables, constraints, and objective defined above
+ model = define_model("< model name>", list(variables.values()), list(constraints.values()), objective, True)
+
+
+Release 0.0.3
+----------------------
+
+Bug fixes
+
++ the published 0.0.2 wheel was unimportable (``__init__`` imported from the package
+  name instead of the submodule) and crashed on nested expressions (a stale internal
+  reference to the pre-rename class); both are fixed and covered by tests.
++ ``__version__`` is synchronized with the package metadata, and the import-time
+  ``print`` is now a debug log line.
+
+New
+
++ the historic ``OptlangHelper`` class is restored as the solver-agnostic base;
+  ``GLPKHelper`` / ``CPLEXHelper`` / ``GurobiHelper`` are interface-pinned subclasses
+  (previously the latter two were empty stubs).
++ ``MatrixHelper.define_model`` builds very large LPs as a sparse CSR matrix directly
+  through ``gurobipy`` (install with ``pip install OptlangHelper[matrix]``): optlang's
+  per-constraint interfaces scale super-linearly (~n^1.8 measured on Gurobi — 48 s at
+  1e5 constraints, ~90 min extrapolated at 1.4e6), while the CSR path ingests 1.4e6
+  constraints in seconds.
++ ``define_model_auto(name, variables, constraints, objective, limit=300000)``
+  dispatches by size: an optlang model at or below ``limit`` constraints, a gurobipy
+  model above it (both expose ``.optimize()``; their result APIs differ).
+
+.. code-block:: python
+
+ from optlanghelper import define_model_auto
+
+ model = define_model_auto("community_fba", variables, constraints, objective)
+ model.optimize()

optlanghelper-0.0.3.dist-info/RECORD

@@ -0,0 +1,6 @@
+optlanghelper/__init__.py,sha256=Oc74Eqs8H6GCwfvfokBW3MjbJ8UFg_ASpY1TIW54sQs,448
+optlanghelper/optlanghelper.py,sha256=6-8ErwT3THsfm-fuUEvp33MQ7MRQKIzlpDGZd0FfA1U,11949
+optlanghelper-0.0.3.dist-info/METADATA,sha256=digciYF_1pVEzoqlYooHHO7XC2GYzXoTmBC1DRTTBHU,8741
+optlanghelper-0.0.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+optlanghelper-0.0.3.dist-info/top_level.txt,sha256=C9TGd-LQ2lpHk_VliXn3f_8u7pdq9ougRebrE3JvOEk,14
+optlanghelper-0.0.3.dist-info/RECORD,,

optlanghelper-0.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

optlanghelper-0.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+optlanghelper