The class Reader obtains forcing data (e.g. wind, waves and currents) from any possible source and provides this to any OpenDrift model through a common interface. To avoid duplication of code, a parent class “BaseReader” contains functionality which is common to all Readers, whereas specific subclasses take care of only the tasks which are specific to a particular source of data, e.g. how to decode and interpret a particular file format. Two methods must be implemented by any Reader subclass: (1) a constructor method which initialises a Reader object and (2) a method to retrieve data for given variables, position and time. The constructor (__init__ in Python) can take any arguments as implemented by the specific Reader class, but it is typical to provide a filename or URL from which data shall be obtained by this Reader. The following Python commands initialise a Reader of type NetCDF_CF_generic to obtain data from a file “ocean_model_output.nc”. >> from opendrift.readers import reader_ netCDF_CF_generic >>> r = reader_netCDF_CF_generic.Reader( "ocean_model_output.nc")]]> The initialisation typically includes opening and reading metadata from a given file or URL to check which variables are available, and the coverage in time and space. The actual reading of the data is, however, not performed yet, but is delayed until it is known exactly which subset in space and time is actually needed (“lazy reading”). The contents can be inspected by printing the object: >> print r Projection: +proj=stere +lat_0=90 +lon_0=70 +lat_ts=60 +units=m +a=6.371e+06 +e=0 +no_defs Coverage: [m] xmin: -2952800.000000 xmax: -2712800.000000 step: 800 numx: 301 ymin: -1384000.000000 ymax: -1224000.000000 step: 800 numy: 201 Corners (lon, lat): ( 2.52, 59.90) ( 4.28, 61.89) ( 5.11, 59.32) ( 7.03, 61.26) Vertical levels [m]: [0.] Available time range: start: 2015-11-16 00:00:00 end: 2015-11-18 18:00:00 step: 1:00:00 67 times (0 missing) Variables: x_sea_water_velocity y_sea_water_velocity]]> The above example shows that the created Reader object can provide ocean surface current on a grid with 800 m pixel size in polar stereographic coordinates, at hourly time resolution.

To allow for generic coupling of any OpenDrift model with any Reader, a naming convention for variables is necessary. By convention, the commonly used Climate and Forecast (CF) naming convention (cfconventions.org) should be used whenever possible. Thus, if the data source is not already following this convention (e.g. a GRIB file), the Reader should map the variable names to corresponding CF standard_name.

The given Reader class must also have implemented a specific instance of the method get_variables which is called to return data: >> data = r.get_variables(["x_wind", "y_wind"], x, y, z, time)]]> The horizontal coordinates (x,y) correspond to the native projection of the Reader, which is polar stereographic in the given example. The task of transforming from one coordinate system to another (including the rotation of vectors) is performed by common methods from the parent class, based on the widely used PROJ.4 library (proj4.org), through its Python interface pyproj. This allows OpenDrift to combine input data from any coordinate systems, whilst keeping the implementation of new Reader classes as minimalistic and clean as possible. Further, this centralisation of code also facilitates optimisation for both performance and robustness. The vertical coordinate (z) is by convention always in metres, zero at the air/water surface and positive upwards. Thus, Readers providing data from sources with other vertical coordinate systems (e.g. topography following coordinates or pressure/density levels) must take care of transforming this to metres before data are returned. This is, e.g. done by an existing Reader supporting native output from the ROMS ocean model. The variable time is consistently handled as Python datetime objects within OpenDrift, with any time intervals as timedelta objects. Readers also share some common convenience methods, such as plotting of geographical coverage.

Readers are, however, normally not called directly by the user or from specific OpenDrift instances (models) but rather implicitly from the parent BaseModel class (see Sect. ). An internal caching mechanism is implemented to minimise the amount of data to be read, which is key to improving performance. Input data from numerical models are normally provided on a 3-D spatial grid (x,y,z) at discrete time steps, which are often larger than the time steps used internally by OpenDrift models. When data are requested for a given set of element positions at a given time, OpenDrift requests from the Readers' 3-D blocks of data from the time before and after the given time. These 3-D blocks encompass the elements tightly, except for a buffer on each side which is large enough so that elements will stay within the coverage during the time step of the Reader. After 3-D blocks of data are provided by the Reader, interpolators are generated and then reused to interpolate the same data blocks onto the element positions successively at each internal calculation time step, until the calculation time step reaches the latter Reader (model) time step. At this point, a 3-D block for the subsequent model time step is requested, and a new interpolator is generated. Due to this very economical access of remote data, simulations with OpenDrift are almost as fast when obtaining data from remote Thredds servers, as when reading the same data from a local file. The interpolator mechanism is also modularised by a dedicated class in OpenDrift, allowing independent development and optimisation. The default interpolation algorithm uses bilinear interpolation (scipy.ndimage.map_coordinates) and may also extrapolate data towards land, to avoid particles stranding in a “no data” gap between ocean pixels from an ocean model and land points as determined from an independent land mask.

