🌊 OceananigansLagrangianFilter.jl

A set of tools to perform online or offline Lagrangian filtering on Oceananigans.jl simulation output.

---

📄 Overview

OceananigansLagrangianFilter.jl filters simulation data generated by Oceananigans.jl simulations. The package provides methods for both offline (post-simulation) and online (in-simulation) filtering to remove motions that are high frequency in the Lagrangian frame. This is useful, for example, for removing waves from simulations when there is strong Doppler shifting, or when the wave displacement is large.

OceananigansLagrangianFilter.jl solves sets of partial differential equations using the native Oceananigans solvers to find the filtered fields. It makes use of efficient sum-of-exponential filters (see Minz et al. 2025) to find the filtered variables at every simulation time, not just at one given reference time. More detailed documentation to come, and see more details below.

---

✨ Features

• Offline Filtering: Apply low-pass Lagrangian filters to existing Oceananigans output, saved in .jld2 format.

• Online Filtering: Integrate filters directly into Oceananigans.jl simulations.

• Multiple Filter Types: Supports custom filter shapes, with 'optimal' default Butterworth-type filters easily implemented.

• Easy Integration: Designed to work directly with Oceananigans.jl data formats.

---

🛠️ Installation

To install OceananigansLagrangianFilter, run the following in the Julia REPL:

using Pkg
Pkg.add("OceananigansLagrangianFilter")

Or, in Pkg mode (by pressing ]):

pkg> add OceananigansLagrangianFilter

To install the dev version:

using Pkg
Pkg.add(url = "https://github.com/loisbaker/OceananigansLagrangianFilter.jl.git")

Or, in Pkg mode (by pressing ]):

add https://github.com/loisbaker/OceananigansLagrangianFilter.jl.git

---

🚀 Quick Start

Offline Filtering

Offline filtering (whereby the data is processed after simulation time) allows for better filter shapes, since for a given reference time, data from the past and the future is available. The filters implemented here have real frequency response, and therefore have linear phase shift. If the exact properties of the filter shape are important, then offline filtering is preferable.

Here is a simple example of how to filter a pre-existing dataset.

using OceananigansLagrangianFilter
using Oceananigans.Units
using CUDA

# Define the filter configuration
filter_config = OfflineFilterConfig(original_data_filename = "my_simulation.jld2", # Where the original simulation output is
                                    output_filename = "my_filtered_simulation.jld2" # Where to save the filtered output
                                    var_names_to_filter = ("T", "b"), # Which variables to filter
                                    velocity_names = ("u","v"), # Velocities to use for remapping
                                    architecture = GPU(), # CPU() or GPU()
                                    Δt = 20minutes, # Time step of filtering simulation
                                    T_out = 1hour, # How often to output filtered data
                                    N = 2, # Order of Butterworth filter
                                    freq_c = 1e-4/2, # Cut-off frequency of Butterworth filter
                                    output_netcdf = false, # Whether to output filtered data to a netcdf file in addition to .jld2
                                    delete_intermediate_files = true, # Delete the individual output of the forward and backward passes
                                    compute_Eulerian_filter = true) # Whether to compute the Eulerian filter for comparison

# Run the offline filter
run_offline_Lagrangian_filter(filter_config)

# The filtered data is now saved to `my_filtered_simulation.jld2`

You can find an example of a simple simulation of geostrophic adjustment in /examples/geostrophic_adjustment.jl. The filtering is then performed using /examples/offline_filter_geostrophic_adjustment.jl.

Online Filtering

For online filtering, you would integrate the filter directly into your Oceananigans.jl setup, using the helper functions provided. See an example corresponding to the above online filtering in /examples/online_filter_geostrophic_adjustment.jl. The filtered values are then computed as your simulation runs, avoiding the need to save data at high frequency.

---

Learn more

There's lots of documentation, examples, and explanation of the methods available in our documentation

---

💻 Contributing

We welcome contributions! See contributing.md.

---

🤝 Support

If you encounter any issues, questions, or requests for functionality, it would be very helpful if you could raise an issue on the GitHub repository.

---

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.