Math 421  •  Fall 2010

About Presentations

18 September 2010

Copyright © 2010 by Murray Eisenberg. All rights reserved.

This notebook describes what the Presentations add-on for Mathematica  is, how to load it, and how to get help about its functions.

Prerequisites

Mathematica

You should know how to navigate around a Mathematica notebook, how to create and type input into an Input cell, and how to evaluate an Input cell.

Mathematics

Just a slight acquaintance with complex numbers is needed here.

About Presentations

Presentations is a Mathematica application written by David J.M. Park, Jr. It consists of Mathematica add-on packages that define many functions for creating and displaying 2-dimensional and 3-dimensional graphics. In particular, the packages provide functions for manipulating objects involving complex numbers, and for creating and graphically representing such objects.

Where did the cell brackets go?

When you look at this notebook, and many others involving the Presentations add-on, you may be surprised to see no cell brackets or group brackets along the right-hand edge of the window.

Actually, the brackets are there! They are just hidden until you move the mouse toward the right boundary of the notebook window. Try it!

The reason this happens is because of a special "style sheet" that has been applied to the notebooks, including this one. It keeps the cell brackets out-of-sight until you need them.

These notebooks also have, besides the "hidden" cell brackets on the right, triangular GroupOpener triangles ▸ to the left of section-type cell groups. With the triangle pointing rightward ▸ like that, the cell group is closed. By clicking on the triangle, the cell group opens (and the triangle turns to point downward ▾).
This action with the GroupOpener triangle is similar to what you may have seen elsewhere where + and - symbols are used to show "collapsed" and "opened" lists of items, for example, in a directory tree or outline.

Installing Presentations

If you are working at the Mathematics and Statistics Department Resource Center, LGRT 110, , then Presentations is already installed. (You will still have to load Presentations after you open Mathematica.)

Using Presentations at a UMass OIT computer classroom

Presentations is not installed on OIT computers, including the ones at the Learning Commons. However, you may still use there the copy you received from Prof. Eisenberg.

Preparing (one time steps)

Do Steps 1 and 2, below—just once.

1. Make a folder Applications on your flash USB drive ("thumb drive").

2. Unzip the entire packagepr.zip archive file inside that Applications folder. Do this so that you preserve the folder tree structure.

Check that you now have a folder Presentations inside the Applications folder you made. And inside that Presentations folder you should have, among other things, a file ComplexGraphics.m as well as further sub-folders Documentation, FrontEnd, and Kernel.

