Visualization and Interaction

Sensitivity Diagrams

Requirements

  • Jupyter Notebook
  • ipysankeywidget
    • Note that you’ll need to activate these widgets on Jupyter by runnning
      • jupyter nbextension enable --py --sys-prefix widgetsnbextension
      • jupyter nbextension enable --py --sys-prefix ipysankeywidget

Example

Code in this section uses the CE solar model

from solar.solar import *
Vehicle = Aircraft(Npod=3, sp=True)
M = Mission(Vehicle, latitude=[20])
M.cost = M[M.aircraft.Wtotal]
sol = M.localsolve("mosek_cli")

from gpkit.interactive.sankey import Sankey

Once the code above has been run in a Jupyter notebook, the code below will create interactive hierarchies of your model’s sensitivities, like so:

_images/Mission.gif

Explanation

Sankey diagrams can be used to visualize sensitivity structure in a model. A blue flow from a constraint to its parent indicates that the sensitivity of the chosen variable (or of making the constraint easier, if no variable is given) is negative; that is, the objective of the overall model would improve if that variable’s value were increased in that constraint alone. Red indicates a positive sensitivity: the objective and the the constraint ‘want’ that variable’s value decreased. Gray flows indicate a sensitivity whose absolute value is below 1e-2, i.e. a constraint that is inactive for that variable. Where equal red and blue flows meet, they cancel each other out to gray.

Usage

Variables

In a Sankey diagram of a variable, the variable is on the right with its final sensitivity; to the left of it are all constraints that variable is in.

Free

Free variables have an overall sensitivity of 0, so this visualization shows how the various pressures on that variable in all its constraints cancel each other out; this can get quite complex, as in this diagram of the pressures on wingspan (right-click and open in a new tab to see it more clearly):

Sankey(sol, M, "SolarMission").diagram(M.aircraft.wing.planform.b, showconstraints=False)
_images/SolarMission_Aircraft.Wing.Planform.b.png

Gray lines in this diagram indicate constraints or constraint sets that the variable is in but which have no net sensitivity to it. Note that the showconstraints argument can be used to hide constraints if you wish to see more of the model hierarchy with the same number of links.

Variable in the cost function, have a “[cost function]” node on the diagram like so:

Sankey(sol, M, "SolarMission").diagram(M.aircraft.Wtotal)
_images/SolarMission_Wtotal.png
Fixed

Fixed variables can have a nonzero overall sensitivity. Sankey diagrams can how that sensitivity comes together:

Sankey(sol, M, "SolarMission").diagram(M.variables_byname("tmin")[0], left=100)
_images/SolarMission_CFRPFabric.tmin.png

Note that the left= syntax is used to reduce the left margin in this plot. Similar arguments exist for the right, top, and bottom margins: all arguments are in pixels.

The only difference between free and fixed variables from this perspective is their final sensitivity; for example Nprop, the number of propellers on the plane, has almost zero sensitivity, much like the wingspan b, above.

Sankey(sol, M, "SolarMission").diagram(M["Nprop"])
_images/SolarMission_Nprop.png

Models

When created without a variable, the diagram shows the sensitivity of every named model to becoming locally easier. Because derivatives are additive, these sensitivities are too: a model’s sensitivity is equal to the sum of its constraints’ sensitivities and the magnitude of its fixed-variable sensitivities. Gray lines in this diagram indicate models without any tight constraints or sensitive fixed variables.

Sankey(sol, M, "SolarMission").diagram(maxlinks=30, showconstraints=False, height=700)
_images/SolarMission.png

Note that in addition to the showconstraints syntax introduced above, this uses two additional arguments you may find useful when visualizing large models: height sets the height of the diagram in pixels (similarly for width), while maxlinks increases the maximum number of links (default 20), making a more detailed plot. Plot construction time goes approximately as the square of the number of links, so be careful when increasing maxlinks!

With some different arguments, the model looks like this:

Sankey(sol, M).diagram(minsenss=1, maxlinks=30, left=130, showconstraints=False)
_images/Mission.png

The only piece of unexplained syntax in this is minsenss. Perhaps unsurprisingly, this just limits the links shown to only those whose sensitivity exceeds that minimum; it’s quite useful for exploring a large model.

Plotting a 1D Sweep

Methods exist to facilitate creating, solving, and plotting the results of a single-variable sweep (see Sweeps for details). Example usage is as follows:

"Demonstrates manual and auto sweeping and plotting"
import matplotlib as mpl
mpl.use('Agg')
# comment out the lines above to show figures in a window
import numpy as np
from gpkit import Model, Variable, units
from gpkit.constraints.tight import Tight

x = Variable("x", "m", "Swept Variable")
y = Variable("y", "m^2", "Cost")
m = Model(y, [
    y >= (x/2)**-0.5 * units.m**2.5 + 1*units.m**2,
    Tight([y >= (x/2)**2])
    ])

# arguments are: model, swept: values, posnomial for y-axis
sol = m.sweep({x: np.linspace(1, 3, 20)}, verbosity=0)
f, ax = sol.plot(y)
ax.set_title("Manually swept (20 points)")
f.show()
f.savefig("plot_sweep1d.png")
sol.save()

# arguments are: model, swept: (min, max, optional logtol), posnomial for y-axis
sol = m.autosweep({x: (1, 3)}, tol=0.001, verbosity=0)
f, ax = sol.plot(y)
ax.set_title("Autoswept (7 points)\nGuaranteed to be in blue region")
f.show()
f.savefig("plot_autosweep1d.png")

Which results in:

_images/plot_sweep1d.png
_images/plot_autosweep1d.png