Merge pull request #6020 from gassmoeller/rework_particle_update_inte…

…rface

Rework particle update interface

doc/modules/changes/20240925_gassmoeller

@@ -0,0 +1,8 @@
+New: The interface for particle property plugins has been updated.
+The new interface can update particles cell-wise and is more efficient. 
+In addition, the interface is more extensible for future improvements.
+All particle property plugins in ASPECT have been updated, user plugins
+will have to be updated accordingly before the support for the now deprecated
+old interface is dropped.
+<br>
+(Rene Gassmoeller, 2024/09/25)

include/aspect/particle/property/composition.h

@@ -58,14 +58,11 @@ namespace aspect
                                             std::vector<double> &particle_properties) const override;
 
           /**
-           * @copydoc aspect::Particle::Property::Interface::update_particle_property()
+           * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
-          virtual
           void
-          update_particle_property (const unsigned int data_position,
-                                    const Vector<double> &solution,
-                                    const std::vector<Tensor<1,dim>> &gradients,
-                                    typename ParticleHandler<dim>::particle_iterator &particle) const override;
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
+                                      typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**
            * This implementation tells the particle manager that

include/aspect/particle/property/cpo_bingham_average.h

@@ -99,36 +99,11 @@ namespace aspect
                                             std::vector<double> &particle_properties) const override;
 
           /**
-           * Update function. This function is called every time an update is
-           * request by need_update() for every particle for every property.
-           * It is obvious that
-           * this function is called a lot, so its code should be efficient.
-           * The interface provides a default implementation that does nothing,
-           * therefore derived plugins that do not require an update do not
-           * need to implement this function.
-           *
-           * @param [in] data_position An unsigned integer that denotes which
-           * component of the particle property vector is associated with the
-           * current property. For properties that own several components it
-           * denotes the first component of this property, all other components
-           * fill consecutive entries in the @p particle_properties vector.
-           *
-           * @param [in] solution The values of the solution variables at the
-           * current particle position.
-           *
-           * @param [in] gradients The gradients of the solution variables at
-           * the current particle position.
-           *
-           * @param [in,out] particle The particle that is updated within
-           * the call of this function. The particle location can be accessed
-           * using particle->get_location() and its properties using
-           * particle->get_properties().
+           * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
           void
-          update_particle_property (const unsigned int data_position,
-                                    const Vector<double> &solution,
-                                    const std::vector<Tensor<1,dim>> &gradients,
-                                    typename ParticleHandler<dim>::particle_iterator &particle) const override;
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
+                                      typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**
            * This implementation tells the particle manager that

include/aspect/particle/property/cpo_elastic_tensor.h

@@ -90,36 +90,11 @@ namespace aspect
                                             std::vector<double> &particle_properties) const override;
 
           /**
-           * Update function. This function is called every time an update is
-           * request by need_update() for every particle for every property.
-           * It is obvious that
-           * this function is called a lot, so its code should be efficient.
-           * The interface provides a default implementation that does nothing,
-           * therefore derived plugins that do not require an update do not
-           * need to implement this function.
-           *
-           * @param [in] data_position An unsigned integer that denotes which
-           * component of the particle property vector is associated with the
-           * current property. For properties that own several components it
-           * denotes the first component of this property, all other components
-           * fill consecutive entries in the @p particle_properties vector.
-           *
-           * @param [in] solution The values of the solution variables at the
-           * current particle position.
-           *
-           * @param [in] gradients The gradients of the solution variables at
-           * the current particle position.
-           *
-           * @param [in,out] particle The particle that is updated within
-           * the call of this function. The particle location can be accessed
-           * using particle->get_location() and its properties using
-           * particle->get_properties().
+           * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
           void
-          update_particle_property (const unsigned int data_position,
-                                    const Vector<double> &solution,
-                                    const std::vector<Tensor<1,dim>> &gradients,
-                                    typename ParticleHandler<dim>::particle_iterator &particle) const override;
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
+                                      typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**
            * This function tells the particle manager that

include/aspect/particle/property/crystal_preferred_orientation.h

@@ -158,36 +158,11 @@ namespace aspect
                                             std::vector<double> &particle_properties) const override;
 
           /**
-           * Update function. This function is called every time an update is
-           * request by need_update() for every particle for every property.
-           * It is obvious that
-           * this function is called a lot, so its code should be efficient.
-           * The interface provides a default implementation that does nothing,
-           * therefore derived plugins that do not require an update do not
-           * need to implement this function.
-           *
-           * @param [in] data_position An unsigned integer that denotes which
-           * component of the particle property vector is associated with the
-           * current property. For properties that own several components it
-           * denotes the first component of this property, all other components
-           * fill consecutive entries in the @p particle_properties vector.
-           *
-           * @param [in] solution The values of the solution variables at the
-           * current particle position.
-           *
-           * @param [in] gradients The gradients of the solution variables at
-           * the current particle position.
-           *
-           * @param [in,out] particle The particle that is updated within
-           * the call of this function. The particle location can be accessed
-           * using particle->get_location() and its properties using
-           * particle->get_properties().
+           * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
           void
-          update_particle_property (const unsigned int data_position,
-                                    const Vector<double> &solution,
-                                    const std::vector<Tensor<1,dim>> &gradients,
-                                    typename ParticleHandler<dim>::particle_iterator &particle) const override;
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
+                                      typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**
            * This implementation tells the particle manager that

include/aspect/particle/property/elastic_stress.h

@@ -58,13 +58,11 @@ namespace aspect
                                             std::vector<double> &particle_properties) const override;
 
           /**
-           * @copydoc aspect::Particle::Property::Interface::update_particle_property()
+           * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
           void
-          update_particle_property (const unsigned int data_position,
-                                    const Vector<double> &solution,
-                                    const std::vector<Tensor<1,dim>> &gradients,
-                                    typename ParticleHandler<dim>::particle_iterator &particle) const override;
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
+                                      typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**
            * @copydoc aspect::Particle::Property::Interface::need_update()

include/aspect/particle/property/elastic_tensor_decomposition.h

@@ -216,36 +216,11 @@ namespace aspect
                                             std::vector<double> &particle_properties) const override;
 
           /**
-           * Update function. This function is called every time an update is
-           * request by need_update() for every particle for every property.
-           * It is obvious that
-           * this function is called a lot, so its code should be efficient.
-           * The interface provides a default implementation that does nothing,
-           * therefore derived plugins that do not require an update do not
-           * need to implement this function.
-           *
-           * @param [in] data_position An unsigned integer that denotes which
-           * component of the particle property vector is associated with the
-           * current property. For properties that own several components it
-           * denotes the first component of this property, all other components
-           * fill consecutive entries in the @p particle_properties vector.
-           *
-           * @param [in] solution The values of the solution variables at the
-           * current particle position.
-           *
-           * @param [in] gradients The gradients of the solution variables at
-           * the current particle position.
-           *
-           * @param [in,out] particle The particle that is updated within
-           * the call of this function. The particle location can be accessed
-           * using particle->get_location() and its properties using
-           * particle->get_properties().
+           * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
           void
-          update_particle_property (const unsigned int data_position,
-                                    const Vector<double> &solution,
-                                    const std::vector<Tensor<1,dim>> &gradients,
-                                    typename ParticleHandler<dim>::particle_iterator &particle) const override;
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
+                                      typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**
            * This function tells the particle manager that

include/aspect/particle/property/grain_size.h

@@ -64,9 +64,7 @@ namespace aspect
            * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
           void
-          update_particle_properties (const unsigned int data_position,
-                                      const std::vector<Vector<double>> &solution,
-                                      const std::vector<std::vector<Tensor<1,dim>>> &gradients,
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
                                       typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**

include/aspect/particle/property/integrated_strain.h

@@ -59,14 +59,11 @@ namespace aspect
                                             std::vector<double> &particle_properties) const override;
 
           /**
-           * @copydoc aspect::Particle::Property::Interface::update_particle_property()
+           * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
-          virtual
           void
-          update_particle_property (const unsigned int data_position,
-                                    const Vector<double> &solution,
-                                    const std::vector<Tensor<1,dim>> &gradients,
-                                    typename ParticleHandler<dim>::particle_iterator &particle) const override;
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
+                                      typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**
            * This implementation tells the particle manager that

include/aspect/particle/property/integrated_strain_invariant.h

@@ -58,14 +58,11 @@ namespace aspect
                                             std::vector<double> &particle_properties) const override;
 
           /**
-           * @copydoc aspect::Particle::Property::Interface::update_particle_property()
+           * @copydoc aspect::Particle::Property::Interface::update_particle_properties()
            */
-          virtual
           void
-          update_particle_property (const unsigned int data_position,
-                                    const Vector<double> &solution,
-                                    const std::vector<Tensor<1,dim>> &gradients,
-                                    typename ParticleHandler<dim>::particle_iterator &particle) const override;
+          update_particle_properties (const ParticleUpdateInputs<dim> &inputs,
+                                      typename ParticleHandler<dim>::particle_iterator_range &particles) const override;
 
           /**
            * This implementation tells the particle manager that