corecel/data/AuxParams.hh

0001 //------------------------------- -*- C++ -*- -------------------------------//
0002 // Copyright Celeritas contributors: see top-level COPYRIGHT file for details
0003 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
0004 //---------------------------------------------------------------------------//
0005 //! \file corecel/data/AuxParams.hh
0006 //---------------------------------------------------------------------------//
0007 #pragma once
0008
0009 #include "AuxState.hh"
0010 #include "AuxStateVec.hh"
0011
0012 namespace celeritas
0013 {
0014 //---------------------------------------------------------------------------//
0015 /*!
0016  * Construct and manage portable dynamic data.
0017  * \tparam P Params collection group
0018  * \tparam S State collection group
0019  *
0020  * This generalization of \rstref{the Celeritas data model,api_data_model}
0021  * manages some of the boilerplate code for the common use case of having
0022  * portable "params" data (e.g., model data) and "state" data (e.g., temporary
0023  * values used across multiple kernels or processed into user space). Each
0024  * state/stream will have an instance of \c AuxState accessible by this
0025  * class. An instance of this class can be shared among multiple actions, or an
0026  * action could inherit from it.
0027  *
0028  * \par Example:
0029  * The \c StepParams inherits from this class to provide access to host and
0030  * state data. The execution inside \c StepGatherAction provides views to both
0031  * the params and state data classes:
0032  * \code
0033     // Extract the local step state data
0034     auto const& step_params = params_->ref<MemSpace::native>();
0035     auto& step_state = params_->ref<MemSpace::native>(state.aux());
0036
0037     // Run the action
0038     auto execute = TrackExecutor{
0039         params.ptr<MemSpace::native>(),
0040         state.ptr(),
0041         detail::StepGatherExecutor<P>{step_params, step_state}};
0042    \endcode
0043  *
0044  * \note For the case where the aux state data contains host-side classes and
0045  * data (e.g., an open file handle) you must manually set up the params/state
0046  * data using \c AuxStateInterface and \c AuxParamsInterface .
0047  */
0048 template<template<Ownership, MemSpace> class P,
0049          template<Ownership, MemSpace> class S>
0050 class AuxParams : public AuxParamsInterface, public ParamsDataInterface<P>
0051 {
0052   public:
0053     //!@{
0054     //! \name Type aliases
0055     template<MemSpace M>
0056     using StateRefT = S<Ownership::reference, M>;
0057     //!@}
0058
0059   public:
0060     // Factory function for building multithread state for a stream
0061     inline UPState create_state(MemSpace, StreamId, size_type size) const final;
0062
0063     // Access the *state* ref (const)
0064     template<MemSpace M>
0065     inline StateRefT<M> const& state_ref(AuxStateVec const& v) const;
0066
0067     // Access the *state* ref (mutable)
0068     template<MemSpace M>
0069     inline StateRefT<M>& state_ref(AuxStateVec& v) const;
0070
0071     //! Allow access host/device *params* ref
0072     using ParamsDataInterface<P>::ref;
0073
0074   private:
0075     template<MemSpace M>
0076     using StateT = AuxState<S, M>;
0077 };
0078
0079 //---------------------------------------------------------------------------//
0080 // INLINE DEFINITIONS
0081 //---------------------------------------------------------------------------//
0082 /*!
0083  * Build a multithread state for a stream.
0084  *
0085  * See \c AuxState .
0086  */
0087 template<template<Ownership, MemSpace> class P,
0088          template<Ownership, MemSpace> class S>
0089 auto AuxParams<P, S>::create_state(
0090     MemSpace m, StreamId sid, size_type size) const -> UPState
0091 {
0092     return ::celeritas::make_aux_state<S, P>(*this, m, sid, size);
0093 }
0094
0095 //---------------------------------------------------------------------------//
0096 /*!
0097  * Access the *state* ref (const).
0098  */
0099 template<template<Ownership, MemSpace> class P,
0100          template<Ownership, MemSpace> class S>
0101 template<MemSpace M>
0102 auto AuxParams<P, S>::state_ref(AuxStateVec const& v) const
0103     -> StateRefT<M> const&
0104 {
0105     return ::celeritas::get<StateT<M>>(v, this->aux_id()).ref();
0106 }
0107
0108 //---------------------------------------------------------------------------//
0109 /*!
0110  * Access the *state* ref (mutable).
0111  */
0112 template<template<Ownership, MemSpace> class P,
0113          template<Ownership, MemSpace> class S>
0114 template<MemSpace M>
0115 auto AuxParams<P, S>::state_ref(AuxStateVec& v) const -> StateRefT<M>&
0116 {
0117     return ::celeritas::get<StateT<M>>(v, this->aux_id()).ref();
0118 }
0119
0120 //---------------------------------------------------------------------------//
0121 }  // namespace celeritas