📚 TL;DR guide[1]

💪 Model capabilities

type	currents	winds	waves	beaching	spreading	entrainment	evaporation	emulsification	dissolution	volatilization	sedimentation	biodegradation
drifter	✔️	✔️	✔️	✔️	❌	❌	❌	❌	❌	❌	❌	❌
sar	✔️	✔️	✔️	✔️	❌	❌	❌	❌	❌	❌	❌	❌
oil	✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️	❌	❌	❌	❌
hns	✔️	✔️	✔️	✔️	✔️	✔️	✔️	❌	✔️	✔️	✔️	✔️

📖 Processes

Brief explanation of the main processes modeled by TESEO. As the majority of lagrangian models, TESEO use a simplified linear super-position technique to approximate particle motion. In this strategy the transport rate for a slick is represented by employing a vector sum of the transports induced by the mean flow, tides, wind, waves (wich is known as advection) and the transport due to turbulent dispersion.

$x_{i}^{t + 1} = x_{0}^{t} + (U_{a} + U_{D}) \cdot Δ t$

where $u_{a}$ is the advection velocity and $u_{D}$ is the turbulent diffusion velocity

$U_{a} = C_{c} \cdot U_{c} + C_{d} \cdot U_{w} + C_{s d} \cdot U_{s d}$

$U_{D} = \sqrt{\frac{6 D}{Δ t}}$

Weathering processes also are taking into account to evaluate the degradation and mass balance of the substances when an oil or hns release is defined. See the full catalog of processes with a brief explanation bellow:

🔀 Currents

The velocity of the currents velocity is directly transfered to the particle $U_{c} = C_{c} \cdot U_{c}$ ; Where $u_{c}$ is the current velocity and $C_{c}$ is a calibration coefficient, with value equal to 1.

💨 Wind drag

The velocity of the particle due to the wind drag over the particle area outside of the waterbody is expressed as $U_{w} = C_{d} \cdot u_{w}$ ; Where $u_{w}$ is the wind velocities at 10m over the sea surface and $C_{d}$ is the wind drag coefficient. This relation between the wind at 10m over the sea surface and the velocity of the particle due to this drag it is not direct related and different studies recommend a transfer rate between the 2.5% and 4.4% of the wind velocity and the deflection angles vary between 0º and 25° to the right/left of the wind direction(northern/southern hemisphere).

$C_{d} = α + β \cdot | u_{w} |$ with $β = 0$

$C_{d} = α$

Reference	$α$ coefficient	$β$ coefficient
`ASCE, 1996`	0.025 - 0.044	0
Note deflection angles correction is not aplied in TESEO

🌊 Stokes drift

Wave effect on particles’ transport is calculated based on wave-induced Stokes drift, calculated as $U_{s d} = C_{s d} \cdot u_{s d}$ . Where $u_{s d}$ is the net movement of the eulerian transport produced by a wave during a complet cycle, and it is calculated as $u_{s d} = \frac{g \cdot H}{8 C}$ and $C$ is the wave celerity Dean and Dalrymple, 1991

Reference	$C_{w}$ coefficient
`Castanedo et al., 2006`	0.005 - 0.015

☁️ Turbulent diffusion

The turbulent diffusion formulation is based on a random walk algorithm to evaluate the turbulent velocity. The turbulent velocity is part of the total velocity that moves the particles on the water and responds to the action of the eddy vorticity of the water in turbulent regimes, which is a chaotic motion.

Turbulent diffusion velocities are calculated using a Monte Carlo sampling in the range of velocities $[\vec{- u_{D}}, \vec{u_{D}}]$

where $U_{D} = \sqrt{\frac{6 D}{Δ t}}$

Formulation	$D_{h}$ horizontal coefficient	$D_{v}$ vertical coefficient
`ASCE, 1996`	1-100 m²/s	0.01-1 m²/s

Moreover, a different implementation is availbale to use TESEO in riverine environments following Shen and Yapa (1988)

🏖️ Beaching

Process of evaluation of each particle’s location to consider if the particle is in the water or on the land. If the particle is on water is particle able to be moved in the following timestep (active particle); If the particle is on land it gets fixed to the land (inactive particle).

This process is subdivided in two main subprocesses: a) Evaluate if the particle is on water or land, based on domain grid or based on coastline polygons, and b) when particle is on land, move the particle to the closest grid or coastline point.

