GPU RHS 1 : Sources (not collisions)

src/geometryXVx/README.md

@@ -1,13 +1,11 @@
 # Geometry (x, v\_x)
 
-The `geoemtryXVx` folder contains all the code describing methods which are specific to a geometry with 1 spatial dimension and 1 velocity dimension. It is broken up into the following sub-folders:
-
-<!-- - [boltzmann](./botzmann/README.md) - -->
-- [geometry](./geometry/README.md)  --> - All the dimension tags used for a simulation in the geometry.
-<!-- - [initialization](./initialization/README.md) - -->
-- [poisson](./poisson/README.md) - Code describing the polar Poisson solver.
-<!-- - [rhs](./rhs/README.md) - Code describing the operators on the right hand side of the Boltzmann equation; namely sources, sinks and collisions.-->
-<!-- - [time_integration](./time_integration/README.md) - -->
-<!-- - [utils](./utils/README.md) - -->
-
-
+The `geometryXVx` folder contains all the code describing methods which are specific to a geometry with 1 spatial dimension and 1 velocity dimension. It is broken up into the following sub-folders:
+
+- [boltzmann](./boltzmann/README.md) : Solvers for a Boltzmann equation. 
+- [geometry](./geometry/README.md) : All the dimension tags used for a simulation in the geometry.
+- [initialization](./initialization/README.md) : Initialization methods for the distribution function. 
+- [poisson](./poisson/README.md) : Code describing the polar Poisson solver.
+- [rhs](./rhs/README.md) : Code describing the operators on the right hand side of the Boltzmann equation; namely sources, sinks and collisions.
+- [time_integration](./time_integration/README.md) : Time integrators for a Boltzmann-Poisson system of equations. 
+- [utils](./utils/README.md) : Miscellaneous utility functions.

src/geometryXVx/boltzmann/README.md

@@ -0,0 +1,11 @@
+# Boltzmann solver
+
+The `boltzmann` folder contains methods for solving a Boltzmann equation. Such methods typically take the distribution function and the electric field computed at a given time $t$, and return the value of the distribution function at a time $t+dt$, where $dt$ is the timestep of the simulation. A Boltzmann equation refers to an advection equation in phase space with sources. In the simplified 1D geometry in space and velocity it has the general form 
+
+$\partial_t f + v \partial_x f + \frac{E}{m}\, \partial_v f = S(f)$
+
+Where $f$ is the distribution function, $x$ and $v$ are the space and velocity variables respectively, $E$ is the electric field and $m$ is the mass of the considered plasma species. The $S(f)$ operator refers to any source terms (including collisions). When taking $S(f)=0$ this equation is often referred to as a Vlasov equation.
+
+The implemented Boltzmann solvers are: 
+- SplitRightHandSideSolver
+- SplitVlasovSolver

src/geometryXVx/boltzmann/iboltzmannsolver.hpp

@@ -4,10 +4,25 @@
 
 #include <geometry.hpp>
 
+/**
+ * @brief An abstract class for solving a Boltzmann equation.
+ */
 class IBoltzmannSolver
 {
 public:
     virtual ~IBoltzmannSolver() = default;
 
-    virtual DSpanSpXVx operator()(DSpanSpXVx allfdistribu, DViewX efield, double dt) const = 0;
+    /**
+     * @brief Operator for solving the Boltzmann equation on one timestep.
+     * @param[in, out] allfdistribu On input : the initial value of the distribution function.
+     *                              On output : the value of the distribution function after solving 
+     *                              the Boltzmann equation on one timestep.
+     * @param[in] efield The electric field computed at every spatial position.
+     * @param[in] dt The timestep.
+     * @return The distribution function after solving the Boltzmann equation.
+     */
+    virtual device_t<DSpanSpXVx> operator()(
+            device_t<DSpanSpXVx> allfdistribu,
+            DViewX efield,
+            double dt) const = 0;
 };

src/geometryXVx/boltzmann/splitrighthandsidesolver.cpp

