SICMUtils

A Clojure(script) implementation of the Scmutils system for math and physics investigations in the Clojure and Clojurescript languages. SICMUtils 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 and Functional Differential Geometry by G.J. Sussman and J. Wisdom.

👋 Need help getting started? Say hi on Twitter or Clojurians Slack in #sicmutils.

Quickstart

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

Install SICMUtils into your Clojure(script) project using the instructions at its Clojars page:

Initialize the sicmutils.env "Batteries Included" environment at the REPL:

(require '[sicmutils.env :as env])
(env/bootstrap-repl!)

Alternatively, visit the SICMUtils Tutorial on Nextjournal to try all of the examples below in your browser with no setup required:

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)
;;=> #sicm/complex "-1.5707963268 + 2.9932228461i"

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))

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

SICMUtils is based on the engine behind The Structure and Interpretation of Classical Mechanics, 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 SICMUtils tutorial on Nextjournal, play with the examples above and start to explore on your own.
• Read the SICMUtils Reference Manual ("refman") for inspiration. All of the code snippets in the refman will work in the Nextjournal environment. Use the two together.
• Visit our CLJDocs page for an introduction and detailed documentation
• Watch Colin's "Physics in Clojure" talk for on overview of SICMUtils and its implementation
• Visit the HTML version of Structure and Interpretation of Classical Mechanics. Many of the SICM exercises have been worked using SICMUtils; they live at this Nextjournal page.

Background

SICM and FDG can be thought of as spiritual successors to The Structure and Interpretation of Computer Programs, 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, 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 SICMUtils

To cite this repository:

@software{sicmutils2016github,
  author = {Colin Smith and Sam Ritchie},
  title = {{SICMU}tils: {F}unctional {C}omputer {A}lgebra in {C}lojure},
  url = {http://github.com/sicmutils/sicmutils},
  version = {0.16.0},
  year = {2016},
}

In the above bibtex entry, the version number is intended to be that from project.clj, and the year corresponds to the project's open-source release.

License

GPL v3.

Copyright © 2016 Colin Smith