DOI: 10.5061/dryad.hqbzkh1s5
title: Data from: Mapping spatial patterns to energetic benefits in groups of flow-coupled swimmers

description: The coordinated motion of animal groups through fluids is thought to
 reduce the cost of locomotion to individuals in the group. However, the
 connection between the spatial patterns observed in collectively moving
 animals and the energetic benefits at each position within the group
 remains unclear. To address this knowledge gap, we study the spontaneous
 emergence of cohesive formations in groups of fish, modeled as flapping
 foils, all heading in the same direction. We show in pairwise formations
 and with increasing group size that (1) in side-by-side arrangements, the
 reciprocal nature of flow coupling results in an equal distribution of
 energy requirements among all members, with reduction in cost of
 locomotion for swimmers flapping inphase but an increase in cost for
 swimmers flapping antiphase, and (2) in inline arrangements, flow coupling
 is non-reciprocal for all flapping phase, with energetic savings in favor
 of trailing swimmers, but only up to a finite number of swimmers, beyond
 which school cohesion and energetic benefits are lost at once. We explain
 these findings mechanistically, and we provide efficient diagnostic tools
 for identifying locations in the wake of single (and multiple) swimmers
 that offer opportunities for hydrodynamic benefits to aspiring followers.
 Our results imply a connection between the resources generated by flow
 physics and social traits that influence greedy and cooperative group
 behavior.
description: We formulate computational
 models that capture the main hydrodynamic features of single and groups of
 swimming fish. Namely, we represent each fish as a freely-swimming
 hydrofoil undergoing pitching oscillations about its leading edge. We
 compute fluid-foil interactions using a Computational Fluid Dynamics (CFD)
 simulations of the Navier-Stokes equations and using vortex sheet
 simulations.