(If you don't want to use so much space on your flash USB drive, you could set up the folders first and burn them to a CD instead.)

Copying (at each log in to an OIT computer)

Do the following step each time you log in to an OIT computer! (That's because your OIT "user profile" disappears each time you log out.)

3. Copy the Applications folder, with its entire Presentations sub-folder, into the following folder, where [netid] is your actual OIT NetID (login name):
• On a Windows 7 PC—
	C:\Users\[netid]\AppData\Roaming\Mathematica
• On a Mac—
	/Users/[netid]/Library/Mathematica

Now open Mathematica and then load Presentations in the usual way—see the section "Loading Presentations", below.

Installing Presentations on your own computer

If you are working on your own computer, install Presentations as follows:

1. Evaluate the following input cell:

$UserBaseDirectory

2. Open the folder whose name appears in the preceding output cell.

3. Open the Applications sub-folder of that folder. (If there is no such sub-folder, create one.)

4. Unzip the entire packagepr.zip archive file into that Applications sub-folder. Do this so that you preserve the folder tree structure.

Check that you now have a sub-folder Presentations inside that Applications sub-folder.
For example, if in Step 1 you obtained the output
	D:\Addons
then you should now have a path: 
	D:\Addons\Applications\Presentations
And inside that Presentations folder you should have, among other things, a file ComplexGraphics.m as well as further sub-folders Documentation, FrontEnd, and Kernel.

(It's possible to change the location that Mathematica uses for the value of $UserBaseDirectory. With Windows, for example, you can set the Windows environment variable MATHEMATICA_USERBASE to a location of your choice.)

You only need to carry out steps 1–4, above, once, of course. Now, whenever you want to use Presentations, first fire up Mathematica and then load Presentations in the usual way—see section "Loading Presentations", below.

Using Presentations elsewhere

To use Presentations somewhere else, you will need to use a flash USB drive ("thumb drive").

Do steps 1–4, below. You need to do these only once.

1. On your flash drive, create a folder, say AddOns.

3. Make a sub-folder Applications of that folder.

4. Unzip the entire packagepr.zip archive file into that Applications sub-folder.

Check that you now have a sub-folder Presentations inside that Applications sub-folder.
For example, if your removable media was drive D, then you should now have a path: 
	D:\AddOns\Applications\Presentations
And inside that Presentations folder you should have, among other things, a file ComplexGraphics.m as well as further sub-folders Documentation, FrontEnd, and Kernel.

Now each time you use Presentations with Mathematica somewhere that Presentations is not already available (e.g., not on your own computer), do the following three steps:

A.  Open Mathematica. Then evaluate the following input cell:

Unprotect[$UserBaseDirectory]

B. Evaluate the following input cell, where in place of my D:\Addons, you use whatever you chose in Step 1, above:

$UserBaseDirectory="D:/AddOns"    (* use YOUR folder path! *)

C. Evaluate the following input cell:

AppendTo[$Path,ToFileName[$UserBaseDirectory,"Applications"]]

Now load Presentations—see section "Loading Presentations", below.

If you don't have the file packagepr.zip

If you don’t have the packagepr.zip file (and you’re not taking Math 421),  you may purchase it from its author, David Park. See his Presentations web page.

Loading Presentations

Before you use any functions from Presentations, you have to load its packages into Mathematica, so that all the definitions in those packages become available for you to use.

To load Presentations, evaluate the following Input cell. Do it now! (Even if the cell was already evaluated, it won’t hurt if you evaluate it again.)

<<Presentations`

Check now whether you evaluated the cell: at its left you should see a label such as In[1].

What happens if you evaluate an expression involving a Presentations function before you load Presentations? 
• At first, the name of the function will appear in blue, just like any name to which you and Mathematica have not assigned a meaning. And Mathematica will be unable to complete evaluating the expression.
• After you subsequently load Presentations, the name will turn red. And you will see a Mathematica warning message about the name appearing “in multiple contexts”.
That red coloring and warning message tell you there could be a problem. But probably no harm will be done.
(Actually, some harm might be done—in case you defined a function with the same name yourself. Then it becomes a matter of which definition Mathematica should use, yours or the one from Presentations. That’s where “contexts” come in. Of course all the Presentations functions, like built-in functions, have names beginning with upper-case letters, and you should never define objects having names beginning with upper-case letters!)

Exercise . Explore the situation with using names from packages before they are defined as follows.
This exercise shows why you need to go through steps (1)–(3) above if you forget to load Presentations before you evaluate an expression involving one of the Presentations functions.
	(a) Exit from Mathematica and start a new Mathematica session.
	(b) Open this notebook, so you can read these instructions, but select No when asked whether to evaluate initialization cells.
	(b) Open a new notebook.
	(c) Type the following in an input cell and evaluate that cell:
		ComplexPoint[1+I]
(Mathematica will just spit your input back at you as output, since it doesn’t know the definition of ComplexPoint yet.)
	(d) Try to rescue yourself by loading Presentations now. See what happens.
	(e) Type and evaluate a new input cell with the same expression ComplexPoint[1+I] as before.

Getting help for Presentations

To open the guide to Presentations in the Documentation Center, evaluate:

PresentationsHelp

Another way to access the Presentations page is: 
	• Open the Documentation Center: from the main Mathematica menu, select Help. From the Help menu, select Documentation Center.
	• In the Documentation Center’s Search bar, type Presentations and press ⌤.
Try that!

By expanding the section cell groups in the Presentations page—use the triangular cell-openers at the start of the section heading—you will see a list of the application’s various sections (which are implemented as individual Mathematica packages).

Try it: open the “Presentations Sections” group on the Presentations page.

One of the packages listed, which you will be using a lot, is DrawingPaper. Click its name there. On the resulting guide page, find the entry about the function Draw2D and click the entry to open the reference page about the function. Try it now!

To obtain information about a particular Presentations function whose name you know, evaluate an expression of the form ?name. Try this:

?Draw2D

That just gives brief information about the function. Then for the function’s reference page in the Documentation Center, click the » hyperlink in the output. Try it!

The other Presentations package you’ll be using a lot is ComplexGraphics. Look it up in the Documentation Center now. (You can either go back to the main Presentations page in the Documentation Center or just search for ComplexGraphics using the Documentation Center search bar.) Do that now.

As usual, for ComplexGraphics functions you may use a ?name information request.  For example:

?ToCoordinates

Again, use the  » hyperlink to get to the Documentation Center reference page about the function.

To search for a particular Presentations function in the Documentation Center, type the function’s name in the search bar there. Try it now: Search for Draw2D in the Documentation Center.

To find out the names of all ComplexGraphics functions, evaluate the following input cell:

?Presentations`ComplexGraphics`*

To get brief information on one of the names listed, click its name in the preceding output. Try it: click  ComplexPoint in that list.
What you’ll see is the same brief information as if you had typed and evaluated ?ComplexPoint in an input cell.
As usual, if you next click the » hyperlink in the output, you’ll get directly to the function’s reference page in the Documentation Center.

Exercise . (a) Find out all the names in the DrawingPaper package.
(b) One of those names is of the function Draw. Look at its reference page in the Documentation Center.

Exercise . Learn something about the Presentations function ToComplex.

Another way to find out what Presentations functions are available, and to find out the syntax of a particular one, is to use the palette PresentationsPalette. See the following section.

The Presentations palette

Presentations comes with a special palette, PresentationsPalette, which makes it easy to find out what functions are available, by category, and to insert a template for any of these functions into your notebook.

The PresentationsPalette is useful for accessing the documentation and for forming templates of Presentations functions. On it you will find buttons for:
	• templates of functions to create a drawing in the plane are in Drawing ▸ DrawingPaper ▸ Graphics (the one you’ll want is Draw2D);
	• templates of functions to create complex geometric graphics objects are in Drawing ▸ Complex Graphics ▸ Primitives; and
	• templates of functions to convert complex numbers between different forms are in Drawing ▸ Complex Graphics ▸ Coordinates.

A quick way to learn about using the palette is to watch the video "UsingPresentationsPalette", available from the Files page on the Math 421 web site.

Here is a short summary of what is shown in the video.

Opening the palette

To open the palette, from Mathematica's menu select Palettes ▸ Presentations.

Here is what the palette looks like:

The palette's big buttons at the top

To load the Presentations package, you may click the palette's big top button, Presentations. (For many of my notebooks, you won't need to do that, as they have Initialization cells that, when you open the notebook, automatically load the package.)

To open Presentations documentation in the Mathematica Documentation Center, you may click the palette's second big button, Documentation.

The palette's main divisions and sections

The palette has two main divisions: Drawing and Writing. In this course, you'll mostly use the Drawing division.

To open the Drawing division in the palette, click the triangular opener there. This is what you'll see:

To open sections in the Drawing division, click their triangular openers. Typically you'll want to open the DrawingPaper and ComplexGraphics sections. When you do, the palette will appear as follows:

Now you see various categories within each of the two opened sections.

Inserting templates into your notebook

For most drawing, you'll want to use the Presentations function Draw2D. To insert a template for Draw2D into your notebook, click the Graphics category in the DrawingPaper section. That will open a fly-out menu; select Draw2D from it. (I couldn't capture the fly-out menu in a screen shot.) Here is the template you'll see inserted in your Input cell:
	Draw2D[{primitives},options]

Just like templates from Mathematica's built-in Classroom Assistant palette, the template for Draw2D will show you the syntax of the function. Placeholders with suggestive names appear where you will type the function's arguments. You can tab from one placeholder to the next and type entries there, or insert entries there from other templates.

For example, in the Draw2D template in your notebook, make sure the primitives placeholder is selected. To insert a template for a complex geometric primitive object, in the palette's Complex Graphics section click Primitives. From the fly-out menu, select a primitive, e.g., ComplexCircle. This is what you will now see in your notebook:
	Draw2D[{ComplexCircle[z,radius]},options]
Now you can go ahead and type in a value for z (the circle's center, as a complex number) and radius.

To complete this example, you would either delete the options placeholder and the comma preceding it, or else insert some options for Draw2D that affect the appearance of the overall drawing.

OptionsFinder

PresentationsPalette includes an OptionsFinder button that is handy for finding out about, and inserting options for any function func—provided you already have an  expression including at least func[ involving that function. To use it:
	1. Click the OptionsFinder button in PresentationsPalette. This opens a new, small Options for selected function palette.
	2. In your notebook, highlight the function's name, or the expression beginning with that name, and on the palette click the button Options (tooltips). This opens a new palette showing all the available options for that function.
	3. If you mouse over an option's name, you'll see a tooltip giving the default value for the option. If you click the ? button next to one of the options' names, you'll see a tooltip giving a brief description of that option.
	4. In your notebook, put the cursor into where an option could go.
	5. On the palette for the function's options, click the name of the option you want. This inserts into your notebook the option with its default value set.
	6. The default value for the option will be highlighted. You may now type over that value to change it.