fix set partition problem case study docs (#827)

* remove build from gitignore

* commit doc build output

* fix references

* remove compile output

* Type examples/ (#819)

* initial pass

* black + isort

* add ignores in pulp.py and pulp/__init__.py

* start fixing mypy errors

* fix some mypy

* mypy passes

* move Pattern class definition to be before use

* restore gitignore

* whiskas 1

* whiskas 2

Author: frrad

doc/source/CaseStudies/a_blending_problem.rst

@@ -90,12 +90,14 @@ for this example is found in :download:`WhiskasModel1.py <../../../examples/Whis
 The start of the your file should then be headed with a short commenting section outlining the purpose of the program. For example:
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 1-5
+    :start-after: # BEGIN file_docstring
+    :end-before: # END file_docstring
 
 Then you will import PuLP's functions for use in your code:
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 7-8
+    :start-after: # BEGIN import_pulp
+    :end-before: # END import_pulp
 
 A variable called ``prob`` (although its name is not important) is
 created using the :class:`~pulp.LpProblem` function. It has two parameters, the first
@@ -104,7 +106,8 @@ parameter being either ``LpMinimize`` or ``LpMaximize`` depending on the
 type of LP you are trying to solve:
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 10-11
+    :start-after: # BEGIN define_prob
+    :end-before: # END define_prob
 
 The problem variables ``x1`` and ``x2`` are created using the
 :class:`~pulp.LpVariable` class. It has four parameters, the first is the
@@ -132,15 +135,17 @@ or::
 To explicitly create the two variables needed for this problem:
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 13-15
+    :start-after: # BEGIN chicken_beef_vars
+    :end-before: # END chicken_beef_vars
 
 The variable ``prob`` now begins collecting problem data with the
 ``+=`` operator. The objective function is logically entered first, with
 an important comma ``,`` at the end of the statement and a short string
 explaining what this objective function is:
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 17-18
+    :start-after: # BEGIN obj_func
+    :end-before: # END obj_func
 
 The constraints are now entered (Note: any "non-negative"
 constraints were already included when defining the variables). This is
@@ -150,7 +155,8 @@ comma at the end of the constraint equation and a brief description of
 the cause of that constraint:
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 20-25
+    :start-after: # BEGIN constraints
+    :end-before: # END constraints
 
 Now that all the problem data is entered, the :meth:`~pulp.LpProblem.writeLP` function
 can be used to copy this information into a .lp file into the directory
@@ -166,14 +172,16 @@ seen frequently in Object Oriented software (such as this):
 
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 27-28
+    :start-after: # BEGIN lp_file
+    :end-before: # END lp_file
 
-The LP is solved using the solver that PuLP chooses. The input
-brackets after :meth:`~pulp.LpProblem.solve` are left empty in this case, however they can be
+The LP is solved using the solver that PuLP chooses. The input brackets after
+:meth:`~pulp.LpProblem.solve` are left empty in this case, however they can be
 used to specify which solver to use (e.g ``prob.solve(CPLEX())`` ):
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 30-31
+    :start-after: # BEGIN prob_solve
+    :end-before: # END prob_solve
 
 Now the results of the solver call can be displayed as output to
 us. Firstly, we request the status of the solution, which can be one of
@@ -184,13 +192,15 @@ to its significant text meaning using the
 :attr:`~pulp.constants.LpStatus` is a dictionary(:obj:`dict`), its input must be in square brackets:
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 33-34
+    :start-after: # BEGIN print_status
+    :end-before: # END print_status
 
 The variables and their resolved optimum values can now be printed
 to the screen. 
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 36-38
+    :start-after: # BEGIN print_var_value
+    :end-before: # END print_var_value
 
 The ``for`` loop makes ``variable`` cycle through all
 the problem variable names (in this case just ``ChickenPercent`` and
@@ -207,7 +217,8 @@ format to be displayed. :attr:`~pulp.LpProblem.objective` is an attribute of the
 ``prob``:
 
 .. literalinclude:: ../../../examples/WhiskasModel1.py
-    :lines: 40-41
+    :start-after: # BEGIN print_obj
+    :end-before: # END print_obj
 
 Running this file should then produce the output to show that 
 Chicken will make up 33.33%, Beef will make up 66.67% and the 
@@ -291,32 +302,36 @@ As with last time, it is advisable to head your file with commenting on its
 purpose, and the author name and date. Importing of the PuLP functions is also done in the same way:
 
 .. literalinclude:: ../../../examples/WhiskasModel2.py
-    :lines: 1-8
+    :start-after: # BEGIN docstring_imports
+    :end-before: # END docstring_imports
 
 Next, before the ``prob`` variable or type of problem are defined,
 the key problem data is entered into dictionaries. This includes the
-list of Ingredients, followed by the cost of each Ingredient, and it's
+list of Ingredients, followed by the cost of each Ingredient, and its
 percentage of each of the four nutrients. These values are clearly laid
 out and could easily be changed by someone with little knowledge of
 programming. The ingredients are the reference keys, with the numbers as
 the data.
 
 .. literalinclude:: ../../../examples/WhiskasModel2.py
-    :lines: 10-61
+    :start-after: # BEGIN problem_data
+    :end-before: # END problem_data
 
 The ``prob`` variable is created to contain the formulation, and the
 usual parameters are passed into :class:`~pulp.LpProblem`.
 
 .. literalinclude:: ../../../examples/WhiskasModel2.py
-    :lines: 63-64
+    :start-after: # BEGIN define_prob
+    :end-before: # END define_prob
 
 A dictionary called ``ingredient_vars`` is created which contains
 the LP variables, with their defined lower bound of zero. The reference
 keys to the dictionary are the Ingredient names, and the data is
 ``Ingr_IngredientName``. (e.g. MUTTON: Ingr_MUTTON)
 
 .. literalinclude:: ../../../examples/WhiskasModel2.py
-    :lines: 66-67
+    :start-after: # BEGIN ingredient_vars
+    :end-before: # END ingredient_vars
 
 Since ``costs`` and ``ingredient_vars`` are now dictionaries with the
 reference keys as the Ingredient names, the data can be simply extracted
@@ -325,12 +340,14 @@ elements of the resulting list. Thus the objective function is simply
 entered and assigned a name:
 
 .. literalinclude:: ../../../examples/WhiskasModel2.py
-    :lines: 69-73
+    :start-after: # BEGIN obj_function
+    :end-before: # END obj_function
 
 Further list comprehensions are used to define the other 5 constraints, which are also each given names describing them.
 
 .. literalinclude:: ../../../examples/WhiskasModel2.py
-    :lines: 75-92
+    :start-after: # BEGIN constraints
+    :end-before: # END constraints
 
 Following this, the :meth:`~pulp.LpProblem.writeLP` line etc follow exactly the same as
 in the simplified example.

doc/source/CaseStudies/a_set_partitioning_problem.rst

@@ -25,29 +25,35 @@ First we use :func:`~pulp.allcombinations` to generate a list of all
 possible table seatings.
 
 .. literalinclude:: ../../../examples/wedding.py
-    :lines: 22-23
+    :start-after: # BEGIN possible_tables
+    :end-before: # END possible_tables
 
 Then we create a binary variable that will be 1 if the table will be in the solution, or zero otherwise.
 
 .. literalinclude:: ../../../examples/wedding.py
-    :lines: 25-28
+    :start-after: # BEGIN define_x
+    :end-before: # END define_x
 
 We create the :class:`~pulp.LpProblem` and then make the objective function. Note that
 happiness function used in this script would be difficult to model in any other way.
 
 .. literalinclude:: ../../../examples/wedding.py
-    :lines: 30-32
+    :start-after: # BEGIN class_and_obj_fn
+    :end-before: # END class_and_obj_fn
+
 
 We specify the total number of tables allowed in the solution.
 
 .. literalinclude:: ../../../examples/wedding.py
-    :lines: 34-38
+    :start-after: # BEGIN total_table_constraint
+    :end-before: # END total_table_constraint
 
 This set of constraints defines the set partitioning problem by guaranteeing that a guest is allocated to
 exactly one table.
 
 .. literalinclude:: ../../../examples/wedding.py
-    :lines: 40-45
+    :start-after: # BEGIN exactly_one_table_constraint
+    :end-before: # END exactly_one_table_constraint
 
 The full file can be found here :download:`wedding.py <../../../examples/wedding.py>`
 

examples/WhiskasModel1.py

@@ -1,41 +1,64 @@
+# BEGIN file_docstring
 """
 The Simplified Whiskas Model Python Formulation for the PuLP Modeller
 
 Authors: Antony Phillips, Dr Stuart Mitchell  2007
 """
+# END file_docstring
 
+# BEGIN import_pulp
 # Import PuLP modeler functions
 from pulp import *
 
+# END import_pulp
+
+# BEGIN define_prob
 # Create the 'prob' variable to contain the problem data
 prob = LpProblem("The Whiskas Problem", LpMinimize)
+# END define_prob
 
+# BEGIN chicken_beef_vars
 # The 2 variables Beef and Chicken are created with a lower limit of zero
 x1 = LpVariable("ChickenPercent", 0, None, LpInteger)
 x2 = LpVariable("BeefPercent", 0)
+# END chicken_beef_vars
 
+# BEGIN obj_func
 # The objective function is added to 'prob' first
 prob += 0.013 * x1 + 0.008 * x2, "Total Cost of Ingredients per can"
+# END obj_func
 
+# BEGIN constraints
 # The five constraints are entered
 prob += x1 + x2 == 100, "PercentagesSum"
 prob += 0.100 * x1 + 0.200 * x2 >= 8.0, "ProteinRequirement"
 prob += 0.080 * x1 + 0.100 * x2 >= 6.0, "FatRequirement"
 prob += 0.001 * x1 + 0.005 * x2 <= 2.0, "FibreRequirement"
 prob += 0.002 * x1 + 0.005 * x2 <= 0.4, "SaltRequirement"
+# END constraints
 
+# BEGIN lp_file
 # The problem data is written to an .lp file
 prob.writeLP("WhiskasModel.lp")
+# END lp_file
 
+# BEGIN prob_solve
 # The problem is solved using PuLP's choice of Solver
 prob.solve()
+# END prob_solve
 
+# BEGIN print_status
 # The status of the solution is printed to the screen
 print("Status:", LpStatus[prob.status])
+# END print_status
 
+# BEGIN print_var_value
 # Each of the variables is printed with it's resolved optimum value
 for v in prob.variables():
     print(v.name, "=", v.varValue)
+# END print_var_value
 
+# BEGIN print_obj
 # The optimised objective function value is printed to the screen
 print("Total Cost of Ingredients per can = ", value(prob.objective))
+# END print_obj

examples/WhiskasModel2.py

@@ -1,3 +1,4 @@
+# BEGIN docstring_imports
 """
 The Full Whiskas Model Python Formulation for the PuLP Modeller
 
@@ -7,6 +8,9 @@
 # Import PuLP modeler functions
 from pulp import *
 
+# END docstring_imports
+
+# BEGIN problem_data
 # Creates a list of the Ingredients
 Ingredients = ["CHICKEN", "BEEF", "MUTTON", "RICE", "WHEAT", "GEL"]
 
@@ -59,19 +63,27 @@
     "WHEAT": 0.008,
     "GEL": 0.000,
 }
+# END problem_data
 
+# BEGIN define_prob
 # Create the 'prob' variable to contain the problem data
 prob = LpProblem("The Whiskas Problem", LpMinimize)
+# END define_prob
 
+# BEGIN ingredient_vars
 # A dictionary called 'ingredient_vars' is created to contain the referenced Variables
 ingredient_vars = LpVariable.dicts("Ingr", Ingredients, 0)
+# END ingredient_vars
 
+# BEGIN obj_function
 # The objective function is added to 'prob' first
 prob += (
     lpSum([costs[i] * ingredient_vars[i] for i in Ingredients]),
     "Total Cost of Ingredients per can",
 )
+# END obj_function
 
+# BEGIN constraints
 # The five constraints are added to 'prob'
 prob += lpSum([ingredient_vars[i] for i in Ingredients]) == 100, "PercentagesSum"
 prob += (
@@ -90,6 +102,7 @@
     lpSum([saltPercent[i] * ingredient_vars[i] for i in Ingredients]) <= 0.4,
     "SaltRequirement",
 )
+# END constraints
 
 # The problem data is written to an .lp file
 prob.writeLP("WhiskasModel2.lp")

examples/wedding.py

@@ -25,30 +25,40 @@ def happiness(
     return abs(ord(table[0]) - ord(table[-1]))
 
 
+# BEGIN possible_tables
 # create list of all possible tables
 possible_tables = [tuple(c) for c in pulp.allcombinations(guests, max_table_size)]
+# END possible_tables
 
+# BEGIN define_x
 # create a binary variable to state that a table setting is used
 x = pulp.LpVariable.dicts(
     "table", possible_tables, lowBound=0, upBound=1, cat=pulp.LpInteger
 )
+# END define_x
 
+# BEGIN class_and_obj_fn
 seating_model = pulp.LpProblem("Wedding Seating Model", pulp.LpMinimize)
 
 seating_model += pulp.lpSum([happiness(table) * x[table] for table in possible_tables])
+# END class_and_obj_fn
 
+# BEGIN total_table_constraint
 # specify the maximum number of tables
 seating_model += (
     pulp.lpSum([x[table] for table in possible_tables]) <= max_tables,
     "Maximum_number_of_tables",
 )
+# END total_table_constraint
 
+# BEGIN exactly_one_table_constraint
 # A guest must seated at one and only one table
 for guest in guests:
     seating_model += (
         pulp.lpSum([x[table] for table in possible_tables if guest in table]) == 1,
         f"Must_seat_{guest}",
     )
+# END exactly_one_table_constraint
 
 seating_model.solve()