News 〉Releases

Helipad 1.1 Adds Virtual Parameters, Improves Jupyter Flexibility, and More

Posted on by charwick

Helipad 1.1 is out today with a number of new possibilities and small quality-of-life improvements.

Virtual Parameters

The trio of add parameter functions – model.addParameter(), model.addGoodParam(), and model.addBreedParam(), can now accept setter and getter arguments to replace the parameter’s own internal handling.

One use of this might be to alias parameters. In this example, the user has an option of creating a square of a particular dimension or specifying an arbitrary height and width. In order to have 'x' and 'y' parameters available regardless of whether square==True, we can use the setter and getter arguments to alias the 'dimension' parameter.

if square:
	model.addParameter('dimension', 'Map Size', 'slider', dflt=x, opts={'low': 1, 'high': x, 'step': 1}, runtime=False)
	def dimget(name, model): return model.param('dimension')
	def dimset(val, name, model): model.param('dimension', val)
	model.addParameter('x', 'Map Width ', 'hidden', dflt=x, setter=dimset, getter=dimget)
	model.addParameter('y', 'Map Height', 'hidden', dflt=x, setter=dimset, getter=dimget)
else:
	model.addParameter('x', 'Map Width ', 'slider', dflt=x, opts={'low': 1, 'high': x, 'step': 1}, runtime=False)
	model.addParameter('y', 'Map Height', 'slider', dflt=y, opts={'low': 1, 'high': y, 'step': 1}, runtime=False)

Anything can go in the setter and getter functions, however, so you can set and get any model properties with the usual parameter types, no matter how complex. The agent population slider, for example, is now a virtual parameter that directly checks and modifies the agent population.

Improved Jupyter Flexibility

Helipad’s control panel is now a great deal more flexible in Jupyter notebooks. Two changes in particular bear mentioning.

First, the control panel can be drawn out of order with certain calls now. Where previously model.addPlot() and model.addParameter() would raise an error if the control panel had already been drawn, now the control panel will refresh automatically if a plot or a parameter is added after it’s drawn. Note that the behavior in Tkinter has not changed, and that these functions will still raise an error if called after the control panel has been drawn.

Connected to this, the Jupyter control panel can now be refreshed programmatically by calling Cpanel.__init__(model, redraw=True).

Second, the control panel can now be drawn multiple times in the same notebook, whereas before this would cause an error. Instead, when a new instance of the control panel is drawn, the old instance is now invalidated and control of the model transferred to the new cell.

These changes help accommodate the exploratory and nonlinear nature of writing a model in a Jupyter notebook.

Color API Improvements

First of all, the Colour dependency has been removed, and replaced with a bare-bones Color object for internal use. While this object will not typically be interacted with directly, it does come with a few user-facing improvements.

Most importantly, in functions that take a color – model.addGood(), model.addBreed(), and TimeSeriesPlot.addSeries(), the color argument is more flexible. Whereas previously it would only take a hex value, it can now take a hex value, a color name (see the Matplotlib documentation for the complete list of names), or an RGB tuple.

In order to support the use of color names, the use of hex values without the initial '#' is now deprecated. Existing code will still work, but will throw a warning. Per the deprecation policy, the ability to take prefix-less hex codes will be removed in Helipad 1.3.

Spatial Pre-Alpha

The methods and classes in the spatial sample model have been moved into core, along with a new function model.spatial(), which initializes a network of patches and adds properties and methods to all agents for location and movement. A new sample model of sheep and grass using the spatial capability is also included.

This is a preview and is not API-stable. There is no visualization capability yet, and no promise of backward-compatibility until the feature is finalized. Nevertheless, it should function as a solid foundation for spatial models.

Other Improvements

  • The endowment argument of model.addGood() can now take a two-item tuple, a low and a high value, to endow agents with a random amount of the good between these two values.
  • The automatically generated ‘agents_[primitive]‘ parameter, with the population of agents of each primitive, has been renamed to the clearer ‘num_[primitive]‘. A model which does not create any new primitives, for example, can now set and get the population using ‘num_agents‘. The use of the agents_ prefix is now deprecated and will be removed in Helipad 1.3.
  • Because the coefficients of a CES utility function become the exponents of a Cobb-Douglass utility function when the elasticity of substitution equals one, the exponents of the CobbDouglas object were previously accessed using the coeffs property inherited from the parent CES class. These can now be accessed more intuitively using the new CobbDouglas.exponents property, which aliases the coeffs property.

API Changes in Version 1.1

  • ⚠️ addThe endowment argument can take a tuple for a random endowment.
    The color argument can now take an RGB tuple or a color name string. Note that hex strings now take an initial '#'. The use of bare hex strings is deprecated and will be removed in a future version.
  • ⚠️ addBreedThe color argument can now take an RGB tuple or a color name string. Note that hex strings now take an initial '#'. The use of bare hex strings is deprecated and will be removed in a future version.
  • ColorIntroduced in lieu of the colour library.
  • initializeFunction signature changed to make it a parameter setter function rather than a GUI callback.
  • addAdded the setter and getter arguments to support virtual parameters.
  • spatialIntroduced.