particle Namespace Reference

Collection of methods and data related to particle object. More...

Data Structures
class	BaseParticle
	A class to store particle geometry, nodal discretization, and methods. More...
class	RefParticle
	A class to store reference particle related data. Consider a case of multiple hexagon-shaped particle related to each other by affine transformation. In such a case, it is possible to consider a reference hexagon particle and store the mesh and other details of only the reference particle. To get the data relevant to specific hexagon particle, one can apply the appropriate transformation on data for the reference hexagon particle. More...

Functions
void	createReferenceParticles (data::ModelData &data)
	Build reference meshes from the particle deck (no placement).
void	createParticlesFromFile (data::ModelData &data)
	Place particles from generation-file data; refs must already exist.
void	createParticleUsingParticleZoneGeomObject (data::ModelData &data)
	Place one particle per zone geometry; refs must already exist.
void	createParticles (data::ModelData &data)
	Build refs then place particles according to the generation method.
bool	isLocallyOwned (const BaseParticle &p)
	True if this rank updates / assembles forces for the particle. Walls are replicated on every rank. With one MPI rank, everything is local.
std::string	resolvedMpiStrategy (const data::ModelData &data)
	Resolved MPI strategy: none|particle|dof (auto expanded).
void	assignMpiOwners (data::ModelData &data)
	Assign grain owners by spatial 2D brick decomposition of centers. Walls get owner -1 (all ranks). Honors Model.MPI_Strategy.
void	exchangeGhostKinematics (data::ModelData &data)
	Distance-limited ghosts + kinematics exchange. Rebuilds the ghost plan on a Verlet-skin cadence (tied to contact neigh interval when available); between rebuilds only exchanges kinematics for the cached ghost set via Alltoallv.

Detailed Description

Collection of methods and data related to particle object.

Function Documentation

assignMpiOwners()

void particle::assignMpiOwners

(

data::ModelData &

data

)

Assign grain owners by spatial 2D brick decomposition of centers. Walls get owner -1 (all ranks). Honors Model.MPI_Strategy.

Definition at line 313 of file particleMpi.cpp.

                                                  {
  const int size = util::parallel::mpiSize();
  const int rank = util::parallel::mpiRank();
  const auto &grains = data.d_particlesListTypeParticle;
  const std::string strategy = resolvedMpiStrategy(data);
 
  for (auto *p : data.d_particlesListTypeAll) {
    if (p->isWall())
      p->d_mpiOwner = -1;
  }
 
  // Particle-MPI only: spatial brick over grain centers.
  // DOF-MPI assigns nodes in pd::setupDofPartition; do not also brick grains.
  const bool use_particle_partition =
      strategy == "particle" && size > 1 && !grains.empty();
 
  if (!use_particle_partition) {
    for (auto *p : grains)
      p->d_mpiOwner = 0;
    if (util::parallel::isMpiEnabled() && rank == 0)
      util::io::print(std::format(
          "MPI strategy={}: grain ownership inactive (all grains → rank 0)\n",
          strategy));
  } else {
    double xmin = std::numeric_limits<double>::max();
    double xmax = -std::numeric_limits<double>::max();
    double ymin = std::numeric_limits<double>::max();
    double ymax = -std::numeric_limits<double>::max();
    for (auto *p : grains) {
      const auto &c = p->getXCenter();
      xmin = std::min(xmin, c.d_x);
      xmax = std::max(xmax, c.d_x);
      ymin = std::min(ymin, c.d_y);
      ymax = std::max(ymax, c.d_y);
    }
    const double Lx = std::max(xmax - xmin, 1.0e-16);
    const double Ly = std::max(ymax - ymin, 1.0e-16);
    int nx = 1, ny = size;
    factor2d(size, Lx, Ly, nx, ny);
 
    const double eps = 1.0e-14 * std::max(Lx, Ly);
    for (auto *p : grains) {
      const auto &c = p->getXCenter();
      int ix = static_cast<int>((c.d_x - xmin) / Lx * nx);
      int iy = static_cast<int>((c.d_y - ymin) / Ly * ny);
      if (ix < 0)
        ix = 0;
      if (iy < 0)
        iy = 0;
      if (ix >= nx)
        ix = nx - 1;
      if (iy >= ny)
        iy = ny - 1;
      // nudge points on the max edge into the last cell
      (void)eps;
      p->d_mpiOwner = iy * nx + ix;
    }
 
    if (util::parallel::isMpiEnabled() && rank == 0)
      util::io::print(std::format(
          "MPI spatial owners: {} ranks as {}x{} brick over [{:.3g},{:.3g}] x "
          "[{:.3g},{:.3g}]\n",
          size, nx, ny, xmin, xmax, ymin, ymax));
  }
 
  data.d_mpiIncludeInContactCloud.assign(data.d_particlesListTypeAll.size(), 1);
  data.d_mpiGhostPlanValid = false;
  data.d_mpiGhostStepsSinceRebuild = 0;
  data.d_mpiGhostNeedFrom.clear();
  data.d_mpiGhostServeTo.clear();
 
  if (util::parallel::isMpiEnabled()) {
    size_t n_local = 0;
    for (auto *p : grains)
      if (isLocallyOwned(*p))
        ++n_local;
    util::io::print(std::format(
        "MPI particle owners: rank {}/{} owns {}/{} grains (walls replicated)\n",
        rank, size, n_local, grains.size()));
  }
}

