# tikzphysics

Draw mechanics, contact surfaces, fluid schematics, differential elements, and
optics diagrams using ordinary TikZ nodes, paths, pics, and anchors.
The main names are **`block`, `spring`, `pulley`, and `wedge`**. No special command namespace is needed.

**Version 1.6.0 · 2026-09-27**

## Start here

1. Install the package files in your TeX tree. For Overleaf, upload the generated
   single file `output/overleaf/tikzphysics.sty` beside your document.
2. Load `\usepackage{tikzphysics}`.
3. Compile with pdfLaTeX. The package itself needs neither shell escape nor external programs.

Build or refresh the Overleaf file from the package root with:

```sh
python3 scripts/build_overleaf_bundle.py
```

The normal CTAN installation remains modular; the generated Overleaf copy
inlines the catalog, core, surface, ramps, mechanics, elements, fluids, and
optics modules.

```latex
\documentclass[tikz,border=5mm]{standalone}
\usepackage{tikzphysics}
\begin{document}
\begin{tikzpicture}
  \node[block] (B) at (3,0) {$m$};
  \draw[spring] (0,0) -- node[above] {$k$} (B.west);
\end{tikzpicture}
\end{document}
```

Here `block` chooses an object, `(B)` names it, and `(B.west)` is its left attachment point. `spring` decorates the connection between two coordinates. You can also position a spring as a named node:

```latex
\node[spring,minimum width=3cm,rotate=30] (S) {};
\draw (A) -- (S.start);
\draw (S.end) -- (B.west);
```

Both forms share the same coil settings and `every spring` hook. Nodes also
provide `coil-start`, `coil-end`, `center`, and `axis-0..100` anchors, with
`show anchors` and `show keys` for inspection. `axis-*` follows the straight
spring axis. See the [spring guide](docs/springs.md) and its rendered gallery.

## Choose what to learn

