Preparation of a simulation#
In order to create a simulation of virtual Argo floats, you need to provide the following:
a float deployment plan, as a dictionary with
lat/lon/time
arrays,a velocity field, as a
parcels.fieldset.FieldSet
instance,and a virtual float mission configuration, as a dictionary.
These requirements are explained below, together with VirtualFleet helpers to do it.
But first, let’s import the usual suspects:
import numpy as np
from datetime import timedelta
from virtualargofleet import Velocity, FloatConfiguration
Deployment plan#
You need to define a deployment plan for your virtual fleet. The VirtualFleet simulator expects a dictionary with arrays for the latitude, longitude and time of virtual floats to deploy. Depth is set by default to the surface, but this can be provided if necessary.
Example:
# Number of floats we want to simulate:
nfloats = 10
# Define space/time locations of deployments:
lat = np.linspace(30, 38, nfloats)
lon = np.full_like(lat, -60)
tim = np.array(['2019-01-01' for i in range(nfloats)], dtype='datetime64')
# Define the deployment plan as a dictionary:
my_plan = {'lat': lat, 'lon': lon, 'time': tim}
Velocity field#
Then, you need to define the velocity field to be used by the virtual fleet.
Note
The VirtualFleet simulator can take any Parcels parcels.fieldset.FieldSet
as input.
However, to make things easier, we provide a convenient utility function Velocity()
to be used for some standard pre-defined velocity fields. It allows to easily create a VelocityField
instance that will be used as input to the VirtualFleet simulator.
The 2 main ways to get a VelocityField
instance with the Velocity()
function are:
1/ Using a xarray.Dataset
:
root = "~/data/GLOBAL-ANALYSIS-FORECAST-PHY-001-024"
ds = xr.open_mfdataset(glob.glob("%s/20201210*.nc" % root))
VELfield = Velocity(model='GLOBAL_ANALYSIS_FORECAST_PHY_001_024', src=ds)
2/ Using a custom
definition of the required arguments:
root = "~/data/GLOBAL-ANALYSIS-FORECAST-PHY-001-024"
filenames = {'U': root + "/20201210*.nc",
'V': root + "/20201210*.nc"}
variables = {'U':'uo', 'V':'vo'}
dimensions = {'time': 'time', 'depth':'depth', 'lat': 'latitude', 'lon': 'longitude'}
VELfield = Velocity(model='custom',
src=filenames,
variables=variables,
dimensions=dimensions)
In this later case, the function Velocity()
will take care of creating a parcels.fieldset.FieldSet
with the appropriate land/sea mask and circular wrapper if the field is global.
Currently, VirtualFleet supports the following values for the model
options of Velocity()
:
GLORYS12V1
,PSY4QV3R1
,GLOBAL_ANALYSIS_FORECAST_PHY_001_024
MEDSEA_ANALYSISFORECAST_PHY_006_013
ARMOR3D
,MULTIOBS_GLO_PHY_TSUV_3D_MYNRT_015_012
custom
if you want to set your own model definition
Argo floats mission parameters#
To define the float mission configuration parameters, VirtualFleet takes a simple dictionary with parameters as input. The virtual float cycle and the simplified associated mission parameters are illustrated figure 1. The minimal set of parameters to provide is: parking_depth
, profile_depth
, vertical_speed
, cycle_duration
and life_expectancy
.
VirtualFleet provides the convenient utility class FloatConfiguration
to make things easier. It allows to simply load a default configuration and can be passed directly to a VirtualFleet
instance.
You can start with a default configuration like this:
cfg = FloatConfiguration('default')
<FloatConfiguration><default>
- cycle_duration (Maximum length of float complete cycle): 240.0 [hours]
- life_expectancy (Maximum number of completed cycle): 200 [cycle]
- parking_depth (Drifting depth): 1000.0 [m]
- profile_depth (Maximum profile depth): 2000.0 [m]
- vertical_speed (Vertical profiling speed): 0.09 [m/s]
or you can fetch online a specific float cycle mission (data are retrieved from the Euro-Argo meta-data API):
cfg = FloatConfiguration([6902920, 98])
<FloatConfiguration><Float 6902920 - Cycle 98>
- cycle_duration (Maximum length of float complete cycle): 240.0 [hours]
- life_expectancy (Maximum number of completed cycle): 500 [cycle]
- parking_depth (Drifting depth): 1000.0 [m]
- profile_depth (Maximum profile depth): 2000.0 [m]
- vertical_speed (Vertical profiling speed): 0.09 [m/s]
Float configurations can be saved in json files:
cfg.to_json("myconfig.json")
This can be useful for later re-use because you can load a configuration from such a file:
cfg = FloatConfiguration("myconfig.json")
Examples of such json files can be found in this folder.
Once you created a FloatConfiguration
instance, you can modify one or more of the parameter values with the update
method like this:
cfg.update('parking_depth', 500)
If you want the same mission configuration for all your virtual floats, you can pass this configuration when instantiating a VirtualFleet
:
VFleet = VirtualFleet(plan=my_plan, fieldset=VELfield, mission=cfg)
But you can also customized the mission of each float by passing an array of mission configurations to the VirtualFleet
instance :
mission = [
FloatConfiguration('default').update('parking_depth', 100),
FloatConfiguration('default').update('parking_depth', 200),
FloatConfiguration('default').update('parking_depth', 500),
FloatConfiguration('default').update('parking_depth', 1000),
FloatConfiguration('default').update('parking_depth', 1500)
]
VFleet = VirtualFleet(plan=my_plan, fieldset=VELfield, mission=mission)