GitHub

Helpful tips

  • The online and offline filtering both work on GPU, just make sure CUDA is installed in the environment and loaded, and set architecture = GPU()
  • Any advection scheme can be used, whatever halo size the original data was saved with: if the scheme needs a larger halo (e.g. WENO(order=9)), the model grid's halo is inflated automatically and an @info message says so.
  • Output saved with an older version of Oceananigans may not be readable with the current one, because the saved grid can't be reconstructed (typically giving KeyError: key "grid" not found or type ReconstructedSingleton has no field ... when the data is loaded). In that case, construct the grid used by the original simulation (with the same size, extent, topology and halo size) and pass it to OfflineFilterConfig with grid = .... The data itself is then read as usual.
  • With NetCDF input, Oceananigans warns that "Reading boundary conditions from NetCDF files is not supported for FieldTimeSeries". This is expected and harmless: for both JLD2 and NetCDF input, the filter uses default boundary conditions to fill the halo regions of the input velocities and variables, and these only affect halo values that the filter doesn't use (in periodic directions, where the defaults are exact, the filter uses one halo cell of the velocities).
  • The post-processing interpolation step using regrid_to_mean_position! works on RectilinearGrids and LatitudeLongitudeGrids, including with immersed boundaries, where it is approximate next to the boundary. On a LatitudeLongitudeGrid it assumes the grid is locally Cartesian over the trajectory excursions. It gives NaN at points that are not the mean position of any particle in the fluid (see Regridding to the mean position).
  • As with any moving average, there are endpoint effects. For the offline filter, a time window at each end of the filtered timeseries of the order of the inverse of the cutoff frequency should be excluded from any further analysis. For the online filter, this is only necessary at the beginning of the timeseries.
  • This method is not tested with open boundaries. There is a fundamental causal issue with knowing the Lagrangian mean near a boundary when part of the trajectory on which it relies is outside of the domain. There are ways to approximate the solution near the open boundary to allow the code to run, (e.g. setting an open boundary condition on the Lagrangian filtered variables) but then the near-boundary region should be discarded.
  • This package can be used to filter output from other numerical models (offline). In particular, model output that shares the same Arakawa type-C grid (such as MITgcm) can easily be manipulated into Oceananigans output format and run through the Lagrangian filter.
  • Eulerian filtering can be performed in two ways. The first is to set compute_Eulerian_filter = true in the configuration for the offline filter, or to use compute_Eulerian_filter! after the online filter. Offline, this filters the original data at its saved times, as the Lagrangian filter reads it (taken to vary linearly in between). Online, it filters the variables saved in the filter output file, so it only sees them at the output interval, and is suitable when that resolves the motions being filtered out (as in the examples). It is quick. The second way is to set lagrangian = false in the OfflineFilterConfig or OnlineFilterConfig. The filtered variables are then not advected, so the filter computes the Eulerian mean, at every filter time step. This needs a separate filter run, but does not depend on the output interval. Online, it also means the unfiltered variables do not need to be saved at high frequency, and it supports a frequency scale that varies in time (frequency_scale_dependencies). Offline, nothing else is needed. Online, the model's tracer_advection must be set so that the filtered variables are not advected, with filtered_vars_advection (see Online filtering implementation). Note that the maps are then not displacements from the mean position, so no regridding is performed (regrid_to_mean is set to false), but the mean (here, Eulerian filtered) velocities can still be computed. If the filter outputs its terms separately (outputs = :separate), the Eulerian filter for comparison does too, e.g. b_Eulerian_filtered_C1_scaled and b_Eulerian_filtered_S1_scaled.