# Extended guide

`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.5.0 (2026-09-26)**

Start with the [quick start](../README.md). The [feature reference](reference.md) lists keys and anchors; the [manual](../tikzphysics.pdf) includes rendered examples and the new debug explorer.
Use the [debug overlay guide](debug-overlays.md) for copy-ready `show anchors`,
`show keys`, and `\physicshelp` examples across all object categories.

## 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, a spring path style, and pulleys, plus strings that
  compute exact pulley tangencies and circular contact arcs.
- `tikzphysics.elements`: polar differential sectors, complete differential
  rings, and unwrapped ring strips with dimension labels and boundary anchors.
- `tikzphysics.fluids`: eight native fluid nodes and fourteen editable
  teaching assemblies with patterns, labels, and semantic anchors.
- `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`, `strip width`, 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`; concise unit-aware convenience keys and
their collision-safe `physics ...` aliases remain available when useful.

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 |
| `platform-left-up`, `platform-right-up` | `physicsplatform-left-up`, `physicsplatform-right-up` | One-wall presets using `wall angle=90` |
| `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`, `pulley` | `physicsblock`, `physicspulley` | Mechanics nodes |
| `spring` | `physics spring`, `physicsspring` | Coil decoration used with `\draw` |
| `polar element` | `physicspolarelement` | General annular-sector element |
| `differential sector` | `physicsdifferentialsector` | Sector with zero inner radius |
| `differential ring` | `physicsdifferentialring` | Full thin annulus |
| `unwrapped ring` | `physicsunwrappedring` | Equivalent `2 pi r` by `d r` strip |
| `fluid tank`, `fluid cylinder` | `physics fluid tank`, `physics fluid cylinder` | Open vessel and projected cylindrical column |
| `pressure element`, `flow tube` | `physics pressure element`, `physics flow tube` | Pressure balance element and curved stream tube |
| `meniscus`, `rotating fluid` | `physics meniscus`, `physics rotating fluid` | Interface and rotating-vessel liquid |
| `liquid ring`, `u tube` | `physics liquid ring`, `physics u tube` | Annular liquid sector and U-shaped column |
| `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.catalog.code.tex`
- `tikzlibrarytikzphysics.surface.code.tex`
- `tikzlibrarytikzphysics.ramps.code.tex`
- `tikzlibrarytikzphysics.mechanics.code.tex`
- `tikzlibrarytikzphysics.elements.code.tex`
- `tikzlibrarytikzphysics.fluids.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.

For direct Overleaf upload, generate the self-contained bundle from the package
root:

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

Upload only `output/overleaf/tikzphysics.sty` beside the main document. This
generated file inlines all eight runtime modules, including the feature catalog.

## 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 generated single-file `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` | `block width`, `block height` |
| Pulley diameter | `minimum size` | `pulley diameter` |
| Platform width/depth | `minimum width`, `minimum height` | `platform width`, `platform depth` |
| Ground or ceiling width/depth | `minimum width`, `minimum height` | `ground ...`, `ceiling ...` |
| Wall thickness/height | `minimum width`, `minimum height` | `wall thickness`, `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` |
| `wedge top inset` | `physics wedge top inset` |
| `wedge top drop` | `physics wedge top drop` |

### Named wedge geometry values

A named wedge records its resolved geometry. Read a value with
`\geometryvalue{node}{property}`; the collision-safe command is
`\tikzphysicsgeometryvalue`. The result belongs to that particular node, so
several wedges can be queried independently:

```latex
\node[wedge, minimum width=6cm, wedge angle=30] (W) at (0,0) {};
\node[block, minimum width=1cm, minimum height=1cm,
      rotate=\geometryvalue{W}{slope angle}, anchor=south]
  at (W.slope-mid) {$m$};

