Merge pull request #26 from rodrigo-arenas/FEATURE/docs

Release 0.4.1

.coveragerc

@@ -8,4 +8,8 @@ omit =
     setup.py
 [report]
 precision = 2
-show_missing = True
+show_missing = True
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+    noqa

.github/workflows/ci-tests.yml

@@ -0,0 +1,42 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: [ 3.7, 3.8, 3.9]
+        os: [ubuntu-latest, windows-latest, macOS-latest]
+        include:
+          - os: ubuntu-latest
+            path: ~/.cache/pip
+          - os: macos-latest
+            path: ~/Library/Caches/pip
+          - os: windows-latest
+            path: ~\AppData\Local\pip\Cache
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/cache@v2
+        with:
+          path: ${{ matrix.path }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('dev-requirements.txt') }}
+          restore-keys: |
+           ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade --upgrade-strategy eager -r dev-requirements.txt -e .
+      - name: Test with pytest
+        run: |
+          pytest pyworkforce/ --verbose --color=yes --assert=plain --cov-fail-under=95 --cov-config=.coveragerc --cov=./ -p no:warnings
+      - name: "Upload coverage to Codecov"
+        uses: codecov/codecov-action@v1
+        with:
+          fail_ci_if_error: true

README.md

@@ -6,21 +6,24 @@
 
 
 # pyworkforce
