# tikzphysics

`tikzphysics` is a TikZ-native library for drawing classical-physics diagrams in
LaTeX. It adds reusable shapes, styles, keys, and geometric anchors while
keeping the normal TikZ workflow: diagrams are still built with `\node`,
`\draw`, `\path`, and `\tikzset`.

Version: **1.1.0 (2026-08-15)**

## Included modules

- `tikzphysics.surface`: single-polygon, sharply mitered bent platforms; wedges, ground, ceilings,
  and walls.
- `tikzphysics.ramps`: continuous wall--floor--incline ramps and filled circular
  ramps, with surface, tangent, and normal anchors.
- `tikzphysics.mechanics`: configurable blocks, spring nodes, and pulleys, plus strings that
  compute exact pulley tangencies and circular contact arcs.
- `tikzphysics.optics`: concave and convex mirrors, biconvex and biconcave lenses, slabs,
  and prisms with named and parametric optical-surface anchors.
- `tikzphysics.core`: unit-aware dimensions, parametric anchors, and debug tools.

Object-specific controls use concise names where they read naturally, for
example `wedge height`, `mirror radius`, and `prism apex angle`. Longer
collision-safe forms begin with `physics`, such as `physics mirror radius` and
`physics strip width`.
Ordinary node sizing uses the familiar TikZ keys `minimum width`,
`minimum height`, and `minimum size`; unit-aware `physics ...` aliases remain
available when convenient.

The primary node styles are intentionally concise:

| Short style | Collision-safe style | Object |
| --- | --- | --- |
| `platform` | `physicsplatform-both` | Platform with independently configurable left and right walls |
| `platform-left`, `platform-right`, `platform-both` | `physicsplatform-left`, `physicsplatform-right`, `physicsplatform-both` | Explicit bent-platform variants |
| `wedge` | `physicswedge` | Inclined plane |
| `ramp`, `ramp-left` | `physicsramp` | Continuous wall--floor--linear-incline body |
| `curved-ramp`, `curved-ramp-left` | `physicscurvedramp` | Circular contact ramp with a filled body |
| `ground`, `ceiling` | `physicsground`, `physicsceiling` | Horizontal contact strips |
| `wall-left`, `wall-right` | `physicswall-left`, `physicswall-right` | Vertical contact strips |
| `block`, `spring`, `pulley` | `physicsblock`, `physicsspring`, `physicspulley` | Mechanics objects |
| `concave-mirror`, `convex-mirror` | `physicsconcavemirror`, `physicsconvexmirror` | Curved reflecting surfaces |
| `convex-lens` | `physicsconvexlens` | Symmetric biconvex lens |
| `concave-lens` | `physicsconcavelens` | Symmetric biconcave lens |
| `slab` | `physicsslab` | Unfilled parallel-sided rectangular slab |
| `prism` | `physicsprism` | Unfilled isosceles triangular prism |

TikZ style names are global. If another package or the surrounding document
already defines a generic name such as `block`, use the corresponding
`physics...` form.

Bent-wall directions are continuous. The only excluded directions are a left
wall at 0 degrees and a right wall at 180 degrees (modulo 360), because those
fold directly back over the floor and have no finite miter.

## Requirements

- LaTeX2e
- PGF/TikZ, including the standard `calc`, `patterns`, `angles`, and
  `decorations.pathmorphing` libraries

No shell escape, external program, special font, or platform-specific runtime
is required when using the package.

## Installation

After publication, install `tikzphysics` through TeX Live or MiKTeX. For a manual
installation, copy these files into a directory searched by TeX:

- `tikzphysics.sty`
- `tikzlibrarytikzphysics.code.tex`
- `tikzlibrarytikzphysics.core.code.tex`
- `tikzlibrarytikzphysics.surface.code.tex`
- `tikzlibrarytikzphysics.ramps.code.tex`
- `tikzlibrarytikzphysics.mechanics.code.tex`
- `tikzlibrarytikzphysics.optics.code.tex`

For a private TeX tree, a suitable location is
`tex/latex/tikzphysics/`; refresh the filename database afterward if your TeX
distribution requires it.

## Quick start

Load all modules:

```latex
\usepackage{tikzphysics}
```

Or load only the modules needed by a document:

```latex
\usepackage{tikz}
\usetikzlibrary{tikzphysics.ramps, tikzphysics.mechanics}
```

