I’ve been assigning Sage assignments for several years in my (standard) undergraduate abstract algebra course. (They are all available now in Judson’s open source text.)  Mid-term last Spring I switched over to using the new “course” functionality in SageMathCloud (SMC).  William Stein and several of his colleagues and students have greatly improved SMC over the summer and courses work really well now.

Today I graded my class’ second assignment.  (The first was just procedural so we made sure their accounts were all in place and we knew the workflow.)  It was the least painless grading session I’ve ever had.  Very smooth and efficient.  “Low friction,” in today’s parlance.  So here is a guide on getting started and how it all works (and why I like it so much).

## Registration

Have your students signup for a free account.  But most important – have them use their real name and have them use their principal university email address with a canonical domain name (e.g. @pugetsound.edu).  You’ll search for them later via the email address, and the names they enter themselves will show up in score reports, etc.

I have an entire SMC project I creatively call “Courses.”  I pay the $7 monthly fee to be on a members-only server without all the free accounts around competing for resources. It has lots of top-level subdirectories organized by semesters. Make a new SMC “course” file inside of a new top-level directory in your project’s file system. Mine is named 2015-Fall/Math433.course. Open your new course and add a title and description via the “Settings” tab (wrench icon, not gear). Then find a search box for “adding” new students under the student tab and off to the right. (Do not confuse this with the box for “finding” — this is local to your course and you do not have any students yet to find.) It is easy for me to get a comma-delimited list of my students from our administrative systems (this is about the only easy thing to do there). Manufacture such a list and dump it all at once into the add box. Real names will come up for all the students who have followed your signup instructions and you can add them to your course (select several, or all). You’ll then get a very easy-to-manage list of students under the students tab. Your students will also each then get a new project automatically in their project list. It has your course name and their real name in the title. You are the owner of the project, and they are a junior partner, a “collaborator.” This gives you a lot of power to help them remotely and to look at their work in-progress (for each student on your list there is a button that you can use to open their project). Snapshots of student projects can sometimes be very helpful (as the student cannot change them since they are not the owner). ## Assignments I made another top-level directory for my current abstract algebra course to contain assignments and demos the student will see, with a name the students will recognize as their course (e.g. Math433F15). Making this at the top-level will make a better experience for the students, see below. For each new assignment, make a subdirectory for just that assignment (eg Chapter02). You can put lots of things in this folder that will all go to all of the students. But be sure to put in a mostly empty Sage worksheet. For example I called mine 02-Math433-turnin.sagews. In this worksheet I put a header (using HTML with an “h2” tag) with the course name, chapter, etc. Then I put in some basic instructions, based on my experience doing these kinds of assignments with Sage Notebooks. Here it is, modulo wrestling with WordPress: Work the exercises for the chapter in this file. It will be collected automatically after the 6 AM deadline on the day it is due. • Work the problems in order. • Clearly label which part of your work is for which problem (or subproblem). When a question asks for an explanation, provide a well-written response. That means complete sentences, correct grammar and spelling, and you address the question that was asked. In SageMathCloud you can format your writing nicely. Follow the directions below and while editing you will get some buttons above your worksheet to help with formatting, or you can just type in the formatting codes yourself with some help from the editor (which you can configure in your user settings). Notice that you can use $$\mathrm{\LaTeX}$$ syntax to get nice typesetting of any mathemtics you want to use. • Use %html on the first line of cell all by itself to have a cell interpret HTML formatting. • Run the cell to see what it looks like. Double-click in the cell to go back to editing. • Similarly, %md will allow you to write in Markdown syntax. • For$\mathrm{\LaTeX}$, use single dollar signs, or use $$and$$, which is preferable. • For displayed mathematics (centered on a line of its own) you can use double dollar-signs or $and$, which is preferable. Now, back in your course file, hit the “Assignments” tab. Use the search box in the top right to select the folder with your “-turnin” file and other materials. Once you choose this folder, set the “Due Date.” Then you will be able to use the “Assign to…” button to push a copy of the folder out to all your students. (Using a top-level directory in your project means the students get a short path to their assignments in their projects.) Students will see a copy of the folder in their project for the course. It will have an additional small text file, DUE_DATE.txt, that contains the due date you set. Instruct your students to do their Sage assignment in the “-turnin” worksheet and to NOT change the filename or move it. ## Grading You need to manually collect the assignment, but it is a one-click operation with the “Collect from…” button. Do it. Now you get a “Grade” button for each student in your list. This will give you a file list that is a copy of the folder at the time you collected it, and a text file with the student’s name as the filename, so you don’t lose track of whose work you are looking at. You can open the “-turnin” worksheet, or any other file. I make comments on the student’s worksheet, and sometimes copy their code and show them an edited version that I might think is helpful. I do comments in HTML, you could use Markdown. I have a template in my clipboard buffer, so comments are clearly visible (red and big). It begins with the line %html and is followed on the next line by a div element with the attribute style="color:red; font-size:141%". I paste and then fill the div with my comments. Done with a student’s work, back in your course file, you can enter the grade, which is any string you please – a number, a letter grade, or a short comment. Under the “Settings” tab of your course, you can get all your grades in CSV format (to import into a spreadsheet), or in a file of Python data structures. Be sure to “Return” the graded version of the assignment to the students. They will get a new folder with the graded versions. ## Conclusion This may be TL;DR but the one-time setup is pretty easy, making an assignment goes quickly and grading is very streamlined. Everything is where you need it and you have good tools at your disposal at each step. And your students just need to make an account and do their work. Zero setup and no technical hurdles. I’m sure the course functionality will change rapidly (for the better), so if you are finding this months later, look around for updates. I strongly encourage students to sign up for memberships (at$7/month) because I tell them that overloaded free servers are not an excuse for not completing the assignment.  But I think it is also important for them to recognize that this service has value and should be supported (and their textbook is free!).  Remind them to go to their project’s settings (wrench icon), click on “Adjust Project Quotas” and then use the “Member hosting” checkbox.  When they stop paying, their project will go back to being on the free servers, so they never lose their work or the ability to interact with it.

