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

mtwichan · 2020-07-19T21:29:27Z

Issue: #1280 : make sure all code in docs is in a running example (#303)

Replaced all stray python/.txt code with their own separate files. See: mtwichan@7560094#diff-570a5dc3719d98db8c8df4e9a3f5b63aL15-R15
Fixed a couple print statements that were missing their brackets (python2 artifacts) Ex: mtwichan@7560094#diff-741b3f2f01574abb85dd461cb2bba89cL19
Very minor spelling/grammar fixes.
Bug Fix: mtwichan@7560094#diff-52397748fa667e06aba5e880d7a597e6L90-R70

Status:

Currently, I am naively running all python files in the examples folders and tackling files containing errors.

CC: @bqpd

…path

acdl-jenkins · 2020-07-19T21:29:29Z

Can one of the admins verify this patch?

bqpd · 2020-07-19T23:19:26Z

add to whitelist

bqpd · 2020-07-20T00:54:30Z

this is fabulous! looks like the linting of examples is throwing a fit, while the unit tests are failing because not all files in the examples directory now run individually. Will do a full code review soon!

bqpd · 2020-07-20T01:50:39Z

docs/source/modelbuilding.rst

@@ -5,22 +5,9 @@ Checking for result changes
 ===========================
 Tracking the effects of changes to complex models can get out of hand;
 we recommend saving solutions with ``sol.save()``, then checking that new solutions are almost equivalent
-with ``sol1.almost_equal(sol2)`` and/or ``print sol1.diff(sol2)``, as shown below.
+with ``sol1.almost_equal(sol2)`` and/or ``print(sol1.diff(sol2))``, as shown below.


oops good catch

bqpd

didn't get through all of them, but here's partial notes

bqpd · 2020-07-20T01:54:19Z

docs/source/examples/checking_result_changes.py

@@ -0,0 +1,12 @@
+import pickle
+...  # build the model
+sol = m.solve()


hmm, should probably create a dummy model here

Added a dummy model here: 33588b9

I noticed when running last_verified_sol = pickle.load(open("last_verified.sol")) here: https://github.com/convexengineering/gpkit/pull/1508/files#diff-79562c84e117012e71221b6d88dd595bR23

I was getting this error:

Traceback (most recent call last): File "checking_result_changes.py", line 23, in <module> last_verified_sol = pickle.load(open("last_verified.sol")) File "/usr/lib/python3.6/codecs.py", line 321, in decode (result, consumed) = self._buffer_decode(data, self.errors, final) UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 330: invalid start byte

so I changed the code to: last_verified_sol = pickle.load(open("last_verified.sol", mode="rb")) and it worked successfully.

Not sure if this is a bug or not.

bqpd · 2020-07-20T01:54:37Z

docs/source/examples/creating_monomials.py

@@ -0,0 +1,6 @@
+# create a Monomial term xy^2/z
+x = Variable("x")


needs to import from gpkit

bqpd · 2020-07-20T01:54:45Z

docs/source/examples/creating_posynomials.py

@@ -0,0 +1,5 @@
+# create a Posynomial expression x + xy^2
+x = Variable("x")


needs to import from gpkit

bqpd · 2020-07-20T01:54:55Z

docs/source/examples/declaring_constraints.py

@@ -0,0 +1,8 @@
+# consider a block with dimensions x, y, z less than 1
+# constrain surface area less than 1.0 m^2
+x = Variable("x", "m")


needs to import from gpkit

bqpd · 2020-07-20T01:55:13Z

docs/source/examples/equivalent_variables.py

@@ -0,0 +1 @@
+Sankey(M).sorted_by('constraints', 11)


alas this one probably can't be a code snippet and should be left as inline rst code :(

Sounds good. For code snippets like this that cannot be run, I will leave them inline.

bqpd · 2020-07-20T01:58:32Z

docs/source/examples/getting_started.py

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


this should be part of a larger file. this particular line can be excerpted as part of the literalquote syntax

What is the literalquote syntax? I searched it up in Sphinx but had no luck. Alternatively, how do you feel about keeping trivial lines of code like this one inline?

bqpd · 2020-07-20T01:59:09Z

docs/source/examples/loose_constraintsets.py

@@ -0,0 +1,9 @@
+from gpkit import Variable, Model
+from gpkit.constraints.tight import Loose


should be from gpkit.constraints.loose, lol. This was an unknown bug in the documentation!

bqpd · 2020-07-20T01:59:27Z

docs/source/examples/models.py

