abstract type AbstractDriftersDataset

Data structure used for plotting. See the docs for examples.

abstract type FlowFields

Data structure that provide access to flow fields (gridded as arrays) which will be used to interpolate velocities to individual locations later on (once embedded in an Individuals struct).

Following the C-grid convention also used in MITgcm (https://mitgcm.readthedocs.io) flow fields are expected to be staggered as follows: grid cell i,j has its center located at i-1/2,j-1/2 while the corresponding u[i,j] (resp. `v[i,j]) is located at i-1,j-1/2 (resp. i-1/2,j-1).

By convention :

• time is in seconds but T can also be provided as a vector of DateTime
• position is in grid units. Local coordinates cover (0 to nx, 0 to ny) if the grid is of size (nx, ny).
• velocity fields must be normalized accordingly to grid units (in 1/s rather than m/s) being used in a FlowFields constructors (whether Array or MeshArray)

uvArrays(u0,u1,v0,v1,T)
uvwArrays(u0,u1,v0,v1,w0,w1,T)
uvMeshArrays(u0,u1,v0,v1,T,update_location!)
uvwMeshArrays(u0,u1,v0,v1,w0,w1,T,update_location!)

Using the FlowFields constructor which gets selected by the type of u0 etc.

For exmaple, with Array type in 3D :

F=FlowFields(u,u,v,v,0*w,1*w,[0.0,10.0])

Or, with MeshArray` type in 2D :

F=FlowFields(u,u,v,v,[0.0,10.0],func)

as shown in the online documentation examples.

FlowFields(;    u::Union{Array,Tuple}=[], v::Union{Array,Tuple}=[], w::Union{Array,Tuple}=[], 
                period::Union{Array,Tuple}=[])

Simplified FlowFields constructor : using keywords, with time invariant flow fields.

uC, vC, _ = SimpleFlowFields(16)
to_C_grid!(uC,dims=1)
to_C_grid!(uC,dims=2)
F=FlowFields(u=uC,v=vC,period=(0,10.))

struct Individuals{T,N}

• Data: 📌 (position), 🔴(record), 🆔 (ID), P (FlowFields)
• Functions: 🚄 (velocity), ∫ (integration), 🔧(postprocessing)
• NamedTuples: D (diagnostics), M (metadata)

The velocity function 🚄 typically computes velocity at individual positions (📌 to start) within the specified space-time domain by interpolating gridded variables (provided via P). Individual trajectories are computed by integrating (∫) interpolated velocities through time. Normally, integration is done by calling ∫! which updates 📌 at the end and records results in 🔴 via 🔧. Ancillary data, for use in 🔧 for example, can be provided in D and metadata stored in M.

Unicode cheatsheet:

• 📌=\:pushpin:<tab>, 🔴=\:red_circle:<tab>, 🆔=\:id:<tab>
• 🚄=\:bullettrain_side:<tab>, ∫=\int<tab>, 🔧=\:wrench:<tab>
• P=\itP<tab>, D=\itD<tab>, M=\itM<tab>

Simple constructors that use FlowFields to choose adequate defaults:

• Individuals(F::uvArrays,x,y)
• Individuals(F::uvwArrays,x,y,z)
• Individuals(F::uvMeshArrays,x,y,fid)
• Individuals(F::uvwMeshArrays,x,y,z,fid)

Further customization is achievable via keyword constructors:

df=DataFrame( ID=[], x=[], y=[], z=[], t = [])
I=Individuals{Float64,2}(📌=zeros(3,10),🆔=1:10,🔴=deepcopy(df))
I=Individuals(📌=zeros(3,2),🆔=collect(1:2),🔴=deepcopy(df))

Or via the plain text (or no-unicode) constructors:

df=DataFrame( ID=[], x=[], y=[], z=[], t = [])
I=(position=zeros(3,2),ID=1:2,record=deepcopy(df))
I=Individuals(I)

struct TimeAxis{Ty} <: AbstractTimeAxis

Time axis specification for FlowFields data structure. This un-mutable specification describes the overall range of simulations that can be performed using the FlowFields.

• initial : beginning of simulation period
• final : end of simulation period
• origin : beginning of the valid time period, when flow fields are available
• horizon : end of the valid time period, when flow fields are available
• climatology : false by default ; but can be set to true for time-periodic flow fields.

Rules :

• In most simple cases origin,horizon is just the same as initial,final.
• By default initial,final and origin,horizon are set to the FlowField's TimePeriod.
• However, any specification where initial,final is within origin,horizon is correct.
• This more general approach makes it easy to split simulations into smaller intervals.

using Drifters, Dates

D0=DateTime(2000,1,1)
D1=DateTime(2000,3,1)
TA=Drifters.TimeAxis(D0,D1)
TA=Drifters.TimeAxis(D0,D1,D0,D1,false)

struct TimePeriod{Ty} <: AbstractTimePeriod

Time period for next simulation of Individuals displacement specified as a vector [initial,final]. The value field is a mutable vector that can be changed, e.g. within a time loop when carrying out longer simulations.

Rules :

• if final precedes initial then the simulation goes backward in time
• in most simple cases, initial,final are the same in TimePeriod and TimeAxis.
• but any initial,final within the periods defined in 'TimeAxisworks forTimePeriod`.

using Drifters, Dates

D0=DateTime(2000,1,1)
D1=DateTime(2000,3,1)
TP=Drifters.TimePeriod([D0,D1])
TA=Drifters.TimeAxis(TP)

∫!(I::Individuals,T::Tuple)

Displace simulated individuals continuously through space over time period T starting from position 📌.

• This is typically achieved by computing the cumulative integral of velocity experienced by each individual along its trajectory (∫ 🚄 dt).
• The current default is solve(prob,Tsit5(),reltol=1e-8,abstol=1e-8) but all solver options from the OrdinaryDiffEq.jl package are available.
• After this, ∫! is also equipped to postprocess results recorded into 🔴 via the 🔧 workflow, and the last step in ∫! consists in updating 📌 to be ready for continuing in a subsequent call to ∫!.

∫!(I::Individuals)

Call ∫!(I::Individuals,I.P.T)