I know William is working on other models for class accounts, so be in touch with him through the “help” email address if your university wants to support all the students in a course with one payment.

Recognize that this environment supports many different types of technical courses.  Besides Sage, there is R, Jupyter notebooks, full Ubuntu Linux terminals with a complete file system, and a wide variety of installed Python packages for science and engineering.  And don’t forget there is a robust LaTeX installation, with semi-live preview and reverse search for compilation errors, which is great for students new to writing mathematical documents.  Sage worksheets use CodeMirror for editing, with goodies like syntax highlighting and tag completion, so it is also a good environment for programming, and other similar work.

## Collaboration

SMC is also great for working with your students.  I’ve got some experiments lined up and will report again soon.

# Summer Progress on MathBook XML

I’ve made a lot of progress this summer on the XML application I have been developing. A better way to describe what I am building is a practical way for authors to create reports, articles and books with the structure explicitly defined, and with no presentation assumed. This will allow for faithful conversions to a variety of formats, and possibly with a variety of sensible options for presentation.

I have been most productive while writing such documents at the same time as I have been developing the application. Here is an example. I have submitted a short note to the American Mathematical Monthly. Authored with MathBook XML, it has been rendered as both a PDF and as a web page.

For the moment, I am trying to have the HTML rendering mimic whatever default rendering you would get from default LaTeX. But you will notice that the HTML version uses knowls for citations. As the HTML rendering evolves, expect it to take even greater advantage of the capabilities of browsers.

I have made a lot of progess with cross-references, including automatic numbering of displayed equations with MathJax. There is minimal support for bibliographic records. Figures and images are supported. A unified approach to tables will have to wait a bit. The CSS for the HTML is functional, but has lots more potential, especially for internationalization. Next I am going to tackle a book-length project that has lots of Sage code (so will make a doctesting framework).

# An XML Application for Mathematics

Some high-level thoughts about a MathBook XML application. I am building an XML vocabulary which I hope will make possible

• relatively painless authoring in XML for for mathematician-authors
• capturing the full structure of scholarly documenst about mathematics
• providing a wide variety of output formats accurately reflecting the content

To do this, I plan to

• keep the number of tags and options to a minimum
• resist too much customization, and resist customizing too much of the presentation
• use simple processing tools, such as xsltproc on XSLT 1.0 features

Specifics and progress will be reported and updated on a project page at the Sage wiki. Priorities for new features will be based on requests. I’ll blog here on less technical aspects of the project.

# The Case for an XML Application

This is the first of two introductory posts about my project supported by my Shuttleworth Flash Grant.  Rationale and motivation here, vague/concrete plan next.

Mathematics or not, I am convinced of the value of capturing scholarly documents in a structured form.  If you wish to have a variety of outputs for your writing, such as print, PDF, HTML web pages, and e-books, then it is a must.

Consider two very different scenarios.  First, when you place a bold typeface to a word, what do you really mean?  Is it emphasis, or perhaps a defined term?  Especially in an electronic medium (see output formats in the previous paragraph), you might wish to handle the two situations differently.  The emphasis could be bold in print, or colored red in an electronic version.  The defined term might be a hyperlink or pop-up window or knowl in the electronic version.  You might begin to see that authoring in a “word processor” is the exact opposite of what I am advocating.

