Emmy

<h1 align="center"> <img src="https://raw.githubusercontent.com/mentat-collective/emmy/main/doc/img/logo.png" width="250" alt="Emmy logo" title="Emmy" /> </h1> <div align="center">

[![Build Status][build-status]][build-status-url] [![License][license]][license-url] [![Codecov branch][codecov]][codecov-url] [![cljdoc badge][cljdoc]][cljdoc-url] [![Clojars Project][clojars]][clojars-url] [![Discord Shield][discord]][discord-url]

</div>

Emmy is a Clojure(Script) implementation of the [scmutils][scmutils-refman-url] system for math and physics investigations in the Clojure and ClojureScript languages. Emmy provides facilities for

• symbolic computation, including state of the art TeX rendering and expression simplification
• automatic, numerical and symbolic differentiation
• numerical integration and optimization
• investigations in differential geometry and Lagrangian and Hamiltonian mechanics

And implementations of many different mathematical objects, all built on a tower of generic, extensible mathematical operations.

Scmutils is extensively used in the textbooks [The Structure and Interpretation of Classical Mechanics][sicm-book-url] and [Functional Differential Geometry][fdg-book-url] by G.J. Sussman and J. Wisdom.

:wave: Need help getting started? Say hi on Clojurians Slack in [#emmy][emmy-slack-url].

Quickstart

Note Emmy is best experienced in an interactive environment like the REPL. We support many environments with rich support for TeX rendering and plotting.

Install Emmy into your Clojure(Script) project using the instructions at its Clojars page:

[![Clojars Project][clojars]][clojars-url]

Or grab the most recent code using a Git dependency:

;; Replace $GIT_SHA with the most recent commit:
{io.github.mentat-collective/emmy
  {:git/sha "$GIT_SHA"}}

Require emmy.env in your Clojure(Script) namespace:

(ns my-app
  (:require [emmy.env :as e :refer :all]))

Or clone this repository:

git clone git@github.com:mentat-collective/emmy.git
cd emmy

then install the Clojure command line tool and run the following command to launch a REPL with emmy.env already loaded:

clj -M:test:dev:repl

Math works as expected (see Generics for the full menu of operations), but notice that the numeric tower includes complex numbers, and proper ratios in ClojureScript:

(- (* 7 (/ 1 2)) 2)
;;=> 3/2

(asin -10)
;;=> #emmy/complex [-1.5707963267948966 2.9932228461263786]

Symbols are interpreted as abstract complex numbers, and arithmetic on them generates symbolic expressions. You can render these with ->TeX and ->infix:

(def render (comp ->infix simplify))

(square (sin (+ 'a 3)))
;;=> (expt (sin (+ a 3)) 2)

(render (square (sin (+ 'a 3))))
;;=> "sin²(a + 3)"

Use the D operator to perform forward-mode automatic differentiation and simplify to collapse symbolic expressions into tidy form:

((D cube) 'x)
;;=>  (+ (* x (+ x x)) (* x x))

(simplify ((D cube) 'x))
;;=> (* 3 (expt x 2))

(->infix
 (simplify ((D cube) 'x)))
;;-> "3 x²"

Emmy is based on the engine behind [The Structure and Interpretation of Classical Mechanics][sicm-book-url], and has a built-in API for exploring Lagrangian and Hamiltonian mechanics.

Define a Lagrangian for a central potential U acting on a particle with mass m:

(defn L-central-polar [m U]
  (fn [[_ [r] [rdot thetadot]]]
    (- (* 1/2 m
          (+ (square rdot)
             (square (* r thetadot))))
       (U r))))

and generate the two Euler-Lagrange equations of motion for the r and theta coordinates:

(let [potential-fn (literal-function 'U)
      L     (L-central-polar 'm potential-fn)
      state (up (literal-function 'r)
                (literal-function 'theta))]
  (render
   (((Lagrange-equations L) state) 't)))
;;=> "down(- m r(t) (Dθ(t))² + m D²r(t) + DU(r(t)), m (r(t))² D²θ(t) + 2 m r(t) Dr(t) Dθ(t))"

There is so much more! This is a dense library, and lots of documentation remains to be written. Some suggested next steps, for now:

• Open up the live, interactive Emmy tutorial on Nextjournal, play with the examples above and start to explore on your own.
• Read the [Emmy Reference Manual][refman-url] ("refman") for inspiration. All of the code snippets in the refman will work in the Nextjournal environment. Use the two together.
• Visit our [CLJDocs][cljdoc-url] page for an introduction and detailed documentation
• Watch Colin's ["Physics in Clojure"][physics-in-clj-talk-url] talk for an overview of Emmy and its implementation
• Watch Sam's ["Emmy: Moldable Physics and Lispy Microworlds"][emmy-talk-url] talk for the motivation behind the visual extensions to Emmy
• Visit the HTML version of Structure and Interpretation of Classical Mechanics. Many of the SICM exercises have been worked using Emmy; they live at this Nextjournal page.

Clerk Support

If you want to use Emmy with [Clerk][clerk-url], check out the [emmy/clerk template][emmy-clerk-template-url]. This [deps-new][deps-new-url] template will generate a Clerk project for you, fully configured to use Emmy in your Clerk notebooks.

Interactive Documentation via Clerk

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

• node.js
• The Clojure command line tool
• Babashka

Next, clone the repository:

git clone git@github.com:mentat-collective/emmy.git
cd emmy

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 documentation notebook. Any edits you make to dev/emmy/notebook.clj will be picked up and displayed in the browser on save.

Background

[SICM][sicm-book-url] and [FDG][fdg-book-url] can be thought of as spiritual successors to [The Structure and Interpretation of Computer Programs][sicp-book-url], a very influential text—as I can attest, since carefully reading this book in my 30s changed my life as a programmer. To see the same techniques applied to differential geometry and physics is an irresistible lure.

Scmutils is an excellent system, but it is written in an older variant of LISP (Scheme) and is tied to a particular implementation of Scheme—MIT/GNU Scheme. (There is a [port to Guile][gscm-url], but due to the fact that Guile does not support MIT Scheme's apply hooks some glue code is required to run examples from the book in that environment.)

Having the system in Clojure offers a number of advantages. It is not necessary to obtain or prepare a MIT/GNU Scheme executable to execute: only a Java runtime is required. It does not require the X Window System for graphics, as MIT Scheme does. All of the standard tooling for Java and Clojure become available, and this is a lot compared to what we get with MIT/GNU scheme. Clojure support is now extensive in any number of editors and IDEs. Even better, you can interact with the system in the context of a Jupyter notebook.

You can invoke the system from within Java or JavaScript code or use any Java or JS packages you like together with the mathematics system. It's my hope that continuing this project will extend the reach of SICM and FDG by allowing experimentation and collaboration with them in modern environments.

Citing Emmy

To cite this repository, see the "Cite this Repository" link on the top right of the Github page. Citation information is generated from CITATION.cff.

Here is the generated BibTeX entry:

@software{Ritchie_Emmy_Functional_Computer_2016},
author = {Ritchie, Sam and Smith, Colin},
license = {GPL-3.0},
month