Documentation bug fixes and Sphinx refactor (replace stray Python/.txt with ..literalinclude)

docs/source/advancedcommands.rst

@@ -12,21 +12,7 @@ For example, air density, viscosity, and temperature are functions of altitude.
 These can be represented by a substitution or value that is a one-argument function
 accepting ``model.substitutions`` (for details, see `Substitutions`_ below).
 
-.. code-block:: python
-
-    # code from t_GPSubs.test_calcconst in tests/t_sub.py
-    x = Variable("x", "hours")
-    t_day = Variable("t_{day}", 12, "hours")
-    t_night = Variable("t_{night}", lambda c: 24 - c[t_day], "hours")
-    # note that t_night has a function as its value
-    m = Model(x, [x >= t_day, x >= t_night])
-    sol = m.solve(verbosity=0)
-    self.assertAlmostEqual(sol(t_night)/gpkit.ureg.hours, 12)
-    m.substitutions.update({t_day: ("sweep", [8, 12, 16])})
-    sol = m.solve(verbosity=0)
-    self.assertEqual(len(sol["cost"]), 3)
-    npt.assert_allclose(sol(t_day) + sol(t_night), 24)
-
+.. literalinclude:: examples/evaluated_fixed_variables.py
 
 These functions are automatically differentiated with the `ad <https://pypi.org/project/ad/>`_ package to provide more accurate sensitivities. In some cases may require using functions from the ``ad.admath`` instead of their python or numpy equivalents; the `ad documentation <https://pypi.org/project/ad/>`_ contains details on how to do this.
 
@@ -40,16 +26,7 @@ variable, but :math:`(1-\nu)` is a valid GP variable, then :math:`\nu` can be ca
 These evaluated free variables can be represented by a ``Variable`` with ``evalfn`` metadata.
 Note that this variable should not be used in constructing your model!
 
-.. code-block:: python
-
-    # code from t_constraints.test_evalfn in tests/t_sub.py
-    x = Variable("x")
-    x2 = Variable("x^2", evalfn=lambda v: v[x]**2)
-    m = Model(x, [x >= 2])
-    m.unique_varkeys = set([x2.key])
-    sol = m.solve(verbosity=0)
-    self.assertAlmostEqual(sol(x2), sol(x)**2)
-
+.. literalinclude:: examples/evaluated_free_variables.py
 
 For evaluated variables that can be used during a solution, see :ref:`sgp`.
 
@@ -94,18 +71,7 @@ tight (that is, the right side does not equal the left side) after solving. This
 is useful when you know that a constraint *should* be tight for a given model,
 but representing it as an equality would be non-convex.
 
-.. code-block:: python
-
-    from gpkit import Variable, Model
-    from gpkit.constraints.tight import Tight
-
-    Tight.reltol = 1e-2  # set the global tolerance of Tight
-    x = Variable('x')
-    x_min = Variable('x_{min}', 2)
-    m = Model(x, [Tight([x >= 1], reltol=1e-3),  # set the specific tolerance
-                  x >= x_min])
-    m.solve(verbosity=0)  # prints warning
-
+.. literalinclude:: examples/tight_constraintsets.py
 
 Loose ConstraintSets
 ====================
@@ -115,18 +81,7 @@ not loose (that is, their sensitivity is above some threshold after solving). Th
 is useful when you want a constraint to be inactive for a given model because
 it represents an important model assumption (such as a fit only valid over a particular interval).
 
-.. code-block:: python
-
-    from gpkit import Variable, Model
-    from gpkit.constraints.tight import Loose
-
-    Tight.reltol = 1e-4  # set the global tolerance of Tight
-    x = Variable('x')
-    x_min = Variable('x_{min}', 1)
-    m = Model(x, [Loose([x >= 2], senstol=1e-4),  # set the specific tolerance
-                  x >= x_min])
-    m.solve(verbosity=0)  # prints warning
-
+.. literalinclude:: examples/loose_constraintsets.py
 
 Substitutions
 =============
@@ -138,31 +93,14 @@ Substituting into Posynomials, NomialArrays, and GPs
 
 The examples below all use Posynomials and NomialArrays, but the syntax is identical for GPs (except when it comes to sweep variables).
 
