Math Minion
Getting Started Tutorial

This short tutorial will introduce some basic concepts of Math Minion, but it is by no means a complete tour of Math Minion's features. Reviewing the in program documentation and the examples in the Getting Started session will provide a more comprehensive feel for Math Minion's capabilities.

There is also short tutorial on models, which is best read after completing this tutorial.

Note Math Minion is an evolving program and replacing screenshots is tedious, so there maybe some minor differences between the views in the most recent versions and the screenshots of this tutorial.

Math Minion runs on both Mac and iOS devices, but the concepts and interface are very similar and sloth dictates that I only produce a single tutorial, so let's start by looking at the differences.

Here is the Mac view of the "A_Simple_Calc" model from the Getting Started session:

Screenshot

while on an iPad it would appear as:

Screenshot

Both have a diagram of the current model on the left and an information view on the right. The "area" expression has been selected in the diagram, and so information about that tool has been pushed onto the right hand view.

While there are differences in the appearance of buttons and text, all of the controls have been arranged to be in similar positions and fulfill similar functions.

On an iPhone or iPod Touch, when the information view is presented, it slides over top of the diagram and takes up the entire display. So starting on the diagram:

Screenshot

When one taps on the "area" icon, you would see:

Screenshot

Tapping on the back button at the upper left would return you to the diagram. The only other significant difference is that the bottom tool bar that only appears on the information view on the Mac and iPad is reproduced on the iPhone diagram view as well.

For this tutorial I will use an iPad and trust that you Mac users can translate tap to click and turn switch on to check box etc. Where there are more significant differences, I will try and point them out.

To get started, launch Math Minion and tap on the Sessions button on the bottom tool bar.

Screenshot

The green arrows and highlights I have added to the screenshots will indicate the actions to take. In some cases where multiple actions are required, I will number them.

I will also show the text instructions for the actions in green text, as I did above.

After tapping the Sessions button, a view of your saved sessions will slide into the information view:

Screenshot

If you have just started using Math Minion, the only session shown will be Getting Started.

We want to start a new session, so tap the New button.

Screenshot

Not that on the Mac the menu will pop up from the New button, rather than taking over the whole information view.

There are a number of ways of creating a new session, but we just want an empty session,

so just tap on the row labeled Blank.

Screenshot

A name will be requested for the new session. I have just called it tutorial

1 - Enter a name in the input field.

2 - tap the button.

Screenshot

A new session has been created. On Macs a new window will be created, while on iOS devices, the view will switch from the previous session to the new one. Any changes to the previous session will be saved.

The diagram represents the base model of the session and is currently empty. The information view is for this model and shows now inputs or outputs - more about those later.

Tap on the diagram background.

Screenshot

A pop up menu will appear at the point where you tapped.

On iOS, tap the line labeled Add Tool to Model, but on the Mac, just move your cursor over it.

Screenshot

A menu will appear showing the various types of tools that can be added to the model.

Select Expression

Screenshot

An icon for the new expression tool will appear on the diagram where you originally tapped. The information view for the expression will also slide in overtop the model information view.

An expression is simply a holder for a single formula or equation. In this case, let's just define a constant.

In the field with the placeholder, Formula or Constant, enter:

2 m

and press the return key.

Screenshot

This defines a value of 2 metre, which Math Minion has identified as a Length.

The expression was auto named as x1. Let's give it a more descriptive name.

Replace the x1 in the top field with radius.

Screenshot

Now tap on the diagram background again and add another expression.

To return to the diagram on an iPhone, you will have to tap the back button at the upper left of the information view.

Rename it area and enter the formula:

{pi}*radius^2

Screenshot

This is of course the formula for the area of a circle. The term {pi} is a convenience function that returns the value of pi. More about that later.

As you can see the calculation has resulted in a value of 12.566 square metres and has identified it as an area.

On the diagram a line now connects the right side of the radius icon to the left side of the area icon. These connections show where all of the values used in a tool originate from.

Place your finger, or cursor, on the background of the diagram and drag it around. The entire diagram should move. Now try dragging one of the icons. Just it should move.

On an iOS or a Mac with a trackpad, try using a pinch gesture (two fingers on the background and move them together or apart) to zoom the diagram in and out.

On a Mac with a mouse, you can use the centre scroll function of the mouse or right click drag up and down to zoom.

Double tap on the diagram background to have it automatically scale and pan the diagram so everything is visible.

Tap on the radius icon to select it.

Arrange the diagram so it looks like the one below.

Screenshot

Tap on the background and add another expression, this time named circumference and enter first part of the formula:

2*radius*{pi}

but stop before entering {pi}.

Screenshot

When you are editing a formula on an iOS device, an extra row of keys appears above the keyboard. The left most keys are simply mathematical operators (on an iPad, swiping sideways on a key gives the side characters), but to the right of those are keys marked as follows:

  • <v> - presents a value browser for inserting tool and parameter names into the formula
  • "u" - presents a unit browser for inserting conversion units.
  • {f} - presents a function browser for inserting function calls.
  • Edit - presents a formula browser for multiline formulas
  • Clear - erases the current formula