\node at (W.bl) {$\geometryvalue{W}{left angle}^\circ$};
```

Interior-angle properties are `left angle`, `right angle`, and `top angle`, at
anchors `bl`, `br`, and `top`. Local edge-direction properties are
`base direction`, `left edge direction`, and `right edge direction`.
`slope angle` (also `slope direction` or `surface angle`) is the rotation of
the contact surface selected by `slope-mid`, so it is the value to use for a
block placed there. It is negative for a wedge that descends left-to-right.
For `wedge right angle at=top`, `slope-mid` selects the left face and
`right slope angle` belongs to `slope-right-mid`. Directions are in degrees
counter-clockwise from local positive x, without a degree symbol. The
remaining values are `base angle`, `right edge angle`, `width`, `height`,
`top inset`, `top drop`, and `right angle at`.

The node must be named and completed before it is queried. Directions describe
the wedge before a node-specific transformation. They work directly when the
wedge and attached object share the same transformed scope. For independently
rotated or non-uniformly scaled nodes, use the edge anchors and TikZ's `sloped`
placement so the final rendered geometry determines the orientation. See
`examples/wedge-geometry-values.tex` for a complete annotated document.

The remaining concise controls follow the same rule:

| Concise key | Collision-safe alias |
| --- | --- |
| `platform width`, `platform depth`, `strip width` | `physics platform width`, `physics platform depth`, `physics strip width` |
| `wall angle`, `left wall angle`, `right wall angle` | The same keys prefixed with `physics` |
| `wall inset`, `left wall inset`, `right wall inset` | The same keys prefixed with `physics` |
| `wall drop`, `left wall drop`, `right wall drop` | The same keys prefixed with `physics` |
| `block width`, `block height` | `physics block width`, `physics block height` |
| `pulley diameter`, `pulley axle radius`, `pulley axle color` | The same keys prefixed with `physics` |
| `string start solution`, `string end solution`, `string route`, `string wrap` | The same keys prefixed with `physics` |
| `ground width/depth`, `ceiling width/depth`, `wall thickness/height` | The same keys prefixed with `physics` |
| `ramp direction/run/rise/angle/depth`, `ramp wall height/width`, `ramp guide length` | The same keys prefixed with `physics` |
| `curved ramp radius/angle/floor length/back extension` | The same keys prefixed with `physics` |
| `mirror radius/thickness/aperture angle` | The same keys prefixed with `physics` |
| `convex lens radius/thickness/aperture angle` | The same keys prefixed with `physics` |
| `concave lens radius/thickness/aperture angle` | The same keys prefixed with `physics` |
| `slab width/height`, `prism width/height/apex angle` | The same keys prefixed with `physics` |

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.

Platform directions use `wall angle`, `left wall angle`, and `right wall angle`.
Optional `wall inset` and `wall drop` dimensions insert a straight transition
between the fixed floor tip and the wall root. Their collision-safe aliases add
the `physics` prefix. Wedges use the `dots`
material pattern by default; a later `pattern=...` option overrides it.

## Continuous pulley-edge platforms

Use `pulley edge` on either one-wall platform. It is a preset for a 5 mm inward
and 5 mm downward transition, matching half the default 1 cm pulley diameter:

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

The platform remains one closed, filled path. `pulley-center` marks the
projecting floor tip. `wall-root` is where the transition ends and the wall
begins; `transition-50` is halfway between them. `transition-0..100` samples
the diagonal from tip to root.

For a two-wall platform, use:

```latex
\node[platform, pulley edges] (Both) {};
\node[pulley] at (Both.left-pulley-center) {};
\node[pulley] at (Both.right-pulley-center) {};
```

`left pulley edge` and `right pulley edge` enable one side independently.
Direct controls are `wall inset` and `wall drop`, or the side-specific
`left wall inset`, `right wall inset`, `left wall drop`, and `right wall drop`.
All default to zero. The two inset distances together must remain smaller than
the platform width. A nonzero inset or drop requires a non-horizontal wall;
upward walls require both to remain zero so their boundary meets the floor
without crossing it. Rotate the complete node for an inclined platform.
`platform depth` remains the wall length measured from its root; the downward
transition is additional.

To inspect this geometry inside the picture, combine `show anchors` with the
`transition` family, or place its complete reference card beside it:

```latex
\node[platform-right,pulley edge,show anchors,
  physics debug/anchor list={pulley-center,wall-root,transition-50},
  physics debug/anchor families={transition},
  physics debug/anchor samples={0,50,100}] (S) {};
