Add type hints in Python by DomFijan · Pull Request #1399 · glotzerlab/freud

DomFijan · 2026-03-05T21:33:08Z

This PR adds missing type hinting for Python function returns.

Description

Many Python functions have missing type hints.

Motivation and Context

Resolves: #1311

How Has This Been Tested?

Locally run mypy succesfully.

Checklist:

I have reviewed the Contributor Guidelines.
I agree with the terms of the Freud Contributor Agreement.
My name is on the list of contributors in the pull request source branch.
I have updated the Change log.

janbridley · 2026-03-06T14:29:11Z

freud/box.py


    @L.setter
-    def L(self, value):
+    def L(self, value: ScalarLike | Sequence[ScalarLike]) -> None:


In cases like this where the valid sequences have a fixed length, I think it might be better to use tuple[ScalarLike, ScalarLike, Scalarlike]. A little more verbose, but gives you meaningful feedback if you pass an incorrectly typed input

janbridley · 2026-03-06T14:30:02Z

freud/box.py

-    def make_absolute(self, fractional_coordinates, out=None):
+    def make_absolute(
+        self, fractional_coordinates: ArrayLike, out: ArrayLike | None = None
+    ) -> npt.NDArray[np.floating]:


We defined FloatArray, could we use that as the return?

janbridley · 2026-03-06T14:30:26Z

freud/box.py

        return np.squeeze(out) if flatten else out

-    def get_images(self, vecs):
+    def get_images(self, vecs: ArrayLike) -> npt.NDArray[np.integer]:


And intarray -- I think we can swap these all out with ruplacer

janbridley · 2026-03-06T14:32:15Z

freud/data.py

-    def __init__(self, box, basis_positions=None):
+    def __init__(
+        self, box: freud.box.Box | ArrayLike, basis_positions: ArrayLike | None = None
+    ) -> None:
        if basis_positions is None:
            basis_positions = [[0, 0, 0]]


Because we automatically convert basis_positions if it is None, could we instead set the default to basis_positions=((0,0,0),)?

janbridley · 2026-03-06T14:38:08Z

freud/diffraction.py

-    def to_image(self, cmap="afmhot", vmin=None, vmax=None):
+    def to_image(
+        self, cmap: str = "afmhot", vmin: float | None = None, vmax: float | None = None
+    ) -> np.ndarray:


Suggested change

) -> np.ndarray:

) -> npt.NDArray[np.uint8]:

Full shape annotation is not supported but it's nice to mark this as uint8 imo

janbridley · 2026-03-06T14:40:01Z

freud/locality.py