-.. code-block:: python
-
-    # adapted from t_sub.py / t_NomialSubs / test_Basic
-    from gpkit import Variable
-    x = Variable("x")
-    p = x**2
-    assert p.sub(x, 3) == 9
-    assert p.sub(x.varkeys["x"], 3) == 9
-    assert p.sub("x", 3) == 9
+.. literalinclude:: examples/substitutions.py
 
 Here the variable ``x`` is being replaced with ``3`` in three ways: first by substituting for ``x`` directly, then by substituting for the ``VarKey("x")``, then by substituting the string "x". In all cases the substitution is understood as being with the VarKey: when a variable is passed in the VarKey is pulled out of it, and when a string is passed in it is used as an argument to the Posynomial's ``varkeys`` dictionary.
 
 Substituting multiple values
 ----------------------------
 
-.. code-block:: python
-
-    # adapted from t_sub.py / t_NomialSubs / test_Vector
-    from gpkit import Variable, VectorVariable
-    x = Variable("x")
-    y = Variable("y")
-    z = VectorVariable(2, "z")
-    p = x*y*z
-    assert all(p.sub({x: 1, "y": 2}) == 2*z)
-    assert all(p.sub({x: 1, y: 2, "z": [1, 2]}) == z.sub(z, [2, 4]))
+.. literalinclude:: examples/substituting_multiple_values.py
 
 To substitute in multiple variables, pass them in as a dictionary where the keys are what will be replaced and values are what it will be replaced with. Note that you can also substitute for VectorVariables by their name or by their NomialArray.
 
@@ -171,28 +109,7 @@ Substituting with nonnumeric values
 
 You can also substitute in sweep variables (see Sweeps_), strings, and monomials:
 
-.. code-block:: python
-
-    # adapted from t_sub.py / t_NomialSubs
-    from gpkit import Variable
-    from gpkit.small_scripts import mag
-
-    x = Variable("x", "m")
-    xvk = x.varkeys.values()[0]
-    descr_before = x.exp.keys()[0].descr
-    y = Variable("y", "km")
-    yvk = y.varkeys.values()[0]
-    for x_ in ["x", xvk, x]:
-        for y_ in ["y", yvk, y]:
-            if not isinstance(y_, str) and type(xvk.units) != str:
-                expected = 0.001
-            else:
-                expected = 1.0
-            assert abs(expected - mag(x.sub(x_, y_).c)) < 1e-6
-    if type(xvk.units) != str:
-        # this means units are enabled
-        z = Variable("z", "s")
-        # y.sub(y, z) will raise ValueError due to unit mismatch
+.. literalinclude:: examples/substituting_nonnumeric_values.py
 
 Note that units are preserved, and that the value can be either a string (in which case it just renames the variable), a varkey (in which case it changes its description, including the name) or a Monomial (in which case it substitutes for the variable with a new monomial).
 
@@ -219,16 +136,7 @@ Freeing Fixed Variables
 
 After creating a Model, it may be useful to "free" a fixed variable and resolve.  This can be done using the command ``del m.substitutions["x"]``, where ``m`` is a Model.  An example of how to do this is shown below.
 
-.. code-block:: python
-
-    from gpkit import Variable, Model
-    x = Variable("x")
-    y = Variable("y", 3)  # fix value to 3
-    m = Model(x, [x >= 1 + y, y >= 1])
-    _ = m.solve()  # optimal cost is 4; y appears in sol["constants"]
-
-    del m.substitutions["y"]
-    _ = m.solve()  # optimal cost is 2; y appears in Free Variables
+.. literalinclude:: examples/freeing_fixed_variables.py
 
 Note that ``del m.substitutions["y"]`` affects ``m`` but not ``y.key``.
 ``y.value`` will still be 3, and if ``y`` is used in a new model,

docs/source/examples.rst

@@ -34,7 +34,7 @@ Say we had a fixed mass of water we wanted to contain within a tank, but also wa
 
 .. literalinclude:: examples/water_tank.py
 