-Common tools for workforce management, schedule and optimization problems built on top of packages like google's or-tools 
-and custom modules
+Standard tools for workforce management, queue, schedule, and optimization problems built on top of packages like google's or-tools 
+and custom modules.
+Documentatio is available [here](https://pyworkforce.readthedocs.io/)
 
 ## Features:
 pyworkforce currently includes:
 
 [Queue Systems](./pyworkforce/queuing):
-- **queing.ErlangC:** Find the number of positions required to attend incoming traffic to a constant rate, infinite queue length and no dropout.
+- **queing.ErlangC:** Find the number of positions required to attend incoming traffic to a constant rate, 
+  infinite queue length, and no dropout.
 
 [Shifts](./pyworkforce/shifts):
 
-It finds the number of resources to schedule in a shift, based in the number of required positions per time interval (found for example using [queing.ErlangC](./pyworkforce/queuing/erlang.py)), maximum capacity restrictions and static shifts coverage.<br>
-- **shifts.MinAbsDifference:** This module finds the "optimal" assignation by minimizing the total absolute differences between required resources per interval, against the scheduled resources found by the solver.
+It finds the number of resources to schedule in a shift based on the number of required positions per time interval 
+(found, for example, using  [queing.ErlangC](./pyworkforce/queuing/erlang.py)), maximum capacity restrictions and static shifts coverage.<br>
+- **shifts.MinAbsDifference:** This module finds the "optimal" assignation by minimizing the total absolute differences between required resources per interval against the scheduled resources found by the solver.
 - **shifts.MinRequiredResources**: This module finds the "optimal" assignation by minimizing the total weighted amount of scheduled resources (optionally weighted by shift cost), it ensures that in all intervals, there are
-            never less resources shifted that the ones required per period. 
+    never fewer resources shifted than the ones required per period. 
 
 
 # Usage:

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api/erlangc.rst

@@ -0,0 +1,15 @@
+ErlangC
+-------
+
+.. currentmodule:: pyworkforce.queuing
+
+.. autosummary:: ErlangC
+   ErlangC.waiting_probability
+   ErlangC.service_level
+   ErlangC.achieved_occupancy
+   ErlangC.required_positions
+
+.. autoclass:: pyworkforce.queuing.ErlangC
+   :members:
+   :inherited-members:
+   :undoc-members: True

docs/api/min_abs_difference.rst

@@ -0,0 +1,12 @@
+MinAbsDifference
+----------------
+
+.. currentmodule:: pyworkforce.shifts
+
+.. autosummary:: MinAbsDifference
+   MinAbsDifference.solve
+
+.. autoclass:: pyworkforce.shifts.MinAbsDifference
+   :members:
+   :inherited-members:
+   :undoc-members: True

docs/api/min_required_resources.rst

@@ -0,0 +1,12 @@
+MinRequiredResources
+--------------------
+
+.. currentmodule:: pyworkforce.shifts
+
+.. autosummary:: MinRequiredResources
+   MinRequiredResources.solve
+
+.. autoclass:: pyworkforce.shifts.MinRequiredResources
+   :members:
+   :inherited-members:
+   :undoc-members: True

docs/api/multierlangc.rst

@@ -0,0 +1,15 @@
+MultiErlangC
+------------
+
+.. currentmodule:: pyworkforce.queuing
+
+.. autosummary:: MultiErlangC
+   MultiErlangC.waiting_probability
+   MultiErlangC.service_level
+   MultiErlangC.achieved_occupancy
+   MultiErlangC.required_positions
+
+.. autoclass:: pyworkforce.queuing.MultiErlangC
+   :members:
+   :inherited-members:
+   :undoc-members: True

docs/conf.py

@@ -0,0 +1,77 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+from datetime import datetime
+
+sys.path.insert(0, os.path.abspath(".."))
+
+from pyworkforce import __version__
+
+# -- Project information -----------------------------------------------------
+
+project = 'pyworkforce'
+copyright = f"2021--{datetime.now().year}, Rodrigo Arenas Gómez"
+author = 'Rodrigo Arenas Gómez'
+
+release = __version__
+version = __version__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "numpydoc",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinx_rtd_theme",
+    "nbsphinx",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+master_doc = "index"
+
+# generate autosummary even if no references
+autosummary_generate = True
+autosummary_imported_members = True
+
+autoclass_content = "both"
+
+numpydoc_show_class_members = False
+numpydoc_class_members_toctree = False
+
+todo_include_todos = False

docs/index.rst

@@ -0,0 +1,47 @@
+.. pyworkforce documentation master file, created by
+   sphinx-quickstart on Fri May 13 15:38:45 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+pyworkforce
+===========
+Common tools for workforce management,
+schedule and optimization problems built on top of packages like google's
+or-tools and custom modules.
+
+#########################################################################
+This package implements a python interface for common problems in operations research
+applied to queue and scheduling problems, among others.
+
+Installation:
+#############
+
+Install pyworkforce
+
+It's advised to install pyworkforce using a virtual env, inside the env use::
+
+   pip install pyworkforce
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :caption: User Guide / Tutorials:
+
+   tutorials/erlangc
+   tutorials/erlangc_example
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference:
+
+   api/erlangc
+   api/multierlangc
+   api/min_abs_difference
+   api/min_required_resources
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/tutorials/erlangc.rst

@@ -0,0 +1,54 @@
+.. _erlangc:
+
+Understanding ErlangC for Queue Problems
+========================================
+
+Introduction
+------------
+
+Finding the number of positions to use in a queue system has been a study case for a long time now;
+it has applications in several fields and industries, for example, finding the optimal number of call centers agents,
+deciding the number of bankers in a support station, network traffic analysis and so on.
+
+There are several methods to analyze this problem;
+this article will look at how to model it using the ErlangC approach.
+
+Queue System
+------------
+
+In the most fundamental Erlang C method, we represent the system as a queue with the following assumptions:
+
+* There is incoming traffic with a constant rate; the arrivals follow a Poisson process
+* There is a fixed capacity in the system; usually, only one transaction gets handled by a resource at the time
+* There is a fixed number of available positions in a time interval
+* When all the positions have a total capacity, there is an infinite queue length
+  where the requests wait for a position to be free.
+* An exponential distribution describes the holding times in the queue
+* There is no dropout from the queue.
+
+A queue system with these characteristics may look like this:
+
+.. image:: ../images/erlangc_queue_system.png
+
+In this representation, we can see several measures that will help us to describe the system;
+here there are their definitions and how we are going to call them from now on:
+
+* **Transactions:** Number of incoming requests
+* **Resource:** The element that handles a transaction
+* **Arrival rate:** The number of incoming transactions in a time interval
+* **Average speed of answer (ASA):** Average time that a transaction waits in the queue to be attended by a resource
+* **Average handle time (AHT):** Average time that takes to a single resource to attend a transaction
+
+Other variables are in the diagram, but that is important for the model, those are:
+
+* **Shrinkage:** Expected percentage of time that a server is not available, for example,
+  due to breaks, scheduled training, etc.
+* **Occupancy:** Percentage of time that a resource is handling a transaction
+* **Service level:** Percentage of transactions that arrives at a resource before a target ASA
+
+The way as Erlang C find the number of resources in this system is by finding the probability
+that a transaction waits in queue, opposed to immediately being attended, it takes a target ASA
+and service level and uses the others variables as the system parameters, if you want to know more about the details of
+Erlang formulation, you can red the definition `here <https://en.wikipedia.org/wiki/Erlang_(unit)>`_
+
+In the following article, we'll explain how to use pyworkforce to solve this kind of problem.