References anonymous_namespace{particleMpi.cpp}::factor2d(), isLocallyOwned(), util::parallel::isMpiEnabled(), util::parallel::mpiRank(), util::parallel::mpiSize(), util::io::print(), and resolvedMpiStrategy().

Referenced by PeriDEMModel::init().

Here is the call graph for this function:

Here is the caller graph for this function:

createParticles()

void particle::createParticles

(

data::ModelData &

data

)

Build refs then place particles according to the generation method.

Definition at line 182 of file createParticles.cpp.

                                                  {
  createReferenceParticles(data);
 
  if (data.d_particleDeck_p->d_pGenDeck.d_genMethod == "From_File") {
    createParticlesFromFile(data);
  } else if (data.d_particleDeck_p->d_pGenDeck.d_genMethod ==
             "Use_Particle_Geometry") {
    createParticleUsingParticleZoneGeomObject(data);
  } else {
    throw std::runtime_error(
        "Error: Particle generation method = " +
        data.d_particleDeck_p->d_pGenDeck.d_genMethod + " is invalid.");
  }
}

References createParticlesFromFile(), createParticleUsingParticleZoneGeomObject(), and createReferenceParticles().

Referenced by PeriDEMModel::init().

Here is the call graph for this function:

Here is the caller graph for this function:

createParticlesFromFile()

void particle::createParticlesFromFile

(

data::ModelData &

data

)

Place particles from generation-file data; refs must already exist.

Definition at line 61 of file createParticles.cpp.

                                                          {
  util::io::log(1, data.d_name + ": Creating particle from file\n");
 
  auto &pgen_deck = data.d_particleDeck_p->d_pGenDeck;
  auto &pgen_json = pgen_deck.d_pGenJson;
 
  util::DistributionSample<UniformDistribution> uniform_dist(
      0., 1., data.d_modelDeck_p->d_seed);
 
  size_t num_particles = pgen_json.value("N", 0);
  if (num_particles == 0)
    throw std::runtime_error("No particles found in particle generation data");
 
  auto model_ptr = modelAlias(data);
 
  for (size_t i = 0; i < num_particles; i++) {
    auto p_data = pgen_json.at(std::to_string(i));
 
    std::map<std::string, size_t> p_group({
        {"geom_id", p_data.at("geom_id").get<size_t>()},
        {"mat_id", p_data.at("mat_id").get<size_t>()},
        {"contact_id", p_data.at("contact_id").get<size_t>()},
    });
 
    auto site = util::Point(p_data.at("x").get<double>(),
                            p_data.at("y").get<double>(),
                            p_data.at("z").get<double>());
 
    double angle = 0.;
    double scale = p_data.value("s", double(1.));
 
    if (p_data.find("theta") != p_data.end()) {
      angle = p_data.at("theta").get<double>();
    } else {
      if (pgen_deck.d_genWithRandomRotation) {
        angle = util::transform_to_uniform_dist(0., 2. * M_PI, uniform_dist());
      }
    }
 
    auto axis = util::Point(p_data.value("ax", 0.), p_data.value("ay", 0.),
                            p_data.value("az", 1.));
    const bool has_rotationPoint =
        p_data.find("rotx") != p_data.end() &&
        p_data.find("roty") != p_data.end() &&
        p_data.find("rotz") != p_data.end();
 
    auto &ref_p = data.d_referenceParticles[p_group["geom_id"]];
    const auto &rep_geom_p = ref_p->d_geom_p;
 
    std::shared_ptr<geom::GeomObject> p_geom(
        geom::createGeomDeepCopy(rep_geom_p.get()));
    const util::Point c0 = p_geom->center();
    const util::Point t = site - c0;
    util::Point rotationPivot =
        has_rotationPoint
            ? util::Point(p_data.value("rotx", 0.), p_data.value("roty", 0.),
                          p_data.value("rotz", 0.))
            : c0;
    p_geom->transform(t, scale, angle, axis, &rotationPivot);
 
    auto p_transform =
        geom::ParticleTransform(t, axis, angle, scale, rotationPivot);
 
    const bool is_wall = p_data.value("is_wall", false);
 
    auto p = new particle::BaseParticle(
        data.d_particlesListTypeAll.size(), is_wall, ref_p->getDimension(),
        p_group, false, ref_p->getNumNodes(), 0., model_ptr, ref_p, p_geom,
        p_transform, ref_p->getMeshP(),
        data.d_particleDeck_p->d_pMaterialVec[p_group["mat_id"]], true);
 
    if (is_wall)
      data.d_particlesListTypeWall.push_back(p);
    else
      data.d_particlesListTypeParticle.push_back(p);
    data.d_particlesListTypeAll.push_back(p);
  }
}

