# 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.0.0 (2026-08-12)**

## Included modules

- `tikzphysics.surface`: single-polygon, sharply mitered bent platforms; wedges, ground, ceilings,
  and walls.
- `tikzphysics.mechanics`: configurable blocks and pulleys, plus strings that
  compute exact pulley tangencies and circular contact arcs.
- `tikzphysics.optics`: a curved optical lens with arc anchors.
- `tikzphysics.core`: unit-aware dimensions, parametric anchors, and debug tools.

All public configuration keys begin with `physics`, for example
`physics wedge angle`, `physics platform width`, and `physics lens radius`.

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` and `patterns` 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.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.surface, tikzphysics.mechanics}
```

An inclined plane with a block:

```latex
\begin{tikzpicture}
  \node[physicswedge, physics wedge angle=30, physics wedge width=6] (W) at (0,0) {};
  \node[physicsblock, physics block width=1, physics block height=1,
        rotate=30, anchor=south] at (W.slope-mid) {$m$};
\end{tikzpicture}
```

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 curved lens:

```latex
\begin{tikzpicture}
  \draw[->] (-3,0) -- (3,0);
  \node[physicslens, physics lens radius=5, physics lens thickness=0.25,
        physics lens aperture angle=30] (L) at (0,0) {};
  \draw (L.front-25) -- ++(-1,0);
\end{tikzpicture}
```

Bare dimension values are interpreted as centimetres; explicit TeX units such
as `8mm`, `12pt`, and `1in` are preserved.

## 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. 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, numeric
anchor endpoints, lens arc 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.