physics / braket / tensor

physics may be the most enthusiastically recommended and most loudly warned-against package in LaTeX. \dv{f}{x} for a derivative, \qty(...) for self-sizing parentheses, \ket{\psi} for a ket — it really does write well. But the package silently rewrites commands your document already uses. \div stops being the division sign ÷ and becomes a divergence; \Re stops being the Fraktur ℜ and becomes an upright “Re”. This page covers physics, its redesign physics2, the Dirac-notation specialist braket, and tensor for lining up indices, and answers the question “what should I choose if I am starting today?” from results actually compiled and measured.

What \usepackage{physics} actually gives you

One line, and the shapes that recur in physics turn into short commands. physics, by Sergio C. de la Barrera, requires xparse and amsmath under the hood, and loads amsmath for you so you need not name it. What you get falls into five groups: self-sizing fences (\qty, \abs, \norm, \eval, \order); vector calculus (\grad, \div, \curl, \laplacian, the dot product \vdot, the cross product \cross); derivatives (\dv, \pdv, \fdv, \dd); Dirac notation (\bra, \ket, \braket, \ketbra, \dyad, \expectationvalue, \matrixelement); and shorthands for matrices and brackets (\mqty, \smqty, \pqty, \bqty, \Bqty, \vqty, the commutator \comm, the anticommutator \acomm, the Poisson bracket \pb, and the bold vectors \vb, \va, \vu).

\usepackage{physics}

\[
  \dv{f}{x}, \qquad \dv[2]{f}{x}, \qquad \pdv{f}{x}{y},
  \qquad \int_0^1 f(x) \dd{x}
\]
\[
  \abs{\frac{a}{b}}, \qquad \norm{\vb{v}}, \qquad
  \eval{x^2}_0^\infty, \qquad \qty( \frac{1}{2} )
\]

Derivatives are the headline. \dv changes shape with the number of arguments: \dv{x} sets the operator d/dx, \dv{f}{x} sets df/dx. Order goes in an optional argument — \dv[2]{f}{x} is d²f/dx², \dv[n]{f}{x} is dⁿf/dxⁿ. The d is upright (roman) by default; \usepackage[italicdiff]{physics} switches it to an italic d. The starred \dv*{f}{x} produces the slashed \flatfrac form. The partial \pdv follows the same idiom, except that a mixed partial takes three arguments: \pdv{f}{x}{y} gives ∂²f/∂x∂y. The differential element itself is \dd: \dd{x} sets dx with the spacing tidied around it, \dd[3]{x} sets d³x. On the fence side, \qty(...), \qty[...] and \qty{...} give round, square and curly brackets, each growing to the height of its contents.

What physics silently redefines — \div, \Re, \sin

No warning, no error. Only the output changes. Reading \meaning back under TeX Live 2024 confirms it: before physics is loaded, \div is \mathchar"2204 — the division sign ÷. After loading, \div is a divergence, and the original ÷ has been moved aside under the name \divisionsymbol. Typeset both in the same document and extract the text from the PDF, and $a \div b$ comes out as “a∇ · b” while $a \divisionsymbol b$ comes out as “a ÷ b”. The widths differ too: 26.79959pt against 21.79968pt. So adding \usepackage{physics} to an existing document that used \div for division silently changes what its formulas mean.

\Re and \Im change in a way you can see. The relevant line of physics.sty reads \let\real\Re \DeclareDocumentCommand\Re{g}{…\operatorname{Re}…} — that is, the Fraktur ℜ is replaced by an upright operator “Re”. Set both in the same document and $\Re z$ comes out as “Re z” while the stashed $\real z$ comes out as “ℜz”. The same happens to the named functions: \sin, \cos, \tan, \log, \ln, \exp and \det are swapped for versions that add parentheses around their argument automatically, and the originals survive under longer names — \sine, \cosine, \tangent, \logarithm, \naturallogarithm, \exponential, \determinant. Only the trigonometric swap can be switched off, with \usepackage[notrig]{physics}.

Write \dv{f}{x}(g) and the (g) disappears

Part of your formula vanishes from the output, with no error and no warning. That is far more serious than “it looks wrong”, so here is the measurement. Under TeX Live 2024, \sbox0{$\dv{f}{x}$} measures 11.50076pt wide, and \sbox0{$\dv{f}{x}(g)$} also measures 11.50076pt — exactly the same. Extract the text from the PDF and both give only “df/dx”; the (g) is nowhere.