Functionality exists also for reading and interpolating data from ensemble models. For example, when obtaining wind from a NetCDF model file containing 10 ensemble members, particles number 1, 11, 21… will use wind from member 1 of the atmospheric ensemble, and particles number 2, 12, 22… will use wind from member 2 of the atmospheric ensemble and so on. This allows for a more realistic spread/diffusion of particles than when using no or constant diffusivity. This functionality is particularly useful for ocean model output, which is inherently uncertain on short timescales, due to limited availability of observations for assimilation.

Whereas obtaining forcing data from 3-D Eulerian models is the most common in practice, Readers may obtain data from any other possible source. One example is to read a time series from an American Standard Code for Information Interchange (ASCII) file of observations, e.g. from a buoy or a weather station. Another example is to calculate forcing data according to some analytical function. One such example is included in the code repository, providing ocean current vectors according to a “perfect circular eddy” with centre coordinates as given to its constructor. Such analytical forcing data fields are useful for, e.g. testing the accuracy of forward propagation schemes, as discussed below.

OpenDrift also contains some internal convenience methods to calculate geophysical variables from others. For example, if a drift module requires wave height or Stokes drift, this may be parameterised internally based on the wind velocity if no Readers providing wave parameters are available.

Functionality which is common to any trajectory model is described in a main class, named BaseModel. This functionality includes the following:

A mechanism for configuration of a trajectory model, or a specific simulation is needed. This may include adjusting the resolution of a coastline or some model-specific parameters concerning the movement of the elements. The configuration mechanism of OpenDrift is based upon the ConfigObj package (https://pypi.python.org/pypi/configobj).

The only part missing is a description of how the elements (e.g. objects or substance) shall be propagated and potentially transformed along their trajectories under the influence of environmental forcing data. Such application-specific description is left to subclasses, yielding trajectory model instances as exemplified in Sect. . These subclasses thus inherit and may reuse any functionality from the BaseModel. The subclasses may also add further functionality as needed, or overload and modify existing functionality. Thus, all necessary core functionality is available by convenience but may be modified for flexibility. In precise terminology, OpenDrift is a framework within which specific trajectory models may be implemented by class inheritance (subclassing). An instance (object) of such a subclass represents a specific trajectory simulation.

In this section, we describe and explain the general workflow of a simulation with an OpenDrift model, as illustrated in the flowchart in Fig. .

The OpenDrift Leeway instance (OpenLeeway) is based on the operational search-and-rescue model of the Norwegian Meteorological Institute . The model ingests a list of object classes, where each drifting object has specific properties such as downwind and crosswind leeway (the motion due to wind) in a way similar to SAROPS, the operational system used by the US Coast Guard (see , and the overview of search-and-rescue models by ). These properties vary greatly from object to object and are based on field work where specific objects of relevance in search and rescue have been studied. All objects are assumed to be small enough that direct wave scattering forces are insignificant. Furthermore, the Stokes drift is inherently part of the leeway obtained from observations. As wind-generated waves have a mean direction closely aligned with the local wind direction, it is neither practical nor desirable to disentangle the Stokes drift from the wind drag for Leeway simulations.

Once an object class has been chosen and the pertinent wind and current forcing fields selected, the particles are seeded based on the available information. If the particles hit the coast, they stick by default. This can, however, be relaxed so that particles detach from the coastline if the wind direction changes.

The OpenLeeway class along with all other subclasses has the option of being run backwards. This is a convenient feature in the cases where, for example, a debris field is observed and the location of the accident is sought. Note that this method is fundamentally different from the BAKTRAK model described by where a large number of particles were seeded in potential initial locations at various times, and only those that ended up close to the location of the observed object were kept. This is an iterative procedure which in principle can deal with nonlinearities in the flow field as well as nonlinear behaviour of the object itself (such as capsizing and swamping). Although in principle this allows for a more realistic mapping of initial locations, the difficulties associated with this iterative process mean that real-time operations are normally better off with a simple negative-time integration.

OpenLeeway is used operationally at Norwegian Meteorological Institute and is also currently being implemented as the operational search-and-rescue model for the Joint Rescue Coordination Centres (JRCC) of Norway.

The following lines of Python code illustrate a complete working example of running an OpenLeeway simulation:

The final plotting command yields Fig. . The coastline shown is from the GSHHS database , which is the default option used to check stranding in OpenDrift. This coastline is, however, interfaced to OpenDrift as a regular Reader (Sect. ) and can be replaced by any other Reader providing the CF variable land_binary_mask. This allows performing simulations in narrow bays or lakes where even the full-resolution GSHHS coastline is too coarse.

OpenOil is a full-fledged oil drift model, bundled within the OpenDrift framework. As a model, it has been developed from scratch but is based on a selection of parameterisations of oil drift as found in the open research literature. With regard to horizontal drift, three processes are considered:

Any element, whether submerged or at the surface, drifts along with the ocean current.

The above three drift components may lead to a very strong gradient of drift magnitude and direction in the upper few metres of the ocean. For this reason, it is also of critical importance to have a good description of the vertical oil transport processes, which in OpenOil are the sum of the following factors:

If the vertical ocean current velocity is available from a Reader, the oil elements will follow it. This part of the movement is, however, often negligible compared to the processes below.

In addition to the vertical and horizontal drift, weathering of the oil also has to be considered. While parameterisations of weathering might also be implemented directly within the OpenDrift framework, the OpenOil module instead interfaces with the already existing OilLibrary software developed by NOAA (https://github.com/NOAA-ORR-ERD/OilLibrary). The NOAA OilLibrary is also open-source and written in Python, so integration is straightforward. In addition to state-of-the-art parameterisations of processes such as evaporation, emulsification and dispersion, this software contains a database of measured properties of almost 1000 oil types from around the world. As oils from different sources/wells have vastly different properties, such a database is of vital importance for accurate results. The same OilLibrary is also used by the NOAA oil drift model PyGNOME (https://github.com/NOAA-ORR-ERD/PyGnome), where it is replacing the original ADIOS oil library . PyGNOME includes also more processes not (yet) included in OpenOil, such as dissolution, and adding of dispersants.

To run an OpenOil simulation, one could reuse the exact code as for the Leeway example of Sect. , only replacing the name of the imported module (OpenOil instead of Leeway) and replacing the objectType property of Leeway with a corresponding oil name from the NOAA database. However, whereas key features and functionality is shared among OpenDrift modules, each module (or group of modules) may add specific functionality. For example, for OpenOil, it is possible to initialise the simulations with an oil slick as read from a file containing contours, either a shapefile or the Geography Markup Language (GML) format/specification, as used by the European Maritime Safety Agency (EMSA): >> o.seed_from_gml("RS2_20151116_002619_ SCNB_HH_Oil.gml", num_elements=2000) >>> o.plot()]]> where o is the oil drift simulation object. The last command produces the plot shown in Fig. .

