Particle-in-Cell for Efficient Swell - PiCLES

PiCLES is a fast and efficient wave model for Earth System Models, using Particle-in-Cell methods for better performance.

The PiCLES on a Surfboard|200px

PiCLES:

JAMES paper version:

Quick Start

A brief guide on how to use PiCLES.

How to Install

Step 1: Install Julia

Download Julia v1.10.2 or higher from the official Julia website.
Follow the installation instructions for your operating system.

Step 2: Download PiCLES Repository

(Once registered as a Package this will be simpler, sry for the delay)

Open a terminal or command prompt.

Clone the PiCLES repository using Git:

git clone https://github.com/mochell/PiCLES.git

Navigate into the cloned repository directory:
```
cd PiCLES
```

Step 3: Install Dependencies and Activate Environment

Start Julia by typing julia in your terminal within the PiCLES.jl directory.
Activate the project environment:
```
using Pkg
Pkg.activate(".")
```
Install the required dependencies:
```
Pkg.instantiate()
```

You are now ready to use PiCLES for your simulations.

How to Run Tests

To run the T04_2D_reg_test.jl file from the command line, follow these steps:

Open a terminal or command prompt.
Navigate to the directory where the T04_2D_reg_test.jl file is located.
Start Julia by typing julia in your terminal.
In the Julia REPL, include the T04_2D_reg_test.jl file:
```
include("T04_2D_reg_test.jl")
```
The test will run and display the results in the terminal.

Basic model structure

PiCLES follows the modular model structure from Oceananigans.jl, but it does not currently share objects. Functionality from Oceananigans does not work in PiCLES.

A minimal working example is the following examples/example_00_minimal.jl:

   using Pkg
   # This will be replaced by the module load in the future
   Pkg.activate("PiCLES/")  # Activate the PiCLES package 

   using PiCLES
   using PiCLES.Operators.core_2D: ParticleDefaults
   using PiCLES.Models.WaveGrowthModels2D: WaveGrowth2D
   using PiCLES.Simulations
   using PiCLES.ParticleMesh: TwoDGrid, TwoDGridNotes, TwoDGridMesh

   using PiCLES.ParticleSystems: particle_waves_v5 as PW
   using Oceananigans.Units

   # just for simple plotting
   import Plots as plt

   # Parameters
   U10, V10 = 10.0, 10.0 # m/s 
   DT = 10minutes
   r_g0 = 0.85 # ratio of c / c_g (phase velocity/ group velocity).

   # Define wind functions
   u(x, y, t) = U10
   v(x, y, t) = V10
   winds = (u=u, v=v)

   # Define grid
   grid = TwoDGrid(100e3, 51, 100e3, 51) # rectangular grid, 51 grid points, 100e3 meters 
   gn = TwoDGridNotes(grid)

   # Define ODE parameters
   ODEpars, Const_ID, Const_Scg = PW.ODEParameters(r_g=r_g0)

   # Define particle equations
   particle_system = PW.particle_equations(u, v, γ=Const_ID.γ, q=Const_ID.q);

   # Calculate minimal wind sea based on characteristic winds
   WindSeamin = FetchRelations.MinimalWindsea(U10, V10, DT)

   # Define default particle
   default_particle = ParticleDefaults(WindSeamin["lne"], WindSeamin["cg_bar_x"], WindSeamin["cg_bar_y"], 0.0, 0.0)

   # Define ODE settings
   ODE_settings = PW.ODESettings(
     Parameters=ODEpars,
     # define mininum energy threshold
     log_energy_minimum=WindSeamin["lne"],
     saving_step=DT,
     timestep=DT,
     total_time=T = 6days,
     dt=1e-3, 
     dtmin=1e-4, 
     force_dtmin=true)

   # Build wave model
   wave_model = WaveGrowth2D(; grid=grid,
     winds=winds,
     ODEsys=particle_system,
     ODEsets=ODE_settings,
     periodic_boundary=false,
     minimal_particle=FetchRelations.MinimalParticle(U10, V10, DT),
     movie=true)

   # Build simulation
   wave_simulation = Simulation(wave_model, Δt=DT, stop_time=2hour)

   # Run simulation
   run!(wave_simulation, cash_store=true)

   # Plot initial state
   istate = wave_simulation.store.store[end];
   p1 = plt.heatmap(gn.x / 1e3, gn.y / 1e3, istate[:, :, 1])

mochell / PiCLES

readme