Algorithm	Domain data needed	Description
`grid`	grid	Uses euclidean distance to grid points to check location. If land, it will move the particle to the closest land point
`coastline_low`	grid and coastline	Same as grid but moves the particle to the closest coastal point
`coastline_high`	grid and coastline	Uses in-polygon algorithm to check water or land location, and moves it to the closest coastal point

🫗 Spreading

One of the main oil transportation processes is the initial spreading. For small oil spills, a complete spreading process occurs during the first hour after the spill. It occurs due to viscosity, gravity, buoyancy and surface tension forces. The spreading process also depends on wind drift, surface current and other mixing processes like diffusion. These mechanisms can transport oil long distances (Pilzis, 2017).

Activating the spreading process in the simulations the model can calculate the initial area and thickness of a puntual release based on the substance properties and the mass or volume released, this is the cause why this process is always activated by default in oil and hns simulation. In the case of the Oil implementation the user should provide a maximum duration and a minimum thickness to let the model stop the spreading process when one of this conditions will be reached.

Release type	Formulation	Maximum duration	Minimum thickness
OIL	`adios2`	0-48h	depending on the substance
OIL	`lehr`	0-48h	depending on the substance
HNS	`mohid_hns`	None	depending on the substance

💧 Entrainment

Due to wind and wave effects it is common that part of the substance will be disperssed into the water column creating droplets of different sizes. This change in the mass balance from surface to the water colunm can be also addresed based on Delvigne & Hulsen, 1994

♨️ Evaporation

Oil evaporation is calculated based on an analytical model proposed by Stiver and Mackay (1980). In their formulation, the rate of evaporation is related to vapor pressure, spill area, a mass transference coefficient that depends on wind speed, environmental temperature, and oil type.

$Δ F = e x p [6.3 - \frac{10.3}{T} (T_{0} + T_{G} \cdot F)] * (\frac{k \cdot A \cdot Δ t}{V_{0}})$

where $F$ is the evaporated fraction, $k$ is the coefficient of mass transfer, $A$ is the oil slick surface, $V_{o}$ is the oil spiled volumem, $T$ is the environmental temperature, and $T_{0}$ and $T_{G}$ are distilation constants.

(!) Check implementation in TESEO

HNS evaporation is based on Kawamura and Mackay (1985) and Fernades (2014). According to these authors, evaporation is estimated following the equaction:

$E = A \cdot K_{m} + \frac{M_{w} \cdot P_{w}}{R t}$

where $E$ is the evaporation rate ( $k g / s$ ), $A$ is the area of the evaporating puddle ( $m^{2}$ ), $K_{m}$ is the mass transfer coefficient ( $m / s$ ), $M_{w}$ is the molecular weight of the chemical ( $k g / m o l$ ), $P_{v}$ is the vapour pressure ( $P a$ ), R is the gas constant ( $8314 J / (k m o l K)$ ), and $T$ is the air temperature ( $º K$ ).

The mass transfer coefficient ( $K_{m}$ ) can be expressed as Mackay and Matsugu (1973):

$K_{m} = 0.0292 U^{7 / 9} \cdot Z^{- 1 / 9} \cdot {S_{c}}^{- 2 / 3}$

where $U$ is the wind speed at a height of 10m ( $m / s$ ), $Z$ is the pool diameter in the along-wind direction ( $m$ ), and $S_{c}$ is the laminar Schmidt number for the selected chemical.

$S_{c} = \frac{ν}{D_{m}}$

where $ν$ is the kinematic viscosity of the air ( $1.5 \cdot 10^{- 5}$ $m^{2} / s$ ) and $D_{m}$ is the molecular diffusivity of the selected chemical in the air ( $m^{2} / s$ ) following Graham’s Law aproximation:

$D_{m} = D_{h_{2} o} {(\frac{M_{w}^{h_{2} o}}{M_{w}^{c h e m}})}^{1 / 2}$

where $D_{h_{2} o}$ is the molecular diffusivity of water ( $2.4 \cdot 10^{- 5}$ $m^{2} / s$ at $8 º C$ ), $M_{w}^{h_{2} o}$ is the molecular weight of water ( $18$ $k g / k m o l$ ) and $M_{w}^{c h e m}$ is the molecular weitght of the chemical.

💥 Volatilization

A correction for volatilization is included based on Brighton (1985), (1990), and Reynolds (1992). Correction coefficient is defined as:

$C = - \frac{P_{a}}{P_{ν}} \cdot l n (1 - \frac{P_{a}}{P_{ν}})$

