Skip to main content

Mathterpiece

A language for math you can touch.

Website · Docs · Specification · Quickstart

Mathterpiece (mtp) is a small language for math figures that readers can drag, slide and play. You describe a figure in a .mtp file, in a Lisp-like syntax: its variables and their ranges, its shapes, and how each one depends on the others. The compiler checks it and writes a .mtpc file, which a JavaScript runtime draws on any web page.

The source of a figure next to the figure it draws: a spiral of dots, each one turned and scaled from the one before. Moving the sliders changes how many dots there are, how far each one turns and how much each one shrinks.

The compiler checks the types and the ranges. A figure that could draw something undefined, such as a circle with a negative radius, does not compile.

Why a language

  • Every figure gets touch, keyboard use, light and dark mode, reduced motion, and labels for screen readers, so you do not build them again for each figure.
  • Every figure uses the same sliders, buttons and gestures, so readers learn them once. A page can restyle them with CSS.
  • The source of a figure is a few dozen lines with the mathematics in them, short enough to review and to compare between versions.
  • A figure is saved as data (the .mtpc file), separate from the runtime that draws it. When the runtime improves, every published figure gets the improvement, and the file keeps working when browsers change.

Install

You need Python 3.13 or later with uv, and, for the web runtime, Node with pnpm. just runs the common tasks.

uv sync
cd web && pnpm install

Try the examples

just web-dev

This builds every example in examples/ and serves a page that draws any of them. Vite prints the address to open.

Build a world model

uv run mtp build dial.mtp              # writes build_dial/: the .mtpc and the inventory page
uv run mtp serve dial.mtp              # serves that page, building again on each save
uv run mtp compile dial.mtp            # writes dial.mtpc next to it
uv run mtp compile dial.mtp -o out.mtpc
uv run mtp check dial.mtp              # reports the first error, writes nothing
uv run mtp parse dial.mtp              # prints the forms the parser reads
uv run mtp fmt dial.mtp                # indents the file as the Emacs mode does

mtp build also writes an inventory page that shows every component of the figure live, next to the line of HTML that places it on a page. mtp build and mtp serve need Node and pnpm, because they build the runtime too.

Put a live figure on a page

Build the runtime with just build-web, which writes web/dist/mathterpiece.js. A page loads it and places the world model's components anywhere in its text. The inventory page mtp build writes lists every component with the line that places it:

<script type="module" src="mathterpiece.js"></script>

<mtp-model id="dial" src="dial.mtpc"></mtp-model>
<p>Drag the slider <mtp-slider model="dial" name="radius"></mtp-slider>
   and watch the <mtp-readout model="dial" name="area"></mtp-readout>.</p>
<mtp-canvas model="dial" name="v"></mtp-canvas>

<mtp-model> can also read the compiled model from a JSON block anywhere in the page, as in <mtp-model id="dial" src="#dial-data"> with <script type="application/json" id="dial-data">, so the page needs no second file. The same lines work in a Markdown file. The data model ("On the page") describes the page's elements, how the author writes them in Markdown, and how a page restyles a world model's components with CSS.

Develop

just web-dev     # build the examples and serve a page that shows any of them
just test        # the compiler's tests
just web-test    # the runtime's tests
just check       # lint, type checks and both test suites

Layout

  • mathterpiece/: the compiler (parse.py, compiler.py, mtpc.py) and the mtp command.
  • web/src/: the runtime, which plays a .mtpc and defines the page's elements.
  • docs/: the language and the file format, and docs/figure-guidelines.md, the rules every figure here follows (phones and touch first).
  • examples/: one figure per feature to read and try, plus the interactive figures from the Bourgain notes (bourgain-*.mtp). house.mtp is not a figure: it holds the colors and fonts that the other examples import.
  • tests/: the compiler's tests; tests/shared/ holds cases both the compiler and the runtime check.
  • web/test/: the runtime's tests.
  • editors/mtp-mode.el: an Emacs mode for .mtp files.

Docs

License

MIT. See LICENSE.

Metadata

Release files for mathterpiece 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mathterpiece 0.1.0
File Size Uploaded Provenance Actions
mathterpiece-0.1.0.tar.gz 797.2 kB Without provenance Details for mathterpiece-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mathterpiece 0.1.0
File Interpreter ABI Platform Actions
mathterpiece-0.1.0-py3-none-any.whl Python 3 none any Details for mathterpiece-0.1.0-py3-none-any.whl

Total release size: 1.6 MB

Release files / mathterpiece-0.1.0.tar.gz

Download URL mathterpiece-0.1.0.tar.gz
Size 797.2 kB
Tags Source
SHA-256 checksum
How to use checksums
201b96e333e874c337d9eb5dc511f486264ef8151d3a82f20c8c6cce31897e1e
BLAKE2b-256 checksum
How to use checksums
37564688e80a5ea6c334aab34e89b93b12db83c37710ae87c613dce7fea37437
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / mathterpiece-0.1.0-py3-none-any.whl

Download URL mathterpiece-0.1.0-py3-none-any.whl
Size 804.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a47d9e44cd6f85a75e606f075b5af391aad9bbb93a70b1278c6a1198e0c48d4
BLAKE2b-256 checksum
How to use checksums
e9404b7e8efd50a7c32f030f0b3bfcc7018ec8abc6c53bf5b7682d62323cfaaa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for mathterpiece 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page