Lagrange2D: A Mathematica package for Lagrangian analysis of two-dimensional fluid flows

William Gilpin

REVIEW 3 major objections 5 minor 16 references

Lagrange2D: A Mathematica package for Lagrangian analysis of two-dimensional fluid flows

T0 review · 3 major / 5 minor · reviewed 2026-08-14 · deepseek-v4-flash

Challenge this review Re-run · record.json Download PDF Read on arXiv ↗ Review JSON

Pith's one-line read A self-contained Mathematica package computes the full set of Lagrangian transport diagnostics—FTLE fields, stretching directions, Kaplan-Yorke dimension, flushing times—from any specified two-dimensional, time-varying velocity field.

desk verdict Useful Mathematica package for Lagrangian diagnostics, but the printed FTLE formula is not the standard one; a referee must check the code to see whether the headline output is correct. read the letter →

arxiv 1908.00717 v1 pith:P77A5Q6O submitted 2019-08-02 physics.flu-dyn physics.comp-ph

William Gilpin This is my paper · ORCID

classification physics.flu-dynphysics.comp-ph

keywords Lagrangiantransportfinite-timeLyapunovexponentscoherentstructuresKaplan-Yorkedimensionflushingtimetwo-dimensionalfluidflowMathematicapackagetrajectoryintegration

verification ladder T0 review T1 audit T2 compute T3 formal

The pith

A machine-rendered reading of the paper's core claim, the machinery that carries it, and where it could break.

The reading

The paper introduces Lagrange2D, a Mathematica package intended to take an arbitrary two-dimensional, time-varying velocity field, specified either analytically or numerically, and produce the usual Lagrangian diagnostics: finite-time Lyapunov exponent fields, stretching vector fields, a Kaplan-Yorke fractal-dimension field, and flushing times, along with pathline plots and animations of advected tracers. The motivation is that unsteady flows are poorly summarized by Eulerian snapshots, and existing Lagrangian tools live in MATLAB and Python, which makes symbolic analysis of analytically defined flows awkward. The package advects a mesh of initial conditions, interpolates the resulting displacement map, and derives all diagnostics from that one map by finite differences, so no separate machinery is needed for each quantity. The paper demonstrates the workflow on the double-gyre flow and reports that ridges in the computed maximal FTLE field line up with the material barriers seen when a blob of particles is advected. The central claim is that users can obtain all of these quantities from a few short commands in a symbolic algebra environment.

What carries the argument

The carrier of the argument is the finite-time flow map $\varphi^\tau_0$. The package builds it by taking a mesh of initial conditions, integrating each trajectory forward for a duration $\tau$ with a variable-step integration scheme, and interpolating the resulting displacement field with Mathematica's built-in interpolation. All subsequent quantities are finite-difference derivatives of that map: FTLE comes from the logarithm of its deformation gradient (Eq. 1), stretching lines from the associated eigenvectors, the Kaplan-Yorke dimension from a ranked combination of the exponents (Eq. 2), and flushing times from trajectory exit statistics. Because the interpolation replaces the raw trajectory endpoints with a smooth map, the same object can be differentiated many times for different diagnostics without re-integrating.

What would settle it

Run findMaxFTLEField on a uniform shear flow $v_x = \dot{\gamma} y$ (or any flow with a known closed-form deformation gradient), and compare the returned field with $\frac{1}{2\tau}\log\lambda_{\max}\big((\nabla\varphi)^\top\nabla\varphi\big)$. If the output matches Eq. (1)'s $\frac{1}{\tau}\log\lambda_{\max}(\nabla\varphi)$ instead, the package is not computing the standard FTLE; if it matches the Cauchy-Green expression, the printed formula is a typo and the central claim stands.

Watch

Extended reading notes

Core claim

The central claim is that a single, self-contained package can take a two-dimensional unsteady velocity field and return the full set of Lagrangian transport diagnostics without any additional software. Given an analytic or interpolated velocity field $(v_x,v_y)(x,y,t)$, Lagrange2D numerically integrates an ensemble of trajectories from a user-supplied mesh, interpolates the finite-time flow map $\varphi^\tau_0$ that sends each initial position to its position after a time $\tau$, and then uses finite-difference operations on that map to compute the maximal finite-time Lyapunov exponents (Eq. 1), the maximal and minimal stretching vector fields, the Kaplan-Yorke dimension (Eq. 2), and the flushing-time field. All of these are presented as outputs of a common trajectory integration, so the same mesh and integration duration serve every diagnostic. The paper claims this approach is accurate enough that FTLE ridges coincide with the kinetic barriers visible in particle advection, and that the stretching and flushing-time fields reveal the expected asymmetry of the flow.