OpenOil also has module-specific configuration settings. The following commands specify that the oil entrainment rate shall be calculated according to , and the oil droplet size spectrum shall be calculated according to . >> o.set_config('wave_entrainment: entrainment_rate', 'Li et al. (2017)') >>> o.set_config('wave_entrainment:droplet_ size_distribution', 'Johansen et al. (2015)')]]> Adjusting configuration this way is convenient for sensitivity studies, where one component is changed for two otherwise identical simulations.

After the simulation is finished, the generic plot command may be used to produce a map with trajectories as shown in Fig. . However, more specific plotting methods are also available. The command o.plot_oil_budget() plots an oil budget as shown in Fig. .

The vertical distribution of the elements can be plotted with the command o.plot_vertical_distribution(), generating output as shown in Fig. . This method is shared among three-dimensional modules and may also be used for simulations with, e.g. the PelagicEgg module (Sect. ).

As an example of a minimalistic trajectory model, we also include the instance WindBlow, which simply calculates the propagation of a passive particle subject to a two-dimensional wind field. The code below is the complete and fully functional WindDrift module.

Because all common functionality is inherited from the main class, the WindBlow model only needs to address its own specific needs. It will use elements without any other properties except for position (PassiveTracer), and the only forcing needed to move the elements is wind, whose vector components are named x_wind and y_wind in CF terminology. The update() method which is called at each time step simply advects all elements with the wind velocity at their respective locations. The wind might be provided by any Reader (Sect. ). The WindDrift module may be run with an even more simplified form of the code example found in Sect. : the WindDrift class has to be imported, no Reader for ocean current is needed, and there is no object category to specify.

Clearly, an air parcel in the real atmosphere will also be subjected to updrafts and diffusion, and will with time rise or fall, but the example serves to demonstrate how little is required to develop a new subclass of OpenDrift. The model may be made more sophisticated by adding, e.g. vertical wind (upward_air_velocity) and turbulence parameters to the list of required variables, and adding corresponding parameterisations of how to use this information for the advection.

In addition to the models described above, some other modules are bundled within the OpenDrift repository, as illustrated in Fig. :

OceanDrift is a basic module for tracking, e.g. water masses or passive tracers. Stokes drift is included, if provided by a Reader. A wind drift factor may also be specified, allowing an additional wind drag at the surface, e.g. for simulation trajectories of various ocean drifting buoys .

A module for drift of icebergs (OpenBerg, not yet included in repository) has been developed by Ron Saper at Carleton University with partial funding from ASL Environmental Sciences of Victoria, Canada, and with data support from the Canadian Ice Service (personal communication, 2017). Two different iceberg drift forecasting approaches are being tested. One approach uses a drag formulation to calculate wind and water drag forces. The challenge with this approach is that the trajectories are very sensitive to underwater draft/shape and suitable drag coefficients, of which information is rarely available. The second approach predicts and subtracts the wind and tidal components of the drift, and then analyses the residual for extrapolation an appropriately short time into the future. Finally, wind and tidal components are added back in to produce a trajectory forecast. The first version of OpenBerg does not include thermodynamic effects (melting) which are important longer timescales from weeks to months.

Drift of marine plastics, including microplastics, is an important application not covered by modules included with the OpenDrift repository version 1.0. However, as most of the needed infrastructure is already provided, including a vertical mixing scheme, a user with knowledge of the relevant physics and basic Python programming should be able to implement such a module with moderate efforts. However, there is no upper limit to the complexity of any module.