Second, suppose you write in LaTeX. How do you know a subsubsection has ended?  Only when you encounter the start of another subsubsection, or the start of a new subsection, or the start of a new section, or the start of the chapter exercises, or the start of a new chapter, or the start of a new part (a major subdivision of a book), or the end of the book.  It can be a nightmare to process all these conditions in an automated way (see output formats in the previous paragraph), when LaTeX does not require a marker for the end of subdivisions like this.  Many people like to say LaTeX separates structure from presentation, but you can very quickly see this is a false promise, and is routinely violated by authors.

XML (eXtensible Markup Language) is an extremely simple language for describing the structure of text.  It is hierarchical (tree-like structure), and a begin is always accompanied by an end, like any structured programming language.  The vocabulary (“elements” and “attributes”) can be anything you like.  The output can be any format.  For example, you can create LaTeX as output (and then use standard programs to convert to PDF).  The power comes through the transformation language XSL (eXtensible Stylesheet Language) which is often called XSLT (T=Transform).  This is not an easy language to understand or learn.  But an author need only write with an accepted vocabulary and let an existing transform do the conversion.  The hard technical details of the output language can be captured in the transform.  A set of elements, their relationships, and the resulting transforms, are together called an XML application.  (X)HTML is an example of an XML vocabulary.

Case in point.  Summer and fall of 2012, I converted the semi-structured LaTeX source of my linear algebra textbook to an ad-hoc set of tags.  The resulting XSL transformation produced the online version.  None of this is very reusable, and I have not released the transforms publicly.  They should not interest most authors.  The source should be of interest (it is not perfect, but is reasonable) and the outputs, such as the online and print versions, should be the demonstration of the power of XML source converting to two very different formats via an XSL transform.

So I see real utility in creating an XML application for authors of writings about mathematics, with a special interest to allow writing about compuational tools, specifically Sage.  An author could adopt this approach, but any mathematician who can write in LaTeX already has the mindset to use a markup lanuguage rather than a word processor.  More in the next post about design requirements and my plans.  If you cannot wait, head over to the project page.

# Shuttleworth Flash Grant

I’ve been working some the past year or so with Kathi Fletcher and especially in connection with her projects at the OER-PUB group. Kathi is a Shuttleworth Fellow and recently nominated me for a Shuttleworth Flash Grant. You would think an application would be in order. Nope, apparently Kathi’s support is enough. Done, grant awarded. Fantastic! Thanks Kathi, and Shuttleworth Foundation, for the vote of confidence.

Better yet, the grant conditions do not include any kind of official reporting. When does this ever happen? I am expected to use the Shuttleworth logo (see sidebar), plus “We ask you to live openly, tell us and the world what you have done with the money” and “Share with the world how you used this award to bring your idea forward.” So I will be using posts here to communicate progress, and likely have a project page on the Sage wiki.

Initial details on grant activities in another post shortly.

# Hack-the-Book

On Monday night (October 29) about 20 UPS students took me up on the offer to help crowd-source editing the latest version of my linear algebra textbook.  I have converted my LaTeX source to XML (more on that later) and despite making the conversion highly automated there are still errors in the resulting HTML version.  My Math 290 students have been champions at rooting out the errors.

I plan to make a physical hardcover print edition, so I want to make it as error-free as possible before committing to print copies!  So I had pizzas delivered and promised a raffle for the eventual hardcover print edition.  For each section reviewed, a student could add an entry to the hat full of raffle tickets.  The eventual winner was Hunter Wills (that’s him in the upper right corner).

Student Copy Editors

Most students stayed for an hour or two and in total we covered about two-thirds of the sections, with some receiving two looks.  They seemed to do an excellent job, and now I have a huge pile of corrections to make.

# African Institute of Mathematical Sciences, 2012

I am at the African Institute of Mathematical Sciences this January, in Muizenberg, South Africa (near Capetown).  I am teaching a 3-week course on Algebraic Graph Theory.  I thought I might use this vehicle for some regular travel news, but now my trip is half-done and this is the first post.

Nothing too extraordinary to report.  Course is going well.  It has been good to be back and renew old acquaintances (staff and alumni), as well as meet and work with the new students.  I’ve been on two hikes so far, an afternoon trip up nearby 500-meter Muizenberg Peak, and the other an epic day-long walk across a wide swath of Table Mountain National Park.

Some photos follow – let me know if you’d like to see more.