where P_a is the atmospheric pressure ( $101.325$ $P a$ at sea level) and $P_{ν}$ is the vapour pressure of the solute ( $P a$ ). For chemicals that are not very volatile $C \approx 1$ . It will increase as the vapour pressure of the chemical increases.

$E_{c} = C * E$

$E_{v o l a t i l i z a t i o n} = E_{c} - E$

🧽 Emulsification

This process is simulated by means of a first-order rate law proposed by Mackay (1980). In this method, the rate of water incorporation is related to wind speed, maximum water-in-oil content, and a constant rate that depends on the type of oil.

$\frac{d Y}{d t} = - k (W_{10} + 1)^{2} (1 - \frac{Y}{Y_{f}})$

where $Y$ is the water content, $Y_{f}$ is the maximum water-in-oil content, $W_{10}$ is the wind velocity at 10m over the sea surface and $k$ is a constant rate that depends on the oil type.

⚗️ Dissolution

Dissolution is calculated according to Mackay and Leinoen (1977) and Fernandes (2014). The dissolved mass following the authors reads as follows:

$M_{d} = K_{d} \cdot A_{s} (S \cdot 10^{- 3}) \cdot Δ t$

Where $M_{d}$ is the disolved mass ( $k g$ ), $t$ is the time-step ( $s$ ), $K_{d}$ is the dissolution mass transfer constant ( $m / s$ ), $S$ is the solubility in water ( $m g / L$ ), and $A_{s}$ is the surface area ( $m^{2}$ ). Considering the slick surface as a flat plate:

$K_{d} = S h \cdot D_{i} \cdot 10^{- 4}$

where $S h$ is the Sherwood Number, $D_{i}$ is the diffusivity ( $c m^{2} / s$ ), and $L$ is the characteristic length ( $m$ ). The diffusivity ( $c m^{2} / s$ ) is computed based on Hayduk and Laudie (1974):

$D_{i} = \frac{13.36 \cdot 10^{.5}}{μ^{1.14} \cdot {V_{b}}^{0.589}}$

where $μ$ is the water dynamic viscosity ( $c P$ ) and $V_{b}$ is the Le Bas molar volume ( $c m^{3} / m o l$ )

⬇️ Sedimentation

🦠 Biodegradation

🔥 Quick start

The 2 main processes that any user needs:

1. Make a simulation

This “Request” to the library is made by instance the class SimulationRequest and for this class definition other main sub-clasessand fields have to be passed:

Required field	Value	Comment
domain	`Domain`	domain object
releases	`list(ReleasePoints)`	each release point is defined by `DrifterReleasePoint`, `SarReleasePoint`, `OilReleasePoint`, or `HnsReleasePoint`
duration	`datetime.timedelta`	duration of the simulation
forcings	`ForcingsRequest`	Object in wich the dataset and how to obtain them (online or local) are defined

domain:
forcings: ForcingsRequest
release_points: list of DrifterReleasePoint, SarReleasePoint, {py:classOilReleasePoint<pyteseo.models.release_points.OilReleasePoint>, or HnsReleasePoint.
duration: datetime.timedelta

For extra configurations see the complete class at API reference For a simple example, see hands-on section.

2. Make a domain

PyTESEO is developed based on Pydantic models, which allows users to instance clasess passing an unpacked dictionary to the parent class like MyClass(**my_dict). Pydantic takes care to check that all the fields are right and parse all the necessary standard fileds, like datetimes and timedeltas from standard notations (ISO_8601). Also, it takes into account nested instances of child classes so it is possible to define all you need in the same dictionary.

Let’s see an example to create a domain:

We are going to use the class DomainRequest

from pyteseo.models.domain_request import DomainRequest

domain_definition = {
        "name": "ibiza",
        "bbox": (0.9, 38.5, 1.9, 39.3),
        "elevation": {
            "service": "opendap",
            "provider": "ihcantabria",
            "dataset": "gebco_2023_1min",
        },
        "coastline": {
            "service": "wfs",
            "provider": "ihcantabria",
            "dataset": "osm_land_polygons",
        },
        "n_polygons": None,
    }

# Instance the class with the desired definition
domain_request = DomainRequest(**domain_definition)

# Execute the process to generate the domain
domain_request.process_request()

The easiest way to start is checking the examples in hands-on section but mainly, you need to create a dictionary following the next steps:

Set up a domain by means of passing the folder location.
Set up some general configurations like duration.
Set up the release points you desire (take into account that all have to be of the same type).
Set up the forcings datasets you want to drive the simulation.

if you need to check all options related to any model you can find them at the API Reference.

SimulationRequest DomainRequest