Merge pull request #76 from tpaviot/update-doc

Update doc

doc/first_order_logic_constraints.rst

@@ -49,16 +49,12 @@ The logical implication (:math:`\implies`) is wrapped by the :func:`implies` fun
 
 is written in Python:
 
-
 .. code-block:: python
 
     problem.add_constraint(implies(t_2.start == 4,
                                    [TasksEndSynced(t_3, t_4)])
 
 
-.. note::
-	The :func:`implies` and :func:`if_then_else` functions names do not conflict with any other function name from another package, thus dont have any underscore suffix.
-
 Finally, an if/then/else statement is available through the function :func:`if_then_else` which takes 3 parameters: a condition and two lists of assertions that applies whether the condition is :const:`True` or :const:`False`.
 
 .. code-block:: python
@@ -67,3 +63,5 @@ Finally, an if/then/else statement is available through the function :func:`if_t
                                         [TasksEndSynced(t_3, t_4)], # if the condition is True
                                         [TasksStartSynced(t_3, t_4)]) # if the condition is False
 
+.. note::
+The :func:`implies` and :func:`if_then_else` functions names do not conflict with any other function name from another package, thus dont have any underscore suffix.

doc/index.rst

@@ -12,8 +12,10 @@ A a 100% pure python library to compute resource-constrained task schedules. It
    task
    task_constraints
    resource
+   resource_assignment
    resource_constraints
    first_order_logic_constraints
+   indicator
    objectives
    solving
    use-case-flow-shop

doc/indicator.rst

@@ -0,0 +1,36 @@
+Indicator
+=========
+
+:class:`Indicator` class
+------------------------
+
+The :class:`Indicator` class allows to define a criterion that quantifies the schedule so that it can be compared with other schedules. An :class:`Indicator` instance results in a conclusion such a 'this schedule A is better than schedule B because the indicator XXX is greater/lower'.
+
+An :class:`Indicator` instance is created by passing the indicator name as well as the mathematical expression to compute. For example:
+
+.. code-block:: python
+
+    flow_time = Indicator('FlowTime', task1.end + task2.end)
+    duration_square = Indicator('MinTaskDuration', task1.duration ** 2 + task2.duration ** 2)
+
+Indicator values are computed by the solver, and are part of the solution. If the solution rendered as a matplotlib Gantt chart, the indicator values are displayed on the upper right corner of the chart.
+
+Indicators can also be bounded, although it is optional to do so. Imagin, for instance, an indicator that can only assume values from 0 to 100. Then, if we are maximizing (or minimizing) this indicator in our problem, we want the solver to know that 100 (or 0) is the best value it can achieve. Therefore, we would write:
+
+.. code-block:: python
+
+    indicator1 = Indicator('Example1', task2.start - task1.end, bounds = (0,100)) # If lower and upper bounded
+    indicator2 = Indicator('Example2', task3.start - task2.end, bounds = (None,100)) # If only upper bounded
+    indicator3 = Indicator('Example3', task4.start - task3.end, bounds = (0,None)) # If only lower bounded
+
+.. note::
+
+    You can add any number of Indicators. The mathematical expression must be expressed in a polynomial formalism, i.e. you can't use advanced mathematical functions such as :func:`sqrt`, :func:`sin` or whatever.
+
+Resource cost and utilization
+-----------------------------
+Two usual indicators are available : the utilization and cost of a resource (or a list of resources).
+
+Use the :func:`add_indicator_resource_utilization` method to insert a cost computation to your schedule. This method takes a list of resources and compute the total cost (sum of productivity * duration for all resources). The result is a percentage: an utilization of 100% means that the resource is assigned 100% of the schedule timeline.
+
+The :func:`add_indicator_resource_cost` method returns the total cost of a resource (or a list of resource). It is computed using each cost function defined for each resource.

doc/introduction.rst

@@ -23,11 +23,6 @@ The following features are provided:
 
 This document explains how to write the model, run the solver, and finally analyze the solution(s).
 
-
-.. note::
-
-    ProcessScheduler was inspired by the `pyschdedule <https://github.com/timnon/pyschedule>`_ library by Tim Nonner. By choosing to rely on an SMT solver rather than a MIP solver such as CBC/Gurobi/SCIP, ProcessScheduler strongly diverges from its predecessor.
-
 What's inside
 -------------