Introduction

The Python code for computing Coherent Structures based on Finite-Time-Lyapunov Exponents (FTLE) and Lagrangian deformation for flow on curved surfaces is available at this link. The following tutorial provides instructions on how to use the code. To understand the mathematical background or additional information on the methods discussed here, we refer you to the accompanying manuscript S. Santhosh, C. Zhu, B. Fencil, M. Serra.

Introduction To Curved Surface FTLE

Pre-requisites

This code was built in Python 3.11, on a Windows 10 system. The following python packages are needed and can be installed with pip in your Python environment:

  • Numpy
  • Pyvista
  • Scipy
  • Matplotlib
  • Numba
  • ffmpeg-python

Note that ffmpeg needs to be installed system wide via apt, brew, or from https://ffmpeg.org/download.html, in order for the python wrapper for ffmpeg to work.

Installation

To install the code, navigate to the path where you would want to install it on the terminal and clone the GitHub repository using the command:

git clone  https://github.com/bfencil/CurvedSurfacesFTLEPython.git
cd CurvedSurfacesFTLEPython
pip install -r requirements.txt

Data required for Langrangian analaysis and Formating

To perform the Lagrangian analysis, we require the velocity field \(\mathbf{v}(\mathbf{x},t)\) that quantifies the material flow on a manifold \(\mathbf{x}\in\mathcal{M}(t)\). The Lagrangian Analysis method that we describe here works well for both static surfaces, where the manifold on which the flow happens is time-independent, and dynamic surfaces, where the manifold on which the flow happens is time-dependent.

NOTE: Obtaining velocity data from tissue mechanics and active nematic simulations is relatively simple, but obtaining them from experimental live imaging of biological systems is more difficult. Several methods exist to extract this information, such as ImSAnE and TubULAR.

The manifold information \(\mathcal{M}\) is stored as a mesh with discrete node points \(\mathbf{x}_i=[x_i,y_i,z_i]\) , where \(i\in\{1,N_p(t)\}\) and \(N_p(t)\) is total number of nodes on the manifold at time \(t\). The connectivity of the mesh is given by a triangulation \(T\) which is a set of all the mesh faces. Each face \(j\in\{1,N_f(t)\}\) consists of set of three nodes \(\{i_1,i_2,i_3\}\) that form face \(j\). \(N_f(t)\) denotes the total number of faces on the mesh at time \(t\). The velocity field is stored as \(\mathbf{v}_i(t)=[v_i^1(t),v_i^2(t),v_i^3(t)]\) where \(v_i^1(t),v_i^2(t)\) and \(v_i^3(t)\) are the x,y and z-component of the velocity at node \(i\) at time \(t\).

Before you run the Lagrangian analysis, the velocity field data and the manifold on which it is defined need to be loaded into the Python file(i.e from a .h5 file) and have the data strucutre:

  • Time steps: vector of size (\(1,N_t\)), where \(N_t\) is the number of time points of the dataset.
  • Node positions : cell array of size (\(N_t,1\)). Each cell array element x{k} \(k\in\{1,N_t\}\) is vector of size \((N_p(k),1)\) containing the x-coordinate of all the \((N_p(k)\) mesh nodes, where \(N_p(k)\) is the total number mesh nodes at \(t=k\). Similarly, the y and z components of the mesh nodes are stored in y and z.
  • Node connections : cell array of size (\(N_t,1\)). The cell array element TrianT{k} \(k\in\{1,N_t\}\) is a matrix of size \((N_f(k),3)\) whose \(j-th\) raw contains the mesh connectivity of face \(j\) (e.g. \([i_1,i_2,i_3]\) for a mesh face with nodes \(i_1,i_2,i_3\)). \(N_f(k)\) denotes the number of mesh faces at time \(t = k\).
  • Node velocities : cell array of size (\(3,N_t\)) , where the cell array element v{1,k} \(k\in\{1,N_t\}\) is a matrix of size \((N_p(k),1)\) with the x-component of the velocity all the mesh nodes. \(N_p(k)\) is the total number of mesh nodes at \(t = k\). Similarly, the y and z components of the velocity are stored in v{2,k} and v{3,k}.

An example dataset is provided in ./Data/growingSphere.h5 in the Python code directory, which can be visualized by running ./Example/Sphere.py. Running this example for the time frame 0 to 21 for both Forward and Backward FTLE fields we get the following results:

NOTE: An accurate Lagrangian Analysis requires that the mesh representation of the manifold is sampled uniformly, whereby the mesh faces are approximately of equal size; deviation from this may result in spurious results. The finer the mesh faces, the better the accuracy of the advection and deformation computed. If the original data does not meet this requirement, remeshing is recommended.

Performing Lagrangian Analysis

Once you load the data you can run the code by importing the FTLE_mesh function form ftle\Curved\CurvedSurfaceMain.py. There are several parameters to adjust. Alternativily you can edit and load data into CurvedSurfaceMain.py directly in order to run the FTLE_mesh function from there.

  • initial_time , final_time: The interval in the time_steps data you want to run the simulation over.

  • plot_ftle: True, False value for indicating whether to plot the FTLE field over the mesh. The default value is False.

  • save_path: The path to the directory where you want the plot to be saved. The default value is None.

  • camera_setup: This is used for orienting the camera for the save plotting image, this only matters if you choose to specify a save_path. This takes in a tuple of the form (camera_position, camera_focal_point, degree). A good camera_setup can be determined by running the Analysis for when plot_ftle is set to True, which allows for the camera details in the plotting window to be printed out to the terminal.

  • neighborhood: This is the amount of nodes used in the sparse FTLE computations on the mesh. This neighborhood corresponds directly to the amount of nodes about each node of the mesh that go into the FTLE computation. The defualt value is 15.

  • lam: This is a regularization parameter for the FTLE computations the defualt value is \(10^{-10}\). There should be no reason to change this value, however meshes that are unusually sparse or dense may require different values.

References

[1] : Santhosh S., Zhu C., Fencil B., Serra M., preprint (2025), Coherent Structures in Active Flows on Dynamic Surfaces.

Copyright © 2025 Sreejith Santhosh & Mattia Serra