carpentries-incubator / sage-lesson

SageMath Software Carpentry Lesson

This is the lesson on SageMath.

It is being developed for the Software Carpentry workshop at the CoDiMa Training School in Computational Discrete Mathematics.

If you would like to contribute to the development of this lesson, please follow the instructions bellow.

Setup

1. Install SageMath.

Access the lesson locally

1. Run

   $ make lesson-ipynb serve
   

   If you don't have SageMath on you PATH you must run

   $ make lesson-ipynb serve SAGE=/full/path/to/sage
   

2. Open http:localhost:4000 on your web browser.

Change the lesson

1. Launch SageMath by running

   $ sage --notebook=jupyter
   

2. Open http://localhost:8888/ on your web browser.

3. Select the directory _episodes_ipynb.

4. Edit the file as you want.

5. To preview the lesson, follow the instructions on "Access the lesson locally".

Sharing your changes

Send a pull request with only the changes on _episodes_ipynb to https://github.com/alex-konovalov/sage-lesson/.

Acknowledgements

We acknowledge financial support from CCP-CoDiMa (Collaborative Computational Project in the area of Computational Discrete Mathematics EP/M022641/1) and from OpenDreamKit Horizon 2020 European Research Infrastructures project (#676541).

sage-lesson's Issues

Contributors welcome

We're assembling a team to develop SageMath software carpentry lesson. Please leave a brief comment here if you're interested in contributing to this project.

Switch to new lesson templates

Do this now before adding actual content

Support to NbConvertApp.output_files_dir by nbconvert

NbConvertApp.output_files_dir should remove a hack from Makefile but NbConvertApp.output_files_dir was introduced only on nbconvert 5.0.0. When SageMath uses nbconvert >=5.0.0 we can implement this.

Use Sage Notebooks for write the lessons

We can patch https://github.com/swcarpentry/lesson-example to have a _episodes_sage directory where we store the Sage Notebooks and use some scripts to convert the Sage Notebook into Markdown suitable for the Software Carpentry template. The workflow should be more or less the same that the R instructors are using for their lessons. We will have to keep the Sage Notebooks and the generated Markdown on the repository.

Explain Loading and Attaching Sage files

See http://doc.sagemath.org/html/en/tutorial/programming.html. This will most likely be creating a file in one episode and then loading it in the next one.

Instructions for SageMath installation

It is a Software Carpentry custom that attendees of the workshop are supplied with installation instructions for the software that they are asked to install prior to the workshop (see e.g. "Setup" section at http://kkwakwa.github.io/2015-11-16-manchester-codima/).

We need to discuss what is the recommended way to use SageMath during the workshop. As I've mentioned in #2, SMC (SageMathCloud, https://cloud.sagemath.com/) is good to ensure that all users have same experience independently on their operating system, and "installation" is trivial because it works in the browser.

On the other hand, this makes teaching very dependent on the network connection (workshop for 40 people in the same room will require extra care). Also, it's good if the workshop gives a hands-on tutorial after which learners are able to continuing on their own machines (as a usual condition of the workshop is to bring your own laptop). With a cloud based solution this may not be the case (though of course, they will be able to continue "in the cloud" when they have network connectivity).

So each choice has its own benefits and downsides.

The lesson needs a story (research-like problem)

To start with, I suggest to pick up some research-like problem, around which the lesson could centred.

We may look at some other Software Carpentry lessons at http://software-carpentry.org/lessons/ to see some examples of this approach. The GAP lesson (http://alex-konovalov.github.io/gap-lesson/) also followed this practice and used a "toy problem" of calculating the average order of an element of a group. It assumed that the learner is familiar with the group theory course at least at the undergraduate level, and walked the learner from exploring properties of groups and their elements interactively using the command line and writing simple scripts to organising code into modular programs, improving implementations and checking them with regression tests and searching in the small group library for interesting examples of groups, exposing thus a diverse variety of techniques.

If you have a suggestion for a problem or several problems which may be put into the "lesson story", please leave your comments under this issue.