News 〉Releases

Helipad 1.0 Runs in Jupyter Notebooks, and Much More

Helipad 1.0 has just launched with a plethora of improvements. Most importantly: you can now run Helipad models in Jupyter notebooks.

Jupyter Integration

Jupyter notebooks are interactive documents into which you can embed Python code to run in-browser. They’re popular for sharing scientific code because putting code in a document can be much more readable than putting comments in code.

Helipad can now run a full-featured instance inside a Jupyter notebook, with the same control panel experience and interactive plotting. Anything you can do with the Tkinter frontend, you can now do in the Jupyter frontend as well, with no* changes to your code. (*except that you’ll need to launch the plots explicitly with a heli.launchPlots() line at the end)

To try out the new Jupyter frontend,

  1. Download one of the sample notebooks
  2. Install Jupyter and Ipywidgets using pip install jupyterlab and pip install ipywidgets
  3. Launch the notebook from your terminal using jupyter notebook /path/to/notebook.ipynb

Because the code can be written and run in-browser, this should flatten the learning curve for writing a Helipad model and increase the shareability of model code.

New Decorators

The most significant API update is a set of new decorators to add hooks and reporters. Previously, it was necessary to define a function and then register it using model.addHook(). This entailed a lot of repetition.

Starting with Helipad 1.0, you can now register hooks using a decorator syntax. Just name your function according to the hook, and add @heli.hook at the top.

from helipad import Helipad
heli = Helipad()

@heli.hook
def modelStep(model, stage):
    pass

You can also use @heli.hook('modelStep') if you want to hook a function of any name to the modelStep hook, for example.

There are also decorators for reporters and button shocks. Though most reporters will still be generated with the data methods, if you’re defining your own reporter function, you can register it with the @heli.reporter decorator. Similarly, you can add buttons easily to the control panel with @heli.button.

API Stability

With the release of Helipad 1.0, every effort will be made to maintain backward-compatibility. Documented functions and properties will not change before six months or two 0.1 releases after the first release in which they are deprecated, whichever is longer. Undocumented functions and properties can change without notice.

Other Improvements

  • Plotting is now completely independent of the control panel. So you can launch the traditional way with model.launchCpanel(), jump straight into plotting with model.launchPlots(), or go completely GUI-less with model.start() (In the latter two cases you’ll have to set parameter values, including any data post-processing, in code).
  • Param objects now allow you to enable and disable the GUI element.
  • Model control is handled in the model object now, rather than the Cpanel object. If you need to control the model with code, use model.start(), model.stop(), and model.terminate().
  • New parameter types checkentry and checkgrid can be registered with model.addParameter().
  • Sliders can be registered with discrete and arbitrary values by passing a list of values to the opts argument of model.addParameter().
  • The CSV and stop-after boxes, along with the refresh rate slider and the plot list, are now proper parameters and can be accessed and set using model.param() under the names 'csv', 'stopafter', 'updateEvery', and 'plots', respectively.
  • The stopafter parameter can be set to a function rather than a number, in order to stop the model after an arbitrary condition is fulfilled. This can also be used in parameter sweeps.
  • Plots can be activated and deactivated from code with the new Plot.active() method.

The full list of API changes is below.

API Changes in Version 1.0

  • ⚠️ HelipadRemoved model.defaultPlots. Select plots programmatically with the selected argument of model.addPlot(), or after the fact with Plot.active().
    Moved Cpanel.graph and Cpanel.running to the model object.
    Model control (the start(), stop(), and terminate() methods) is handled here rather than in the Cpanel object.
    Removed the buttons parameter. The addButton() method now aliases Shocks.register().
  • ⚠️ CpanelChanged name to Cpanel from GUI.
    Moved the graph and running properties to the model object, and the lastUpdate property to the Graph object.
    Removed the headless parameter and property. To run the model headless, run model.launchPlots() without running model.launchCpanel().
    The stopafter, updateEvery, csv, and checks properties, which formerly stored Tkinter widgets relating to configuration, have been removed. Their values can be accessed through parameters of the same name with model.param() except checks, which can now be accessed with model.param('plots').
    Moved model control methods run(), pause(), terminate(), and preparePlots() to model.start(), model.stop(), model.terminate(), and model.launchPlots(), respectively.
    With the plot list being a parameter now, the CpanelAbovePlotlist hook has been removed.
  • ⚠️ launchCpanelRenamed from model.launchGUI, and removed the headless parameter. To run the model headless, run model.launchPlots() without calling this function.
  • ⚠️ launchPlotsMoved from Cpanel.preparePlots.
  • ⚠️ paramSweepRemoved the t parameter. Use model.param('stopafter') to set a time limit or a stop condition.
  • ⚠️ addButtonPass the model object to the button function, and move the display from the top to the shocks section.
  • ⚠️ terminateTakes the model object rather than the GUI object as the first argument.
  • ⚠️ modelStopTakes the model object rather than the GUI object as the first argument.
  • ⚠️ graphKeypressSecond argument is now the model object rather than the GUI object.
  • ⚠️ CpanelAboveItemParamsName changed from GUIAboveItemParams.
  • ⚠️ CpanelAboveParamsName changed from GUIAboveParams.
  • ⚠️ CpanelAboveShocksName changed from GUIAboveShocks.
  • ⚠️ CpanelBottomName changed from GUIBottom.
  • ⚠️ CpanelTopName changed from GUITop.
  • ⚠️ CpanelPostInitName changed from GUIPostInit.
  • ⚠️ CpanelPreLaunchName changed from GUIPreLaunch.
  • ⚠️ GUICloseNever executes in a Jupyter environment.
  • activeIntroduced.
  • PlotAdded the check and selected properties and the active() method.
  • logSliderWith the log slider now available for use in user-defined parameters, the Tkinter class now has a complement of methods: set, get, enable, disable, and disabled.
  • GraphAdded the lastUpdate property, formerly from the GUI object.
  • addHookAdded the prioritize argument.
  • addCheckNow returns the textCheck widget.
  • disabledMade the second parameter optional to allow the entire checkGrid to be enabled or disabled at once.
  • checkEntryAdded the command argument and callback parameters to enable callback functions.
  • addParameterAdded support for checkgrid, checkentry, and logslider parameters.
  • ParamAdded the defaultVal property, and split the parameter types into subclasses.
  • startIntroduced as part of the transfer of model control functions from GUI to the model object.
  • genDecoratorIntroduced.
  • @hookIntroduced.
  • @buttonIntroduced.
  • @reporterIntroduced.
  • enableIntroduced.
  • disableIntroduced.
  • disabledIntroduced.
  • launchCpanelInterrupts the 'Run All' sequence in a Jupyter environment.
  • plotsPreLaunchIntroduced.
  • plotsLaunchIntroduced.