particle.h

Go to the documentation of this file.

// ------------------------------------------------------------------------
//
// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) 2017 - 2024 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Part of the source code is dual licensed under Apache-2.0 WITH
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information
// governing the source code and code contributions can be found in
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
//
// ------------------------------------------------------------------------
 
#ifndef dealii_particles_particle_h
#define dealii_particles_particle_h
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/array_view.h>
#include <deal.II/base/point.h>
#include <deal.II/base/types.h>
 
#include <deal.II/particles/property_pool.h>
 
#include <boost/serialization/array.hpp>
 
#include <cstdint>
 
DEAL_II_NAMESPACE_OPEN
 
namespace Particles
{
  namespace internal
  {
    using LevelInd = std::pair<int, int>;
  } // namespace internal
 
  template <int dim, int spacedim = dim>
  class Particle
  {
  public:
    Particle();
 
    Particle(const Point<spacedim>      &location,
             const Point<dim>           &reference_location,
             const types::particle_index id);
 
    Particle(const Particle<dim, spacedim> &particle);
 
    Particle(const void                       *&begin_data,
             PropertyPool<dim, spacedim> *const property_pool = nullptr);
 
    Particle(Particle<dim, spacedim> &&particle) noexcept;
 
    Particle<dim, spacedim> &
    operator=(const Particle<dim, spacedim> &particle);
 
    Particle<dim, spacedim> &
    operator=(Particle<dim, spacedim> &&particle) noexcept;
 
    ~Particle();
 
    void *
    write_particle_data_to_memory(void *data) const;
 
 
    const void *
    read_particle_data_from_memory(const void *data);
 
    void
    set_location(const Point<spacedim> &new_location);
 
    const Point<spacedim> &
    get_location() const;
 
    Point<spacedim> &
    get_location();
 
    void
    set_reference_location(const Point<dim> &new_reference_location);
 
    const Point<dim> &
    get_reference_location() const;
 
    types::particle_index
    get_id() const;
 
    void
    set_id(const types::particle_index &new_id);
 
    void
    set_property_pool(PropertyPool<dim, spacedim> &property_pool);
 
    bool
    has_properties() const;
 
    void
    set_properties(const ArrayView<const double> &new_properties);
 
    ArrayView<double>
    get_properties();
 
    ArrayView<const double>
    get_properties() const;
 
    std::size_t
    serialized_size_in_bytes() const;
 
    template <class Archive>
    void
    save(Archive &ar, const unsigned int version) const;
 
    template <class Archive>
    void
    load(Archive &ar, const unsigned int version);
 
    void
    free_properties();
 
#ifdef DOXYGEN
    template <class Archive>
    void
    serialize(Archive &archive, const unsigned int version);
#else
    // This macro defines the serialize() method that is compatible with
    // the templated save() and load() method that have been implemented.
    BOOST_SERIALIZATION_SPLIT_MEMBER()
#endif
 
  private:
    static PropertyPool<dim, spacedim> global_property_pool;
 
    PropertyPool<dim, spacedim> *property_pool;
 
    typename PropertyPool<dim, spacedim>::Handle property_pool_handle;
  };
 
 
 
  /* ---------------------- inline and template functions ------------------ */
 
  template <int dim, int spacedim>
  template <class Archive>
  inline void
  Particle<dim, spacedim>::load(Archive &ar, const unsigned int)
  {
    unsigned int n_properties = 0;
 
    Point<spacedim>                       location;
    Point<dim>                            reference_location;
    types::particle_index                 id;
    ar &location &reference_location &id &n_properties;
 
    set_location(location);
    set_reference_location(reference_location);
    set_id(id);
 
    if (n_properties > 0)
      {
        ArrayView<double> properties(get_properties());
        Assert(
          properties.size() == n_properties,
          ExcMessage(
            "This particle was serialized with " +
            std::to_string(n_properties) +
            " properties, but the new property handler provides space for " +
            std::to_string(properties.size()) +
            " properties. Deserializing a particle only works for matching property sizes."));
 
        ar &boost::serialization::make_array(properties.data(), n_properties);
      }
  }
 
 
 
  template <int dim, int spacedim>
  template <class Archive>
  inline void
  Particle<dim, spacedim>::save(Archive &ar, const unsigned int) const
  {
    unsigned int n_properties = 0;
    if ((property_pool != nullptr) &&
        (property_pool_handle != PropertyPool<dim, spacedim>::invalid_handle))
      n_properties = get_properties().size();
 
    Point<spacedim>       location           = get_location();
    Point<dim>            reference_location = get_reference_location();
    types::particle_index id                 = get_id();
 
    ar &location &reference_location &id &n_properties;
 
    if (n_properties > 0)
      ar &boost::serialization::make_array(get_properties().data(),
                                           n_properties);
  }
 
 
 
