Cleaning up the climlab namespace

[brian-rose]

Currently there are lots of inconsistencies in how various classes can be accessed.

For example, several radiation processes can be accessed like

mystate = climlab.column_state()
climab.radiation.RRTMG(state=mystate)
climlab.radiation.CAM3(state=mystate)

whereas the grey gas model requires

climlab.radiation.greygas.GreyGas(state=mystate)

but is instead in the notes usually accessed through a "convenience" wrapper

climlab.GreyRadiationModel()
climlab.RadiativeConvectiveModel()

(which, unlike the above methods, does not require a state dictionary as input and will initialize a new state when called with no arguments).

This is confusing. And there are several other, better kinds of "Radiative Convective Models" that can be built that do not have a convenience wrapper.

Similarly the "convenience" wrappers for 1D EBM models are currently

climlab.EBM()
climlab.EBM_annual()
climlab.EBM_seasonal()

These inconsistencies are really a legacy of old, poorly-thought-out API design going back to the beginning of the climlab project. I think that some API changes are needed to make all this more consistent.

Specifically, the GreyGas and GreyGasSW modules should be accessible like any other radiation module:

climlab.radiation.GreyGas
climlab.radiation.GreyGasSW

That one is easy and obvious and won't break anything.

Next, I think that all the "convenience" wrappers for ready-made models should be moved to the climlab.model namespace. So we would do

climlab.model.EnergyBalanceModel()
climlab.model.RadiativeConvectiveModel()

etc.

This would be a breaking change and shouldn't be done right away. We should have a clear deprecation cycle in the climlab releases.

Finally, I think that basically all Process objects should be callable without arguments. If no state is provided then a sensible default should be created upon initialization. So that

climlab.radiation.RRTMG()

would be equivalent to

mystate = climlab.surface_state()
climlab.radiation.RRTMG(state=mystate)

This would also be easy and wouldn't break anything.