Emmy-Viewers

Emmy-Viewers is a library of tools for visually rendering mathematical objects found in the Emmy computer algebra system. These tools allow you to build symbolic representations and 2D and 3D mathematical scenes for exploring physical and mathematical worlds.

Examples

The first example uses the functions in the emmy.mafs namespace to plot

• ((cube D) tanh), the third derivative of the hyperbolic tangent function, shifted by the x-value of the (interactive, try sliding!) pink point in the scene, and
• the inequality between that function and (cos x):

(emmy.viewer/with-let [!phase [0 0]]
  (let [shifted (emmy.viewer/with-params {:atom !phase :params [0]}
                  (fn [shift]
                    (((cube D) tanh) (- identity shift))))]
    (emmy.mafs/mafs
     {:height 400}
     (emmy.mafs/cartesian)
     (emmy.mafs/of-x shifted)
     (emmy.mafs/inequality
      {:y {:<= shifted :> cos} :color :blue})
     (emmy.mafs/movable-point
      {:atom !phase :constrain "horizontal"}))))

Note To play with interactive versions of these examples, visit https://emmy-viewers.mentat.org.

The next example uses the functions in emmy.mathbox.plot and emmy.leva to plot the functions

• $f(x, y) := D^3\tanh(x) + \sin(y-\texttt{phase})$
• $g(y) := \texttt{shift} * \cos(y - \texttt{phase})$

where $\texttt{phase}$ is supplied by the interactive slider hovering in the top right:

(emmy.viewer/with-let [!phase {:phase 0}]
  (emmy.mathbox.plot/scene
   (emmy.leva/controls
    {:folder {:name "Intro Demo"}
     :schema {:phase {:min -4 :max 4 :step 0.01}}
     :atom !phase})
   (emmy.mathbox.plot/of-y
    {:z (ev/with-params {:atom !phase :params [:phase]}
          (fn [shift]
            (fn [y]
              (* shift (sin (- y shift))))))

     :color "LimeGreen"})
   (emmy.mathbox.plot/of-xy
    {:color "#3090FF"
     :z (ev/with-params {:atom !phase :params [:phase]}
          (fn [shift]
            (fn [[x y]]
              (+ (((cube D) tanh) x)
                 (sin (- y shift))))))})))

Emmy-Viewers uses either Clerk or Portal as a presentation environment.

Quickstart

Install Emmy-Viewers into your Clojure project using the instructions at its Clojars page:

Or grab the most recent code using a Git dependency:

;; replace $GIT_SHA with the sha you'd like to target!

{org.mentat/emmy-viewers
  {:git/url "https://github.com/mentat-collective/emmy-viewers.git"
   :git/sha "$GIT_SHA"}}

Next visit "Quickstart via Clerk" to build scenes using Clerk, or "Quickstart via Portal" to use Portal.

Quickstart via Clerk

The fastest way to get started with Clerk is to use the emmy-viewers/clerk project template. Jump there, or read on to set Clerk up manually.

Install Clerk by adding the following entry to your deps.edn:

{:deps
 {<your other dependencies>
  io.github.nextjournal/clerk {:mvn/version "0.14.919"}}}

Require and start emmy.clerk in your user.clj:

(ns user
  (:require [emmy.clerk :as ec]))

;; start Clerk's built-in webserver on the default port 7777, opening the
;; browser when done
(ec/serve! {:browse true})

Note See Clerk's "Using Clerk" section for more configuration options. Replace any call in that guide to nextjournal.clerk/{serve!,halt!,build!} with emmy.clerk/{serve!,halt!,build!}.

Create a file called emmy/demo.clj and install our default Clerk viewers from emmy.clerk:

(ns emmy.demo
  (:refer-clojure
   :exclude [+ - * / zero? compare divide numerator denominator
             infinite? abs ref partial =])
  (:require [emmy.clerk :as ec]
            [emmy.env :as e :refer :all]
            [emmy.mafs :as mafs]
            [emmy.mathbox.plot :as plot]
            [emmy.viewer :as ev]
            [nextjournal.clerk :as clerk]))

^{::clerk/visibility {:code :hide :result :hide}}
(ec/install!)

Note This namespace imports every function from emmy.env. You'll need to build your mathematical functions out of these emmy.env functions to use them with Emmy-Viewers 2D and 3D plotting capabilities.