On a Mac, buttons with similar functions appear in the name field when you are editing a formula.

Screenshot

On iOS, tap the {f} key and on the Mac click the Functions button.

Screenshot

On the resulting function browser, tap on the Trigonometric math functions line (1) and then on the {pi} line (3). Both of these have already been done in the screenshot above.

The browser lists all of Math Minion's functions by category. A function in Math Minion always starts with a curly brace {, followed by the function name and then a comma separated list of parameters and finally a closing curly brace }.

The pi function doesn't require any parameters, but you can see the form for the other trigonometric functions.

Tap the Insert button to return to the formula with the template inserted.

Screenshot

The formula for circumference, with the pi function added.

Tap the return key.

Screenshot

The circumference has been calculated as 12.566 m. If you are particularly attentive, or bored, you might remember that the area number was also 12.566, which seem strange until you realize that 2 squared from the area formula of course equals 2 * 2 from the circumference formula.

However in Math Minion these aren't really equal, since one has units of length squared and the other just length. Let's change the display units to US.

Tap the Units button on the bottom toolbar.

Screenshot

Tap on the line labelled US

Screenshot

The circumference is now displayed as 41.228 feet, while the area (tap on its icon to display it) is 135.263 feet squared. The formula for radius is still 2 m, but its value is displayed as 6.562 feet.

The change we made only affects the display of results, not the calculations themselves. Inputs must always have the unit included with them and internally all calculations are done in SI units.

You can also set an explicit display unit for individual expressions and a number of other Math Minion tools.

If you aren't already, switch to viewing the circumference information and then tap on the info button at the right of the unit line.

Screenshot

The unit browser slides into place and from here you can select the unit you want to display or even construct a compound unit (things like m/s^2) to use. In this case the expression knows the result is a length, so the section with those units has been opened and the default unit of ft has a check beside it.

Tap on the line labelled fathom. This will put "fathom" into the input field at the top. Tap the Apply button to use that value as the display unit.

Screenshot

The value for circumference is now displayed in fathoms. If you have a look at area or radius, you will see they are still displayed in feet. Also, the unit name is now displayed in blue text as an indication that a specific display unit has been selected.

Return to circumference a turn on the Output switch. Then tap the back button to return to the model information.

On an iPhone, the back button will return you to the diagram. Tap the Model button on the lower toolbar to see the model information.

Screenshot

The model information view will show values for any expression which has its Input or Output switches turned on.

Turn on the Output switch for the area expression and the Input switch for radius. Then return to the model information view.

Screenshot

With the appropriate inputs and outputs designated, the model information view provides a handy place to change input values and view the results.

Tapping on an input row will place the formula for that expression in the formula field near the top, where it can be modified. In this case there is only one input, so it is already selected.

First tap on the Units button and return to SI units.

Screenshot

The radius and area values now appear in metres and metres squared, but circumference will continue to appear in fathoms unless we clear the display unit.

Tap in the formula field and modify it so it reads:

2 m * 1:20

and hit the return key.

Screenshot

The colon is a range operator and produces an array of integers from its first operand to its second. In this case that will be 1,2,3...19,20. When this is multiplied by 2 m, the result will be 2 m, 4 m etc. up to 40 m.

On the radius input row, the value is displayed as:

2.00000...[20,1]

which that the result has 20 rows, 1 column and the first value is 2.0.

Tap the info button on the radius row.

Screenshot

The calculated value for the radius expression is shown. You can drag the result grid up and down (and side to side if it were wider) to see additional values. You can also use the arrows at the bottom to jump to the edge of the grid they point towards. In larger matrices, the centre dot will scroll to the middle of the grid.

Tap the back button to return to the model information view and then try tapping on the area and circumference output rows to inspect their values. Since outputs can't be selected for the formula field, there is no need for the info button and tapping anywhere on the row displays the result.

Return to the diagram and tap on the background, select Add Tool to Model and then Graph.

Screenshot

Rename the tool to Plot and then tap on the X1 row and enter radius into the formula field.

Note that you could also use the value browser to enter the expression name. See the section on formula field in the program documentation.

Screenshot

The X1 row now shows the formula and the default minimum and maximum for the X axis.

Tap on the Y1 and enter area into the formula field.

Screenshot

Tap on the plot button.

Screenshot

If you are on a Mac or an iPad, tap the button at the left of the bottom toolbar to expand the plot.

Each value of the radius array has been plotted along the x axis against the values of the area array along the y axis. Since we haven't specified axis minimums or maximums, the largest and smallest values in the array were used.

If you expanded the plot, tap the button at the lower left again to show the diagram again.

Tap the back button to show the graph definition again.

Screenshot

Now tap on the info button to the right of the X axis row.

