<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <link rel="icon" href="favicon.ico">
    <link rel="stylesheet" href="root.css">
    <title>About SageMathCell</title>
  </head>
  <body>
    <h1>About SageMathCell</h1>
    <p>
      <a href="https://github.com/sagemath/sagecell">SageMathCell</a>
      is an <a href="https://github.com/sagemath/sagecell/blob/master/LICENSE.txt">open-source</a>,
      scalable, and easy-to-use web interface to
      <a href="https://www.sagemath.org">Sage</a>, a comprehensive open-source math
      software system. Additionally, SageMathCell can be used to embed
      Sage computations into any webpage.
    </p>
    <h2 id="embedding">Embedding into a webpage</h2>
    Embedding a Sage cell into a webpage is straightforward:
    <ol>
      <li>
      <p>
        Include the following HTML at the top of the webpage
        (optionally replacing <code>sagecell.sagemath.org</code> with the name
        of your server). The second line makes it so that any element with a
        class of <code>sage</code> will turn into a Sage cell.
      </p>
      <pre data-lang="text/html">&lt;script src="https://sagecell.sagemath.org/static/embedded_sagecell.js"&gt;&lt;/script&gt;
&lt;script&gt;sagecell.makeSagecell({"inputLocation": ".sage"});&lt;/script&gt;</pre>
      <p>
        If you are embedding into a webpage with lots of styling (like
        a blog, or a deck.js presentation), there might be conflicts
        between the page styling and the styles for the Sage cell.  If
        you notice that the Sage cell is not looking normal, you might
        also include the following code after the above in order to
        fix the Sage cell styles.
      </p>
     <pre data-lang="text/html">&lt;link rel="stylesheet" type="text/css" href="https://sagecell.sagemath.org/static/sagecell_embed.css"></pre>
      </li>
      <li>
        Include code in the body of the page. The code is wrapped in
        <code>&lt;script&gt;</code> tags so that it is not
        treated as HTML.
        <pre data-lang="text/html">&lt;div class="sage"&gt;
  &lt;script type="text/x-sage"&gt;1+2&lt;/script&gt;
&lt;/div&gt;</pre>
      </li>
      <li>
        Subscribe to the discussion group <a href="https://groups.google.com/forum/#!forum/sage-cell">sage-cell</a> to be aware of changes and issues.
      </li>
    </ol>
    There are <a href="https://github.com/sagemath/sagecell/blob/master/doc/embedding.rst">lots of options</a>
    controlling how cells are embedded, including:
    <ul>
      <li>
        linking multiple cells together with a single session
      </li>
      <li>
        hiding various parts of the user interface (for example, hiding the
        code box so only the Evaluate button is visible)
      </li>
      <li>
        changing the text of the Evaluate button
      </li>
      <li>
        changing the system used to evaluate code (so the code is evaluated
        as <a href="http://www.r-project.org/">R</a>, for example).
      </li>
    </ul>

    <h2 id="fullexample">Full Example</h2>
    Here is a complete web page example:
<pre data-lang="text/html">
&lt;!DOCTYPE HTML&gt;
&lt;html&gt;
  &lt;head&gt;
    &lt;meta charset="utf-8"&gt;
    &lt;meta name="viewport" content="width=device-width"&gt;
    &lt;title&gt;SageMathCell&lt;/title&gt;
    &lt;script src="https://sagecell.sagemath.org/static/embedded_sagecell.js"&gt;&lt;/script&gt;
    &lt;script&gt;
    // Make the div with id 'mycell' a Sage cell
    sagecell.makeSagecell({inputLocation:  '#mycell',
                           template:       sagecell.templates.minimal,
                           evalButtonText: 'Activate'});
    // Make *any* div with class 'compute' a Sage cell
    sagecell.makeSagecell({inputLocation: 'div.compute',
                           evalButtonText: 'Evaluate'});
    &lt;/script&gt;
  &lt;/head&gt;
  &lt;body&gt;
  &lt;h1&gt;Embedded Sage Cells&lt;/h1&gt;

  &lt;h2&gt;Factorial&lt;/h2&gt;
  Click the &ldquo;Activate&rdquo; button below to calculate factorials.
    &lt;div id="mycell"&gt;&lt;script type="text/x-sage"&gt;
@interact
def _(a=(1, 10)):
    print(factorial(a))
 &lt;/script&gt;
&lt;/div&gt;

&lt;h2&gt;Your own computations&lt;/h2&gt;
Type your own Sage computation below and click &ldquo;Evaluate&rdquo;.
    &lt;div class="compute"&gt;&lt;script type="text/x-sage"&gt;plot(sin(x), (x, 0, 2*pi))&lt;/script&gt;&lt;/div&gt;
    &lt;div class="compute"&gt;&lt;script type="text/x-sage"&gt;
@interact
def f(n=(0,10)):
    print(2^n)
&lt;/script&gt;&lt;/div&gt;
  &lt;/body&gt;
