The Sea Turtle Active Movement Model (STAMM) is an Individual Based Model that aims at calculating juvenile sea turtles dispersal. A lagrangian approach is used in which turtles ground velocity is computed as the result of the ocean current velocity and a swimming velocity directed towards favorable habitats (Gaspar and Lalire 2017). Originally based on the lagrangian software ARIANE, its last version uses PARCELS (http://oceanparcels.org/), a set of Python classes and methods for lagrangian simulations.

Please note that the model is still under development and that you might need to look deeper in the code for specific uses.

There are four directories:

• A directory src including the source code of STAMM.
• A directory templates with examples of namelist, script to run the model, release file,...
• A directory STIT containing pre-processing and post-processing tools.
• A directory LIB containing libraries used in STIT and in src.

You can create a new environment named stamm and including necessary modules with the following command:

conda create -n stamm -c conda-forge python=3.6 parcels spyder basemap basemap-data-hires opencv

Then, activate this environment with command conda activate stamm.

Note: STAMM was tested with Parcels 2.2.0

In your ~/.bashrc file, you can add command export stamm=/data/rd_exchange3/pgiffard/stamm/ to have stamm directory as shortcut.

STAMM needs 4 variables to run: U and V, respectively the zonal and meridional surface current velocities; T, the ocean surface temperature; and a food proxy (Net Primary Production - NPP for example).

The model accepts regular and non-regular grids (Orca for example), A-grid or C-grid, at any time resolution. PARCELS will take care of spatial and temporal interpolations. The food proxy (NPP for example) can be on a different grid than physics variables (U, V and T). For the moment, STAMM was tested with A-grids only. The food proxy needs to be vertically integrated.

You can download data directly on the CMEMS website. We also created a script to help downloading a whole dataset: STIT/preprocessing/Extract_CMEMS_data.py.

Parcels needs data files to satisfy the following conditions:

• They need to have a time variable giving the file date. Files have to be ordered in time. You can use the script STIT/preprocessing/Change_netcdf_time.py.
• Variables need a FillValue attribute to represent land or cells without data. If Parcels doesn't find it, please rename it using the script STIT/preprocessing/Rename_FillValue.py (for example it doesn't find Hole_Value).
• PARCELS also needs to read the coordinates of your cells in longitude/latitude: the cells centers for A-grids and f-nodes (upper right corner) for C-grids. It can read them directly in a forcing file or in another mesh file. You can create a mesh_file following the VGPM example: STIT/preprocessing/Create_VGPM_mesh.py.

Create a release file giving release longitude, latitude and time for each turtle. Follow the example in templates. You can use the script STIT/create_init_pos.py . STAMM needs time in days since the 1st of january of the starting year.

Calibrate model for your species and for the zone your turtles will move in. To calibrate P0 as the 90th percentile of the NPP distribution in a zone, you can use the script STIT/preprocessing/P0_calibration.py. You will need to set parameters in namalist as well as in the src/Species folder.

Below you will find a description of all STAMM parameters.

Note: no space should appear between two sections.

&GENERAL PARAMETERS

init_file = path to your release file

nturtles = number of turtles

tstep = computational time step in seconds

ndays_simu = Number of days to simulate

time_periodic = To loop periodically data. It is set to either False, the length of the period in days (since first particle release) or 'auto'. In mode 'auto', it will loop automatically after last complete available year. Default: 'auto'.

t_output = Writing time of output file.

mode = Simulation mode: 'passive' (ocean currents only) or 'active' (ocean currents plus swimming velocity). Default: active.

key_alltracers = boolean, if False doesn't use T and NPP for diagnostics. Default: True.

adv_scheme = advection scheme: 'RK4' or 'Euler'. Default: RK4

ystart = integer, simulation starting year.

/

&ACTIVE MODE

species = 'Leatherback' or 'Loggerhead'.

alpha = Scaling parameter for the Von Mises distribution in m-1.

P0 = Scaling factor used to calculate food habitat expressed in the same units as NPP.

grad_dx = distance from turtle (in meters) to which habitat gradients are computed.

cold_death = boolean, if True turtles are deleted after cold_resistance days under Tmin. Default: False

cold_resistance = integer, number of days turtles can resist under Tmin. Default: 30.

growth = 'VGBF' or 'Gompertz'. To use a von Bertalanffy function for growth or the Gompertz model with habitat dependance (only for Leatherbacks).

SCL0 = 'float'. Turtles initial SCL.

tactic_factor = float [0, 1]. Proportion of current swimming angle taken into account in final swimming direction. 1 for no memory effect. Default: 1.

frenzy = boolean. To simulate frenzy swimming. Turtles will swim during several days towards the same direction (define parameters in src/Species). Default: False

wave_swim = boolean. So that turtles swim against wave at the beginning of the simulation. Wave direction is calculated based on Stokes drift. Default: False

/

&GRIDPARAM

periodicBC = boolean, set to True for East/West periodicity. Default: True.

halo = boolean. Set to True if your data already has a halo (for example Orca grids already has a repetition of last/first columns). Default: False.

/

&FORCINGS FILES

U_dir = data directory of the zonal velocity

U_suffix = files suffix

V_dir = data directory of the meridional velocity

V_suffix = files suffix

T_dir = data directory of the temperature

T_suffix = files suffix

food_dir = data directory of the food proxy.

food_suffix = files suffix

/

&PHYSICS

mesh_phy = File from which lon/lat coordinates will be extracted for physics (U, V and T). Can be one of the data files for A-grids. For a C-grid you need to provide f-nodes (cells corners).

grid_phy = 'C' for C-grid, 'A' for A-grid (centered grid). The interpolation scheme is nearest neighbour for C-grid tracers.

