summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorClaudius "keldu" Holeksa <mail@keldu.de>2026-11-09 14:17:11 +0100
committerClaudius "keldu" Holeksa <mail@keldu.de>2026-11-09 14:17:11 +0100
commitff88ea49eca3961e1aa4194944b93a3bfbf3d3d8 (patch)
tree0e5b061931c5e8526969e9661e3cc1fca53b995f
parentc59aeef2e0c86ec3f0f34ce77c205f3ef0b034cc (diff)
downloadlibs-lbm-ff88ea49eca3961e1aa4194944b93a3bfbf3d3d8.tar.gz
Work on masking
-rw-r--r--examples/moving_poiseulle_particles_2d_psm_gpu/sim.cpp18
-rw-r--r--examples/stokes_drag_particle_2d_hlbm_gpu/sim.cpp2
-rw-r--r--examples/stokes_drag_particle_2d_psm_gpu/sim.cpp2
-rw-r--r--modules/core/c++/abstract/data_ptr.hpp150
-rw-r--r--modules/core/c++/fplbm.hpp55
-rw-r--r--modules/core/c++/hlbm.hpp156
-rw-r--r--modules/core/c++/lbm.hpp5
-rw-r--r--modules/core/c++/particle/aabb.hpp17
-rw-r--r--modules/core/c++/particle/blur.hpp37
-rw-r--r--modules/core/c++/particle/cell_list.hpp210
-rw-r--r--modules/core/c++/particle/contact.hpp567
-rw-r--r--modules/core/c++/particle/couple.hpp108
-rw-r--r--modules/core/c++/particle/integrate.hpp175
-rw-r--r--modules/core/c++/particle/mask.hpp399
-rw-r--r--modules/core/c++/particle/particle.hpp161
-rw-r--r--modules/core/c++/particle/porosity.hpp46
-rw-r--r--modules/core/c++/particle/schema.hpp54
-rw-r--r--modules/core/c++/particle/voxel_narrow.hpp262
-rw-r--r--modules/core/c++/psm.hpp69
-rw-r--r--modules/core/tests/cell_list.cpp197
-rw-r--r--modules/core/tests/component_instantiation.cpp199
-rw-r--r--modules/core/tests/contact_dynamics.cpp272
-rw-r--r--modules/core/tests/mask.cpp238
-rw-r--r--modules/core/tests/particle_3d.cpp265
-rw-r--r--modules/core/tests/particle_consistency.cpp269
-rw-r--r--modules/core/tests/particle_edges.cpp224
-rw-r--r--modules/core/tests/particle_gaps.cpp297
-rw-r--r--modules/core/tests/particles.cpp414
-rw-r--r--modules/core/tests/rotation.cpp211
-rw-r--r--modules/core/tests/voxel_narrow.cpp191
30 files changed, 5052 insertions, 218 deletions
diff --git a/examples/moving_poiseulle_particles_2d_psm_gpu/sim.cpp b/examples/moving_poiseulle_particles_2d_psm_gpu/sim.cpp
index 947407e..a27c402 100644
--- a/examples/moving_poiseulle_particles_2d_psm_gpu/sim.cpp
+++ b/examples/moving_poiseulle_particles_2d_psm_gpu/sim.cpp
@@ -184,7 +184,18 @@ kel::lbm::error_or<void> step(
}).wait();
q.submit([&](acpp::sycl::handler& h){
- component<T,Desc,cmpt::PsmOneParticle,encode::Sycl<kel::lbm::enc::Native>> psm_one_part;
+ /**
+ * Split so contact sits between the fluid gather and the integration:
+ * reset -> fluid gather -> contact -> integrate.
+ */
+ component<T,Desc,cmpt::ParticleForceReset,encode::Sycl<kel::lbm::enc::Native>> p_reset;
+ component<T,Desc,cmpt::PsmOneParticleGather,encode::Sycl<kel::lbm::enc::Native>> p_gather;
+ component<T,Desc,cmpt::ParticleIntegrate,encode::Sycl<kel::lbm::enc::Native>> p_integrate;
+
+ // Soft shell against neighbours and against the domain walls.
+ dem_params<T> p_dem{1.0e-2, 0.3, 0.0, 0.0};
+ kel::lbm::data<sch::FixedArray<sch::UInt64,Desc::D>> p_extent{{dim_x,dim_y}};
+ component<T,Desc,cmpt::ParticleContact,encode::Sycl<kel::lbm::enc::Native>> p_contact{p_dem,p_extent};
h.parallel_for(acpp::sycl::range<1u>{particle_amount}, [=](acpp::sycl::id<1u> idx){
kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index;
@@ -192,7 +203,10 @@ kel::lbm::error_or<void> step(
index.at({{i}}).set(idx[i]);
}
- psm_one_part.apply(fields,macros,particles,index,t_i,{16u});
+ p_reset.apply(particles,index,t_i);
+ p_gather.apply(fields,macros,particles,index,t_i,{16u});
+ p_contact.apply(particles,index,t_i,{16u});
+ p_integrate.apply(particles,index,t_i,{16u});
});
}).wait();
diff --git a/examples/stokes_drag_particle_2d_hlbm_gpu/sim.cpp b/examples/stokes_drag_particle_2d_hlbm_gpu/sim.cpp
index 0fe76cb..8117b19 100644
--- a/examples/stokes_drag_particle_2d_hlbm_gpu/sim.cpp
+++ b/examples/stokes_drag_particle_2d_hlbm_gpu/sim.cpp
@@ -194,7 +194,6 @@ kel::lbm::error_or<void> step(
q.submit([&](acpp::sycl::handler& h){
component<T,Desc,cmpt::BGK, encode::Sycl<kel::lbm::enc::Native>> bgk{0.8};
component<T,Desc,cmpt::Hlbm,encode::Sycl<kel::lbm::enc::Native>> collision{0.8};
- component<T,Desc,cmpt::HlbmOneParticle,encode::Sycl<kel::lbm::enc::Native>> one_part_moment;
component<T,Desc,cmpt::BounceBack,encode::Sycl<kel::lbm::enc::Native>> bb;
component<T,Desc,cmpt::AntiBounceBack<0u>,encode::Sycl<kel::lbm::enc::Native>> abb;
@@ -241,7 +240,6 @@ kel::lbm::error_or<void> step(
break;
case 2u:
opa.apply(macros,index,t_i);
- one_part_moment.apply(fields,macros,index,t_i);
collision.apply(fields,macros,index,t_i);
fg.apply(fields,macros,index,t_i);
break;
diff --git a/examples/stokes_drag_particle_2d_psm_gpu/sim.cpp b/examples/stokes_drag_particle_2d_psm_gpu/sim.cpp
index 652309c..49a6128 100644
--- a/examples/stokes_drag_particle_2d_psm_gpu/sim.cpp
+++ b/examples/stokes_drag_particle_2d_psm_gpu/sim.cpp
@@ -174,7 +174,7 @@ kel::lbm::error_or<void> step(
q.submit([&](acpp::sycl::handler& h){
component<T,Desc,cmpt::BGK, encode::Sycl<kel::lbm::enc::Native>> bgk{0.8};
- component<T,Desc,cmpt::PSM,encode::Sycl<kel::lbm::enc::Native>> collision{0.8};
+ component<T,Desc,cmpt::Psm,encode::Sycl<kel::lbm::enc::Native>> collision{0.8};
component<T,Desc,cmpt::BounceBack,encode::Sycl<kel::lbm::enc::Native>> bb;
component<T,Desc,cmpt::AntiBounceBack<0u>,encode::Sycl<kel::lbm::enc::Native>> abb;
diff --git a/modules/core/c++/abstract/data_ptr.hpp b/modules/core/c++/abstract/data_ptr.hpp
new file mode 100644
index 0000000..183b653
--- /dev/null
+++ b/modules/core/c++/abstract/data_ptr.hpp
@@ -0,0 +1,150 @@
+#pragma once
+
+#include "data.hpp"
+#include "data_math.hpp"
+
+namespace kel {
+namespace lbm {
+
+/**
+ * Host-side borrowed views, mirroring the device Ptr encodings.
+ *
+ * On an accelerator a kernel captures its arguments by value into a const
+ * lambda, so a device view is always reached through a const object. The
+ * device types answer that by being a const POINTER to mutable data -- the
+ * same distinction as `T* const` against `const T*`. That is the correct model
+ * for a borrowed device handle, not a workaround.
+ *
+ * The consequence is that components, which take their group through such a
+ * view, cannot be instantiated against the plain host `data` types, because
+ * those are honestly const-correct. Templates are only checked when
+ * instantiated, so a component referencing a member that does not exist
+ * compiles fine until a real kernel is built -- which is how two such bugs got
+ * past the host tests here already.
+ *
+ * These views close that hole: same const semantics as the device, usable on
+ * the host, so a component can be instantiated and exercised in a plain test.
+ */
+
+template <typename Sch, uint64_t... Dims>
+class data<sch::Ptr<sch::FixedArray<Sch, Dims...>>, enc::Native> final {
+public:
+ using Schema = sch::Ptr<sch::FixedArray<Sch, Dims...>>;
+ using Inner = data<Sch, enc::Native>;
+
+ static constexpr uint64_t Rank = sizeof...(Dims);
+
+private:
+ Inner *values_;
+
+public:
+ KEL_DEFAULT_COPY(data);
+ KEL_DEFAULT_MOVE(data);
+
+ data() : values_{nullptr} {}
+
+ data(data<sch::FixedArray<Sch, Dims...>, enc::Native> &backing)
+ : values_{backing.flat_data()} {}
+
+ data(Inner *values__) : values_{values__} {}
+
+ static constexpr index_data<Rank> get_dims() { return {Dims...}; }
+
+ static constexpr index_data<Rank> meta() { return {Dims...}; }
+
+ /**
+ * Const on the view, mutable through it. Matches the device encoding.
+ */
+ Inner &at(const index_data<Rank> &index) const {
+ // Row major, same fold the owning FixedArray uses.
+ constexpr std::array<uint64_t, Rank> dims{Dims...};
+ uint64_t flat = 0u;
+ uint64_t stride = 1u;
+ for(uint64_t i{0u}; i < Rank; ++i){
+ flat += index.flat_at(i).get() * stride;
+ stride *= dims.at(i);
+ }
+ return values_[flat];
+ }
+
+ Inner &flat_at(uint64_t i) const { return values_[i]; }
+
+ Inner *flat_data() const { return values_; }
+};
+
+template <typename... Sch, string_literal... Keys>
+class data<sch::Ptr<sch::Struct<sch::Member<Sch, Keys>...>>, enc::Native> final {
+public:
+ using Schema = sch::Ptr<sch::Struct<sch::Member<Sch, Keys>...>>;
+
+private:
+ using StorageT = std::tuple<data<sch::Ptr<Sch>, enc::Native>...>;
+ StorageT members_;
+
+ template <string_literal K>
+ static constexpr size_t index_of = parameter_key_pack_index<K, Keys...>::value;
+
+public:
+ data() = default;
+
+ KEL_DEFAULT_COPY(data);
+ KEL_DEFAULT_MOVE(data);
+
+ /**
+ * Builds a view over an owning struct, member by member.
+ */
+ data(data<sch::Struct<sch::Member<Sch, Keys>...>, enc::Native> &backing) {
+ bind<0u>(backing);
+ }
+
+ template <size_t i> auto &get() const {
+ return std::get<i>(const_cast<StorageT &>(members_));
+ }
+
+ template <string_literal K> auto &get() const {
+ return std::get<index_of<K>>(const_cast<StorageT &>(members_));
+ }
+
+private:
+ template <uint64_t i, typename Backing> void bind(Backing &backing) {
+ if constexpr (i < sizeof...(Sch)) {
+ std::get<i>(members_) = {backing.template get_at_index<i>()};
+ bind<i + 1u>(backing);
+ }
+ }
+};
+
+/**
+ * Non-structural leaves are borrowed as a plain pointer to the value.
+ */
+template <typename Sch>
+class data<sch::Ptr<Sch>, enc::Native> final {
+public:
+ using Schema = sch::Ptr<Sch>;
+ using Inner = data<Sch, enc::Native>;
+
+private:
+ Inner *value_;
+
+public:
+ KEL_DEFAULT_COPY(data);
+ KEL_DEFAULT_MOVE(data);
+
+ data() : value_{nullptr} {}
+ data(Inner &value__) : value_{&value__} {}
+
+ Inner &operator()() const { return *value_; }
+
+ Inner *handle() const { return value_; }
+};
+
+/**
+ * Convenience: build a host view over an owning value, mirroring make_view.
+ */
+template <typename Sch>
+data<sch::Ptr<Sch>, enc::Native> make_host_view(data<Sch, enc::Native> &backing) {
+ return data<sch::Ptr<Sch>, enc::Native>{backing};
+}
+
+} // namespace lbm
+} // namespace kel
diff --git a/modules/core/c++/fplbm.hpp b/modules/core/c++/fplbm.hpp
index 6783f12..4f9c81d 100644
--- a/modules/core/c++/fplbm.hpp
+++ b/modules/core/c++/fplbm.hpp
@@ -2,6 +2,7 @@
#include "common.hpp"
#include "particle/particle.hpp"
+#include "particle/integrate.hpp"
#include "iterator.hpp"
namespace kel {
@@ -12,6 +13,7 @@ struct FpLbm {};
struct FpLbmOneParticle {};
struct FpLbmMomentumOneParticle {};
struct FpLbmOneParticleNoVelocity{};
+struct FpLbmOneParticleGather {};
}
namespace method {
struct FpLbm {};
@@ -138,9 +140,9 @@ public:
};
template<typename T, typename Descriptor, typename Encode>
-class component<T, Descriptor, cmpt::FpLbmOneParticle, Encode> final {
+class component<T, Descriptor, cmpt::FpLbmOneParticleGather, Encode> final {
public:
- using Component = cmpt::FpLbmOneParticle;
+ using Component = cmpt::FpLbmOneParticleGather;
private:
kel::lbm::data<sch::Vector<T,Descriptor::D>> global_force_;
public:
@@ -177,12 +179,11 @@ public:
auto& pirb = pi.template get<"rigid_body">();
auto& pirb_pos = pirb.template get<"position">();
auto& pirb_pos_old = pirb.template get<"position_old">();
+ auto& p_rad = pi.template get<"collision">().template get<"radius">();
- auto& p_coll = pg.template get<"collision">().at({});
- auto& p_rad = p_coll.template get<"radius">();
- auto eo_aabb = particle_aabb<typename ParticleSchema::ValueType>::calculate(pg,{{0u}},mom_f.meta());
+ auto eo_aabb = particle_aabb<typename ParticleSchema::ValueType>::calculate(pg,index,mom_f.meta());
if(eo_aabb.is_error()){
return;
}
@@ -227,15 +228,43 @@ public:
force_p = force_p - force;
}, aabb.template get<"a">(), aabb.template get<"b">());
- auto& pirb_acc = pirb.template get<"acceleration">();
- pirb_acc = global_force_ + force_p / (pg.template get<"total_mass">().at({}));
+ /**
+ * Accumulate rather than assign, so a contact pass can add to this
+ * before cmpt::ParticleIntegrate turns the total into motion.
+ */
+ auto& pirb_force = pirb.template get<"force">();
+ pirb_force = pirb_force + force_p;
+ }
+};
- if(sub_steps.get() > 0u){
- auto sss_inv = one / sss;
- for(kel::lbm::data<sch::UInt64> i{0u}; i < sub_steps; ++i){
- verlet_step_lambda<T,Descriptor::D>(pi,sss_inv);
- }
- }
+/**
+ * The original fused one-particle step, kept so existing call sites keep
+ * working. global_force_ is an acceleration, so it rides along as the
+ * integrator's body acceleration.
+ */
+template<typename T, typename Descriptor, typename Encode>
+class component<T, Descriptor, cmpt::FpLbmOneParticle, Encode> final {
+public:
+ using Component = cmpt::FpLbmOneParticle;
+private:
+ kel::lbm::data<sch::Vector<T,Descriptor::D>> global_force_;
+public:
+ component():
+ global_force_{}
+ {}
+ component(kel::lbm::data<sch::Vector<T,Descriptor::D>> global_force__):
+ global_force_{global_force__}
+ {}
+
+ template<typename CellFieldSchema, typename MacroFieldSchema, typename ParticleSchema>
+ void apply(const kel::lbm::data<CellFieldSchema, Encode>& field, const kel::lbm::data<MacroFieldSchema,Encode>& macros, const kel::lbm::data<ParticleSchema,Encode>& pg, kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index, kel::lbm::data<sch::UInt64> time_step, kel::lbm::data<sch::UInt64> sub_steps) const {
+ component<T,Descriptor,cmpt::ParticleForceReset,Encode> reset;
+ component<T,Descriptor,cmpt::FpLbmOneParticleGather,Encode> gather;
+ component<T,Descriptor,cmpt::ParticleIntegrate,Encode> integrate{global_force_};
+
+ reset.apply(pg,index,time_step);
+ gather.apply(field,macros,pg,index,time_step,sub_steps);
+ integrate.apply(pg,index,time_step,sub_steps);
}
};
}
diff --git a/modules/core/c++/hlbm.hpp b/modules/core/c++/hlbm.hpp
index 4f22cbc..b7bf003 100644
--- a/modules/core/c++/hlbm.hpp
+++ b/modules/core/c++/hlbm.hpp
@@ -5,6 +5,7 @@
#include "equilibrium.hpp"
#include "particle/particle.hpp"
+#include "particle/integrate.hpp"
#include <iostream>
@@ -16,6 +17,8 @@ struct Hlbm {};
struct HlbmOneParticle {};
struct HlbmParticle {};
struct HlbmOneParticleMomentumExchange {};
+struct HlbmOneParticleGather {};
+struct HlbmOneParticleStamp {};
}
namespace method {
struct Hlbm {};
@@ -103,61 +106,59 @@ public:
}
};
-
+/**
+ * Gathers the hydrodynamic force on one particle and stamps its porosity.
+ *
+ * Accumulates into the particle's force member rather than writing
+ * acceleration, so contact forces can be added before cmpt::ParticleIntegrate
+ * turns the total into motion.
+ */
template<typename T, typename Desc, typename Encode>
-class component<T, Desc, cmpt::HlbmOneParticle, Encode> final {
+class component<T, Desc, cmpt::HlbmOneParticleGather, Encode> final {
private:
public:
template<typename CellFieldSchema, typename MacroFieldSchema, typename ParticleSchema>
void apply(const kel::lbm::data<CellFieldSchema, Encode>& field, const kel::lbm::data<MacroFieldSchema,Encode>& macros, const kel::lbm::data<ParticleSchema,Encode>& part_group, kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index, kel::lbm::data<sch::UInt64> time_step, kel::lbm::data<sch::UInt64> sub_steps) const {
- /// Figure out how to access the particle list
- // auto& p = particles.at(i);
-
- /// Iterate over the grid bounds
- // auto& grid = p.template get<"grid">();
using dfi = df_info<T,Desc>;
bool is_even = ((time_step.get() % 2) == 0);
-
+
kel::lbm::data<sch::Scalar<T>> one;
one.at({}) = 1.0;
-
+
auto& dfs_old_f = (is_even) ? field.template get<"dfs_old">() : field.template get<"dfs">();
auto& part_spheroid_group = part_group;
auto& mvel_f = macros.template get<"momentum">();
auto& mrho_f = macros.template get<"density">();
auto& mpor_f = macros.template get<"porosity">();
-
- auto& particle_N_f = field.template get<"particle_N">();
- auto& particle_D_f = field.template get<"particle_D">();
{
auto parts = part_spheroid_group.template get<"particles">();
- auto parts_size = parts.meta().at({0u});
-
- auto& p_coll = part_spheroid_group.template get<"collision">().at({});
- auto& p_rad = p_coll.template get<"radius">();
auto& pi = parts.at(index);
auto& pirb = pi.template get<"rigid_body">();
+ auto& p_rad = pi.template get<"collision">().template get<"radius">();
kel::lbm::data<sch::Vector<T,Desc::D>>& pirb_pos = pirb.template get<"position">();
auto& pirb_pos_old = pirb.template get<"position_old">();
-
- // TODO !!!! Divide by actual time step - for now it's ok
- kel::lbm::data<sch::Scalar<T>> ts;
- ts.at({}) = one.at({}) / sub_steps.template cast_to<T>();
- kel::lbm::data<sch::FixedArray<sch::UInt64,Desc::D>> start;
- kel::lbm::data<sch::FixedArray<sch::UInt64,Desc::D>> stop;
+ // Matches cmpt::ParticleIntegrate: zero sub steps means one step.
+ uint64_t steps = sub_steps.get();
+ if(steps == 0u){
+ steps = 1u;
+ }
+ kel::lbm::data<sch::Scalar<T>> ts;
+ ts.at({}).set(
+ typename kel::lbm::native_data_type<T>::type(1)
+ / static_cast<typename kel::lbm::native_data_type<T>::type>(steps)
+ );
- auto eo_aabb = particle_aabb<typename ParticleSchema::ValueType>::calculate(part_spheroid_group,{{0u}},mvel_f.meta());
+ auto eo_aabb = particle_aabb<typename ParticleSchema::ValueType>::calculate(part_spheroid_group,index,mvel_f.meta());
if(eo_aabb.is_error()){
return;
}
auto& aabb = eo_aabb.get_value();
- /// Ok, I iterate over the space which covers our particle? So lower bounds to upper bounds
- start = aabb.template get<"a">();
- stop = aabb.template get<"b">();
+ auto start = aabb.template get<"a">();
+ auto stop = aabb.template get<"b">();
kel::lbm::data<sch::Vector<T,Desc::D>> force_p;
for(uint64_t i{0u}; i < Desc::D; ++i){
@@ -170,7 +171,7 @@ public:
kel::lbm::data<sch::Vector<T,Desc::D>> rel_dist = kel::lbm::math::vectorize_data(index_f).template cast_to<T>() - pirb_pos;
kel::lbm::data<sch::Scalar<T>> eps;
eps.at({}) = 1.5f;
-
+
auto& mpor = mpor_f.at(index_f);
mpor = particle_porosity<T,Desc::D,1u,por::ParticleSpheroid<T>>::calculate(rel_dist,p_rad,eps);
@@ -206,30 +207,99 @@ public:
// TODO technically needs to adjust for rotation as well
auto& rho = mrho_f.at(index_f);
+ (void) rho;
macros.template get<"force">().at(index_f) = momentum;
force_p = force_p + momentum;
},start,stop);
-
- auto& pirb_acc = pirb.template get<"acceleration">();
- pirb_acc = - force_p / part_spheroid_group.template get<"total_mass">().at({});
- for(kel::lbm::data<sch::UInt64> i{0u}; i < sub_steps; ++i){
- verlet_step_lambda<T,Desc::D>(pi,ts);
- }
- auto vel_p = (pirb_pos-pirb_pos_old) / ts;
+ // Accumulate, do not assign: contact adds to this before integration.
+ auto& pirb_force = pirb.template get<"force">();
+ pirb_force = pirb_force - force_p;
+ }
+ }
+};
- iterator<Desc::D>::apply([&](const auto& index_f){
- auto& N = particle_N_f.at(index_f);
- auto& D = particle_D_f.at(index_f);
- auto& mpor = mpor_f.at(index_f);
- auto flip_porosity = one - mpor;
+/**
+ * Writes the HLBM solid-fraction coupling terms.
+ *
+ * Must run AFTER cmpt::ParticleIntegrate, because it uses the post-move
+ * particle velocity.
+ */
+template<typename T, typename Desc, typename Encode>
+class component<T, Desc, cmpt::HlbmOneParticleStamp, Encode> final {
+private:
+public:
+ template<typename CellFieldSchema, typename MacroFieldSchema, typename ParticleSchema>
+ void apply(const kel::lbm::data<CellFieldSchema, Encode>& field, const kel::lbm::data<MacroFieldSchema,Encode>& macros, const kel::lbm::data<ParticleSchema,Encode>& part_group, kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index, kel::lbm::data<sch::UInt64> time_step, kel::lbm::data<sch::UInt64> sub_steps) const {
+ (void) time_step;
- D = D + flip_porosity;
- N = N + vel_p * flip_porosity;
- },start,stop);
- // Check
+ kel::lbm::data<sch::Scalar<T>> one;
+ one.at({}) = 1.0;
+
+ auto& mvel_f = macros.template get<"momentum">();
+ auto& mpor_f = macros.template get<"porosity">();
+ auto& particle_N_f = field.template get<"particle_N">();
+ auto& particle_D_f = field.template get<"particle_D">();
+
+ auto parts = part_group.template get<"particles">();
+ auto& pi = parts.at(index);
+ auto& pirb = pi.template get<"rigid_body">();
+ auto& pirb_pos = pirb.template get<"position">();
+ auto& pirb_pos_old = pirb.template get<"position_old">();
+
+ uint64_t steps = sub_steps.get();
+ if(steps == 0u){
+ steps = 1u;
}
+ kel::lbm::data<sch::Scalar<T>> ts;
+ ts.at({}).set(
+ typename kel::lbm::native_data_type<T>::type(1)
+ / static_cast<typename kel::lbm::native_data_type<T>::type>(steps)
+ );
+
+ auto eo_aabb = particle_aabb<typename ParticleSchema::ValueType>::calculate(part_group,index,mvel_f.meta());
+ if(eo_aabb.is_error()){
+ return;
+ }
+ auto& aabb = eo_aabb.get_value();
+
+ auto vel_p = (pirb_pos-pirb_pos_old) / ts;
+
+ iterator<Desc::D>::apply([&](const auto& index_f){
+ auto& N = particle_N_f.at(index_f);
+ auto& D = particle_D_f.at(index_f);
+ auto& mpor = mpor_f.at(index_f);
+ auto flip_porosity = one - mpor;
+
+ D = D + flip_porosity;
+ N = N + vel_p * flip_porosity;
+ },aabb.template get<"a">(),aabb.template get<"b">());
+ }
+};
+
+/**
+ * The original fused one-particle step, kept so existing call sites keep
+ * working: gather, integrate, then stamp, in that order.
+ *
+ * New code should launch the three components separately, which is what makes
+ * room for a contact pass between the gather and the integrate.
+ */
+template<typename T, typename Desc, typename Encode>
+class component<T, Desc, cmpt::HlbmOneParticle, Encode> final {
+private:
+public:
+ template<typename CellFieldSchema, typename MacroFieldSchema, typename ParticleSchema>
+ void apply(const kel::lbm::data<CellFieldSchema, Encode>& field, const kel::lbm::data<MacroFieldSchema,Encode>& macros, const kel::lbm::data<ParticleSchema,Encode>& part_group, kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index, kel::lbm::data<sch::UInt64> time_step, kel::lbm::data<sch::UInt64> sub_steps) const {
+ component<T,Desc,cmpt::ParticleForceReset,Encode> reset;
+ component<T,Desc,cmpt::HlbmOneParticleGather,Encode> gather;
+ component<T,Desc,cmpt::ParticleIntegrate,Encode> integrate;
+ component<T,Desc,cmpt::HlbmOneParticleStamp,Encode> stamp;
+
+ reset.apply(part_group,index,time_step);
+ gather.apply(field,macros,part_group,index,time_step,sub_steps);
+ integrate.apply(part_group,index,time_step,sub_steps);
+ stamp.apply(field,macros,part_group,index,time_step,sub_steps);
}
};
}
diff --git a/modules/core/c++/lbm.hpp b/modules/core/c++/lbm.hpp
index 8c48e54..eefb556 100644
--- a/modules/core/c++/lbm.hpp
+++ b/modules/core/c++/lbm.hpp
@@ -17,6 +17,11 @@
#include "macroscopic.hpp"
#include "momentum_gather.hpp"
#include "memory.hpp"
+#include "particle/voxel_narrow.hpp"
+#include "particle/cell_list.hpp"
+#include "particle/couple.hpp"
+#include "particle/contact.hpp"
+#include "particle/integrate.hpp"
#include "psm.hpp"
#include "component/psm.hpp"
#include "stream.hpp"
diff --git a/modules/core/c++/particle/aabb.hpp b/modules/core/c++/particle/aabb.hpp
index e986272..caf3210 100644
--- a/modules/core/c++/particle/aabb.hpp
+++ b/modules/core/c++/particle/aabb.hpp
@@ -39,7 +39,8 @@ public:
auto& a = aabb.template get<"a">();
auto& b = aabb.template get<"b">();
- const kel::lbm::data<sch::Scalar<T>>& rad_d = p_grp.template get<"collision">().at({{0u}}).template get<"radius">();
+ // Radius is per particle now, so a group can hold mixed sizes.
+ const kel::lbm::data<sch::Scalar<T>>& rad_d = pi.template get<"collision">().template get<"radius">();
kel::lbm::data<sch::Vector<T,D>> lower;
kel::lbm::data<sch::Vector<T,D>> upper;
@@ -47,8 +48,20 @@ public:
for(uint64_t i{0u}; i < D; ++i){
lower.at({{i}}) = ((pirb_pos.at({{i}}) >= rad_d.at({})) ? (pirb_pos.at({{i}}) - rad_d.at({})) : kel::lbm::data<T>{0});
a.at({i}) = lower.at({{i}}).template cast_to<sch::UInt64>();
+
upper.at({{i}}) = pirb_pos.at({{i}}) + rad_d.at({});
- b.at({i}) = (upper.at({{i}})+kel::lbm::data<T>{1}).template cast_to<sch::UInt64>();
+ /**
+ * Clamp against the field extent. Callers hand the result straight
+ * to iterator<D>::apply as [a,b), so an unclamped b reads past the
+ * end for any particle within a radius of the far wall.
+ *
+ * Note this bounds the cell itself, not its neighbours: HLBM also
+ * reads neighbour_at on dfs, which is safe because DfChunk carries
+ * Ghost = 1. The macro chunks have Ghost = 0 and are only ever
+ * read at the cell itself.
+ */
+ auto b_i = (upper.at({{i}})+kel::lbm::data<T>{1}).template cast_to<sch::UInt64>();
+ b.at({i}) = (b_i < meta.at({i})) ? b_i : meta.at({i});
}
return aabb;
diff --git a/modules/core/c++/particle/blur.hpp b/modules/core/c++/particle/blur.hpp
deleted file mode 100644
index 972a309..0000000
--- a/modules/core/c++/particle/blur.hpp
+++ /dev/null
@@ -1,37 +0,0 @@
-#pragma once
-
-namespace kel {
-namespace lbm {
-template<typename T, uint64_t D>
-void blur_mask(kel::lbm::data<sch::Array<T,D>>& p_mask){
-
- kel::lbm::data<T> mid{2.0/3.0};
- kel::lbm::data<T> edge{1.0/6.0};
-
- // kel::lbm::data<sch::FixedArray<sch::UInt64>,2u> blur_weights{{2.0/3.0},{1.0/6.0}};
-
- auto meta = p_mask.dims();
- kel::lbm::data<sch::Array<T,D>> blurred_mask{meta};
-
- /* 1D blur into N-D Blur*/
- for(kel::lbm::data<sch::UInt64> i{0u}; i < kel::lbm::data<sch::UInt64>{D}; ++i){
- iterator<D>::apply([&](const auto& index){
- blurred_mask.at(index) = p_mask.at(index) * mid;
-
- if(index.at({i}).get() > 0u){
- auto l_ind = index;
- l_ind.at({i}) = ind.at({i}) - 1u;
- blurred_mask.at(index) = blurred_mask.at(index) + p_mask.at(l_ind) * edge;
- }
- if((index.at({i}).get() + 1u) < meta.at({i})){
- auto r_ind = index;
- r_ind.at({i}) = ind.at({i}) + 1u;
- blurred_mask.at(index) = blurred_mask.at(index) + p_mask.at(r_ind) * edge;
- }
- },{},meta);
-
- p_mask = blurred_mask;
- }
-}
-}
-}
diff --git a/modules/core/c++/particle/cell_list.hpp b/modules/core/c++/particle/cell_list.hpp
new file mode 100644
index 0000000..d1d1537
--- /dev/null
+++ b/modules/core/c++/particle/cell_list.hpp
@@ -0,0 +1,210 @@
+#pragma once
+
+#include "../component.hpp"
+#include "../iterator.hpp"
+#include "common.hpp"
+#include "schema.hpp"
+#include "particle.hpp"
+
+namespace kel {
+namespace lbm {
+
+namespace sch {
+/**
+ * Uniform bin grid over the lattice, used to answer "which particles can
+ * cover this cell" without scanning every particle.
+ *
+ * Bin size must be at least the largest particle diameter. Then a particle
+ * covering a lattice cell is always registered in that cell's own bin or one
+ * of its immediate neighbours, so a query only ever touches 3^D bins.
+ *
+ * `count` and `slot` are flat because that is the layout the SYCL copy helper
+ * handles as a single memcpy; `slot` holds CellCapacity ids per bin.
+ */
+template<typename T, uint64_t D, uint64_t CellCapacity>
+using ParticleCellList = Struct<
+ Member<FixedArray<Scalar<T>,1u>, "bin_size">,
+ Member<FixedArray<UInt64,D>, "grid">,
+ Member<Array<UInt64,1u>, "count">,
+ Member<Array<UInt64,1u>, "slot">,
+ Member<FixedArray<UInt64,1u>, "overflow">
+>;
+}
+
+/**
+ * Bin a position. Clamped, so a particle that has drifted outside the domain
+ * still lands in a real bin rather than indexing out of bounds.
+ */
+template<typename T, uint64_t D, typename PosRef, typename GridRef>
+uint64_t particle_bin_of(
+ const PosRef& pos,
+ typename kel::lbm::native_data_type<T>::type bin_size,
+ const GridRef& grid
+){
+ uint64_t flat = 0u;
+ uint64_t stride = 1u;
+
+ for(uint64_t i{0u}; i < D; ++i){
+ auto g = grid.at({i}).get();
+ auto x = pos.at({{i}}).get() / bin_size;
+
+ int64_t b = static_cast<int64_t>(x);
+ if(b < 0){
+ b = 0;
+ }
+ if(static_cast<uint64_t>(b) >= g){
+ b = static_cast<int64_t>(g) - 1;
+ }
+
+ flat += static_cast<uint64_t>(b) * stride;
+ stride *= g;
+ }
+
+ return flat;
+}
+
+/**
+ * Clears every bin. Must precede a rebuild; bins are not self-clearing.
+ */
+template<typename ClRef>
+void clear_cell_list(ClRef&& cl){
+ auto& count = cl.template get<"count">();
+ const uint64_t cells = count.size().get();
+ for(uint64_t i{0u}; i < cells; ++i){
+ count.at({i}).set(0);
+ }
+ cl.template get<"overflow">().at({0u}).set(0);
+}
+
+/**
+ * Registers every particle in its bin.
+ *
+ * Insertion runs in particle-index order, so the contents of each bin are
+ * reproducible run to run -- which is what keeps the downstream per-cell sums
+ * deterministic.
+ *
+ * Overflow is recorded rather than silently dropped: a lost particle would
+ * show up as a quietly missing body in the fluid, which is close to
+ * impossible to spot in a result.
+ */
+template<typename T, uint64_t D, uint64_t CellCapacity, typename PartsRef, typename ClRef>
+void build_cell_list(const PartsRef& parts, ClRef&& cl){
+ clear_cell_list(cl);
+
+ auto bin_size = cl.template get<"bin_size">().at({0u}).at({}).get();
+ auto& grid = cl.template get<"grid">();
+ auto& count = cl.template get<"count">();
+ auto& slot = cl.template get<"slot">();
+
+ const uint64_t n = parts.get_dims().at({0u}).get();
+
+ for(uint64_t p{0u}; p < n; ++p){
+ auto& pos = parts.at({p}).template get<"rigid_body">().template get<"position">();
+ auto bin = particle_bin_of<T,D>(pos,bin_size,grid);
+
+ auto c = count.at({bin}).get();
+ if(c >= CellCapacity){
+ auto& of = cl.template get<"overflow">().at({0u});
+ of.set(of.get() + 1u);
+ continue;
+ }
+
+ slot.at({bin * CellCapacity + c}).set(p);
+ count.at({bin}).set(c + 1u);
+ }
+}
+
+/**
+ * Calls func(particle_index) for every particle registered in the bin holding
+ * `cell` or in any bin adjacent to it.
+ *
+ * The 3^D neighbourhood is what makes the bin-size rule above load bearing: a
+ * smaller bin would let a particle reach past the neighbours it is searched in.
+ */
+template<typename T, uint64_t D, uint64_t CellCapacity, typename ClRef, typename CellRef, typename Func>
+void for_each_bin_candidate(const ClRef& cl, const CellRef& cell, Func&& func){
+ auto bin_size = cl.template get<"bin_size">().at({0u}).at({}).get();
+ auto& grid = cl.template get<"grid">();
+ auto& count = cl.template get<"count">();
+ auto& slot = cl.template get<"slot">();
+
+ int64_t base[D];
+ for(uint64_t i{0u}; i < D; ++i){
+ auto x = static_cast<typename kel::lbm::native_data_type<T>::type>(cell.at({i}).get());
+ base[i] = static_cast<int64_t>(x / bin_size);
+ }
+
+ // 3^D neighbourhood, unrolled as a mixed-radix counter.
+ uint64_t total = 1u;
+ for(uint64_t i{0u}; i < D; ++i){
+ total *= 3u;
+ }
+
+ for(uint64_t off{0u}; off < total; ++off){
+ uint64_t rem = off;
+ uint64_t flat = 0u;
+ uint64_t stride = 1u;
+ bool inside = true;
+
+ for(uint64_t i{0u}; i < D; ++i){
+ int64_t delta = static_cast<int64_t>(rem % 3u) - 1;
+ rem /= 3u;
+
+ int64_t b = base[i] + delta;
+ auto g = static_cast<int64_t>(grid.at({i}).get());
+ if(b < 0 || b >= g){
+ inside = false;
+ break;
+ }
+
+ flat += static_cast<uint64_t>(b) * stride;
+ stride *= static_cast<uint64_t>(g);
+ }
+
+ if(!inside){
+ continue;
+ }
+
+ auto c = count.at({flat}).get();
+ for(uint64_t s{0u}; s < c; ++s){
+ func(slot.at({flat * CellCapacity + s}).get());
+ }
+ }
+}
+
+/**
+ * Sizes a cell list for a domain and a largest particle radius.
+ */
+template<typename T, uint64_t D, uint64_t CellCapacity, typename ExtentRef>
+kel::lbm::data<sch::ParticleCellList<T,D,CellCapacity>> make_cell_list(
+ const ExtentRef& extent,
+ typename kel::lbm::native_data_type<T>::type max_radius
+){
+ kel::lbm::data<sch::ParticleCellList<T,D,CellCapacity>> cl;
+
+ // At least one lattice unit, and at least the largest diameter.
+ auto bin_size = max_radius * 2;
+ if(!(bin_size > 1)){
+ bin_size = 1;
+ }
+ cl.template get<"bin_size">().at({0u}).at({}).set(bin_size);
+
+ auto& grid = cl.template get<"grid">();
+ uint64_t cells = 1u;
+ for(uint64_t i{0u}; i < D; ++i){
+ auto e = static_cast<typename kel::lbm::native_data_type<T>::type>(extent.at({i}).get());
+ uint64_t g = static_cast<uint64_t>(e / bin_size) + 1u;
+ grid.at({i}).set(g);
+ cells *= g;
+ }
+
+ cl.template get<"count">() = {kel::lbm::data<sch::FixedArray<sch::UInt64,1u>>{{cells}}};
+ cl.template get<"slot">() = {kel::lbm::data<sch::FixedArray<sch::UInt64,1u>>{{cells * CellCapacity}}};
+
+ clear_cell_list(cl);
+
+ return cl;
+}
+
+}
+}
diff --git a/modules/core/c++/particle/contact.hpp b/modules/core/c++/particle/contact.hpp
new file mode 100644
index 0000000..2e7973a
--- /dev/null
+++ b/modules/core/c++/particle/contact.hpp
@@ -0,0 +1,567 @@
+#pragma once
+
+#include "../component.hpp"
+#include "../abstract/math.hpp"
+#include "common.hpp"
+#include "schema.hpp"
+#include "particle.hpp"
+#include "integrate.hpp"
+
+namespace kel {
+namespace lbm {
+
+namespace sch {
+/**
+ * One resolved contact.
+ *
+ * `normal` is a unit vector pointing from the partner into the body the force
+ * is being computed for, so the contact force on that body is along +normal.
+ * `depth` is the penetration along that normal; positive means in contact.
+ */
+template<typename T, uint64_t D>
+using ContactManifold = Struct<
+ Member<Scalar<T>, "depth">,
+ Member<Vector<T,D>, "normal">,
+ Member<Vector<T,D>, "point">
+>;
+}
+
+/**
+ * Soft-shell contact parameters.
+ *
+ * k_n normal stiffness
+ * zeta_n normal damping ratio, ~0.2..0.9; critical damping is 1
+ * gamma_t tangential viscous coefficient
+ * mu Coulomb friction cap
+ */
+template<typename T>
+struct dem_params {
+ kel::lbm::data<sch::Scalar<T>> k_n;
+ kel::lbm::data<sch::Scalar<T>> zeta_n;
+ kel::lbm::data<sch::Scalar<T>> gamma_t;
+ kel::lbm::data<sch::Scalar<T>> mu;
+
+ dem_params(){
+ k_n.at({}).set(1.0);
+ zeta_n.at({}).set(0.3);
+ gamma_t.at({}).set(0.0);
+ mu.at({}).set(0.0);
+ }
+
+ dem_params(
+ typename kel::lbm::native_data_type<T>::type k_n__,
+ typename kel::lbm::native_data_type<T>::type zeta_n__,
+ typename kel::lbm::native_data_type<T>::type gamma_t__ = 0.0,
+ typename kel::lbm::native_data_type<T>::type mu__ = 0.0
+ ){
+ k_n.at({}).set(k_n__);
+ zeta_n.at({}).set(zeta_n__);
+ gamma_t.at({}).set(gamma_t__);
+ mu.at({}).set(mu__);
+ }
+};
+
+/**
+ * Suggests a stiffness that keeps the worst-case overlap under delta_max for
+ * an impact at v_0. Energy argument: k delta^2 / 2 = m v^2 / 2.
+ */
+template<typename T>
+constexpr typename kel::lbm::native_data_type<T>::type dem_stiffness_for(
+ typename kel::lbm::native_data_type<T>::type m_eff,
+ typename kel::lbm::native_data_type<T>::type v_0,
+ typename kel::lbm::native_data_type<T>::type delta_max
+){
+ return m_eff * v_0 * v_0 / (delta_max * delta_max);
+}
+
+namespace impl {
+/**
+ * math::normalize divides by sqrt(dot) with no guard, so a zero vector yields
+ * NaN and poisons everything downstream. Contact routinely produces
+ * near-degenerate vectors, so every normalization here goes through this.
+ */
+template<typename T, uint64_t D>
+bool safe_normalize(
+ const kel::lbm::data<sch::Vector<T,D>>& in,
+ kel::lbm::data<sch::Vector<T,D>>& out
+){
+ auto len_2 = kel::lbm::math::dot(in,in);
+ auto l2 = len_2.at({}).get();
+ if(!(l2 > 0)){
+ return false;
+ }
+ auto inv = typename kel::lbm::native_data_type<T>::type(1)
+ / std::sqrt(l2);
+ for(uint64_t i{0u}; i < D; ++i){
+ out.at({{i}}).set(in.at({{i}}).get() * inv);
+ }
+ return true;
+}
+}
+
+/**
+ * Narrow phase. Specialized per collision shape so the voxel version can be
+ * swapped in later without touching the force law.
+ */
+template<typename Collision>
+class narrow_phase {
+ static_assert(kel::lbm::always_false<Collision>, "Not supported");
+};
+
+template<typename T>
+class narrow_phase<coll::Spheroid<T>> final {
+public:
+ /**
+ * Sphere-sphere contact.
+ *
+ * Takes the pair in a canonical order chosen by the caller. The result is
+ * then bitwise identical for both owners of the pair, which is what makes
+ * the symmetric no-atomics formulation conserve momentum exactly: IEEE
+ * subtraction is exactly antisymmetric, but only if both sides subtract in
+ * the same order.
+ *
+ * `normal` points from `hi` toward `lo`.
+ */
+ template<uint64_t D, typename PRef>
+ static bool contact(
+ const PRef& lo,
+ const PRef& hi,
+ kel::lbm::data<sch::ContactManifold<T,D>>& out
+ ){
+ auto& pos_lo = lo.template get<"rigid_body">().template get<"position">();
+ auto& pos_hi = hi.template get<"rigid_body">().template get<"position">();
+
+ auto r_lo = lo.template get<"collision">().template get<"radius">().at({}).get();
+ auto r_hi = hi.template get<"collision">().template get<"radius">().at({}).get();
+
+ kel::lbm::data<sch::Vector<T,D>> d;
+ for(uint64_t i{0u}; i < D; ++i){
+ d.at({{i}}) = pos_lo.at({{i}}) - pos_hi.at({{i}});
+ }
+
+ auto len_2 = kel::lbm::math::dot(d,d).at({}).get();
+ auto sum_r = r_lo + r_hi;
+
+ if(!(len_2 < sum_r * sum_r)){
+ return false;
+ }
+
+ auto len = std::sqrt(len_2);
+ auto depth = sum_r - len;
+
+ /**
+ * Cap the penetration at the smaller radius. A pair that tunnelled
+ * would otherwise produce an unbounded impulse and blow up the run.
+ */
+ auto cap = (r_lo < r_hi) ? r_lo : r_hi;
+ if(depth > cap){
+ depth = cap;
+ }
+
+ auto& n = out.template get<"normal">();
+ if(!impl::safe_normalize<T,D>(d,n)){
+ /**
+ * Coincident centres: there is no geometric direction left, so
+ * pick a fixed axis. Deterministic, and it separates the pair
+ * instead of producing NaN.
+ */
+ for(uint64_t i{0u}; i < D; ++i){
+ n.at({{i}}).set(0);
+ }
+ n.at({{0u}}).set(1);
+ }
+
+ out.template get<"depth">().at({}).set(depth);
+
+ // Contact point: on the surface of hi, along the normal.
+ auto& point = out.template get<"point">();
+ for(uint64_t i{0u}; i < D; ++i){
+ point.at({{i}}).set(
+ pos_hi.at({{i}}).get() + n.at({{i}}).get() * (r_hi - depth * 0.5)
+ );
+ }
+
+ return true;
+ }
+};
+
+/**
+ * Force and torque produced by one contact, on one body.
+ */
+template<typename T, uint64_t D>
+struct contact_response {
+ kel::lbm::data<sch::Vector<T,D>> force;
+ kel::lbm::data<typename sch::impl::rotation_type_helper<T,D>::Schema> torque;
+};
+
+namespace impl {
+/**
+ * The soft-shell law itself, shared by particle-particle and particle-wall.
+ *
+ * `m_eff` is the reduced mass of the pair; a wall is the infinite-mass limit,
+ * where it collapses to the particle's own mass. `v_rel` is the relative
+ * surface velocity at the contact point.
+ */
+template<typename T, uint64_t D>
+contact_response<T,D> soft_shell_response(
+ const kel::lbm::data<sch::ContactManifold<T,D>>& m,
+ const kel::lbm::data<sch::Vector<T,D>>& r_self,
+ const kel::lbm::data<sch::Vector<T,D>>& v_rel,
+ typename kel::lbm::native_data_type<T>::type m_eff,
+ const dem_params<T>& dem
+){
+ contact_response<T,D> res;
+
+ auto& n = m.template get<"normal">();
+ auto depth = m.template get<"depth">().at({}).get();
+
+ auto k_n = dem.k_n.at({}).get();
+ auto zeta = dem.zeta_n.at({}).get();
+
+ // Critical damping is 2 sqrt(m k); zeta scales it.
+ auto g_n = 2.0 * zeta * std::sqrt(m_eff * k_n);
+
+ auto v_n = kel::lbm::math::dot(v_rel,n).at({}).get();
+
+ /**
+ * Clamped at zero: a contact pushes, never pulls. Without this the
+ * dashpot would suck separating particles back together.
+ */
+ auto f_n = k_n * depth - g_n * v_n;
+ if(f_n < 0){
+ f_n = 0;
+ }
+
+ // Tangential part of the relative velocity.
+ kel::lbm::data<sch::Vector<T,D>> v_t;
+ for(uint64_t i{0u}; i < D; ++i){
+ v_t.at({{i}}).set(v_rel.at({{i}}).get() - v_n * n.at({{i}}).get());
+ }
+
+ kel::lbm::data<sch::Vector<T,D>> t_hat;
+ auto have_t = safe_normalize<T,D>(v_t,t_hat);
+
+ auto v_t_len = std::sqrt(kel::lbm::math::dot(v_t,v_t).at({}).get());
+ auto f_t = dem.gamma_t.at({}).get() * v_t_len;
+ auto f_t_cap = dem.mu.at({}).get() * f_n;
+ if(f_t > f_t_cap){
+ f_t = f_t_cap;
+ }
+
+ for(uint64_t i{0u}; i < D; ++i){
+ auto v = f_n * n.at({{i}}).get();
+ if(have_t){
+ // Friction opposes sliding.
+ v -= f_t * t_hat.at({{i}}).get();
+ }
+ res.force.at({{i}}).set(v);
+ }
+
+ // cross gives Scalar in 2D and Vector3 in 3D, which is exactly the
+ // rotation type in each case, so one spelling covers both.
+ res.torque = kel::lbm::math::cross<T>(r_self,res.force);
+
+ return res;
+}
+
+/**
+ * Surface velocity of a body at an offset from its centre.
+ *
+ * Velocity is implicit in position-Verlet, recovered from the position pair.
+ */
+template<typename T, uint64_t D, typename PRef>
+kel::lbm::data<sch::Vector<T,D>> surface_velocity(
+ const PRef& p,
+ const kel::lbm::data<sch::Vector<T,D>>& r,
+ typename kel::lbm::native_data_type<T>::type steps
+){
+ auto& rb = p.template get<"rigid_body">();
+ auto& pos = rb.template get<"position">();
+ auto& pos_old = rb.template get<"position_old">();
+
+ kel::lbm::data<sch::Vector<T,D>> v;
+ for(uint64_t i{0u}; i < D; ++i){
+ v.at({{i}}).set((pos.at({{i}}).get() - pos_old.at({{i}}).get()) * steps);
+ }
+
+ auto& rot = rb.template get<"rotation">();
+ auto& rot_old = rb.template get<"rotation_old">();
+
+ if constexpr ( D == 2u ){
+ kel::lbm::data<sch::Scalar<T>> omega;
+ omega.at({}).set((rot.at({}).get() - rot_old.at({}).get()) * steps);
+ auto tang = kel::lbm::math::cross<T>(omega,r);
+ for(uint64_t i{0u}; i < D; ++i){
+ v.at({{i}}) = v.at({{i}}) + tang.at({{i}});
+ }
+ }else{
+ kel::lbm::data<sch::Vector<T,3u>> omega;
+ for(uint64_t i{0u}; i < 3u; ++i){
+ omega.at({{i}}).set((rot.at({{i}}).get() - rot_old.at({{i}}).get()) * steps);
+ }
+ auto tang = kel::lbm::math::cross<T>(omega,r);
+ for(uint64_t i{0u}; i < D; ++i){
+ v.at({{i}}) = v.at({{i}}) + tang.at({{i}});
+ }
+ }
+
+ return v;
+}
+}
+
+/**
+ * Contact response on `self` from `other`.
+ *
+ * `self_is_lo` says which side of the canonical pair ordering `self` is on.
+ * The manifold is always computed as (lo,hi) so both owners see bitwise
+ * identical geometry; the hi owner simply flips the normal.
+ */
+template<typename T, uint64_t D, typename PRef>
+contact_response<T,D> particle_contact_response(
+ const kel::lbm::data<sch::ContactManifold<T,D>>& m_in,
+ const PRef& self,
+ const PRef& other,
+ bool self_is_lo,
+ const dem_params<T>& dem,
+ kel::lbm::data<sch::UInt64> sub_steps
+){
+ auto steps = static_cast<typename kel::lbm::native_data_type<T>::type>(
+ particle_sub_steps(sub_steps));
+
+ kel::lbm::data<sch::ContactManifold<T,D>> m = m_in;
+ if(!self_is_lo){
+ auto& n = m.template get<"normal">();
+ for(uint64_t i{0u}; i < D; ++i){
+ n.at({{i}}).set(-n.at({{i}}).get());
+ }
+ }
+
+ auto& point = m.template get<"point">();
+ auto& pos_s = self.template get<"rigid_body">().template get<"position">();
+ auto& pos_o = other.template get<"rigid_body">().template get<"position">();
+
+ kel::lbm::data<sch::Vector<T,D>> r_s, r_o;
+ for(uint64_t i{0u}; i < D; ++i){
+ r_s.at({{i}}).set(point.at({{i}}).get() - pos_s.at({{i}}).get());
+ r_o.at({{i}}).set(point.at({{i}}).get() - pos_o.at({{i}}).get());
+ }
+
+ auto v_s = impl::surface_velocity<T,D>(self,r_s,steps);
+ auto v_o = impl::surface_velocity<T,D>(other,r_o,steps);
+
+ kel::lbm::data<sch::Vector<T,D>> v_rel;
+ for(uint64_t i{0u}; i < D; ++i){
+ v_rel.at({{i}}).set(v_s.at({{i}}).get() - v_o.at({{i}}).get());
+ }
+
+ auto m_s = self.template get<"rigid_body">().template get<"mass">().at({}).get();
+ auto m_o = other.template get<"rigid_body">().template get<"mass">().at({}).get();
+ auto m_eff = (m_s * m_o) / (m_s + m_o);
+
+ return impl::soft_shell_response<T,D>(m,r_s,v_rel,m_eff,dem);
+}
+
+/**
+ * Contact response against a static wall.
+ *
+ * A wall is a partner of infinite mass and zero velocity, so the reduced mass
+ * collapses to the particle's own and the relative velocity is just the
+ * particle's surface velocity. The force law is otherwise identical -- the
+ * same soft shell.
+ */
+template<typename T, uint64_t D, typename PRef>
+contact_response<T,D> wall_contact_response(
+ const kel::lbm::data<sch::ContactManifold<T,D>>& m,
+ const PRef& self,
+ const dem_params<T>& dem,
+ kel::lbm::data<sch::UInt64> sub_steps
+){
+ auto steps = static_cast<typename kel::lbm::native_data_type<T>::type>(
+ particle_sub_steps(sub_steps));
+
+ auto& point = m.template get<"point">();
+ auto& pos_s = self.template get<"rigid_body">().template get<"position">();
+
+ kel::lbm::data<sch::Vector<T,D>> r_s;
+ for(uint64_t i{0u}; i < D; ++i){
+ r_s.at({{i}}).set(point.at({{i}}).get() - pos_s.at({{i}}).get());
+ }
+
+ auto v_rel = impl::surface_velocity<T,D>(self,r_s,steps);
+
+ auto m_s = self.template get<"rigid_body">().template get<"mass">().at({}).get();
+
+ return impl::soft_shell_response<T,D>(m,r_s,v_rel,m_s,dem);
+}
+
+/**
+ * Accumulates wall contacts for the axis-aligned domain box.
+ *
+ * One manifold per face the particle has entered; a particle in a corner gets
+ * a contribution from each axis, which is what makes it settle into the corner
+ * rather than squeeze through it.
+ */
+template<typename T, uint64_t D, typename PRef>
+void accumulate_box_wall_contacts(
+ PRef&& self,
+ const kel::lbm::data<sch::FixedArray<sch::UInt64,D>>& extent,
+ const dem_params<T>& dem,
+ kel::lbm::data<sch::UInt64> sub_steps
+){
+ auto& rb = self.template get<"rigid_body">();
+ auto& pos = rb.template get<"position">();
+ auto r = self.template get<"collision">().template get<"radius">().at({}).get();
+
+ for(uint64_t ax{0u}; ax < D; ++ax){
+ auto x = pos.at({{ax}}).get();
+ auto hi_bound = static_cast<typename kel::lbm::native_data_type<T>::type>(
+ extent.at({ax}).get());
+
+ // Low face, inward normal +e_ax; high face, inward normal -e_ax.
+ for(uint64_t side{0u}; side < 2u; ++side){
+ auto depth = (side == 0u) ? (r - x) : (x - (hi_bound - r));
+ if(!(depth > 0)){
+ continue;
+ }
+ if(depth > r){
+ depth = r;
+ }
+
+ kel::lbm::data<sch::ContactManifold<T,D>> m;
+ auto& n = m.template get<"normal">();
+ auto& point = m.template get<"point">();
+ for(uint64_t i{0u}; i < D; ++i){
+ n.at({{i}}).set(0);
+ point.at({{i}}).set(pos.at({{i}}).get());
+ }
+ n.at({{ax}}).set((side == 0u) ? 1.0 : -1.0);
+ point.at({{ax}}).set((side == 0u) ? 0.0 : hi_bound);
+ m.template get<"depth">().at({}).set(depth);
+
+ auto res = wall_contact_response<T,D>(m,self,dem,sub_steps);
+
+ auto& force = rb.template get<"force">();
+ for(uint64_t i{0u}; i < D; ++i){
+ force.at({{i}}) = force.at({{i}}) + res.force.at({{i}});
+ }
+ if constexpr ( particle_angular_supported<D> ){
+ auto& torque = rb.template get<"torque">();
+ torque = torque + res.torque;
+ }
+ }
+ }
+}
+
+/**
+ * Brute-force pair loop: accumulates every contact acting on one particle.
+ *
+ * Only `self` is written. The partner's half is computed by the partner's own
+ * work-item, which is what removes the need for atomics. The pair geometry is
+ * evaluated in canonical (lo,hi) order on both sides so the two halves are
+ * exactly equal and opposite.
+ */
+template<typename T, uint64_t D, typename PartsRef>
+void accumulate_particle_contacts(
+ PartsRef&& parts,
+ uint64_t self_index,
+ const dem_params<T>& dem,
+ kel::lbm::data<sch::UInt64> sub_steps
+){
+ auto& self = parts.at({self_index});
+
+ // get_dims() is the one spelling both the host array and the device Ptr view share.
+ const uint64_t count = parts.get_dims().at({0u}).get();
+
+ for(uint64_t j{0u}; j < count; ++j){
+ if(j == self_index){
+ continue;
+ }
+
+ auto& other = parts.at({j});
+
+ if(!(broadphase_collision_check<T,D,coll::Spheroid<T>>)(self,other)){
+ continue;
+ }
+
+ const bool self_is_lo = (self_index < j);
+ auto& lo = self_is_lo ? self : other;
+ auto& hi = self_is_lo ? other : self;
+
+ kel::lbm::data<sch::ContactManifold<T,D>> m;
+ if(!narrow_phase<coll::Spheroid<T>>::template contact<D>(lo,hi,m)){
+ continue;
+ }
+
+ auto res = particle_contact_response<T,D>(m,self,other,self_is_lo,dem,sub_steps);
+
+ auto& rb = self.template get<"rigid_body">();
+ auto& force = rb.template get<"force">();
+ for(uint64_t i{0u}; i < D; ++i){
+ force.at({{i}}) = force.at({{i}}) + res.force.at({{i}});
+ }
+ // Tied to the integrator: accumulating torque the integrator will not
+ // consume would be a silent no-op.
+ if constexpr ( particle_angular_supported<D> ){
+ auto& torque = rb.template get<"torque">();
+ torque = torque + res.torque;
+ }
+ }
+}
+
+namespace cmpt {
+/**
+ * Accumulates contact forces onto one particle. Runs between the fluid gather
+ * and the integrate.
+ */
+struct ParticleContact {};
+}
+
+template<typename T, typename Descriptor, typename Encode>
+class component<T, Descriptor, cmpt::ParticleContact, Encode> final {
+public:
+ using Component = cmpt::ParticleContact;
+
+private:
+ dem_params<T> dem_;
+ bool with_walls_;
+ kel::lbm::data<sch::FixedArray<sch::UInt64,Descriptor::D>> extent_;
+
+public:
+ component():
+ dem_{}, with_walls_{false}, extent_{}
+ {}
+
+ component(const dem_params<T>& dem__):
+ dem_{dem__}, with_walls_{false}, extent_{}
+ {}
+
+ component(
+ const dem_params<T>& dem__,
+ const kel::lbm::data<sch::FixedArray<sch::UInt64,Descriptor::D>>& extent__
+ ):
+ dem_{dem__}, with_walls_{true}, extent_{extent__}
+ {}
+
+ template<typename ParticleSchema>
+ void apply(
+ const kel::lbm::data<ParticleSchema,Encode>& pg,
+ kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index,
+ kel::lbm::data<sch::UInt64> time_step,
+ kel::lbm::data<sch::UInt64> sub_steps
+ ) const {
+ (void) time_step;
+
+ auto& parts = pg.template get<"particles">();
+
+ accumulate_particle_contacts<T,Descriptor::D>(
+ parts, index.at({{0u}}).get(), dem_, sub_steps);
+
+ if(with_walls_){
+ accumulate_box_wall_contacts<T,Descriptor::D>(
+ parts.at(index), extent_, dem_, sub_steps);
+ }
+ }
+};
+
+}
+}
diff --git a/modules/core/c++/particle/couple.hpp b/modules/core/c++/particle/couple.hpp
new file mode 100644
index 0000000..19a276c
--- /dev/null
+++ b/modules/core/c++/particle/couple.hpp
@@ -0,0 +1,108 @@
+#pragma once
+
+#include "../component.hpp"
+#include "common.hpp"
+#include "schema.hpp"
+#include "porosity.hpp"
+#include "cell_list.hpp"
+
+namespace kel {
+namespace lbm {
+
+/**
+ * Solid fraction at one lattice cell, summed over every particle covering it.
+ *
+ * This is the gather counterpart of the per-particle porosity stamp. The
+ * stamp *writes* macros.porosity from a per-particle work item, so two
+ * particles whose bounding boxes overlap race on the same cell -- and
+ * contacting particles always overlap. Here one work item owns one cell and
+ * writes only that cell, so there is nothing to race on and no atomic needed.
+ *
+ * Porosity composes as a product of the per-particle fluid fractions: a cell
+ * fully inside either body is fully solid, and partial overlaps multiply
+ * rather than clobbering one another. The per-particle version could not do
+ * this at all -- whichever particle ran last simply won.
+ */
+template<typename T, uint64_t D, uint64_t CellCapacity, typename PartsRef, typename ClRef, typename CellRef>
+kel::lbm::data<sch::Scalar<T>> cell_porosity(
+ const PartsRef& parts,
+ const ClRef& cl,
+ const CellRef& cell,
+ kel::lbm::data<sch::Scalar<T>> eps
+){
+ kel::lbm::data<sch::Scalar<T>> por;
+ por.at({}).set(1);
+
+ kel::lbm::data<sch::Vector<T,D>> cell_pos;
+ for(uint64_t i{0u}; i < D; ++i){
+ cell_pos.at({{i}}).set(
+ static_cast<typename kel::lbm::native_data_type<T>::type>(cell.at({i}).get())
+ );
+ }
+
+ for_each_bin_candidate<T,D,CellCapacity>(cl,cell,[&](uint64_t p){
+ auto& pi = parts.at({p});
+ auto& pos = pi.template get<"rigid_body">().template get<"position">();
+ auto rad = pi.template get<"collision">().template get<"radius">();
+
+ kel::lbm::data<sch::Vector<T,D>> rel;
+ for(uint64_t i{0u}; i < D; ++i){
+ rel.at({{i}}).set(cell_pos.at({{i}}).get() - pos.at({{i}}).get());
+ }
+
+ auto p_por = particle_porosity<T,D,1u,por::ParticleSpheroid<T>>::calculate(rel,rad,eps);
+
+ // 1 = fluid, 0 = solid, so fractions multiply.
+ por.at({}).set(por.at({}).get() * p_por.at({}).get());
+ });
+
+ return por;
+}
+
+namespace cmpt {
+/**
+ * Writes the particle coupling fields for one lattice cell.
+ *
+ * Replaces the per-particle scatter. Runs over the lattice, not the particle
+ * list, so it stays correct once particles start overlapping.
+ */
+template<uint64_t CellCapacity>
+struct ParticleFluidCouple {};
+}
+
+template<typename T, typename Descriptor, uint64_t CellCapacity, typename Encode>
+class component<T, Descriptor, cmpt::ParticleFluidCouple<CellCapacity>, Encode> final {
+public:
+ using Component = cmpt::ParticleFluidCouple<CellCapacity>;
+
+private:
+ kel::lbm::data<sch::Scalar<T>> eps_;
+
+public:
+ component(){
+ eps_.at({}).set(1.5);
+ }
+
+ component(const kel::lbm::data<sch::Scalar<T>>& eps__):
+ eps_{eps__}
+ {}
+
+ template<typename MacroFieldSchema, typename ParticleSchema, typename CellListSchema>
+ void apply(
+ const kel::lbm::data<MacroFieldSchema,Encode>& macros,
+ const kel::lbm::data<ParticleSchema,Encode>& pg,
+ const kel::lbm::data<CellListSchema,Encode>& cl,
+ kel::lbm::data<sch::FixedArray<sch::UInt64,Descriptor::D>> index,
+ kel::lbm::data<sch::UInt64> time_step
+ ) const {
+ (void) time_step;
+
+ auto& parts = pg.template get<"particles">();
+
+ macros.template get<"porosity">().at(index) =
+ cell_porosity<T,Descriptor::D,CellCapacity>(parts,cl,index,eps_);
+ }
+};
+
+}
+}
diff --git a/modules/core/c++/particle/integrate.hpp b/modules/core/c++/particle/integrate.hpp
new file mode 100644
index 0000000..f83465a
--- /dev/null
+++ b/modules/core/c++/particle/integrate.hpp
@@ -0,0 +1,175 @@
+#pragma once
+
+#include "../component.hpp"
+#include "common.hpp"
+#include "schema.hpp"
+#include "particle.hpp"
+
+namespace kel {
+namespace lbm {
+/**
+ * Zero sub steps means "advance once", not "do not advance".
+ *
+ * Taking it literally gave ts = 1/0 = inf and a loop that never ran, which
+ * silently froze the particle. Several step functions pass {0u}.
+ */
+inline uint64_t particle_sub_steps(kel::lbm::data<sch::UInt64> sub_steps){
+ uint64_t steps = sub_steps.get();
+ return (steps == 0u) ? 1u : steps;
+}
+/**
+ * Whether rotation is integrated at all for a given dimension.
+ *
+ * True in 2D, where the scalar moment of inertia is exact about the single
+ * out-of-plane axis and verlet_step_lambda's vector update is the correct
+ * integrator.
+ *
+ * False in 3D, and deliberately so rather than approximately right. Two
+ * separate things are missing there: a scalar inertia only describes an
+ * isotropic body, and integrating the rotation vector as if it were a
+ * displacement cannot represent non-commuting composition -- the gyroscopic
+ * term omega x (I omega) is absent entirely. Shipping that would give plausible
+ * looking but wrong 3D spin, which is worse than none. Callers can branch on
+ * this; a correct 3D path wants a quaternion and an inertia tensor.
+ */
+template<uint64_t D>
+constexpr bool particle_angular_supported = (D == 2u);
+
+
+/**
+ * Turns the accumulated force/torque into acceleration and advances the body.
+ *
+ * A free function rather than only a component so it is callable from a host
+ * test, and so a future stiff-contact scheme can call it from inside its own
+ * sub-step loop.
+ */
+template<typename T, uint64_t D>
+void integrate_particle(
+ kel::lbm::data<sch::Particle<T,D>>& pi,
+ const kel::lbm::data<sch::Vector<T,D>>& body_acceleration,
+ kel::lbm::data<sch::UInt64> sub_steps
+){
+ auto& pirb = pi.template get<"rigid_body">();
+
+ const uint64_t steps = particle_sub_steps(sub_steps);
+
+ kel::lbm::data<sch::Scalar<T>> ts;
+ ts.at({}).set(
+ typename kel::lbm::native_data_type<T>::type(1)
+ / static_cast<typename kel::lbm::native_data_type<T>::type>(steps)
+ );
+
+ pirb.template get<"acceleration">() =
+ pirb.template get<"force">() / pirb.template get<"mass">()
+ + body_acceleration;
+
+ // See particle_angular_supported for why 3D is excluded rather than
+ // approximated.
+ if constexpr ( particle_angular_supported<D> ){
+ pirb.template get<"angular_acceleration">() =
+ pirb.template get<"torque">() / pirb.template get<"inertia">();
+ }
+
+ for(uint64_t i{0u}; i < steps; ++i){
+ verlet_step_lambda<T,D>(pi,ts);
+ }
+}
+
+/**
+ * Clears the force/torque accumulators. Must run before any contributor.
+ */
+template<typename T, uint64_t D>
+void reset_particle_accumulators(kel::lbm::data<sch::Particle<T,D>>& pi){
+ auto& pirb = pi.template get<"rigid_body">();
+
+ auto& force = pirb.template get<"force">();
+ for(uint64_t i{0u}; i < D; ++i){
+ force.at({{i}}).set(0);
+ }
+
+ auto& torque = pirb.template get<"torque">();
+ if constexpr ( D == 2u ){
+ torque.at({}).set(0);
+ }else{
+ for(uint64_t i{0u}; i < 3u; ++i){
+ torque.at({{i}}).set(0);
+ }
+ }
+}
+
+namespace cmpt {
+/**
+ * Clears the per-particle force/torque accumulators.
+ *
+ * Must run before any contributor. Separate from integration because
+ * contributors (fluid coupling, contact, body forces) sit between the two.
+ */
+struct ParticleForceReset {};
+
+/**
+ * Turns the accumulated force/torque into acceleration and advances the body.
+ *
+ * This is the single place that writes acceleration, which is what lets the
+ * contributors merely accumulate. Previously each fluid component assigned
+ * acceleration directly, so a second contributor silently overwrote the first.
+ */
+struct ParticleIntegrate {};
+}
+
+template<typename T, typename Descriptor, typename Encode>
+class component<T, Descriptor, cmpt::ParticleForceReset, Encode> final {
+public:
+ using Component = cmpt::ParticleForceReset;
+
+ component() = default;
+
+ template<typename ParticleSchema>
+ void apply(
+ const kel::lbm::data<ParticleSchema,Encode>& pg,
+ kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index,
+ kel::lbm::data<sch::UInt64> time_step
+ ) const {
+ (void) time_step;
+
+ auto& parts = pg.template get<"particles">();
+ reset_particle_accumulators<T,Descriptor::D>(parts.at(index));
+ }
+};
+
+template<typename T, typename Descriptor, typename Encode>
+class component<T, Descriptor, cmpt::ParticleIntegrate, Encode> final {
+public:
+ using Component = cmpt::ParticleIntegrate;
+
+private:
+ /**
+ * Body acceleration applied to every particle, e.g. gravity. Kept as an
+ * acceleration rather than a force so it does not need the mass.
+ */
+ kel::lbm::data<sch::Vector<T,Descriptor::D>> body_acceleration_;
+
+public:
+ component():
+ body_acceleration_{}
+ {}
+
+ component(const kel::lbm::data<sch::Vector<T,Descriptor::D>>& body_acceleration__):
+ body_acceleration_{body_acceleration__}
+ {}
+
+ template<typename ParticleSchema>
+ void apply(
+ const kel::lbm::data<ParticleSchema,Encode>& pg,
+ kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index,
+ kel::lbm::data<sch::UInt64> time_step,
+ kel::lbm::data<sch::UInt64> sub_steps
+ ) const {
+ (void) time_step;
+
+ auto& parts = pg.template get<"particles">();
+ integrate_particle<T,Descriptor::D>(parts.at(index), body_acceleration_, sub_steps);
+ }
+};
+
+}
+}
diff --git a/modules/core/c++/particle/mask.hpp b/modules/core/c++/particle/mask.hpp
new file mode 100644
index 0000000..246c31f
--- /dev/null
+++ b/modules/core/c++/particle/mask.hpp
@@ -0,0 +1,399 @@
+#pragma once
+
+#include <cmath>
+
+#include "../abstract/math.hpp"
+#include "../iterator.hpp"
+#include "common.hpp"
+#include "schema.hpp"
+
+namespace kel {
+namespace lbm {
+
+/**
+ * Voxel shape convention
+ * ======================
+ *
+ * The group's mask is a D-cube of R voxels per axis holding a SIGNED DISTANCE
+ * in NORMALIZED PARTICLE-LOCAL units, where the shape's bounding radius is
+ * exactly 1. So the mask spans local [-1,1]^D and
+ *
+ * step = 2 / R
+ * u_local(k) = -1 + (k + 0.5) * step (cell centred)
+ * k(u_local) = (u_local + 1) / step - 0.5
+ *
+ * Normalized rather than lattice units because radius is now a per-particle
+ * property: one group mask has to serve particles of different sizes, and the
+ * physical radius is then exactly `scale`. That also makes the bounding-sphere
+ * broad phase agree with the voxel narrow phase by construction -- spheres
+ * disjoint implies voxels disjoint -- instead of by argument.
+ *
+ * Local to global, and its inverse, which is what the narrow phase needs:
+ *
+ * x_global = pos + scale * Rot(theta) * (u_local - com)
+ * u_local = Rot(-theta) * (x_global - pos) / scale + com
+ *
+ * Signed distance rather than a 0/1 indicator because the indicator's gradient
+ * is a one-cell delta quantized to lattice directions, which cannot give a
+ * usable contact normal. From an SDF the normal is grad(phi) and the
+ * penetration is -phi directly, and a smooth solid fraction is still one cheap
+ * ramp away. Switching later would mean rebuilding every mask, so it is
+ * decided here.
+ *
+ * Sign: negative inside the body, positive outside. Solid fraction is derived,
+ * and porosity stays 1 = fluid / 0 = solid to match the analytic path.
+ */
+
+namespace impl {
+/**
+ * Rotates a local offset into the global frame.
+ *
+ * 2D rotation is an angle; 3D is a rotation vector (axis * angle) applied via
+ * Rodrigues, which matches how verlet_step_lambda integrates it.
+ */
+template<typename T, uint64_t D, typename RotRef>
+kel::lbm::data<sch::Vector<T,D>> mask_rotate(
+ const kel::lbm::data<sch::Vector<T,D>>& v,
+ const RotRef& rot,
+ bool inverse
+){
+ if constexpr ( D == 2u ){
+ auto a = rot.at({}).get();
+ if(inverse){
+ a = -a;
+ }
+ auto c = std::cos(a);
+ auto s = std::sin(a);
+
+ kel::lbm::data<sch::Vector<T,D>> out;
+ out.at({{0u}}).set(v.at({{0u}}).get() * c - v.at({{1u}}).get() * s);
+ out.at({{1u}}).set(v.at({{0u}}).get() * s + v.at({{1u}}).get() * c);
+ return out;
+ }else{
+ kel::lbm::data<sch::Vector<T,3u>> r;
+ for(uint64_t i{0u}; i < 3u; ++i){
+ r.at({{i}}).set(rot.at({{i}}).get());
+ }
+
+ auto theta_2 = kel::lbm::math::dot(r,r).at({}).get();
+ if(!(theta_2 > 0)){
+ return v;
+ }
+ auto theta = std::sqrt(theta_2);
+ if(inverse){
+ theta = -theta;
+ }
+
+ kel::lbm::data<sch::Vector<T,3u>> n;
+ for(uint64_t i{0u}; i < 3u; ++i){
+ n.at({{i}}).set(r.at({{i}}).get() / std::sqrt(theta_2));
+ }
+
+ auto c = std::cos(theta);
+ auto s = std::sin(theta);
+ auto n_dot_v = kel::lbm::math::dot(n,v).at({}).get();
+ auto cross = kel::lbm::math::cross<T>(n,v);
+
+ kel::lbm::data<sch::Vector<T,D>> out;
+ for(uint64_t i{0u}; i < D; ++i){
+ out.at({{i}}).set(
+ v.at({{i}}).get() * c
+ + cross.at({{i}}).get() * s
+ + n.at({{i}}).get() * n_dot_v * (1 - c)
+ );
+ }
+ return out;
+ }
+}
+}
+
+/**
+ * Voxel index -> normalized local position (cell centred).
+ */
+template<typename T, uint64_t D, typename IndexRef>
+kel::lbm::data<sch::Vector<T,D>> mask_voxel_to_local(
+ const IndexRef& k,
+ uint64_t resolution
+){
+ auto step = typename kel::lbm::native_data_type<T>::type(2)
+ / static_cast<typename kel::lbm::native_data_type<T>::type>(resolution);
+
+ kel::lbm::data<sch::Vector<T,D>> u;
+ for(uint64_t i{0u}; i < D; ++i){
+ auto ki = static_cast<typename kel::lbm::native_data_type<T>::type>(k.at({i}).get());
+ u.at({{i}}).set(-1 + (ki + 0.5) * step);
+ }
+ return u;
+}
+
+/**
+ * Normalized local -> global lattice position.
+ */
+template<typename T, uint64_t D, typename PRef, typename ComRef>
+kel::lbm::data<sch::Vector<T,D>> mask_local_to_global(
+ const kel::lbm::data<sch::Vector<T,D>>& u,
+ const PRef& p,
+ const ComRef& com
+){
+ auto& rb = p.template get<"rigid_body">();
+ auto& pos = rb.template get<"position">();
+ auto scale = p.template get<"collision">().template get<"radius">().at({}).get();
+
+ kel::lbm::data<sch::Vector<T,D>> rel;
+ for(uint64_t i{0u}; i < D; ++i){
+ rel.at({{i}}).set(u.at({{i}}).get() - com.at({{i}}).get());
+ }
+
+ auto rot = impl::mask_rotate<T,D>(rel, rb.template get<"rotation">(), false);
+
+ kel::lbm::data<sch::Vector<T,D>> x;
+ for(uint64_t i{0u}; i < D; ++i){
+ x.at({{i}}).set(pos.at({{i}}).get() + scale * rot.at({{i}}).get());
+ }
+ return x;
+}
+
+/**
+ * Global lattice position -> normalized local. The inverse of the above, and
+ * what the narrow phase and the porosity gather both go through.
+ */
+template<typename T, uint64_t D, typename PRef, typename ComRef>
+kel::lbm::data<sch::Vector<T,D>> mask_global_to_local(
+ const kel::lbm::data<sch::Vector<T,D>>& x,
+ const PRef& p,
+ const ComRef& com
+){
+ auto& rb = p.template get<"rigid_body">();
+ auto& pos = rb.template get<"position">();
+ auto scale = p.template get<"collision">().template get<"radius">().at({}).get();
+
+ kel::lbm::data<sch::Vector<T,D>> rel;
+ for(uint64_t i{0u}; i < D; ++i){
+ rel.at({{i}}).set((x.at({{i}}).get() - pos.at({{i}}).get()) / scale);
+ }
+
+ auto unrot = impl::mask_rotate<T,D>(rel, rb.template get<"rotation">(), true);
+
+ kel::lbm::data<sch::Vector<T,D>> u;
+ for(uint64_t i{0u}; i < D; ++i){
+ u.at({{i}}).set(unrot.at({{i}}).get() + com.at({{i}}).get());
+ }
+ return u;
+}
+
+/**
+ * Samples the stored signed distance at a normalized local position, with
+ * n-linear interpolation.
+ *
+ * Interpolated rather than nearest so the field stays continuous as a particle
+ * slides across the lattice; a nearest lookup aliases whenever the voxel pitch
+ * does not divide the lattice, and leaves grad(phi) piecewise constant, which
+ * the contact normal cannot use.
+ *
+ * Outside the mask box the distance is extrapolated from the box corner, which
+ * is monotone and good enough -- nothing in contact range is ever out there.
+ */
+template<typename T, uint64_t D, typename MaskRef>
+typename kel::lbm::native_data_type<T>::type mask_sample_local(
+ const MaskRef& mask,
+ const kel::lbm::data<sch::Vector<T,D>>& u,
+ uint64_t resolution
+){
+ using NT = typename kel::lbm::native_data_type<T>::type;
+
+ auto step = NT(2) / static_cast<NT>(resolution);
+
+ NT frac[D];
+ int64_t base[D];
+ NT outside = 0;
+
+ for(uint64_t i{0u}; i < D; ++i){
+ auto g = (u.at({{i}}).get() + 1) / step - NT(0.5);
+
+ // Track how far the query sits beyond the stored box.
+ if(g < 0){
+ outside += g * g * step * step;
+ g = 0;
+ }else if(g > static_cast<NT>(resolution - 1u)){
+ auto over = g - static_cast<NT>(resolution - 1u);
+ outside += over * over * step * step;
+ g = static_cast<NT>(resolution - 1u);
+ }
+
+ auto f = std::floor(g);
+ base[i] = static_cast<int64_t>(f);
+ if(base[i] > static_cast<int64_t>(resolution) - 2){
+ base[i] = static_cast<int64_t>(resolution) - 2;
+ if(base[i] < 0){
+ base[i] = 0;
+ }
+ }
+ frac[i] = g - static_cast<NT>(base[i]);
+ }
+
+ // n-linear blend over the 2^D surrounding voxels.
+ uint64_t corners = 1u;
+ for(uint64_t i{0u}; i < D; ++i){
+ corners *= 2u;
+ }
+
+ NT acc = 0;
+ for(uint64_t c{0u}; c < corners; ++c){
+ NT w = 1;
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> k;
+
+ for(uint64_t i{0u}; i < D; ++i){
+ const bool hi = ((c >> i) & 1u) != 0u;
+ auto idx = base[i] + (hi ? 1 : 0);
+ if(idx < 0){
+ idx = 0;
+ }
+ if(idx > static_cast<int64_t>(resolution) - 1){
+ idx = static_cast<int64_t>(resolution) - 1;
+ }
+ k.at({i}).set(static_cast<uint64_t>(idx));
+ w *= hi ? frac[i] : (1 - frac[i]);
+ }
+
+ acc += w * mask.at(k).get();
+ }
+
+ if(outside > 0){
+ acc += std::sqrt(outside);
+ }
+
+ return acc;
+}
+
+/**
+ * Signed distance from a global lattice position to the body, in LATTICE
+ * units. Negative inside.
+ */
+template<typename T, uint64_t D, typename GroupRef, typename PRef>
+typename kel::lbm::native_data_type<T>::type mask_signed_distance(
+ const GroupRef& pg,
+ const PRef& p,
+ const kel::lbm::data<sch::Vector<T,D>>& x,
+ uint64_t resolution
+){
+ auto& com = pg.template get<"center_of_mass">().at({0u});
+ auto u = mask_global_to_local<T,D>(x,p,com);
+
+ auto scale = p.template get<"collision">().template get<"radius">().at({}).get();
+ return mask_sample_local<T,D>(pg.template get<"mask">(),u,resolution) * scale;
+}
+
+/**
+ * Smooth solid fraction: 1 fully inside, 0 fully outside, with a cos^2 ramp of
+ * width `eps` lattice units straddling the surface.
+ *
+ * Derived from the signed distance rather than stored, so one field serves
+ * both the fluid coupling and the contact normal.
+ */
+template<typename T>
+typename kel::lbm::native_data_type<T>::type solid_fraction_from_sdf(
+ typename kel::lbm::native_data_type<T>::type sdf,
+ typename kel::lbm::native_data_type<T>::type eps
+){
+ using NT = typename kel::lbm::native_data_type<T>::type;
+
+ auto half = eps / 2;
+ if(sdf <= -half){
+ return 1;
+ }
+ if(sdf >= half){
+ return 0;
+ }
+
+ // t runs 0 at the inner edge to 1 at the outer; cos^2 gives a smooth
+ // 1 -> 0 with zero slope at both ends.
+ auto t = (sdf + half) / eps;
+ auto c = std::cos(NT(3.14159265358979323846) * t / 2);
+ return c * c;
+}
+
+/**
+ * Signed distance functions in normalized local units, radius 1.
+ */
+namespace sdf {
+template<typename T, uint64_t D>
+typename kel::lbm::native_data_type<T>::type sphere(
+ const kel::lbm::data<sch::Vector<T,D>>& u
+){
+ return std::sqrt(kel::lbm::math::dot(u,u).at({}).get()) - 1;
+}
+
+/**
+ * Chebyshev distance: the inscribed-box shape whose bounding radius is 1 along
+ * each axis.
+ */
+template<typename T, uint64_t D>
+typename kel::lbm::native_data_type<T>::type cube(
+ const kel::lbm::data<sch::Vector<T,D>>& u
+){
+ typename kel::lbm::native_data_type<T>::type m = 0;
+ for(uint64_t i{0u}; i < D; ++i){
+ auto a = std::abs(u.at({{i}}).get());
+ if(a > m){
+ m = a;
+ }
+ }
+ return m - 1;
+}
+}
+
+/**
+ * Fills a group's mask from a signed distance function, and returns the volume
+ * centroid in normalized local units.
+ *
+ * The centroid is weighted by solid fraction, so it is the mass centre of the
+ * voxelized body rather than the centre of its bounding box -- they differ for
+ * anything asymmetric, and the physics wants the former.
+ */
+template<typename T, uint64_t D, typename MaskRef, typename Func>
+kel::lbm::data<sch::Vector<T,D>> fill_mask_from_sdf(
+ MaskRef&& mask,
+ uint64_t resolution,
+ Func&& sdf_fn
+){
+ using NT = typename kel::lbm::native_data_type<T>::type;
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> dims;
+ for(uint64_t i{0u}; i < D; ++i){
+ dims.at({i}).set(resolution);
+ }
+
+ kel::lbm::data<sch::Vector<T,D>> com;
+ for(uint64_t i{0u}; i < D; ++i){
+ com.at({{i}}).set(0);
+ }
+
+ NT weight_sum = 0;
+ auto step = NT(2) / static_cast<NT>(resolution);
+
+ iterator<D>::apply([&](const auto& k){
+ auto u = mask_voxel_to_local<T,D>(k,resolution);
+ auto d = sdf_fn(u);
+
+ mask.at(k).set(d);
+
+ // Ramp one voxel wide, purely so partially filled cells near the
+ // surface weight the centroid sensibly.
+ auto w = solid_fraction_from_sdf<T>(d,step);
+ weight_sum += w;
+ for(uint64_t i{0u}; i < D; ++i){
+ com.at({{i}}).set(com.at({{i}}).get() + w * u.at({{i}}).get());
+ }
+ },{},dims);
+
+ if(weight_sum > 0){
+ for(uint64_t i{0u}; i < D; ++i){
+ com.at({{i}}).set(com.at({{i}}).get() / weight_sum);
+ }
+ }
+
+ return com;
+}
+
+}
+}
diff --git a/modules/core/c++/particle/particle.hpp b/modules/core/c++/particle/particle.hpp
index 2b2ceac..d9b5444 100644
--- a/modules/core/c++/particle/particle.hpp
+++ b/modules/core/c++/particle/particle.hpp
@@ -8,31 +8,35 @@
#include "schema.hpp"
#include "aabb.hpp"
+#include "mask.hpp"
+#include "../abstract/data_ptr.hpp"
#include "particle_opa.hpp"
namespace kel {
namespace lbm {
+/**
+ * Builds a group of identical spheroids.
+ *
+ * The signature is unchanged from when radius/density/mass lived on the group:
+ * the three scalars are fanned out to every particle here, so no caller moves.
+ */
template<typename T, uint64_t D,uint64_t PartAmount>
kel::lbm::data<sch::ParticleGroup<T, D, PartAmount, coll::Spheroid<T>>> create_spheroid_particle_group(
kel::lbm::data<sch::Scalar<T>> radius_p,
kel::lbm::data<sch::Scalar<T>> density_p,
const kel::lbm::data<sch::UInt64>& mask_resolution
){
+ static_assert(D >= 1u and D <= 3u, "Dimensions only supported for Dim 1,2 & 3.");
+ static_assert(PartAmount > 0u, "A group needs at least one particle");
+
kel::lbm::data<sch::ParticleGroup<T,D,PartAmount,coll::Spheroid<T>>> part;
+ // The group keeps the shape prototype; the particles carry their own copy.
auto& rad_s = part.template get<"collision">().at({0u}).template get<"radius">();
rad_s = radius_p;
auto& mask = part.template get<"mask">();
- auto& density = part.template get<"density">().at({{0u}});
-
- auto& total_mass = part.template get<"total_mass">().at({{0u}});
- // Paranoia
- total_mass.at({}) = {};
-
- static_assert(D >= 1u and D <= 3u, "Dimensions only supported for Dim 1,2 & 3.");
- density = density_p;
kel::lbm::data<sch::FixedArray<sch::UInt64,D>> mask_dims;
for(uint64_t i = 0u; i < D; ++i){
@@ -43,53 +47,76 @@ kel::lbm::data<sch::ParticleGroup<T, D, PartAmount, coll::Spheroid<T>>> create_s
mask = {mask_dims};
+ /**
+ * mask_step stays in LATTICE units for callers that reason in them, but
+ * the mask itself is normalized to radius 1 so one group shape serves
+ * particles of any scale. See particle/mask.hpp for the full convention.
+ */
auto& mask_step = part.template get<"mask_step">().at({{0u}});
mask_step.at({}) = dia_d / mask_resolution.template cast_to<T>();
+ /**
+ * Fill the mask with the signed distance of a unit sphere.
+ *
+ * The loop that used to be here computed an offset and a radius-squared
+ * and discarded both without ever writing a voxel, so every mask was
+ * silently all zeros and the centre of mass came out as 0/0.
+ */
auto& com = part.template get<"center_of_mass">().at({{0u}});
- // Paranoia
- for(uint64_t i = 0u; i < D; ++i){
- com.at({{i}}) = {};
- }
- kel::lbm::data<sch::UInt64> ele_ctr{0u};
-
- // Radius ^ 2
- kel::lbm::data<sch::Scalar<T>> rad_2_d;
- rad_2_d.at({}) = rad_d * rad_d;
-
- kel::lbm::data<sch::Vector<T,D>> center;
- for(uint64_t i = 0u; i < D; ++i){
- center.at({{i}}) = rad_d;
- }
-
- iterator<D>::apply([&](const auto& index){
- ++ele_ctr;
-
- kel::lbm::data<sch::Vector<T,D>> offset_index = kel::lbm::math::vectorize_data(index).template cast_to<T>() - center;
+ com = fill_mask_from_sdf<T,D>(
+ mask,
+ mask_resolution.get(),
+ [](const kel::lbm::data<sch::Vector<T,D>>& u){
+ return sdf::sphere<T,D>(u);
+ }
+ );
- auto& dpi = mask.at(index);
+ /**
+ * Analytic mass and inertia for a uniform spheroid.
+ *
+ * Taken from the closed form rather than summed off the mask: the mask is
+ * a signed distance, so a mass integral would need the ramp applied first
+ * and would only approximate what the closed form gives exactly.
+ *
+ * The 3D branch used to be empty, leaving total_mass at 0 and then
+ * dividing the centre of mass by it.
+ */
+ kel::lbm::data<sch::Scalar<T>> mass_p;
+ kel::lbm::data<sch::Scalar<T>> inertia_p;
+ {
+ constexpr typename kel::lbm::native_data_type<T>::type pi = 3.14159265358979323846;
+ auto r = rad_d.get();
+ auto rho = density_p.at({}).get();
- for(uint64_t i = 0u; i < D; ++i){
- com.at({{i}}) = com.at({{i}}) + index.at({i}).template cast_to<T>() * dpi;
+ if constexpr ( D == 1u ) {
+ mass_p.at({}).set(2.0 * r * rho);
+ // A rod has no out-of-line rotation to speak of.
+ inertia_p.at({}).set(0.0);
+ } else if constexpr ( D == 2u ) {
+ auto m = pi * r * r * rho;
+ mass_p.at({}).set(m);
+ // Disc about its centre: m r^2 / 2
+ inertia_p.at({}).set(0.5 * m * r * r);
+ } else {
+ auto m = (4.0 / 3.0) * pi * r * r * r * rho;
+ mass_p.at({}).set(m);
+ // Solid sphere: 2 m r^2 / 5
+ inertia_p.at({}).set(0.4 * m * r * r);
}
+ }
- total_mass.at({}) = total_mass.at({}) + dpi;
- },{},mask_dims);
+ auto& parts = part.template get<"particles">();
+ for(uint64_t p_i = 0u; p_i < PartAmount; ++p_i){
+ auto& pi = parts.at({p_i});
+ pi.template get<"collision">().template get<"radius">() = radius_p;
- // TODO ? Do mass properly
- if constexpr ( D == 2u ) {
- total_mass.at({}) = rad_d * rad_d * density.at({}) * 3.141592;
- }else if constexpr ( D == 3u ){
-
- }else if constexpr ( D == 1u ){
- total_mass.at({}) = rad_d * 2.0;
+ auto& rb = pi.template get<"rigid_body">();
+ rb.template get<"mass">() = mass_p;
+ rb.template get<"inertia">() = inertia_p;
+ rb.template get<"density">() = density_p;
}
- std::cout<<"Total Mass: "<<total_mass.at({}).get()<<std::endl;
- for(uint64_t i = 0u; i < D; ++i){
- com.at({{i}}) = com.at({{i}}) / total_mass.at({});
- }
return part;
}
@@ -206,22 +233,26 @@ constexpr auto handle_collision = [](
};
-template<typename T, uint64_t D, typename Collision>
-constexpr auto broadphase_collision_distance_squared = [](
- kel::lbm::data<sch::Particle<T,D>>& left,
- const kel::lbm::data<Collision>& coll_l,
- kel::lbm::data<sch::Particle<T,D>>& right,
- const kel::lbm::data<Collision>& coll_r
+/**
+ * Bounding-sphere overlap test.
+ *
+ * Radius lives on the particle now, so the collision shapes no longer have to
+ * be threaded through separately.
+ *
+ * Returns the squared centre distance alongside the verdict so a caller that
+ * goes on to a narrow phase does not recompute it.
+ */
+template<typename T, uint64_t D, typename Collision = coll::Spheroid<T>>
+constexpr auto broadphase_collision_distance_squared = []<typename PRef>(
+ const PRef& left,
+ const PRef& right
) -> std::pair<bool,kel::lbm::data<sch::Scalar<T>>>{
- auto rad_l = coll_l.template get<"radius">();
- auto rad_r = coll_r.template get<"radius">();
+ auto rad_l = left.template get<"collision">().template get<"radius">();
+ auto rad_r = right.template get<"collision">().template get<"radius">();
- auto& rb_l = left.template get<"rigid_body">();
- auto& rb_r = right.template get<"rigid_body">();
-
- auto& pos_l = rb_l.template get<"position">();
- auto& pos_r = rb_r.template get<"position">();
+ auto& pos_l = left.template get<"rigid_body">().template get<"position">();
+ auto& pos_r = right.template get<"rigid_body">().template get<"position">();
auto pos_dist = pos_l - pos_r;
@@ -229,22 +260,18 @@ constexpr auto broadphase_collision_distance_squared = [](
kel::lbm::data<sch::Scalar<T>> two;
two.at({}) = 2.0;
+ // (r_l + r_r)^2
auto rad_ab_2 = rad_l * rad_l + rad_r * rad_r + rad_r * rad_l * two;
return std::make_pair((norm_2.at({}).get() < rad_ab_2.at({}).get()), norm_2);
};
-/**
-*
-*
-*/
-template<typename T, uint64_t D, typename Collision>
-constexpr auto broadphase_collision_check = [](
- kel::lbm::data<sch::Particle<T,D>>& left,
- const kel::lbm::data<Collision>& coll_l,
- kel::lbm::data<sch::Particle<T,D>>& right,
- const kel::lbm::data<Collision>& coll_r
+
+template<typename T, uint64_t D, typename Collision = coll::Spheroid<T>>
+constexpr auto broadphase_collision_check = []<typename PRef>(
+ const PRef& left,
+ const PRef& right
) -> bool{
- return broadphase_collision_distance_squared<T,D,Collision>(left,coll_l,right,coll_r).first;
+ return broadphase_collision_distance_squared<T,D,Collision>(left,right).first;
};
template<typename T,uint64_t D, uint64_t PartAmount>
diff --git a/modules/core/c++/particle/porosity.hpp b/modules/core/c++/particle/porosity.hpp
index 0fe630d..593b15e 100644
--- a/modules/core/c++/particle/porosity.hpp
+++ b/modules/core/c++/particle/porosity.hpp
@@ -3,32 +3,53 @@
#include "common.hpp"
#include "schema.hpp"
#include "../math/n_closest.hpp"
+#include "mask.hpp"
namespace kel {
namespace lbm {
namespace por {
template<typename T>
struct ParticleSpheroid {};
+
+/**
+ * Porosity read off the group's voxel mask rather than an analytic sphere.
+ *
+ * Shape agnostic: anything that can be voxelized participates, and the fluid
+ * then sees exactly the body the contact resolution uses, because both go
+ * through the same signed distance field.
+ */
+template<typename T>
+struct ParticleVoxel {};
}
+/**
+ * Mask-based porosity.
+ *
+ * Replaces a stub that computed a distance and then returned a
+ * default-constructed value, so every caller silently got zero.
+ */
template<typename T, uint64_t D, uint64_t PC, typename Coll>
class particle_porosity {
public:
-
- static kel::lbm::data<sch::Scalar<T>> calculate(const kel::lbm::data<sch::ParticleGroup<T,D,PC,Coll>>& part_group, uint64_t p_i, const kel::lbm::data<sch::Vector<T,D>>& lbm_pos){
+ template<typename GroupRef>
+ static kel::lbm::data<sch::Scalar<T>> calculate(
+ const GroupRef& part_group,
+ uint64_t p_i,
+ const kel::lbm::data<sch::Vector<T,D>>& lbm_pos,
+ kel::lbm::data<sch::Scalar<T>> eps
+ ){
auto& mask = part_group.template get<"mask">();
+ auto& part_i = part_group.template get<"particles">().at({p_i});
- auto& particles = part_group.template get<"particles">();
- auto& part_i = particles.at({p_i});
-
- auto& part_i_rb = part_i.template get<"rigid_body">();
- auto& pirb = part_i_rb.template get<"position">();
+ const uint64_t resolution = mask.get_dims().at({0u}).get();
- auto dist = lbm_pos - pirb;
+ auto sdf = mask_signed_distance<T,D>(part_group,part_i,lbm_pos,resolution);
+ auto solid = solid_fraction_from_sdf<T>(sdf,eps.at({}).get());
- // index 0 is at
-
- return {};
+ // Convention: 1 = fluid, 0 = solid, matching the analytic path.
+ kel::lbm::data<sch::Scalar<T>> por;
+ por.at({}).set(1 - solid);
+ return por;
}
};
@@ -85,8 +106,7 @@ public:
kel::lbm::data<sch::Scalar<T>> dist_len = kel::lbm::math::dot(dist,dist);
dist_len.at({}).set(std::sqrt(dist_len.at({}).get()));
-
- auto& coll = part_group.template get<"collision">().at({});
+ auto& coll = pi.template get<"collision">();
const kel::lbm::data<sch::Scalar<T>>& rad_d = coll.template get<"radius">();
const auto& eps = part_group.template get<"epsilon">().at({});
// Move this somewhere
diff --git a/modules/core/c++/particle/schema.hpp b/modules/core/c++/particle/schema.hpp
index 40033cd..fe7a33c 100644
--- a/modules/core/c++/particle/schema.hpp
+++ b/modules/core/c++/particle/schema.hpp
@@ -30,6 +30,19 @@ template<typename T>
struct rotation_type_helper<T,3u> {
using Schema = Vector<T,3u>;
};
+
+/**
+ * Moment of inertia.
+ *
+ * A scalar is exact in 2D, where rotation is about the single out-of-plane
+ * axis. In 3D it is only correct for isotropic bodies -- anything else needs
+ * a body-frame tensor plus the gyroscopic term. The angular DEM path
+ * static_asserts on D == 2u so 3D fails loudly rather than silently wrong.
+ */
+template<typename T,uint64_t D>
+struct inertia_type_helper {
+ using Schema = Scalar<T>;
+};
}
template<typename T, uint64_t D>
@@ -40,27 +53,52 @@ using ParticleRigidBody = Struct<
Member<typename impl::rotation_type_helper<T,D>::Schema, "rotation_old">,
Member<Vector<T,D>, "acceleration">,
- Member<typename impl::rotation_type_helper<T,D>::Schema, "angular_acceleration">
+ Member<typename impl::rotation_type_helper<T,D>::Schema, "angular_acceleration">,
+
+ /**
+ * Accumulators, zeroed at the start of every step.
+ *
+ * Every contributor -- fluid coupling, particle contact, body forces --
+ * adds into these; a single integrate pass then turns them into
+ * acceleration. Writing acceleration directly, as the fluid components
+ * used to, means the last writer silently wins.
+ */
+ Member<Vector<T,D>, "force">,
+ Member<typename impl::rotation_type_helper<T,D>::Schema, "torque">,
+
+ /**
+ * Inertial properties, per particle rather than per group, so a group can
+ * hold particles of differing size and density.
+ */
+ Member<Scalar<T>, "mass">,
+ Member<typename impl::inertia_type_helper<T,D>::Schema, "inertia">,
+ Member<Scalar<T>, "density">
>;
-template<typename T, uint64_t D>
+/**
+ * CollisionType is defaulted so the plain `Particle<T,D>` spelling used by the
+ * integrator and the tests keeps working.
+ */
+template<typename T, uint64_t D, typename CollisionType = coll::Spheroid<T>>
using Particle = Struct<
- Member<ParticleRigidBody<T,D>, "rigid_body">
- // Problem is that dynamic data would two layered
- // Member<Array<Float64,D>, "mask">,
+ Member<ParticleRigidBody<T,D>, "rigid_body">,
+ Member<typename CollisionType::Schema, "collision">
>;
+/**
+ * A group is one shape shared by many particles: the voxel mask and its
+ * sampling parameters describe the shape, the particles carry the transform
+ * and the dynamics. Multiple groups give multiple shapes.
+ */
template<typename T, uint64_t D, uint64_t PartAmount, typename CollisionType = coll::Spheroid<T>>
using ParticleGroup = Struct<
Member<Array<T,D>, "mask">,
Member<FixedArray<typename CollisionType::Schema,1u>, "collision">,
Member<FixedArray<Scalar<T>,1u>, "epsilon">,
Member<FixedArray<Scalar<T>,1u>, "mask_step">,
- Member<FixedArray<Scalar<T>,1u>, "density">,
Member<FixedArray<Vector<T,D>,1u>, "center_of_mass">,
- Member<FixedArray<Scalar<T>,1u>, "total_mass">,
- Member<FixedArray<Particle<T,D>,PartAmount>, "particles">
+ Member<FixedArray<Particle<T,D,CollisionType>,PartAmount>, "particles">
>;
}
}
diff --git a/modules/core/c++/particle/voxel_narrow.hpp b/modules/core/c++/particle/voxel_narrow.hpp
new file mode 100644
index 0000000..68a28e3
--- /dev/null
+++ b/modules/core/c++/particle/voxel_narrow.hpp
@@ -0,0 +1,262 @@
+#pragma once
+
+#include <cmath>
+
+#include "common.hpp"
+#include "schema.hpp"
+#include "mask.hpp"
+#include "aabb.hpp"
+#include "contact.hpp"
+
+namespace kel {
+namespace lbm {
+
+/**
+ * Voxel narrow phase.
+ *
+ * Resolves a contact from the overlap of two bodies' signed distance fields
+ * rather than from an analytic shape test, so anything that can be voxelized
+ * participates -- spheres, cubes, whatever the mask holds.
+ *
+ * Why it iterates the LATTICE, not either particle's voxel grid
+ * ------------------------------------------------------------
+ * Two reasons, and the second is the important one:
+ *
+ * - Cost. Sweeping one body's R^D voxels is hopeless at useful resolutions.
+ * The intersection of the two integer lattice bounding boxes is tiny for
+ * near-touching bodies, which is the only case that matters.
+ *
+ * - Symmetry. Both owners of a pair evaluate it independently and neither
+ * writes the other, so the two halves must come out exactly equal and
+ * opposite or every contact leaks momentum. Sampling on a particle-local
+ * grid makes the sample points depend on WHICH particle you started from.
+ * The lattice is common to both, so with a canonical (lo,hi) ordering both
+ * work items visit identical points in identical order and the results are
+ * bitwise identical.
+ */
+
+namespace impl {
+/**
+ * Gradient of the signed distance at a global point, by central differences.
+ *
+ * Taken in global coordinates directly, so no rotation of the result is
+ * needed -- the field is already expressed there.
+ */
+template<typename T, uint64_t D, typename GroupRef, typename PRef>
+kel::lbm::data<sch::Vector<T,D>> sdf_gradient(
+ const GroupRef& pg,
+ const PRef& p,
+ const kel::lbm::data<sch::Vector<T,D>>& x,
+ uint64_t resolution,
+ typename kel::lbm::native_data_type<T>::type h
+){
+ kel::lbm::data<sch::Vector<T,D>> g;
+
+ for(uint64_t i{0u}; i < D; ++i){
+ auto lo = x;
+ auto hi = x;
+ lo.at({{i}}).set(x.at({{i}}).get() - h);
+ hi.at({{i}}).set(x.at({{i}}).get() + h);
+
+ auto d_lo = mask_signed_distance<T,D>(pg,p,lo,resolution);
+ auto d_hi = mask_signed_distance<T,D>(pg,p,hi,resolution);
+
+ g.at({{i}}).set((d_hi - d_lo) / (2 * h));
+ }
+
+ return g;
+}
+}
+
+/**
+ * Contact between two bodies of the same group, from their voxel overlap.
+ *
+ * `lo` and `hi` must be passed in the caller's canonical order. `normal`
+ * points from hi toward lo, matching the analytic narrow phase so the force
+ * law downstream is unchanged.
+ */
+template<typename T, uint64_t D, typename GroupRef, typename PRef>
+bool voxel_contact(
+ const GroupRef& pg,
+ const PRef& lo,
+ const PRef& hi,
+ const kel::lbm::data<sch::FixedArray<sch::UInt64,D>>& extent,
+ kel::lbm::data<sch::Scalar<T>> eps,
+ kel::lbm::data<sch::ContactManifold<T,D>>& out
+){
+ using NT = typename kel::lbm::native_data_type<T>::type;
+
+ auto& mask = pg.template get<"mask">();
+ const uint64_t resolution = mask.get_dims().at({0u}).get();
+
+ auto& pos_lo = lo.template get<"rigid_body">().template get<"position">();
+ auto& pos_hi = hi.template get<"rigid_body">().template get<"position">();
+ auto r_lo = lo.template get<"collision">().template get<"radius">().at({}).get();
+ auto r_hi = hi.template get<"collision">().template get<"radius">().at({}).get();
+
+ /**
+ * Intersection of the two bounding boxes, clamped to the lattice. Built
+ * from the bounding radii, which the normalized mask guarantees are a
+ * true bound -- so a non-empty overlap can never be missed here.
+ */
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> start, stop;
+ for(uint64_t i{0u}; i < D; ++i){
+ auto a_lo = pos_lo.at({{i}}).get() - r_lo;
+ auto a_hi = pos_hi.at({{i}}).get() - r_hi;
+ auto a = (a_lo > a_hi) ? a_lo : a_hi;
+
+ auto b_lo = pos_lo.at({{i}}).get() + r_lo;
+ auto b_hi = pos_hi.at({{i}}).get() + r_hi;
+ auto b = (b_lo < b_hi) ? b_lo : b_hi;
+
+ if(a < 0){ a = 0; }
+ int64_t ai = static_cast<int64_t>(std::floor(a));
+ int64_t bi = static_cast<int64_t>(std::ceil(b)) + 1;
+
+ auto e = static_cast<int64_t>(extent.at({i}).get());
+ if(ai < 0){ ai = 0; }
+ if(bi > e){ bi = e; }
+ if(bi <= ai){
+ return false;
+ }
+
+ start.at({i}).set(static_cast<uint64_t>(ai));
+ stop.at({i}).set(static_cast<uint64_t>(bi));
+ }
+
+ NT volume = 0;
+ kel::lbm::data<sch::Vector<T,D>> centroid;
+ kel::lbm::data<sch::Vector<T,D>> grad_sum;
+ for(uint64_t i{0u}; i < D; ++i){
+ centroid.at({{i}}).set(0);
+ grad_sum.at({{i}}).set(0);
+ }
+
+ const NT eps_v = eps.at({}).get();
+ // One lattice unit is the natural differencing width here.
+ const NT h = 0.5;
+
+ iterator<D>::apply([&](const auto& cell){
+ kel::lbm::data<sch::Vector<T,D>> x;
+ for(uint64_t i{0u}; i < D; ++i){
+ x.at({{i}}).set(static_cast<NT>(cell.at({i}).get()));
+ }
+
+ auto d_lo = mask_signed_distance<T,D>(pg,lo,x,resolution);
+ auto s_lo = solid_fraction_from_sdf<T>(d_lo,eps_v);
+ if(!(s_lo > 0)){
+ return;
+ }
+
+ auto d_hi = mask_signed_distance<T,D>(pg,hi,x,resolution);
+ auto s_hi = solid_fraction_from_sdf<T>(d_hi,eps_v);
+ if(!(s_hi > 0)){
+ return;
+ }
+
+ auto w = s_lo * s_hi;
+ volume += w;
+
+ for(uint64_t i{0u}; i < D; ++i){
+ centroid.at({{i}}).set(centroid.at({{i}}).get() + w * x.at({{i}}).get());
+ }
+
+ /**
+ * grad(phi_hi) - grad(phi_lo), weighted by the overlap.
+ *
+ * Antisymmetric in (lo,hi) by construction, which is what lets the
+ * two owners of the pair agree exactly. A centre-to-centre normal
+ * cannot represent face-on-face contact between boxes; this can.
+ */
+ auto g_lo = impl::sdf_gradient<T,D>(pg,lo,x,resolution,h);
+ auto g_hi = impl::sdf_gradient<T,D>(pg,hi,x,resolution,h);
+ for(uint64_t i{0u}; i < D; ++i){
+ grad_sum.at({{i}}).set(
+ grad_sum.at({{i}}).get() + w * (g_hi.at({{i}}).get() - g_lo.at({{i}}).get())
+ );
+ }
+ },start,stop);
+
+ if(!(volume > 0)){
+ return false;
+ }
+
+ for(uint64_t i{0u}; i < D; ++i){
+ centroid.at({{i}}).set(centroid.at({{i}}).get() / volume);
+ }
+
+ /**
+ * phi is negative inside, so grad(phi_hi) points out of hi. The mutual
+ * gradient therefore already points from hi toward lo.
+ */
+ auto& n = out.template get<"normal">();
+ if(!impl::safe_normalize<T,D>(grad_sum,n)){
+ kel::lbm::data<sch::Vector<T,D>> fallback;
+ for(uint64_t i{0u}; i < D; ++i){
+ fallback.at({{i}}).set(pos_lo.at({{i}}).get() - pos_hi.at({{i}}).get());
+ }
+ if(!impl::safe_normalize<T,D>(fallback,n)){
+ for(uint64_t i{0u}; i < D; ++i){
+ n.at({{i}}).set(0);
+ }
+ n.at({{0u}}).set(1);
+ }
+ }
+
+ /**
+ * Penetration as the extent of the overlap projected on the normal.
+ *
+ * Not volume^(1/D): that is dimensionally plausible but wrong in
+ * magnitude, because a lens of depth d between radii r has volume
+ * ~ r^((D-1)/2) * d^((D+1)/2), so the exponent does not come out right.
+ */
+ NT s_min = 0;
+ NT s_max = 0;
+ bool first = true;
+
+ iterator<D>::apply([&](const auto& cell){
+ kel::lbm::data<sch::Vector<T,D>> x;
+ for(uint64_t i{0u}; i < D; ++i){
+ x.at({{i}}).set(static_cast<NT>(cell.at({i}).get()));
+ }
+
+ auto d_lo = mask_signed_distance<T,D>(pg,lo,x,resolution);
+ if(!(solid_fraction_from_sdf<T>(d_lo,eps_v) > 0.5)){
+ return;
+ }
+ auto d_hi = mask_signed_distance<T,D>(pg,hi,x,resolution);
+ if(!(solid_fraction_from_sdf<T>(d_hi,eps_v) > 0.5)){
+ return;
+ }
+
+ auto s = kel::lbm::math::dot(x,n).at({}).get();
+ if(first){
+ s_min = s;
+ s_max = s;
+ first = false;
+ }else{
+ if(s < s_min){ s_min = s; }
+ if(s > s_max){ s_max = s; }
+ }
+ },start,stop);
+
+ // One lattice unit so a single-cell overlap reads as a real depth, not 0.
+ NT depth = first ? NT(1) : (s_max - s_min + NT(1));
+
+ auto cap = (r_lo < r_hi) ? r_lo : r_hi;
+ if(depth > cap){
+ depth = cap;
+ }
+
+ out.template get<"depth">().at({}).set(depth);
+
+ auto& point = out.template get<"point">();
+ for(uint64_t i{0u}; i < D; ++i){
+ point.at({{i}}).set(centroid.at({{i}}).get());
+ }
+
+ return true;
+}
+
+}
+}
diff --git a/modules/core/c++/psm.hpp b/modules/core/c++/psm.hpp
index b3a2673..19c3524 100644
--- a/modules/core/c++/psm.hpp
+++ b/modules/core/c++/psm.hpp
@@ -3,12 +3,14 @@
#include "macroscopic.hpp"
#include "component.hpp"
#include "equilibrium.hpp"
+#include "particle/integrate.hpp"
namespace kel {
namespace lbm {
namespace cmpt {
struct PsmReset {};
struct PsmOneParticle {};
+struct PsmOneParticleGather {};
struct Psm {};
}
namespace method {
@@ -91,7 +93,7 @@ public:
* PSM collision operator for LBM
*/
template<typename T, typename Descriptor, typename Encode>
-class component<T, Descriptor, cmpt::PsmOneParticle, Encode> final {
+class component<T, Descriptor, cmpt::PsmOneParticleGather, Encode> final {
private:
public:
component() = default;
@@ -140,14 +142,10 @@ void apply(
{
auto parts = pg.template get<"particles">();
-
- auto& p_coll =
- pg.template get<"collision">().at({});
+ auto& pi = parts.at(index);
auto& p_rad =
- p_coll.template get<"radius">();
-
- auto& pi = parts.at(index);
+ pi.template get<"collision">().template get<"radius">();
auto& pirb =
pi.template get<"rigid_body">();
@@ -193,7 +191,7 @@ void apply(
typename ParticleSchema::ValueType
>::calculate(
pg,
- {{0u}},
+ index,
vel_f.meta()
);
@@ -443,32 +441,43 @@ void apply(
* ------------------------------------------------------------
*/
- auto& pirb_acc =
- pirb.template get<"acceleration">();
-
- pirb_acc =
- force_p
- / pg.template get<"total_mass">().at({});
-
-
- /*
- * ------------------------------------------------------------
- * Integrate particle
- * ------------------------------------------------------------
+ /**
+ * Accumulate rather than assign, so a contact pass can add to this
+ * before cmpt::ParticleIntegrate turns the total into motion.
*/
-
- for(kel::lbm::data<sch::UInt64> i{0u};
- i < sub_steps;
- ++i){
-
- verlet_step_lambda<T,Descriptor::D>(
- pi,
- ts
- );
- }
+ auto& pirb_force = pirb.template get<"force">();
+ pirb_force = pirb_force + force_p;
}
}
};
+/**
+ * The original fused one-particle step, kept so existing call sites keep
+ * working.
+ */
+template<typename T, typename Descriptor, typename Encode>
+class component<T, Descriptor, cmpt::PsmOneParticle, Encode> final {
+public:
+ component() = default;
+
+ template<typename CellFieldSchema, typename MacroFieldSchema, typename ParticleSchema>
+ void apply(
+ const kel::lbm::data<CellFieldSchema, Encode>& field,
+ const kel::lbm::data<MacroFieldSchema, Encode>& macros,
+ const kel::lbm::data<ParticleSchema, Encode>& pg,
+ kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> index,
+ kel::lbm::data<sch::UInt64> time_step,
+ kel::lbm::data<sch::UInt64> sub_steps
+ ) const {
+ component<T,Descriptor,cmpt::ParticleForceReset,Encode> reset;
+ component<T,Descriptor,cmpt::PsmOneParticleGather,Encode> gather;
+ component<T,Descriptor,cmpt::ParticleIntegrate,Encode> integrate;
+
+ reset.apply(pg,index,time_step);
+ gather.apply(field,macros,pg,index,time_step,sub_steps);
+ integrate.apply(pg,index,time_step,sub_steps);
+ }
+};
+
}
}
diff --git a/modules/core/tests/cell_list.cpp b/modules/core/tests/cell_list.cpp
new file mode 100644
index 0000000..00b260c
--- /dev/null
+++ b/modules/core/tests/cell_list.cpp
@@ -0,0 +1,197 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/cell_list.hpp"
+#include "../c++/particle/couple.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 2u;
+constexpr uint64_t Cap = 8u;
+
+template<uint64_t PC>
+auto make_group(double radius){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(1.0);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,PC>(r,d,{4u});
+}
+
+template<typename G>
+void place(G& g, uint64_t i, double x, double y){
+ auto& pos = g.template get<"particles">().at({i})
+ .template get<"rigid_body">().template get<"position">();
+ pos.at({{0u}}).set(x);
+ pos.at({{1u}}).set(y);
+}
+
+SAW_TEST("CellList / bins and finds particles"){
+ using namespace kel;
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,32u}};
+ auto cl = (lbm::make_cell_list<sch::T,D,Cap>)(extent, 2.0);
+
+ auto g = make_group<3u>(2.0);
+ place(g, 0u, 5.0, 5.0);
+ place(g, 1u, 6.0, 5.0); // same neighbourhood as 0
+ place(g, 2u, 50.0, 25.0); // far away
+
+ auto& parts = g.template get<"particles">();
+ (lbm::build_cell_list<sch::T,D,Cap>)(parts, cl);
+
+ SAW_EXPECT(cl.template get<"overflow">().at({0u}).get() == 0u, "no overflow expected");
+
+ // A cell next to particles 0 and 1 must see both, and not particle 2.
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> near{{5u,5u}};
+ bool saw[3] = {false,false,false};
+ (lbm::for_each_bin_candidate<sch::T,D,Cap>)(cl, near, [&](uint64_t p){ saw[p] = true; });
+
+ SAW_EXPECT(saw[0], "particle 0 must be a candidate");
+ SAW_EXPECT(saw[1], "particle 1 must be a candidate");
+ SAW_EXPECT(!saw[2], "a distant particle must be pruned");
+
+ // And the far cell sees only particle 2.
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> far{{50u,25u}};
+ bool saw2[3] = {false,false,false};
+ (lbm::for_each_bin_candidate<sch::T,D,Cap>)(cl, far, [&](uint64_t p){ saw2[p] = true; });
+ SAW_EXPECT(saw2[2], "particle 2 must be a candidate at its own cell");
+ SAW_EXPECT(!saw2[0] && !saw2[1], "distant particles must be pruned");
+}
+
+SAW_TEST("CellList / never misses a covering particle"){
+ using namespace kel;
+
+ /**
+ * The bin size rule is load bearing: bins are one diameter wide so a
+ * covering particle is always within the 3^D neighbourhood. Check it
+ * exhaustively against brute force rather than trusting the argument.
+ */
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{48u,24u}};
+ const double radius = 3.0;
+ auto cl = (lbm::make_cell_list<sch::T,D,Cap>)(extent, radius);
+
+ auto g = make_group<4u>(radius);
+ place(g, 0u, 4.0, 4.0);
+ place(g, 1u, 20.0, 12.0);
+ place(g, 2u, 21.5, 13.0);
+ place(g, 3u, 44.0, 20.0);
+
+ auto& parts = g.template get<"particles">();
+ (lbm::build_cell_list<sch::T,D,Cap>)(parts, cl);
+
+ uint64_t checked = 0u;
+ lbm::iterator<D>::apply([&](const auto& cell){
+ ++checked;
+
+ bool candidate[4] = {false,false,false,false};
+ (lbm::for_each_bin_candidate<sch::T,D,Cap>)(cl, cell, [&](uint64_t p){ candidate[p] = true; });
+
+ for(uint64_t p = 0u; p < 4u; ++p){
+ auto& pos = parts.at({p}).template get<"rigid_body">().template get<"position">();
+ double dx = static_cast<double>(cell.at({0u}).get()) - pos.at({{0u}}).get();
+ double dy = static_cast<double>(cell.at({1u}).get()) - pos.at({{1u}}).get();
+ bool covers = (dx*dx + dy*dy) <= radius*radius;
+
+ // Over-reporting is fine; missing a cover is not.
+ SAW_EXPECT(!covers || candidate[p],
+ std::string{"bin query missed particle "} + std::to_string(p));
+ }
+ },{},extent);
+
+ SAW_EXPECT(checked == 48u*24u, "expected to sweep the whole lattice");
+}
+
+SAW_TEST("CellList / overflow is reported not dropped"){
+ using namespace kel;
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{16u,16u}};
+ auto cl = (lbm::make_cell_list<sch::T,D,2u>)(extent, 2.0);
+
+ // Four particles stacked in one bin, capacity two.
+ auto g = make_group<4u>(2.0);
+ for(uint64_t i = 0u; i < 4u; ++i){
+ place(g, i, 5.0, 5.0);
+ }
+
+ auto& parts = g.template get<"particles">();
+ (lbm::build_cell_list<sch::T,D,2u>)(parts, cl);
+
+ SAW_EXPECT(cl.template get<"overflow">().at({0u}).get() == 2u,
+ std::string{"expected 2 overflows, got "}
+ + std::to_string(cl.template get<"overflow">().at({0u}).get()));
+}
+
+SAW_TEST("Couple / overlapping particles compose instead of clobbering"){
+ using namespace kel;
+
+ /**
+ * The per-particle stamp assigned porosity, so for two overlapping
+ * particles whichever work item ran last simply won. The per-cell gather
+ * multiplies the fluid fractions instead, which is the whole point of
+ * inverting the loop.
+ */
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{32u,32u}};
+ auto cl = (lbm::make_cell_list<sch::T,D,Cap>)(extent, 3.0);
+
+ auto g = make_group<2u>(3.0);
+ place(g, 0u, 15.0, 16.0);
+ place(g, 1u, 17.0, 16.0); // overlaps particle 0
+
+ auto& parts = g.template get<"particles">();
+ (lbm::build_cell_list<sch::T,D,Cap>)(parts, cl);
+
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.5);
+
+ // Deep inside both bodies: fully solid.
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> mid{{16u,16u}};
+ auto p_mid = (lbm::cell_porosity<sch::T,D,Cap>)(parts,cl,mid,eps);
+ SAW_EXPECT(p_mid.at({}).get() == 0.0,
+ std::string{"overlap region must read fully solid: "}
+ + std::to_string(p_mid.at({}).get()));
+
+ // Well outside both: fully fluid.
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> out{{2u,2u}};
+ auto p_out = (lbm::cell_porosity<sch::T,D,Cap>)(parts,cl,out,eps);
+ SAW_EXPECT(p_out.at({}).get() == 1.0,
+ std::string{"clear fluid must read 1: "} + std::to_string(p_out.at({}).get()));
+}
+
+SAW_TEST("Couple / is order independent"){
+ using namespace kel;
+
+ /**
+ * The property the per-particle scatter could not provide: the result
+ * must not depend on which particle was processed first.
+ */
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{32u,32u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.5);
+
+ auto a = make_group<2u>(3.0);
+ place(a, 0u, 15.0, 16.0);
+ place(a, 1u, 17.0, 16.0);
+
+ auto b = make_group<2u>(3.0);
+ place(b, 0u, 17.0, 16.0); // same pair, swapped order
+ place(b, 1u, 15.0, 16.0);
+
+ auto cl_a = (lbm::make_cell_list<sch::T,D,Cap>)(extent, 3.0);
+ auto cl_b = (lbm::make_cell_list<sch::T,D,Cap>)(extent, 3.0);
+ (lbm::build_cell_list<sch::T,D,Cap>)(a.template get<"particles">(), cl_a);
+ (lbm::build_cell_list<sch::T,D,Cap>)(b.template get<"particles">(), cl_b);
+
+ lbm::iterator<D>::apply([&](const auto& cell){
+ auto pa = (lbm::cell_porosity<sch::T,D,Cap>)(a.template get<"particles">(),cl_a,cell,eps);
+ auto pb = (lbm::cell_porosity<sch::T,D,Cap>)(b.template get<"particles">(),cl_b,cell,eps);
+ SAW_EXPECT(pa.at({}).get() == pb.at({}).get(),
+ "porosity must not depend on particle ordering");
+ },{{10u,10u}},{{24u,24u}});
+}
+}
diff --git a/modules/core/tests/component_instantiation.cpp b/modules/core/tests/component_instantiation.cpp
new file mode 100644
index 0000000..94d0536
--- /dev/null
+++ b/modules/core/tests/component_instantiation.cpp
@@ -0,0 +1,199 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/integrate.hpp"
+#include "../c++/particle/contact.hpp"
+#include "../c++/abstract/data_ptr.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+struct TestDesc { static constexpr uint64_t D = 2u; static constexpr uint64_t Q = 9u; };
+constexpr uint64_t D = 2u;
+
+/**
+ * The components are what a step function actually launches, but they take
+ * their group through a borrowed view -- const handle, mutable target -- so
+ * they could not be instantiated against the honestly const-correct owning
+ * types. Templates are only checked on instantiation, so a component naming a
+ * member that does not exist stayed quiet until a real kernel compiled it.
+ * Twice, here: ParticleSchema::PartAmount and CellListSchema::CellCapacity.
+ *
+ * With a host view carrying the same const semantics, the wrappers can be
+ * exercised directly.
+ */
+
+using GroupSch = kel::lbm::sch::ParticleGroup<sch::T,D,2u,kel::lbm::coll::Spheroid<sch::T>>;
+using GroupView = kel::lbm::data<sch::Ptr<GroupSch>, kel::lbm::enc::Native>;
+
+auto make_group(double radius){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(1.0);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,2u>(r,d,{8u});
+}
+
+template<typename G>
+void rest_at(G& g, uint64_t i, double x, double y){
+ auto& rb = g.template get<"particles">().at({i}).template get<"rigid_body">();
+ const double v[2] = {x,y};
+ for(uint64_t k = 0u; k < D; ++k){
+ rb.template get<"position">().at({{k}}).set(v[k]);
+ rb.template get<"position_old">().at({{k}}).set(v[k]);
+ }
+}
+
+SAW_TEST("Component / host view keeps device const semantics"){
+ using namespace kel;
+
+ /**
+ * The whole point: a const view must still allow writing through it, the
+ * way a device handle does.
+ */
+ auto g = make_group(2.0);
+ auto& parts = g.template get<"particles">();
+
+ const kel::lbm::data<sch::Ptr<sch::FixedArray<
+ sch::Particle<sch::T,D,lbm::coll::Spheroid<sch::T>>, 2u>>, lbm::enc::Native> view{parts};
+
+ view.at({0u}).template get<"rigid_body">()
+ .template get<"position">().at({{0u}}).set(7.0);
+
+ SAW_EXPECT(parts.at({0u}).template get<"rigid_body">()
+ .template get<"position">().at({{0u}}).get() == 7.0,
+ "a write through a const view must reach the owning data");
+
+ SAW_EXPECT(view.get_dims().at({0u}).get() == 2u,
+ "the view must report the backing extent");
+}
+
+SAW_TEST("Component / ParticleForceReset instantiates and clears"){
+ using namespace kel;
+
+ auto g = make_group(2.0);
+ auto& parts = g.template get<"particles">();
+
+ auto& rb = parts.at({0u}).template get<"rigid_body">();
+ rb.template get<"force">().at({{0u}}).set(5.0);
+ rb.template get<"torque">().at({}).set(3.0);
+
+ lbm::component<sch::T,TestDesc,lbm::cmpt::ParticleForceReset,lbm::enc::Native> reset;
+ GroupView view{g};
+ reset.apply(view,{{0u}},{0u});
+
+ SAW_EXPECT(rb.template get<"force">().at({{0u}}).get() == 0.0, "force must clear");
+ SAW_EXPECT(rb.template get<"torque">().at({}).get() == 0.0, "torque must clear");
+}
+
+SAW_TEST("Component / ParticleIntegrate instantiates and moves the body"){
+ using namespace kel;
+
+ auto g = make_group(2.0);
+ auto& parts = g.template get<"particles">();
+ rest_at(g, 0u, 0.0, 0.0);
+
+ auto& rb = parts.at({0u}).template get<"rigid_body">();
+ auto mass = rb.template get<"mass">().at({}).get();
+ rb.template get<"force">().at({{0u}}).set(mass); // unit acceleration
+
+ kel::lbm::data<sch::Vector<sch::T,D>> gravity;
+ gravity.at({{1u}}).set(-0.5);
+
+ lbm::component<sch::T,TestDesc,lbm::cmpt::ParticleIntegrate,lbm::enc::Native> integrate{gravity};
+ GroupView view{g};
+ integrate.apply(view,{{0u}},{0u},{1u});
+
+ SAW_EXPECT(std::abs(rb.template get<"acceleration">().at({{0u}}).get() - 1.0) < 1e-12,
+ "force/mass must reach acceleration");
+ SAW_EXPECT(std::abs(rb.template get<"acceleration">().at({{1u}}).get() + 0.5) < 1e-12,
+ "the body acceleration must be added in");
+ SAW_EXPECT(rb.template get<"position">().at({{0u}}).get() > 0.0, "and the body must move");
+}
+
+SAW_TEST("Component / ParticleContact instantiates and accumulates"){
+ using namespace kel;
+
+ /**
+ * This is the component that previously only compiled once a GPU kernel
+ * referenced it -- the PartAmount slip lived exactly here.
+ */
+ auto g = make_group(2.0);
+ auto& parts = g.template get<"particles">();
+
+ rest_at(g, 0u, 20.0, 16.0);
+ rest_at(g, 1u, 23.0, 16.0); // overlapping by 1
+
+ lbm::dem_params<sch::T> dem{4.0, 0.0, 0.0, 0.0};
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,32u}};
+
+ lbm::component<sch::T,TestDesc,lbm::cmpt::ParticleContact,lbm::enc::Native> contact{dem,extent};
+
+ for(uint64_t i = 0u; i < 2u; ++i){
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({i}));
+ }
+ GroupView view{g};
+ contact.apply(view,{{0u}},{0u},{1u});
+ contact.apply(view,{{1u}},{0u},{1u});
+
+ auto f0 = parts.at({0u}).template get<"rigid_body">().template get<"force">().at({{0u}}).get();
+ auto f1 = parts.at({1u}).template get<"rigid_body">().template get<"force">().at({{0u}}).get();
+
+ // Undamped, overlap 1, k = 4, so the pair pushes apart with magnitude 4.
+ SAW_EXPECT(std::abs(f0 + 4.0) < 1e-12,
+ std::string{"particle 0 should be pushed -x by k*delta: "} + std::to_string(f0));
+ SAW_EXPECT(f0 == -f1, "and the halves must cancel exactly");
+}
+
+SAW_TEST("Component / wall contact runs through the component too"){
+ using namespace kel;
+
+ auto g = make_group(2.0);
+ auto& parts = g.template get<"particles">();
+
+ // Against the low x wall, far from the other particle.
+ rest_at(g, 0u, 1.5, 16.0);
+ rest_at(g, 1u, 50.0, 16.0);
+
+ const double k_n = 6.0;
+ lbm::dem_params<sch::T> dem{k_n, 0.0, 0.0, 0.0};
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,32u}};
+
+ lbm::component<sch::T,TestDesc,lbm::cmpt::ParticleContact,lbm::enc::Native> contact{dem,extent};
+
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({0u}));
+ GroupView view{g};
+ contact.apply(view,{{0u}},{0u},{1u});
+
+ auto fx = parts.at({0u}).template get<"rigid_body">().template get<"force">().at({{0u}}).get();
+ SAW_EXPECT(std::abs(fx - k_n * 0.5) < 1e-12,
+ std::string{"wall should push +x by k*depth: "} + std::to_string(fx));
+}
+
+SAW_TEST("Component / contact without walls leaves the wall term out"){
+ using namespace kel;
+
+ // The two-argument constructor opts out of wall contact; a particle
+ // overlapping a wall must then feel nothing from it.
+ auto g = make_group(2.0);
+ auto& parts = g.template get<"particles">();
+ rest_at(g, 0u, 1.5, 16.0);
+ rest_at(g, 1u, 50.0, 16.0);
+
+ lbm::dem_params<sch::T> dem{6.0, 0.0, 0.0, 0.0};
+ lbm::component<sch::T,TestDesc,lbm::cmpt::ParticleContact,lbm::enc::Native> contact{dem};
+
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({0u}));
+ GroupView view{g};
+ contact.apply(view,{{0u}},{0u},{1u});
+
+ SAW_EXPECT(parts.at({0u}).template get<"rigid_body">()
+ .template get<"force">().at({{0u}}).get() == 0.0,
+ "no walls configured means no wall force");
+}
+}
diff --git a/modules/core/tests/contact_dynamics.cpp b/modules/core/tests/contact_dynamics.cpp
new file mode 100644
index 0000000..b6545b9
--- /dev/null
+++ b/modules/core/tests/contact_dynamics.cpp
@@ -0,0 +1,272 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/integrate.hpp"
+#include "../c++/particle/contact.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 2u;
+
+template<uint64_t PC>
+auto make_group(double radius, double density){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(density);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,PC>(r,d,{8u});
+}
+
+template<typename G>
+void set_state(G& g, uint64_t i, double x, double y, double vx, double vy){
+ auto& rb = g.template get<"particles">().at({i}).template get<"rigid_body">();
+ rb.template get<"position">().at({{0u}}).set(x);
+ rb.template get<"position">().at({{1u}}).set(y);
+ // Position-Verlet carries velocity implicitly in the position pair.
+ rb.template get<"position_old">().at({{0u}}).set(x - vx);
+ rb.template get<"position_old">().at({{1u}}).set(y - vy);
+}
+
+template<typename G>
+double vel_x(G& g, uint64_t i){
+ auto& rb = g.template get<"particles">().at({i}).template get<"rigid_body">();
+ return rb.template get<"position">().at({{0u}}).get()
+ - rb.template get<"position_old">().at({{0u}}).get();
+}
+
+/**
+ * One full step of the pipeline for every particle: clear, accumulate
+ * contacts, integrate.
+ */
+template<typename G>
+void step_all(G& g, uint64_t n, const kel::lbm::dem_params<sch::T>& dem){
+ using namespace kel;
+ auto& parts = g.template get<"particles">();
+ for(uint64_t i = 0u; i < n; ++i){
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({i}));
+ }
+ for(uint64_t i = 0u; i < n; ++i){
+ (lbm::accumulate_particle_contacts<sch::T,D>)(parts, i, dem, {1u});
+ }
+ for(uint64_t i = 0u; i < n; ++i){
+ (lbm::integrate_particle<sch::T,D>)(parts.at({i}), {}, {1u});
+ }
+}
+
+SAW_TEST("Dynamics / head-on collision reverses both bodies"){
+ using namespace kel;
+
+ auto g = make_group<2u>(2.0, 1.0);
+ // Approaching, just touching.
+ set_state(g, 0u, 0.0, 0.0, 0.05, 0.0);
+ set_state(g, 1u, 4.0, 0.0, -0.05, 0.0);
+
+ // Stiff enough to turn them around inside the window, lightly damped.
+ lbm::dem_params<sch::T> dem{2.0, 0.1, 0.0, 0.0};
+
+ bool reversed = false;
+ for(uint64_t step = 0u; step < 400u; ++step){
+ step_all(g, 2u, dem);
+ if(vel_x(g,0u) < 0.0 && vel_x(g,1u) > 0.0){
+ reversed = true;
+ break;
+ }
+ }
+
+ SAW_EXPECT(reversed, "an approaching pair must end up separating");
+}
+
+SAW_TEST("Dynamics / collision does not create energy"){
+ using namespace kel;
+
+ /**
+ * The dashpot can only remove energy. If the sign of the damping term or
+ * the velocity convention were wrong, a bounce would come back faster
+ * than it went in -- which is the classic way a DEM blows up slowly
+ * enough that you do not notice for a thousand steps.
+ */
+ auto g = make_group<2u>(2.0, 1.0);
+ const double v0 = 0.05;
+ set_state(g, 0u, 0.0, 0.0, v0, 0.0);
+ set_state(g, 1u, 4.0, 0.0, -v0, 0.0);
+
+ lbm::dem_params<sch::T> dem{2.0, 0.2, 0.0, 0.0};
+
+ double peak = 0.0;
+ for(uint64_t step = 0u; step < 600u; ++step){
+ step_all(g, 2u, dem);
+
+ auto s0 = std::abs(vel_x(g,0u));
+ auto s1 = std::abs(vel_x(g,1u));
+ if(s0 > peak){ peak = s0; }
+ if(s1 > peak){ peak = s1; }
+ }
+
+ SAW_EXPECT(peak <= v0 * 1.02,
+ std::string{"no body may exceed its incoming speed, peak was "}
+ + std::to_string(peak) + " against " + std::to_string(v0));
+}
+
+SAW_TEST("Dynamics / resting contact settles at the force balance"){
+ using namespace kel;
+
+ /**
+ * A body held against a wall by a constant body acceleration must come to
+ * rest where the spring balances the load, at an overlap of m*g/k.
+ *
+ * Note this needs confinement to mean anything: two FREE bodies pushed
+ * apart just separate and coast, so there is no equilibrium to find.
+ */
+ auto g = make_group<1u>(2.0, 1.0);
+ auto& parts = g.template get<"particles">();
+ auto& rb = parts.at({0u}).template get<"rigid_body">();
+
+ const double mass = rb.template get<"mass">().at({}).get();
+ const double k_n = 1.0;
+ const double gravity = 0.0005;
+
+ // Start just touching the low x wall, at rest.
+ set_state(g, 0u, 2.0, 16.0, 0.0, 0.0);
+
+ lbm::dem_params<sch::T> dem{k_n, 0.8, 0.0, 0.0};
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,32u}};
+
+ // Gravity pointing at the wall, as a body acceleration.
+ kel::lbm::data<sch::Vector<sch::T,D>> body_acc;
+ body_acc.at({{0u}}).set(-gravity);
+ body_acc.at({{1u}}).set(0.0);
+
+ auto x_of = [&](){
+ return rb.template get<"position">().at({{0u}}).get();
+ };
+
+ for(uint64_t step = 0u; step < 4000u; ++step){
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({0u}));
+ (lbm::accumulate_box_wall_contacts<sch::T,D>)(parts.at({0u}), extent, dem, {1u});
+ (lbm::integrate_particle<sch::T,D>)(parts.at({0u}), body_acc, {1u});
+ }
+
+ auto settled = x_of();
+ auto expect_overlap = mass * gravity / k_n;
+ auto got_overlap = 2.0 - settled;
+
+ SAW_EXPECT(std::isfinite(settled), "must stay finite");
+ SAW_EXPECT(std::abs(got_overlap - expect_overlap) < 0.1 * expect_overlap,
+ std::string{"expected overlap m*g/k = "} + std::to_string(expect_overlap)
+ + " got " + std::to_string(got_overlap));
+
+ // And it must actually be at rest, not still travelling.
+ auto speed = std::abs(x_of() - rb.template get<"position_old">().at({{0u}}).get());
+ SAW_EXPECT(speed < 1e-4,
+ std::string{"should have come to rest, residual speed "} + std::to_string(speed));
+}
+
+SAW_TEST("Dynamics / three body momentum is conserved"){
+ using namespace kel;
+
+ /**
+ * Two bodies cancelling is weak evidence -- a sign error can cancel
+ * pairwise and still be wrong once a particle has two neighbours at once.
+ */
+ auto g = make_group<3u>(2.0, 1.0);
+ set_state(g, 0u, 0.0, 0.0, 0.03, 0.01);
+ set_state(g, 1u, 3.5, 0.0, -0.01, 0.02);
+ set_state(g, 2u, 7.0, 0.3, 0.00, -0.02);
+
+ lbm::dem_params<sch::T> dem{5.0, 0.3, 2.0, 0.4};
+
+ auto& parts = g.template get<"particles">();
+ for(uint64_t i = 0u; i < 3u; ++i){
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({i}));
+ }
+ for(uint64_t i = 0u; i < 3u; ++i){
+ (lbm::accumulate_particle_contacts<sch::T,D>)(parts, i, dem, {1u});
+ }
+
+ // The middle body touches both neighbours, so this is the case that
+ // pairwise cancellation alone would not catch.
+ for(uint64_t k = 0u; k < D; ++k){
+ double sum = 0.0;
+ for(uint64_t i = 0u; i < 3u; ++i){
+ sum += parts.at({i}).template get<"rigid_body">()
+ .template get<"force">().at({{k}}).get();
+ }
+ SAW_EXPECT(std::abs(sum) < 1e-12,
+ std::string{"net force in component "} + std::to_string(k)
+ + " should vanish: " + std::to_string(sum));
+ }
+
+ // And the middle body must actually be feeling both sides.
+ auto f1 = parts.at({1u}).template get<"rigid_body">().template get<"force">().at({{0u}}).get();
+ SAW_EXPECT(std::abs(f1) > 0.0, "the middle body must be loaded from both sides");
+}
+
+SAW_TEST("Dynamics / wall stops an incoming body"){
+ using namespace kel;
+
+ auto g = make_group<1u>(2.0, 1.0);
+ // Heading into the low x wall.
+ set_state(g, 0u, 2.5, 16.0, -0.05, 0.0);
+
+ lbm::dem_params<sch::T> dem{2.0, 0.2, 0.0, 0.0};
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,32u}};
+
+ auto& parts = g.template get<"particles">();
+ double deepest = 2.5;
+
+ for(uint64_t step = 0u; step < 400u; ++step){
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({0u}));
+ (lbm::accumulate_box_wall_contacts<sch::T,D>)(parts.at({0u}), extent, dem, {1u});
+ (lbm::integrate_particle<sch::T,D>)(parts.at({0u}), {}, {1u});
+
+ auto x = parts.at({0u}).template get<"rigid_body">()
+ .template get<"position">().at({{0u}}).get();
+ if(x < deepest){ deepest = x; }
+ }
+
+ auto final_x = parts.at({0u}).template get<"rigid_body">()
+ .template get<"position">().at({{0u}}).get();
+
+ SAW_EXPECT(deepest > 0.0,
+ std::string{"the body must not pass through the wall, reached "}
+ + std::to_string(deepest));
+ SAW_EXPECT(final_x > deepest,
+ "and it must be pushed back out again");
+}
+
+SAW_TEST("Dynamics / sub steps do not change the trajectory"){
+ using namespace kel;
+
+ /**
+ * sub_steps subdivides one unit of time, so the displacement under a
+ * constant acceleration should come out the same regardless of how many
+ * pieces it is cut into. A mis-scaled dt would show up here immediately.
+ */
+ auto run = [&](uint64_t steps){
+ auto g = make_group<1u>(2.0, 1.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+ rb.template get<"force">().at({{0u}}).set(rb.template get<"mass">().at({}).get());
+ (lbm::integrate_particle<sch::T,D>)(p, {}, {steps});
+ return rb.template get<"position">().at({{0u}}).get();
+ };
+
+ auto one = run(1u);
+ auto four = run(4u);
+ auto sixteen = run(16u);
+
+ SAW_EXPECT(one > 0.0, "must move at all");
+ // Verlet from rest: total displacement converges as the step shrinks.
+ SAW_EXPECT(std::abs(four - one) / one < 0.5,
+ std::string{"1 vs 4 sub steps diverged: "} + std::to_string(one)
+ + " vs " + std::to_string(four));
+ SAW_EXPECT(std::abs(sixteen - four) < std::abs(four - one),
+ "refining the sub step should be converging, not drifting");
+}
+}
diff --git a/modules/core/tests/mask.cpp b/modules/core/tests/mask.cpp
new file mode 100644
index 0000000..dfb5ef8
--- /dev/null
+++ b/modules/core/tests/mask.cpp
@@ -0,0 +1,238 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/mask.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 2u;
+
+auto make_one(double radius){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(1.0);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,1u>(r,d,{32u});
+}
+
+SAW_TEST("Mask / is actually filled"){
+ using namespace kel;
+
+ /**
+ * The voxelizer used to discard everything it computed, leaving every
+ * voxel at zero. A mask of all zeros reads as "surface everywhere", which
+ * is indistinguishable from a working mask until you look at a value.
+ */
+ auto g = make_one(4.0);
+ auto& mask = g.template get<"mask">();
+
+ bool any_negative = false;
+ bool any_positive = false;
+ lbm::iterator<D>::apply([&](const auto& k){
+ auto v = mask.at(k).get();
+ if(v < -0.1){ any_negative = true; }
+ if(v > 0.1){ any_positive = true; }
+ },{},mask.get_dims());
+
+ SAW_EXPECT(any_negative, "mask must have interior (negative) voxels");
+ SAW_EXPECT(any_positive, "mask must have exterior (positive) voxels");
+}
+
+SAW_TEST("Mask / stores a signed distance"){
+ using namespace kel;
+
+ auto g = make_one(4.0);
+ auto& mask = g.template get<"mask">();
+ const uint64_t R = 32u;
+
+ // Centre of a unit sphere mask: distance -1.
+ kel::lbm::data<sch::Vector<sch::T,D>> centre;
+ centre.at({{0u}}).set(0.0);
+ centre.at({{1u}}).set(0.0);
+ auto d_centre = (lbm::mask_sample_local<sch::T,D>)(mask,centre,R);
+ SAW_EXPECT(std::abs(d_centre + 1.0) < 0.05,
+ std::string{"centre distance should be -1: "} + std::to_string(d_centre));
+
+ // On the surface along +x: distance 0.
+ kel::lbm::data<sch::Vector<sch::T,D>> surf;
+ surf.at({{0u}}).set(1.0);
+ surf.at({{1u}}).set(0.0);
+ auto d_surf = (lbm::mask_sample_local<sch::T,D>)(mask,surf,R);
+ SAW_EXPECT(std::abs(d_surf) < 0.05,
+ std::string{"surface distance should be 0: "} + std::to_string(d_surf));
+
+ // Halfway out: distance -0.5.
+ kel::lbm::data<sch::Vector<sch::T,D>> half;
+ half.at({{0u}}).set(0.5);
+ half.at({{1u}}).set(0.0);
+ auto d_half = (lbm::mask_sample_local<sch::T,D>)(mask,half,R);
+ SAW_EXPECT(std::abs(d_half + 0.5) < 0.05,
+ std::string{"half radius distance should be -0.5: "} + std::to_string(d_half));
+}
+
+SAW_TEST("Mask / centre of mass is the body centre"){
+ using namespace kel;
+
+ // A sphere is symmetric, so its centroid must sit at the origin of the
+ // local frame. The old code divided by a zero mass and produced 0/0.
+ auto g = make_one(4.0);
+ auto& com = g.template get<"center_of_mass">().at({0u});
+
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(std::isfinite(com.at({{i}}).get()), "com must be finite");
+ SAW_EXPECT(std::abs(com.at({{i}}).get()) < 0.02,
+ std::string{"com component "} + std::to_string(i) + ": "
+ + std::to_string(com.at({{i}}).get()));
+ }
+}
+
+SAW_TEST("Mask / transform round trips"){
+ using namespace kel;
+
+ auto g = make_one(3.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+ rb.template get<"position">().at({{0u}}).set(20.0);
+ rb.template get<"position">().at({{1u}}).set(11.0);
+ rb.template get<"rotation">().at({}).set(0.7);
+
+ auto& com = g.template get<"center_of_mass">().at({0u});
+
+ const double pts[4][2] = {{0.0,0.0},{0.5,-0.25},{-0.9,0.1},{1.0,0.0}};
+ for(uint64_t c = 0u; c < 4u; ++c){
+ kel::lbm::data<sch::Vector<sch::T,D>> u;
+ u.at({{0u}}).set(pts[c][0]);
+ u.at({{1u}}).set(pts[c][1]);
+
+ auto x = (lbm::mask_local_to_global<sch::T,D>)(u,p,com);
+ auto back = (lbm::mask_global_to_local<sch::T,D>)(x,p,com);
+
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(std::abs(back.at({{i}}).get() - u.at({{i}}).get()) < 1e-12,
+ std::string{"round trip failed at point "} + std::to_string(c));
+ }
+ }
+}
+
+SAW_TEST("Mask / scale maps to physical radius"){
+ using namespace kel;
+
+ /**
+ * The mask is normalized, so the physical bounding radius is exactly the
+ * particle's radius. That identity is what lets the bounding-sphere broad
+ * phase and the voxel narrow phase agree by construction.
+ */
+ auto g = make_one(3.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+ rb.template get<"position">().at({{0u}}).set(10.0);
+ rb.template get<"position">().at({{1u}}).set(10.0);
+ rb.template get<"rotation">().at({}).set(0.0);
+
+ auto& com = g.template get<"center_of_mass">().at({0u});
+ const uint64_t R = 32u;
+
+ // Centre: distance -radius.
+ kel::lbm::data<sch::Vector<sch::T,D>> at_centre;
+ at_centre.at({{0u}}).set(10.0);
+ at_centre.at({{1u}}).set(10.0);
+ auto d0 = (lbm::mask_signed_distance<sch::T,D>)(g,p,at_centre,R);
+ SAW_EXPECT(std::abs(d0 + 3.0) < 0.2,
+ std::string{"centre should read -radius: "} + std::to_string(d0));
+
+ // Exactly one radius out: on the surface.
+ kel::lbm::data<sch::Vector<sch::T,D>> at_surface;
+ at_surface.at({{0u}}).set(13.0);
+ at_surface.at({{1u}}).set(10.0);
+ auto d1 = (lbm::mask_signed_distance<sch::T,D>)(g,p,at_surface,R);
+ SAW_EXPECT(std::abs(d1) < 0.2,
+ std::string{"one radius out should read 0: "} + std::to_string(d1));
+}
+
+SAW_TEST("Mask / solid fraction ramp"){
+ using namespace kel;
+
+ // Deep inside is fully solid, far outside fully fluid, and the ramp is
+ // monotone across the shell rather than doubling back.
+ SAW_EXPECT((lbm::solid_fraction_from_sdf<sch::T>)(-5.0, 1.5) == 1.0, "inside must be solid");
+ SAW_EXPECT((lbm::solid_fraction_from_sdf<sch::T>)( 5.0, 1.5) == 0.0, "outside must be fluid");
+
+ double prev = 1.0;
+ for(int i = 0; i <= 20; ++i){
+ double sdf = -0.75 + 1.5 * (i / 20.0);
+ double f = (lbm::solid_fraction_from_sdf<sch::T>)(sdf, 1.5);
+ SAW_EXPECT(f <= prev + 1e-12,
+ std::string{"ramp must be monotone, broke at sdf="} + std::to_string(sdf));
+ SAW_EXPECT(f >= -1e-12 && f <= 1.0 + 1e-12, "ramp must stay in [0,1]");
+ prev = f;
+ }
+}
+
+SAW_TEST("Mask / cube sdf is not a sphere"){
+ using namespace kel;
+
+ // The corner of a cube is further from the centre than its face, which is
+ // what a sphere cannot express -- the point of keeping the mask generic.
+ kel::lbm::data<sch::Vector<sch::T,D>> face;
+ face.at({{0u}}).set(1.0);
+ face.at({{1u}}).set(0.0);
+
+ kel::lbm::data<sch::Vector<sch::T,D>> corner;
+ corner.at({{0u}}).set(1.0);
+ corner.at({{1u}}).set(1.0);
+
+ SAW_EXPECT(std::abs((lbm::sdf::cube<sch::T,D>)(face)) < 1e-12, "face is on the surface");
+ SAW_EXPECT(std::abs((lbm::sdf::cube<sch::T,D>)(corner)) < 1e-12, "corner is on the surface too");
+ SAW_EXPECT((lbm::sdf::sphere<sch::T,D>)(corner) > 0.4, "but a sphere puts the corner outside");
+}
+
+SAW_TEST("Mask / porosity agrees with the analytic sphere"){
+ using namespace kel;
+
+ /**
+ * The mask path and the analytic path describe the same body, so they
+ * must agree to within the voxel pitch. This is the check that the whole
+ * "one field serves both consumers" idea rests on.
+ */
+ auto g = make_one(5.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+ rb.template get<"position">().at({{0u}}).set(16.0);
+ rb.template get<"position">().at({{1u}}).set(16.0);
+ rb.template get<"rotation">().at({}).set(0.0);
+
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.5);
+ auto rad = p.template get<"collision">().template get<"radius">();
+
+ double worst = 0.0;
+ for(int i = 0; i <= 40; ++i){
+ double x = 16.0 + 10.0 * (i / 40.0) - 5.0;
+
+ kel::lbm::data<sch::Vector<sch::T,D>> pos;
+ pos.at({{0u}}).set(x);
+ pos.at({{1u}}).set(16.0);
+
+ kel::lbm::data<sch::Vector<sch::T,D>> rel;
+ rel.at({{0u}}).set(x - 16.0);
+ rel.at({{1u}}).set(0.0);
+
+ auto analytic = (lbm::particle_porosity<sch::T,D,1u,lbm::por::ParticleSpheroid<sch::T>>::calculate)(rel,rad,eps);
+ auto voxel = (lbm::particle_porosity<sch::T,D,1u,lbm::por::ParticleVoxel<sch::T>>::calculate)(g,0u,pos,eps);
+
+ auto diff = std::abs(analytic.at({}).get() - voxel.at({}).get());
+ if(diff > worst){ worst = diff; }
+ }
+
+ // Voxel pitch is 2*5/32 ~ 0.3 lattice units, and the ramp spans 1.5, so
+ // the two profiles can differ by roughly a fifth of the ramp.
+ SAW_EXPECT(worst < 0.35,
+ std::string{"mask and analytic porosity disagree by "} + std::to_string(worst));
+}
+}
diff --git a/modules/core/tests/particle_3d.cpp b/modules/core/tests/particle_3d.cpp
new file mode 100644
index 0000000..8c3e579
--- /dev/null
+++ b/modules/core/tests/particle_3d.cpp
@@ -0,0 +1,265 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/integrate.hpp"
+#include "../c++/particle/contact.hpp"
+#include "../c++/particle/mask.hpp"
+#include "../c++/particle/cell_list.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 3u;
+
+/**
+ * Nothing anywhere else in the suite instantiates D = 3, and templates are only
+ * checked when instantiated -- which is how two "member does not exist" bugs
+ * already slipped past the host tests and were only caught by a GPU build.
+ * These exercise the 3D specializations so they cannot rot silently.
+ */
+
+template<uint64_t PC>
+auto make_group(double radius, double density, uint64_t res = 12u){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(density);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,PC>(r,d,{res});
+}
+
+template<typename G>
+void place(G& g, uint64_t i, double x, double y, double z){
+ auto& rb = g.template get<"particles">().at({i}).template get<"rigid_body">();
+ auto& pos = rb.template get<"position">();
+ auto& old = rb.template get<"position_old">();
+ const double v[3] = {x,y,z};
+ for(uint64_t i2 = 0u; i2 < 3u; ++i2){
+ pos.at({{i2}}).set(v[i2]);
+ // At rest. position_old defaults to zero, which would otherwise read
+ // as an enormous separating velocity and damp the contact to nothing.
+ old.at({{i2}}).set(v[i2]);
+ }
+}
+
+SAW_TEST("3D / group construction fills mass and inertia"){
+ using namespace kel;
+
+ /**
+ * The 3D mass branch used to be empty, leaving total_mass at zero and then
+ * dividing the centre of mass by it.
+ */
+ const double r = 2.0;
+ const double rho = 1.5;
+ auto g = make_group<2u>(r, rho);
+
+ constexpr double pi = 3.14159265358979323846;
+ const double expect_m = (4.0/3.0) * pi * r*r*r * rho;
+ const double expect_i = 0.4 * expect_m * r * r;
+
+ for(uint64_t i = 0u; i < 2u; ++i){
+ auto& rb = g.template get<"particles">().at({i}).template get<"rigid_body">();
+
+ auto m = rb.template get<"mass">().at({}).get();
+ SAW_EXPECT(std::abs(m - expect_m) < 1e-9,
+ std::string{"3D mass should be 4/3 pi r^3 rho: "} + std::to_string(m));
+
+ auto in = rb.template get<"inertia">().at({}).get();
+ SAW_EXPECT(std::abs(in - expect_i) < 1e-9,
+ std::string{"3D inertia should be 2/5 m r^2: "} + std::to_string(in));
+ }
+
+ auto& com = g.template get<"center_of_mass">().at({0u});
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(std::isfinite(com.at({{i}}).get()),
+ "centre of mass must be finite, not 0/0");
+ SAW_EXPECT(std::abs(com.at({{i}}).get()) < 0.05,
+ std::string{"a sphere's centroid should sit at the origin, component "}
+ + std::to_string(i) + " = " + std::to_string(com.at({{i}}).get()));
+ }
+}
+
+SAW_TEST("3D / mask is filled with a signed distance"){
+ using namespace kel;
+
+ auto g = make_group<1u>(2.0, 1.0, 16u);
+ auto& mask = g.template get<"mask">();
+
+ kel::lbm::data<sch::Vector<sch::T,D>> centre;
+ for(uint64_t i = 0u; i < D; ++i){ centre.at({{i}}).set(0.0); }
+ auto d_centre = (lbm::mask_sample_local<sch::T,D>)(mask,centre,16u);
+ SAW_EXPECT(std::abs(d_centre + 1.0) < 0.12,
+ std::string{"3D centre should read -1: "} + std::to_string(d_centre));
+
+ kel::lbm::data<sch::Vector<sch::T,D>> surf;
+ surf.at({{0u}}).set(1.0);
+ surf.at({{1u}}).set(0.0);
+ surf.at({{2u}}).set(0.0);
+ auto d_surf = (lbm::mask_sample_local<sch::T,D>)(mask,surf,16u);
+ SAW_EXPECT(std::abs(d_surf) < 0.12,
+ std::string{"3D surface should read 0: "} + std::to_string(d_surf));
+}
+
+SAW_TEST("3D / Rodrigues rotation round trips"){
+ using namespace kel;
+
+ /**
+ * 3D rotation goes through Rodrigues on a rotation vector, a path with no
+ * other coverage at all.
+ */
+ auto g = make_group<1u>(3.0, 1.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+
+ place(g, 0u, 20.0, 15.0, 10.0);
+
+ // A rotation about a tilted axis, so no component is trivially preserved.
+ auto& rot = rb.template get<"rotation">();
+ rot.at({{0u}}).set(0.3);
+ rot.at({{1u}}).set(-0.5);
+ rot.at({{2u}}).set(0.9);
+
+ auto& com = g.template get<"center_of_mass">().at({0u});
+
+ const double pts[3][3] = {{1.0,0.0,0.0},{0.0,0.6,-0.3},{-0.4,0.2,0.8}};
+ for(uint64_t c = 0u; c < 3u; ++c){
+ kel::lbm::data<sch::Vector<sch::T,D>> u;
+ for(uint64_t i = 0u; i < D; ++i){ u.at({{i}}).set(pts[c][i]); }
+
+ auto x = (lbm::mask_local_to_global<sch::T,D>)(u,p,com);
+ auto back = (lbm::mask_global_to_local<sch::T,D>)(x,p,com);
+
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(std::abs(back.at({{i}}).get() - u.at({{i}}).get()) < 1e-10,
+ std::string{"3D round trip failed at point "} + std::to_string(c)
+ + " component " + std::to_string(i));
+ }
+ }
+}
+
+SAW_TEST("3D / zero rotation vector is the identity"){
+ using namespace kel;
+
+ // Rodrigues divides by the angle, so the zero vector is the degenerate
+ // case that would produce NaN without a guard.
+ auto g = make_group<1u>(2.0, 1.0);
+ auto& p = g.template get<"particles">().at({0u});
+ place(g, 0u, 10.0, 10.0, 10.0);
+
+ auto& rot = p.template get<"rigid_body">().template get<"rotation">();
+ for(uint64_t i = 0u; i < D; ++i){ rot.at({{i}}).set(0.0); }
+
+ auto& com = g.template get<"center_of_mass">().at({0u});
+
+ kel::lbm::data<sch::Vector<sch::T,D>> u;
+ u.at({{0u}}).set(1.0);
+ u.at({{1u}}).set(0.0);
+ u.at({{2u}}).set(0.0);
+
+ auto x = (lbm::mask_local_to_global<sch::T,D>)(u,p,com);
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(std::isfinite(x.at({{i}}).get()),
+ "zero rotation must not produce NaN");
+ }
+ SAW_EXPECT(std::abs(x.at({{0u}}).get() - 12.0) < 0.05,
+ std::string{"unrotated +x should sit at centre plus radius: "}
+ + std::to_string(x.at({{0u}}).get()));
+}
+
+SAW_TEST("3D / contact is antisymmetric and conserves momentum"){
+ using namespace kel;
+
+ auto g = make_group<2u>(2.0, 1.0);
+ auto& parts = g.template get<"particles">();
+
+ // Overlapping, offset on every axis so nothing cancels by symmetry.
+ place(g, 0u, 10.0, 10.0, 10.0);
+ place(g, 1u, 12.5, 10.8, 11.2);
+
+ lbm::dem_params<sch::T> dem{8.0, 0.3, 2.0, 0.5};
+
+ for(uint64_t i = 0u; i < 2u; ++i){
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({i}));
+ }
+ for(uint64_t i = 0u; i < 2u; ++i){
+ (lbm::accumulate_particle_contacts<sch::T,D>)(parts, i, dem, {1u});
+ }
+
+ for(uint64_t k = 0u; k < D; ++k){
+ auto f0 = parts.at({0u}).template get<"rigid_body">()
+ .template get<"force">().at({{k}}).get();
+ auto f1 = parts.at({1u}).template get<"rigid_body">()
+ .template get<"force">().at({{k}}).get();
+ SAW_EXPECT(f0 == -f1,
+ std::string{"3D force component "} + std::to_string(k)
+ + " not exactly opposite");
+ }
+
+ auto fx = parts.at({0u}).template get<"rigid_body">()
+ .template get<"force">().at({{0u}}).get();
+ SAW_EXPECT(std::abs(fx) > 0.0, "an overlapping 3D pair must feel a force");
+}
+
+SAW_TEST("3D / linear integration works and rotation stays gated"){
+ using namespace kel;
+
+ auto g = make_group<1u>(2.0, 1.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+
+ place(g, 0u, 0.0, 0.0, 0.0);
+ for(uint64_t i = 0u; i < D; ++i){
+ rb.template get<"position_old">().at({{i}}).set(0.0);
+ }
+
+ auto mass = rb.template get<"mass">().at({}).get();
+ rb.template get<"force">().at({{2u}}).set(mass); // unit acceleration in z
+ rb.template get<"torque">().at({{0u}}).set(100.0); // and a large torque
+
+ (lbm::integrate_particle<sch::T,D>)(p, {}, {1u});
+
+ SAW_EXPECT(std::abs(rb.template get<"position">().at({{2u}}).get() - 1.0) < 1e-12,
+ std::string{"3D linear motion should follow a dt^2: "}
+ + std::to_string(rb.template get<"position">().at({{2u}}).get()));
+
+ /**
+ * 3D rotation is deliberately not integrated: a scalar inertia only
+ * describes an isotropic body, and integrating the rotation vector as a
+ * displacement cannot represent non-commuting composition. Assert the gate
+ * holds, so a future change cannot quietly start producing wrong spin.
+ */
+ static_assert(!lbm::particle_angular_supported<3u>, "3D rotation must stay gated");
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(rb.template get<"angular_acceleration">().at({{i}}).get() == 0.0,
+ "3D angular acceleration must stay untouched even under torque");
+ }
+}
+
+SAW_TEST("3D / cell list bins in three dimensions"){
+ using namespace kel;
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{24u,24u,24u}};
+ auto cl = (lbm::make_cell_list<sch::T,D,8u>)(extent, 2.0);
+
+ auto g = make_group<3u>(2.0, 1.0);
+ auto& parts = g.template get<"particles">();
+ place(g, 0u, 5.0, 5.0, 5.0);
+ place(g, 1u, 6.0, 5.5, 5.0);
+ place(g, 2u, 20.0, 20.0, 20.0);
+
+ (lbm::build_cell_list<sch::T,D,8u>)(parts, cl);
+ SAW_EXPECT(cl.template get<"overflow">().at({0u}).get() == 0u, "no overflow");
+
+ // The 3^D neighbourhood is 27 bins here, not 9.
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> near{{5u,5u,5u}};
+ bool saw[3] = {false,false,false};
+ (lbm::for_each_bin_candidate<sch::T,D,8u>)(cl, near, [&](uint64_t p){ saw[p] = true; });
+
+ SAW_EXPECT(saw[0] && saw[1], "neighbours must be found in 3D");
+ SAW_EXPECT(!saw[2], "the distant particle must be pruned in 3D");
+}
+}
diff --git a/modules/core/tests/particle_consistency.cpp b/modules/core/tests/particle_consistency.cpp
new file mode 100644
index 0000000..ae40aa8
--- /dev/null
+++ b/modules/core/tests/particle_consistency.cpp
@@ -0,0 +1,269 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/contact.hpp"
+#include "../c++/particle/cell_list.hpp"
+#include "../c++/particle/voxel_narrow.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 2u;
+constexpr uint64_t Cap = 16u;
+
+template<uint64_t PC>
+auto make_group(double radius, uint64_t res = 24u){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(1.0);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,PC>(r,d,{res});
+}
+
+template<typename G>
+void place(G& g, uint64_t i, double x, double y){
+ auto& pos = g.template get<"particles">().at({i})
+ .template get<"rigid_body">().template get<"position">();
+ pos.at({{0u}}).set(x);
+ pos.at({{1u}}).set(y);
+}
+
+SAW_TEST("Consistency / broad phase never rejects a real contact"){
+ using namespace kel;
+
+ /**
+ * The broad phase is allowed to over-report, never to under-report: a
+ * missed pair is a contact that silently never happens. Sweep a grid of
+ * separations and assert the implication in the direction that matters.
+ */
+ auto g = make_group<2u>(3.0);
+ auto& parts = g.template get<"particles">();
+
+ for(int i = 0; i <= 60; ++i){
+ double sep = 0.1 * i;
+ place(g, 0u, 20.0, 20.0);
+ place(g, 1u, 20.0 + sep, 20.0);
+
+ bool broad = (lbm::broadphase_collision_check<sch::T,D>)(parts.at({0u}),parts.at({1u}));
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m;
+ bool narrow = (lbm::narrow_phase<lbm::coll::Spheroid<sch::T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), m);
+
+ SAW_EXPECT(!narrow || broad,
+ std::string{"narrow found a contact the broad phase rejected at sep="}
+ + std::to_string(sep));
+ }
+}
+
+SAW_TEST("Consistency / cell list finds the same contacts as brute force"){
+ using namespace kel;
+
+ /**
+ * The cell list is only an accelerator. If it ever disagrees with the
+ * exhaustive pair loop about WHICH pairs touch, every result built on it
+ * is suspect -- and the disagreement would be invisible in output.
+ */
+ const double radius = 3.0;
+ auto g = make_group<6u>(radius);
+ auto& parts = g.template get<"particles">();
+
+ // A cluster plus a couple of outliers, so some pairs touch and some do not.
+ place(g, 0u, 20.0, 20.0);
+ place(g, 1u, 24.5, 20.0);
+ place(g, 2u, 22.0, 24.0);
+ place(g, 3u, 21.0, 16.5);
+ place(g, 4u, 50.0, 40.0);
+ place(g, 5u, 54.0, 40.0);
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,64u}};
+ auto cl = (lbm::make_cell_list<sch::T,D,Cap>)(extent, radius);
+ (lbm::build_cell_list<sch::T,D,Cap>)(parts, cl);
+
+ for(uint64_t i = 0u; i < 6u; ++i){
+ // Brute force: everyone.
+ bool brute[6] = {false,false,false,false,false,false};
+ for(uint64_t j = 0u; j < 6u; ++j){
+ if(j == i){ continue; }
+ brute[j] = (lbm::broadphase_collision_check<sch::T,D>)(parts.at({i}),parts.at({j}));
+ }
+
+ // Via the bins.
+ bool binned[6] = {false,false,false,false,false,false};
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> cell;
+ auto& pos = parts.at({i}).template get<"rigid_body">().template get<"position">();
+ for(uint64_t k = 0u; k < D; ++k){
+ cell.at({k}).set(static_cast<uint64_t>(pos.at({{k}}).get()));
+ }
+ (lbm::for_each_bin_candidate<sch::T,D,Cap>)(cl, cell, [&](uint64_t j){
+ if(j == i){ return; }
+ if((lbm::broadphase_collision_check<sch::T,D>)(parts.at({i}),parts.at({j}))){
+ binned[j] = true;
+ }
+ });
+
+ for(uint64_t j = 0u; j < 6u; ++j){
+ SAW_EXPECT(brute[j] == binned[j],
+ std::string{"pair ("} + std::to_string(i) + "," + std::to_string(j)
+ + ") disagrees: brute=" + std::to_string(brute[j])
+ + " binned=" + std::to_string(binned[j]));
+ }
+ }
+}
+
+SAW_TEST("Consistency / contact accumulation is deterministic"){
+ using namespace kel;
+
+ /**
+ * Same input twice must give bitwise identical output. Anything else
+ * means a result that cannot be reproduced or bisected.
+ */
+ lbm::dem_params<sch::T> dem{7.0, 0.35, 3.0, 0.6};
+
+ auto run = [&](){
+ auto g = make_group<4u>(3.0);
+ auto& parts = g.template get<"particles">();
+ place(g, 0u, 20.0, 20.0);
+ place(g, 1u, 24.5, 20.3);
+ place(g, 2u, 22.0, 24.0);
+ place(g, 3u, 18.0, 23.0);
+
+ for(uint64_t i = 0u; i < 4u; ++i){
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({i}));
+ }
+ for(uint64_t i = 0u; i < 4u; ++i){
+ (lbm::accumulate_particle_contacts<sch::T,D>)(parts, i, dem, {1u});
+ }
+
+ std::array<double,8> out{};
+ for(uint64_t i = 0u; i < 4u; ++i){
+ auto& f = parts.at({i}).template get<"rigid_body">().template get<"force">();
+ out[i*2u] = f.at({{0u}}).get();
+ out[i*2u + 1u] = f.at({{1u}}).get();
+ }
+ return out;
+ };
+
+ auto a = run();
+ auto b = run();
+
+ for(uint64_t i = 0u; i < 8u; ++i){
+ SAW_EXPECT(a[i] == b[i],
+ std::string{"run to run difference at slot "} + std::to_string(i));
+ }
+}
+
+SAW_TEST("Consistency / voxel narrow phase handles a cube mask"){
+ using namespace kel;
+
+ /**
+ * The point of the voxel narrow phase is that it is shape agnostic. A
+ * cube is the cheapest shape a sphere test cannot stand in for: its
+ * corner is further out than its face, so a face-on contact and a
+ * corner-on contact at the same centre distance differ.
+ */
+ auto g = make_group<2u>(5.0, 32u);
+ auto& mask = g.template get<"mask">();
+
+ // Overwrite the sphere mask with a cube of the same bounding radius.
+ auto com = (lbm::fill_mask_from_sdf<sch::T,D>)(
+ mask, 32u,
+ [](const kel::lbm::data<sch::Vector<sch::T,D>>& u){
+ return (lbm::sdf::cube<sch::T,D>)(u);
+ }
+ );
+ g.template get<"center_of_mass">().at({0u}) = com;
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,64u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.0);
+
+ auto& parts = g.template get<"particles">();
+
+ // Face to face along x, overlapping.
+ place(g, 0u, 28.0, 32.0);
+ place(g, 1u, 36.0, 32.0);
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m_face;
+ bool face = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,m_face);
+
+ SAW_EXPECT(face, "overlapping cubes must register a contact");
+ // A flat face gives a clean axis-aligned normal, which is exactly what a
+ // centre-to-centre normal would also give here -- so check the shape
+ // really is a cube by its reach instead.
+ SAW_EXPECT(std::abs(m_face.template get<"normal">().at({{0u}}).get()) > 0.9,
+ "face contact normal should be close to the x axis");
+
+ // Diagonal placement: a sphere of the same bounding radius would already
+ // have separated at this distance, the cube corners still meet.
+ place(g, 0u, 28.0, 28.0);
+ place(g, 1u, 35.0, 35.0);
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m_corner;
+ bool corner = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,m_corner);
+
+ SAW_EXPECT(corner,
+ "cube corners should still touch where spheres would not");
+}
+
+SAW_TEST("Consistency / voxel and analytic agree on a sphere across offsets"){
+ using namespace kel;
+
+ /**
+ * Spot checks pass easily; sweep the configuration instead. Both routes
+ * describe the same body, so they must track each other everywhere, not
+ * just at one convenient separation.
+ */
+ const double radius = 6.0;
+ auto g = make_group<2u>(radius, 32u);
+ auto& parts = g.template get<"particles">();
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{72u,72u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.0);
+
+ uint64_t compared = 0u;
+ for(int dx = 2; dx <= 11; ++dx){
+ for(int dy = 0; dy <= 4; ++dy){
+ place(g, 0u, 36.0, 36.0);
+ place(g, 1u, 36.0 + dx, 36.0 + dy);
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> mv, ma;
+ bool hv = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,mv);
+ bool ha = (lbm::narrow_phase<lbm::coll::Spheroid<sch::T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), ma);
+
+ if(!ha){
+ continue;
+ }
+ SAW_EXPECT(hv,
+ std::string{"voxel missed a contact the analytic found at dx="}
+ + std::to_string(dx) + " dy=" + std::to_string(dy));
+
+ auto nv = mv.template get<"normal">();
+ auto na = ma.template get<"normal">();
+ auto dot = nv.at({{0u}}).get()*na.at({{0u}}).get()
+ + nv.at({{1u}}).get()*na.at({{1u}}).get();
+
+ SAW_EXPECT(dot > 0.9,
+ std::string{"normals diverged at dx="} + std::to_string(dx)
+ + " dy=" + std::to_string(dy) + " dot=" + std::to_string(dot));
+
+ auto diff = std::abs(mv.template get<"depth">().at({}).get()
+ - ma.template get<"depth">().at({}).get());
+ SAW_EXPECT(diff < 2.0,
+ std::string{"depths diverged at dx="} + std::to_string(dx)
+ + " dy=" + std::to_string(dy) + " by " + std::to_string(diff));
+
+ ++compared;
+ }
+ }
+
+ SAW_EXPECT(compared > 10u,
+ std::string{"expected a meaningful number of overlapping cases, got "}
+ + std::to_string(compared));
+}
+}
diff --git a/modules/core/tests/particle_edges.cpp b/modules/core/tests/particle_edges.cpp
new file mode 100644
index 0000000..cbc1bab
--- /dev/null
+++ b/modules/core/tests/particle_edges.cpp
@@ -0,0 +1,224 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/contact.hpp"
+#include "../c++/particle/cell_list.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 2u;
+
+template<uint64_t PC>
+auto make_group(double radius){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(1.0);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,PC>(r,d,{8u});
+}
+
+template<typename G>
+void place(G& g, uint64_t i, double x, double y){
+ auto& pos = g.template get<"particles">().at({i})
+ .template get<"rigid_body">().template get<"position">();
+ pos.at({{0u}}).set(x);
+ pos.at({{1u}}).set(y);
+}
+
+SAW_TEST("Edges / AABB clamps at the low wall too"){
+ using namespace kel;
+
+ /**
+ * The high side needed an explicit clamp against meta. The low side is
+ * handled by a ternary on the radius, which is easy to get backwards --
+ * and an index that underflows to a huge unsigned would sweep the whole
+ * field rather than failing visibly.
+ */
+ using PG = lbm::sch::ParticleGroup<sch::T,D,2u,lbm::coll::Spheroid<sch::T>>;
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> meta{{64u,32u}};
+
+ auto g = make_group<2u>(4.0);
+ place(g, 0u, 1.0, 0.5); // well inside both low walls
+ place(g, 1u, 0.0, 0.0); // exactly at the origin
+
+ for(uint64_t i = 0u; i < 2u; ++i){
+ kel::lbm::data<sch::FixedArray<sch::UInt64,1u>> idx;
+ idx.at({{0u}}).set(i);
+
+ auto eo = lbm::particle_aabb<PG>::calculate(g, idx, meta);
+ SAW_EXPECT(eo.is_value(), "aabb must succeed near the origin");
+
+ auto& a = eo.get_value().template get<"a">();
+ auto& b = eo.get_value().template get<"b">();
+
+ for(uint64_t k = 0u; k < D; ++k){
+ // Unsigned underflow would show up as an absurd lower bound.
+ SAW_EXPECT(a.at({k}).get() <= meta.at({k}).get(),
+ std::string{"lower bound underflowed for particle "} + std::to_string(i));
+ SAW_EXPECT(b.at({k}).get() <= meta.at({k}).get(),
+ std::string{"upper bound not clamped for particle "} + std::to_string(i));
+ SAW_EXPECT(a.at({k}).get() < b.at({k}).get(),
+ "box must be non-empty");
+ }
+ }
+}
+
+SAW_TEST("Edges / AABB of a particle larger than the domain"){
+ using namespace kel;
+
+ // Radius exceeds the field, so both bounds want to run off the ends.
+ using PG = lbm::sch::ParticleGroup<sch::T,D,1u,lbm::coll::Spheroid<sch::T>>;
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> meta{{8u,8u}};
+
+ auto g = make_group<1u>(20.0);
+ place(g, 0u, 4.0, 4.0);
+
+ auto eo = lbm::particle_aabb<PG>::calculate(g, {{0u}}, meta);
+ SAW_EXPECT(eo.is_value(), "oversized particle must still produce a box");
+
+ auto& a = eo.get_value().template get<"a">();
+ auto& b = eo.get_value().template get<"b">();
+ for(uint64_t k = 0u; k < D; ++k){
+ SAW_EXPECT(a.at({k}).get() == 0u, "should start at the field edge");
+ SAW_EXPECT(b.at({k}).get() == meta.at({k}).get(), "and stop at the far edge");
+ }
+}
+
+SAW_TEST("Edges / cell list tolerates particles outside the domain"){
+ using namespace kel;
+
+ /**
+ * A particle that has drifted out of bounds must still bin somewhere
+ * rather than indexing past the end of the grid.
+ */
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{32u,32u}};
+ auto cl = (lbm::make_cell_list<sch::T,D,8u>)(extent, 2.0);
+
+ auto g = make_group<3u>(2.0);
+ place(g, 0u, -50.0, -50.0); // far negative
+ place(g, 1u, 500.0, 500.0); // far positive
+ place(g, 2u, 16.0, 16.0); // legitimately inside
+
+ auto& parts = g.template get<"particles">();
+ (lbm::build_cell_list<sch::T,D,8u>)(parts, cl);
+
+ SAW_EXPECT(cl.template get<"overflow">().at({0u}).get() == 0u,
+ "clamped out-of-range particles should not overflow a bin");
+
+ // The interior particle is still findable where it actually is.
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> cell{{16u,16u}};
+ bool found = false;
+ (lbm::for_each_bin_candidate<sch::T,D,8u>)(cl, cell, [&](uint64_t p){
+ if(p == 2u){ found = true; }
+ });
+ SAW_EXPECT(found, "the in-bounds particle must still be found");
+}
+
+SAW_TEST("Edges / cell list rebuild clears the previous frame"){
+ using namespace kel;
+
+ /**
+ * Bins are not self-clearing. If a rebuild forgot to reset the counts,
+ * stale entries would accumulate and particles would appear to be in two
+ * places at once -- for a few frames, then overflow.
+ */
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{32u,32u}};
+ auto cl = (lbm::make_cell_list<sch::T,D,8u>)(extent, 2.0);
+
+ auto g = make_group<1u>(2.0);
+ auto& parts = g.template get<"particles">();
+
+ place(g, 0u, 5.0, 5.0);
+ (lbm::build_cell_list<sch::T,D,8u>)(parts, cl);
+
+ // Move it well away and rebuild.
+ place(g, 0u, 25.0, 25.0);
+ (lbm::build_cell_list<sch::T,D,8u>)(parts, cl);
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> old_cell{{5u,5u}};
+ uint64_t stale = 0u;
+ (lbm::for_each_bin_candidate<sch::T,D,8u>)(cl, old_cell, [&](uint64_t){ ++stale; });
+ SAW_EXPECT(stale == 0u,
+ std::string{"old position still reports "} + std::to_string(stale) + " entries");
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> new_cell{{25u,25u}};
+ uint64_t fresh = 0u;
+ (lbm::for_each_bin_candidate<sch::T,D,8u>)(cl, new_cell, [&](uint64_t){ ++fresh; });
+ SAW_EXPECT(fresh == 1u, "new position must report exactly one entry");
+}
+
+SAW_TEST("Edges / zero relative velocity contact is pure spring"){
+ using namespace kel;
+
+ /**
+ * With both bodies at rest the dashpot contributes nothing, so the force
+ * must be exactly k*delta. Any velocity-convention slip shows up as a
+ * spurious damping term here.
+ */
+ auto g = make_group<2u>(2.0);
+ auto& parts = g.template get<"particles">();
+
+ // At rest: position_old equals position.
+ for(uint64_t i = 0u; i < 2u; ++i){
+ auto& rb = parts.at({i}).template get<"rigid_body">();
+ auto& pos = rb.template get<"position">();
+ auto& old = rb.template get<"position_old">();
+ for(uint64_t k = 0u; k < D; ++k){
+ old.at({{k}}).set(pos.at({{k}}).get());
+ }
+ }
+ place(g, 0u, 0.0, 0.0);
+ place(g, 1u, 3.0, 0.0);
+ for(uint64_t i = 0u; i < 2u; ++i){
+ auto& rb = parts.at({i}).template get<"rigid_body">();
+ auto& pos = rb.template get<"position">();
+ auto& old = rb.template get<"position_old">();
+ for(uint64_t k = 0u; k < D; ++k){
+ old.at({{k}}).set(pos.at({{k}}).get());
+ }
+ }
+
+ const double k_n = 3.0;
+ lbm::dem_params<sch::T> dem{k_n, 0.9, 1.0, 0.5};
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m;
+ (void)(lbm::narrow_phase<lbm::coll::Spheroid<sch::T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), m);
+
+ auto res = (lbm::particle_contact_response<sch::T,D>)(
+ m, parts.at({0u}), parts.at({1u}), true, dem, {1u});
+
+ // Overlap is 2+2-3 = 1, so the spring alone gives k*1 pointing -x.
+ SAW_EXPECT(std::abs(res.force.at({{0u}}).get() + k_n) < 1e-12,
+ std::string{"expected exactly -k*delta: "} + std::to_string(res.force.at({{0u}}).get()));
+ SAW_EXPECT(res.force.at({{1u}}).get() == 0.0,
+ "no tangential force without relative motion");
+}
+
+SAW_TEST("Edges / single particle group has no self contact"){
+ using namespace kel;
+
+ // The pair loop must skip j == i; a self contact would read as a huge
+ // permanent overlap.
+ auto g = make_group<1u>(2.0);
+ auto& parts = g.template get<"particles">();
+ place(g, 0u, 10.0, 10.0);
+
+ lbm::dem_params<sch::T> dem{5.0, 0.3, 0.0, 0.0};
+
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({0u}));
+ (lbm::accumulate_particle_contacts<sch::T,D>)(parts, 0u, dem, {1u});
+
+ for(uint64_t k = 0u; k < D; ++k){
+ SAW_EXPECT(parts.at({0u}).template get<"rigid_body">()
+ .template get<"force">().at({{k}}).get() == 0.0,
+ "a lone particle must feel no contact force");
+ }
+}
+}
diff --git a/modules/core/tests/particle_gaps.cpp b/modules/core/tests/particle_gaps.cpp
new file mode 100644
index 0000000..3db831e
--- /dev/null
+++ b/modules/core/tests/particle_gaps.cpp
@@ -0,0 +1,297 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/contact.hpp"
+#include "../c++/particle/mask.hpp"
+#include "../c++/particle/voxel_narrow.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 2u;
+
+template<uint64_t PC>
+auto make_group(double radius, uint64_t res = 32u){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(1.0);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,PC>(r,d,{res});
+}
+
+template<typename G>
+void rest_at(G& g, uint64_t i, double x, double y){
+ auto& rb = g.template get<"particles">().at({i}).template get<"rigid_body">();
+ const double v[2] = {x,y};
+ for(uint64_t k = 0u; k < D; ++k){
+ rb.template get<"position">().at({{k}}).set(v[k]);
+ rb.template get<"position_old">().at({{k}}).set(v[k]);
+ }
+}
+
+SAW_TEST("Gaps / mask sampling outside the box extrapolates monotonically"){
+ using namespace kel;
+
+ /**
+ * mask_sample_local clamps the lookup to the stored box and adds back the
+ * distance to the box. That extrapolation branch has no other coverage,
+ * and getting it wrong would make far-field queries read as *inside*.
+ */
+ auto g = make_group<1u>(3.0);
+ auto& mask = g.template get<"mask">();
+ const uint64_t R = 32u;
+
+ double prev = -2.0;
+ for(int i = 0; i <= 12; ++i){
+ double d = 0.5 * i; // walk out along +x, past the box edge at 1.0
+
+ kel::lbm::data<sch::Vector<sch::T,D>> u;
+ u.at({{0u}}).set(d);
+ u.at({{1u}}).set(0.0);
+
+ auto s = (lbm::mask_sample_local<sch::T,D>)(mask,u,R);
+
+ SAW_EXPECT(std::isfinite(s),
+ std::string{"sample must stay finite at u="} + std::to_string(d));
+ SAW_EXPECT(s > prev - 1e-9,
+ std::string{"distance must grow outward, broke at u="} + std::to_string(d));
+ if(d > 1.5){
+ SAW_EXPECT(s > 0.0,
+ std::string{"well outside must read positive, got "} + std::to_string(s)
+ + " at u=" + std::to_string(d));
+ }
+ prev = s;
+ }
+}
+
+SAW_TEST("Gaps / solid fraction is exact at the shell edges"){
+ using namespace kel;
+
+ // The ramp endpoints are where an off-by-half would hide.
+ const double eps = 2.0;
+ SAW_EXPECT((lbm::solid_fraction_from_sdf<sch::T>)(-eps/2, eps) == 1.0,
+ "the inner edge of the shell must be fully solid");
+ SAW_EXPECT((lbm::solid_fraction_from_sdf<sch::T>)( eps/2, eps) == 0.0,
+ "the outer edge must be fully fluid");
+
+ // Midpoint of a cos^2 ramp is exactly one half.
+ auto mid = (lbm::solid_fraction_from_sdf<sch::T>)(0.0, eps);
+ SAW_EXPECT(std::abs(mid - 0.5) < 1e-12,
+ std::string{"the surface itself should read 0.5: "} + std::to_string(mid));
+}
+
+SAW_TEST("Gaps / one shared mask serves particles of different sizes"){
+ using namespace kel;
+
+ /**
+ * This is the central claim of the normalized-mask design: the group holds
+ * one shape and each particle scales it by its own radius. If the scaling
+ * were dropped the two bodies below would read identically.
+ */
+ auto g = make_group<2u>(4.0);
+ auto& parts = g.template get<"particles">();
+ auto& com = g.template get<"center_of_mass">().at({0u});
+ const uint64_t R = 32u;
+
+ rest_at(g, 0u, 20.0, 20.0);
+ rest_at(g, 1u, 50.0, 20.0);
+
+ // Shrink the second particle; same group, same mask.
+ parts.at({1u}).template get<"collision">().template get<"radius">().at({}).set(1.0);
+
+ // Two lattice units out from each centre: inside the big one, outside the
+ // small one.
+ kel::lbm::data<sch::Vector<sch::T,D>> probe_big;
+ probe_big.at({{0u}}).set(22.0);
+ probe_big.at({{1u}}).set(20.0);
+
+ kel::lbm::data<sch::Vector<sch::T,D>> probe_small;
+ probe_small.at({{0u}}).set(52.0);
+ probe_small.at({{1u}}).set(20.0);
+
+ auto d_big = (lbm::mask_signed_distance<sch::T,D>)(g,parts.at({0u}),probe_big,R);
+ auto d_small = (lbm::mask_signed_distance<sch::T,D>)(g,parts.at({1u}),probe_small,R);
+
+ SAW_EXPECT(d_big < -0.5,
+ std::string{"2 units into a radius 4 body must be inside: "} + std::to_string(d_big));
+ SAW_EXPECT(d_small > 0.5,
+ std::string{"2 units from a radius 1 body must be outside: "} + std::to_string(d_small));
+
+ // And the physical bounding radius really is the particle's radius, which
+ // is what makes the broad phase a valid bound for the voxel narrow phase.
+ kel::lbm::data<sch::Vector<sch::T,D>> at_edge;
+ at_edge.at({{0u}}).set(51.0);
+ at_edge.at({{1u}}).set(20.0);
+ auto d_edge = (lbm::mask_signed_distance<sch::T,D>)(g,parts.at({1u}),at_edge,R);
+ SAW_EXPECT(std::abs(d_edge) < 0.15,
+ std::string{"one radius out should be the surface: "} + std::to_string(d_edge));
+}
+
+SAW_TEST("Gaps / mixed size pair contacts correctly"){
+ using namespace kel;
+
+ auto g = make_group<2u>(4.0);
+ auto& parts = g.template get<"particles">();
+
+ parts.at({1u}).template get<"collision">().template get<"radius">().at({}).set(1.0);
+
+ // Centres 4.5 apart: radii 4 + 1 = 5, so they overlap by 0.5.
+ rest_at(g, 0u, 20.0, 20.0);
+ rest_at(g, 1u, 24.5, 20.0);
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m;
+ bool hit = (lbm::narrow_phase<lbm::coll::Spheroid<sch::T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), m);
+
+ SAW_EXPECT(hit, "a mixed size overlapping pair must register");
+ SAW_EXPECT(std::abs(m.template get<"depth">().at({}).get() - 0.5) < 1e-12,
+ std::string{"depth should be r0+r1-d = 0.5: "}
+ + std::to_string(m.template get<"depth">().at({}).get()));
+
+ // The contact point must lie on the small body's surface, i.e. much
+ // closer to it than to the large one.
+ auto px = m.template get<"point">().at({{0u}}).get();
+ SAW_EXPECT(px > 23.0,
+ std::string{"contact should sit near the small body: "} + std::to_string(px));
+}
+
+SAW_TEST("Gaps / the high wall pushes inward"){
+ using namespace kel;
+
+ /**
+ * Only the low wall and the corner had coverage. The high face has its own
+ * sign and its own offset from the extent, either of which could be wrong
+ * independently.
+ */
+ auto g = make_group<1u>(2.0);
+ auto& parts = g.template get<"particles">();
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,32u}};
+ const double k_n = 4.0;
+ lbm::dem_params<sch::T> dem{k_n, 0.0, 0.0, 0.0};
+
+ // Overlapping the high x wall by 0.5.
+ rest_at(g, 0u, 62.5, 16.0);
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({0u}));
+ (lbm::accumulate_box_wall_contacts<sch::T,D>)(parts.at({0u}), extent, dem, {1u});
+
+ auto fx = parts.at({0u}).template get<"rigid_body">()
+ .template get<"force">().at({{0u}}).get();
+ SAW_EXPECT(std::abs(fx + k_n * 0.5) < 1e-12,
+ std::string{"high wall should push -x by k*depth: "} + std::to_string(fx));
+
+ // Same on the high y face, which uses the other extent.
+ auto g2 = make_group<1u>(2.0);
+ auto& p2 = g2.template get<"particles">();
+ rest_at(g2, 0u, 32.0, 30.5);
+ (lbm::reset_particle_accumulators<sch::T,D>)(p2.at({0u}));
+ (lbm::accumulate_box_wall_contacts<sch::T,D>)(p2.at({0u}), extent, dem, {1u});
+
+ auto fy = p2.at({0u}).template get<"rigid_body">()
+ .template get<"force">().at({{1u}}).get();
+ SAW_EXPECT(std::abs(fy + k_n * 0.5) < 1e-12,
+ std::string{"high y wall should push -y by k*depth: "} + std::to_string(fy));
+}
+
+SAW_TEST("Gaps / friction is capped by Coulomb"){
+ using namespace kel;
+
+ /**
+ * The tangential force is min(gamma_t |v_t|, mu f_n). With a large
+ * gamma_t the cap must bind, otherwise friction can exceed the normal
+ * load and a sliding contact gains energy.
+ */
+ auto g = make_group<2u>(2.0);
+ auto& parts = g.template get<"particles">();
+
+ // Overlapping, sliding hard past each other.
+ auto set = [&](uint64_t i, double x, double y, double vy){
+ auto& rb = parts.at({i}).template get<"rigid_body">();
+ rb.template get<"position">().at({{0u}}).set(x);
+ rb.template get<"position">().at({{1u}}).set(y);
+ rb.template get<"position_old">().at({{0u}}).set(x);
+ rb.template get<"position_old">().at({{1u}}).set(y - vy);
+ };
+ set(0u, 0.0, 0.0, 1.0);
+ set(1u, 3.0, 0.0, -1.0);
+
+ const double k_n = 2.0;
+ const double mu = 0.25;
+ // gamma_t absurdly large so the viscous term would dominate uncapped.
+ lbm::dem_params<sch::T> dem{k_n, 0.0, 1000.0, mu};
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m;
+ (void)(lbm::narrow_phase<lbm::coll::Spheroid<sch::T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), m);
+
+ auto res = (lbm::particle_contact_response<sch::T,D>)(
+ m, parts.at({0u}), parts.at({1u}), true, dem, {1u});
+
+ // Undamped normal force is k*delta = 2*1 = 2, so friction caps at 0.5.
+ auto f_n = std::abs(res.force.at({{0u}}).get());
+ auto f_t = std::abs(res.force.at({{1u}}).get());
+
+ SAW_EXPECT(std::abs(f_n - k_n * 1.0) < 1e-12,
+ std::string{"normal force should be k*delta: "} + std::to_string(f_n));
+ SAW_EXPECT(std::abs(f_t - mu * f_n) < 1e-9,
+ std::string{"friction should sit exactly on the Coulomb cap "}
+ + std::to_string(mu * f_n) + ", got " + std::to_string(f_t));
+}
+
+SAW_TEST("Gaps / stiffness helper matches its own definition"){
+ using namespace kel;
+
+ /**
+ * dem_stiffness_for is the only guidance a caller gets for choosing k_n,
+ * so it should at least be self consistent: a body hitting at v0 with the
+ * suggested stiffness should stop near delta_max.
+ */
+ const double m_eff = 4.0;
+ const double v0 = 0.1;
+ const double delta_max = 0.05;
+
+ auto k = (lbm::dem_stiffness_for<sch::T>)(m_eff, v0, delta_max);
+
+ // Energy balance: k delta^2 / 2 == m v^2 / 2.
+ auto spring_energy = 0.5 * k * delta_max * delta_max;
+ auto kinetic = 0.5 * m_eff * v0 * v0;
+
+ SAW_EXPECT(std::abs(spring_energy - kinetic) < 1e-12,
+ std::string{"energies should match: "} + std::to_string(spring_energy)
+ + " vs " + std::to_string(kinetic));
+ SAW_EXPECT(k > 0.0, "stiffness must be positive");
+}
+
+SAW_TEST("Gaps / voxel contact is deterministic"){
+ using namespace kel;
+
+ // The overlap integral walks the lattice; the sweep order must not drift
+ // between calls or results stop being reproducible.
+ auto g = make_group<2u>(5.0);
+ auto& parts = g.template get<"particles">();
+ rest_at(g, 0u, 28.0, 30.0);
+ rest_at(g, 1u, 35.0, 32.0);
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,64u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.0);
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> a, b;
+ bool ha = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,a);
+ bool hb = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,b);
+
+ SAW_EXPECT(ha && hb, "both calls must find the contact");
+ SAW_EXPECT(a.template get<"depth">().at({}).get() == b.template get<"depth">().at({}).get(),
+ "depth must be bitwise reproducible");
+ for(uint64_t k = 0u; k < D; ++k){
+ SAW_EXPECT(a.template get<"normal">().at({{k}}).get()
+ == b.template get<"normal">().at({{k}}).get(),
+ "normal must be bitwise reproducible");
+ }
+}
+}
diff --git a/modules/core/tests/particles.cpp b/modules/core/tests/particles.cpp
index 823bcd7..2105abc 100644
--- a/modules/core/tests/particles.cpp
+++ b/modules/core/tests/particles.cpp
@@ -1,9 +1,13 @@
#include <forstio/test/suite.hpp>
+#include <cmath>
#include <iostream>
#include "../c++/particle/particle.hpp"
+#include "../c++/particle/integrate.hpp"
+#include "../c++/particle/contact.hpp"
namespace {
+struct TestDesc2D { static constexpr uint64_t D = 2u; static constexpr uint64_t Q = 9u; };
namespace sch {
using namespace kel::lbm::sch;
@@ -319,4 +323,414 @@ SAW_TEST("Spheroid Particle / AABB"){
// std::cout<<res<<std::endl;
}
+
+SAW_TEST("Spheroid Particle / AABB per particle"){
+ using namespace kel;
+
+ using T = sch::Float64;
+ constexpr uint64_t D = 2u;
+ constexpr uint64_t PC = 3u;
+
+ kel::lbm::data<sch::Scalar<T>> radi,dense;
+ radi.at({}) = 2.2f;
+ dense.at({}) = 1.0f;
+ auto pgrp = lbm::create_spheroid_particle_group<T,D,PC>(radi,dense,{8u});
+
+ auto& parts = pgrp.template get<"particles">();
+
+ auto place = [&](uint64_t i, double x, double y){
+ auto& pos = parts.at({i}).template get<"rigid_body">().template get<"position">();
+ pos.at({{0u}}).set(x);
+ pos.at({{1u}}).set(y);
+ };
+
+ place(0u, 4.1, 2.9);
+ place(1u, 40.0, 20.0);
+ place(2u, 63.0, 31.0); // hard against the far wall
+
+ using PG = lbm::sch::ParticleGroup<T,D,PC,lbm::coll::Spheroid<T>>;
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> meta{{64u,32u}};
+
+ // Each particle must get its OWN box. Before the fix every call site
+ // handed particle 0's index in, so this returned particle 0's box.
+ auto eo_1 = lbm::particle_aabb<PG>::calculate(pgrp,{{1u}},meta);
+ SAW_EXPECT(eo_1.is_value(), "particle_aabb errored for particle 1");
+ auto& a1 = eo_1.get_value().template get<"a">();
+ auto& b1 = eo_1.get_value().template get<"b">();
+
+ SAW_EXPECT(a1.at({{0u}}).get() == 37u,
+ std::string{"particle 1 a.x: "} + std::to_string(a1.at({{0u}}).get()));
+ SAW_EXPECT(a1.at({{1u}}).get() == 17u,
+ std::string{"particle 1 a.y: "} + std::to_string(a1.at({{1u}}).get()));
+ SAW_EXPECT(b1.at({{0u}}).get() == 43u,
+ std::string{"particle 1 b.x: "} + std::to_string(b1.at({{0u}}).get()));
+ SAW_EXPECT(b1.at({{1u}}).get() == 23u,
+ std::string{"particle 1 b.y: "} + std::to_string(b1.at({{1u}}).get()));
+
+ // The far-wall particle must be clamped to the domain. calculate() takes
+ // meta and, before the fix, never looked at it.
+ auto eo_2 = lbm::particle_aabb<PG>::calculate(pgrp,{{2u}},meta);
+ SAW_EXPECT(eo_2.is_value(), "particle_aabb errored for particle 2");
+ auto& b2 = eo_2.get_value().template get<"b">();
+
+ SAW_EXPECT(b2.at({{0u}}).get() == 64u,
+ std::string{"particle 2 b.x should clamp to 64: "} + std::to_string(b2.at({{0u}}).get()));
+ SAW_EXPECT(b2.at({{1u}}).get() == 32u,
+ std::string{"particle 2 b.y should clamp to 32: "} + std::to_string(b2.at({{1u}}).get()));
+
+ // Out of range index is still an error, not a silent clamp.
+ auto eo_bad = lbm::particle_aabb<PG>::calculate(pgrp,{{PC}},meta);
+ SAW_EXPECT(eo_bad.is_error(), "out of range particle index must error");
+}
+
+SAW_TEST("Spheroid Particle / per-particle inertial fan-out"){
+ using namespace kel;
+
+ using T = sch::Float64;
+ constexpr uint64_t D = 2u;
+ constexpr uint64_t PC = 4u;
+
+ kel::lbm::data<sch::Scalar<T>> radi,dense;
+ radi.at({}) = 2.0;
+ dense.at({}) = 3.0;
+ auto pgrp = lbm::create_spheroid_particle_group<T,D,PC>(radi,dense,{8u});
+
+ auto& parts = pgrp.template get<"particles">();
+
+ constexpr double pi = 3.14159265358979323846;
+ const double expect_m = pi * 2.0 * 2.0 * 3.0; // pi r^2 rho
+ const double expect_i = 0.5 * expect_m * 2.0 * 2.0; // m r^2 / 2
+
+ // Every particle must carry its own copy, not just particle 0.
+ for(uint64_t i = 0u; i < PC; ++i){
+ auto& pi_p = parts.at({i});
+ auto& rb = pi_p.template get<"rigid_body">();
+
+ SAW_EXPECT(pi_p.template get<"collision">().template get<"radius">().at({}).get() == 2.0,
+ std::string{"radius not fanned out at "} + std::to_string(i));
+ SAW_EXPECT(rb.template get<"density">().at({}).get() == 3.0,
+ std::string{"density not fanned out at "} + std::to_string(i));
+
+ auto m = rb.template get<"mass">().at({}).get();
+ SAW_EXPECT(std::abs(m - expect_m) < 1e-9,
+ std::string{"mass at "} + std::to_string(i) + ": " + std::to_string(m));
+
+ auto in = rb.template get<"inertia">().at({}).get();
+ SAW_EXPECT(std::abs(in - expect_i) < 1e-9,
+ std::string{"inertia at "} + std::to_string(i) + ": " + std::to_string(in));
+ }
+
+ // Accumulators start clean.
+ auto& rb0 = parts.at({0u}).template get<"rigid_body">();
+ SAW_EXPECT(rb0.template get<"force">().at({{0u}}).get() == 0.0, "force must start zeroed");
+ SAW_EXPECT(rb0.template get<"torque">().at({}).get() == 0.0, "torque must start zeroed");
+
+ // Sizes are now independent per particle.
+ parts.at({1u}).template get<"collision">().template get<"radius">().at({}).set(5.0);
+ SAW_EXPECT(parts.at({0u}).template get<"collision">().template get<"radius">().at({}).get() == 2.0,
+ "changing one particle's radius must not touch another's");
+}
+
+SAW_TEST("Spheroid Particle / broadphase uses per-particle radii"){
+ using namespace kel;
+
+ using T = sch::Float64;
+ constexpr uint64_t D = 2u;
+
+ kel::lbm::data<sch::Particle<T,D>> a, b;
+
+ auto set = [](auto& p, double x, double r){
+ p.template get<"rigid_body">().template get<"position">().at({{0u}}).set(x);
+ p.template get<"collision">().template get<"radius">().at({}).set(r);
+ };
+
+ // Centres 10 apart. Radii 2+2 do not reach; 2+9 do.
+ set(a, 0.0, 2.0);
+ set(b, 10.0, 2.0);
+ SAW_EXPECT((!lbm::broadphase_collision_check<T,D>(a,b)), "r=2,2 at distance 10 must not overlap");
+
+ set(b, 10.0, 9.0);
+ SAW_EXPECT((lbm::broadphase_collision_check<T,D>(a,b)), "r=2,9 at distance 10 must overlap");
+
+ // Squared centre distance comes back for the narrow phase to reuse.
+ auto res = (lbm::broadphase_collision_distance_squared<T,D>)(a,b);
+ SAW_EXPECT(std::abs(res.second.at({}).get() - 100.0) < 1e-9,
+ std::string{"expected squared distance 100: "} + std::to_string(res.second.at({}).get()));
+}
+
+SAW_TEST("Particle / force accumulates then integrates"){
+ using namespace kel;
+ using T = sch::Float64;
+ constexpr uint64_t D = 2u;
+ constexpr uint64_t PC = 2u;
+
+
+
+ kel::lbm::data<sch::Scalar<T>> radi,dense;
+ radi.at({}) = 1.0;
+ dense.at({}) = 1.0 / 3.14159265358979323846; // gives mass == 1
+ auto pgrp = lbm::create_spheroid_particle_group<T,D,PC>(radi,dense,{4u});
+
+ auto& rb = pgrp.template get<"particles">().at({0u}).template get<"rigid_body">();
+
+
+
+
+ lbm::reset_particle_accumulators<T,D>(pgrp.template get<"particles">().at({0u}));
+ SAW_EXPECT(rb.template get<"force">().at({{0u}}).get() == 0.0, "reset must zero force");
+
+ // Two contributors must sum, not overwrite each other.
+ auto& f = rb.template get<"force">();
+ f.at({{0u}}).set(f.at({{0u}}).get() + 3.0);
+ f.at({{0u}}).set(f.at({{0u}}).get() + 1.0);
+ SAW_EXPECT(f.at({{0u}}).get() == 4.0, "contributors must accumulate");
+
+ // mass == 1, so acceleration == force. One step of x = 2x - x_old + a dt^2.
+ (lbm::integrate_particle<T,D>)(pgrp.template get<"particles">().at({0u}), {}, {1u});
+ SAW_EXPECT(std::abs(rb.template get<"acceleration">().at({{0u}}).get() - 4.0) < 1e-9,
+ "acceleration must come from accumulated force");
+ SAW_EXPECT(std::abs(rb.template get<"position">().at({{0u}}).get() - 4.0) < 1e-9,
+ std::string{"expected x=4 after one unit step: "}
+ + std::to_string(rb.template get<"position">().at({{0u}}).get()));
+}
+
+SAW_TEST("Particle / zero sub steps still advances"){
+ using namespace kel;
+ using T = sch::Float64;
+ constexpr uint64_t D = 2u;
+ constexpr uint64_t PC = 1u;
+
+
+
+ kel::lbm::data<sch::Scalar<T>> radi,dense;
+ radi.at({}) = 1.0;
+ dense.at({}) = 1.0 / 3.14159265358979323846;
+ auto pgrp = lbm::create_spheroid_particle_group<T,D,PC>(radi,dense,{4u});
+
+ auto& rb = pgrp.template get<"particles">().at({0u}).template get<"rigid_body">();
+ rb.template get<"force">().at({{0u}}).set(2.0);
+
+
+
+ /**
+ * sub_steps == 0 used to give ts = 1/0 = inf and a loop that never ran,
+ * so the particle silently froze. Several examples pass {0u}.
+ */
+ (lbm::integrate_particle<T,D>)(pgrp.template get<"particles">().at({0u}), {}, {0u});
+
+ SAW_EXPECT(rb.template get<"position">().at({{0u}}).get() != 0.0,
+ "zero sub steps must still advance the particle");
+ SAW_EXPECT(std::isfinite(rb.template get<"position">().at({{0u}}).get()),
+ "position must stay finite");
+}
+
+namespace contact_fx {
+using T = sch::Float64;
+constexpr uint64_t D = 2u;
+
+template<uint64_t PC>
+auto make_group(double radius, double density){
+ kel::lbm::data<sch::Scalar<T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(density);
+ return kel::lbm::create_spheroid_particle_group<T,D,PC>(r,d,{4u});
+}
+
+template<typename G>
+void place(G& g, uint64_t i, double x, double y, double ox = 0.0, double oy = 0.0){
+ auto& rb = g.template get<"particles">().at({i}).template get<"rigid_body">();
+ rb.template get<"position">().at({{0u}}).set(x);
+ rb.template get<"position">().at({{1u}}).set(y);
+ rb.template get<"position_old">().at({{0u}}).set(x - ox);
+ rb.template get<"position_old">().at({{1u}}).set(y - oy);
+}
+}
+
+SAW_TEST("Contact / manifold geometry"){
+ using namespace kel;
+ using namespace contact_fx;
+
+ auto g = make_group<2u>(2.0, 1.0);
+ place(g, 0u, 0.0, 0.0);
+ place(g, 1u, 3.0, 0.0);
+
+ auto& parts = g.template get<"particles">();
+ kel::lbm::data<sch::ContactManifold<T,D>> m;
+
+ bool hit = (lbm::narrow_phase<lbm::coll::Spheroid<T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), m);
+
+ SAW_EXPECT(hit, "r=2,2 at distance 3 must be in contact");
+ SAW_EXPECT(std::abs(m.template get<"depth">().at({}).get() - 1.0) < 1e-12,
+ std::string{"depth: "} + std::to_string(m.template get<"depth">().at({}).get()));
+ // normal points from hi (particle 1, at +x) back toward lo (particle 0)
+ SAW_EXPECT(std::abs(m.template get<"normal">().at({{0u}}).get() + 1.0) < 1e-12,
+ "normal must point from hi toward lo");
+ SAW_EXPECT(std::abs(m.template get<"point">().at({{0u}}).get() - 1.5) < 1e-12,
+ std::string{"contact point x: "} + std::to_string(m.template get<"point">().at({{0u}}).get()));
+}
+
+SAW_TEST("Contact / exact antisymmetry"){
+ using namespace kel;
+ using namespace contact_fx;
+
+ auto g = make_group<2u>(2.0, 1.0);
+ // Approaching each other, off-axis so the tangential path is exercised.
+ place(g, 0u, 0.0, 0.3, 0.05, 0.0);
+ place(g, 1u, 3.0, 0.0, -0.05, 0.0);
+
+ lbm::dem_params<T> dem{10.0, 0.4, 2.0, 0.5};
+
+ auto& parts = g.template get<"particles">();
+ kel::lbm::data<sch::ContactManifold<T,D>> m;
+ bool hit = (lbm::narrow_phase<lbm::coll::Spheroid<T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), m);
+ SAW_EXPECT(hit, "expected contact");
+
+ auto r0 = (lbm::particle_contact_response<T,D>)(m, parts.at({0u}), parts.at({1u}), true, dem, {1u});
+ auto r1 = (lbm::particle_contact_response<T,D>)(m, parts.at({1u}), parts.at({0u}), false, dem, {1u});
+
+ /**
+ * Bitwise, not approximate. An epsilon here would hide exactly the
+ * ordering mistake this test exists to catch: if the two owners evaluate
+ * the pair in different orders the halves differ by a rounding step and
+ * every contact leaks momentum.
+ */
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(r0.force.at({{i}}).get() == -r1.force.at({{i}}).get(),
+ std::string{"force component "} + std::to_string(i) + " not exactly opposite: "
+ + std::to_string(r0.force.at({{i}}).get()) + " vs "
+ + std::to_string(r1.force.at({{i}}).get()));
+ }
+}
+
+SAW_TEST("Contact / never attracts"){
+ using namespace kel;
+ using namespace contact_fx;
+
+ auto g = make_group<2u>(2.0, 1.0);
+ // Overlapping but separating fast: the dashpot alone would pull them back.
+ place(g, 0u, 0.0, 0.0, -1.0, 0.0);
+ place(g, 1u, 3.0, 0.0, 1.0, 0.0);
+
+ lbm::dem_params<T> dem{1.0, 0.9, 0.0, 0.0};
+
+ auto& parts = g.template get<"particles">();
+ kel::lbm::data<sch::ContactManifold<T,D>> m;
+ (void)(lbm::narrow_phase<lbm::coll::Spheroid<T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), m);
+
+ auto r0 = (lbm::particle_contact_response<T,D>)(m, parts.at({0u}), parts.at({1u}), true, dem, {1u});
+
+ // Particle 0 sits at -x, so any push on it must be toward -x, never +x.
+ SAW_EXPECT(r0.force.at({{0u}}).get() <= 0.0,
+ std::string{"separating pair must not be pulled together: "}
+ + std::to_string(r0.force.at({{0u}}).get()));
+}
+
+SAW_TEST("Contact / degenerate pair stays finite"){
+ using namespace kel;
+ using namespace contact_fx;
+
+ auto g = make_group<2u>(2.0, 1.0);
+ // Exactly coincident centres: no geometric normal exists.
+ place(g, 0u, 5.0, 5.0);
+ place(g, 1u, 5.0, 5.0);
+
+ lbm::dem_params<T> dem{1.0, 0.3, 0.0, 0.0};
+
+ auto& parts = g.template get<"particles">();
+ kel::lbm::data<sch::ContactManifold<T,D>> m;
+ bool hit = (lbm::narrow_phase<lbm::coll::Spheroid<T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), m);
+ SAW_EXPECT(hit, "coincident centres are in contact");
+
+ auto r0 = (lbm::particle_contact_response<T,D>)(m, parts.at({0u}), parts.at({1u}), true, dem, {1u});
+
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(std::isfinite(r0.force.at({{i}}).get()),
+ "degenerate contact must not produce NaN");
+ }
+ // Penetration is capped at the smaller radius, not 2r.
+ SAW_EXPECT(std::abs(m.template get<"depth">().at({}).get() - 2.0) < 1e-12,
+ std::string{"depth should cap at the radius: "}
+ + std::to_string(m.template get<"depth">().at({}).get()));
+}
+
+SAW_TEST("Contact / pair loop conserves momentum"){
+ using namespace kel;
+ using namespace contact_fx;
+
+ auto g = make_group<2u>(2.0, 1.0);
+ place(g, 0u, 0.0, 0.4, 0.1, 0.0);
+ place(g, 1u, 3.0, 0.0, -0.1, 0.0);
+
+ lbm::dem_params<T> dem{10.0, 0.4, 1.0, 0.3};
+
+ auto& parts = g.template get<"particles">();
+ for(uint64_t i = 0u; i < 2u; ++i){
+ lbm::reset_particle_accumulators<T,D>(parts.at({i}));
+ }
+ for(uint64_t i = 0u; i < 2u; ++i){
+ (lbm::accumulate_particle_contacts<T,D>)(g.template get<"particles">(), i, dem, {1u});
+ }
+
+ // Each owner computed only its own half; the halves must cancel exactly.
+ for(uint64_t k = 0u; k < D; ++k){
+ auto f0 = parts.at({0u}).template get<"rigid_body">().template get<"force">().at({{k}}).get();
+ auto f1 = parts.at({1u}).template get<"rigid_body">().template get<"force">().at({{k}}).get();
+ SAW_EXPECT(f0 == -f1,
+ std::string{"net force must be zero in component "} + std::to_string(k)
+ + ": " + std::to_string(f0) + " vs " + std::to_string(f1));
+ }
+}
+
+SAW_TEST("Contact / wall soft shell"){
+ using namespace kel;
+ using namespace contact_fx;
+
+ auto g = make_group<1u>(2.0, 1.0);
+ // Overlapping the low x wall by 0.5, drifting further in.
+ place(g, 0u, 1.5, 10.0, -0.1, 0.0);
+
+ lbm::dem_params<T> dem{4.0, 0.0, 0.0, 0.0};
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,32u}};
+
+ auto& parts = g.template get<"particles">();
+ lbm::reset_particle_accumulators<T,D>(parts.at({0u}));
+ (lbm::accumulate_box_wall_contacts<T,D>)(parts.at({0u}), extent, dem, {1u});
+
+ auto fx = parts.at({0u}).template get<"rigid_body">().template get<"force">().at({{0u}}).get();
+ // Undamped: f = k * depth = 4 * 0.5 = 2, pushing inward (+x).
+ SAW_EXPECT(std::abs(fx - 2.0) < 1e-12,
+ std::string{"wall push: "} + std::to_string(fx));
+
+ // Well clear of every wall means no contact at all.
+ auto g2 = make_group<1u>(2.0, 1.0);
+ place(g2, 0u, 32.0, 16.0);
+ auto& p2 = g2.template get<"particles">();
+ lbm::reset_particle_accumulators<T,D>(p2.at({0u}));
+ (lbm::accumulate_box_wall_contacts<T,D>)(p2.at({0u}), extent, dem, {1u});
+ SAW_EXPECT(p2.at({0u}).template get<"rigid_body">().template get<"force">().at({{0u}}).get() == 0.0,
+ "a particle away from the walls must feel nothing");
+}
+
+SAW_TEST("Contact / corner touches both axes"){
+ using namespace kel;
+ using namespace contact_fx;
+
+ auto g = make_group<1u>(2.0, 1.0);
+ place(g, 0u, 1.0, 1.0); // inside both the low x and low y walls
+
+ lbm::dem_params<T> dem{4.0, 0.0, 0.0, 0.0};
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,32u}};
+
+ auto& parts = g.template get<"particles">();
+ lbm::reset_particle_accumulators<T,D>(parts.at({0u}));
+ (lbm::accumulate_box_wall_contacts<T,D>)(parts.at({0u}), extent, dem, {1u});
+
+ auto& f = parts.at({0u}).template get<"rigid_body">().template get<"force">();
+ SAW_EXPECT(f.at({{0u}}).get() > 0.0, "corner must push in +x");
+ SAW_EXPECT(f.at({{1u}}).get() > 0.0, "corner must push in +y");
+}
}
diff --git a/modules/core/tests/rotation.cpp b/modules/core/tests/rotation.cpp
new file mode 100644
index 0000000..e1e8c46
--- /dev/null
+++ b/modules/core/tests/rotation.cpp
@@ -0,0 +1,211 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/integrate.hpp"
+#include "../c++/particle/contact.hpp"
+#include "../c++/particle/mask.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 2u;
+
+template<uint64_t PC>
+auto make_group(double radius, double density){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(density);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,PC>(r,d,{16u});
+}
+
+SAW_TEST("Rotation / support flag matches the integrator"){
+ using namespace kel;
+
+ /**
+ * 3D rotation is deliberately absent rather than approximated: a scalar
+ * inertia only describes an isotropic body, and integrating the rotation
+ * vector as a displacement cannot represent non-commuting composition.
+ * The flag exists so torque accumulation and angular integration cannot
+ * drift apart -- accumulating a torque nothing consumes would be a silent
+ * no-op.
+ */
+ static_assert(lbm::particle_angular_supported<2u>, "2D rotation must be live");
+ static_assert(!lbm::particle_angular_supported<3u>, "3D rotation must stay gated");
+}
+
+SAW_TEST("Rotation / constant torque gives constant angular acceleration"){
+ using namespace kel;
+
+ /**
+ * Nothing in the library ever wrote angular_acceleration before contact
+ * started producing torque, so verlet_step_lambda's angular half had
+ * never actually run. This is the first exercise of that path.
+ */
+ auto g = make_group<1u>(2.0, 1.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+
+ auto inertia = rb.template get<"inertia">().at({}).get();
+ SAW_EXPECT(inertia > 0.0,
+ std::string{"inertia must be positive: "} + std::to_string(inertia));
+
+ // Pure torque, no force.
+ const double torque = 3.0;
+ rb.template get<"torque">().at({}).set(torque);
+
+ (lbm::integrate_particle<sch::T,D>)(p, {}, {1u});
+
+ auto ang_acc = rb.template get<"angular_acceleration">().at({}).get();
+ SAW_EXPECT(std::abs(ang_acc - torque / inertia) < 1e-12,
+ std::string{"angular acceleration should be torque/inertia: "}
+ + std::to_string(ang_acc));
+
+ // One unit step of theta = 2 theta - theta_old + alpha dt^2, from rest.
+ auto rot = rb.template get<"rotation">().at({}).get();
+ SAW_EXPECT(std::abs(rot - ang_acc) < 1e-12,
+ std::string{"rotation after one unit step should equal alpha: "}
+ + std::to_string(rot));
+}
+
+SAW_TEST("Rotation / spins up under sustained torque"){
+ using namespace kel;
+
+ auto g = make_group<1u>(2.0, 1.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+
+ auto inertia = rb.template get<"inertia">().at({}).get();
+ const double torque = 1.0;
+ const double alpha = torque / inertia;
+
+ // Hold the torque for 10 unit steps; position-Verlet from rest should
+ // track theta = alpha t^2 / 2.
+ for(uint64_t step = 0u; step < 10u; ++step){
+ rb.template get<"torque">().at({}).set(torque);
+ (lbm::integrate_particle<sch::T,D>)(p, {}, {1u});
+ }
+
+ auto rot = rb.template get<"rotation">().at({}).get();
+ auto expect = 0.5 * alpha * 10.0 * 10.0;
+
+ // Verlet from rest lags the closed form by about half a step of drift.
+ SAW_EXPECT(rot > 0.0, "must have spun up");
+ SAW_EXPECT(std::abs(rot - expect) / expect < 0.15,
+ std::string{"expected about "} + std::to_string(expect)
+ + " got " + std::to_string(rot));
+}
+
+SAW_TEST("Rotation / no torque means no spin"){
+ using namespace kel;
+
+ auto g = make_group<1u>(2.0, 1.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+
+ // Linear force only.
+ rb.template get<"force">().at({{0u}}).set(5.0);
+ (lbm::reset_particle_accumulators<sch::T,D>)(p);
+ rb.template get<"force">().at({{0u}}).set(5.0);
+
+ (lbm::integrate_particle<sch::T,D>)(p, {}, {4u});
+
+ SAW_EXPECT(rb.template get<"rotation">().at({}).get() == 0.0,
+ "a pure force must not induce spin");
+ SAW_EXPECT(rb.template get<"position">().at({{0u}}).get() > 0.0,
+ "but it must move the body");
+}
+
+SAW_TEST("Rotation / tangential contact produces torque"){
+ using namespace kel;
+
+ /**
+ * A glancing contact with friction must spin the bodies, and the two
+ * halves must be consistent: equal and opposite forces, with each torque
+ * taken about its own centre.
+ */
+ auto g = make_group<2u>(2.0, 1.0);
+ auto& parts = g.template get<"particles">();
+
+ auto place = [&](uint64_t i, double x, double y, double ox, double oy){
+ auto& rb = parts.at({i}).template get<"rigid_body">();
+ rb.template get<"position">().at({{0u}}).set(x);
+ rb.template get<"position">().at({{1u}}).set(y);
+ rb.template get<"position_old">().at({{0u}}).set(x - ox);
+ rb.template get<"position_old">().at({{1u}}).set(y - oy);
+ };
+
+ // Overlapping, sliding past each other along y.
+ place(0u, 0.0, 0.0, 0.0, 0.2);
+ place(1u, 3.0, 0.0, 0.0, -0.2);
+
+ lbm::dem_params<sch::T> dem{10.0, 0.2, 5.0, 0.8};
+
+ for(uint64_t i = 0u; i < 2u; ++i){
+ (lbm::reset_particle_accumulators<sch::T,D>)(parts.at({i}));
+ }
+ for(uint64_t i = 0u; i < 2u; ++i){
+ (lbm::accumulate_particle_contacts<sch::T,D>)(g.template get<"particles">(), i, dem, {1u});
+ }
+
+ auto t0 = parts.at({0u}).template get<"rigid_body">().template get<"torque">().at({}).get();
+ auto t1 = parts.at({1u}).template get<"rigid_body">().template get<"torque">().at({}).get();
+
+ SAW_EXPECT(std::abs(t0) > 0.0, "sliding contact must produce torque");
+
+ // Equal and opposite forces about mirrored lever arms means same-sign
+ // torque: both bodies are spun the same way by the shear between them.
+ SAW_EXPECT(t0 * t1 > 0.0,
+ std::string{"both bodies should spin the same way: "}
+ + std::to_string(t0) + " and " + std::to_string(t1));
+
+ // Linear halves still cancel exactly.
+ for(uint64_t k = 0u; k < D; ++k){
+ auto f0 = parts.at({0u}).template get<"rigid_body">().template get<"force">().at({{k}}).get();
+ auto f1 = parts.at({1u}).template get<"rigid_body">().template get<"force">().at({{k}}).get();
+ SAW_EXPECT(f0 == -f1, "linear momentum must still be conserved exactly");
+ }
+}
+
+SAW_TEST("Rotation / mask actually turns with the body"){
+ using namespace kel;
+
+ /**
+ * mask_local_to_global applies Rot(theta). Until torque existed, theta
+ * never changed, so this had no observable effect.
+ */
+ auto g = make_group<1u>(3.0, 1.0);
+ auto& p = g.template get<"particles">().at({0u});
+ auto& rb = p.template get<"rigid_body">();
+ rb.template get<"position">().at({{0u}}).set(20.0);
+ rb.template get<"position">().at({{1u}}).set(20.0);
+
+ auto& com = g.template get<"center_of_mass">().at({0u});
+
+ // A point on the local +x axis.
+ kel::lbm::data<sch::Vector<sch::T,D>> u;
+ u.at({{0u}}).set(1.0);
+ u.at({{1u}}).set(0.0);
+
+ rb.template get<"rotation">().at({}).set(0.0);
+ auto x0 = (lbm::mask_local_to_global<sch::T,D>)(u,p,com);
+
+ // Quarter turn: +x should swing to +y.
+ rb.template get<"rotation">().at({}).set(3.14159265358979323846 / 2.0);
+ auto x90 = (lbm::mask_local_to_global<sch::T,D>)(u,p,com);
+
+ SAW_EXPECT(std::abs(x0.at({{0u}}).get() - 23.0) < 0.05,
+ std::string{"unrotated should sit at +radius in x: "}
+ + std::to_string(x0.at({{0u}}).get()));
+ SAW_EXPECT(std::abs(x90.at({{1u}}).get() - 23.0) < 0.05,
+ std::string{"quarter turn should sit at +radius in y: "}
+ + std::to_string(x90.at({{1u}}).get()));
+ SAW_EXPECT(std::abs(x90.at({{0u}}).get() - 20.0) < 0.05,
+ "and back on the centre line in x");
+}
+}
diff --git a/modules/core/tests/voxel_narrow.cpp b/modules/core/tests/voxel_narrow.cpp
new file mode 100644
index 0000000..5cffc76
--- /dev/null
+++ b/modules/core/tests/voxel_narrow.cpp
@@ -0,0 +1,191 @@
+#include <forstio/test/suite.hpp>
+
+#include <cmath>
+#include <iostream>
+
+#include "../c++/particle/particle.hpp"
+#include "../c++/particle/voxel_narrow.hpp"
+
+namespace {
+namespace sch {
+using namespace kel::lbm::sch;
+using T = Float64;
+}
+
+constexpr uint64_t D = 2u;
+
+auto make_pair(double radius, uint64_t res = 32u){
+ kel::lbm::data<sch::Scalar<sch::T>> r,d;
+ r.at({}).set(radius);
+ d.at({}).set(1.0);
+ return kel::lbm::create_spheroid_particle_group<sch::T,D,2u>(r,d,{res});
+}
+
+template<typename G>
+void place(G& g, uint64_t i, double x, double y){
+ auto& pos = g.template get<"particles">().at({i})
+ .template get<"rigid_body">().template get<"position">();
+ pos.at({{0u}}).set(x);
+ pos.at({{1u}}).set(y);
+}
+
+SAW_TEST("VoxelNarrow / depth matches the analytic oracle"){
+ using namespace kel;
+
+ /**
+ * For spheres the answer is known exactly: delta = r_lo + r_hi - |d|.
+ * The voxel result should land within about a voxel pitch of it. This is
+ * the check that the overlap integral is measuring what it claims to.
+ */
+ const double radius = 6.0;
+ auto g = make_pair(radius);
+ auto& parts = g.template get<"particles">();
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,64u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.0);
+
+ for(int step = 1; step <= 4; ++step){
+ double sep = 2.0 * radius - step * 1.5;
+ place(g, 0u, 32.0 - sep/2.0, 32.0);
+ place(g, 1u, 32.0 + sep/2.0, 32.0);
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m;
+ bool hit = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,m);
+ SAW_EXPECT(hit, "expected an overlap");
+
+ double expect = 2.0 * radius - sep;
+ double got = m.template get<"depth">().at({}).get();
+
+ SAW_EXPECT(std::abs(got - expect) < 1.6,
+ std::string{"sep="} + std::to_string(sep) + " expected depth "
+ + std::to_string(expect) + " got " + std::to_string(got));
+ }
+}
+
+SAW_TEST("VoxelNarrow / normal points hi to lo"){
+ using namespace kel;
+
+ const double radius = 6.0;
+ auto g = make_pair(radius);
+ auto& parts = g.template get<"particles">();
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,64u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.0);
+
+ place(g, 0u, 28.0, 32.0);
+ place(g, 1u, 36.0, 32.0);
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m;
+ bool hit = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,m);
+ SAW_EXPECT(hit, "expected an overlap");
+
+ auto& n = m.template get<"normal">();
+ SAW_EXPECT(n.at({{0u}}).get() < -0.9,
+ std::string{"normal x should be about -1: "} + std::to_string(n.at({{0u}}).get()));
+ SAW_EXPECT(std::abs(n.at({{1u}}).get()) < 0.1,
+ std::string{"normal y should be about 0: "} + std::to_string(n.at({{1u}}).get()));
+
+ // Contact point sits between the two centres.
+ auto px = m.template get<"point">().at({{0u}}).get();
+ SAW_EXPECT(px > 28.0 && px < 36.0,
+ std::string{"contact point x out of range: "} + std::to_string(px));
+}
+
+SAW_TEST("VoxelNarrow / exactly antisymmetric under pair swap"){
+ using namespace kel;
+
+ /**
+ * The reason the lattice is swept rather than either particle's local
+ * grid: both owners must visit identical points in identical order, so
+ * the two halves of the pair cancel bitwise. Sampling on a particle-local
+ * grid would make the sample set depend on which particle you started
+ * from, and every contact would leak a little momentum.
+ */
+ const double radius = 5.0;
+ auto g = make_pair(radius);
+ auto& parts = g.template get<"particles">();
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,64u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.0);
+
+ // Off-axis, so a symmetry accident cannot hide a real asymmetry.
+ place(g, 0u, 29.0, 30.0);
+ place(g, 1u, 36.0, 33.5);
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m01, m10;
+ bool a = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,m01);
+ bool b = (lbm::voxel_contact<sch::T,D>)(g,parts.at({1u}),parts.at({0u}),extent,eps,m10);
+
+ SAW_EXPECT(a && b, "both orderings must find the contact");
+
+ SAW_EXPECT(m01.template get<"depth">().at({}).get() == m10.template get<"depth">().at({}).get(),
+ "depth must be identical under swap");
+
+ for(uint64_t i = 0u; i < D; ++i){
+ SAW_EXPECT(m01.template get<"normal">().at({{i}}).get()
+ == -m10.template get<"normal">().at({{i}}).get(),
+ std::string{"normal component "} + std::to_string(i) + " not exactly opposite");
+ SAW_EXPECT(m01.template get<"point">().at({{i}}).get()
+ == m10.template get<"point">().at({{i}}).get(),
+ std::string{"contact point component "} + std::to_string(i) + " must match");
+ }
+}
+
+SAW_TEST("VoxelNarrow / separated bodies report nothing"){
+ using namespace kel;
+
+ auto g = make_pair(4.0);
+ auto& parts = g.template get<"particles">();
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,64u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.0);
+
+ place(g, 0u, 16.0, 32.0);
+ place(g, 1u, 48.0, 32.0);
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> m;
+ SAW_EXPECT(!(lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,m),
+ "well separated bodies must not report a contact");
+}
+
+SAW_TEST("VoxelNarrow / agrees with the analytic narrow phase"){
+ using namespace kel;
+
+ /**
+ * Same bodies, two independent routes to a manifold. They should agree on
+ * direction closely and on depth to within the voxel pitch; if they do
+ * not, one of the two is wrong about the geometry.
+ */
+ const double radius = 6.0;
+ auto g = make_pair(radius);
+ auto& parts = g.template get<"particles">();
+
+ kel::lbm::data<sch::FixedArray<sch::UInt64,D>> extent{{64u,64u}};
+ kel::lbm::data<sch::Scalar<sch::T>> eps;
+ eps.at({}).set(1.0);
+
+ place(g, 0u, 29.0, 31.0);
+ place(g, 1u, 36.0, 33.0);
+
+ kel::lbm::data<sch::ContactManifold<sch::T,D>> mv, ma;
+ bool hv = (lbm::voxel_contact<sch::T,D>)(g,parts.at({0u}),parts.at({1u}),extent,eps,mv);
+ bool ha = (lbm::narrow_phase<lbm::coll::Spheroid<sch::T>>::template contact<D>)(
+ parts.at({0u}), parts.at({1u}), ma);
+
+ SAW_EXPECT(hv && ha, "both narrow phases must find the contact");
+
+ auto dot = mv.template get<"normal">().at({{0u}}).get() * ma.template get<"normal">().at({{0u}}).get()
+ + mv.template get<"normal">().at({{1u}}).get() * ma.template get<"normal">().at({{1u}}).get();
+ SAW_EXPECT(dot > 0.97,
+ std::string{"normals should nearly agree, dot = "} + std::to_string(dot));
+
+ auto diff = std::abs(mv.template get<"depth">().at({}).get()
+ - ma.template get<"depth">().at({}).get());
+ SAW_EXPECT(diff < 1.6,
+ std::string{"depths disagree by "} + std::to_string(diff));
+}
+}