Snake Tongue Particle Capture

Analysis pipeline accompanying the paper [TBD]

This code quantifies how much odorant an oscillating snake tongue captures from its surroundings, using experimental Shake-The-Box (STB) particle tracking velocimetry data. It converts measured velocity fields into capture fraction fields, swept volumes, and entrainment ratios.

DOI: [Zenodo/PURR DOI once minted]

What this repository contains

Path	Contents
`snake_tongue_particle_capture_pipeline.py`	The complete four-step analysis pipeline
`READER_PATHLINE_FORMAT.md`	Specification of the pathline input files
`data/stl_geometry/`	Tongue geometry STL models (the virtual model released with the paper)
`data/control_laws/`	Actuator control-law spreadsheets defining tongue motion
`data/domain_extents/`	Measurement domain bounding boxes (small JSON, one per case)
`data/pathlines/`	Pre-computed particle pathlines (see Obtaining the data)
`tools/`	Utility for regenerating domain extents from raw data
`results/`	Pipeline output (created on first run; not tracked by git)
`requirements.txt`	Python dependencies

Quick start

git clone https://github.com/<ORG>/snake-tongue-particle-capture.git
cd snake-tongue-particle-capture

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Download the dataset into data/ (see below), then:
python snake_tongue_particle_capture_pipeline.py

Requirements

Python 3.10 or later. Dependencies are listed in requirements.txt — all are standard scientific-Python packages. The pipeline is a single self-contained module with no project-specific helper packages to install.

Scope: this pipeline does not perform particle advection

The Lagrangian particle advection step is not part of this release. The pipeline instead consumes pre-computed pathlines, which are provided in the archived dataset for every case in the paper.

This also means you can apply the analysis to your own flow using any advection code you like. READER_PATHLINE_FORMAT.md specifies the required file structure, with a worked example and a validation script.

Obtaining the data

The tongue geometry (data/stl_geometry/) and control laws (data/control_laws/) are included in this repository.

The measurement domain extents (data/domain_extents/) are also included — they are only a few hundred bytes per case.

Only the pre-computed pathlines are archived separately, at [Zenodo/Dryad DOI], because of their size. Download and extract into data/:

tar xzf snake_tongue_pathlines_v1.tar.gz -C .

The raw STB velocity fields are not required. The pipeline consumes pathlines, and needs only the domain bounding box from the velocity data — six numbers per case, already provided. This keeps the dataset download small.

To keep the dataset outside the repository, redirect either root with an environment variable:

export SNAKE_TONGUE_DATA_ROOT=/mnt/bigdisk/snake_tongue_data
export SNAKE_TONGUE_RESULTS_ROOT=/mnt/bigdisk/snake_tongue_results

Data layout

data/
├── domain_extents/
│   ├── stf_02_27_s1_domain.json
│   ├── stf_02_27_s2_domain.json
│   └── ...                                  (one file per section case)
├── pathlines/
│   ├── stf_02_27_s1_pathlines.pkl
│   ├── stf_02_27_s2_pathlines.pkl
│   └── ...                                  (one file per section case)
├── stl_geometry/
│   ├── Snake_Tongue_02_deg_short_remeshed_v1.stl
│   ├── Snake_Tongue_10_deg_short_remeshed_v1.stl
│   └── Snake_Tongue_20_deg_short_remeshed_v1.stl
└── control_laws/
    ├── control_law_27_1_start_le.xlsx
    └── control_law_60_1_start_le.xlsx

Filename patterns are set in the configuration block near the top of the pipeline script (STL_FILENAME_PATTERN, CONTROL_LAW_FILENAME_PATTERN) if your local copies differ.

Case naming

Cases follow stf_<angle>_<Re>_<section>, e.g. stf_02_27_s1.

Code	Meaning
`angle` = `02`, `10`, `20`	Full branching angle of the tongue geometry, in degrees
`Re` = `27`, `60`	Flow condition, given as the maximum Reynolds number reached
`section` = `s1`, `s2`	The two measurement volumes, acquired separately