&lt;/html&gt;
</pre>

    <h2 id="permalinks">Permalinks</h2>
    SageMathCell has two types of permalinks generated with each
    computation (accessible from links at the upper right of any output).
    <dl>
      <dt>Permalink<dt>
        <dd>
          A URL which contains a compressed version of the code. This is a
          truly permanent link that does not depend on the server storing the
          code (since the text is encoded in the URL itself). This URL can be
          used with a different server simply by changing the
          domain name. If the code is too long, the length of the URL may
          cause problems in some browsers.
        </dd>
      <dt>Shortened Temporary Link</dt>
      <dd>
        A shorter URL containing an identifier for the code. The code is
        stored in a database and retrieved using the ID, so the
        link will be valid only with servers connected to the same database, and only as long as the
        database retains the input.
      </dd>
    </dl>
    <h2 id="in-use">Where is it used?</h2>
    SageMathCell is used in a variety of places. If you know of
    another use of SageMathCell, please let us know.
    <ul>
      <li>
        Curricular materials
        <ul>
          <li>
            <a href="http://buzzard.ups.edu/">Rob Beezer</a>&rsquo;s
            <a href="http://linear.ups.edu/html/fcla.html"><cite>A First Course in Linear Algebra</cite></a>
            (see, for example, the Sage demonstrations in the section on
            <a href="http://linear.ups.edu/html/section-RREF.html">RREF</a>)
          </li>
          <li>
            The <a href="http://calculuscourse.maa.org/">MAA Calculus textbook</a>.
            This book is transitioning to using embedded Sage Cells for all
            of its interactive activities.
          </li>
          <li>
            Ben Woodruff&rsquo;s
            <a href="https://github.com/bmwoodruff/multivariable-calculus-IBL">Multivariable Calculus notes</a>,
            with Sage links in the margins
          </li>
          <li>
            <a href="http://www.mc.edu/faculty/travis">John Travis</a> has
            been embedding Sage Cells in <a href="http://webwork.maa.org/">WeBWorK</a> problems
          <li>
            <a href="http://jasongrout.github.com/applied-linear-algebra/">Applied Linear Algebra notes</a>
            by Jason Grout
          </li>
          <li>
            Brandon Curtis</a> developed some very <a href="http://sage.brandoncurtis.com/">nice short examples</a> for a variety
            of areas
          </li>
          <li>
            Christian Bär</a> has <a href="https://www.cbaer.eu/joomla/index.php/en/mathematics/practice">a collection of online
