Write v4 upgrade guide

[twiecki]

In anticipation of the big v4 release we should start to write a document walking people through the upgrade process. Specifically, this document should contain:

• Information about the Theano->Aesara switch
• Instructions and code on how to remove any former Theano installation and install Aesara
• A script to guide in the renaming of imports from Theano to Aesara for a code-base as well as NBs (I think @brandonwillard has some code for this already).
• [Please add more]

@MarcoGorelli is that something you can help with?

[MarcoGorelli]

Hey @twiecki - which part did you want help with?

[ricardoV94]

We should mention somewhere some of the benefits / future developments that are facilitated by this change, so that it doesn't look like we are just trying to reinvent the wheel (i.e., get people excited for the change and not simply bothered)

[OriolAbril]

This will be also great to help outreachy interns learn how to update all the other notebooks to take advantage of all the improvements.

Maybe we can start by updating the getting started notebook pymc-devs/pymc-examples#31 and from there start gathering and writing down all the changes that are needed to update the code.

[brandonwillard]

Here are the basics:

• theano is now aesara
• theano.gof is now aesara.graph and, more specifically, theano.gof.graph is aesara.graph.basic
• config options previously under .-delimited "sections", like theano.config.gcc, are now replaced with double-underscores (e.g. theano.config.gcc.cxxflags is now aesara.config.gcc__cxxflags)
• most internal classes and functions are no longer exported at the package level (e.g. theano.Variable no longer works; use aesara.graph.basic.Variable instead)

[twiecki]

@MarcoGorelli Ideally the conversion script, is that something you are familiar with?

[MarcoGorelli]

I think you could subclass ast.NodeVisitor and override some methods like visit_ImportFrom and visit_Name (example) - I'm starting a new job next week though and likely won't have capacity for this in the near future though, sorry

[brandonwillard]

I wrote a small template/example for Distribution-to-RandomVariable conversions here.

[ricardoV94]

New ones:

• Transforms that take arguments require a callable as input that takes the rv and returns the needed arguments. They are now Uppercase, indicating they are a class that needs be instantiated when defined interval(a, b) -> Interval(lambda rv: (a, b)).
• Lowerbound and Upperbound transforms were removed. The same functionality can still be obtained with Interval(lambda rv: (None, upperbound)) or Interval(lambda rv: (lowerbound, None))
• Missing data x is now split automatically into x_observed containing non-missing values (new), x_missing containing only missing values (old), and a deterministic x that combines the two (~newish).
• One can no longer do pm.Distribution.dist(x).logp(y)/.logcdf(y).

[Aut0R3V]

I'd like to work on this. Can anyone please guide me a little bit on where to locate the upgrade guide and some general comments on the guide development?

[ricardoV94]

We should also mention how size/ shape/ dims work and the new ellipsis functionality: #4696

[ricardoV94]

testval -> initval (still being discussed in #4729)