The cause is in the argument declaration. \derivative in physics.sty is declared with the signature { s o m g d() }, and that trailing d() swallows a following parenthesised group as an argument. It exists for the “long form” \dv{x}(\Psi), where d/dx acts on the contents of the parentheses. But in the branch taken when g (here, x) has been supplied, the body of the macro never refers to the d() argument at all. So the (g) is read, and then discarded. There are two workarounds: put an empty group {} in between, or an explicit space. Measured, $\dv{f}{x}{}(g)$ gives 24.40703pt and $\dv{f}{x}\,(g)$ gives 26.07365pt, and in both the (g) survives into the output. The same d() is attached to \grad, \div, \curl, \laplacian, \dd, \pdv and \fdv, so a following parenthesis needs care everywhere.

% the (g) is read as the trailing d() argument and then thrown away:
% this prints df/dx and nothing else
$\dv{f}{x}(g)$

% either of these keeps the (g)
$\dv{f}{x}{}(g)$
$\dv{f}{x}\,(g)$

This behaviour has come up repeatedly on tex.stackexchange, to the point that a package called physics-patch exists to correct it. That a patch has been needed for so long is itself worth weighing when you choose.

The \qty clash with siunitx — load order does not fix it

The result is identical in either order, and physics wins. siunitx, the standard for typesetting units, introduced \qty as its quantity command in recent versions, colliding by name with physics's \qty. Load both and compile, and siunitx announces: Package siunitx Warning: Detected the "physics" package: omitting definition of \qty. It even hands you the workaround, telling you to add \AtBeginDocument{\RenewCommandCopy\qty\SI} to the preamble. In that state, writing a unit as \qty{2}{\metre} is taken by physics's \qty instead and falls over with ! Missing $ inserted. Putting \usepackage{physics} before or after made no difference: the warning and the errors came out word for word the same.

One detail here is hard to skim past. Look inside siunitx.sty and you find the line \@ifpackageloaded{physics} — siunitx names physics by package name and steps aside for it. A major package of several thousand lines carrying a concession hard-coded for one other package by name is an unusual sight in the LaTeX ecosystem, and it says something about how widely this collision was hit.

\abs in physics vs mathtools — the star means the opposite

Load both and \abs becomes the physics one — and the star flips meaning. Declaring \DeclarePairedDelimiter\abs{\lvert}{\rvert} with mathtools and then writing \usepackage{physics} produced not a single error: physics overwrites it silently. But the behaviour is exactly inverted. Measured, the mathtools version gives \abs{\frac ab} a height of 7.5pt (fixed) and \abs*{\frac ab} 8.50006pt (auto-stretched). The physics version gives \abs{\frac ab} 8.50006pt (auto-stretched) and \abs*{\frac ab} 7.5pt (fixed). In other words, mathtools uses the star to stretch and physics uses the star to stop stretching.

The syntax for choosing a size differs too. mathtools takes it in brackets, \abs[\big]{x}; physics takes it directly, \abs\big{x}. Use the mathtools syntax while physics is loaded and you get ! Missing delimiter (. inserted). with the broken output “[] ||x” on the page. If you intend to mix the two, this incompatibility is unavoidable. In practice the answer is to pick one.

physics2 — the redesign that overwrites nothing

Run the same inspection against physics2 and not one standard command has been rewritten. Load physics2, by Zhang Tingxuan, read \meaning back, and \div is still \mathchar"2204 (÷), \Re is \mathchar"23C and \Im is \mathchar"23D (still Fraktur), \sin still has its standard definition, and \qty is undefined. Typeset it and $a\div b$ gives “a ÷ b”, $\Re z$ gives “ℜz”, $\sin(x)$ gives “sin(x)” — output identical to plain LaTeX. Used alongside siunitx it produced zero warnings and zero errors, and \qty{2}{\metre} set correctly as “2 m”. The version in TeX Live 2024 is v1.0.1, dated 2024-01-10.

The design difference shows up in how you load it. Where physics brings everything in at once, physics2 has you enable modules one at a time. After \usepackage{physics2} you write something like \usephysicsmodule{ab,braket} and pull in only what you want. The modules bundled with TeX Live 2024 are ab (self-sizing fences), ab.braket, braket, diagmat (diagonal matrices), xmat (general matrices), doubleprod, plus ab.legacy, bm-um.legacy, nabla.legacy, op.legacy and qtext.legacy for people migrating from physics. The price of not polluting the namespace is that the names are less terse than physics's: fences are \ab(...), \ab[...], \ab\{...\}, \ab|...|, \ab<...>; a diagonal matrix is \pdiagmat{1,2,3}; a matrix is \pxmat{a}{2}{2}.

\usepackage{physics2}
\usephysicsmodule{ab,braket,diagmat,xmat}