| I want to… | Start with… |
| --- | --- |
| Build a spring–block–pulley system | [Complete example below](#spring-block-and-pulley-on-a-wedge) |
| Find every feature and its keys | [Feature reference](docs/reference.md) |
| See keys and anchors while drawing | [Debug explorer](#explore-inside-tikz) |
| Compare `show anchors` and `show keys` across object types | [Debug overlay guide](docs/debug-overlays.md) and [complete feature tour](examples/debug-feature-tour.tex) |
| Understand dimensions and percentage anchors | [Extended guide](docs/guide.md) |
| Browse rendered diagrams and detailed explanations | [PDF manual](tikzphysics.pdf) |
| Copy a complete document | [Example directory and learning routes](examples/README.md) |

The default block is **1 cm × 1 cm**, and the default pulley diameter is **1 cm**.

## Differential elements

The `tikzphysics.elements` module provides reusable nodes for polar area and
mass elements. It is loaded automatically by `\usepackage{tikzphysics}`:

```latex
\begin{tikzpicture}
  \node[polar element,
    element inner radius=18mm,
    element radial thickness=2mm,
    element start angle=30,
    element delta angle=30,
    show dimensions] (dA) at (0,0) {};
\end{tikzpicture}
```

Use `differential sector` for a zero-inner-radius sector and
`differential ring` for a complete thin annulus. The combined teaching pic
keeps the original circular body, its annular element, centre mark, and opened
strip in one named construction:

```latex
\pic (D) {differential ring diagram={
  element inner radius=1cm,
  element radial thickness=2mm
}};
% Components: (D-ring), (D-strip); body anchors: (D-body-east), etc.
```

Use `unwrapped ring,source element=R` when the strip should be positioned
independently. Its differential approximation has width $2\pi r$, using the
inner reference radius, and height $d\!r$.

The same module includes solid and sheet constructions. Each named pic keeps
the body and highlighted integration element together:

```latex
\pic (S) {sphere shell diagram};   % (S-body), (S-shell)
\pic (C) at (6,0) {cylinder slice diagram}; % (C-body), (C-slice)
\pic (A) at (12,0) {sheet element diagram}; % (A-body), (A-element)
```

Available teaching pics are `sphere shell diagram`, `sphere slice diagram`,
`hollow sphere diagram`, `cylinder shell diagram`, `cylinder slice diagram`,
`cone slice diagram`, and `sheet element diagram`. Standalone element nodes
include `spherical shell`, `hollow sphere`, `rectangular element`,
`rectangular strip`, and `rectangular sheet`.

The default labels use ordinary LaTeX `$d\!r$`, `$d\!x$`, `$d\!y$`, and
`$d\!\theta$`, while formula labels use the corresponding shell or slice
expression. No notation package is required. Use `show anchors` or
`show keys` on any element node to inspect its complete API.

Element labels and dimension arrows inherit the surrounding or per-node
`font`. Native TikZ styles remain available on every element node: use, for
example, `pattern=dots`, `pattern=north east lines`,
`pattern=horizontal lines,dashed`, or `pattern=none,fill=gray!20`. In a solid
pic, apply these keys through `every solid element/.append style={...}`.
Projected solid diagrams use `every solid hidden edge` for dashed rear curves.

## Set your defaults once

```latex
\tikzset{
  every block/.style={minimum width=1cm,minimum height=1cm,fill=white},
  every spring/.style={pre length=3mm,post length=3mm,amplitude=2mm},
  every pulley/.style={minimum size=1cm}
}
```

Then continue using `\node[block]` and `\draw[spring]`. For one exception, put options after the object name:

```latex
\node[block,minimum width=2cm] (B) {$m$};
```

Node and path styles apply built-in settings, `every physics object` or `every physics connection`, and the object-specific hook, in that order. Later local options win. Inside a scope these customisations stay local. `spring/.append style={...}` is also ordinary supported TikZ.

Use explicit units with native `minimum width`, `minimum height`, and `minimum size`. Convenience keys such as `block width=1.2` interpret bare numbers as centimetres. Spring leads accept zero.

## Spring, block and pulley on a wedge

Copy this complete document:

```latex
\documentclass[tikz,border=6mm]{standalone}
\usepackage{tikzphysics}
\tikzset{
  every block/.style={minimum width=1cm,minimum height=1cm,fill=white},
  every pulley/.style={minimum size=1cm,fill=white},
  every spring/.style={pre length=3mm,post length=3mm,
    amplitude=2mm,segment length=2mm}
}
\begin{document}
\begin{tikzpicture}
  \node[ground,ground width=8.6cm,ground depth=3mm,
        anchor=top-left] (G) at (-0.6,0) {};
  \node[wedge,pulley edge,wedge width=7cm,wedge angle=30] (W) {};
  % The contact anchors select the actual incline in every wedge mode.
  \path (W.tangent-before-50) -- (W.tangent-after-50)
    node[midway,sloped,block,anchor=south] (B) {$m_1$};
  \edef\InclineAngle{\geometryvalue{W}{slope angle}}
  \draw[thick] (W.surface-start) -- ++({\InclineAngle+90}:10mm);
  \coordinate (S) at ($(W.surface-start)+({\InclineAngle+90}:5mm)$);
  \draw[spring] (S) -- node[above=3mm,sloped] {$k$} (B.west);
  \node[pulley] (P) at (W.pulley-center) {};
  \node[block,anchor=north] (H) at ($(P.east)+(0,-2.5cm)$) {$m_2$};
  \draw[rope] (B.east) to[over pulley=P] (H.north);
\end{tikzpicture}
\end{document}

```

The wedge is 7 cm wide at 30 degrees, so its resolved height is about 4.04 cm.
With the hanging block's north anchor 2.5 cm below the pulley centreline, the
full default 1 cm block clears the ground by about 5.4 mm.

The block height matches the pulley diameter, keeping the incoming string parallel to the incline for this placement. The string follows exact tangent points and the pulley arc. If you change these sizes independently, that alignment is no longer guaranteed.

The older `\physicsstringoverpulley{B.east}{P}{H.north}` command is still supported. Both forms respect scoped `string route` settings.

## Continuous pulley edges

`pulley edge` adds the familiar tapered textbook support to a platform without
assembling separate shapes. The horizontal surface still reaches the fixed
tip, the wall begins 5 mm inward and 5 mm lower, and the complete hatched body
is one closed path. The preset matches the default 1 cm pulley:

```latex
\node[platform-right, pulley edge, platform width=5cm] (S) {};
\node[pulley] (P) at (S.pulley-center) {};
```

The same preset works with `platform-left`. Use `platform, pulley edges` for
both sides, or `left pulley edge` and `right pulley edge` independently. Set
`wall inset` and `wall drop` directly for other proportions; the corresponding
left/right keys configure a two-wall platform asymmetrically. Both dimensions
default to zero, preserving the ordinary sharp platform corner. Upward walls
require zero inset and drop to keep the floor outline simple. `platform depth`
continues to set the wall length measured from the new wall root, so the preset
extends the total support 5 mm farther downward.

For `platform`, `platform-left`, `platform-right`, `ground`, `ceiling`, and
`wall-left`/`wall-right`, use `(S.surface-25)` to select a percentage of the
usable contact face. It runs left to right on horizontal faces and bottom to
top on freestanding walls. `surface-50` is the midpoint. The other boundaries
have their own percentage families: `bottom`, `left`, and `right` for a
platform's floor; `wall-surface`, `wall-back`, `wall-base`, and `wall-tip` for
its attached wall. A two-wall platform prefixes these with `left-` or
`right-`. Use `show anchors` with `physics debug/anchor families=all` and
`physics debug/anchor samples={0,50,100}` to inspect them in the picture.
The [surface-anchor guide](docs/surface-anchors.md) maps every family and
includes copy-ready `show anchors` examples for ground, ceiling, both walls,
and all three platforms. Its [visual gallery](docs/surface-anchor-coverage.pdf)
shows every boundary at 0, 50, and 100, including upward platform corners.

On a wedge, the same `pulley edge` name produces the longer textbook nose
used in the complete example above:

```latex
\node[wedge,pulley edge,wedge width=7cm,wedge angle=30] (W) {};
\node[pulley] (P) at (W.pulley-center) {};
```

The wedge preset uses `wedge top inset=5mm` and
`wedge top drop=10mm`. Ordinary wedges keep both values at zero. The
`top` and `pulley-center` anchors coincide at the fixed tip; `wall-root`,
`transition-mid`, and `transition-0..100` expose the added boundary. The
preset supports `wedge right angle at=br` and its mirrored `bl` form.
The [wedge-anchor guide](docs/wedge-anchors.md) maps all three right-angle
modes and both pulley-edge orientations. Its [visual gallery](docs/wedge-anchor-coverage.pdf)
uses `show anchors` to check the contact and boundary points.

Straight and curved ramps also have percentage anchors for each drawn
boundary. The [ramp-anchor guide](docs/ramp-anchors.md) maps the floor,
incline or arc, wall, base, and end edges; its
[visual gallery](docs/ramp-anchor-coverage.pdf) checks both directions.

## Explore inside TikZ

Add `show anchors` or `show keys` to a node. A name is optional when you only
want the overlay; keep a name when you also want to refer to its anchors later:

```latex
\begin{tikzpicture}
  \node[wedge,show anchors,show keys] (W) {};
\end{tikzpicture}
```

`show keys` displays the feature reference: **defaults, size aliases, named anchors, and percentage families**, not the live values of this particular node. To display a reference without creating an object (including path styles and pics):

```latex
\begin{tikzpicture}
  \physicshelp{spring}
\end{tikzpicture}
```

For a larger object, select the anchors you want to inspect:

```latex
\node[wedge,show anchors,
  physics debug/anchor list={bl,br,top},
  physics debug/anchor families={surface},
  physics debug/anchor samples={0,25,50,75,100}] (W) {};
```

`anchor list=auto` lists every named anchor in a table. Each distinct position
has one numbered marker; anchors at the same point share its number in the
table. Families list their entire `0..100` range in the reference; samples
choose points to plot. Native ranges such as `anchor samples={0,1,...,100}`
work; `anchor families=all` selects every family. Use `show anchors=false` or
`show keys=false` for local overrides. Reference panels and legends can be
moved using the debug x/y shift keys described in the manual.

These overlays work on every native physics node, including all eight fluid
nodes, including spring nodes. For paths and pics, use `\physicshelp{spring}`
or `\physicshelp{fluid tank diagram}` for their reference cards. See the
[debug overlay guide](docs/debug-overlays.md) for copy-ready examples covering
platforms, wedges, ramps, fluids, elements, optics, paths, and pics.

## What can I draw?

| Kind | Features |
| --- | --- |
| Contact surfaces | Platforms, ground, walls, ceilings, wedges, straight and circular ramps |
| Mechanics nodes | Blocks, pulleys, particles, disks, rings |
| Differential elements | Polar regions, rings, sphere/cylinder shells and slices, cone slices, and Cartesian sheet elements |
| Fluid mechanics | Eight native fluid nodes plus fourteen editable teaching assemblies |
| Connections and vectors | Springs, ropes, rods, force, velocity, acceleration, torque |
| Named assemblies (`pic`) | Pin supports, roller supports, pendulums |
| Optics | Concave/convex mirrors and lenses, slabs, prisms |

Named assemblies use normal TikZ syntax:

```latex
\pic (A) {pin-support};
\pic (B) at (4,0) {roller-support};
\draw[rod] (A-pivot) -- (B-pivot);
\draw[force] (2,1) -- (2,0);
```

This is a diagram library: forces, trajectories, and optical rays are specified by you. It does not solve dynamics or ray tracing automatically.

## Fluid mechanics and typography

The separate `tikzphysics.fluids` module adds eight native fluid nodes and
fourteen teaching assemblies. Start individual objects with ordinary node
syntax such as `\node[fluid tank] (T) {};`. Use explicit pic names such as
`fluid tank diagram` when the complete labeled teaching assembly is useful.
The original short pic names remain compatibility aliases.

Liquid defaults to dots. Users can set native `pattern`, `pattern color`,
`fill`, and `dashed` directly; `pattern=north east lines` is a standard
alternative. See [the fluid guide](docs/fluids.md), [the native-node
gallery](examples/fluid-mechanics-nodes.tex), [the assembly
gallery](examples/fluid-mechanics-gallery.tex), and [reference
compositions](examples/fluid-mechanics-reference-scenes.tex). Scoped
`fluid={...}` keys, collision-safe `physics fluid ...` aliases, and named
anchors or coordinates are supported. Element labels inherit document,
picture, and node fonts; dimension arrows use font-relative sizes.
For example, `\node[fluid tank,show anchors,show keys] (F) {};` shows the
native tank's attachment points and documented settings.

## Compatibility and precise attachments

Ramps and optical shapes retain their numeric shorthand. Prefer explicit
anchors such as `(W.surface-50)` and `(L.front-50)`: `(L.30)` is a percentage
on optical shapes, while `(P.30)` on a pulley is an angle in degrees.

Use physical anchors for contact with irregular shapes. Their inherited rectangular automatic borders have not been replaced in this release. Standard block and circular-body borders retain normal TikZ behaviour. Use tangent anchors with `sloped` for rotated objects; nonuniform scaling does not preserve circles or perpendicular normals.

## Development

```sh
python3 scripts/generate_reference.py --check
l3build check
l3build doc
python3 scripts/build_overleaf_bundle.py --check
```

The manual uses Fourier and `minted`, and therefore needs their dependencies and shell escape when rebuilding. This does not apply to ordinary package use. Run the generator without `--check` after editing feature reference declarations.

Licensed under [LPPL 1.3c or later](LICENSE).

For predictable percentages on fluid and mechanics nodes, see the
[anchor direction guide](docs/fluid-mechanics-anchors.md) and
[complete visual example](examples/fluid-mechanics-anchor-coverage.tex).