Load-bearing premise

Everything hinges on whether the package's Lyapunov-exponent output matches the standard definition; Eq. (1) as printed takes the logarithm of the deformation-gradient matrix itself, rather than of the symmetric Cauchy-Green strain tensor, and no test in the paper shows the two agree.

Editorial extensions

If this is right

Users can go from an analytic flow definition to FTLE fields, stretching fields, and videos in a few notebook commands, without writing trajectory-integrating code.
FTLE ridges computed by the package provide candidate Lagrangian coherent structures for flows that lack closed-form transport barriers, offering a quick screen for eddies and manifolds.
The Kaplan-Yorke dimension field gives a spatially resolved, time-scale-dependent picture of where particles cluster, distinguishing regions of filamentation from regions with no localization tendency.
Flushing-time fields can be computed on any user-specified domain and integration window, directly quantifying residence-time asymmetries in unsteady flows.
Because the package is self-contained, it can be used inside a symbolic setting to compare transport properties across many analytic flows with little setup cost.

Reading between the lines

Editorial extensions of the paper, not claims the author makes directly.

If the printed Eq. (1) is what the code implements, the FTLE output is not the standard finite-time Lyapunov exponent: standard FTLE uses the largest eigenvalue of the Cauchy-Green strain tensor $(\nabla\varphi)^\top\nabla\varphi$ with a prefactor $1/(2\tau)$, not the logarithm of $\nabla\varphi$ alone. Checking the package output against this definition on a flow with a known deformation gradient
The same interpolated flow-map construction could support additional deformation-gradient diagnostics, such as finite-time rotation, stretching angle, or Okubo-Weiss-type invariants, with no new trajectory integrations, since the map is already available.
Because the package accepts numerically specified velocity fields, it could in principle be coupled with experimentally measured particle-image-velocimetry fields, although the paper only demonstrates analytic flows.

Share X Bluesky LinkedIn Reddit HN

Signed reviews

No signed human review yet.

Editorial analysis

A structured set of objections, weighed in public.

Desk editor's note, referee report, and a circularity audit.

Desk Editor's Note

read the letter

Colleague,

Here is my take on the Lagrange2D paper. What is actually new is the package itself: a single Mathematica interface that bundles trajectory integration, FTLE fields, stretching vectors, Kaplan-Yorke dimension, flushing times, pathlines, and video export. For people who work with analytically defined velocity fields in a symbolic environment, that is genuinely convenient; the established MATLAB/Python tools like LCS Tool and PATATO do not offer that integration. The code is public, GPLv3, and comes with a demo notebook, and the double-gyre examples look qualitatively reasonable. The citation pattern is fine: the LCS literature is standard, and the one self-citation to Flowtrace is contextual, not load-bearing.

The soft spot is the printed definition of FTLE. Equation (1) defines λ(r) = (1/τ) max[eig(log(dφ/dr))]. That is not the standard finite-time Lyapunov exponent, which is (1/(2τ)) log λ_max((dφ/dr)ᵀ(dφ/dr)). The printed formula omits the factor 1/2 and applies the logarithm to the deformation gradient rather than the symmetric Cauchy–Green tensor. For simple shear, the deformation gradient has unit eigenvalues, so Eq. (1) gives zero while the standard FTLE is positive. The formula is also rotation-sensitive in a way FTLE should not be. The solution-method text says FTLE is computed by finite differences on the interpolated displacement map, which is consistent with either definition, so the paper does not tell the reader which one the code implements. No benchmark against LCS Tool or an analytic flow is provided, and Figure 1D is only qualitative. A smaller issue: the code listing contains an unused definition of g, which is minor.

If the package source implements the standard Cauchy–Green formula and Eq. (1) is simply a typo, then this is a solid software paper needing a corrected formula and a validation figure. If the code implements Eq. (1) literally, the package's headline output is not FTLE and the central utility claim fails. Since the source is on GitHub, a referee can resolve this in an hour. Given that the package is a serious, self-contained contribution and the issue is checkable, I would send it to peer review rather than desk reject. The author should be asked to verify the implementation against a known case and fix Eq. (1).

Referee Report

3 major / 5 minor

Summary. The manuscript describes Lagrange2D, an open-source Mathematica package for Lagrangian analysis of two-dimensional time-varying fluid flows. It provides functions for advecting tracer ensembles, computing finite-time Lyapunov exponent (FTLE) fields, stretching vector fields, a Kaplan-Yorke dimension field, flushing/residence times, pathline plots, and videos. The theoretical background is presented in Sections 2.1 and 2.2, and a double-gyre example with six figure panels is used to illustrate the package's capabilities. The claimed contribution is a self-contained, easy-to-install tool that lets users go from an analytic or numerical velocity field to standard Lagrangian diagnostics in a single environment.