References geom::createGeomDeepCopy(), util::io::log(), anonymous_namespace{createParticles.cpp}::modelAlias(), and util::transform_to_uniform_dist().

Referenced by createParticles().

Here is the call graph for this function:

Here is the caller graph for this function:

createParticleUsingParticleZoneGeomObject()

void particle::createParticleUsingParticleZoneGeomObject

(

data::ModelData &

data

)

Place one particle per zone geometry; refs must already exist.

Definition at line 38 of file createParticles.cpp.

                                                                            {
  util::io::log(1, data.d_name + ": Creating particle using Particle Zone Geometry Object\n");
 
  auto p_transform = geom::ParticleTransform();
  auto model_ptr = modelAlias(data);
 
  for (size_t z = 0; z < data.d_particleDeck_p->d_pMeshVec.size(); z++) {
    std::map<std::string, size_t> p_group(
        {{"geom_id", z}, {"mat_id", 0}, {"contact_id", 0}});
 
    auto ref_p = data.d_referenceParticles[z];
 
    auto p = new particle::BaseParticle(
        data.d_particlesListTypeAll.size(), false, ref_p->getDimension(),
        p_group, false, ref_p->getNumNodes(), 0., model_ptr, ref_p,
        ref_p->getGeomP(), p_transform, ref_p->getMeshP(),
        data.d_particleDeck_p->d_pMaterialVec[0], true);
 
    data.d_particlesListTypeParticle.push_back(p);
    data.d_particlesListTypeAll.push_back(p);
  }
}

References util::io::log(), and anonymous_namespace{createParticles.cpp}::modelAlias().

Referenced by createParticles().

Here is the call graph for this function:

Here is the caller graph for this function:

createReferenceParticles()

void particle::createReferenceParticles

(

data::ModelData &

data

)

Build reference meshes from the particle deck (no placement).

Definition at line 140 of file createParticles.cpp.

                                                           {
  data.d_particlesListTypeParticle.resize(0);
  data.d_particlesListTypeAll.resize(0);
  data.d_particlesListTypeWall.resize(0);
  data.d_referenceParticles.clear();
 
  if (data.d_particleDeck_p->d_pGeomVec.size() == 0)
    throw std::runtime_error(
        "No particle geometry groups found in particle deck");
 
  if (data.d_particleDeck_p->d_pGeomVec.size() !=
      data.d_particleDeck_p->d_pMeshVec.size())
    throw std::runtime_error(
        "Number of particle geometry groups must be equal to number of "
        "particle mesh groups");
 
  auto model_ptr = modelAlias(data);
 
  for (size_t z = 0; z < data.d_particleDeck_p->d_pMeshVec.size(); z++) {
    auto &zmeshDeck = data.d_particleDeck_p->d_pMeshVec[z];
    auto &zgeomDeck = data.d_particleDeck_p->d_pGeomVec[z];
 
    util::io::log(0, data.d_name +
                   ": Creating mesh for reference particle in mesh group = " +
                   std::to_string(z) + "\n");
 
    auto mesh = mesh_gen::createParticleMesh(
        zmeshDeck, zgeomDeck, data.d_modelDeck_p.get(), data.d_name);
 
    util::io::log(0, data.d_name +
                   ": Creating reference particle in mesh group = " +
                   std::to_string(z) + "\n");
 
    auto &rep_geom_p = zgeomDeck.d_geom_p;
 
    auto ref_p = std::make_shared<particle::RefParticle>(
        data.d_referenceParticles.size(), model_ptr, rep_geom_p, mesh);
 
    data.d_referenceParticles.emplace_back(ref_p);
  }
}

References mesh_gen::createParticleMesh(), util::io::log(), and anonymous_namespace{createParticles.cpp}::modelAlias().

Referenced by createParticles().

Here is the call graph for this function:

Here is the caller graph for this function:

exchangeGhostKinematics()

void particle::exchangeGhostKinematics

(

data::ModelData &

data

)

Distance-limited ghosts + kinematics exchange. Rebuilds the ghost plan on a Verlet-skin cadence (tied to contact neigh interval when available); between rebuilds only exchanges kinematics for the cached ghost set via Alltoallv.