\physicshelp[xshift=4cm,yshift=2.5cm]{platform-right}
```

See `examples/debug-pulley-edge.tex` for the standalone version.
The [surface-anchor guide](surface-anchors.md) gives the complete edge map,
`show anchors` settings for every surface and platform, and a rendered gallery.

## Pulley edge on a wedge

The same `pulley edge` preset works on the ordinary right-facing wedge and its
`wedge right angle at=bl` mirror. The wedge profile uses a 5 mm inward inset
and a 10 mm drop, which leaves room for a full default 1 cm hanging block:

```latex
\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) {};
\node[pulley] (P) at (W.pulley-center) {};
\node[block,anchor=north] (H)
  at ($(P.east)+(0,-2.5cm)$) {$m_2$};
```

The resolved 7 cm by 30 degree wedge is about 4.04 cm tall. A 2.5 cm vertical
placement from `P.east` to `H.north` leaves the 1 cm block about 5.4 mm above
the supporting ground. Increase `wedge width` or shorten that placement when a
larger clearance is required.

`top` and `pulley-center` identify the unchanged projecting tip. `wall-root`
marks the top of the vertical support, `transition-mid` marks the middle of the
sloping nose, and `transition-0..100` samples the whole nose. The direct keys
are `wedge top inset` and `wedge top drop`; their zero defaults preserve the
triangle. The inset must be smaller than the wedge width and the drop must be
smaller than its resolved height. For a nonzero inset, the drop must also put
the wall root strictly below the incline.

The preset does not apply to `wedge right angle at=top`, because that mode has
two sloping sides and no vertical supporting side to continue below the nose.

Debug the geometry directly in TikZ:

```latex
\node[wedge,pulley edge,show anchors,show keys,
  physics debug/anchor list={pulley-center,wall-root,transition-mid},
  physics debug/anchor families={transition},
  physics debug/anchor samples={0,50,100}] (W) {};
```

The [wedge-anchor guide](wedge-anchors.md) maps every boundary and contact
family in all three right-angle modes. Its [rendered gallery](wedge-anchor-coverage.pdf)
shows the named midpoints and centroid on the drawn wedge.

## Spring paths

`spring` is used directly on a path. Its two endpoints determine the complete
length and direction:

```latex
\draw[spring,
      pre length=5pt, post length=5pt,
      amplitude=4.5pt, segment length=4.5pt,
      aspect=0.5]
  (A) -- node[above] {$k$} (B);