@@ -17,8 +17,8 @@ SplitRightHandSideSolver::SplitRightHandSideSolver(
 {
 }
 
-DSpanSpXVx SplitRightHandSideSolver::operator()(
-        DSpanSpXVx const allfdistribu,
+device_t<DSpanSpXVx> SplitRightHandSideSolver::operator()(
+        device_t<DSpanSpXVx> const allfdistribu,
         DViewX const electric_field,
         double const dt) const
 {

src/geometryXVx/boltzmann/splitrighthandsidesolver.hpp

@@ -10,18 +10,49 @@
 
 #include "iboltzmannsolver.hpp"
 
+/**
+ * @brief A class that solves a Boltzmann equation using Strang's splitting.
+ *
+ * The solver splits the Boltzmann equation and separates the advective 
+ * part from the source part. The sources refers to any operator that 
+ * appears on the right-hand-side of Boltzmann's equation (typically, every 
+ * operator except the advections). The splitting involves solving all the
+ * source terms on a dt/2 timestep, then solving the advections on a dt
+ * timestep using a Vlasov solver, then solving the sources again on dt/2
+ * in reverse order. 
+ */
 class SplitRightHandSideSolver : public IBoltzmannSolver
 {
+    /** Member solver for the Vlasov equation. */
     IBoltzmannSolver const& m_boltzmann_solver;
 
+    /** Member vector containing the source terms. */
     std::vector<std::reference_wrapper<IRightHandSide const>> m_rhs;
 
 public:
+    /**
+     * @brief Creates an instance of the split boltzmann solver class.
+     * @param[in] vlasov_solver A solver for the associated Vlasov equation 
+     *                          (the boltzmann equation with no sources).
+     * @param[in] rhs A vector containing all of the source terms of the 
+     *                          considered Boltzmann equation.
+     */
     SplitRightHandSideSolver(
             IBoltzmannSolver const& vlasov_solver,
             std::vector<std::reference_wrapper<IRightHandSide const>> rhs);
 
     ~SplitRightHandSideSolver() override = default;
-
-    DSpanSpXVx operator()(DSpanSpXVx allfdistribu, DViewX electric_field, double dt) const override;
+    /**
+     * @brief Solves a Boltzmann equation on a timestep dt.
+     * @param[in, out] allfdistribu On input: the initial value of the distribution function.
+     *                              On output: the value of the distribution function after solving 
+     *                              the Boltzmann equation.
+     * @param[in] electric_field The electric field computed at all spatial positions. 
+     * @param[in] dt The timestep. 
+     * @return The distribution function after solving the Boltzmann equation.
+     */
+    device_t<DSpanSpXVx> operator()(
+            device_t<DSpanSpXVx> allfdistribu,
+            DViewX electric_field,
+            double dt) const override;
 };

src/geometryXVx/boltzmann/splitvlasovsolver.cpp

@@ -13,13 +13,16 @@ SplitVlasovSolver::SplitVlasovSolver(
 }
 
 
-DSpanSpXVx SplitVlasovSolver::operator()(
-        DSpanSpXVx const allfdistribu,
+device_t<DSpanSpXVx> SplitVlasovSolver::operator()(
+        device_t<DSpanSpXVx> const allfdistribu_device,
         DViewX const electric_field,
         double const dt) const
 {
+    auto allfdistribu_alloc = ddc::create_mirror_view_and_copy(allfdistribu_device);
+    ddc::ChunkSpan allfdistribu = allfdistribu_alloc.span_view();
     m_advec_x(allfdistribu, dt / 2);
     m_advec_vx(allfdistribu, electric_field, dt);
     m_advec_x(allfdistribu, dt / 2);
-    return allfdistribu;
+    ddc::deepcopy(allfdistribu_device, allfdistribu);
+    return allfdistribu_device;
 }

src/geometryXVx/boltzmann/splitvlasovsolver.hpp

@@ -6,23 +6,52 @@
 
 #include "iboltzmannsolver.hpp"
 
+/**A generic class for a spatial advection*/
 template <class Geometry, class DDimX>
 class IAdvectionSpatial;
+/**A generic class for a velocity advection*/
 template <class Geometry, class DDimV>
 class IAdvectionVelocity;
 
+/**
+ * @brief A class that solves a Vlasov equation using Strang's splitting.
+ *
+ * The Vlasov equation is split between two advection equations 
+ * along the X and Vx directions. The splitting involves solving 
+ * the x-direction advection first on a time interval of length dt/2, 
+ * then the vx-direction advection on a tim dt, and then x-direction
+ * again on dt/2.
+ */
 class SplitVlasovSolver : public IBoltzmannSolver
 {
+    /** Member advection operator in the x direction*/
     IAdvectionSpatial<GeometryXVx, IDimX> const& m_advec_x;
 
+    /** Member advection operator in the vx direction*/
     IAdvectionVelocity<GeometryXVx, IDimVx> const& m_advec_vx;
 
 public:
+    /**
+     * @brief Creates an instance of the split vlasov solver class.
+     * @param[in] advec_x An advection operator along the x direction.
+     * @param[in] advec_vx An advection operator along the vx direction.
+     */
     SplitVlasovSolver(
             IAdvectionSpatial<GeometryXVx, IDimX> const& advec_x,
-            IAdvectionVelocity<GeometryXVx, IDimVx> const& m_advec_vx);
+            IAdvectionVelocity<GeometryXVx, IDimVx> const& advec_vx);
 
     ~SplitVlasovSolver() override = default;
-
-    DSpanSpXVx operator()(DSpanSpXVx allfdistribu, DViewX electric_field, double dt) const override;
+    /**
+     * @brief Solves a Vlasov equation on a timestep dt.
+     * @param[in, out] allfdistribu On input : the initial value of the distribution function.
+     *                              On output : the value of the distribution function after solving 
+     *                              the Vlasov equation.
+     * @param[in] electric_field The electric field computed at all spatial positions. 
+     * @param[in] dt The timestep. 
+     * @return The distribution function after solving the Vlasov equation.
+     */
+    device_t<DSpanSpXVx> operator()(
+            device_t<DSpanSpXVx> allfdistribu,
+            DViewX electric_field,
+            double dt) const override;
 };

src/geometryXVx/initialization/README.md

@@ -1,3 +1,9 @@
-# Initializatin methods
+# Initialization methods
 
-Initialization methods define the value of the distribution function at the start of the simulation. For instance, these methods allows for initializing the distribution function as a perturbed maxwellian, or to read the values from a previous simulation.  
+The initialization folder contains any methods that define the value of the distribution function at the start of the simulation.
+
+The implemented initialization methods are: 
+- BumpontailEquilibrium
+- MaxwellianEquilibrium
+- RestartInitialization
+- SingleModePerturbInitialization

src/geometryXVx/initialization/bumpontailequilibrium.cpp

@@ -38,14 +38,6 @@ device_t<DSpanSpVx> BumpontailEquilibrium::operator()(
     return allfequilibrium;
 }
 
-/*
-Computation of the Maxwellian fM which is the equilibrium part 
-of the distribution function : 
-  fM(v) = f1(v) + f2(v) 
-with 
-  f1(v) = (1-epsilon)/(sqrt(2*PI))*exp(-v**2/2)  
-  f2(v) = epsilon/sqrt(2*PI*T0)[exp(-(v-v0)**2/2*T0)]
-*/
 void BumpontailEquilibrium::compute_twomaxwellian(
         device_t<DSpanVx> const fMaxwellian,
         double const epsilon_bot,

src/geometryXVx/initialization/bumpontailequilibrium.hpp

@@ -7,50 +7,83 @@
 
 #include "iequilibrium.hpp"
 
-/// Equilibrium operator as the sum of two Maxwellian. This initializes all species.
+/**
+ * @brief A class that initializes the distribution function as a sum of two Maxwellian functions.
+ *
+ * This class initializes the distribution function as a sum of two Maxwellian, 
+ * enabling the study of the so-called bump-on-tail instability. One of the 
+ * Maxwellians represents the bulk of the distribution function that has no mean 
+ * velocity, and the other Maxwellian corresponds to high velocity particles. 
+ * The second Maxwellian is referred to as the "bump-on-tail" Maxwellian.
+ */
 class BumpontailEquilibrium : public IEquilibrium
 {
-    // density of the bump-on-tail part for all kinetic species
+    /**Density of the bump-on-tail part for all kinetic species*/
     FieldSp<double> m_epsilon_bot;
 
-    // temperature of the bump-on-tail for all kinetic species
+    /**Temperature of the bump-on-tail for all kinetic species*/
     FieldSp<double> m_temperature_bot;
 
-    // mean velocity of the bump-on-tail for all kinetic species
+    /**Mean velocity of the bump-on-tail for all kinetic species*/
     FieldSp<double> m_mean_velocity_bot;
 
 public:
-    /*
-      Computation of the Maxwellian fM which is the equilibrium part 
-      of the distribution function : 
-        fM(v) = f1(v) + f2(v) 
-      with 
-        f1(v) = (1-epsilon)/(sqrt(2*PI))*exp(-v**2/2)  
-        f2(v) = epsilon/sqrt(2*PI*T0)*0.5*[exp(-(v-v0)**2/2*T0)
-                                           +exp(-(v+v0)**2/2*T0)]
+    /**
+     * @brief Compute a distribution function defined as a sum of two Maxwellians.
+     * This distribution function can be written as 
+     * $f(x,v) = f1(v) + f2(v) $
+     * with 
+     * $f1(v) = (1-epsilon)/(sqrt(2*PI))*exp(-v**2/2)$
+     * $f2(v) = epsilon/sqrt(2*PI*T0)[exp(-(v-v0)**2/2*T0)$
+     * @param[out] fMaxwellian The initial distribution function. 
+     * @param[in] epsilon_bot A parameter that represents the density of the bump-on-tail Maxwellian. 
+     * @param[in] temperature_bot A parameter that represents the temperature of the bump-on-tail Maxwellian. 
+     * @param[in] mean_velocity_bot A parameter that represents the mean velocity of the bump-on-tail Maxwellian. 
      */
     void compute_twomaxwellian(
             device_t<DSpanVx> fMaxwellian,
             double epsilon_bot,
             double temperature_bot,
             double mean_velocity_bot) const;
-
+    /**
+     * @brief Creates an instance of the BumpontailEquilibrium class.
+     * @param[in] epsilon_bot A parameter that represents the density of the bump-on-tail Maxwellian for each species. 
+     * @param[in] temperature_bot A parameter that represents the temperature of the bump-on-tail Maxwellian for each species. 
+     * @param[in] mean_velocity_bot A parameter that represents the mean velocity of the bump-on-tail Maxwellian for each species. 
+     */
     BumpontailEquilibrium(DViewSp epsilon_bot, DViewSp temperature_bot, DViewSp mean_velocity_bot);
 
     ~BumpontailEquilibrium() override = default;
 
+    /**
+     * @brief Initializes the distribution function as the sum of a bulk and a bump-on-tail Maxwellians. 
+     * @param[out] allfequilibrium The initialized distribution function.
+     * @return The initialized distribution function.
+     */
     device_t<DSpanSpVx> operator()(device_t<DSpanSpVx> allfequilibrium) const override;
 
+    /**
+     * @brief A method for accessing the m_epsilon_bot member variable of the class.
+     * @return a View containing the m_epsilon_bot variable.
+     */
     ViewSp<double> epsilon_bot() const
     {
         return m_epsilon_bot;
     }
 
+    /**
+     * @brief A method for accessing the m_temperature_bot member variable of the class.
+     * @return a View containing the m_temperature_bot variable.
+     */
     ViewSp<double> temperature_bot() const
     {
         return m_temperature_bot;
     }
 
+    /**
+     * @brief A method for accessing the m_mean_velocity_bot member variable of the class.
+     * @return a View containing the m_velocity_bot variable.
+     */
     ViewSp<double> mean_velocity_bot() const
     {
         return m_mean_velocity_bot;

src/geometryXVx/initialization/iequilibrium.hpp

@@ -4,10 +4,19 @@
 
 #include <geometry.hpp>
 
+/**
+ * @brief An abstract class for initializing a distribution function that does not depend on space.
+ */
 class IEquilibrium
 {
 public:
     virtual ~IEquilibrium() = default;
 
+    /**
+     * @brief Operator for initializing a distribution function that does not depend on space.
+     * @param[in, out] allfequilibrium On input: the uninitialized distribution function.
+     *                                 On output: the initialized distribution function.
+     * @return The initialized distribution function.
+     */
     virtual device_t<DSpanSpVx> operator()(device_t<DSpanSpVx> allfequilibrium) const = 0;
 };

src/geometryXVx/initialization/iinitialization.hpp

@@ -4,10 +4,19 @@
 
 #include <geometry.hpp>
 
+/**
+ * @brief An abstract class that allows for initializing a distribution function.
+ */
 class IInitialization
 {
 public:
     virtual ~IInitialization() = default;
 
+    /**
+     * @brief Operator for initializing a distribution function.
+     * @param[in, out] allfdistribu On input: the uninitialized distribution function.
+     *                                 On output: the initialized distribution function.
+     * @return The initialized distribution function.
+     */
     virtual device_t<DSpanSpXVx> operator()(device_t<DSpanSpXVx> allfdistribu) const = 0;
 };

src/geometryXVx/initialization/maxwellianequilibrium.cpp

@@ -38,12 +38,6 @@ device_t<DSpanSpVx> MaxwellianEquilibrium::operator()(
     return allfequilibrium;
 }
 
-/*
- Computing the non-centered Maxwellian function as
-   fM(v) = n/(sqrt(2*PI*T))*exp(-(v-u)**2/(2*T))
-  with n the density and T the temperature and
-  where u is the mean velocity
-*/
 void MaxwellianEquilibrium::compute_maxwellian(
         device_t<DSpanVx> const fMaxwellian,
         double const density,