General comments on notebooks

[moorepants]

general

• many notebooks need more exercises. a good rule of thumb might be 5 minutes talking, 10 minutes for exercises
• i think we should write out learning objectives and timing at the top of each notebook, ala software carpentry

  Intro to sympy

  • i think it hits the right bits that will be important later
  • would it be worth showing what init_printing does? My students have been confused about why things display in the notebook in different ways. Maybe show the string, pretty, and latex printing based on a single input?
  • I think it is worth having some simple exercises here, just to get their fingers used to typing symbols.
  • the opening paragraph could have a bit more about what sympy is, maybe pointing them to the website (or maybe this is done in the intro slides)
  • could be worth showing them what type() returns for these objects

    Code printers

  • is the llvm printer available to show?
  • it is unfortunate we don't really have a python printer
  • a simple exercise would be to list a bunch of mathematical expressions in the mardown cell and ask them to try printing them with different languages
  • there are other interesting things to show here to like piecewise printing, indexed types that will print to loops, printing matrices, assignment, and different printer options
  • custom functions

25 chemical kinetics intro

• Using the chemical names as variable names is a bit confusing. Any way we can just use simple varialbes like x, y, z instead of [NO], [Br2], etc? I assume this is normal in chemistry but I think it would be more understandable by non-chemists if more normal mathematical notation is used, i.e. dy/dt, etc.
• the intro paragrapsh are well written and give a good set up. make sure to use some key words like "nonlinear ordinary differential equations"
• can your write out the odes instead of using the intermediate r variables? at least in addition to the other form
• i'd use "function" instead of "callback"
• needs some explanation that about how sympy can be used to write the right hand side of the diffeqs before jumping into odeint
• not sure what you mean by "deserialize", this needs to be explained. maybe showing how chem odes are typically created and stored
• i don't understand this need " Ideally we would like to construct it programatically from some serialized data format describing the set of reactions". what use is sympy if you have this?
• lambdify needs an introducation and explanation. the name is confusing and then people need to know what the purpose is, i.e. to convert sympy expressions in python functions that evaluate the expressions numerically
• odeint needs a bit more explanation: this function numerically integrates systems of odes, it has these features, and does x, y, z behind the scenes
• what are learning objectives here? maybe:
  • students will understand how a chemical reaction balance maps to a set of ordinary differential equations
  • students will be able to create a function that numerically evaluates the rhs of the odes manually
  • students will be able to create a sympy expression that represents the rhs of the odes
  • students will be able to convert a symbolic expression to a numerical function using lambdify

32 chemical kinetics

• i like this notebook. good scope, simple example to frame it.
• here are the main learning objectives i'm seeing:
  • students will understand that chemical reactions are governed by non-linear ordinary differential equations
  • students will be able to serialize/deserialize an ODE (not sure this one is needed, see below)
  • students will be able to use lambdify to convert a matrix of expressions into a python function that can be used to numerically evaluate the expressions with floating point inputs
  • students will be able to numerically integrate a lambdified expression with scipy's odeint
  • students will be able to take derivaives of matrix objects and utlize the jacobian method to do so
  • students will understand why a Jacaobian is needed for numerical integration
  • students will experience the computational speed ups provided by analytical derivatives
• it isn't clear to me where serialization/deserialization fits into the learning objectives of the tutorial, can we abstract that away if it is necessary? i think it'd be more useful for the students to manually construct sympy expressions. if we are going to teach something like this seems like saving/loading from a repr'd string or using pickling is better.
• # %load ../scipy2017codegen/symbolic_constr.py should be hidden, not sure there is any reason for students to read this code, or is this an exercise? if so, see the previous point
• can't the students just write ydot manually?
• labmdify needs some explanation on the first use. the name is confusing and i don't think anyone will know what it is doing. it would be worth spend some time explaining what lambdify does with simple examples here, then you can let them try to use lambdify to convert the ODE rhs to a numerical function as an exercise. explain why it is called lambdify and show a simple lambda function.
• i'd also explain a bit more about what odeint is, showing the docstring and telling how it runs LSODA under the hood and what types of intergration algortihms there are. students may not even remember what it means to integrate an ode. explain why the jacobian might be evaluated and how odeint does this if you don't provide one. i see you have some of this after the graph, i'd move the discussion to before you run the computation
• first graph needs axis labels
• be sure to explain what a Jacobian of a vector is and why it is important here. i'm not sure everyone would know what it is important to know how fast the states change
• what's the purpose of plotting on log, log? maybe show a normal plot first and explain why log-log is useful
• i suggest making "adding a jacobian" into an exercise. have them read the doc string of odeint and tell them to follow the same pattern as the first lambdify

  numba/symengine