```

The spring is not a node and therefore has no private anchors. Use the path
endpoints and ordinary TikZ nodes along the path. Its keys are `pre length`,
`post length`, `amplitude`, `segment length`, and `aspect`; collision-safe
aliases begin with `physics spring ...`.

## Percentage anchors

Percentage anchors place something partway along a named edge or curved
surface without coordinate arithmetic. Their explicit form is:

```latex
(node-name.family-number)
```

The number is an integer from `0` to `100`; do not include a `%` sign. `0` is
the family's documented start, `50` is halfway along it, and `100` is its end.
For example:

```latex
\node[wedge, wedge width=6cm, wedge angle=30] (W) at (0,0) {};
\node[block, rotate=30, anchor=south] at (W.slope-50) {$m$};
\fill[red] (W.slope-25) circle (1.5pt);
```

Here `W` is the node name, `slope` chooses one edge, and `25` means 25 percent
from `slope-0` towards `slope-100`. Wedge slope direction runs from the top
vertex to the lower foot, so `slope-25` is near the top.

Common directions are:

| Family | Direction from `0` to `100` |
| --- | --- |
| Platform or ground `surface-T` | Left to right across the top contact face |
| Ceiling `surface-T` | Left to right across the underside |
| Freestanding wall `surface-T` | Bottom to top on the contact face |
| Platform `bottom-T` | Left to right along the floor underside |
| Rectangular `left-T`, `right-T` | Bottom to top on the named side |
| Platform `wall-surface-T`, `wall-back-T` | Wall root to free tip |
| Platform `transition-T` | Projecting pulley tip to wall root |
| Wedge `base-T` | `bl` to `br` |
| Wedge `right-T` | `br` to `top` |
| Wedge `slope-T` | `top` to `bl` |
| Ramp `surface-T` | `surface-start` to `surface-end` along the complete contact path |
| Curved ramp `curve-T` | Start to end of the circular portion only |
| Mirror/lens/slab surfaces | Bottom to top |
| Prism `base-T` | `base-left` to `base-right` |
| Prism `left-T` | `apex` to `base-left` |
| Prism `right-T` | `base-right` to `apex` |

On platforms, `surface-*` covers the floor's top, while `bottom-*`, `left-*`,
and `right-*` cover its other three edges. An attached wall uses
`wall-surface-*` and `wall-back-*` along its length, then `wall-base-*` and
`wall-tip-*` across its two ends. A two-wall platform prefixes these wall
families and `transition-*` with `left-` or `right-`. Horizontal percentages
increase left to right, vertical strip percentages bottom to top, and attached
wall percentages run from root to free tip. The midpoint of any family is
`*-50`; `surface` names the main contact midpoint directly.

On a multi-part ramp, `surface-50` means halfway by distance along the entire
contact path; it is not necessarily the visual centre or the floor-to-ramp
joint. On circular families, the percentage follows the arc.

Ramps and optical shapes also provide `(name.T)` shorthand. For ramps it means
`surface-T`; for mirrors it means `surface-T`; for lenses and slabs it means
`front-T`; and for prisms it means `left-T`. Prefer the explicit family form
while learning, especially because ordinary TikZ numeric anchors can instead
mean an angle around a node. Platforms and wedges require explicit forms such
as `(P.surface-50)` and `(W.slope-50)`.

See `examples/percentage-anchors-beginner.tex` for an annotated copy-paste
document and `examples/surface-numeric-anchors.tex` for a larger edge gallery.

## Combining coordinates for horizontal connections

TikZ's native projection syntax can take x from one anchor and y from another:

| Syntax | Result |
| --- | --- |
| `(A |- B)` | x from `A`, y from `B` |
| `(A -| B)` | x from `B`, y from `A` |

For a horizontal spring from a ramp's vertical wall to a block, use:

```latex
\coordinate (A) at (R.wall-mid |- B.west);
\draw[spring] (A) -- (B.west);
```

This requires no measured offset: both endpoints necessarily use the y-value
of `B.west`. For `platform-left-up`, replace `R.wall-mid` with
`P.wall-surface-50`. For a right upward wall, project from its wall anchor to
`B.east`. This is exact for vertical walls; an arbitrary angled-wall
intersection requires TikZ's `intersections` library. The complete examples
are in `examples/coordinate-projection.tex` and
`examples/ramp-straight-system.tex`.

## 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 3.75cm
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] (B) {$m$};
\draw[->] (B.north) --
  ($(B.north)+(R.curve-normal-60)-(R.curve-60)$) node[above left] {$N$};
```

The last coordinate expression translates the exact normal vector to start at
the top of the block, keeping the force arrow out of the block body.

The [ramp-anchor guide](ramp-anchors.md) maps every edge of both shapes,
including the underside and wall or back. Its
[12-page `show anchors` gallery](ramp-anchor-coverage.pdf) checks both
directions, the contact guides, and a straight ramp with a taller wall.

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 `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.

For a wedge-mounted pulley, place its centre at `pulley-center` (an alias of the unchanged wedge vertex). If
the string starts at `B.east`, the default `1cm` pulley diameter and a `1cm`
block height keep that tangent exactly parallel to the incline:

```latex
\node[block, block height=1cm, rotate=30, anchor=south]
  (B) at (W.slope-mid) {$m$};
\node[pulley] (P) at (W.pulley-center) {};
```

## Circular differential elements

The `tikzphysics.elements` library represents the shaded region as a real TikZ
node. The general `polar element` is bounded by two radii and two angles:

```latex
\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) {};
```

`element outer radius=20mm` may replace `element radial thickness=2mm`.
Whichever of those two keys occurs later controls the outer boundary. Explicit
units are accepted; bare radial values are centimetres. The inner radius may be
zero, the outer radius must be larger, and `element delta angle` must be in
the interval `(0,360]` degrees.

Two presets cover the common mechanics constructions:

```latex
\node[differential sector,element outer radius=2cm] (S) {};
\node[differential ring,element inner radius=18mm,
      element radial thickness=2mm] (R) at (5,0) {};