@@ -0,0 +1 @@
+Sankey(M).diagram(left=60, right=90, width=1050)


as with other Sankey probably can't be run as example code

bqpd · 2020-07-20T01:59:35Z

docs/source/examples/printing_results_1.py

@@ -0,0 +1 @@
+print (sol.table())


should be part of a larger file

I made this inline.

bqpd · 2020-07-20T01:59:47Z

docs/source/examples/printing_results_2.py

@@ -0,0 +1,3 @@
+print ("The optimal value is %s." % sol["cost"])


should be part of a larger file

I made this inline.

…s.py

mtwichan · 2020-07-20T06:21:21Z

docs/source/examples/substituting_multiple_values.py

+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]))


This line is throwing this error:

Traceback (most recent call last): File "substituting_multiple_values.py", line 9, in <module> sub_two = p.sub({x: 1, y: 2, "z": [1, 2]}).any() == z.sub(z, [2, 4]).any() File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/array.py", line 182, in sub return self.vectorize(lambda nom: nom.sub(subs, require_positive)) File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/array.py", line 178, in vectorize return vec_recurse(self, function, *args, **kwargs) File "/home/matthew/.local/lib/python3.6/site-packages/numpy/lib/function_base.py", line 1972, in __call__ return self._vectorize_call(func=func, args=vargs) File "/home/matthew/.local/lib/python3.6/site-packages/numpy/lib/function_base.py", line 2042, in _vectorize_call ufunc, otypes = self._get_ufunc_and_otypes(func=func, args=args) File "/home/matthew/.local/lib/python3.6/site-packages/numpy/lib/function_base.py", line 2002, in _get_ufunc_and_otypes outputs = func(*inputs) File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/array.py", line 24, in vec_recurse return function(element, *args, **kwargs) File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/array.py", line 182, in <lambda> return self.vectorize(lambda nom: nom.sub(subs, require_positive)) File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/variables.py", line 83, in sub return Monomial.sub(self, *args, **kwargs) File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/math.py", line 171, in sub return Signomial(self.hmap.sub(substitutions, self.varkeys), File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/map.py", line 104, in sub if parsedsubs or not substitutions: ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

Haven't quite been able to fix it.

mtwichan · 2020-07-20T07:23:28Z

docs/source/examples/substituting_nonnumeric_values.py

+from gpkit.small_scripts import mag
+
+x = Variable("x", "m")
+xvk = x.varkeys.values()[0]


Line 6 throws:

Exception has occurred: TypeError 'dict_values' object does not support indexing File "/home/matthew/Desktop/the_gpkit/docs/source/examples/substituting_nonnumeric_values.py", line 6, in <module> xvk = x.varkeys.values()[0]

which may be because of a Python 2 artifact, where the original function returned a list, and now in Python3 it returns a view. One solution is to wrap list(x.varkets.values()) see: Link . If I do list(x.varkeys)[0] I get the right value.

Line 16 than throws:

Exception has occurred: TypeError string indices must be integers File "/home/matthew/Desktop/the_gpkit/docs/source/examples/substituting_nonnumeric_values.py", line 16, in <module> assert abs(expected - mag(x.sub(x_, y_).c)) < 1e-6

Since, x is gpkit.Variable(x [m]), I think x.sub(x_, y_) is invalid because x contains a single variable. If I run the code without y_ it runs fine, until I pass in a string "x" into x.sub(x_) which throws:

x.sub('x') ValueError: could not convert string to float: 'x'

If I comment out the assert, and add list(x.varkeys)[0] everything runs fine and line 20 throws an error as it should. I think I may need your insight.

mtwichan · 2020-07-20T07:36:38Z

docs/source/examples/substitutions.py

+from gpkit import Variable
+x = Variable("x")
+p = x**2
+assert p.sub(x, 3) == 9


Traceback (most recent call last): File "substitutions.py", line 5, in <module> assert p.sub(x, 3) == 9 File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/math.py", line 171, in sub return Signomial(self.hmap.sub(substitutions, self.varkeys), File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/map.py", line 107, in sub fixed, _, _ = parse_subs(varkeys, substitutions) File "/home/matthew/.local/lib/python3.6/site-packages/gpkit/nomials/substitution.py", line 23, in parse_subs for var in substitutions: TypeError: 'Variable' object is not iterable

An easy fix is:

p.sub({x:3}).value == 9

The subs are always dicts.

oops yup it looks like a lot of these examples are from when I had a little "convenience" syntax...that nobody but me used...so I removed it.

1ozturkbe · 2020-07-20T20:31:21Z

docs/source/examples/substitutions.py

+x = Variable("x")
+p = x**2
+assert p.sub(x, 3) == 9
+assert p.sub(x.varkeys["x"], 3) == 9


p.sub({x.key :3}) I think is intended here.

1ozturkbe · 2020-07-20T20:36:29Z

This all looks great! Super amped to have the documentation up to date and tested!

mtwichan · 2020-07-24T01:45:30Z

Transfer PR to: #1509

mtwichan added 6 commits July 19, 2020 12:22

Add new .py and .txt .. literalinclude files

ba46ab0

Replace floating .py and .txt doc text with .. literinclude file rel …

7560094

…path

Format relaxation.py for readability

3400603

Fix Python print syntax in Model Building docs section

05cccb5

Update stray sin(x) string in signomial programming docs

f9ae65d

Text format requirements in visint docs

0ca98a7

bqpd reviewed Jul 20, 2020

View reviewed changes

bqpd requested changes Jul 20, 2020

View reviewed changes

mtwichan added 3 commits July 19, 2020 21:00

Add dummy model to check_result_changes.py

33588b9

Fixed UTF-8 encoding error from pickle load in checking_result_change…

a3f25b9

…s.py

Refactor check_result_changes.py

fbaa470

mtwichan commented Jul 20, 2020

View reviewed changes

mtwichan added 2 commits July 20, 2020 00:42

Requested PR fixes

e5909e9

Remove potientially unecessary assert statements?

fc12f08

1ozturkbe reviewed Jul 20, 2020

View reviewed changes

bqpd mentioned this pull request Jul 21, 2020

Documentation bug fixes and Sphinx refactor #1509

Merged

mtwichan closed this Jul 24, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

mtwichan commented Jul 19, 2020 •

edited

Loading

acdl-jenkins commented Jul 19, 2020

bqpd commented Jul 19, 2020

bqpd commented Jul 20, 2020

bqpd Jul 20, 2020

bqpd left a comment

bqpd Jul 20, 2020

mtwichan Jul 20, 2020 •

edited

Loading

bqpd Jul 20, 2020

bqpd Jul 20, 2020

bqpd Jul 20, 2020

bqpd Jul 20, 2020

mtwichan Jul 20, 2020

bqpd Jul 20, 2020

mtwichan Jul 20, 2020 •

edited

Loading

bqpd Jul 20, 2020

bqpd Jul 20, 2020

bqpd Jul 20, 2020

mtwichan Jul 20, 2020

bqpd Jul 20, 2020

mtwichan Jul 20, 2020

mtwichan Jul 20, 2020

mtwichan Jul 20, 2020 •

edited

Loading

mtwichan Jul 20, 2020

1ozturkbe Jul 20, 2020 •

edited

Loading

bqpd Jul 21, 2020

1ozturkbe Jul 20, 2020 •

edited

Loading

1ozturkbe commented Jul 20, 2020

mtwichan commented Jul 24, 2020

		@@ -0,0 +1,6 @@
		# create a Monomial term xy^2/z
		x = Variable("x")

		@@ -0,0 +1,5 @@
		# create a Posynomial expression x + xy^2
		x = Variable("x")

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

		@@ -0,0 +1,9 @@
		from gpkit import Variable, Model
		from gpkit.constraints.tight import Loose

		@@ -0,0 +1 @@
		Sankey(M).diagram(left=60, right=90, width=1050)

		@@ -0,0 +1,3 @@
		print ("The optimal value is %s." % sol["cost"])

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

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

Conversation

mtwichan commented Jul 19, 2020 • edited Loading

acdl-jenkins commented Jul 19, 2020

bqpd commented Jul 19, 2020

bqpd commented Jul 20, 2020

Choose a reason for hiding this comment

bqpd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtwichan Jul 20, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtwichan Jul 20, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtwichan Jul 20, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1ozturkbe Jul 20, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

1ozturkbe Jul 20, 2020 • edited Loading

Choose a reason for hiding this comment

1ozturkbe commented Jul 20, 2020

mtwichan commented Jul 24, 2020

mtwichan commented Jul 19, 2020 •

edited

Loading

mtwichan Jul 20, 2020 •

edited

Loading

mtwichan Jul 20, 2020 •

edited

Loading

mtwichan Jul 20, 2020 •

edited

Loading

1ozturkbe Jul 20, 2020 •

edited

Loading

1ozturkbe Jul 20, 2020 •

edited

Loading