exercises for students</a> and <a href="https://math.cbaer.eu/CTP/CTP.html">the cosmic travel planner</a>
          </li>
          <li>
            <a href="https://sebastien-breteaux.perso.math.cnrs.fr/">Mathematical Automatisms Development: Exercises for first year university students in a scientific field</a> by Sébastien Breteaux. (In French.)
          </li>
        </ul>
      </li>
      <li>
        <a href="https://www.findstat.org">The database of combinatorial statistics and maps</a>
      </li>
      <li>
        The <a href="https://wiki.sagemath.org/interact/">Sage Wiki</a>
      </li>
      <li>
        Tanzania Students and Scholars Foundation Limited (TSSFL) <a href="https://www.tssfl.com/">Open Discussion Forums<a>
      </li>
      <li>
        SageMathCell powers the Sage
        <a href="https://itunes.apple.com/us/app/sage-math/id496492945">iOS</a> app
      </li>
    </ul>
    <h2 id="technology">Technology used</h2>
    SageMathCell is built on top of the
    <a href="https://ipython.org">IPython</a> architecture for executing Python
    code remotely. We use:
    <ul>
      <li>
        <a href="http://www.tornadoweb.org/">Tornado</a> web server (possibly
        set up with something like <a href="http://nginx.org/">nginx</a>, to
        serve static assets, and <a href="http://haproxy.1wt.eu/">HAProxy</a>,
        to proxy connections)
      </li>
        <li>
        <a href="http://www.zeromq.org">&Oslash;MQ</a> for communication between web server and IPython kernels
      </li>
      <li>
        A <a href="https://github.com/sagemath/sagecell/blob/master/interact_sagecell.py">new implementation</a>
        of Sage interacts which provides cleaner code and better functionality,
        along with a
        <a href="https://github.com/sagemath/sagecell/blob/master/interact_compatibility.py">backwards-compatible interact interface</a>
      </li>
      <li>
        <a href="http://www.sqlite.org/">SQLite</a> (via
        <a href="http://www.sqlalchemy.org/">SQLAlchemy</a>) for storing
        permalinks and usage statistics
      </li>
      <li>
        In the browser, we use:
        <ul>
          <li>
            <a href="http://jquery.com/">jQuery</a> for general JavaScript code
          </li>
          <li>
            <a href="http://jqueryui.com/">jQuery UI</a> for interact controls
          </li>
          <li>
            <a href="https://github.com/furf/jquery-ui-touch-punch">jQuery UI Touch Punch</a>
            for allowing touch events in jQuery UI
          </li>
          <li>
            <a href="http://www.mathjax.org/">MathJax</a> for rendering mathematics
          </li>
          <li>
            <a href="https://github.com/sockjs/sockjs-client">SockJS</a> for
            communication with the server (using
            <a href="http://www.websocket.org/">WebSockets</a> in modern browsers).
          </li>
          <li>
            <a href="http://codemirror.net/">CodeMirror</a> for the code editor
          </li>
        </ul>
      </li>
    </ul>
    <h2 id="history">A short history</h2>
    <p>
      In January 2011 at <a href="https://wiki.sagemath.org/days27">Sage Days 27</a>,
      William Stein and Jason Grout implemented a proof-of-concept
      &ldquo;Single Cell&rdquo; server designed to be a web interface for a
      single Sage computation. Ira Hanson soon joined the project and Jason and
      Ira continued building a prototype. Many helpful design discussions with
      Robert Bradshaw, Fernando Perez, Min Ragan-Kelly, and Brian Granger at
      <a href="https://wiki.sagemath.org/days29">Sage Days 29</a> pushed the
      design further. Alex Kramer joined the project in May 2011, and Jason,
      Ira, and Alex (the &ldquo;Drake Sage Group&rdquo;) worked full-time at
      Drake University (thanks to the
      <a href="http://utmost.aimath.org">UTMOST</a> NSF funding and a
      <a href="http://artsci.drake.edu/grout/lib/exe/fetch.php/assistantships-scalableinternetinterfaceforsage.pdf">Drake internal grant</a>)
      to design and implement the first version of SageMathCell in the
      summer of 2011. Ira Hanson worked with Michael Gage, Jason Aubrey, Davide
      Cervone, and John Travis from WeBWorK at
      <a href="https://wiki.sagemath.org/days31">Sage Days 31</a> to allow Sage
      cells to be embedded in WeBWorK problems and other external pages.  In
      July 2011, the SageMathCell developers
      <a href="https://groups.google.com/forum/?fromgroups=#!topic/sage-devel/SRnR9vdNmBc">announced</a>
      the release of an open beta for SageMathCell Version 1 on a
      public server for testing.
    </p>
    <p>
      Version 1 of SageMathCell reimplemented much of the IPython 0.12
      messaging protocol in a custom layer on top of Sage (since IPython was
      not yet mature enough to be included in Sage). Jason, Ira, and Alex
      continued maintaining and improving this codebase throughout the
      2011&ndash;2012 academic year. The Android and iOS apps, which relied on
      SageMathCell, were built by Ivan Andrus and Volker Braun. People
      started incorporating Sage cells into their curricular materials, and
      momentum was gathering. Alex and Jason attended
      <a href="https://wiki.sagemath.org/days35.5">Sage Days 35.5</a> to help
      in these and other efforts.
    </p>
    <p>
      By the spring of 2012, the IPython codebase had matured enough to be
      included in Sage and serve as a base for SageMathCell. Steven Johnson
      joined Jason, Ira, and Alex to work full-time (under NSF funding) during
      the summer of 2012 to go back to the drawing board and redesign and
      reimplement SageMathCell to take advantage of insights gained
      during the first year. Byron Varberg also joined the Drake Sage Group to
      implement the Sage Interact website. SageMathCell Version 2
      <a href="https://groups.google.com/forum/?fromgroups#!topic/sage-devel/8B3ihC93DYU">went beta</a>
      in July 2012.
    </p>
    <p>
      In the summer and fall of 2012, David Smith started transitioning the MAA
      Calculus book to use Sage interacts for all interactive activities, which
      was tested at Hood College during the 2012&ndash;2013 academic year.
      Jason, Ira, and Alex continued maintaining and improving SageMathCell
      codebase during the academic year as well.
    </p>
    <p>
      In the summer of 2014, Andrey Novoseltsev picked up maintenance and
      continued further development of SageMathCell.
    </p>
    <h2 id="authors">Authors</h2>
    <ul>
      <li><a href="https://github.com/jasongrout">Jason Grout</a></li>
      <li><a href="https://github.com/ihanson">Ira Hanson</a></li>
      <li><a href="https://github.com/stevenJohnson">Steven Johnson</a></li>
      <li><a href="https://github.com/kramer314">Alex Kramer</a></li>
      <li><a href="https://github.com/novoselt">Andrey Novoseltsev</a></li>
      <li><a href="http://wstein.org">William Stein</a></li>
    </ul>
    <p class="sagecell_disclaimer">
      This material is based upon work supported by the National Science
      Foundation under Grant No. DUE-1022574. Any opinions, findings and
      conclusions or recomendations expressed in this material are those of the
      author(s) and do not necessarily reflect the views of the National
      Science Foundation (NSF).
    </p>
  </body>
</html>


Collaborative Calculation and Data Science

colby

sagemath

Product

Resources

Company