Add lane formation order parameter - #572
Open
aQuetzalcoatlus wants to merge 2 commits into
Open
Conversation
added 2 commits
August 13, 2026 15:30
Implements the order parameter Phi for lane formation in bidirectional flow. Two pedestrians count as sharing a lane when their distance perpendicular to the walking direction is below a threshold gamma. Each pedestrian is assigned an individual order parameter: the difference between the number of same- and opposite-direction lane mates, divided by their sum, squared. This is zero when both directions are equally represented and one when the lane holds a single direction. Phi is the mean of the individual values over all pedestrians. The measure was introduced for pedestrian dynamics by Nowak and Schadschneider (2012), adapting an order parameter from colloidal suspensions, and extended to continuous space by von Kruechten (2019). Walking direction is taken from a species DataFrame as produced by compute_species, rather than computed internally, since the order parameter needs neither Voronoi cells nor a measurement line. Users working with simulation output, where the direction is known at spawn time, can supply the same two columns directly. The perpendicular coordinate is assumed to be y.
schroedtert
reviewed
Aug 14, 2026
schroedtert
left a comment
schroedtert
left a comment
Collaborator
There was a problem hiding this comment.
Just a quick note, without any real reviewing: Plesse also add a the new function to the user guide
Collaborator
Exactly, otherwise review is difficult. |
Author
Ok, I'll add it soon! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the lane formation order parameter from #507.
compute_lane_order_parameterreturns Phi per frame from a trajectory and aspecies DataFrame. Seven unit tests cover the hand-computable cases.
A few decisions I'd like your view on:
Placement. I put it in
spatial_analysis.py, next to the pairdistribution function, since it is also a pairwise structural measure and
fits none of density/speed/flow/profiles. Happy to move it.
Species as an argument. The walking direction is passed in rather than
computed internally, since the order parameter needs neither Voronoi cells
nor a measurement line. Users with simulation output can build the two
columns directly.
Self-counting. Each pedestrian counts itself as a lane mate, so N_L >= 1
and the denominator cannot vanish; an isolated pedestrian scores 1. Neither
Nowak and Schadschneider nor von Krüchten state this explicitly, but the
alternative divides by zero. Four of the tests pin this down.
Perpendicular coordinate. Hard-coded to y, i.e. the corridor is assumed
parallel to the x-axis.
Not included: the reduced order parameter (Nowak and Schadschneider Eq.
12), which corrects for the density dependence of Phi. The docstring warns
about this. It needs a numerical baseline over shuffled species labels, so
it seemed better as a separate PR.