lon_phy = name of longitude variable in mesh_phy (f-node if C-grid)

lat_phy = name of latitude variable in mesh_phy (f-node if C-grid)

lon_T = Only for C-grid. Name of temperature longitude variable in mesh_phy

lat_T = Only for C-grid. Name of temperature latitude variable in mesh_phy

time_var_phy = name of time variable in your physical files

U_var = name of zonal velocity variable

V_var = name of meridional velocity variable

T_var = name of temperature variable

/

&FOOD PROXY

mesh_food = File from which lon/lat coordinates will be extracted for food proxy. Can be one of the data files for A-grids.

lon_food = name of longitude variable in mesh_food

lat_food = name of latitude variable in mesh_food

time_var_food = name of time variable in your food proxy files

food_var = name of food proxy variable

/

&WAVES

wave_dir = data directory for waves (Stokes drift) if wave_swim is True.

wave_suffix = files suffix

Ust_var = name of zonal Stokes drift

Vst_var = name of meridional Stokes drift

/

Execute command python src/STAMM.py namelist outfile.nc. STAMM will create a netcdf file with turtles trajectories and with many other variables such as habitat, temperature, SCL,... You can also use script src/run_stamm.sh to run STAMM, and then to execute some post-processing diagnosis.

You will find e few scripts to visualize the outputs in STIT/postprocessing:

STAMM is sensitive to forcings selection. In the namelist, you will provide a directory containing one or several variables. For each variable, a suffix is also given. Take care that one suffix matches only with the desired variable. You can also create symbolic links pointing to your files.

If it doesn't work for your files, try to modify your file names or the function forcing_list in Funtions.py.

The swimming velocity is supposed constant over a whole timestep.

In STAMM, all variables are set to 0 on land so that habitat gradient is directed towards ocean and turtles avoid beaching. Physical land mask can be different from food land mask. Then, land corresponds to the physical land mask. Most turtles won't enter into the food land mask because habitat is set to 0. If they do so, they could be 'lost' because there won't be any habitat gradient because habitat will be 0 everywhere.

Turtles can beach in case of convergence or in case the hazard on swimming direction lead them towards land. This shouldn't happen too often since variables are set to 0 on land, and hence habitat is also 0 on land. The habitat gradient is then directed towards the open ocean. In case turtles beach, they are sent back to their last position. They are disabled (don't move anymore) if:

• they pass through the northern boundary of domain.
• periodicBC is set to False and they reach the east-west boundary.
• they beach more than 50 times in a row.
• cold_mortality is set to True and they stay too long in a cold area.

The variable active can help you to visualize disabled turtles.

The choice of the simulation time step depends on the advection scheme used, on velocities experimented by turtles and on grid resolution. For Euler advection scheme, the Courant–Friedrichs–Lewy condition has to be respected in the whole area: u * dt / dx has to be less than 1 in the whole domain. u is the maximum velocity turtles will experiment, dt is the simulation time step and dx is the spatial grid resolution.

The Runge-Kutta scheme is more stable, but has no criteria as simple as for Euler scheme. Hence, and for security reasons, it is possible to use the Courant criteria also for Runge-Kutta 4.

The computational time is not proportional to time step. Hence, a great part of computational time is dedicated to access data from disk (operation done each day for daily datasets). Also, it is quite fast to calculate turtles positions evolution since it is done in C (up to 10 000 turtles). Indeed, Parcels translates all python kernels to C language in order to speed up execution.

Field chunking is available for large datasets, to load data that would never fit into memory in one go. In STAMM chunksize is set to False for 1/4° resolution 2D fields, to 'auto' for 2D fields of higher resolution and to a fixed value (256) for 3D fields. This fixed value might to be optimal in all situations.

Note that using 3D data is a way slower than using surface data only.

If the writing time step (t_output) is smaller than the computational time step (tstep), the actual computational time step will be t_output. On the contrary, if tstep is smaller than t_output and if they aren't multiple, Parcels will define a smaller time step multiple of tstep and t_output.

Also, it's worth mention that outputs aren't means over multiple time steps but are only the value at a certain time. For example if tstep =1h and t_output = 24h, then output variables won't be the daily mean but only the value each 24h.

Currently, STAMM is only prepared for Leatherback and Loggerhead sea turtles. To add a new specie, you will need:

1. Create a new parameter file in src/Species using the other ones as templates.
2. In src/Functions.py, function Initialisation, add an elif for your species to select your parameter file. You also need to import it at the beginning of the file.
3. In namelist, choose your species.

You can add argument in the namelist. You only need to add it to the dictionary in LIB/IOlib.py

It is quite easy to add behaviours to turtles. To do so, you can add a function to Active_kernels.py, _Passive_kernels.p_y or Advection_kernel.py. However, parcels will pass your functions to C code. For this reason, your functions have to use only basic Python: no for loops, no extern function call, …

Then, in Functions.py you need to add your function to the kernel_list so that it become in kernel used during execution. At each time step, all kernels are applied to each particle one by one. That's why the order is very important.

In kernels, you can print text as in python, but to print particle attribute you need to use print('%f'%particle.lon).

For now, STAMM was tested with A-grids (centered grids). It should work with C-grids although it hasn't been tested yet.

At t=0, all tracers are set to 0. Indeed, defining temperature as T = Variable('T', initial=fieldset.T) is too long to initialize because it is executed in Scipy mode. An other possibility is to execute a sampling kernel for one timestep: pset.execute(SampleTracers, dt=0) but it works only if all particles are released at the same time because of deferred_load (only 3 time steps are loaded at the same time).