Thanks to the ec/install! call above, the return values of all Emmy-Viewers functions will be able to present themselves graphically.

Add this line to plot the sine function using the Mafs.cljs 2D plotting library:

(mafs/of-x sin {:color :blue})

Render it by calling (nextjournal.clerk/show! "src/emmy/demo.clj") at the REPL. You'll see the following:

See the Mafs Guide for 2D plotting examples.

Use plot/scene to render multiple plots onto a 3D canvas:

(plot/scene
 (plot/of-x {:z sin})
 (plot/parametric-curve
  {:f (up sin cos (/ identity 3))
   :t [-10 10]
   :color :green}))

See the MathBox Guide for 3D plotting examples.

Next, try clicking the 'show code' link for the examples at the top of the page and pasting their source into your namespace. Then visit the "Specific Guides" section, and click through "Demos" for inspiration.

Quickstart via Portal

Follow the Portal Usage instructions to the point where you have the Portal dependency installed and loadable.

You'll also need to install node.js to download JavaScript dependencies.

Test your installation by running this command at the REPL:

(require '[portal.api :as p])

If this returns nil you're all set.

Require emmy.portal in your user.clj, and call prepare! to make sure you've downloaded all JavaScript dependencies from npm:

(ns user
  (:require [emmy.portal :as ep]))

;; This really only needs to be run once, but run it at each system start to
;; be safe.
(ep/prepare!)

Start the Emmy-Viewers customization of Portal:

(def portal
  (ep/start!
   {:emmy.portal/tex {:macros {"\\f" "#1f(#2)"}}
    :theme :portal.colors/zenburn}))

The options passed above are optional; :emmy.portal/tex customizes the katex viewer with any option allowed by katex's option support, while :theme sets a custom theme. You can pass any Portal theme that you like, or remove this entry.

Use tap> to send values to Portal:

(tap> (mafs/of-x sin {:color :indigo}))

tap> an Emmy symbolic expression:

(tap> (((exp D) (literal-function 'f)) 'x))

then click the cell in the Portal UI and choose :emmy.portal/tex from the viewer list at the bottom. You should see the expression transform into nicely typeset mathematics.

Note Currently anything from emmy.mafs, emmy.leva, emmy.jsxgraph and emmy.mathlive will render. MathBox support is coming soon!

Visit the "Specific Guides" section, and click through "Demos" for inspiration.

Specific Guides

• MathBox Guide
• Mafs Guide
• Leva Guide

JSXGraph.cljs and MathLive.cljs guides are coming soon.

Demos

These demos are in-progress, more advanced demonstrations of the capabilities of Emmy-Viewers. I'm using these as test cases to flesh out the more settled API, so please read them with that in mind!

• examples.manifold.fdg
• examples.manifold.klein
• examples.manifold.pq-knot
• examples.mathbox.cube-controls
• examples.mathbox.functions
• examples.mathbox.geom
• examples.mathbox.ode
• examples.mathbox.quickstart
• examples.simulation.cylinder-flow
• examples.simulation.oscillator
• examples.simulation.ellipsoid
• examples.simulation.double-ellipsoid
• examples.simulation.lorenz
• examples.simulation.phase-portrait
• examples.simulation.quartic-well
• examples.simulation.toroid
• examples.vega.pendulum

Interactive Demos via Clerk

The project's interactive documentation was generated using Nextjournal's Clerk. If you'd like to edit or play with the documentation or demos, you'll need to install

• The Clojure command line tool
• Babashka

Next, clone the repository:

git clone [email protected]:mentat-collective/emmy-viewers.git
cd emmy-viewers

Run this command in the cloned repository:

bb clerk-watch

This will open a browser window to http://localhost:7777 with the contents of the main documentation notebook. Any edits you make to any file in the src or dev directories will be picked up and displayed in the browser on save.

Dependencies

These viewers are built on the following libraries:

• MathBox.cljs
• JSXGraph.cljs
• Mafs.cljs
• Leva.cljs
• MathLive.cljs

Thanks and Support

To support this work and my other open source projects, consider sponsoring me via my GitHub Sponsors page. Thank you to my current sponsors!

I'm grateful to Clojurists Together for financial support during this library's creation. Please consider becoming a member to support this work and projects like it.

License

Copyright © 2022-2023 Sam Ritchie.

Distributed under the MIT License. See LICENSE.