-The output is
+The output is:
 
 .. literalinclude:: examples/water_tank_output.txt
 
@@ -44,7 +44,7 @@ This example comes from Section 3 of `Geometric Programming for Aircraft Design
 
 .. literalinclude:: examples/simpleflight.py
 
-The output is
+The output is:
 
 .. literalinclude:: examples/simpleflight_output.txt
 
@@ -54,7 +54,7 @@ In this example we consider a beam subjected to a uniformly distributed transver
 
 .. literalinclude:: examples/beam.py
 
-The output is
+The output is:
 
 .. literalinclude:: examples/beam_output.txt
 

docs/source/examples/checking_result_changes.py

@@ -0,0 +1,29 @@
+import pickle
+from gpkit import Model, Variable
+
+# build model (dummy)
+# decision variable
+x = Variable("x")
+y = Variable("y")
+
+# objective and constraints
+objective = 0.23 + x/y # minimize x and y
+constraints = [x + y <= 5, x >= 1, y >= 2]
+
+# create model
+m = Model(objective, constraints)
+
+# solve the model
+sol = m.solve()
+
+# save the current state of the model
+sol.save("last_verified.sol")
+
+# uncomment the line below to verify a new model
+last_verified_sol = pickle.load(open("last_verified.sol", mode="rb"))
+if not sol.almost_equal(last_verified_sol, reltol=1e-3):
+    print(last_verified_sol.diff(sol))
+
+# Note you can replace the last three lines above with
+# print(sol.diff("last_verified.sol"))
+# if you don't mind doing the diff in that direction.

docs/source/examples/creating_monomials.py

@@ -0,0 +1,8 @@
+from gpkit import Variable
+
+# create a Monomial term xy^2/z
+x = Variable("x")
+y = Variable("y")
+z = Variable("z")
+m = x * y**2 / z
+print(type(m))  # gpkit.nomials.Monomial

docs/source/examples/creating_posynomials.py

@@ -0,0 +1,7 @@
+from gpkit import Variable
+
+# create a Posynomial expression x + xy^2
+x = Variable("x")
+y = Variable("y")
+p = x + x * y**2
+print(type(p))  # gpkit.nomials.Posynomial

docs/source/examples/declaring_constraints.py

@@ -0,0 +1,10 @@
+from gpkit import Variable
+
+# consider a block with dimensions x, y, z less than 1
+# constrain surface area less than 1.0 m^2
+x = Variable("x", "m")
+y = Variable("y", "m")
+z = Variable("z", "m")
+S = Variable("S", 1.0, "m^2")
+c = (2*x*y + 2*x*z + 2*y*z <= S)
+print(type(c))  # gpkit.nomials.PosynomialInequality

docs/source/examples/evaluated_fixed_variables.py

@@ -0,0 +1,15 @@
+import gpkit
+from gpkit import Variable, Model
+
+# code from t_GPSubs.test_calcconst in tests/t_sub.py
+x = Variable("x", "hours")
+t_day = Variable("t_{day}", 12, "hours")
+t_night = Variable("t_{night}", lambda c: 24 - c[t_day], "hours")
+
+# note that t_night has a function as its value
+m = Model(x, [x >= t_day, x >= t_night])
+sol = m.solve(verbosity=0)
+
+# call substitutions
+m.substitutions.update({t_day: ("sweep", [8, 12, 16])})
+sol = m.solve(verbosity=0)

docs/source/examples/evaluated_free_variables.py

@@ -0,0 +1,8 @@
+from gpkit import Variable, Model
+
+# code from t_constraints.test_evalfn in tests/t_sub.py
+x = Variable("x")
+x2 = Variable("x^2", evalfn=lambda v: v[x]**2)
+m = Model(x, [x >= 2])
+m.unique_varkeys = set([x2.key])
+sol = m.solve(verbosity=0)

docs/source/examples/fixed_variables_1.py

@@ -0,0 +1,5 @@
+from gpkit import Variable
+
+# Declare \rho equal to 1.225 kg/m^3.
+# NOTE: in python string literals, backslashes must be doubled
+rho = Variable("\\rho", 1.225, "kg/m^3", "Density of air at sea level")

docs/source/examples/fixed_variables_2.py

@@ -0,0 +1,4 @@
+from gpkit import Variable
+
+#Declare pi equal to 3.14
+pi = Variable("\\pi", 3.14)

docs/source/examples/formulating_a_model.py

@@ -0,0 +1,10 @@
+from gpkit import Variable, Model
+
+x = Variable("x")
+y = Variable("y")
+z = Variable("z")
+S = 200
+objective = 1/(x*y*z)
+constraints = [2*x*y + 2*x*z + 2*y*z <= S,
+                x >= 2*y]
+m = Model(objective, constraints)

docs/source/examples/free_variables.py

@@ -0,0 +1,10 @@
+from gpkit import Variable
+
+# Declare a variable, x
+x = Variable("x")
+
+# Declare a variable, y, with units of meters
+y = Variable("y", "m")
+
+# Declare a variable, z, with units of meters, and a description
+z = Variable("z", "m", "A variable called z with units of meters")

docs/source/examples/freeing_fixed_variables.py

@@ -0,0 +1,8 @@
+from gpkit import Variable, Model
+x = Variable("x")
+y = Variable("y", 3)  # fix value to 3
+m = Model(x, [x >= 1 + y, y >= 1])
+_ = m.solve()  # optimal cost is 4; y appears in sol["constants"]
+
+del m.substitutions["y"]
+_ = m.solve()  # optimal cost is 2; y appears in Free Variables

docs/source/examples/getting_started.py

@@ -0,0 +1 @@
+from gpkit import Variable, VectorVariable, Model

docs/source/examples/loose_constraintsets.py

@@ -0,0 +1,9 @@
+from gpkit import Variable, Model
+from gpkit.constraints.loose import Loose
+
+Loose.reltol = 1e-4  # set the global tolerance of Tight
+x = Variable('x')
+x_min = Variable('x_{min}', 1)
+m = Model(x, [Loose([x >= 2], senstol=1e-4),  # set the specific tolerance
+                x >= x_min])
+m.solve(verbosity=0)  # prints warning

docs/source/examples/relaxation.py

@@ -1,6 +1,7 @@
 "Relaxation examples"
 
 from gpkit import Variable, Model
+
 x = Variable("x")
 x_min = Variable("x_min", 2)
 x_max = Variable("x_max", 1)
@@ -13,7 +14,9 @@
 
 print("With constraints relaxed equally")
 print("================================")
+
 from gpkit.constraints.relax import ConstraintsRelaxedEqually
+
 allrelaxed = ConstraintsRelaxedEqually(m)
 mr1 = Model(allrelaxed.relaxvar, allrelaxed)
 print(mr1)
@@ -22,7 +25,9 @@
 
 print("With constraints relaxed individually")
 print("=====================================")
+
 from gpkit.constraints.relax import ConstraintsRelaxed
+
 constraintsrelaxed = ConstraintsRelaxed(m)
 mr2 = Model(constraintsrelaxed.relaxvars.prod() * m.cost**0.01,
             # add a bit of the original cost in
@@ -33,7 +38,9 @@
 
 print("With constants relaxed individually")
 print("===================================")
+
 from gpkit.constraints.relax import ConstantsRelaxed
+
 constantsrelaxed = ConstantsRelaxed(m)
 mr3 = Model(constantsrelaxed.relaxvars.prod() * m.cost**0.01,
             # add a bit of the original cost in

docs/source/examples/solving_the_model.py

@@ -0,0 +1 @@
+sol = m.solve(verbosity=0)

docs/source/examples/substituting_multiple_values.py

@@ -0,0 +1,8 @@
+# adapted from t_sub.py / t_NomialSubs / test_Vector
+from gpkit import Variable, VectorVariable
+x = Variable("x")
+y = Variable("y")
+z = VectorVariable(2, "z")
+p = x*y*z
+assert all(p.sub({x: 1, "y": 2}) == 2*z)
+assert all(p.sub({x: 1, y: 2, "z": [1, 2]}) == z.sub(z, [2, 4]))