+NeighborQueryDict = dict[str, object]
+
+
+class _CPPNPoint(Protocol):
+    def getQueryPointIdx(self) -> int: ...
+    def getPointIdx(self) -> int: ...
+    def getDistance(self) -> float: ...
+
+
+class _CPPNeighborList(Protocol):
+    def copy(self, other: object) -> None: ...
+    def getNeighbors(self) -> _CPPIntArray: ...
+    def getWeights(self) -> _CPPFloatArray: ...
+    def getDistances(self) -> _CPPFloatArray: ...
+    def getVectors(self) -> _CPPFloatArray: ...
+    def getSegments(self) -> _CPPIntArray: ...
+    def getCounts(self) -> _CPPIntArray: ...
+    def getNumBonds(self) -> int: ...
+    def getNumQueryPoints(self) -> int: ...
+    def getNumPoints(self) -> int: ...
+    def find_first_index(self, i: int) -> int: ...
+    def filter(self, filt: ArrayLike) -> None: ...
+    def filter_r(self, r_max: ScalarLike, r_min: ScalarLike) -> None: ...
+    def sort(self, by_distance: bool) -> None: ...
+
+
+class _CPPNeighborIterator(Protocol):
+    def next(self) -> _CPPNPoint: ...
+    def toNeighborList(self, sort_by_distance: bool) -> _CPPNeighborList: ...
+
+
+class _CPPNeighborQuery(Protocol):
+    def query(self, points: ArrayLike, query_args: object) -> _CPPNeighborIterator: ...
+    def getBox(self) -> freud.box._CPPBox: ...
+
+
+class _CPPLinkCell(_CPPNeighborQuery, Protocol):
+    def getCellWidth(self) -> float: ...
+
+
+class _CPPFloatArray(Protocol):
+    def toNumpyArray(self) -> npt.NDArray[np.floating]: ...
+
+
+class _CPPIntArray(Protocol):
+    def toNumpyArray(self) -> npt.NDArray[np.integer]: ...
+
+
+class _CPPSpatialHistogram(Protocol):
+    mode: int
+
+    def getBox(self) -> freud.box._CPPBox: ...
+    def getBinCounts(self) -> _CPPFloatArray: ...
+    def getBinCenters(self) -> Sequence[npt.NDArray[np.floating]]: ...
+    def getBinEdges(self) -> Sequence[npt.NDArray[np.floating]]: ...
+    def getBounds(self) -> list[tuple[float, float]] | tuple[float, float]: ...
+    def getAxisSizes(self) -> list[int] | int: ...
+    def reset(self) -> None: ...
+    def accumulate(self, *args: object) -> None: ...
+    def getCorrelation(self) -> _CPPFloatArray: ...
+    def getNBins(self) -> int: ...
+    def accumulateRDF(self, *args: object) -> None: ...
+    def getRDF(self) -> _CPPFloatArray: ...
+    def getNr(self) -> _CPPFloatArray: ...
+    def getBondOrder(self) -> _CPPFloatArray: ...
+    def getMode(self) -> _CPPModeEnum: ...
+    def getPCF(self) -> _CPPFloatArray: ...
+
+
+class _CPPModeEnum(Protocol):
+    name: str
+
+
+class _CPPVoronoi(Protocol):
+    def compute(self, query: _CPPNeighborQuery) -> None: ...
+    def getPolytopes(self) -> Sequence[Sequence[Sequence[float]]]: ...
+    def getVolumes(self) -> _CPPFloatArray: ...
+    def getNeighborList(self) -> _CPPNeighborList: ...
+
+
+class _CPPFilter(Protocol):
+    def compute(
+        self,
+        query: _CPPNeighborQuery,
+        query_points: FloatArray,
+        nlist: _CPPNeighborList,
+        qargs: object,
+    ) -> None: ...
+    def getFilteredNlist(self) -> _CPPNeighborList: ...
+    def getUnfilteredNlist(self) -> _CPPNeighborList: ...
+
+
+class _MDATimestep(Protocol):
+    triclinic_dimensions: ArrayLike
+    positions: ArrayLike
+
+
+class _ConfigurationLike(Protocol):
+    box: ArrayLike
+    dimensions: int
+
+
+class _ParticlesWithPosition(Protocol):
+    position: ArrayLike
+
+
+class _SnapshotLike(Protocol):
+    configuration: _ConfigurationLike
+    particles: _ParticlesWithPosition
+
+
+class _GarnettFrame(Protocol):
+    box: object
+    positions: ArrayLike
+
+
+class _GarnettFrameNew(_GarnettFrame, Protocol):
+    position: ArrayLike
+
+
+class _Hoomd2Box(Protocol):
+    dimensions: int
+    Lx: float
+    Ly: float
+    xy: float
+
+
+class _Hoomd2Particles(Protocol):
+    position: ArrayLike
+
+
+class _Hoomd2Snapshot(Protocol):
+    box: _Hoomd2Box
+    particles: _Hoomd2Particles
+
+
+class _OvitoCell(Protocol):
+    matrix: FloatArray
+    is2D: bool  # noqa: N815 - external API naming
+
+
+class _OvitoParticles(Protocol):
+    positions: ArrayLike
+
+
+class _OvitoCollection(Protocol):
+    cell: _OvitoCell
+    particles: _OvitoParticles
+
+
+class _SystemWithBoxPoints(Protocol):
+    box: object
+    points: ArrayLike


We could consider moving this to a freud/locality_typing.py or similar?

janbridley · 2026-03-06T14:41:10Z

freud/locality.py

 import inspect
+from collections.abc import Iterator, Mapping, Sequence
 from importlib.util import find_spec
+from typing import TYPE_CHECKING, Literal, Protocol, cast


Even in Python we end up with reinterpret cast, it truly is inevitable

janbridley · 2026-03-06T14:44:06Z

I'm generally happy with these changes, just a few consistency questions and a nitpick here or there. This will be quite useful to have, it's remarkable to see how far python typing has come.

As a quick heads-up: while the typing is correct at a hight level there are many cases where we don't formally satisfy all the requirements. I don't think this really matters but it does cause a lot of typing errors in LSPs:

DomFijan added 2 commits March 2, 2026 19:25

add type hints in python

30d8f7c

ruff

51487bd

DomFijan requested a review from janbridley March 5, 2026 21:36

DomFijan added 4 commits March 5, 2026 16:46

add missing _typing.py file to cmake lists

a5dcae5

fix msd's Axes typing

8be47e5

fix MSD quotes

a37b351

appease prek import sorting

66fec81

janbridley reviewed Mar 6, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add type hints in Python#1399

Add type hints in Python#1399
DomFijan wants to merge 6 commits intomainfrom
feat/add_type_hints

DomFijan commented Mar 5, 2026

Uh oh!

janbridley Mar 6, 2026

Uh oh!

janbridley Mar 6, 2026

Uh oh!

janbridley Mar 6, 2026

Uh oh!

janbridley Mar 6, 2026

Uh oh!

janbridley Mar 6, 2026 •

edited

Loading

Uh oh!

janbridley Mar 6, 2026

Uh oh!

janbridley Mar 6, 2026 •

edited

Loading

Uh oh!

janbridley commented Mar 6, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

DomFijan commented Mar 5, 2026

Description

Motivation and Context

How Has This Been Tested?

Checklist:

Uh oh!

janbridley Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

janbridley Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

janbridley Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

janbridley Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

janbridley Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janbridley Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

janbridley Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janbridley commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

janbridley Mar 6, 2026 •

edited

Loading

janbridley Mar 6, 2026 •

edited

Loading

janbridley commented Mar 6, 2026 •

edited

Loading