# Penrose — Create Beautiful Diagrams by Typing Math Notation

> A system that automatically generates diagrams from plain-text mathematical notation using optimization-based layout.

## Install

Save in your project root:

# Penrose — Create Beautiful Diagrams by Typing Math Notation

## Quick Use
```bash
npm install @penrose/core @penrose/roger
npx roger watch my-diagram/
# Or use the online editor at penrose.cs.cmu.edu/try
```

## Introduction
Penrose is a research-driven system from Carnegie Mellon University that turns plain-text mathematical notation into publication-quality diagrams. You describe what you mean in a domain-specific language, and Penrose finds an aesthetically pleasing layout automatically.

## What Penrose Does
- Generates 2D diagrams from three plain-text input files (domain, substance, style)
- Uses numerical optimization to find visually appealing element placement
- Supports set theory, linear algebra, geometry, and other mathematical domains
- Exports diagrams as SVG for use in papers and presentations
- Provides a live editor with instant preview for iterative design

## Architecture Overview
Penrose separates domain knowledge, concrete instances, and visual style into three files. The compiler parses these into a constraint system, and a numerical optimizer (gradient descent) adjusts element positions and sizes to satisfy all constraints while minimizing an energy function that encodes aesthetic preferences.

## Self-Hosting & Configuration
- Install the CLI tool (roger) via npm for local compilation
- Use the web-based editor at penrose.cs.cmu.edu for quick experiments
- Define custom domains by writing .domain, .substance, and .style files
- Style files control colors, shapes, labels, and layout constraints
- Output SVGs can be embedded in LaTeX, HTML, or Markdown documents

## Key Features
- Declarative: describe relationships, not coordinates
- Optimization-based layout produces consistent, balanced results
- Extensible domain system for custom mathematical fields
- Interactive editor with real-time diagram preview
- Publication-ready SVG output with proper label rendering

## Comparison with Similar Tools
- **TikZ/PGF** — manual coordinate placement in LaTeX; Penrose auto-layouts
- **Mermaid** — flowcharts and sequence diagrams; Penrose targets mathematical diagrams
- **D2** — general software diagrams; Penrose specializes in math and set theory
- **Manim** — animated math videos; Penrose produces static publication diagrams
- **draw.io** — GUI-based drag-and-drop; Penrose is text-first and deterministic

## FAQ
**Q: Do I need to know programming to use Penrose?**
A: Basic familiarity with text files helps, but the DSL is designed for mathematicians, not programmers.

**Q: Can I use Penrose in LaTeX papers?**
A: Yes. Export SVGs and include them with standard LaTeX graphics packages.

**Q: What mathematical domains are supported out of the box?**
A: Set theory, linear algebra, graph theory, and geometry ship as built-in domains.

**Q: Is Penrose production-ready?**
A: It is an active research project. The core system works well, though some advanced features are evolving.

## Sources
- https://github.com/penrose/penrose
- https://penrose.cs.cmu.edu/

---
Source: https://tokrepo.com/en/workflows/asset-ac4874ec
Author: AI Open Source