{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Tutorial on how to 'delay' the start of particle advection"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In many applications, it is needed to 'delay' the start of particle advection. For example because particles need to be released at different times throughout an experiment. Or because particles need to be released at a constant rate from the same set of locations.\n",
"\n",
"This tutorial will show how this can be done. We start with importing the relevant modules."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"%matplotlib inline\n",
"from parcels import FieldSet, ParticleSet, JITParticle, plotTrajectoriesFile\n",
"from parcels import AdvectionRK4\n",
"import numpy as np\n",
"import xarray as xr\n",
"from datetime import timedelta as delta"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"First import a `FieldSet` (from the Peninsula example, in this case)"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [],
"source": [
"fieldset = FieldSet.from_parcels('Peninsula_data/peninsula', allow_time_extrapolation = True)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now, there are two ways to delay the start of particles. Either by defining the whole `ParticleSet` at initialisation and giving each particle its own `time`. Or by using the `repeatdt` argument. We will show both options here"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Assigning each particle its own `time` ###"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The simplest way to delaye the start of a particle is to use the `time` argument for each particle"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [],
"source": [
"npart = 10 # number of particles to be released\n",
"lon = 3e3 * np.ones(npart)\n",
"lat = np.linspace(3e3 , 45e3, npart, dtype=np.float32)\n",
"time = np.arange(0, npart) * delta(hours=1).total_seconds() # release every particle one hour later\n",
"\n",
"pset = ParticleSet(fieldset=fieldset, pclass=JITParticle, lon=lon, lat=lat, time=time)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Then we can execute the `pset` as usual"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"INFO: Compiled ArrayJITParticleAdvectionRK4 ==> /var/folders/r2/8593q8z93kd7t4j9kbb_f7p00000gr/T/parcels-504/lib15ab640308c954e580b6f93be742baae_0.so\n"
]
}
],
"source": [
"output_file = pset.ParticleFile(name=\"DelayParticle_time.nc\", outputdt=delta(hours=1))\n",
"pset.execute(AdvectionRK4, runtime=delta(hours=24), dt=delta(minutes=5),\n",
" output_file=output_file)\n",
"output_file.export() # export the trajectory data to a netcdf file"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And then finally, we can show a movie of the particles. Note that the southern-most particles start to move first."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"plotTrajectoriesFile('DelayParticle_time.nc', mode='movie2d_notebook')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Using the `repeatdt` argument ###"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The second method to delay the start of particle releases is to use the `repeatdt` argument when constructing a `ParticleSet`. This is especially useful if you want to repeatedly release particles from the same set of locations."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [],
"source": [
"npart = 10 # number of particles to be released\n",
"lon = 3e3 * np.ones(npart)\n",
"lat = np.linspace(3e3 , 45e3, npart, dtype=np.float32)\n",
"repeatdt = delta(hours=3) # release from the same set of locations every 3 hours\n",
"\n",
"pset = ParticleSet(fieldset=fieldset, pclass=JITParticle, lon=lon, lat=lat, repeatdt=repeatdt)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we again define an output file and execute the `pset` as usual."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"INFO: Compiled ArrayJITParticleAdvectionRK4 ==> /var/folders/r2/8593q8z93kd7t4j9kbb_f7p00000gr/T/parcels-504/libcbcec39cf73cfa7671e8798abaac733b_0.so\n"
]
}
],
"source": [
"output_file = pset.ParticleFile(name=\"DelayParticle_releasedt\", outputdt=delta(hours=1))\n",
"pset.execute(AdvectionRK4, runtime=delta(hours=24), dt=delta(minutes=5),\n",
" output_file=output_file)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And we get an animation where a new particle is released every 3 hours from each start location"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"output_file.export() # export the trajectory data to a netcdf file\n",
"plotTrajectoriesFile('DelayParticle_releasedt.nc', mode='movie2d_notebook')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that, if you want to if you want to at some point stop the repeatdt, the easiest implementation is to use two calls to `pset.execute()`. For example, if in the above example you only want four releases of the pset, you could do the following"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"INFO: Compiled ArrayJITParticleAdvectionRK4 ==> /var/folders/r2/8593q8z93kd7t4j9kbb_f7p00000gr/T/parcels-504/libd1c17d6554e6d39a5c989beb50bcc2d3_0.so\n"
]
},
{
"data": {
"text/html": [
""
],
"text/plain": [
""
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pset = ParticleSet(fieldset=fieldset, pclass=JITParticle, lon=lon, lat=lat, repeatdt=repeatdt)\n",
"output_file = pset.ParticleFile(name=\"DelayParticle_releasedt_9hrs\", outputdt=delta(hours=1))\n",
"\n",
"# first run for 3 * 3 hrs\n",
"pset.execute(AdvectionRK4, runtime=delta(hours=9), dt=delta(minutes=5),\n",
" output_file=output_file)\n",
"\n",
"# now stop the repeated release\n",
"pset.repeatdt = None\n",
"\n",
"# now continue running for the remaining 15 hours\n",
"pset.execute(AdvectionRK4, runtime=delta(hours=15), dt=delta(minutes=5),\n",
" output_file=output_file)\n",
"\n",
"output_file.export() # export the trajectory data to a netcdf file\n",
"plotTrajectoriesFile('DelayParticle_releasedt_9hrs.nc', mode='movie2d_notebook')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Synced `time` in the output file\n",
"\n",
"Note that, because the `outputdt` variable controls the JIT-loop, all particles are written _at the same time_, even when they start at a non-multiple of `outputdt`. \n",
"\n",
"For example, if your particles start at `time=[0, 1, 2]` and `outputdt=2`, then the times written (for `dt=1` and `endtime=4`) will be "
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[ 0 2 4]\n",
" [ 2 4 'NaT']\n",
" [ 2 4 'NaT']]\n"
]
}
],
"source": [
"outtime_expected = np.array([[0, 2, 4], [2, 4, np.datetime64(\"NaT\")], [2, 4, np.datetime64(\"NaT\")]], dtype=\"timedelta64[s]\")\n",
"print(outtime_expected)"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"INFO: Compiled ArrayJITParticleAdvectionRK4 ==> /var/folders/r2/8593q8z93kd7t4j9kbb_f7p00000gr/T/parcels-504/lib73f1058452aa339434e56df780d0ba46_0.so\n"
]
}
],
"source": [
"outfilepath = \"DelayParticle_nonmatchingtime.nc\"\n",
"\n",
"pset = ParticleSet(fieldset=fieldset, pclass=JITParticle,\n",
" lat=[3e3]*3, lon=[3e3]*3, time=[0, 1, 2])\n",
"pset.execute(AdvectionRK4, endtime=4, dt=1, output_file=pset.ParticleFile(name=outfilepath, outputdt=2))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And indeed, the `time` values in the NetCDF output file are as expected"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[ 0 2 4]\n",
" [ 2 4 'NaT']\n",
" [ 2 4 'NaT']]\n"
]
}
],
"source": [
"outtime_infile = xr.open_dataset(outfilepath).time.values[:]\n",
"print(outtime_infile.astype('timedelta64[s]'))\n",
"\n",
"assert (outtime_expected[np.isfinite(outtime_expected)] == outtime_infile[np.isfinite(outtime_infile)]).all()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now, for some applications, this behavior may be undesirable; for example when particles need to be analyzed at a same age (instead of at a same time). In that case, we recommend either changing `outputdt` so that it is a common divisor of all start times; or doing multiple Parcels runs with subsets of the original `ParticleSet` (e.g., in the example above, one run with the Particles that start at `time=[0, 2]` and one with the Particle at `time=[1]`). In that case, you will get two files:"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"INFO: Compiled ArrayJITParticleAdvectionRK4 ==> /var/folders/r2/8593q8z93kd7t4j9kbb_f7p00000gr/T/parcels-504/lib4a9283c7ab81279666f072b74de9d644_0.so\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[ 0 2 4]\n",
" [ 2 4 'NaT']]\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"INFO: Compiled ArrayJITParticleAdvectionRK4 ==> /var/folders/r2/8593q8z93kd7t4j9kbb_f7p00000gr/T/parcels-504/libef5ef37165aa5febcc2e916a89504269_0.so\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"[[1 3 4]]\n"
]
}
],
"source": [
"for times in [[0,2], [1]]:\n",
" pset = ParticleSet(fieldset=fieldset, pclass=JITParticle,\n",
" lat=[3e3]*len(times), lon=[3e3]*len(times), time=times)\n",
" pset.execute(AdvectionRK4, endtime=4, dt=1, output_file=pset.ParticleFile(name=outfilepath, outputdt=2))\n",
" print(xr.open_dataset(outfilepath).time.values[:].astype('timedelta64[s]'))"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.10"
}
},
"nbformat": 4,
"nbformat_minor": 1
}