The following is a complete document. Copy it into a new Overleaf project with
the package installed or with the standalone `tikzphysics.sty` bundle beside
the main file:

```latex
\documentclass[tikz, border=6mm]{standalone}
\usepackage{tikzphysics}

\begin{document}
\begin{tikzpicture}
  \node[platform, minimum width=5cm, minimum height=2cm]
    (platform) at (0,0) {};

  \node[pulley, minimum size=8mm]
    (pulley) at (platform.north east) {};
\end{tikzpicture}
\end{document}
```

Native and convenience sizing can be used side by side:

| Shape/property | Native TikZ (preferred) | Package convenience |
| --- | --- | --- |
| Block width/height | `minimum width`, `minimum height` | `physics block width`, `physics block height` |
| Spring length | `minimum width` | — |
| Pulley diameter | `minimum size` | `physics pulley diameter` |
| Platform width/depth | `minimum width`, `minimum height` | `physics platform width`, `physics platform depth` |
| Ground or ceiling width/depth | `minimum width`, `minimum height` | `physics ground ...`, `physics ceiling ...` |
| Wall thickness/height | `minimum width`, `minimum height` | `physics wall thickness`, `physics wall height` |
| Wedge width | `minimum width` | `wedge width` |
| Straight-ramp width | `minimum width` | — |
| Slab width/height | `minimum width`, `minimum height` | `slab width`, `slab height` |
| Prism width/height | `minimum width`, `minimum height` | `prism width`, `prism height` |

Put the shape style first and the sizing keys after it. If both forms are
present, the last value wins. `wedge height` is deliberately not
replaced by `minimum height`: it selects the wedge's geometry when no angle is
given.

The wedge keys also have collision-safe forms:

| Concise key | Collision-safe alias |
| --- | --- |
| `wedge width` | `physics wedge width` |
| `wedge height` | `physics wedge height` |
| `wedge angle` | `physics wedge angle` |
| `wedge right angle at` | `physics wedge right angle at` |

Shape-specific controls such as wall angle, strip width, axle styling, and
optical geometry use the names documented for their shapes; collision-safe
`physics ...` aliases are available where listed.

## Spring nodes

`spring` is a rotatable node with exact attachment anchors, so it composes like
`block` and `pulley` instead of being an anonymous decorated line:

```latex
\node[spring, minimum width=4cm,
      pre length=5pt, post length=5pt,
      amplitude=4.5pt, segment length=4.5pt,
      aspect=0.5] (S) at (0,0) {};
\draw (wall) -- (S.start);
\draw (S.end) -- (block.west);
\node[above] at (S.coil-mid) {$k$};
```

The anchors are `start`, `end`, `coil-start`, `coil-mid`, and `coil-end`, plus
the standard compass anchors. Native TikZ keys control total length and line
appearance: `minimum width`, `draw`, `line width`, and `rotate`. The collision-safe
coil-key names are `pre length`, `post length`, `amplitude`, `segment length`,
and `aspect`; collision-safe aliases begin with `physics spring ...`.

## Rare ramp geometries

The ramp objects are true node shapes and each body is one closed path. The
straight `ramp` has a vertical wall, a horizontal floor, and a linear incline
with a sharp floor-to-incline corner. `minimum width` controls its overall
horizontal width; `ramp run`, `ramp angle` or `ramp rise`, `ramp wall height`,
`ramp wall width`, and `ramp depth` control the remaining geometry.
After naming the node, `\physicsrampangle{R}{$30^\circ$}` draws the dashed
reference ray, acute angle arc, and label at that sharp corner.

The `curved-ramp` contact surface begins with a horizontal floor and joins its
circular arc with the same horizontal tangent. Its default floor extends 2cm
left of the arc foot; set `curved ramp floor length` to change it. A 90-degree
sweep ends with a vertical tangent. Use `curved ramp radius`, `curved ramp angle`, and
`curved ramp back extension`. Both shapes accept `ramp direction=left` or
`right`; the left-facing convenience styles are `ramp-left` and
`curved-ramp-left`.

Both ramps provide `surface-0` through `surface-100` and the shorthand `.0`
through `.100` over the complete contact surface. Curved ramps additionally
provide `curve-0..100`, `curve-tangent-before/after-T`, and `curve-normal-T`
for the circular portion alone. This places a block on the arc at its exact tangent:

```latex
\node[curved-ramp, curved ramp radius=4cm] (R) at (0,0) {};
\path (R.curve-tangent-before-60) -- (R.curve-tangent-after-60)
  node[midway,sloped,block,anchor=south] {$m$};
\draw[->] (R.curve-60) -- (R.curve-normal-60) node[above] {$N$};
```

For a block-pulley system, use
`\physicsstringoverpulley{B.east}{P}{H.north}`. It computes both tangent contact
points and the circular wrap around pulley node `P`; the string does not rely
on approximate compass anchors. The default `physics string route=surface-right`
is intended for a block on a horizontal or rising surface with the mass
hanging on the pulley's right. The approaching string remains parallel to the
surface and passes over the upper pulley rim. The optional argument also
accepts `over`, `under`, and `shortest`, or the individual tangent-solution and
wrap keys.

A complete optics composition:

```latex
\begin{tikzpicture}
  \node[convex-lens, convex lens radius=3cm,
        convex lens thickness=0.2cm,
        convex lens aperture angle=25] (L) at (0,0) {};
  % Snell-law values for n(lens)/n(air)=1.50 and this fixed geometry.
  \coordinate (Lexit) at ($(L.center)+(0.29194,0.72588)$);
  \coordinate (Lf) at ($(L.center)+(2.93841,0)$);
  \node[slab, minimum width=1.2cm, minimum height=3cm]
    (S) at (5,0) {};
  \node[prism, prism width=3cm, prism apex angle=60]
    (P) at (10,0) {};

  \draw[red,->] ($(L.80)+(-3,0)$) -- (L.80) -- (Lexit) -- (Lf);
  \draw[red,->] (3.2,-0.8) -- (S.30) -- (S.back-65) -- (7,0.8);
  \draw[red,->] (8,-0.4) -- (P.50) -- (P.right-65) -- (12,0.8);
\end{tikzpicture}
```

The non-axial lens ray changes direction at both interfaces. The package
provides the geometry and anchors but does not automatically solve Snell's
law; if the lens keys or refractive indices change, recompute the exit and
focal coordinates.

For `prism`, an explicitly supplied `prism apex angle` derives the height and
takes precedence over `minimum height` or `prism height`.

Optical nodes also provide shorthand numeric anchors from `.0` to `.100`.
For mirrors they mean `surface-T`; for both lens types and slabs they mean
`front-T`; for prisms they mean `left-T`. For example, `(L.50)` is the middle
of a lens's front surface and `(L.80)` is near its upper edge.

Bare dimension values are interpreted as centimetres; explicit TeX units such
as `8mm`, `12pt`, and `1in` are preserved by package convenience keys. Native
TikZ sizing keys should be given explicit units.

## Documentation and examples

The complete user manual is `tikzphysics.pdf`, built from `tikzphysics.tex`.
Standalone source examples are provided in `examples/`, including complete
bent-platform configuration and key-variant galleries. Start with
`examples/short-names-platform-pulley.tex` for the smallest complete document.
Use `examples/short-names-wedge-variants.tex` for complete angle-, height-,
width-, and right-angle-mode examples.
Use `examples/optics-components.tex` for the complete optics gallery and
`examples/optics-ray-composition.tex` for named and numeric surface anchors in
ray paths. `examples/optics-complete-ray-diagrams.tex` contains complete
converging and diverging diagrams for both lenses and mirrors.
The ramp examples are `ramp-straight-system.tex`, `ramp-curved-system.tex`,
and `ramps-gallery.tex`.
The pulley examples include horizontal-plane, inclined-plane, bent-platform,
two-hanging-mass, and six string-routing arrangements. A terminal quick reference is available
through:

```sh
./tikzphysics-help
./tikzphysics-help platform
```

## Development

The package uses `l3build` for regression testing and release packaging:

```sh
l3build check
l3build doc
l3build ctan
```

The regression suite checks fixed platform corners, wall extents, straight and
circular ramp endpoints, tangent/normal guides, mirror and lens arc endpoints, shorthand optical anchors,
slab and prism surface
endpoints, and unit-aware sizing.

## License

Copyright (C) 2026 Vaibhav Blayer.

This material is subject to the LaTeX Project Public License version 1.3c or
later. The work has LPPL maintenance status `maintained`; the Current
Maintainer is Vaibhav Blayer. See `LICENSE` for details.