description: # Mapping spatial patterns to energetic benefits in groups of flow-coupled
 swimmers The dataset contains the simulation data for paper entitled
 "Mapping Spatial Patterns to Energetic Benefits in Groups of
 Flow-coupled Swimmers" published on
 [Elife](https://doi.org/10.7554/eLife.96129.2). Numerical simulations are
 performed using both Vortex Sheet Method (VSM) and Immersed Boundary
 Method (IBM) to study the energetic benefits and school cohesion of
 flow-coupled flapping swimmers. We study the spontaneous emergence of
 cohesive formations in groups of fish, modeled as flapping foils, all
 heading in the same direction. We show in pairwise formations and with
 increasing group size that (1) in side-by-side arrangements, the
 reciprocal nature of flow coupling results in an equal distribution of
 energy requirements among all members, with reduction in cost of
 locomotion for swimmers flapping inphase but an increase in cost for
 swimmers flapping antiphase, and (2) in inline arrangements, flow coupling
 is non-reciprocal for all flapping phase, with energetic savings in favor
 of trailing swimmers, but only up to a finite number of swimmers, beyond
 which school cohesion and energetic benefits are lost at once. ##
 Description of the data and file structure Our dataset are organized into
 two parts: dataset for VSM simulations and dataset for CFD simulations.
 The dataset contains both dataset for vortex sheet method (VSM)
 simulations and CFD simulations using immersed boundary method (IBM).  The
 VSM simulations are performed using in-house python codes (not open
 sourced). The output data can be plotted using the scripts provided in the
 folders. Each folder contains the time-evolution of a single simulation.
 The folder naming convention is that: it start with the spatial
 configuration of the swimmers, e.g. inline, side-by-side, staggered
 (inline means that all swimmers are in a straight line, head to tail;
 side-by-side means they are swimming next to each other with lateral
 distance but not stremwise distance; staggered means they have both
 distance in streamwise and laterally), and then is the number of the
 swimmers, and then, some cases have additional information, like changing
 the dissipation time or amplitude.  The Detailed description of data in
 each folder(e.g. inline_3) are given as follows.
 "information_*.txt" file contains time-evolution of the location
 of each swimmer. Each row contains the information of a single time step.
 The first column is the number of timestep, and the second column is the
 dimensionless time in simulation. After that, each 12 columns correspond
 to the information of each swimmer: location of the leading edge, pitching
 angle, velocity at leading edge, angular velocity, hydrodynamic force and
 torque, location of the nearest free vortex, vorticity of the nearest free
 vortex, and the free vortex shedding rate. Detailed information about
 bound vortex sheet and free vortex sheet is saved in folder
 "./datout*/". The data is saved every 50 timesteps. Each swimmer
 at each timestep is saved as a separate file, containing location and
 strength of all bound vortices, named as "{timestep}structure{swimmer
 index}.npy". Each free vortex sheet corresponds to each swimmer is
 saved as another separate file, containing the strength, location, and
 life time of each free vortices, named as
 "{timestep}structure{swimmer index}free_sheet{free vortex
 index}.npy". Python scripts are provided to visualize these data,
 wcich involves plotting the time evolution of the position of the swimmers
 (line_plot.py), plotting flow fields (plot_flow_field**.py), plot vortex
 sheet (plot_results.py), and colormaps (newMap.mat; rbcmap.mat) and
 auxiliary python scripts (calculate_influ.py; FreeVortexSheet.py;
 Rigid_pitching_swimmer.py; Structure.py) are imported by the
 aforementioned python scripts and helps the plotting and post
 processing. The sss.npy file describes the shape of the pitching plate,
 which is used for postprocessing and plotting only. The CFD simulations
 are performed using an open-source immersed boundary software,
 [IBAMR](https://ibamr.github.io/), with the custom-developed case files
 attached with the data.  The folder naming convention is that: for two
 fish datasets (main portion of the dataset): the naming is
 d={}_l={}_phase={}, which d indicates the initial longitudinal distance,
 and l is the lateral distance, phase is the phase difference. Other
 folders are named as one_swimmer, etc. The Detailed description of data in
 each folder(e.g. d=3.0_l=0.0_phase=1.0) are given as follows. The time
 evolution of the location of each swimmer is saved in
 "rbd.foil*". Each swimmer is saved in a separate file. Each row
 represents time, location, and velocity. The time evolution of
 hydrodynamic force acting on each swimmer is saved in
 "hydro_force_torque.foil*". Each swimmer is saved in a separate
 file. Each row represents time, location, and velocity. Each row
 represents time, viscous force, and pressure force. The flow field data
 are saved in folder "./viz_foil2d/". All the samrai data are
 valid hdf5 files, with detailed description available at IBAMR website.
 The data structure in viz_foil2d folder is that:  visit_dump.000xx folder
 contains the data from a single timestep. The files in it contain
 velocity, pressure, and vorticity data over the entire simulation domain. 
 Different files (processor_cluster.00xxx.samrai) saves the data from
 different processors during parallel computation. Python scripts
 (plot_data.py) are provided to visualize these data. All C++ code and
 header (*.cpp, *.h) are the C++ code which perform this simulation, and
 input2d is the configuration file to start the simulation. ### Files and
 variables #### File: CFD\_data\_save.py **Description:** summary of
 pairwise distance, swimming speed, and energy consumption for all CFD
 simulations #### File: VSM\_dataset.zip **Description:** VSM simulation
 dataset #### File: CFD\_dataset.zip **Description:** CFD (IBM) simulation
 dataset and code Note that all the data are given in dimensionless form.
 As stated in our paper, the length scale is the length of the swimmer, and
 the time scale is the pitching period of the swimmer.  ## Code/software
 The scripts for visualizing the data are developed using python, and it is
 not specified to a certain version. Packages like
 [numpy](https://numpy.org/), [matplotlib](https://matplotlib.org/), are
 required to run these visualization scripts which are accompanied with the
 data.  The CFD dataset can also be visualized using
 [VisIt](https://visit-dav.github.io/visit-website/index.html).