```

`differential sector` sets the inner radius to zero. `differential ring` sets
the angular extent to 360 degrees and draws the annulus without a radial seam.
The default dimension labels are ordinary LaTeX `$r$`, `$d\!r$`,
`$d\!\theta$`, and `$r\,d\!\theta$`; they do not require a notation package.
Change them with `element radius label`, `element radial label`,
`element angular label`, and `element arc label`.

An unwrapped strip can copy the resolved radii from any named polar element:

```latex
\node[unwrapped ring,source element=R,show dimensions] (U) at (0,-4) {};
```

Its differential-approximation length is `2 pi` times the inner reference
radius and its height is the radial thickness. For the complete teaching
diagram use the named pic:

```latex
\pic (D) {differential ring diagram={
  element inner radius=1cm,
  element radial thickness=2mm
}};
```

The pic keeps the original circular body, a 1.2 pt centre mark, the annular
element, and its opened strip together. The body radius defaults to 2 cm and
the body-to-strip gap to 5 mm; change them with `element body radius` and
`element diagram gap`. The components are the real nodes `(D-ring)` and
`(D-strip)`, while `(D-center)` and `(D-body-north)`, `(D-body-south)`,
`(D-body-east)`, and `(D-body-west)` expose the surrounding construction.
Style the circle and centre through `every element body` and
`every element center`; `every differential ring diagram` changes the whole
pic. The boundary anchors are `inner-start`, `inner-mid`, `inner-end`, `outer-start`,
`outer-mid`, `outer-end`, `start-mid`, and `end-mid`. The numeric families
`inner-0..100`, `outer-0..100`, `start-0..100`, and `end-0..100` expose every
edge. `centroid` is the area centroid; for a complete ring it coincides with
`center`.

Named elements record `inner radius`, `outer radius`, `radial thickness`,
`mean radius`, `start angle`, `delta angle`, and `end angle`. An unwrapped ring
also records `circumference`. Read them through `\geometryvalue{node}{property}`.
As elsewhere in the package, `show anchors`, `show keys`, and
`\physicshelp{polar element}` work inside the TikZ environment.

### Solid, shell, slice, and sheet elements

The solid diagrams name the integration method explicitly. A sphere may use a
concentric shell or an axial disk, and a cylinder may use a radial shell or an
axial disk. This avoids giving one ambiguous meaning to a name such as
`solid sphere`.

| Construction | Pic | Default differential expression |
| --- | --- | --- |
| Solid sphere by shells | `sphere shell diagram` | `dV = 4 pi r^2 d r` |
| Solid sphere by disks | `sphere slice diagram` | `dV = pi y^2 d x` |
| Finite hollow sphere | `hollow sphere diagram` | `V = 4 pi (R^3-a^3)/3` |
| Cylinder by shells | `cylinder shell diagram` | `dV = 2 pi r h d r` |
| Cylinder by disks | `cylinder slice diagram` | `dV = pi R^2 d z` |
| Cone by disks | `cone slice diagram` | `dV = pi r(x)^2 d x` |
| Cartesian sheet | `sheet element diagram` | `dA = d x d y` |

All of them are ordinary named pics:

```latex
\pic (S) {sphere shell diagram={
  element body radius=2cm,
  element inner radius=1cm,
  element radial thickness=1.5mm
}};
\pic (C) at (6,0) {cylinder slice diagram={
  element body radius=1.6cm,
  element body height=3.4cm,
  element position=.55,
  element axial thickness=2mm
}};
```

`element position` is unitless. On `sphere slice diagram` it is the signed
axial coordinate divided by the sphere radius and must lie strictly between
-1 and 1. On the cylinder diagrams it runs from bottom to top in `[0,1]`.
On `cone slice diagram` it runs from apex to base in `(0,1)`. The key
`element projection ratio` controls the apparent depth of projected circles;
it changes the drawing only, not the physical radius.

The component names follow the pic name. For `(S)` they include `(S-body)`,
`(S-shell)` or `(S-slice)`, `(S-center)`, and `(S-formula-anchor)`. Cylinder
and cone pics similarly expose `body` and `shell` or `slice`; the cone also
provides `apex` and `base`. The sheet pic exposes `(A-body)` and `(A-element)`.

The reusable nodes are useful when a complete body is unnecessary:

```latex
\node[spherical shell,show dimensions] (S) {};
\node[hollow sphere,element inner radius=8mm,
      element outer radius=2cm] (H) at (5,0) {};
