Manipulate Secrets Revealed

Everything you never knew you didn't know about Manipulate

Lou D’Andria

Wolfram Research, Inc.

Manipulate is one of the most used functions in Mathematica 6, and is the basis for such ambitious projects as the Demonstrations site and Mathematica Player. But just how well do you know the Manipulate function? In this talk, we will examine some of its lesser known features, ranging from those that are fully documented to those that are not documented at all. The goal of this talk is to empower you to become a Manipulate expert.

The basics

This talk will not focus on the basics:

Manipulate[x,{x,0,1}]

Manipulate[x,{x,{True,False}}]

Manipulate[x,{{x,1},0,1}]

Manipulate[x,{{x,1,"variable"},0,1}]

We'll assume you have used Manipulate, possibly extensively, and will focus on features which are less widely known.

Refresher

If you'd like study the basics of Manipulate, please see the two very fine Manipulate tutorials, as well as my introductory talk from last year's tech conference. Or come talk to me.

• Introduction to Manipulate

• Advanced Manipulate Functionality

• http://library.wolfram.com/infocenter/Conferences/6526/

Biggest surprise

Manipulate is written entirely in the Mathematica language. The primitives from which it is built are accessible to all developers, and are reasonably fully documented.

Building Manipulate

{Slider[Dynamic[x]], Dynamic[x]}

DynamicModule[{x}, Panel[Column[{Slider[Dynamic[x]], Dynamic[x]}]]]

Note

Manipulate does in fact automatically wrap the first argument in Dynamic, and automatically uses a DynamicModule to localize it's variables. It is not necessary for you to use Dynamic and DynamicModule literally in Manipulate, unless you are doing something out of the ordinary.

Syntax: Using options in variable specs

If the specification for a particular Manipulate variable causes it to use a certain control, then you can pass options to that control as options to the variable spec. Recall:

With[{opts = Style[opts,Blue]},Style[Grid[{
{Style["Variable Specification", Bold], Style["Default Control Type", Bold]},
{{var,xmin,∞, opts}, Animator},
{{var, xmin, xmax, opts}, Manipulator},
{{var,xmin,xmax,Δx, opts},Manipulator},
{{var,{xmin,ymin},{xmax,ymax}, opts}, Slider2D},
{{var,{xmin,ymin},{xmax,ymax},{Δx,Δy}, opts}, Slider2D},
{{var,{True, False}, opts}, Checkbox},
{{var, list, opts}, "PopupMenu or SetterBar"},
{{var, color, opts}, ColorSlider},
{{var, other, opts}, InputField}
}, ItemSize -> {"Columns" -> {{Scaled[0.5]}}},Background-> {"Rows" -> {{White, GrayLevel[0.9]}}}, Dividers->{"ColumnsIndexed"->{2 -> True},"RowsIndexed"->{2 -> True}}], FontFamily->"Helvetica", TextAlignment -> Center]]

Example

For example, this Manipulate uses a Manipulator control for x.

Manipulate[x,{x,0,1}]

ImageSize and ContinuousAction are Manipulator options, and so they can be included in x's variable spec.

Manipulate[x,{x,0,1, ImageSize -> Small, ContinuousAction -> False}]

Options can also be set to values which dynamically depend on other variables. Note that, like elsewhere in Manipulate, no explicit Dynamic is required.

Manipulate[{x,y},{x,0,1, Enabled:> y>0.5},{y,0,1}]

Syntax: Locator options

Actually, using a Locator style variable in Manipulate does not literally use the Locator function internally. Rather, it uses LocatorPane.

That means that the LocatorPane will intercept all mouse clicks on the content area.

That also mans that the options you can use in the variable specs are LocatorPane options, like Appearance and LocatorAutoCreate.

Manipulate[Graphics[Line[pts],PlotRange->1],{{pts,{{0,0}}},{-1,-1},{1,1},Locator,Appearance -> Style["●",24,Red], LocatorAutoCreate->True}]

Remember

You can have lots of single locator variables, or you can have one multi-locator variable, but you can' t mix and match.

OK:

Manipulate[..., {pt1,{-1,-1},{1,1}, Locator}, {pt2, {-1,-1},{1,1},Locator}]

OK:

Manipulate[..., {{pts,{{0,0},{.1,.2}}},{-1,-1},{1,1}, Locator}]

Not OK:

Manipulate[..., {{pts,{{0,0},{.1,.2}}},{-1,-1},{1,1}, Locator},{pt2, {-1,-1},{1,1},Locator}]

Syntax: {u, func} and {u, domain, func}

Manipulate lets you specify custom controls and thus controls with custom dynamic tracking functions by using {u, func} or {u, domain, func}

func is a pure function used to produce the display of the control.

Details

Two argument are passed to func by default:
• #1 refers to Dynamic[var] for the current variable var
• #2 refers to the domain specification for that variable, if one is given, wrapped in a list.

