ParticleBase.h

Go to the documentation of this file.

//
// Class ParticleBase
//   Base class for all user-defined particle classes.
//
//   ParticleBase is a container and manager for a set of particles.
//   The user must define a class derived from ParticleBase which describes
//   what specific data attributes the particle has (e.g., mass or charge).
//   Each attribute is an instance of a ParticleAttribute<T> class; ParticleBase
//   keeps a list of pointers to these attributes, and performs particle creation
//   and destruction.
//
//   ParticleBase is templated on the ParticleLayout mechanism for the particles.
//   This template parameter should be a class derived from ParticleLayout.
//   ParticleLayout-derived classes maintain the info on which particles are
//   located on which processor, and performs the specific communication
//   required between processors for the particles.  The ParticleLayout is
//   templated on the type and dimension of the atom position attribute, and
//   ParticleBase uses the same types for these items as the given
//   ParticleLayout.
//
//   ParticleBase and all derived classes have the following common
//   characteristics:
//       - The spatial positions of the N particles are stored in the
//         particle_position_type variable R
//       - The global index of the N particles are stored in the
//         particle_index_type variable ID
//       - A pointer to an allocated layout class.  When you construct a
//         ParticleBase, you must provide a layout instance, and ParticleBase
//         will delete this instance when it (the ParticleBase) is deleted.
//
//   To use this class, the user defines a derived class with the same
//   structure as in this example:
//
//     class UserParticles :
//              public ParticleBase< ParticleSpatialLayout<double,3> > {
//     public:
//       // attributes for this class
//       ParticleAttribute<double> rad;  // radius
//       particle_position_type    vel;  // velocity, same storage type as R
//
//       // constructor: add attributes to base class
//       UserParticles(ParticleSpatialLayout<double,2>* L) : ParticleBase(L) {
//         addAttribute(rad);
//         addAttribute(vel);
//       }
//     };
//
//   This example defines a user class with 3D position and two extra
//   attributes: a radius rad (double), and a velocity vel (a 3D Vector).
//
#ifndef IPPL_PARTICLE_BASE_H
#define IPPL_PARTICLE_BASE_H
 
#include <tuple>
#include <type_traits>
#include <vector>
 
#include "Types/IpplTypes.h"
 
#include "Utility/TypeUtils.h"
 
#include "Particle/ParticleLayout.h"
 
namespace ippl {

    class ParticleBaseBase {
    public:
        virtual ~ParticleBaseBase() = default;
    };

    template <class PLayout, typename... IDProperties>
    class ParticleBase: public ParticleBaseBase {
        constexpr static bool EnableIDs = sizeof...(IDProperties) > 0;
 
    public:
        using vector_type            = typename PLayout::vector_type;
        using index_type             = typename PLayout::index_type;
        using particle_position_type = typename PLayout::particle_position_type;
        using particle_index_type    = ParticleAttrib<index_type, IDProperties...>;
 
        using Layout_t = PLayout;
 
        template <typename... Properties>
        using attribute_type = typename detail::ParticleAttribBase<Properties...>;
 
        template <typename MemorySpace>
        using container_type = std::vector<attribute_type<MemorySpace>*>;
 
        using attribute_container_type =
            typename detail::ContainerForAllSpaces<container_type>::type;
 
        using bc_container_type = typename PLayout::bc_container_type;
 
        using hash_container_type = typename detail::ContainerForAllSpaces<detail::hash_type>::type;
 
        using size_type = detail::size_type;
 
    public:
        particle_position_type R;

        particle_index_type ID;

        ParticleBase();

        ParticleBase(Layout_t& layout);
 
        /* cannot use '= default' since we get a
         * compiler warning otherwise:
         * warning: calling a __host__ function("std::vector< ::ippl::detail::ParticleAttribBase *,
         * ::std::allocator<
         * ::ippl::detail::ParticleAttribBase *> > ::~vector") from a __host__ __device__
         * function("ippl::ParticleBase<
         * ::ippl::ParticleLayout<double, (unsigned int)3u> > ::~ParticleBase") is not allowed
         */
        ~ParticleBase() {}  // = default; //{ }

        void initialize(Layout_t& layout);

        size_type getLocalNum() const { return localNum_m; }
 
        void setLocalNum(size_type size) { localNum_m = size; }

        size_type getTotalNum() const { return totalNum_m; }

        Layout_t& getLayout() { return *layout_m; }

        const Layout_t& getLayout() const { return *layout_m; }

        void setParticleBC(const bc_container_type& bcs) { layout_m->setParticleBC(bcs); }

        void setParticleBC(BC bc) { layout_m->setParticleBC(bc); }

        template <typename MemorySpace>
        void addAttribute(detail::ParticleAttribBase<MemorySpace>& pa);

        template <typename MemorySpace = Kokkos::DefaultExecutionSpace::memory_space>
        attribute_type<MemorySpace>* getAttribute(size_t i) {
            return attributes_m.template get<MemorySpace>()[i];
        }

        template <typename MemorySpace = void, typename Functor>
        void forAllAttributes(Functor&& f) const {
            if constexpr (std::is_void_v<MemorySpace>) {
                attributes_m.forAll(f);
            } else {
                for (auto& attribute : attributes_m.template get<MemorySpace>()) {
                    f(attribute);
                }
            }
        }
 
        // Non-const variant of same function
        template <typename MemorySpace = void, typename Functor>
        void forAllAttributes(Functor&& f) {
            if constexpr (std::is_void_v<MemorySpace>) {
                attributes_m.forAll([&]<typename Attributes>(Attributes& atts) {
                    for (auto& attribute : atts) {
                        f(attribute);
                    }
                });
            } else {
                for (auto& attribute : attributes_m.template get<MemorySpace>()) {
                    f(attribute);
                }
            }
        }

        unsigned getAttributeNum() const {
            unsigned total = 0;
            detail::runForAllSpaces([&]<typename MemorySpace>() {
                total += attributes_m.template get<MemorySpace>().size();
            });
            return total;
        }

        void create(size_type nLocal);

        void createWithID(index_type id);

        void globalCreate(size_type nTotal);

        template <typename... Properties>
        void destroy(const Kokkos::View<bool*, Properties...>& invalid, const size_type destroyNum);
 
        // This is a collective call.
        void update() { layout_m->update(*this); }
 
        /*
         * The following functions should not be called in an application.
         */
 
        /* This function does not alter the totalNum_m member function. It should only be called
         * during the update function where we know the number of particles remains the same.
         */
        template <typename... Properties>
        void internalDestroy(const Kokkos::View<bool*, Properties...>& invalid,
                             const size_type destroyNum);

        template <typename HashType>
        void sendToRank(int rank, int tag, std::vector<MPI_Request>& requests,
                        const HashType& hash);

        void recvFromRank(int rank, int tag, size_type nRecvs);

        template <typename Archive>
        void serialize(Archive& ar, size_type nsends);

        template <typename Archive>
        void deserialize(Archive& ar, size_type nrecvs);

        template <typename MemorySpace>
        size_type packedSize(const size_type count) const;
 
    protected:
        void pack(const hash_container_type& hash);

        void unpack(size_type nrecvs);
 
    private:
        // cannot use std::unique_ptr due to Kokkos
        Layout_t* layout_m;

        size_type localNum_m;

        size_type totalNum_m;

        attribute_container_type attributes_m;

        index_type nextID_m;

        index_type numNodes_m;

        hash_container_type deleteIndex_m;
        hash_container_type keepIndex_m;
    };
}  // namespace ippl
 
#include "Particle/ParticleBase.hpp"
 
#endif