Add a low pass time filter to GK

[Maxwell-Rosen]

Feature

Summary

The coding for this PR was almost entirely done with GitHub Copilot, with @Maxwell-Rosen providing direction. I certify the results and take responsibility for any mistakes that may have been made.

Purpose: A low-pass filter is added to the gk_species_damping modules to damp high-frequency oscillations in $f$.

$$ \frac{d f_s}{d t} = -\nu_{\rm LP} \left(f_s-\bar f_s\right), $$

$$ \frac{d \bar f_s}{d t} = \nu_{\rm LP} \left(f_s-\bar f_s\right). $$

Issue link: fixes #985

Implementation Details

Key changes:
This PR features pretty big changes, extending from gk_species_damping.c, all the way to the SSPRK3 time stepper. This is necessary because the low-pass filter adds an entirely new equation, RHS, and a new variable to step in time. I did my best to preserve the current architecture while simply adding new arguments to existing functions and mirroring how the distribution function is updated.

The new variable fbar is constructed as P0 so that this feature doesn't take up too much memory. I am pretty sure that fbar and f having different bases will not cause discritization errors, but I wouldn’t be surprised if it did.

I had to refactor gk_species_damping quite a lot because there were tons of if statements in the advance functions and the write function.

There are severe merge conflicts with #934, so I ultimately deprecated the loss cone damping term. I'm not using this, and no one else is running mirror simulations. If it's important in the future, we can always bring it back. This was implemented as one of the first ideas regarding pseudo-orbit averaging, which did not work as we intended.

Although this function does look like a BGK operator, we should keep the BGK collisions app seperate, while this term is used to damp oscillations. The damping properties of the low pass filter are why I put this in damping, not the bgk app.

Automated testing: rt_gk_wham_1x2v has included this as a term in its input file

Example Use

  struct gkyl_gyrokinetic_species elc = {
    ...
    .damping = {
      .type = GKYL_GK_DAMPING_LOW_PASS_FILTER,
      .rate_const = 1/1e-6, # Damps on a time scale of 1e-6 seconds
      .write_rate = true,
      .write_fbar = true,
    },
    ....
  },

Community Standards

• Documentation has been updated.
• My code follows the project's coding guidelines.
• Changes to layer/zero should have a unit test, e.g., core/zero.

Testing:

• I added a regression test to test this feature.
• I added this feature to an existing regression test.
• I added a unit test to test this feature.
• Ran make check and unit tests all pass.
• I ran the code with make valcheck, and it is clean.
• I ran the code through computer-sanitizer on GPU, and it is clean.
• I ran a few regression tests to ensure no apparent errors.
• Tested and works on CPU.
• Tested and works on multi-CPU.
• Tested and works on GPU.
• Tested and works on multi-GPU.

Additional Notes

gyrokinetic/creg/rt_gk_mirror_boltz_elc_poa_1x2v_p1.c and gyrokinetic/creg/rt_gk_mirror_boltz_elc_damping_1x2v_p1.c are valgrind clean, even with the resets and restoring fbar during different cycles.

Here is a simulation that used the low-pass filter using R=50 for the mirror ratio. I do notice that the time evolution is much slower in the density; however, in the temperatures, it can be quite rapid. Although rapid oscillations are strongly damped, they still occur. This simulation uses rate_const = 1/5e-6.

[Maxwell-Rosen]

This will merge after the sundials branch. It heavily interacts with #996