\node[rectangular element,element width=8mm,
      element height=6mm,show dimensions] (dA) at (10,0) {};
```

`spherical shell` and `hollow sphere` inherit all polar boundary anchors and
the `inner-*`, `outer-*`, `start-*`, and `end-*` families. Rectangular nodes
provide the four corners plus `bottom-*`, `right-*`, `top-*`, and `left-*`.
They record resolved `width` and `height` values. Use
`\physicshelp{sphere slice diagram}` for a pic reference card or add
`show anchors,show keys` to any element node.

Change formula text with `element formula label`. The labels remain plain
LaTeX, such as `$d\!x$`, `$d\!y$`, and `$d\!r$`, without a notation package.
Dimension labels and arrow sizes inherit the node or picture font. On an
element node, apply native TikZ options directly: `pattern=dots`,
`pattern=north east lines`, `pattern=horizontal lines,dashed`, or
`pattern=none,fill=gray!20`. For the highlighted slice or shell inside a solid
pic, put the same native keys in `every solid element/.append style={...}`.
Projected circular bodies draw their rear half with `every solid hidden edge`
and their visible front half with the ordinary body or dimension style. The
full rendered galleries are `examples/elements-solid-geometries.tex` and
`examples/elements-fonts.tex`.

## Fluid mechanics

Use ordinary nodes for individual fluid objects:

```latex
\node[fluid tank,
  fluid={width=4cm,height=3cm,left level=.8,right level=.55},
  pattern=north east lines,pattern color=gray] (T) {};
\draw[->] (T.right-surface) -- ++(1,0) node[right] {$a_x$};
```

The native styles are `fluid tank`, `fluid cylinder`, `pressure element`,
`meniscus`, `rotating fluid`, `flow tube`, `liquid ring`, and `u tube`.
They support standard node text, compass/base/mid anchors, positioning,
transforms, minimum sizes, `inner sep`, and `outer sep`. Their semantic
anchors describe free surfaces, inlets, outlets, and liquid-sector ends.

Use a named pic when labels, force arrows, axes, or several component objects
belong to one teaching diagram. For objects that also have a node, add the
explicit `diagram` suffix:

```latex
\pic (U) {u tube diagram={
  fluid left level=.4,fluid right level=.64,fluid level=.86,
  fluid left label={Water},fluid body label={Mercury}}};
\draw[<->] (U-interface -| 1,0) -- (U-upper-surface -| 1,0);
```

The original short pic names remain compatibility aliases. Liquid defaults to
`pattern=dots`; native `pattern=north east lines`, `horizontal lines`, solid
`fill`, `pattern color`, `dashed`, opacity, and line-width settings remain
available. A later `fill` replaces the current pattern, and a later `pattern`
selects patterned liquid again. Geometry belongs to `fluid={...}` or the
individual `fluid ...` keys. Every semantic key also has a collision-safe
`physics fluid ...` alias. See [the complete fluid guide](fluids.md) for all
fourteen assemblies, geometry bounds, labels, hooks, and coordinates.

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 shorthand percentage anchors are summarized in the percentage-anchor
section above. 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.
Start with `examples/percentage-anchors-beginner.tex` when learning percentage
anchors; it labels the direction and shows both explicit and short forms.
The ramp examples are `ramp-straight-system.tex`, `ramp-curved-system.tex`,
`ramps-gallery.tex`, and the [anchor coverage source](../examples/ramp-anchor-coverage.tex).
The [seven-page feature tour](../examples/debug-feature-tour.tex) shows
`show anchors` and `show keys` on nodes from six modules, then shows
reference cards for a path and a pic. The [debug overlay guide](debug-overlays.md)
explains how to choose families and move cards.
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.