Screenshot

Here we can specify the minimum and maximum to use for the x axis, as well as what display unit to use if we want something other than the current default.

In the Min field enter 0 m. (This has already been done in the screenshot above).

Note that entering the unit is not optional and the unit must be a length unit to match the values in the radius array. While we have just entered a constant here, any valid Math Minion formula could have been used.

Enter 40 m into the Min field and then tap the back button to return to the graph definition view. Then repeat the process for the y axis, with a minimum of 0 m^2 and a maximum of 6000 m^2. Finally return to the graph definition view again and tap the Plot button.

Screenshot

That looks better.

Return to the graph definition view.

Screenshot

Let's add the circumference to the plot. For two dimensional plots, an x value can have multiple y value lines associated with it. They should all have the same number of values in their arrays. You can also have multiple x values, each with its own set of y lines.

First select the y axis line so the new y axis is added below it. Then tap the Add Y button.

Enter circumference in the formula field.

Screenshot

Note that the circumference values are in the default display units of metres, not the fathoms that we specifically assigned to the circumference expression.

Tap the info button at the right of the Y2 line and enter 0 m for the minimum and 300 m for the maximum. Then return to the graph definition view and tap the Plot button.

Screenshot

I have also expanded the graph to full screen in the shot above.

Both lines are now plotted, but the Y axis values are still just those for the area.

Tap on any of the y axis labels. This will cycle the labels to the next y axis.

Screenshot

The circumference labels are now shown.

You can also drag the graph around and zoom in and out just as you can with the diagram. As you pan and zoom, the labels will change to reflect the changes.

Try panning and zooming the plot.

Screenshot

This is a good way to check out particular features and determine their coordinates.

Shrink the plot back down if you expanded it and tap the Sessions button on the bottom toolbar.

Screenshot

Tap on the info button to the right of the tutorial session name.

Screenshot

This will copy the entire session to the pasteboard and return to the model view.

Screenshot

Tap on the background and then select Paste to Model from the resulting pop up menu.

Screenshot

We have now pasted a copy of our session into itself, which is kind of weird. When you paste a session into a model, a new child model is created with the contents of the top model of the copied session. Models can contain other models to whatever depth you want.

A practical use of this might be that you have some calculation in a session that you want to embed in another session.

Tap on the tutorial icon.

Screenshot

This is kind of confusing since the information view for the new tutorial model looks just like the one for the base model. However the name in the tutorial icon is in blue, indicating it is the selected tool and there is a back button at the top left of the view.

Replace the formula for radius with radius.

Screenshot

The outputs look the same, but now there is a connection from the base model's radius expression to the tutorial model. When tool names are used in the formula of an expression designated as an input, they refer to tools in the parent model, not the model that contains the expression.

Therefore when we enter radius as the formula for the radius expression in the tutorial model, it doesn't refer to itself, but rather the expression named radius in the parent model.

Tap on the background somewhere to the left of the area icon and then choose Select Multiple from the pop up menu.

Screenshot

A selection box appears.

Drag the upper left and lower right handles on the selection box until the box covers some part of the area, circumference and plot icons, but not the other two.

Tap inside the selection box and then on Delete Selection in the pop up menu.

Screenshot

The selected tools are gone. If this wasn't what was intended, you could use the Undo button to reverse the deletion.

With the tutorial model selected, tap on the Diagram button near the bottom.

Screenshot

The diagram for the tutorial model slides into view.

Add two additional expressions. Name the first graph and make its formula just plot. Turn on its output switch.

Name the second expression table and make its formula plot.table. Make it an output as well.

Tidy up the diagram by moving icons around and zooming in or out as appropriate. Note that you can move multiple icons with the Select Multiple options used to delete icons. Just drag the selection box and the icons in will all move together.

Screenshot

In the screenshot above, I have the table expression selected. Its formula is plot.table which ask for the table parameter of the tool named plot. Many tools have parameters you can request and these are listed on the documentation page for each type of tool. They will also appear in the value browser.

When you request a table from a graph, it returns a type of variable that is something like a database query result. It has named columns, which can have different unit types or even be strings. See the documentation on minion values and on the data table tool for more information. There are also a number of examples in the Getting Started session.

Tap the back button at the top left of the diagram to return to the parent model.

Screenshot

The information view for the tutorial model now shows the additional two outputs. The graph expression just references the plot tool in the model and the only reason for including it was to be accessed from outside the model. If you tap on the graph output line, the graph will be displayed. Similarly if you tap on the table line, the table will appear.

You can also use the output expression names as parameters to the model. For instance, a formula tutorial.table.area/2 would return a column area taken from the table expression, with all the values divided by 2. You might want to try adding an expression and playing around with that.

This tutorial is already way too long, so I will end here. However I have barely touched Math Minion's capabilities, so I would strongly urge you to check out the documentation (the question mark at the upper right) and also the examples in the Getting Started session.