Manipulate[{x,y},{x,0,10,Slider[Dynamic[x,(x=#;y=(Sqrt[#]))&],#2]&},{y,0,(Sqrt[10])}]

Advanced tip (UNDOCUMENTED)

Variables specified using the {u, domain, func} syntax will even autorun properly, which is especially important if you are creating Mainpulates for the Demonstrations Project.

Syntax: Non-variables

You can intersperse a few different kinds of elements among variable specifications. These are intended to annotate existing controls, but they can also be used to insert other controls, or other arbitrary content.

Manipulate`Dump`$validOtherArgumentHeads

Simple examples

Manipulate[f[x],"the independent variable",{x,0,1}]

Manipulate[t,{t,1,10},Dynamic[Plot[Sin[x],{x,0,t}]]]

Layout examples

You can use this for arbitrary layout in the control area (which is one of the current limitations of the simpler Manipulate syntaxes).

Manipulate[{x,y},{x,{1,2,3},None},{y,{1,2,3},None},
Row[{
"x",SetterBar[Dynamic[x],{1,2,3}],Spacer[20],
"y",SetterBar[Dynamic[y],{1,2,3}] }]]

Experimental`ControlBlock (UNDOCUMENTED)

Anywhere a variable specification is accepted, you can also have a group of specifications in a collapsible group.

Experimental`ControlBlock[label, {var, spec}, {var, spec}, …]

Example

Manipulate[
  Plot[amp f[freq x],{x,0,6},PlotStyle->{color,Dashing[dashing],Thickness[thickness]},Axes->axes,Frame->frame,AxesOrigin->axesorigin,PlotLabel->f],
  {f, {Sin, Cos, Tan}},

  Experimental`ControlBlock["Function Variations",
  {freq, 1, 5},
  {amp, 1, 5}],

  Experimental`ControlBlock["Axes and Frames",
  {axes, {True, False}},
  {frame, {False, True}},
  {axesorigin, {0, 0}, {6, 1}}],

  Experimental`ControlBlock["Plot Style",
  {color, Blue},
  {dashing, 0, 0.1},
  {thickness, 0.001, 0.1}] ]

Options: SaveDefinitions

SaveDefinitions uses FullDefinition to extract the kernel definitions for all the symbols involved in your Manipulate, and stores them in the Initialization option.

Be careful when using this with package functions -- especially ReadProtected functions -- you may want to use a manually crafted Initialization option instead.

Example

h[x_]:=x^2

Manipulate[h[x],{x,0,1},SaveDefinitions -> True]

Options: avoiding $Aborted

Dynamic evaluations are only allowed to take a few seconds by default.

If evaluating the Initialization might take longer than that, set SynchronousInitialization -> False.

If evaluating the first argument might take longer than that during interactive manipulation, set SynchronousUpdating -> False. (You should also think about whether such an example belongs in Manipulate to begin with.

SynchronousInitialization

Manipulate[x,{x,0,1},Initialization:>Pause[7], SynchronousInitialization->False]

SynchronousUpdating

Manipulate[Pause[x];x,{x,0,7,ContinuousAction -> False}, SynchronousUpdating->False]

Options: AutorunSequencing

AutorunSequencing is one of the most overlooked options, since it controls one of the most obscure but important features of Manipulate: Autorun.

Manipulate[{x,y,z},{x,0,1},{y,Checkbox},{z,Range[5]},AutorunSequencing -> {1,3}]

Note

Autorun is the same animation which is used when you export a Manipulate to a movie format like Flash, or when you upload a Demonstration.

To keep swf file size down, you can exclude controls via AutorunSequencing.

If you're unhappy with the Autorun animation, you can use bookmarks instead (next slide please)

Options: Pre-defining bookmarks (UNDOCUMENTED)

Bookmarks are useful to set interactively, but they can also be specified in your input.

Manipulate[x,{x,0,1}]

Advanced tips

When two or more bookmarks are present, flash export and demonstrations animation will use them as animation key frames instead of Autorun.

The smoothness through which bookmarks are animated is specified by Manipulate's InterpolationOrder option.

InterpolationOrder -> 0 will effectively give a slideshow.

InterpolationOrder -> None will traverse a Manhattan-style route from one key frame to the next.

Advanced: Accessing animation data (UNDOCUMENTED)

What if you don't just want to see the Autorun animation, but you want to get your hands on the parametrization used.

Manipulate`AnimationData[ Manipulate[....] ]

Example

{vars,funcs,{min,max},other}=Manipulate[{x,y},{x,0,1},{y,0,1},AutorunSequencing -> All]//Manipulate`AnimationData

Block[{x},Plot[Evaluate[Through[funcs[x]]],{x,min,30}]]

Manipulate[Block[{x},Graphics[Line[Table[Through[funcs[x]],{x,min,t,0.01}]],PlotRange->{{0,1},{0,1}}]],{t,min,100}]

XXXX what is the name of this design?

Interesting

This type of approach can be used to build animations like the one shown here.

Options: LocalizeVariables

The LocalizeVariabled option determines whether the variables you declare in your Manipulate input are automatically added to a DynamicModule or not.

Turning this off might be useful if you want to build your own interface, using Manipulate as a control layout engine.

Example

Note the use of None as Manipualte's first argument, which suppresses the content area.

Manipulate[None,{x,0,1},{y,0,1},{z,0,1},LocalizeVariables->False,Paneled -> False,AppearanceElements -> False,ImageMargins -> 10]//CreatePalette

As with Manipulate`AnimationData, this enables you to leverage Manipulate technology to do other, related tasks.

Options: ControllerPath

The ControllerPath option will let you use the orientation sensor built into this computer, or any other HID system that might be excluded by default (like keyboards, trackpads, digitizers, …).

ControllerInformation[]

Example

Manipulate[Graphics[{Circle[{0,0},.2],Disk[{-x,-z},0.2],Opacity[0.4],Red,Disk[{-x,0}],Blue,Disk[{0,-z}]},PlotRange->3],{x,-2,2},{y,-2,2},{z,-2,2},ControllerPath->"Sudden Motion Sensor",ControllerMethod->"Absolute"]

Conclusion

Manipulate at first glance is rather analogous to Table, making it trivial to create useful interfaces in a few lines of code. But there is quite a bit of depth too. We've seen some of it today.

Questions?