• i suggest we leave these out or have them as special extra topics, as they are outside the original scope of the proposal

  the harder way

• break into four 15 minute notebooks with approximately 5 minutes of teaching and 10 minutes of doing for each
• should we stop where I stopped or try compiling the C code? not sure how the compilation step will work cross platform unless they all have gcc installed somehow
• work on the exercises to give some template code and hints
• figure out how to use bjorn's exercise solution loading tool

  the easy hard way

• maybe "the easier hard way" or 'the easy "hard" way' gets the point across better
• what about a vectorized operation for the example cython intro code. this would essentially show them what ufuncify does behind the scenes. this would be a function more like:

int add(double first_array[10], double second_array[10], double result[10]){
    for (i = 0; i < n, i++) {
        result[i] = first_array[i] + second_array[i];
        }

or have this as an exercise, i.e. have them create their own vectorized function

• codegen and autowrap don't work with array inputs, would be nice if they did

• 
  ---------------------------------------------------------------------------
  FileNotFoundError                         Traceback (most recent call last)
  <ipython-input-1-016e1aa967c4> in <module>()
    1 from scipy2017codegen.chem import load_large_ode
  ----> 2 rhs_of_odes, states = load_large_ode()
    3 jac_of_odes = rhs_of_odes.jacobian(states)

~/miniconda3/envs/codegen17/lib/python3.6/site-packages/scipy2017codegen/chem.py in load_large_ode() 32 file_path = os.path.join(os.path.dirname(file), 'data', 33 'radiolysis_300_Gy_s.json') ---> 34 with open(file_path) as f: 35 ode_def_dict = json.load(f) 36 eqs, states = mk_exprs_symbs(ode_def_dict['reactions'],

FileNotFoundError: [Errno 2] No such file or directory: '/home/moorepants/miniconda3/envs/codegen17/lib/python3.6/site-packages/scipy2017codegen/data/radiolysis_300_Gy_s.json'

- show off the files that are generated so that people can see the translation,
  `!cat odes.c`
- maybe it is worth creating the cython pyx file and compiling the cython
  extension manually to show how that happen, then say "autowrap" does all this
  for you
- %time seems more appropriate than %timeit for the odeint calls since they
  take some time to run a lot of them

[asmeurer]

Heads up, my main focus right now is the release, so I may be slow in fixing the things for my notebooks.

is the llvm printer available to show?

The LLVM printer is a bit weird. It doesn't actually create a string. Rather, it creates an LLVM jit callable directly from llvmlite objects. The theanocode printer is similar actually.

it is unfortunate we don't really have a python printer

Agree. It wouldn't be hard to start doing a cleanup of lambdify moving the translations into the printers. Worth doing for the release?

a simple exercise would be to list a bunch of mathematical expressions in the mardown cell and ask them to try printing them with different languages

Good idea.

there are other interesting things to show here to like piecewise printing, indexed types that will print to loops, printing matrices, assignment, and different printer options

I'll add those. Also Piecewise is a good thing to show in the intro notebook.

custom functions

What do you mean here?

labmdify needs some explanation on the first use. the name is confusing and i don't think anyone will know what it is doing. it would be worth spend some time explaining what lambdify does with simple examples here, then you can let them try to use lambdify to convert the ODE rhs to a numerical function as an exercise. explain why it is called lambdify and show a simple lambda function.

Yes, I was just thinking this. It isn't even clear that lambdify is code generation. Honestly, I think it's worth explaining exactly how lambdify works. The better you understand exactly what it does, the better you can utilize it.

what about a vectorized operation for the example cython intro code. this would essentially show them what ufuncify does behind the scenes. this would be a function more like:

ufuncify is a bit more complicated than this (it specifically fits the ufunc API, which lets it get broadcasting).

i suggest we leave these out or have them as special extra topics, as they are outside the original scope of the proposal

100% agree on symengine, which is still early work anyway. But for numba, I think we should show that you can wrap lambdify in numba.jit to make it faster. It's literally just two extra cells, and it could just be a section at the bottom of an existing notebook. There's no need to have a whole separate notebook for it.

codegen and autowrap don't work with array inputs, would be nice if they did

Let's not use autowrap for anything ever. As far as I'm concerned, autowrap should be deprecated in favor of ufuncify. The only reason you might ever want to use it is if you know you never care about vectorization, you only care about Python's float (no numpy data types), and want to get rid of a little bit of Python overhead. Neither of those conditions are really worth it in my view, and they definitely don't make it worth showing in the tutorial.