# penrose/penrose

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/penrose-penrose).**

7,949 stars · 357 forks · TypeScript · MIT

## Links

- GitHub: https://github.com/penrose/penrose
- Homepage: https://penrose.cs.cmu.edu
- awesome-repositories: https://awesome-repositories.com/repository/penrose-penrose.md

## Topics

`diagrams` `domain-specific-language` `mathematics` `programming-language` `visualization`

## Description

Penrose is a compiler that transforms structured mathematical notation into optimized SVG diagrams. It uses a three-stage pipeline of separate domain, substance, and style files to define mathematical objects, relationships, and visual presentation, then solves continuous optimization problems with user-defined spatial constraints and objectives to automatically arrange diagram elements.

The system separates diagram content from visual style using distinct declarative languages, and provides a typed domain language with subtype hierarchies for mathematical objects. It supports embedding compiled diagrams in React and SolidJS applications with real-time optimization and drag-based manipulation, and offers incremental optimization stepping for interactive diagram tuning. The project installs as an NPM package with native TypeScript type definitions and integrates with modern JavaScript bundlers.

Penrose generates diagrams from plain-text notation, supports browser-based diagramming without local installation, and can package diagram source files into standalone web applications. It provides built-in literal types, arithmetic operations, color specification, and collection-based variable matching for aggregate operations across diagram elements.

## Tags

### Part of an Awesome List

