Math Minion

Getting Started Tutorial

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.

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. (images updated November 2018 for version 3.1)

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:

while on an iPad it would appear as:

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:

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

Tapping on the **< A_Simple_Calc** 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.

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:

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.

Note 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**.

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 **Create** button.

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 inputs or outputs, of which there are currently none - more about those later.

Tap on the diagram background.

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.

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

Select **Expression**

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. 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.

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**.

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.

** Because adding expressions is so common, there is a shortcut for it:
**

- On iOS, a long press on the background will immediately add a new expression
- On a Mac, holding down the Command key while clicking on the background will do the same thing.

If on iOS you accidentally create an expression with an unintended long press, just tap the **Undo** button and the bottom of the information view.

Rename the expression **area** and enter the formula:

{pi}*radius^2

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 functions 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 a corner of the **radius** icon to the middle of one of the vertical sides of the **area** icon. These connections show where all of the values used in a tool originate from. Values flow from the corners of icons, to the middle of vertical sides of icons that reference them.

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 trackpad, two finger scrolling (dragging up or down with two fingers) will also zoom in or out.

On a Mac with a mouse, you can use the centre scroll function of the mouse 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. On the Mac and iPad, the view to the right will switch to displaying information about this object. On the iPhone, the information view will overlay the diagram.

Arrange the diagram so it looks like the one below.

Notice that the connection line can run from any corner to either vertical side and will rearrange itself as you move an icon.

Add another expression, this time named **circumference** and enter first part of the formula:

2*radius*{pi}

but stop before entering {pi}.

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.

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

On the resulting function browser, tap on the **Trigonometric math functions** line (1) and then on the **{pi}** line (2). 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 (3) to return to the formula with the template inserted.

The formula for circumference, with the pi function added.

Tap the return key.

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.

Tap on the line labelled **US**

The circumference is now displayed as 41.228 feet, while the area 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.

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.

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

Return to **circumference**, if it isn't still selected, and 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.

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.

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.

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:40

and hit the return key.

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...39,40. When this is multiplied by 2 m, the result will be 2 m, 4 m etc. up to 80 m.

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

2.00000...[40,1]

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

Tap the info button on the **radius** row.

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**.

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.

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.

Tap on the plot button.

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.

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

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.

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 80 m into the **Max** 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 24000 m^2. Finally return to the graph definition view again by tapping the back button (i.e. **< plot**) at the top left.

The scale values should now be reported as you entered them for both **X1** and **Y1**. Tap the **Plot** button to view the graph again.

That looks better.

Return to the graph definition view.

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 for Y2.

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 600 m for the maximum. Then return to the graph definition view and tap the **Plot** button.

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.

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.

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

If you are wondering about the apparent convergence of the two lines at radius 80, note that area/circumference would be:

(pi * r^2) / (2 * pi * r) = r / 2

With a radius of 80, this ratio will be 40 and since we specified the maximum scale for area to be 40 times greater than the maximum scale for circumference, at radius 80 the two lines will appear to cross.

Shrink the plot back down if you expanded it by tapping on the **< tutorial** button at the lower left. Then tap the **Sessions** button on the bottom toolbar.

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

Tap on the **Copy to Pasteboard** item in the resulting menu

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

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

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.

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.

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.

A selection box appears.

Drag the upper left and lower right corners of the selection box until the box covers some part of the area and circumference icons, but not the other ones.

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

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

Double tap (two taps in quick succession) on the plot icon. This will bring up a pop up menu for the plot tool.

A double click will also work on a Mac, but you can also right click or click with two fingers on the trackpad to achieve the same result.

Select the **Delete** item from the menu.

Finally, tap on the tutorial icon to select it.

The the graph is now gone as well, just leaving the radius expression and the tutorial model.

**Note:** if you have quick fingers, you can quickly delete a tool by triple tapping inside its icon. Similarly triple tapping inside a selection box will delete all the selected tools.

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

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.

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.

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 allow the graph 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.