Significance. Software papers of this type are valuable when the implementations faithfully encode standard definitions and are vetted against known cases. The manuscript's strengths are the package's simple call syntax, absence of external dependencies, documentation, demo notebook, and the inclusion of video and mesh utilities. If the implementation matches the standard FTLE definition, the package would be a convenient complement to existing MATLAB/Python tools, especially for analytic flows in a symbolic environment. However, the paper does not include quantitative benchmarks or convergence tests, and the printed FTLE definition in Eq. (1) does not match the standard Cauchy-Green formulation; because FTLE is the headline diagnostic, the central claim is currently not established. The paper contains no fitted parameters and no circular reasoning; the risk is purely one of correctness and validation.

major comments (3)

[Section 2.1, Eq. (1)] The printed definition λ(r) ≡ (1/τ) max[eig(log(dφτ0/dr))] is not the standard finite-time Lyapunov exponent. The standard FTLE is λ_τ(r) = (1/(2τ)) log λ_max(C), where C = (dφ/dr)^T (dφ/dr) is the right Cauchy-Green tensor. The manuscript's formula both omits the factor 1/2 and takes eigenvalues of the deformation gradient rather than of the strain tensor. For simple shear, this formula gives zero identically even though material lines stretch, and for a solid-body rotation it gives imaginary or otherwise ambiguous eigenvalues. Thus either Eq. (1) is a documentation error and the package actually computes the standard FTLE, or the package's principal output is not FTLE as commonly understood. The manuscript must state which, show the relevant implementation, and benchmark against an analytic or existing-tool FTLE calculation.
[Section 3 and Program Summary, 'Solution method'] No quantitative validation is provided. Figure 1D is qualitative, with no comparison to a ground-truth FTLE field, no mesh-refinement or integration-tolerance convergence study, and no run-time benchmarking. Because the central claim is that Lagrange2D computes standard quantities such as Lyapunov exponents, the paper should include at least one convergence check and one comparison against a published implementation or an exact solution.
[Section 2.2, Eq. (2) and Figure 1E] For a two-dimensional incompressible flow the Lyapunov spectrum obeys λ1 + λ2 = 0, so the Kaplan-Yorke formula gives DKY = 2 identically. The text explicitly acknowledges j = 1 for incompressible flows but then presents a spatially varying DKY field for the double gyre, which is incompressible. It is not explained whether the variation arises from numerical violation of incompressibility, from a finite-time estimate, or from a different object entirely; this needs clarification because it affects the validity of the findKYDim diagnostic.

minor comments (5)

[Section 2.2, after Eq. (2)] The sentence 'we use estimates of the Lyapunov exponents generated by the FTLE calculation in (2)' should refer to Eq. (1), not Eq. (2), which is the Kaplan-Yorke definition.
[Figure 1 caption] The caption says panel D was generated using the function findFTLE, but Table 1 lists findFTLEField and findMaxFTLEField; the naming should be consistent.
[Section 3.0.1, code listing] The function g[t_, x_, y_] is defined in the example code but never used; it should be removed or explained.
[Section 2.1] The notation 'max[eig(log(...))]' is nonstandard; if Eq. (1) is corrected, the authors should define λ_max(C) explicitly and state the 1/(2τ) factor clearly.
[References] The definition of the finite-time Lyapunov exponent is attributed to review articles [6,7]; a primary citation for the definition and the Cauchy-Green strain tensor interpretation should be added.

Circularity Check

0 steps flagged · score 0.0 of 10

No significant circularity: the package implements established Lagrangian diagnostics from cited literature, with no fitted parameter renamed as a prediction.

full rationale

The paper is a software description, not a derivation of a new physical result. Its central claim is that Lagrange2D computes standard Lagrangian quantities (FTLE fields, stretching vectors, Kaplan-Yorke dimension, flushing times) from a user-supplied velocity field. These quantities are defined in the paper by explicit formulas or by reference to cited prior work: Eq. (1) defines the finite-time Lyapunov exponent, Eq. (2) defines the Kaplan-Yorke dimension, and the double-gyre example is taken from Shadden et al. [16]. There is no fitted parameter that is later renamed as a prediction, and no uniqueness theorem or ansatz is imported from the author's own prior work. The only self-citation, Flowtrace [8], appears in the introduction as an example of biological fluid-flow applications and is not load-bearing for any computation in the package. The reader-flagged issue that Eq. (1) does not match the standard Cauchy-Green-strain definition of FTLE is a correctness concern about the printed formula or the implementation, not a circularity: even if the code follows Eq. (1) literally, that would make the output a nonstandard diagnostic, but it would not make the package's claims equivalent to its inputs by construction. Since no circular reduction or self-citation chain is evident, the appropriate finding is no significant circularity (score 0).

