From f85398e072f62f7da6e1d04c76dd9ba81ea0cbcd Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 09:55:40 +1000 Subject: [PATCH 01/10] Reformat and restructure landing page --- docs/source/index.rst | 48 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 8 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index b6e1901..ed87bf2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,25 +1,57 @@ -Welcome to gurobipy-pandas's documentation! -=========================================== +gurobipy-pandas documentation +============================= -``gurobipy-pandas`` is a convenient (optional) wrapper to connect pandas with gurobipy. It enables users to more easily and efficiently build mathematical optimization models from data stored in DataFrames and Series, and to read solutions back directly as pandas objects. +``gurobipy-pandas`` is a convenient (optional) wrapper to connect +:pypi:`pandas` with :pypi:`gurobipy`. It enables users to more easily +and efficiently build mathematical optimization models from data stored +in DataFrames and Series, and to read solutions back directly as pandas +objects. -``gurobipy-pandas`` is aimed at experienced pandas users who are familiar with methods to transform, group, and aggregate data stored in dataframes. It expects some familiarity with optimization modelling, but does not require deep experience with gurobipy. +``gurobipy-pandas`` is aimed at experienced pandas users who are +familiar with methods to transform, group, and aggregate data stored in +dataframes. It expects some familiarity with optimization modelling, but +does not require deep experience with gurobipy. + +Installation +------------ + +:code:`gurobipy-pandas` can be installed directly from PyPI:: + + python -m pip install gurobipy-pandas + +This will also install pandas and gurobipy as dependencies. Please note +that gurobipy is commercial software and requires a license. The package +ships with an evaluation license which is only for testing and can only +solve models of limited size. You will be able to run all the examples +given in this documentation using this evaluation license. Getting Started --------------- -``gurobipy-pandas`` provides simple to use functions and pandas accessors to help build optimization models and query solutions. Read the :doc:`usage` page first for an overview of the key methods. Second, explore the :doc:`examples` which provide complete model implementations formatted as Jupyter notebooks. The later sections cover advanced techniques, and advice on writing clean and performant model building code using this library. +``gurobipy-pandas`` provides simple to use functions and pandas +accessors to help build optimization models and query solutions. Read +the :doc:`usage` page first for an overview of the key methods. Second, +explore the :doc:`examples` which provide complete model implementations +formatted as Jupyter notebooks. The later sections cover advanced +techniques, and advice on writing clean and performant model building +code using this library. Documentation ------------- .. toctree:: - :maxdepth: 1 - :caption: Start + :hidden: installation usage - examples + +.. toctree:: + :maxdepth: 1 + :caption: Examples + + examples/projects + examples/regression + examples/workforce .. toctree:: :maxdepth: 1 From af5c9dca659a3d9efb428c94a058ae2111088c97 Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 09:55:50 +1000 Subject: [PATCH 02/10] Update typing guidance --- docs/source/typing.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/source/typing.rst b/docs/source/typing.rst index 65e4b64..5ea08f8 100644 --- a/docs/source/typing.rst +++ b/docs/source/typing.rst @@ -1,6 +1,12 @@ Typing ====== -The ``gurobipy-pandas`` API is partially typed. There is currently no mechanism in Python's type system to allow for type checking of the DataFrame or Series accessor methods. So, it is only possible to get type checking in your IDE, or static type checking with tools like ``mypy`` if you use the free functions ``gppd.add_vars`` and ``gppd.add_constrs`` when building your model. +The ``gurobipy-pandas`` API is partially typed. There is currently no +mechanism in Python's type system to allow for type checking of the +DataFrame or Series accessor methods. So, it is only possible to get +type checking in your IDE, or static type checking with tools like +``mypy`` if you use the global functions ``gppd.add_vars`` and +``gppd.add_constrs`` when building your model. -To enable type checking, you should also install ``pandas-stubs`` and ``gurobipy-stubs`` in your Python environment. +To enable type checking, you will also need to install +:pypi:`pandas-stubs` in your Python environment. From c4ea6326247d6f6269382e5e335dfd9d9368869c Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 11:43:31 +1000 Subject: [PATCH 03/10] Update docs structure --- docs/source/index.rst | 8 ++++---- docs/source/inspect.rst | 10 ++++++++++ docs/source/modify.rst | 14 ++++++++++++++ 3 files changed, 28 insertions(+), 4 deletions(-) create mode 100644 docs/source/inspect.rst create mode 100644 docs/source/modify.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index ed87bf2..6ae4640 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -55,17 +55,17 @@ Documentation .. toctree:: :maxdepth: 1 - :caption: Model Building + :caption: How To ... - performance - naming - advanced + Avoid Performance Pitfalls + Add Specialized Constraints .. toctree:: :maxdepth: 1 :caption: Reference api + naming typing license contact diff --git a/docs/source/inspect.rst b/docs/source/inspect.rst new file mode 100644 index 0000000..5f860d5 --- /dev/null +++ b/docs/source/inspect.rst @@ -0,0 +1,10 @@ +Inspecting Models +================= + +TODO + +- Show some examples of inspecting vars and constraints in interactive + mode (for sanity checks). +- Note that this doesn't replace proper testing for production-level + code. But it is a useful tool when developing to check that a given + pandas operation produces the constraints you expect. diff --git a/docs/source/modify.rst b/docs/source/modify.rst new file mode 100644 index 0000000..2a3aaaf --- /dev/null +++ b/docs/source/modify.rst @@ -0,0 +1,14 @@ +Modifying Models +================ + +TODO + +- Modifying the RHS of constraints (using Gurobi attributes) + - Mention gotchas around how the sense & RHS are defined +- Modifying variable bounds + - Note that it's best to include any necessary bounds from the beginning +- Fixing variables (testing scenarios) +- Adding constraints (this is no different after solving a model) +- Modifying coefficients +- Note that in some cases, just writing your model as a parameterised + function is a cleaner/better approach From 0bcfb0ff0ecb843d87b82ad91ed36afc215a9ded Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 11:57:11 +1000 Subject: [PATCH 04/10] Mark old examples page as orphan --- docs/source/examples.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/examples.rst b/docs/source/examples.rst index e8d5528..20120f0 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -1,3 +1,5 @@ +:orphan: + Examples ======== From e75acc0c38755cb36a21e6347934d8c3226715a7 Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 11:45:18 +1000 Subject: [PATCH 05/10] Rename some pages --- docs/source/naming.rst | 4 ++-- docs/source/typing.rst | 4 ++-- docs/source/usage.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/naming.rst b/docs/source/naming.rst index 47fbb82..8b9a4d8 100644 --- a/docs/source/naming.rst +++ b/docs/source/naming.rst @@ -1,5 +1,5 @@ -Variable & Constraint Naming -============================ +Variable & Constraint Names +=========================== It's good practice to name variables and constraints in optimization models. One good reason is that once a model is formulated from a dataset, you can write it to LP format for checking and debugging purposes. diff --git a/docs/source/typing.rst b/docs/source/typing.rst index 5ea08f8..58235fe 100644 --- a/docs/source/typing.rst +++ b/docs/source/typing.rst @@ -1,5 +1,5 @@ -Typing -====== +Type Hints +========== The ``gurobipy-pandas`` API is partially typed. There is currently no mechanism in Python's type system to allow for type checking of the diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 3da8a46..98126a0 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,5 +1,5 @@ -Usage -===== +Tutorial +======== This page gives a brief run through of methods used to build optimization models in ``gurobipy-pandas`` and extract solutions. ``gurobipy-pandas`` provides several free functions for model building, and implements pandas' `accessors `_ to facilitate building models and querying results from dataframes and series respectively. From 6cd40acee13dfc26995b146e1af8fdda1b3d0d6f Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 12:17:47 +1000 Subject: [PATCH 06/10] Try nested structure --- docs/source/index.rst | 24 ++---------------------- 1 file changed, 2 insertions(+), 22 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 6ae4640..f90f671 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,29 +44,9 @@ Documentation installation usage - -.. toctree:: - :maxdepth: 1 - :caption: Examples - - examples/projects - examples/regression - examples/workforce - -.. toctree:: - :maxdepth: 1 - :caption: How To ... - - Avoid Performance Pitfalls - Add Specialized Constraints - -.. toctree:: - :maxdepth: 1 - :caption: Reference - + examples + howto api - naming - typing license contact acknowledgements From 9dd76c35150bf4f322799177bbf08051bcb628b9 Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 12:18:49 +1000 Subject: [PATCH 07/10] delete pages --- docs/source/inspect.rst | 10 ---------- docs/source/modify.rst | 14 -------------- 2 files changed, 24 deletions(-) delete mode 100644 docs/source/inspect.rst delete mode 100644 docs/source/modify.rst diff --git a/docs/source/inspect.rst b/docs/source/inspect.rst deleted file mode 100644 index 5f860d5..0000000 --- a/docs/source/inspect.rst +++ /dev/null @@ -1,10 +0,0 @@ -Inspecting Models -================= - -TODO - -- Show some examples of inspecting vars and constraints in interactive - mode (for sanity checks). -- Note that this doesn't replace proper testing for production-level - code. But it is a useful tool when developing to check that a given - pandas operation produces the constraints you expect. diff --git a/docs/source/modify.rst b/docs/source/modify.rst deleted file mode 100644 index 2a3aaaf..0000000 --- a/docs/source/modify.rst +++ /dev/null @@ -1,14 +0,0 @@ -Modifying Models -================ - -TODO - -- Modifying the RHS of constraints (using Gurobi attributes) - - Mention gotchas around how the sense & RHS are defined -- Modifying variable bounds - - Note that it's best to include any necessary bounds from the beginning -- Fixing variables (testing scenarios) -- Adding constraints (this is no different after solving a model) -- Modifying coefficients -- Note that in some cases, just writing your model as a parameterised - function is a cleaner/better approach From b48297ab9fdefcfac68b246f90fd02e2eb079d53 Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 12:19:28 +1000 Subject: [PATCH 08/10] Add how-to sub-page --- docs/source/howto.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/source/howto.rst diff --git a/docs/source/howto.rst b/docs/source/howto.rst new file mode 100644 index 0000000..1e776e0 --- /dev/null +++ b/docs/source/howto.rst @@ -0,0 +1,11 @@ +How-To Guides +============= + +.. toctree:: + :maxdepth: 1 + :caption: How To ... + + Avoid Performance Pitfalls + Add Specialized Constraints + Name Variables and Constraints + Use Type Hinting From 76a7d6696c619e23775f2f65c6c54f91621d18a3 Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 12:28:39 +1000 Subject: [PATCH 09/10] Front page rewrite --- docs/source/index.rst | 44 ++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index f90f671..e63d371 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,25 +19,43 @@ Installation python -m pip install gurobipy-pandas -This will also install pandas and gurobipy as dependencies. Please note -that gurobipy is commercial software and requires a license. The package -ships with an evaluation license which is only for testing and can only -solve models of limited size. You will be able to run all the examples -given in this documentation using this evaluation license. +This will also install pandas and gurobipy as dependencies. -Getting Started ---------------- +Please note that gurobipy is commercial software and requires a license. +The package ships with an evaluation license which is only for testing +and can only solve models of limited size. You will be able to run all +the examples given in this documentation using this evaluation license. + +A Simple Example +---------------- + +Build a simple optimization model! + +How to Use this Documentation +----------------------------- ``gurobipy-pandas`` provides simple to use functions and pandas accessors to help build optimization models and query solutions. Read the :doc:`usage` page first for an overview of the key methods. Second, explore the :doc:`examples` which provide complete model implementations -formatted as Jupyter notebooks. The later sections cover advanced -techniques, and advice on writing clean and performant model building -code using this library. +formatted as Jupyter notebooks. The :doc:`howto` cover methods for +specific use-cases and provide advice on writing clean and performant +model building code using this library. The :doc:`api` provides complete +reference documentation for the library. + +Contact Us +---------- + +For questions related to using gurobipy-pandas please use the +`Gurobi Community Forum `_. + +For reporting bugs, issues and feature requests, specific to ``gurobipy-pandas``, please +`open an issue `_. + +If you encounter issues with Gurobi or ``gurobipy`` please contact +`Gurobi Support `_. + -Documentation -------------- .. toctree:: :hidden: @@ -45,7 +63,7 @@ Documentation installation usage examples - howto + How To ... api license contact From 6c43a60740fb9cb23252ec37b26b5a0ef204326f Mon Sep 17 00:00:00 2001 From: Simon Bowly Date: Sat, 20 Jul 2024 12:30:21 +1000 Subject: [PATCH 10/10] No longer an orphan --- docs/source/examples.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/source/examples.rst b/docs/source/examples.rst index 20120f0..e8d5528 100644 --- a/docs/source/examples.rst +++ b/docs/source/examples.rst @@ -1,5 +1,3 @@ -:orphan: - Examples ========