From 90392aa74721a6aaf63e8718083ee2deabe0b41f Mon Sep 17 00:00:00 2001
From: Rene Gassmoeller <rene.gassmoeller@mailbox.org>
Date: Tue, 20 Feb 2024 13:46:50 -0500
Subject: [PATCH] Add test

---
 include/deal.II/particles/particle.h        |  18 +++-
 tests/particles/particle_10.cc              |  51 ++++++++++
 tests/particles/particle_10.output          |   5 +
 tests/particles/particle_iterator_03.cc     | 101 ++++++++++++++++++++
 tests/particles/particle_iterator_03.output |   6 ++
 5 files changed, 180 insertions(+), 1 deletion(-)
 create mode 100644 tests/particles/particle_10.cc
 create mode 100644 tests/particles/particle_10.output
 create mode 100644 tests/particles/particle_iterator_03.cc
 create mode 100644 tests/particles/particle_iterator_03.output

diff --git a/include/deal.II/particles/particle.h b/include/deal.II/particles/particle.h
index 1d60e894a4..6a9f975a95 100644
--- a/include/deal.II/particles/particle.h
+++ b/include/deal.II/particles/particle.h
@@ -251,7 +251,23 @@ namespace Particles
     get_location() const;
 
     /**
-     * Get the location of this particle.
+     * Get read- and write-access to the location of this particle.
+     * Note that changing the location does not check
+     * whether this is a valid location in the simulation domain.
+     *
+     * @note In parallel programs, the ParticleHandler class stores particles
+     *   on both the locally owned cells, as well as on ghost cells. The
+     *   particles on the latter are *copies* of particles owned on other
+     *   processors, and should therefore be treated in the same way as
+     *   ghost entries in
+     *   @ref GlossGhostedVector "vectors with ghost elements"
+     *   or
+     *   @ref GlossGhostCell "ghost cells":
+     *   In both cases, one should
+     *   treat the ghost elements or cells as `const` objects that shouldn't
+     *   be modified even if the objects allow for calls that modify
+     *   properties. Rather, properties should only be modified on processors
+     *   that actually *own* the particle.
      *
      * @return The location of this particle.
      */
diff --git a/tests/particles/particle_10.cc b/tests/particles/particle_10.cc
new file mode 100644
index 0000000000..7f79da28ac
--- /dev/null
+++ b/tests/particles/particle_10.cc
@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------
+//
+// Copyright (C) 2014 by the deal.II authors
+//
+// This file is part of the deal.II library.
+//
+// The deal.II library is free software; you can use it, redistribute
+// it, and/or modify it under the terms of the GNU Lesser General
+// Public License as published by the Free Software Foundation; either
+// version 2.1 of the License, or (at your option) any later version.
+// The full text of the license can be found in the file LICENSE.md at
+// the top level directory of deal.II.
+//
+// ---------------------------------------------------------------------
+
+
+
+// A copy of test particle_01.cc but using the get_location
+// function to retrieve a writable reference to the location.
+
+#include <deal.II/particles/particle.h>
+
+#include "../tests.h"
+
+
+template <int dim>
+void
+test()
+{
+  {
+    Particles::Particle<dim> particle;
+
+    Point<dim> position;
+    position[0]             = 1.0;
+    particle.get_location() = position;
+
+    deallog << "Particle location: " << particle.get_location() << std::endl;
+  }
+
+  deallog << "OK" << std::endl;
+}
+
+
+
+int
+main()
+{
+  initlog();
+  test<2>();
+  test<3>();
+}
diff --git a/tests/particles/particle_10.output b/tests/particles/particle_10.output
new file mode 100644
index 0000000000..b466e15e4a
--- /dev/null
+++ b/tests/particles/particle_10.output
@@ -0,0 +1,5 @@
+
+DEAL::Particle location: 1.00000 0.00000
+DEAL::OK
+DEAL::Particle location: 1.00000 0.00000 0.00000
+DEAL::OK
diff --git a/tests/particles/particle_iterator_03.cc b/tests/particles/particle_iterator_03.cc
new file mode 100644
index 0000000000..d81ca4c0da
--- /dev/null
+++ b/tests/particles/particle_iterator_03.cc
@@ -0,0 +1,101 @@
+// ---------------------------------------------------------------------
+//
+// Copyright (C) 2017 - 2021 by the deal.II authors
+//
+// This file is part of the deal.II library.
+//
+// The deal.II library is free software; you can use it, redistribute
+// it, and/or modify it under the terms of the GNU Lesser General
+// Public License as published by the Free Software Foundation; either
+// version 2.1 of the License, or (at your option) any later version.
+// The full text of the license can be found in the file LICENSE.md at
+// the top level directory of deal.II.
+//
+// ---------------------------------------------------------------------
+
+
+
+// Like particle_iterator_01, but changes the location through the
+// particle iterator.
+
+#include <deal.II/base/array_view.h>
+
+#include <deal.II/fe/mapping_q.h>
+
+#include <deal.II/grid/grid_generator.h>
+#include <deal.II/grid/tria.h>
+
+#include <deal.II/particles/particle.h>
+#include <deal.II/particles/particle_handler.h>
+#include <deal.II/particles/particle_iterator.h>
+
+#include "../tests.h"
+
+
+template <int dim>
+void
+test()
+{
+  {
+    Triangulation<dim> tr;
+
+    GridGenerator::hyper_cube(tr);
+    MappingQ<dim>      mapping(1);
+    const unsigned int n_properties_per_particle = 3;
+
+    Particles::ParticleHandler<dim> particle_handler(tr,
+                                                     mapping,
+                                                     n_properties_per_particle);
+
+    Point<dim> position;
+    position[0] = 0.3;
+
+    if (dim > 1)
+      position[1] = 0.5;
+
+    Point<dim> reference_position;
+    reference_position[0] = 0.2;
+
+    if (dim > 1)
+      reference_position[1] = 0.4;
+
+    const types::particle_index index(7);
+
+    std::vector<double> properties = {0.15, 0.45, 0.75};
+
+    Particles::Particle<dim> particle(position, reference_position, index);
+
+    // Insert two identical particles
+    Particles::ParticleIterator<dim> particle_it =
+      particle_handler.insert_particle(particle, tr.begin());
+    particle_it->set_properties(
+      ArrayView<double>(&properties[0], properties.size()));
+
+    particle_it = particle_handler.insert_particle(particle, tr.begin());
+    particle_it->set_properties(
+      ArrayView<double>(&properties[0], properties.size()));
+
+    // Modify the location of the second particle
+    particle_it->get_location()[0] = 0.05;
+
+    for (const auto &particle : particle_handler)
+      {
+        deallog << "Particle position: " << particle.get_location() << std::endl
+                << "Particle properties: "
+                << std::vector<double>(particle.get_properties().begin(),
+                                       particle.get_properties().end())
+                << std::endl;
+      }
+  }
+
+  deallog << "OK" << std::endl;
+}
+
+
+
+int
+main()
+{
+  initlog();
+  test<2>();
+}
diff --git a/tests/particles/particle_iterator_03.output b/tests/particles/particle_iterator_03.output
new file mode 100644
index 0000000000..bf65839abb
--- /dev/null
+++ b/tests/particles/particle_iterator_03.output
@@ -0,0 +1,6 @@
+
+DEAL::Particle position: 0.300000 0.500000
+DEAL::Particle properties: 0.150000 0.450000 0.750000
+DEAL::Particle position: 0.0500000 0.500000
+DEAL::Particle properties: 0.150000 0.450000 0.750000
+DEAL::OK
-- 
2.39.5