Definition at line 395 of file particleMpi.cpp.

                                                          {
  if (!util::parallel::isMpiEnabled()) {
    data.d_mpiIncludeInContactCloud.assign(data.d_particlesListTypeAll.size(),
                                           1);
    return;
  }
 
  // Particle-MPI only. DOF-MPI owns nodes, not whole grains; grain packing
  // from the "grain owner" rank would overwrite remote-owned nodal u/v with
  // stale zeros. Nodal sync lives in pd::exchangeGhostDisplacement.
  if (data.d_pdDofMpi || resolvedMpiStrategy(data) == "dof") {
    data.d_mpiIncludeInContactCloud.assign(data.d_particlesListTypeAll.size(),
                                           1);
    return;
  }
 
  using clock = std::chrono::steady_clock;
  const auto t0 = clock::now();
 
  const size_t interval = ghostRebuildInterval(data);
  int local_need =
      (!data.d_mpiGhostPlanValid ||
       data.d_mpiGhostStepsSinceRebuild >= interval)
          ? 1
          : 0;
  // All ranks must take the same branch: rebuild uses Allgather, exchange uses
  // Alltoall — disagreeing on rebuild deadlocks (seen past ~50% with contact).
  int global_need = local_need;
  MPI_Allreduce(MPI_IN_PLACE, &global_need, 1, MPI_INT, MPI_MAX,
                util::parallel::mpiComm());
  const bool need_rebuild = global_need != 0;
 
  auto t_rebuild0 = t0;
  auto t_rebuild1 = t0;
  if (need_rebuild) {
    t_rebuild0 = clock::now();
    rebuildGhostPlan(data);
    t_rebuild1 = clock::now();
  }
 
  const auto t_ex0 = clock::now();
  exchangeCachedKinematics(data);
  const auto t1 = clock::now();
 
  ++data.d_mpiGhostStepsSinceRebuild;
 
  data.appendKeyData("mpi_ghost_select_time",
                     util::methods::timeDiff(t_rebuild0, t_rebuild1));
  data.appendKeyData("mpi_halo_exchange_time",
                     util::methods::timeDiff(t_ex0, t1));
  data.appendKeyData("mpi_exchange_time", util::methods::timeDiff(t0, t1));
  data.setKeyData("mpi_ghost_rebuild", need_rebuild ? 1.0 : 0.0);
}

References anonymous_namespace{particleMpi.cpp}::exchangeCachedKinematics(), anonymous_namespace{particleMpi.cpp}::ghostRebuildInterval(), util::parallel::isMpiEnabled(), util::parallel::mpiComm(), anonymous_namespace{particleMpi.cpp}::rebuildGhostPlan(), resolvedMpiStrategy(), and util::methods::timeDiff().

Referenced by PeriDEMModel::computeForces().

Here is the call graph for this function:

Here is the caller graph for this function:

isLocallyOwned()

bool particle::isLocallyOwned

(

const BaseParticle &

p

)

True if this rank updates / assembles forces for the particle. Walls are replicated on every rank. With one MPI rank, everything is local.

Definition at line 28 of file particleMpi.cpp.

                                                   {
  if (!util::parallel::isMpiEnabled())
    return true;
  if (p.isWall())
    return true;
  return p.d_mpiOwner == util::parallel::mpiRank();
}

References particle::BaseParticle::d_mpiOwner, util::parallel::isMpiEnabled(), particle::BaseParticle::isWall(), and util::parallel::mpiRank().

Referenced by rw::writer::VtkParticleWriter::appendMeshParallelPiece(), contact::Damping::apply(), assignMpiOwners(), PeriDEMModel::computeExternalForces(), PeriDEMModel::init(), anonymous_namespace{main.cpp}::GrainContactProbe::ownsNode(), anonymous_namespace{main.cpp}::ownsNode(), MpiMetricTsProbe::ownsNode(), and anonymous_namespace{particleMpi.cpp}::rebuildGhostPlan().

Here is the call graph for this function:

Here is the caller graph for this function:

resolvedMpiStrategy()

std::string particle::resolvedMpiStrategy

(

const data::ModelData &

data

)

Resolved MPI strategy: none|particle|dof (auto expanded).

Definition at line 36 of file particleMpi.cpp.

                                                                 {
  std::string s = "auto";
  if (data.d_input_p && data.d_input_p->d_modelDeck_p)
    s = data.d_input_p->d_modelDeck_p->d_mpiStrategy;
  if (s.empty())
    s = "auto";
  if (s == "auto") {
    if (data.d_input_p && data.d_input_p->isMultiParticle())
      return "particle";
    return "dof";
  }
  return s;
}

Referenced by assignMpiOwners(), exchangeGhostKinematics(), and pd::setupDofPartition().

Here is the caller graph for this function: