lptlib (Lagrangian Particle Tracking Library)

Previously project-arrakis

Python based particle tracking algorithms for CFD data

A highly parallelized set of Lagrangian Particle Tracking (LPT) algorithms based on Python to post-process steady and unsteady CFD data. An advanced programming interface (API) is developed for uncertainty quantification of optical velocimetry data.

Installation

pip install lptlib

Python >= 3.10 is required. Core dependencies include numpy, scipy, matplotlib, pandas, seaborn, tqdm, mpi4py, and scikit-learn.

Overview

lptlib provides building blocks to:

Read Plot3D grid/flow data (GridIO, FlowIO)
Locate points in structured curvilinear grids (Search)
Interpolate flow variables at arbitrary locations (Interpolation)
Integrate particle paths and streamlines with multiple schemes (Integration, Streamlines)
Run stochastic, parallel particle simulations (StochasticModel, Particle, SpawnLocations)
Compute derived variables like velocity, temperature, pressure, Mach, viscosity (Variables)
Post-process LPT outputs to Eulerian fields and Plot3D files (DataIO)

Quickstart

Read Plot3D grid and flow

from lptlib.io.plot3dio import GridIO, FlowIO

grid = GridIO('path/to/grid.sp.x')
flow = FlowIO('path/to/sol-0000010.q')
grid.read_grid()
flow.read_flow()
grid.compute_metrics()

To read 2D Plot3D-style plane grid files that use Fortran unformatted records (e.g., for an i, j, or k plane), you can use the GridIO helper:

from lptlib.io.plot3dio import GridIO

grid = GridIO('path/to/iplane.grd')
grid.read_grid_fortran_2d(precision='single', plane='i')
xi = grid.grd[..., 0, 0]  # x-coordinates on the plane
yi = grid.grd[..., 1, 0]  # y-coordinates on the plane

Interpolate and integrate a streamline

import numpy as np
from lptlib.streamlines.search import Search
from lptlib.streamlines.interpolation import Interpolation
from lptlib.streamlines.integration import Integration

point = np.array([0.1, 0.05, 0.0])
idx = Search(grid, point)
idx.compute(method='p-space')

interp = Interpolation(flow, idx)
interp.compute(method='p-space')

intg = Integration(interp)
new_point, u = intg.compute(method='pRK4', time_step=1e-3)

One-shot streamline extraction

from lptlib.streamlines.streamlines import Streamlines

sl = Streamlines('path/to/grid.sp.x', 'path/to/sol-0000010.q', [0.1, 0.05, 0.0])
sl.compute(method='p-space')
coords = sl.streamline  # list of points

Stochastic parallel run (oblique shock example)

The repository includes a fully working example in main.py that generates an oblique shock test case and launches an adaptive particle tracking simulation in parallel:

python main.py

Key objects used in the example:

ObliqueShock, ObliqueShockData to synthesize grid/flow for a controlled shock case
Particle, SpawnLocations to define particle size distribution and seed locations
StochasticModel to run many particles in parallel with adaptive time stepping

DataIO pipeline (Lagrangian → Eulerian)

DataIO reads scattered particle tracks (as .npy per particle), interpolates flow to those points, removes outliers, then interpolates both flow and particle fields onto a structured mesh and writes Plot3D outputs for visualization and downstream tools.

Essential steps:

Scatter interpolation of flow to particle locations (MPI-parallel)
Outlier removal and caching of intermediate .npy files under dataio/
Grid interpolation to a user-defined mesh
Export to Plot3D: mgrd_to_p3d.x, mgrd_to_p3d_fluid.q, mgrd_to_p3d_particle.q

See test/test_dataio.py for a minimal, runnable example.

Core API

lptlib.io.plot3dio.GridIO
- read_grid(data_type='f4'), compute_metrics(), mgrd_to_p3d(...)
lptlib.io.plot3dio.FlowIO
- read_flow(data_type='f4'), read_unsteady_flow(...), mgrd_to_p3d(...), read_formatted_txt(...)
lptlib.streamlines.Search
- compute(method=...), p2c(ppoint), c2p(cpoint)
lptlib.streamlines.Interpolation
- compute(method=...) with options: p-space, c-space, rbf-*, rgi-*, simple_oblique_shock
lptlib.streamlines.Integration
- compute(method=..., time_step=...) with pRK2/4, cRK2/4, unsteady variants
- compute_ppath(...) for particle dynamics with drag models (stokes, loth, etc.)
lptlib.streamlines.Streamlines
- High-level orchestrator: compute(method=...), exposes streamline, fvelocity, svelocity, time
lptlib.streamlines.StochasticModel
- Parallel execution over many particles: multi_process(), multi_thread(), mpi_run(), serial()
lptlib.function.Variables
- compute_velocity(), compute_temperature(), compute_pressure(), compute_mach(), compute_viscosity()
lptlib.io.DataIO
- compute() end-to-end Lagrangian→Eulerian conversion and Plot3D export

Testing

Run the test suite from the repo root:

pytest -q

Tests cover search, interpolation (steady/unsteady), integration, DataIO, streamlines, plotting, and MPI helpers.

License

Distributed under MIT AND (Apache-2.0 OR BSD-2-Clause). See LICENSE.

Metadata

Release files for lptlib 0.0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lptlib 0.0.6
File	Size	Uploaded
lptlib-0.0.6.tar.gz	72.3 kB	May 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for lptlib 0.0.6
File	Interpreter	ABI	Platform	Reset
lptlib-0.0.6-py3-none-any.whl 65.8 kB May 19, 2026	Python 3	none	any	Details

Total release size: 138.1 kB

Release files / lptlib-0.0.6.tar.gz

Download URL	lptlib-0.0.6.tar.gz
Size	72.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`73958cce5f70616031a9bb036b4c2131acc707167d2d9c722c01fd3a8304c68b`
BLAKE2b-256 checksum How to use checksums	`9bee7f3457c6e2b3ae22653867436e0d69fa3cdde56e51961c2b74fbc18782c1`
Upload date	May 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.2`

Release files / lptlib-0.0.6-py3-none-any.whl

Download URL	lptlib-0.0.6-py3-none-any.whl
Size	65.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`cd65d2a5865bb34ff38a6df79355e5beb87f0aca82a0a34b9539f3a256b59177`
BLAKE2b-256 checksum How to use checksums	`aba51dbccfab3255fbbbd980daf56a602dd2097dcacc4ae0dc12bd32f036a781`
Upload date	May 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.2`