Both codes are stated exactly as reported in the paper — no conversion is applied anywhere in the pipeline.

s1 and s2 cover different regions of the same physical experiment and are stitched together in Step 3. Both sections of a case must be processed through Steps 1–2 before Steps 3–4 can run for that case.

Running the pipeline

All settings live in the CONFIGURATION block at the top of the script; nothing below it needs editing for a normal run.

RUN_TAG    = 'my_analysis_run'   # names the output directory for this run
ATTEMPT_NO = 1

RUN_STEP1_ADVECTION_AND_CAPTURE = True
RUN_STEP2_CAPTURE_FRACTION      = True
RUN_STEP3_STITCHING             = True
RUN_STEP4_INTEGRALS             = True

SECTION_CASES  = ['stf_02_27_s1', 'stf_02_27_s2']   # Steps 1–2
COMBINED_CASES = ['stf_02_27']                      # Steps 3–4

NUM_PARTICLES       = 60000    # tracers in the pathline file; IDs >= this
                               # value are treated as reseeded particles
N_CANDIDATES        = 60000    # Eulerian grid resolution
CAPTURE_THRESHOLD_M = 0.001    # capture distance, metres

The step toggles let you re-run part of the pipeline without repeating earlier stages — useful because Step 1 (advection) dominates the runtime.

Pipeline stages

Step	Operates on	Description
1	Section cases	Loads pre-computed pathlines, builds the time-resolved tongue geometry motion, and flags particles captured within `CAPTURE_THRESHOLD_M` of the tongue surface
2	Section cases	Groups particle origins onto an Eulerian grid; computes capture fraction per cell
3	Combined cases	Interpolates the s1 capture-fraction field onto the s2 grid and merges the two sections
4	Combined cases	Integrates capture volume, tongue swept volume, and entrainment ratio

Output

results/<RUN_TAG>/
├── <case>_s1/, <case>_s2/          per-section capture CSVs and capture fractions
├── stitched_capture_fraction/      merged s1+s2 fields
└── ...
results/<RUN_TAG>_stitched_volume_calc/
└── <case>_results.pickle           capture volume, swept volume, entrainment ratio

Runtime

Roughly 30–60 minutes per case on a single core at 2.9 GHz, dominated by the Step 1 capture loop. (The advection that produced the pathlines is far more expensive, but is not repeated here.) Cases are independent, so processing them in parallel — one process per case — scales close to linearly. Peak memory is a few GB per case, driven by the size of the pathline file.

Reproducing the published figures

Set SECTION_CASES to all twelve section cases and COMBINED_CASES to all six combined cases, keep the defaults above, and run. The values in <case>_results.pickle correspond to the quantities reported in the paper.

Case-specific corrections

Two corrections are applied automatically and are documented here for transparency:

stf_02_27 — the s1 tongue geometry is offset by +0.0125 m in x during Step 1; Step 3 removes this offset before stitching so both sections share a coordinate frame.
stf_20_27_s1 — the source velocity field was reconstructed with an incorrect inter-frame time. The archived dataset has already been corrected, so no runtime adjustment is needed.

Citation

If you use this code or data, please cite the paper [TBD]:

@article{[KEY],
  title   = {[TITLE]},
  author  = {[AUTHORS]},
  journal = {[JOURNAL]},
  year    = {[YEAR]},
  doi     = {[DOI]}
}

License

Code in this repository is released under the MIT License (see LICENSE).

The tongue geometry models in data/stl_geometry/ are released under CC BY 4.0.

The pipeline is a single self-contained module; there are no bundled third-party components beyond the packages listed in requirements.txt.

Contact

Pranjal Anand - anand139@purdue.edu

Please open an issue for questions about running the code.

PavlosVlachosGroup/snake-tongue-odorant-capture-analysis

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Contributors 1

Languages