Assumptions & free parameters 0 free parameters · 3 assumptions · 0 invented entities

No free parameters are fitted to data; the example double gyre parameters A, epsilon, omega, integration time tau, and mesh sizes are user-specified demonstrations. The package relies on standard numerical integration and interpolation assumptions. No new physical entities are introduced.

assumptions (3)

domain assumption Standard FTLE is a valid diagnostic of Lagrangian coherent structures via ridges in the FTLE field.
The package's purpose is to compute and visualize FTLE-based LCS metrics; the paper cites Haller and Yuan (2000) and Shadden et al. (2005) but does not itself establish the physical validity of ridge-based LCS.
domain assumption Mathematica's Interpolate provides a displacement map whose numerical derivatives are accurate enough for FTLE and stretching computations.
Section 2.1: the flow map is built using Mathematica's built-in Interpolate; no error or convergence analysis is provided for interpolation of the deformation gradient.
domain assumption The Kaplan-Yorke dimension computed from finite-time Lyapunov exponents estimates the clustering tendency in unsteady flows.
Section 2.2 uses FTLE estimates as Lyapunov exponents to define a timescale-dependent D_KY; the relationship between finite-time dimension fields and attractor dimension is assumed.

how reviews work

0 comments

Cite this review

Pith. "Pith review of Lagrange2D: A Mathematica package for Lagrangian analysis of two-dimensional fluid flows." pith.science (2026). https://pith.science/paper/P77A5Q6O

@misc{pith2026190800717,
  author       = {Pith},
  title        = {Pith review of: Lagrange2D: A Mathematica package for Lagrangian analysis of two-dimensional fluid flows},
  year         = {2026},
  howpublished = {\url{https://pith.science/paper/P77A5Q6O}},
  note         = {Machine review of arXiv:1908.00717}
}

read the original abstract

We introduce Lagrange2D, a Mathematica package for analysis and characterization of complex fluid flows using Lagrangian transport metrics. Lagrange2D includes built-in functions for integrating ensembles of trajectories subject to time-varying two-dimensional flows, as well as utilities for calculating various quantities of interest, such as finite-time Lyapunov exponents, stretching vector fields, the fractal dimension, and flushing times. The package also includes tools for visualizing transport and pathlines, as well as for generating videos. This package aims to ease rapid characterization of arbitrary flows, by allowing identification of Lagrangian coherent structures and other quantities of interest. The open-source code for the package is available on GitHub at: \url{https://github.com/williamgilpin/lagrange2d}

Figures

Figures reproduced from arXiv: 1908.00717 by the authors.

**Figure 1.** Example plots produced by Lagrange2D. (A) Streamlines of the timedependent “double gyre” flow, generated at times corresponding to times when the flow is maximally symmetric (blue) and maximally asymmetric (red). (B) Pathlines for particles advected by the double gyre flow, generated using the function pathPlot. (C) The motion of a blob of particles advected by the flow, with successive timepoints indicated in dark… view at source ↗

Discussion (0). Continue with ORCID to comment.

Reference graph

Works this paper leans on

16 extracted references · 16 canonical work pages

[1]

Bennett, et al., Lagrangian ﬂuid dynamics, Cambridge University Press, 2006

A. Bennett, et al., Lagrangian ﬂuid dynamics, Cambridge University Press, 2006

work page 2006
[2]

Samelson, Lagrangian motion, coherent structures, and lines of per- sistent material strain, Annual review of marine science 5 (2013) 137– 163

R. Samelson, Lagrangian motion, coherent structures, and lines of per- sistent material strain, Annual review of marine science 5 (2013) 137– 163

work page 2013
[3]

J. F. Price, Lagrangian and eulerian representations of ﬂuid ﬂow: Kine- matics and the equations of motion, MIT OpenCourseWare, 2006

work page 2006
[4]

Falkovich, Fluid mechanics: A short course for physicists, Cambridge University Press, 2011

G. Falkovich, Fluid mechanics: A short course for physicists, Cambridge University Press, 2011

work page 2011
[5]

Haller, G

G. Haller, G. Yuan, Lagrangian coherent structures and mixing in two- dimensional turbulence, Physica D: Nonlinear Phenomena 147 (3-4) (2000) 352–370

work page 2000
[6]

Haller, Lagrangian coherent structures, Annual Review of Fluid Me- chanics 47 (2015) 137–162

G. Haller, Lagrangian coherent structures, Annual Review of Fluid Me- chanics 47 (2015) 137–162

work page 2015
[7]

S. C. Shadden, Lagrangian coherent structures, Transport and Mixing in Laminar Flows: From Microﬂuidics to Oceanic Currents (2011) 59–89

work page 2011
[8]

Gilpin, V

W. Gilpin, V. N. Prakash, M. Prakash, Flowtrace: simple visualization of coherent structures in biological ﬂuid ﬂows, Journal of Experimental Biology 220 (19) (2017) 3411–3418

work page 2017

Show all 16 references

[9]

S. C. Shadden, J. O. Dabiri, J. E. Marsden, Lagrangian analysis of ﬂuid transport in empirical vortex ring ﬂows, Physics of Fluids 18 (4) (2006) 047105

2006
[10]

K. Onu, F. Huhn, G. Haller, Lcs tool: A computational platform for la- grangian coherent structures, Journal of Computational Science 7 (2015) 26–36. 11

2015
[11]

Fredj, D

E. Fredj, D. F. Carlson, Y. Amitai, A. Gozolchiani, H. Gildor, The particle tracking and analysis toolbox (patato) for matlab, Limnology and Oceanography: Methods 14 (9) (2016) 586–599

2016
[12]

J. Peng, J. Dabiri, Transport of inertial particles by lagrangian coherent structures: application to predator–prey interaction in jellyﬁsh feeding, Journal of Fluid Mechanics 623 (2009) 75–84

2009
[13]

Kaplan, J

J. Kaplan, J. Yorke, Functional diﬀerential equations and approximation of ﬁxed points, Lecture notes in mathematics 730 (1979) 204–227

1979
[14]

R. D. Vilela, V. M. de Oliveira, A map for heavy inertial particles in ﬂuid ﬂows, The European Physical Journal Special Topics 226 (9) (2017) 2079–2088

2017
[15]

Tuval, J

I. Tuval, J. Schneider, O. Piro, T. T´ el, Opening up fractal structures of three-dimensional ﬂows via leaking, EPL (Europhysics Letters) 65 (5) (2004) 633

2004
[16]

S. C. Shadden, F. Lekien, J. E. Marsden, Deﬁnition and properties of lagrangian coherent structures from ﬁnite-time lyapunov exponents in two-dimensional aperiodic ﬂows, Physica D: Nonlinear Phenomena 212 (3-4) (2005) 271–304. 12

2005

Pith tools

Reviewed August 14, 2026 · model on record in the stance chip above.

[1] [1]

Bennett, et al., Lagrangian ﬂuid dynamics, Cambridge University Press, 2006

A. Bennett, et al., Lagrangian ﬂuid dynamics, Cambridge University Press, 2006

work page 2006

[2] [2]

Samelson, Lagrangian motion, coherent structures, and lines of per- sistent material strain, Annual review of marine science 5 (2013) 137– 163

R. Samelson, Lagrangian motion, coherent structures, and lines of per- sistent material strain, Annual review of marine science 5 (2013) 137– 163

work page 2013

[3] [3]

J. F. Price, Lagrangian and eulerian representations of ﬂuid ﬂow: Kine- matics and the equations of motion, MIT OpenCourseWare, 2006

work page 2006

[4] [4]

Falkovich, Fluid mechanics: A short course for physicists, Cambridge University Press, 2011

G. Falkovich, Fluid mechanics: A short course for physicists, Cambridge University Press, 2011

work page 2011

[5] [5]

Haller, G

G. Haller, G. Yuan, Lagrangian coherent structures and mixing in two- dimensional turbulence, Physica D: Nonlinear Phenomena 147 (3-4) (2000) 352–370

work page 2000

[6] [6]

Haller, Lagrangian coherent structures, Annual Review of Fluid Me- chanics 47 (2015) 137–162

G. Haller, Lagrangian coherent structures, Annual Review of Fluid Me- chanics 47 (2015) 137–162

work page 2015

[7] [7]

S. C. Shadden, Lagrangian coherent structures, Transport and Mixing in Laminar Flows: From Microﬂuidics to Oceanic Currents (2011) 59–89

work page 2011

[8] [8]

Gilpin, V

W. Gilpin, V. N. Prakash, M. Prakash, Flowtrace: simple visualization of coherent structures in biological ﬂuid ﬂows, Journal of Experimental Biology 220 (19) (2017) 3411–3418

work page 2017