  template <int dim, int spacedim>
  inline void
  Particle<dim, spacedim>::set_location(const Point<spacedim> &new_loc)
  {
    property_pool->set_location(property_pool_handle, new_loc);
  }
 
 
 
  template <int dim, int spacedim>
  inline const Point<spacedim> &
  Particle<dim, spacedim>::get_location() const
  {
    return property_pool->get_location(property_pool_handle);
  }
 
 
 
  template <int dim, int spacedim>
  inline Point<spacedim> &
  Particle<dim, spacedim>::get_location()
  {
    return property_pool->get_location(property_pool_handle);
  }
 
 
 
  template <int dim, int spacedim>
  inline void
  Particle<dim, spacedim>::set_reference_location(const Point<dim> &new_loc)
  {
    property_pool->set_reference_location(property_pool_handle, new_loc);
  }
 
 
 
  template <int dim, int spacedim>
  inline const Point<dim> &
  Particle<dim, spacedim>::get_reference_location() const
  {
    return property_pool->get_reference_location(property_pool_handle);
  }
 
 
 
  template <int dim, int spacedim>
  inline types::particle_index
  Particle<dim, spacedim>::get_id() const
  {
    return property_pool->get_id(property_pool_handle);
  }
 
 
 
  template <int dim, int spacedim>
  inline void
  Particle<dim, spacedim>::set_id(const types::particle_index &new_id)
  {
    property_pool->set_id(property_pool_handle, new_id);
  }
 
 
 
  template <int dim, int spacedim>
  inline void
  Particle<dim, spacedim>::set_property_pool(
    PropertyPool<dim, spacedim> &new_property_pool)
  {
    // First, we do want to save any properties that may
    // have previously been set, and copy them over to the memory allocated
    // on the new pool.
    //
    // It is possible that a particle currently has no properties -- for
    // example if it has been created without an associated property
    // pool (i.e., uses the default global pool which does not store any
    // properties) but that the new pool has properties. In that case,
    // there is simply nothing to transfer -- but the register_particle()
    // call here will make sure that the newly allocated properties are
    // zero-initialized.
    const typename PropertyPool<dim, spacedim>::Handle new_handle =
      new_property_pool.register_particle();
 
    const Point<spacedim>       location           = get_location();
    const Point<dim>            reference_location = get_reference_location();
    const types::particle_index id                 = get_id();
 
    if (/* old pool */ has_properties())
      {
        ArrayView<const double> old_properties = this->get_properties();
        ArrayView<double>       new_properties =
          new_property_pool.get_properties(new_handle);
        std::copy(old_properties.cbegin(),
                  old_properties.cend(),
                  new_properties.begin());
      }
 
    // Now release the old memory handle
    property_pool->deregister_particle(property_pool_handle);
 
 
    // Then set the pointer to the property pool we want to use. Also set the
    // handle to any properties.
    property_pool        = &new_property_pool;
    property_pool_handle = new_handle;
 
    // Now also store the saved locations
    set_location(location);
    set_reference_location(reference_location);
    set_id(id);
  }
 
 
 
  template <int dim, int spacedim>
  inline ArrayView<const double>
  Particle<dim, spacedim>::get_properties() const
  {
    if (has_properties() == false)
      return {};
    else
      return property_pool->get_properties(property_pool_handle);
  }
 
 
 
  template <int dim, int spacedim>
  inline bool
  Particle<dim, spacedim>::has_properties() const
  {
    // Particles always have a property pool associated with them,
    // but we can access properties only if there is a valid handle.
    // The only way a particle can have no valid handle if it has
    // been moved-from -- but that leaves an object in an invalid
    // state, and so we can just assert that that can't be the case.
    Assert((property_pool_handle !=
            PropertyPool<dim, spacedim>::invalid_handle),
           ExcInternalError());
    return (property_pool->n_properties_per_slot() > 0);
  }
 
} // namespace Particles
 
DEAL_II_NAMESPACE_CLOSE
 
 
namespace boost
{
  namespace geometry
  {
    namespace index
    {
      // Forward declaration of bgi::indexable
      template <class T>
      struct indexable;
 
      template <int dim, int spacedim>
      struct indexable<::Particles::Particle<dim, spacedim>>
      {
        using result_type = const ::Point<spacedim> &;
 
        result_type
        operator()(
          const ::Particles::Particle<dim, spacedim> &particle) const
        {
          return particle.get_location();
        }
      };
 
    } // namespace index
  }   // namespace geometry
} // namespace boost
 
#endif