- [Mathematical Notation Diagramming](https://awesome-repositories.com/f/awesome-lists/devtools/visualization-and-diagrams/mathematical-notation-diagramming.md) — Creates mathematical diagrams by compiling plain-text Domain, Substance, and Style programs. ([source](https://cdn.jsdelivr.net/gh/penrose/penrose@main/README.md))
- [Diagram Embedding Components](https://awesome-repositories.com/f/awesome-lists/devtools/react-components/diagram-embedding-components.md) — Ships a pre-built React component that renders mathematical diagrams by accepting source files. ([source](https://penrose.cs.cmu.edu/docs/ref/react))
- [Declarative Content Specifications](https://awesome-repositories.com/f/awesome-lists/devtools/visualization-and-diagrams/entity-relationship-diagram-editors/declarative-content-specifications.md) — Defines the objects and relationships that appear in a diagram using domain-specific predicates and functions. ([source](https://penrose.cs.cmu.edu/docs/ref))
- [Substance Object Collections](https://awesome-repositories.com/f/awesome-lists/devtools/pattern-matching/variable-length-segment-matching/substance-object-collections.md) — Groups multiple Substance objects into named collections for aggregate operations across diagram elements.
- [Browser-Based Diagramming Tools](https://awesome-repositories.com/f/awesome-lists/devtools/visualization-and-diagrams/browser-based-diagramming-tools.md) — Runs the diagramming system directly in a web browser without requiring any local installation or setup. ([source](https://cdn.jsdelivr.net/gh/penrose/penrose@main/README.md))

### Data & Databases

- [Structured Notation Compilers](https://awesome-repositories.com/f/data-databases/data-analysis-visualization/visualization-frameworks-libraries/svg-diagramming-libraries/svg-primitive-converters/natural-language-diagram-compilers/structured-notation-compilers.md) — Transforms structured mathematical notation into optimized SVG diagrams through a three-stage pipeline of domain, substance, and style files.
- [Optimized Scalar Placeholders](https://awesome-repositories.com/f/data-databases/data-type-definitions/scalar-types/custom-scalars/scalar-value-generation/optimized-scalar-placeholders.md) — Assigns placeholders that the engine initializes randomly and optimizes to suitable values for diagram layout. ([source](https://penrose.cs.cmu.edu/docs/ref/style/expressions))

### Software Engineering & Architecture

- [Declarative Visualization DSLs](https://awesome-repositories.com/f/software-engineering-architecture/integration-extensibility/extensibility/plugin-architectures/domain-specific/declarative-visualization-dsls.md) — Defines custom mathematical domains and visual styles through separate declarative DSL files.
- [Mathematical Predicate Declarations](https://awesome-repositories.com/f/software-engineering-architecture/boolean-predicates/type-predicate-injections/mathematical-predicate-declarations.md) — Defines named predicates with typed arguments to represent mathematical or logical statements about diagram objects. ([source](https://penrose.cs.cmu.edu/docs/ref/domain/predicates))
- [Instance Specifications](https://awesome-repositories.com/f/software-engineering-architecture/diagram-notation-legends/instance-specifications.md) — Lists the specific instances of objects to include in a diagram using a dedicated notation file. ([source](https://penrose.cs.cmu.edu/docs/tutorial/welcome))
- [Optimization Problem Solvers](https://awesome-repositories.com/f/software-engineering-architecture/dynamic-programming/optimization-problem-solvers.md) — Sets up a problem with constraints and an objective, then runs the optimizer until convergence or a stopping condition is met. ([source](https://penrose.cs.cmu.edu/docs/ref/optimization-api))
- [Layout Constraints](https://awesome-repositories.com/f/software-engineering-architecture/layout-constraints.md) — Defines spatial relationships as optimization constraints and objectives that the solver minimizes to produce a diagram layout.
- [Spatial Objective Functions](https://awesome-repositories.com/f/software-engineering-architecture/performance-reliability/performance-optimization/graphql-performance-optimizers/optimization-objectives/spatial-objective-functions.md) — Defines continuous objective functions encoding spatial relationships for diagram optimization. ([source](https://penrose.cs.cmu.edu/docs/ref/constraints))
- [Domain-Specific](https://awesome-repositories.com/f/software-engineering-architecture/schema-based-type-systems/type-hierarchies/domain-specific.md) — Provides a typed domain language with subtype hierarchies and built-in literal types for mathematical objects.
- [Subtype Hierarchies](https://awesome-repositories.com/f/software-engineering-architecture/schema-based-type-systems/type-hierarchies/subtype-hierarchies.md) — Declares 'is-a' relationships between types so subtype objects are accepted wherever parent types are expected. ([source](https://penrose.cs.cmu.edu/docs/ref/domain/types))
- [TypeScript Type Definitions](https://awesome-repositories.com/f/software-engineering-architecture/typescript-type-definitions.md) — Provides native TypeScript type definitions and React component support for type-safe diagram development. ([source](https://penrose.cs.cmu.edu/docs/bloom/tutorial/getting_started))

### Content Management & Publishing

- [Diagrammatic Notation Renderers](https://awesome-repositories.com/f/content-management-publishing/markdown-renderers/mathematical-notation-renderers/diagrammatic-notation-renderers.md) — Generates diagrams from plain-text mathematical notation using a domain-specific language. ([source](https://penrose.cs.cmu.edu/))

### Development Tools & Productivity

- [Mathematical Domain Definitions](https://awesome-repositories.com/f/development-tools-productivity/configuration-generators/configuration-file-generators/diagram-definition-generators/mathematical-domain-definitions.md) — Describes the types of objects, predicates, and functions that can appear in a diagram for a specific subject area. ([source](https://penrose.cs.cmu.edu/docs/ref))
- [Mathematical Notation Compilers](https://awesome-repositories.com/f/development-tools-productivity/diagramming-tools/visual-diagram-editors/ai-driven-diagramming/data-driven-diagram-generators/uml-diagram-generators/mathematical-notation-compilers.md) — Generates mathematical diagrams from plain-text notation using a domain-specific language.
- [TypeScript Diagram Authoring](https://awesome-repositories.com/f/development-tools-productivity/type-safe-diagram-editors/typescript-diagram-authoring.md) — Provides native TypeScript definitions and React components for type-safe diagram development.

### Graphics & Multimedia

- [Diagram Layout Algorithms](https://awesome-repositories.com/f/graphics-multimedia/diagram-layout-algorithms.md) — Runs the full layout optimization on a compiled diagram state to produce a final arrangement. ([source](https://penrose.cs.cmu.edu/docs/ref/api))
- [Framework-Specific Embeddings](https://awesome-repositories.com/f/graphics-multimedia/visualization-mapping/visualization-frameworks/interactive-diagramming-libraries/framework-specific-embeddings.md) — Ships pre-built React and SolidJS components for embedding interactive mathematical diagrams in web applications.
- [Hot-Reload Diagram Editors](https://awesome-repositories.com/f/graphics-multimedia/visualization-mapping/interactive-diagramming-engines/hot-reload-diagram-editors.md) — Supports interactive diagram development with hot-reload and browser-based testing.
- [Interactive Diagramming Libraries](https://awesome-repositories.com/f/graphics-multimedia/visualization-mapping/visualization-frameworks/interactive-diagramming-libraries.md) — Creates optimization-driven interactive diagrams in JavaScript using a domain-specific language for mathematical visualizations. ([source](https://penrose.cs.cmu.edu/docs/bloom/tutorial/getting_started))

### Programming Languages & Runtimes

- [Domain Specific Languages](https://awesome-repositories.com/f/programming-languages-runtimes/domain-specific-languages.md) — Compiles separate domain, substance, and style DSL files into an intermediate representation for diagram generation.
- [Mathematical Domain Languages](https://awesome-repositories.com/f/programming-languages-runtimes/domain-specific-languages/mathematical-domain-languages.md) — Defines the types, objects, and operations within a mathematical field using a dedicated domain-specific language. ([source](https://penrose.cs.cmu.edu/docs/tutorial/welcome))
- [Diagram DSLs](https://awesome-repositories.com/f/programming-languages-runtimes/programming-language-varieties/domain-specific-languages/diagram-dsls.md) — Provides a declarative DSL to define mathematical objects, relationships, and visual styles.
- [Diagram](https://awesome-repositories.com/f/programming-languages-runtimes/user-defined-types/object-types/diagram.md) — Defines the kinds of objects that can appear in a diagram, establishing the vocabulary for the visual domain. ([source](https://penrose.cs.cmu.edu/docs/ref/domain/overview))
- [Typed Function Declarations](https://awesome-repositories.com/f/programming-languages-runtimes/function-definitions/recursive-type-definitions/typed-function-declarations.md) — Declares functions with typed inputs and outputs that diagram schemas can reference. ([source](https://penrose.cs.cmu.edu/docs/ref/domain/functions))
- [Typed Constructors](https://awesome-repositories.com/f/programming-languages-runtimes/primary-constructors/type-constructor-applications/typed-constructors.md) — Declares constructors that create objects of specified types for diagram generation. ([source](https://penrose.cs.cmu.edu/docs/ref/domain/functions))
- [Literal Type Definitions](https://awesome-repositories.com/f/programming-languages-runtimes/string-literal-type-manipulations/string-literal-union-type-definitions/literal-type-definitions.md) — Provides String and Number as predeclared types that can be inferred from literal expressions and used as arguments to predicates and functions. ([source](https://penrose.cs.cmu.edu/docs/ref/domain/types))

### Scientific & Mathematical Computing

- [Numerical Parameter Optimization](https://awesome-repositories.com/f/scientific-mathematical-computing/numerical-parameter-optimization.md) — Minimizes a continuous objective function with constraints to automatically position diagram elements.
- [Repulsion Penalty Functions](https://awesome-repositories.com/f/scientific-mathematical-computing/shape-placement-optimization/repulsion-penalty-functions.md) — Implements repulsion penalties that grow as diagram shapes get closer together. ([source](https://penrose.cs.cmu.edu/docs/ref/constraints))
- [Optimization Variable Declarations](https://awesome-repositories.com/f/scientific-mathematical-computing/numerical-mathematical-foundations/statistics-probability/random-variables/variable-initializers/optimization-variable-declarations.md) — Declares a numeric variable with an initial value that the optimizer can adjust during the solving process. ([source](https://penrose.cs.cmu.edu/docs/ref/optimization-api))

### User Interface & Experience

- [Geometric Containment Constraints](https://awesome-repositories.com/f/user-interface-experience/constraint-layout-engines/constraint-priority-assignment/constraint-definitions/geometric-containment-constraints.md) — Defines geometric containment relationships as optimization constraints for diagram layout. ([source](https://penrose.cs.cmu.edu/docs/ref/constraints))
- [Continuous Optimization Layout Engines](https://awesome-repositories.com/f/user-interface-experience/constraint-layout-engines/continuous-optimization-layout-engines.md) — Arranges diagram elements by solving continuous optimization problems with spatial constraints.
- [Content-Style Separation Languages](https://awesome-repositories.com/f/user-interface-experience/styling-theming-systems/content-styling/component-styling-tools/component-styling/style-encapsulations/visual-structural-separations/content-style-separation-languages.md) — Separates diagram content from visual presentation using distinct declarative languages.
- [Diagram Element Styling](https://awesome-repositories.com/f/user-interface-experience/visual-styling-rules/diagram-element-styling.md) — Defines how domain objects and relationships are visually displayed in the generated diagram. ([source](https://penrose.cs.cmu.edu/docs/ref))
- [Constrained Shape Draggers](https://awesome-repositories.com/f/user-interface-experience/form-and-input-management/interaction-and-event-handling/drag-operation-controls/drag-handles/drag-direction-restrictions/constrained-shape-draggers.md) — Enables drag-based translation and scaling of diagram shapes with movement constraints. ([source](https://penrose.cs.cmu.edu/docs/ref/Interactivity))

### Web Development

- [Relationship Declarations](https://awesome-repositories.com/f/web-development/declarative-diagramming-frameworks/relationship-declarations.md) — Specifies relationships between object types, like subset or disjoint, that the diagram can illustrate between objects. ([source](https://penrose.cs.cmu.edu/docs/ref/domain/overview))
- [Text-to-Diagram Compilers](https://awesome-repositories.com/f/web-development/markup-compilers/text-to-diagram-compilers.md) — Compiles structured notation into optimized SVG diagrams through a three-stage pipeline. ([source](https://penrose.cs.cmu.edu/docs/ref/api))
- [Multi-File Diagram Compilers](https://awesome-repositories.com/f/web-development/markup-compilers/text-to-diagram-compilers/multi-file-diagram-compilers.md) — Accepts a trio of domain, substance, and style programs and returns a compiled state ready for layout. ([source](https://penrose.cs.cmu.edu/docs/ref/api))
- [SVG Renderers](https://awesome-repositories.com/f/web-development/server-side-rendering/svg-renderers.md) — Converts optimized diagram state into SVG elements for web-based display and interaction.
- [Live SVG DOM Renderers](https://awesome-repositories.com/f/web-development/server-side-rendering/svg-renderers/live-svg-dom-renderers.md) — Converts compiled diagram state into live SVG DOM elements for web page display. ([source](https://penrose.cs.cmu.edu/docs/ref/api))