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:

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.

\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:

\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 and its rendered gallery.

Choose what to learn

I want to…	Start with…
Build a spring–block–pulley system	Complete example below
Find every feature and its keys	Feature reference
See keys and anchors while drawing	Debug explorer
Compare show anchors and show keys across object types	Debug overlay guide and complete feature tour
Understand dimensions and percentage anchors	Extended guide
Browse rendered diagrams and detailed explanations	PDF manual
Copy a complete document	Example directory and learning routes

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}:

\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:

\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 $2pi 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:

\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

\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:

\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:

\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:

\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 maps every family and includes copy-ready show anchors examples for ground, ceiling, both walls, and all three platforms. Its visual gallery 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:

\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 maps all three right-angle modes and both pulley-edge orientations. Its visual gallery 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 maps the floor, incline or arc, wall, base, and end edges; its visual gallery 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:

\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):

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

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

\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 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:

\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, the native-node gallery, the assembly gallery, and reference compositions. 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

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.

For predictable percentages on fluid and mechanics nodes, see the anchor direction guide and complete visual example.