The dataset contains the simulation data for paper entitled "Mapping Spatial Patterns to Energetic Benefits in Groups of Flow-coupled Swimmers" published on Elife.

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, 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, matplotlib, are required to run these visualization scripts which are accompanied with the data. 

The CFD dataset can also be visualized using VisIt.