Trace Flows
Exploring Ocean Surface Currents through Lagrangian Analysis
TraceFlows is an online high-performance computational service for analysis of geophysical fluid flows, with a primary focus on ocean surface currents. This web-based platform efficiently computes Lagrangian quantities on a large scale, uncovering coherent structures of geophysical flows.
This user guide offers both a quick overview of the application usage and more in-depth details. We recommend starting with the Getting Started section and then acquainting yourself with the interface detailed in the following sections.
When accessing our online service, your web browser communicates with our computing server through ports 3000 to 3010. However, firewalls implemented by certain internet connections, such as public WiFi networks, including eduroams, may block these ports. In the event of a connection failure, you will receive a notification message. To ensure uninterrupted access to our service, we recommend switching to an alternative network connection.
To get a quick overview on the interface, we recommend watching a short demo video. You can also find more videos on our Vimeo channel, where we have assembled a gallery showcasing a few results generated by TraceFlows.
To quickly familiarize yourself with the application, you can follow these steps to run a minimalistic example on a sample dataset:
This section offers comprehensive guidance on preparing your datasets to ensure their compatibility as input for TraceFlows.
The input dataset can consist of one or multiple files, which should adhere to the following formats:
.nc, .nc4, .ncd, or .nc.gz..ncml or .ncml.gz. For more information on NcML files, see Single Dataset Stored Across Multiple Files.Note that it is also acceptable to provide a NetCDF file without a file extension.
It is highly recommended to save your data file in NetCDF4 format instead of NetCDF3. For more information, refer to NetCDF4 Package documentation in Python or NetCDF Files in MATLAB.
Also, you may follow the best practice of preparing a NetCDF file, which involves passing the CF 1.8 compliance test using online CF-convention compliance checker. In particular, this involves adding the standard_name attribute to your variables (see Required NetCDF Variables section below). For reference, you can consult the comprehensive list of CF compliance standard names.
An input NetCDF file to our application should include all the variables listed in the table below. To ensure proper detection of these variables by our application, each variable should include at least one of the attributes: standard_name, name, or both, as listed in the table. Note that checking the (standard) name is done in a case-insensitive manner.
| Variable | Acceptable Standard Names | Acceptable Names |
|---|---|---|
| Time | time |
t, time, datetime |
| Longitude | longitude |
lon, long, longitude |
| Latitude | latitude |
lat, latitude |
| Ocean's Surface East Velocity |
surface_eastward_sea_water_velocityeastward_sea_water_velocitysurface_geostrophic_eastward_sea_water_velocitysurface_geostrophic_sea_water_x_velocitysurface_geostrophic_eastward_sea_water_velocity_assuming_sea_level_for_geoidsurface_eastward_geostrophic_sea_water_velocity_assuming_sea_level_for_geoidsurface_geostrophic_sea_water_x_velocity_assuming_mean_sea_level_for_geoidsurface_geostrophic_sea_water_x_velocity_assuming_sea_level_for_geoidsurface_geostrophic_eastward_sea_water_velocity_assuming_mean_sea_level_for_geoidsea_water_x_velocityx_sea_water_velocity
|
east_veleastward_veluugoseast_velocityeastward_velocityu-velocity
|
| Ocean's Surface North Velocity |
surface_northward_sea_water_velocitynorthward_sea_water_velocitysurface_geostrophic_northward_sea_water_velocitysurface_geostrophic_sea_water_y_velocitysurface_geostrophic_northward_sea_water_velocity_assuming_sea_level_for_geoidsurface_northward_geostrophic_sea_water_velocity_assuming_sea_level_for_geoidsurface_geostrophic_sea_water_y_velocity_assuming_mean_sea_level_for_geoidsurface_geostrophic_sea_water_y_velocity_assuming_sea_level_for_geoidsurface_geostrophic_northward_sea_water_velocity_assuming_mean_sea_level_for_geoidsea_water_y_velocityy_sea_water_velocity
|
north_velnorthward_velvvgosnorth_velocitynorthward_velocityv-velocity
|
Apart from the required variables mentioned above, you have the option to include the following additional variables in your input file.
| Variable | Acceptable Standard Names | Acceptable Names |
|---|---|---|
| East Windage | eastward_wind |
east_windage, eastward_windage, east_wind, east_wind |
| North Windage | northward_wind |
north_windage, northward_windage, north_wind, north_wind |
| Land | land, land_binary_mask |
land |
The following provides further details for each of the variables listed in the tables above.
The time variable should be a one-dimensional array and strictly increases in values.
units: a string specifying both the time unit (such as years, months, days, hours, minutes, seconds or microseconds) and the origin of the time axis (such as since 1970-01-01 00:00:00 UTC). If this attribute is not provided, the default assumption is days since 1970-01-01 00:00:00 UTC.calendar: a string indicating the time calendar. If this attribute is not provided, the default assumption is gregorian.Ensure that the time variable is not masked. If the _FillValue attribute is included, the variable will be masked. Therefore, make sure this attribute is not present for the time variable.
These variables should be one-dimensional arrays, each representing an axis of a rectilinear grid. The values in both longitude and latitude arrays should either strictly increase or strictly decrease. The units of the arrays should be degrees positive eastward (for longitude) and degrees positive northward (for latitude).
Our application is designed to process data on rectilinear grids which are presented by one-dimensional longitude and latitude arrays. However, if your data is on irregular grids represented by two-dimensional longitude and latitude arrays, you can remap the data to a rectilinear grid by using interpolation functions such as scipy.interpolate.griddata in Python or griddata in MATLAB.
Ensure that the longitude and latitude variables are not masked. The presence of _FillValue attribute, for example, will cause these variables to be masked. Therefore, make sure this attribute is not present for the longitude and latitude variables.
The velocity data should be provided in the unit of meter per second positive eastward (for the east component) and positive northward (for the north component).
The east and north ocean's surface velocity variables should be three-dimensional arrays that include dimensions for time, longitude, and latitude. However, you can also provide four-dimensional arrays, where an additional dimension represents depth. In the latter case, only the first index of the depth dimension (representing the surface at near zero depth) will be read from these variables.
The order of dimensions for a velocity variable, named east_vel for instance, is as follows:
east_vel[time, lat, lon] in Python and east_vel(lon, lat, time) in MATLAB.east_vel[time, depth, lat, lon] in Python and east_vel(lon, lat, depth, time) in MATLAB.Note that the order of dimensions in MATLAB is reversed compared to Python.
In areas where the velocity is unknown (either due to being located on land or having incomplete data coverage), the velocity variable should be masked using one of the following methods:
9999.0 and assign the attribute missing_value or _FillValue with this value.NaN.Note that when applying masking to the velocity arrays, it does not distinguish between locations where the velocity is unknown due to being on land or due to missing measurement data. For specific identification of land points, you can provide the Land Variable.
When a tracer reaches a masked grid cell, its trajectory will be terminated and recorded in the output file at that point in time. To avoid premature termination of trajectories, we recommend the following approaches:
Windage refers to the atmospheric velocity at the lowest altitude, typically 10 meters above the ground. When considering windage, the effective velocity of a floating drifter (tracer) is determined by the linear combination \( \boldsymbol{v} + c_{w} \boldsymbol{w} \), where \( \boldsymbol{v} \) represents the ocean's surface velocity vector, \( \boldsymbol{w} \) denotes the windage vector, and \( c_{w} \) is a scalar coefficient parametrizing the wind effect on drifters.
The east and north windage variables should be three-dimensional arrays that include dimensions for time, longitude, and latitude. However, you can also provide four-dimensional windage arrays, where an additional dimension represents altitude. In the latter case, only the first index of the altitude dimension (representing ground at near zero altitude) will be read from these variables.
The order of dimensions for a windage variable, named east_wind for instance, is as follows:
east_wind[time, lat, lon] in Python and east_wind(lon, lat, time) in MATLAB.east_wind[time, alt, lat, lon] in Python and east_wind(lon, lat, alt, time) in MATLAB. Here, alt refers to the altitude dimension.Note that the order of dimensions in MATLAB is reversed compared to Python.
The time, longitude, and latitude dimensions in the windage arrays should have sizes that match the corresponding dimensions in the ocean's surface velocity arrays.
It is important to note that including the windage variable in your input files does not automatically apply windage to the tracers. To incorporate windage into the computations, you must explicitly enable it within the application's interface (refer to Apply windage to surface velocities option) and provide a windage coefficient.
To distinguish land from the ocean in your dataset, it is advisable to include a land array in your input file. This will allow you to precisely identify land points within the dataset. Alternatively, you may mask velocity variables at land points, but it's essential to note that this approach won't differentiate whether the velocity mask is due to land or missing velocity data. Therefore, using the land array method is recommended for accurate differentiation between land and ocean points in your analysis.
Our application utilizes the land variable to adjust the trajectory of tracers at the land boundary in the following ways:
However, if land information is not provided, the trajectory of a tracer reaching the land boundary will be terminated and recorded in the output file at the time of termination.
The land array should have two dimensions, representing longitude and latitude only. In Python, the order of these dimensions should be land[lat, lon], while in MATLAB, it should be land(lon, lat).
The land array should be of integer type, with values of either 0 or 1. Grid points located on land or the land-ocean boundary should be assigned a value of 1, while grid points in the ocean should be assigned a value of 0.
It is important to note that including the land variable in your input files does not automatically apply land conditions to the tracers. To incorporate land into the computations, you must explicitly enable it within the application's interface (refer to the Include land mask variable in input data option).
You have the option to treat the velocity mask as land without explicitly providing a separate land variable. To do this, first, enable the land option using Include land mask variable in input data and then select Detect land from velocity mask option in the interface.
However, please be aware that in this case, all masked velocity points will be treated as land, regardless of whether the velocity mask was intended to indicate land or missing velocity data. So, while this approach can be convenient, you should exercise caution with this option. For cases where precise identification of land points is necessary, it's advisable to use a dedicated land array to ensure accuracy in the analysis.
Certain datasets may exhibit incomplete velocity coverage, resulting in spatial gaps where data is missing. One such example is ocean surface velocity data obtained by HF radar measurements. These missing locations can a significantly impact on trajectory tracing and other Lagrangian-based analyses. To address this issue, we offer an online data restoration gateway accessible at https://restoreio.org. By utilizing this gateway, you can restore the missing coverage of velocity data prior to utilizing TraceFlows for your analysis.
You can provide the input dataset in two different ways:
To select the desired input method, simply use the tabs available in the Input Type section. Details of each method will be described in the following.
Note About Tabs:
During the execution of a computation, only the currently active tab among the available tab options will be taken into consideration, regardless of whether you have entered data in other tabs. For example, if you have uploaded a file under the Upload File tab, but later you accidentally switched to the OpenDap URL tab, your selection will be interpreted as using the OpenDap URL option. However, the file you have uploaded will not be discarded. This rule applies to all tab selections within the form.
Finding OpenDap URL from THREDDS catalog (Click to Play/Stop)
You can provide an OpenDap URL of a remote dataset through the Enter URL text box under the OpenDap URL tab within the Input Type section of the interface.
Many providers of geophysical data host their datasets on THREDDS Data servers, which offer OpenDap protocols. The following steps guide you to obtain the OpenDap URL of a remote dataset hosted on a THREDDS server. In the example below, we use a sample HF radar data hosted on our THREDDS server available at https://transport.me.berkeley.edu/thredds.
https://transport.me.berkeley.edu/thredds/dodsC/root/WHOI-HFR/WHOI_HFR_2014_restored.nc
For a visual demonstration of the steps described above, you may refer to the animated clip.
To help users explore the application, we have included the OpenDap URLs for two sample datasets in the Input Type section of the interface. Simply click on the drop-down menu located on the right side of the Enter URL text box, and choose one of the sample datasets. This selection will automatically populate the URL text box with the corresponding OpenDap URL.
You can upload your files under the Upload File tab from the Input Type entry. You can upload one or multiple files (see Multi-File Dataset section below).
To upload data files, you will need to provide an 8-character token string (refer to Enter Token within the interface). Tokens are required to prevent bots from uploading malicious files to the server. To obtain a token, please make a request to ude.yelekreb@ilemas. Tokens are available free of charge and offer unlimited uploads without any expiration date.
You have the option to provide multiple files. A multi-file datasets can appear in two scenarios:
If your dataset is divided into multiple files, where each file represents a distinct part of the data (e.g., different time frames), you can use the NetCDF Markup Language (NcML) to create an ncml file that aggregates all the individual NetCDF files into a single dataset. To provide this multi-file dataset, simply specify the URL of the NcML file. For detailed guidance on using NcML, you can consult the NcML Tutorial.
Alternatively, you may have several files, with each file representing an independent dataset. In this case, you can provide all these datasets simultaneously to the interface. An example of such multiple files could be ensembles obtained from ocean models, where each file corresponds to a velocity ensemble.
The following steps guide you to provide multiple files.
When providing multiple files, the name of your files (or the URLs) should include a numeric pattern. For instance, you can use the file name format like MyInputxxxxFile.nc where xxxx is the numeric pattern. An example of such data URLs where the pattern ranges from 0000 to 0020 could be:
https://transport.me.berkeley.edu/thredds/dodsC/public/SomeDirectory/MyInput0000File.nc https://transport.me.berkeley.edu/thredds/dodsC/public/SomeDirectory/MyInput0001File.nc https://transport.me.berkeley.edu/thredds/dodsC/public/SomeDirectory/MyInput0002File.nc ... https://transport.me.berkeley.edu/thredds/dodsC/public/SomeDirectory/MyInput0020File.nc
There are two method for providing your multi-file data:
https://transport.me.berkeley.edu/thredds/dodsC/public/SomeDirectory/MyInput0015File.ncOur application can parse the URL pattern and generate the URLs for the other remote files automatically.
Uploading multiple files alone does not automatically enable processing of multiple files. To enable multi-file processing, you need to explicitly enable this feature within the application's interface (refer to Enable processing multiple files (separate datasets) option).
Within the interface, enter the Minimum file index and Maximum file index to define the range of files to be processed. This allows the application to search through your uploaded files or generate new URLs based on the provided URL to access the other datasets.
For example, in the case of the URLs mentioned earlier, you can enter 0 as the minimum file index and 20 as the maximum file index within the interface. Alternatively, you can specify the full iterator pattern with the leading zeros as 0000 to 0020.
After providing the input data, it is recommended that you perform a scan of your dataset by clicking on Scan Data. This button performs a simple check on your data to make sure required variables exists and are readable. In addition, it reads the time span and spatial extent of the data and fills the interface form with these information. This is often useful if you do not have a priori knowledge on the time and spatial extent of your data. In particular, the scan applies the following information to the form:
You might adjust these settings to a desired configuration.
To visualize your input data, click on the Visualize button located in the input data section. This will display the east and north components of the velocity data on the map.
Please keep in mind that if your input dataset is hosted remotely and the remote data server does not allow Cross-Origin Resource Sharing (CORS) policy, the visualization of your dataset may be slower on our end as our server will try to proxy the remote data server to access the data. If you experience slow rendering or encounter an error during visualization, you can choose to skip visualization and proceed with the computation.
The Time section of the interface allows you to configure how the trajectory time is set, including the release time of the tracers and the times when the evolving quantities along trajectories are recorded in the output file.
Note About Setting Time
It's essential to understand that the time variable in the output file can have two distinct interpretations depending on how tracers are initialized over time. Please read this section thoroughly to avoid any confusion.
The configurations that can be input through the interface in the Time section are as follows. The usage of these variables will be described later:
Before describing how the above variables are used, it's essential to mention the notations we use to describe the trajectory times:
The time variable in the output NetCDF file is named time. This variable could refer to either the initial time \(t_i\) or the final time \(t_f\) depending on your selection at Initialization Type. There are two methods to initialize times:
In the following, we will describe the differences between these two selections, how each selection defines \(t_i\) and \(t_f\), and how time in the output file is defined accordingly.
In the Single Initial Time method, the tracers are released only once at the initial time. However, the tracers' information can be recorded (i.e. observed) at multiple times along the trajectory. This results in the following parameters:
This setting means that all trajectories start at \(t_o\), and their information is recorded at \(n\) final times \(t_f(j)\) as the trajectory time-span \(\tau\) increases from zero to the total integration duration \(T\). Accordingly, the output time variable is an array of length \(n\) where time[j] represents the final time \(t_f(j)\).
This time parametrization is useful when you want to follow the evolution of variables such as the trajectory coordinates and velocity gradient tensor along the trajectory as the tracers progress in time.
Note that in the above explanation, we use zero-indexed arrays to align with Python indexing conventions. You may adjust the indexing for MATLAB accordingly.
In the Multiple Initial Times method, tracers are released at multiple subsequent initial times, forming separate trajectories for each release. However, after each release, the trajectories are recorded only once for a fixed time span, rather than recording intermediate positions at various times along the trajectory. This approach is the opposite of the previous method in the sense that \(t_i\) is an array, whereas \(\tau\) is fixed. Specifically:
Unlike the previous method, in this case, the output variable time[j] is set to the initialization time \(t_i(j)\). This parametrization is suitable for variables defined at the initial time of the trajectories, such as the Cauchy-Green deformation tensor and finite-time Lyapunov exponent (FTLE). In particular, this parametrization allows the animation of such quantities over subsequent initialization of the tracers.
Tracers represent trajectory points on the ocean's surface that drift with the ocean's surface current and atmospheric wind at the ground level. You have the option to initialize a set of tracers using one of the following methods:
You can choose the desired method by selecting the corresponding tab in the Initialize Tracers section of the interface. More detail on each method is given below.
This method allows you to initialize tracers on a uniform grid of points defined by a rectilinear longitude and latitude grid. You can specify the desired grid resolution and range within the interface.
In addition to selecting the grid resolution and range, you also have the option to choose how the tracers are identified within the output arrays (output files). There are two indexing methods available:
You can select the desired indexing method using the Array Structure option within the interface. It's important to note that the choice of indexing method will impact the dimensions of the NetCDF variables in the resulting output file. For more detailed information, you may refer to the Output Array Structure section.
The Random Points method allows you to generate a set of tracers by randomly sampling points from a uniform distribution over a rectangular domain. You can specify the domain bounds and the Number of random tracers.
With this method, the trajectories of the tracers are identified using unique IDs. It's important to note that the grid-based indexing method is not available when using the Random Points method.
If you choose to specify a custom set of points, you need to upload a file containing the list of point coordinates. This file should be in ASCII text format with the .txt extension. Please note that the file size limit for uploading tracer coordinates is 1MB.
Each line of the file represents the longitude and latitude of a tracer point. The file should have two columns. The longitudes should be written in the first column, followed by the latitudes in the second column. The columns should be separated by a comma. Here's an example of a file containing the coordinates of five tracers:
-70.521275, 41.180086 -70.635745, 41.151272 -70.721598, 41.316957 -70.502196, 41.338562 -70.750216, 41.122458
Both the longitudes and latitudes are given in degrees. The longitude values should be within the range of -180ℴ to +180ℴ. If a tracer point falls outside the data domain, the solver will ignore it, but it will still be included in the output file to maintain consistency with the intended trajectory indices specified by the user.
In the User-Defined Points method, each tracer trajectory is identified by a unique ID. It's important to note that grid-based indexing is not available with this method.
For the inner computations of the solver, you can choose between two types of coordinate systems which can be selected by Coordinate System section within the interface.
In this method, the curvature of the Earth is ignored, and the domain is assumed to be flat using an equi-rectangular projection onto a tangent plane at the centroid of the initial tracers. This assumption works well when the spatial extent of your tracers (not the spatial extent of the input data) is less than 4 degrees. For larger spatial extents, it is recommended to select the spherical coordinate system.
This option takes into account the curvature of the Earth. It is suitable when the spatial extent of the tracers (not the spatial extent of the input data) is larger than 4 degrees. However, for domains with less than 4 degrees of extent, this option does not provide any advantage and may even result in arithmetic underflow during the inner computations.
For the numerical integration of trajectories, you have the flexibility to fine-tune settings for the ODE solver, ensuring it aligns with the specific characteristics of your velocity dataset. While the default settings are suitable for most scenarios, customizing these settings can optimize performance and accuracy based on your unique requirements.
You can select the numerical integration algorithm in the Integration Method section of the interface. Methods range from 2nd to 7th order numerical integrators. The default method, RKF45, is well-suited for most datasets. However, for non-smooth velocity datasets, such as those with noise or sparse measurements, you may choose a higher order scheme like RKF78, acknowledging that it may be slightly slower. Conversely, for smooth data, such as high-resolution ocean model simulations, you can use a lower order method to gain speed. Nevertheless, for most datasets, we recommend leaving this option at its default setting.
The ODE solver uses adaptive numerical integration, where the integration step size varies adaptively. Initially, the integration starts with a step size determined by Initial adaptive timestep multiplied by the time difference between two consecutive time-steps in the input dataset, namely time[i+1] - time[i].
If the integration accuracy within a Relative error tolerance is not met, the integration time-step is iteratively reduced until the desired accuracy is achieved within the specified Maximum number of iterations. Conversely, if the desired accuracy is met, the time-step is gradually increased to accelerate the solver in subsequent steps. You can control the time-step size by setting the Minimum adaptive timestep and Maximum adaptive timestep.
The default integrator settings are well-suited for most data. However, in highly noisy datasets, especially those with non-continuous velocity fields and jumps, the solver may struggle to converge. In such cases, if you encounter an error indicating that the numerical integration cannot converge, you can consider relaxing these settings by:
However, keep in mind that by relaxing these settings, the numerical solver may take longer to progress or even stall. Alternatively, you may choose a higher-order Integration Method or consider smoothening your data to avoid velocity field jumps, making it easier for the ODE solver to converge successfully.
You can choose between two types of spatial interpolations employed by the solver. The interpolation method can be set by Interpolation section within the interface.
In this method, velocity and windage variables in the input dataset are interpolated at tracer location using bilinear interpolation in space and linear interpolation in time. Bilinear interpolation is approximately twice faster than the alternative bi-cubic interpolation option.
In this method, velocity and windage variables in the input dataset are interpolated at tracer location using bi-cubic spline interpolation in space and linear interpolation in time. For low-resolution input velocity dataset, such as HF radar measurements, it is advisable to use bi-cubic spline interpolation for better accuracy.
You can choose the variables to be computed during the tracing the trajectories at the Output Variables section of the interface. These variables are described below.
Interpreting Output Variables at the Correct Time
It is essential to be aware that some of the output variables are defined for the final time \(t_f\) (including the trajectory coordinates and velocity gradient tensor), whereas other variables are defined at the initial time \(t_i\) (including Cauchy-Green deformation tensor and finite-time Lyapunov exponent (FTLE)).
However, the time variable in the output file could represent either the initial time \(t_i\) or the final time \(t_f\), depending on how the Initialization Type is set. It is important to refer to the Time section to interpret the output variables correctly.
In addition to the detailed description of each variable provided below, you can explore a compilation of output variable names, along with their corresponding NetCDF dimensions, in the NetCDF Variables section available within the tutorials.
To include the trajectory coordinates in the output file, you should explicitly enable the Output trajectory coordinates at observation times option within the interface. Once enabled, the output file will store the tracer longitudes and latitudes under the names tracer_lon and tracer_lat, respectively.
Note that the tracer coordinates are stored at their final time, \(t_f\). Hence, the time of tracer_lon[j, ...] and tracer_lat[j, ...] (the \(j\)-th time index) can be read as follows:
time[j] represents the final time \(t_f(j)\), which is the time associated with tracer_lon[j, ...] and tracer_lat[j, ...].time[j] represents the initial time \(t_i(j)\). In this case, time[j] plus the time span \(\gamma \tau\) yields the final time \(t_f(j)\), which is the time associated with tracer_lon[j, ...] and tracer_lat[j, ...].When working with the tracer coordinate variables, it is recommended to set Initialization Type to Single initial time for convenience.
The velocity gradient \(\nabla \boldsymbol{v}\) is a \(2 \times 2\) tensor with the components \(\partial v_k/\partial x_l\), \(k,l = 0, 1\). The velocity components \(\boldsymbol{v} = [v_0, v_1]\) are in the unit of meter per second, and the spatial axes \(\boldsymbol{x} = [x_0, x_1]\) are in the unit of meters (not longitudes and latitudes).
To include the velocity gradient in the output file, you should explicitly enable the Compute velocity gradient tensor on trajectory option within the interface. Once enabled, the output file will store the velocity gradient variable under the name velocity_gradient. The indices \(k\) and \(l\) of the tensor can be accessed using the NetCDF dimensions dim and dir in the output file, respectively. Specifically, dim represent the components (or dimensions) the velocity vector, while dir represents the direction of derivative along coordinate axes.
Note that the velocity gradient is computed at the final time, \(t_f\). Hence, the time of velocity_gradient[j, ...] (the \(j\)-th time index) can be read as follows:
time[j] represents the final time \(t_f(j)\), which is the time associated with velocity_gradient[j, ...].time[j] represents the initial time \(t_i(j)\). In this case, time[j] plus the time span \(\gamma \tau\) yields the final time \(t_f(j)\), which is the time associated with velocity_gradient[j, ...].When working with the velocity gradient variable, it is recommended to set Initialization Type to Single initial time for convenience.
The Cauchy-Green tensor represents the nonlinear deformation of an infinitesimal flow element for the time interval \([t_i, t_f]\). Conventionally, this quantity is assigned to the initial time \(t_i\). This physical quantity is dimensionless and is represented by a symmetric and non-negative definite matrix of the size \(2 \times 2\).
To include the Cauchy-Green variable in the output file, you should explicitly enable the Compute Cauchy-Green tensor on trajectory option within the interface. Once enable, the output file will store the Cauchy-Green variable under the name cauchy_green. The indices \(k\) and \(l\) of the Cauchy-Green tensor \(C_{kl}\) can be accessed using the NetCDF dimensions dim and dir in the output file, respectively.
Note that the Cauchy-Green tensor is conventionally defined for the initial time, \(t_i\). Hence, the time of cauchy_green[j, ...] (the \(j\)-th time index) can be read as follows:
time[j] represents the final time \(t_f(j)\). In this case, time[j] minus the time span \(\gamma \tau\) yields the initial time \(t_i(j)\), which is the time associated with cauchy_green[j, ...].time[j] represents the initial time \(t_i(j)\), which is the time associated with cauchy_green[j, ...].When working with the Cauchy-Green variable, it is recommended to set Initialization Type to Multiple initial times for convenience.
The finite-time Lyapunov exponent (FTLE) represent the exponential growth rate of an infinitesimal flow element along the principal direction of nonlinear deformation within the time interval \([t_i, t_f]\). Conventionally, this quantity is assigned to the initial time \(t_i\). This physical quantity has the dimension of day\(-1\) (day inverse). FTLE is obtained by the logarithm of the largest eigenvalue of the Cauchy-Green tensor. This value is then normalized by \(2 \tau\) where \(\tau\) is the time span of the trajectory.
Depending on whether the flow is advected forward or backward in time (refer to Time Direction option in the interface), the FTLE is referred to as either forward or backward FTLE, respectively.
To include the FTLE variable in the output file, you should explicitly enable the Compute FTLE on trajectory option within the interface. Once enabled, the output file will store the FTLE variable under the name ftle.
Note that the FTLE is conventionally defined for the initial time, \(t_i\). Hence, the time of ftle[j, ...] (the \(j\)-th time index) can be read as follows:
time[j] represents the final time \(t_f(j)\). In this case, time[j] minus the time span \(\gamma \tau\) yields the initial time \(t_i(j)\), which is the time associated with ftle[j, ...].time[j] represents the initial time \(t_i(j)\), which is the time associated with ftle[j, ...].When working with the FTLE variable, it is recommended to set Initialization Type to Multiple initial times for convenience.
The output variables in the output file can be structured using two methods:
You can select the desired indexing method using the Array Structure option within the interface. We describe the difference between these two methods, for the variable ftle, for instance, which represents the finite-time Lyapunov exponent (FTLE). Here we describe how this array should be interpreted in the output file.
In the first method, each tracer is identified by a unique trajectory ID. Consequently, the output variables would include a NetCDF dimension called trajectory. The FTLE variable, for instance, is represented as ftle[trajectory, time] in Python and ftle(time, trajectory) in MATLAB.
In the second method, each tracer is identified by the longitude and latitude indices of its initial position in the initial grid, provided that the tracers were initialized on a uniform grid (refer to Uniform Grid Points). As a result, the output variables would include the lon and lat dimensions. The FTLE variable, for instance, is represented as ftle[time, lat, lon] in Python and ftle(lon, lat, time) in MATLAB.
We emphasize that grid-based indexing method is only available if the tracers are initialized in a grid. You may refer to Uniform Grid Points section for further details.
Interactive Animation Panel and Navigation Gadgets (Click to Play/Stop).
To visualize the output results, ensure that you have selected at least one variable to be visualized in the Visualization section of the interface before starting the computation. After the computation is complete, you can visualize the chosen variables by clicking on the Visualize button. This action loads an animated visualization of your results in the map section.
There are two types of output results that can be visualized: tracers and scalar fields. However, it is important to note that these two types of visualizations cannot be selected simultaneously. Below is a description of each visualization type:
To visualize tracers, enable both Output trajectory coordinates at observation times and Visualize tracer trajectories options within the interface.
Depending on whether the trajectories are computed forward or backward in time (refer to the Time Direction option), the tracers are represented by red or yellow points, respectively. However, in both cases, the trajectories are animated in the forward time direction. The difference between forward and backward trajectory calculation lies in the initialization of the set of initial points, respectively in the beginning or at the end of the given time interval.
A Note About Visualizing Large Number of Tracers
We advise against visualizing more than approximately 20000 tracers due to the following reasons.
When the visualization of tracers is enabled, in addition to producing an output NetCDF file, the coordinates of the tracers are also written to an ASCII file with .czml format. This file is then utilized by the application's map to visualize the tracers. However, writing to an ASCII file can be time-consuming, significantly increasing the computation time, especially when dealing with a large number of tracers. Furthermore, loading this file on your browser for visualization within the map can also take a considerably long time when handling a large number of tracers.
The visualization of scalar fields includes the surface velocity divergence, normal vorticity, and the finite-time Lyapunov exponent (FTLE) fields, each described in the sections below.
Note that visualizing these scalar fields does not have the restriction on the number of tracers mentioned in the visualization of the tracer coordinates. You can visualize scalar fields generated by a large number of initial tracers.
To have more control over the visualization, you can utilize the Show Workbench button on the visualization screen. This allows you to set desired color ranges and styles for a customized display. If you are visualizing a large dataset on a slow internet connection, consider switching to a 2D map view (as opposed to the spherical globe) by clicking the Map button on the top-right corner of the map screen. Additionally, to reset the normal angle view on the domain, click on the circle in the middle of the zoom buttons on the right panel of the screen.
The surface velocity divergence is obtained from the velocity gradient tensor and computed as \(\partial v_0 /\partial x_0 + \partial v_1 / \partial x_1\). Note that the surface velocity divergence does not take into account the vertical component of the velocity.
You can visualize the surface velocity divergence by enabling both Compute velocity gradient tensor on trajectory and Visualize surface velocity divergence options within the interface.
It is important to interpret the surface velocity divergence field at the correct time, as explained in the section Interpreting Velocity Gradient at the Correct Time.
The normal vorticity field is obtained from the velocity gradient tensor and computed as \(\partial v_1 /\partial x_0 - \partial v_0 / \partial x_1\). Note that the normal vorticity only takes into account a component of the vorticity normal to the ocean's surface.
You can visualize the normal vorticity by enabling both Compute velocity gradient tensor on trajectory and Visualize normal vorticity options within the interface.
It is important to interpret the normal vorticity field at the correct time, as explained in the section Interpreting Velocity Gradient at the Correct Time.
You can visualize the FTLE field by enabling both Compute FTLE on trajectory and Visualize FTLE options within the interface.
It is important to interpret the FTLE field at the correct time, as explained in the section Interpreting FTLE at the Correct Time.
Note that the output data is stored only during the lifetime of your browser session. Once you refresh or close your browser, both the uploaded input data (if any) and the generated output files will be completely purged from the server.
You can download the output result using Download button. Depending on your selection of single or multi-file dataset (refer to Multi-File Datasets), the output file you download can be one of the following:
If your input consists of a single dataset (either as a single input file or multiple files representing a single dataset), the output result will be a single .nc file.
If your input files represent multiple separate datasets (refer to Multiple Separate Dataset, Each within a File), a distinct output file with a .nc format is generated for each input file (or URL). These output files are named similarly to their corresponding input files. All of these files are then bundled into a .zip file. When you download your results, you will receive this zip file.
If you have chosen to visualize tracers (refer to the Visualize Tracers section), an ASCII file with a .czml format is generated along with the NetCDF output file(s). The CZML file contains the coordinates of the tracers and is used solely for visualization within this application's map. However, you have the option to download this file from the dropdown menu on the Download button by selecting Download CZML.
During the generation of output results, the output NetCDF files are temporarily hosted on our THREDDS data server for the duration of your browser session. As such, you have the option to view the THREDDS catalog page corresponding to your data. The catalog page contains useful information about your output file, allowing you to explore its contents before downloading. You can use services such as OPENDAP to explore the variables, NetcdfSubset to subset your data, and Godiva3 as an alternative visualization tool.
To access the THREDDS catalog of your data, navigate to the dropdown menu on the right corner of the Download button and select View THREDDS Catalog.
Every user's session is assigned a distinct ID, represented by a 32-character string. This ID serves as both the name for the output files and can be useful for reporting any bugs or issues. You can locate your exclusive identifier in the About section below.
To conveniently save and retrieve your configuration settings within your session, our application offers to save and load the form contents. By clicking on the Save Form button, you can store all the settings you have entered into a file named FormData.json. This file captures your configuration and can be downloaded for future use. In subsequent visits to the web page, you can easily restore your previous settings by uploading the FormData.json file using the Load Form button. Examples of form files for various tasks can be found in the Produce Output File section within the tutorials provided below.
The following concise tutorial offers guidance on reading the output files using NetCDF library in both Python and MATLAB. If you require general information on utilizing the NetCDF library, you can consult the NetCDF API in Python or NetCDF Files tutorial in MATLAB.
To install the NetCDF package in Python, you have two options:
Using conda to install the NetCDF package distributed on Anaconda Cloud:
$ conda install -c conda-forge netcdf4
Using pip to install the NetCDF package distributed on PyPI:
$ sudo pip install netCDF4
For MATLAB users, the NetCDF library is already included in the MATLAB installation.
To begin, you can utilize the form files provided below, each of which includes preset settings for a specific task:
Download the desired form and load it into the interface using the Load Form button. This action pre-configures the interface settings, but you can adjust them as needed. Once the settings are ready, scroll to the bottom of the interface and click on the Restore button to initiate the computation. Once the computation is complete, use the Download button to retrieve the output results. The resulting output file will be saved under the name output-dataset.nc.
Below are brief demonstrations on how to read the output file and view its variables using both Python and MATLAB. Keep in mind that the list of output variables in the code examples below may differ based on the specific example you selected.
# Import the netCDF4 package
>>> import netCDF4
# Create a NetCDF object from the data
>>> nc = netCDF4.Dataset('output-dataset.nc')
# Print the list of all dimensions in the file
>>> nc.dimensions.keys()
dict_keys(['time', 'lon', 'lat', 'dim', 'dir'])
# Print the list of all variables in the file
>>> nc.variables.keys()
dict_keys(['time', 'lon', 'lat', 'tracer_lon', 'tracer_lat', 'velocity_gradient', 'cauchy_green', 'ftle'])
# Assigning nc objects to variables
>>> t = nc.variables['time']
>>> lon = nc.variables['lon']
>>> lat = nc.variables['lat']
>>> tracer_lon = nc.variables['tracer_lon']
>>> tracer_lat = nc.variables['tracer_lat']
>>> vg = nc.variables['velocity_gradient']
>>> cg = nc.variables['cauchy_green']
>>> ftle = nc.variables['ftle']
>> % Display NetCDF file information
>> ncdisp('output-dataset.nc')
>> % Alternative way of getting a summary of file information
>> info = ncinfo('output-dataset.nc');
>> % Get dimensions name
>> info.Dimensions
>> % Get variables info
>> info.Variables
>> % Assigning nc objects to variables
>> t = ncread('output-dataset.nc', 'time');
>> lon = ncread('output-dataset.nc', 'lon');
>> lat = ncread('output-dataset.nc', 'lat');
>> tracer_lon = ncread('output-dataset.nc', 'tracer_lon');
>> tracer_lat = ncread('output-dataset.nc', 'tracer_lat');
>> vg = ncread('output-dataset.nc', 'velocity_gradient');
>> cg = ncread('output-dataset.nc', 'cauchy_green');
>> ftle = ncread('output-dataset.nc', 'ftle');
The NetCDF dimensions and variables in the above code are further detailed below.
The output dataset contains some or all of the following NetCDF dimensions, depending on the configuration:
| Name | Size | Description |
|---|---|---|
time |
Depending on the Initialization Type option:
|
The time dimension of variables. |
lon |
Number of tracers along longitude axis | Longitude index used to identify tracers based on their initial grid position. This dimension is included in the output data only if the Grid-indexed arrays option is chosen (also refer to the Grid-Indexed Arrays section). |
lat |
Number of tracers along latitude axis | Latitude index used to identify tracers based on their initial grid position. This dimension is included in the output data only if the Grid-indexed arrays option is chosen (also refer to the Grid-Indexed Arrays section). |
trajectory |
Depending on the Initialize Tracers option:
|
Index used to identify tracers. This dimension is present in the output data only if the Trajectory-indexed arrays option is chosen (also refer to the Trajectory-Indexed Arrays section). |
dim |
Two |
This index is used to identify the spatial axes, with the values of 0 and 1 indicating the longitude and latitude axes, respectively. This dimension appears in the output data only if either of the following variables are included in the output dataset:
|
dir |
Two |
This index is used to identify the direction of partial derivatives along spatial axes, with the values of 0 and 1 indicating the derivative direction along longitude and latitude axis, respectively. This dimension appears in the output data only if either of the following variables is included in the output dataset:
|
The output dataset contains some or all of the following NetCDF variables, depending on the configuration:
| Variable | Name and Dimensions | Notes | ||
|---|---|---|---|---|
| Time | time[time] |
Depending on Initialization Type:
|
||
| Grid Longitude | lon[lon] |
Longitude of the grid where the tracers are initialized. This variable appears in the output data only if the Grid-indexed arrays option is chosen (also refer to the Grid-Indexed Arrays section). | ||
| Grid Latitude | lat[lat] |
Latitude of the grid where the tracers are initialized. This variable appears in the output data only if the Grid-indexed arrays option is chosen (also refer to the Grid-Indexed Arrays section). | ||
| Tracers Longitude |
|
Longitude of tracers. This variable appears in the output data only if the Output trajectory coordinates at observation times option is chosen (also refer to Trajectory Coordinates section). | ||
| Tracers Latitude |
|
Latitude of tracers. This variable appears in the output data only if the Output trajectory coordinates at observation times option is chosen (also refer to Trajectory Coordinates section). | ||
| Velocity Gradient |
|
Velocity gradient tensor along tracers trajectory. This variable appears in the output data only if the Compute velocity gradient tensor on trajectory option is chosen (also refer to Velocity Gradient Tensor section). | ||
| Cauchy Green |
|
Cauchy-Green deformation tensor. This variable appears in the output data only if the Compute Cauchy-Green tensor on trajectory option is chosen (also refer to Cauchy-Green Deformation Tensor section). | ||
| FTLE |
|
Finite-time Lyapunov exponent. This variable appears in the output data only if the Compute FTLE on trajectory option is chosen (also refer to Finite-Time Lyapunov Exponent (FTLE) section). |
The indexing for the variables listed in the above table is presented for Python. It's important to note that the indexing of NetCDF variables in MATLAB follows a reverse ordering. For instance, a variable like ftle[time, lat, lon] in Python should be interpreted as ftle(lon, lat, time) in MATLAB.
Martha's Vineyard, MA
Monterey Bay, CA
If you find TraceFlows valuable for your research, we kindly ask that you recognize the original contributions by citing the following references:
| [1] | TraceFlows - An online high-performance computational service for Lagrangian analysis of geophysical flows. Available at https://traceflows.org | BibTex | |||
|
We are delighted to introduce RestoreIO, a companion tool to TraceFlows that offers computational services to Restore Incomplete Oceanographic datasets, with a specific focus on ocean surface velocity data. This gateway can also generate data ensembles and perform statistical analysis, which allows uncertainty qualification of such datasets. The output of RestoreIO is seamlessly compatible with TraceFlows, allowing users to preprocess their data and reconstruct missing spatial gaps before proceeding to in-depth Lagrangian analysis with TraceFlows.
You can access RestoreIO at https://restoreio.org.
Issues and comments may be addressed to ude.yelekreb@ilemas. Please provide the Session ID within your email to better identify issues. Your current session ID is:
This material is based upon work supported by the National Science Foundation grant No. 1520825.
