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()
