Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation updates #84

Merged
merged 2 commits into from
Jul 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/source/advanced.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Advanced Patterns
=================
Adding Specialized Constraints
==============================

``gurobipy-pandas`` helper methods currently only cover building linear and quadratic constraints, i.e. those which can be expressed using pandas' built-in arithmetic, groupby, and aggregation methods. In some cases you may need to build other constraint types, such as SOS or general constraints, between different series of variables. This page provides some simple recipes for such operations.

Expand Down
69 changes: 57 additions & 12 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -1,40 +1,85 @@
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. The package provides simple to use functions and pandas
accessors to help build optimization models efficiently from data and
query solutions as pandas structures.

``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.

Getting Started
---------------
Installation
------------

``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.
: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.

How to use this documentation
-----------------------------

- The :doc:`usage` page provides an overview of the key methods
available for creating variables and constraints in an optimization
model using pandas data as input.
- The :doc:`examples` provide complete model implementations as Jupyter
notebooks.
- The :doc:`api` provides complete reference documentation for the
library.
- The remaining sections (see the contents sidebar for a full listing)
cover further details and techniques, and provide advice on writing
clean and performant model building code using this library.

Contact us
----------

For questions related to using ``gurobipy-pandas`` please use the
`Gurobi Community Forum <https://support.gurobi.com/hc/en-us/community/topics/10373864542609-GitHub-Projects>`_.

For reporting bugs, issues and feature requests, specific to ``gurobipy-pandas``, please
`open an issue <https://github.com/Gurobi/gurobipy-pandas/issues>`_.

If you encounter issues with Gurobi or ``gurobipy`` please contact
`Gurobi Support <https://support.gurobi.com/hc/en-us>`_.

Documentation
-------------

.. toctree::
:hidden:
:maxdepth: 1
:caption: Start
:caption: Getting Started

installation
usage
examples

.. toctree::
:hidden:
:maxdepth: 1
:caption: Model Building
:caption: Users Guide

performance
naming
advanced
typing

.. toctree::
:hidden:
:maxdepth: 1
:caption: Reference

api
typing
license
contact
acknowledgements
4 changes: 2 additions & 2 deletions docs/source/naming.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Variable & Constraint Naming
============================
Naming Variables & Constraints
==============================

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.

Expand Down
4 changes: 2 additions & 2 deletions docs/source/performance.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Performance
===========
Improving Performance
=====================

This section contains general advice for improving the performance of model building code in ``gurobipy-pandas``.

Expand Down
14 changes: 10 additions & 4 deletions docs/source/typing.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
Typing
======
Using 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 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.
4 changes: 2 additions & 2 deletions docs/source/usage.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Usage
=====
Basic Usage
===========

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 <https://pandas.pydata.org/docs/ecosystem.html#accessors>`_ to facilitate building models and querying results from dataframes and series respectively.

Expand Down