\[
  \ab(\frac{a}{b}), \quad \ab[\frac{a}{b}], \quad \ab|\frac{a}{b}|
\]
\[
  \bra{\phi}, \quad \ket{\psi}, \quad \braket{a}{b}, \quad \ketbra{a}{b}
\]
\[
  \pdiagmat{1,2,3}, \qquad \pxmat{a}{2}{2}
\]

One practical caution. The ab.braket and braket modules cannot be loaded together. List both in \usephysicsmodule and you get Package physics2 Warning: You cannot load 'ab.braket' and 'braket' modules together., with only one of them left active. Both provide Dirac notation: ab.braket rides on the auto-sizing machinery of ab, while braket stands on its own. To summarise the practical judgement — for a document you are starting now, physics2 is the safe choice; for an existing physics document, weigh the cost of rewriting against the side effects on \div, \Re and \qty. If derivatives are all you are after, the derivative package handles high orders and several variables cleanly, and fixdif tidies up how differential operators are set.

The braket package — uppercase stretches, lowercase does not

If Dirac notation is all you need, Donald Arseneau's braket is the minimal answer. One line, \usepackage{braket}, and there are only two families of commands: the fixed-size lowercase \bra{ }, \ket{ }, \braket{ }, \set{ }, and the auto-stretching uppercase \Bra{ }, \Ket{ }, \Braket{ }, \Set{ }. The advantage of the uppercase forms is that a vertical bar | written directly inside the argument stretches along with the outer fences. In \Braket every interior | grows to the height of the arguments; in \Set the first | grows. For a double bar use \|, or its local alias ||.

% braket: one argument, the bars written inside it
\Braket{ \phi | \frac{\partial^2}{\partial t^2} | \psi }

\Set{ x \in \mathbf{R}^2 | 0 < {|x|} < 5 }

Note that the arguments are counted differently from physics. physics's \braket{a}{b} takes two arguments, while braket's \braket{a|b} takes one, and you write the dividing bar yourself. In the example above, the first sets the matrix element ⟨φ| ∂²/∂t² |ψ⟩, with the outer angle brackets and both interior bars stretched to the height of the operator. The second sets the set { x ∈ R² | 0 < |x| < 5 }, stretching the outer braces and the dividing bar while the inner |x|, wrapped as {|x|}, stays at a fixed size. Note also that braket does not define an outer-product \ketbra; the author recommends writing \ket{ }\bra{ } instead.

The tensor package — upper and lower indices in the right order

In tensors the horizontal position of an index is itself meaningful. In Γ^μ_{νρ} or R^μ_ν{}^ρ_σ the upper and lower indices must run in the correct order from the left. But writing ^ and _ naively in succession stacks them at the same position, and you can no longer tell which index comes first. The package that solves this is Philip G. Ratcliffe's tensor (a complete revision of Mike Piff's original, v2.2). It needs no external packages; \usepackage{tensor} is enough.

\[
  M\indices{^a_b^{cd}_e}, \qquad
  \tensor{M}{^a_b^{cd}_e}, \qquad
  \tensor[^a_b^c_d]{M}{^e_f^g_h}
\]

% works in text mode as well as math mode
\nuclide[14][6]{C}

There are two central commands. The lightweight \indices goes right after the tensor body and takes only the index string: write M\indices{^a_b^{cd}_e} and you get M followed by an upper a, lower b, upper cd and lower e, each holding its correct horizontal position. Inside the string you use ^ and _ directly, grouping multi-character indices with braces as in ^{cd} (\sp and \sb do the same job). The other command, \tensor, is backward compatible with Mike Piff's original and takes the body and the index string as separate arguments. \tensor{M}{^a_b^{cd}_e} produces the same output as the \indices example, but the strength of \tensor is that it can place indices before the body, passing a pre-index string in the optional first argument. Both have starred forms, \indices* and \tensor*, which collapse the spacing between indices to a more standard look. Additionally, a * at the start of the index string left-aligns the successive upper/lower pairs.

As a bonus, \nuclide is defined, and it works in both text mode and math mode. \nuclide[14][6]{C} sets ¹⁴₆C, placing the mass number 14 at the upper left and the atomic number 6 at the lower left of the element symbol C (both numbers are optional). Note that inside the index string a multi-token index must always be grouped in braces, and constructs such as \mathrm have to be fully enclosed too — write \indices{_{\mathrm{H}}^x}.

So which package should you use?

The conclusion from the measurements is: do not start a new document on physics. An argument silently discarded, \div and \Re changing meaning, a clash with siunitx that load order does not resolve — all three happen without a warning. That said, physics remains widely used, and a manuscript handed over by a co-author may well be written with it. In that case the realistic course is not to rewrite it, but to work with it knowing that \divisionsymbol, \real and \imaginary exist and that the (g) trap is there. The table below sorts the choice by what you are doing.