Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
AdaptiveSparseContacts< dim, PropertiesIndex > Class Template Reference

#include <adaptive_sparse_contacts.h>

Public Types

enum  mobility_status : unsigned int {
  inactive = 0 , static_active = 1 , advected = 2 , advected_active = 3 ,
  mobile = 4 , empty = 5
}

Public Member Functions

 AdaptiveSparseContacts ()
void set_parameters (const double granular_temperature, const double solid_fraction, const bool advect_particles)
void update_local_and_ghost_cell_set (const DoFHandler< dim > &background_dh)
void update_average_velocities_acceleration (Particles::ParticleHandler< dim > &particle_handler, const Tensor< 1, 3 > &g, const std::vector< Tensor< 1, 3 > > &force, const double dt)
void identify_mobility_status (const DoFHandler< dim > &background_dh, const Particles::ParticleHandler< dim > &particle_handler, const unsigned int n_active_cells, MPI_Comm mpi_communicator)
void map_periodic_nodes (const AffineConstraints< double > &constraints)
unsigned int check_cell_mobility (const typename Triangulation< dim >::active_cell_iterator &cell) const
void get_mobility_status_vector (Vector< float > &status)
DEM::dem_data_structures< dim >::cell_index_int_map & get_mobility_status ()
std::map< typename Triangulation< dim >::active_cell_iterator, std::pair< Tensor< 1, 3 >, Tensor< 1, 3 > > > & get_velocities_accelerations ()
bool has_advected_particles () const

Private Member Functions

void calculate_granular_temperature_and_solid_fraction (const Particles::ParticleHandler< dim > &particle_handler, const std::set< typename DoFHandler< dim >::active_cell_iterator > &local_and_ghost_cells_with_particles, Vector< double > &cell_granular_temperature, Vector< double > &cell_solid_fraction)
void assign_mobility_status (unsigned int cell_id, const std::vector< types::global_dof_index > &dof_indices, const int cell_status, const int node_status)
void assign_mobility_status (unsigned int cell_id, const int cell_status)

Private Attributes

std::set< typename DoFHandler< dim >::active_cell_iterator > local_and_ghost_cells
DEM::dem_data_structures< dim >::cell_index_int_map cell_mobility_status
LinearAlgebra::distributed::Vector< int > mobility_at_nodes
std::unordered_map< unsigned int, unsigned int > periodic_node_ids
std::map< typename Triangulation< dim >::active_cell_iterator, std::pair< Tensor< 1, 3 >, Tensor< 1, 3 > > > cell_velocities_accelerations
bool sparse_contacts_enabled
bool advect_particles_enabled
double granular_temperature_threshold
double solid_fraction_threshold

Detailed Description

template<int dim, typename PropertiesIndex>
class AdaptiveSparseContacts< dim, PropertiesIndex >

Mechanism that disables contacts computation through mobility status of cells based on granular temperature.

The general idea behind the algorithm:

It uses the granular temperature to determinate if particles in a cell are sufficiently mobile that the contact forces are worth computation. A cell having a granular temperature under a threshold (default is 1e-4) will have an inactive or advected status which makes them rejected in the broad search step. There is also an extra layer of mobile cells around the current mobile cells to propagate the motion of particles. Additionally, there is another layer of cells around those mobile cells that are flagged as static_active or advected_active cells.

While the inactive status makes the particles static (no further handling), the advected status will lead to computation and application of a cell-averaged advected term. This term is computed from the last average velocity and acceleration of the particles when the cell had a mobile status, or at the first DEM time step of a CFD iteration in CFD-DEM (ensures an update of the hydrodynamic forces). Those forces are reapplied after each DEM time step.

Particles in cells with an inactive status results in skipping the fine contact search, the p-p & p-w forces computation and the velocity and position update. It reduces the computational cost of the simulation when particles are not moving.

Particles in cells with an advected status results in skipping the fine contact search, the p-p & p-w forces computations, but they do have a velocity and position update through the advection term. This is critical for CFD-DEM.

In summary, cells are flagged using a mobility status:

  • mobile (all contacts are calculated, same as if the feature is not enabled)
  • static_active (particles with low velocity variance next to mobile particles)
  • advected_active (same as above but particles will be advected)
  • inactive (particles next to mobile particles that allow one way contact forces calculation, not computation of collision pair in the cell)
  • advected (same as above, but particles will be advected)

There are some edge cases that need some attention. In these cases, particles in cells cannot be deactivated:

  1. Solid fraction The solid fraction of the cell is under a value (default = 40%): particles in the cell are not consolidated (packed) and may move freely.
  2. Empty cell neighbor Cell having empty cell neighbor: it means that particles are next to a floating wall/mesh, and they may have a change of contact forces from it if the wall moves or disappears.
  3. Additional mobile cell layer The cell has at least one cell neighbor flagged as mobile from the 3 criteria mentioned above (granular temperature, solid fractions or floating walls): this is because motion is badly propagated to particles to the cell around without this additional "layer" of mobile cells.
  4. Active cell layer The cell has at least one cell neighbor flagged as mobile from the previous criterion (additional layer of mobile cells): again, this is to allow the motion propagation, but only the particles in contact with particles from the mobile cells are considered for the contact force calculation but their position is not computed at the integration step. Those cells are flagged as active cells. It works with the assignment and verification of the mobility status at nodes to check the status of the neighboring cells.
Template Parameters
dimAn integer that denotes the number of spatial dimensions.
PropertiesIndexIndex of the properties used within the ParticleHandler.

Definition at line 103 of file adaptive_sparse_contacts.h.

Member Enumeration Documentation

◆ mobility_status

template<int dim, typename PropertiesIndex>
enum AdaptiveSparseContacts::mobility_status : unsigned int

Mobility status flags used to identify the status at nodes and the status of the cell:

inactive (0) The motion of particles in the cell is considered as negligible, particles within this cell are not considered in the contact detection (rejected at the broad search step), so no force calculation or integration is applied

static_active (1) The motion of particles in the cell is considered as negligible, but there's at least one neighbor cell that is flagged as mobile, meaning that particles need to be in contact candidates lists at the broad search step, particles directly in contact with the mobile cell are also considered in force calculation, but none of the particles in the cell are integrated.

advected (2) The variance of the velocity of the particles in cell is low, suggesting that contact forces are negligible but particles are advected by other forces. Note that there are currently no mechanisms that distinct active vs advected status: advection of particles is a user-defined feature. Advected and active status are detected in the same way, but are not processed the same at the velocity integration step. For advected particles, the last computed cell-averaged velocity and acceleration is used to advect the particles.

advected_active (3) Same as (1), but particles are advected by the last computed cell-averaged velocity and acceleration.

mobile (4) The motion of particles in the cell is significant or there is at least one cell neighbor that is mobile by criteria (see the identify_mobility_status() description), particles need to be in contact candidate lists at the broad search step and particles are treated as usual (force calculation and integration)

empty (5) This status is only used for the node-based mobility status identification, no cells are flagged as empty, only node can be identified as empty. Without this identification of the empty cells, we cannot identify the cell that have an empty neighbor cell, which is critical for simulations using floating walls or mesh.

Enumerator
inactive 
static_active 
advected 
advected_active 
mobile 
empty 

Definition at line 154 of file adaptive_sparse_contacts.h.

Constructor & Destructor Documentation

◆ AdaptiveSparseContacts()

template<int dim, typename PropertiesIndex>
AdaptiveSparseContacts< dim, PropertiesIndex >::AdaptiveSparseContacts ( )

Member Function Documentation

◆ assign_mobility_status() [1/2]

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::assign_mobility_status ( unsigned int cell_id,
const int cell_status )
inlineprivate

Assign the mobility status to the cell. No need to update the node status. Only use for active status assignment since nodes are not evaluated after this step.

Parameters
[in]cell_idThe current cell index.
[in]cell_statusThe mobility status of cell to assign.

Definition at line 425 of file adaptive_sparse_contacts.h.

References cell_mobility_status.

◆ assign_mobility_status() [2/2]

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::assign_mobility_status ( unsigned int cell_id,
const std::vector< types::global_dof_index > & dof_indices,
const int cell_status,
const int node_status )
inlineprivate

Assign the mobility status to the cell, its nodes, and its periodic coinciding nodes from the periodic nodes map. If required, this will prevent overwriting a node status prevailing over the initial one. For instance, empty status must not be overwritten by mobile status because all cells with this node will be part of the additional mobile layer and will wrongly propagate mobility status to the next cells.

Parameters
[in]cell_idThe current cell index.
[in]dof_indicesThe vector of the DoF indices of the cell.
[in]cell_statusThe mobility status of cell to assign.
[in]node_statusThe current mobility status of the node.

Definition at line 389 of file adaptive_sparse_contacts.h.

References cell_mobility_status, mobility_at_nodes, and periodic_node_ids.

◆ calculate_granular_temperature_and_solid_fraction()

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::calculate_granular_temperature_and_solid_fraction ( const Particles::ParticleHandler< dim > & particle_handler,
const std::set< typename DoFHandler< dim >::active_cell_iterator > & local_and_ghost_cells_with_particles,
Vector< double > & cell_granular_temperature,
Vector< double > & cell_solid_fraction )
private

Calculate the granular temperature and solid fraction approximation (pcm method). Those values are criteria for cell mobility.

Parameters
[in]particle_handlerThe particle handler that contains all the particles.
[in]local_and_ghost_cells_with_particlesThe set of locally owned and ghost cells that empty cells were removed from.
[out]cell_granular_temperatureThe empty vector of granular temperature.
[out]cell_solid_fractionThe empty vector of solid fraction.

Definition at line 36 of file adaptive_sparse_contacts.cc.

◆ check_cell_mobility()

template<int dim, typename PropertiesIndex>
unsigned int AdaptiveSparseContacts< dim, PropertiesIndex >::check_cell_mobility ( const typename Triangulation< dim >::active_cell_iterator & cell) const
inline

Find the mobility status of a cell.

Parameters
[in]cellThe iterator of the cell that needs mobility evaluation.

Definition at line 303 of file adaptive_sparse_contacts.h.

References cell_mobility_status.

◆ get_mobility_status()

template<int dim, typename PropertiesIndex>
DEM::dem_data_structures< dim >::cell_index_int_map & AdaptiveSparseContacts< dim, PropertiesIndex >::get_mobility_status ( )
inline

Give the map of the mobility status of the cells.

Definition at line 330 of file adaptive_sparse_contacts.h.

References cell_mobility_status.

◆ get_mobility_status_vector()

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::get_mobility_status_vector ( Vector< float > & status)
inline

Convert the map of mobility status to a vector of mobility status because map cannot be used as is in the pvd post-processing or any data out, it needs to be converted to a vector of mobility status by active cell index.

Parameters
[out]statusThe initiated vector for the conversion.

Definition at line 318 of file adaptive_sparse_contacts.h.

References cell_mobility_status.

◆ get_velocities_accelerations()

template<int dim, typename PropertiesIndex>
std::map< typename Triangulation< dim >::active_cell_iterator, std::pair< Tensor< 1, 3 >, Tensor< 1, 3 > > > & AdaptiveSparseContacts< dim, PropertiesIndex >::get_velocities_accelerations ( )
inline

Give the map of the cell-averaged velocities and accelerations * dt.

Definition at line 340 of file adaptive_sparse_contacts.h.

References cell_velocities_accelerations.

◆ has_advected_particles()

template<int dim, typename PropertiesIndex>
bool AdaptiveSparseContacts< dim, PropertiesIndex >::has_advected_particles ( ) const
inline

Give the advected particles flag.

Definition at line 349 of file adaptive_sparse_contacts.h.

References advect_particles_enabled.

◆ identify_mobility_status()

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::identify_mobility_status ( const DoFHandler< dim > & background_dh,
const Particles::ParticleHandler< dim > & particle_handler,
const unsigned int n_active_cells,
MPI_Comm mpi_communicator )

Identify of the mobility status of each cell through a node-based identification and check. Only the active and ghost cells are processed.

The following 4 checks (search loops) are done:

  1. Check if the cell is empty (n_particle = 0), if so, nodes and cells are flagged as empty mobility status (5)
  2. Check if the cell is mobile by criteria (average granular temperature > threshold, solid fraction < threshold or has at least one empty node from previous check), if so, nodes are flagged and cells are stored with mobile mobility status (4)
  3. Check if the cell is mobile by neighbor (at least a node is flagged as mobile from previous check), if so, cells are stored in map as mobile status (4) and nodes that are not mobile are flagged as active (1/3)
  4. Check if the cell is active (at least a node is flagged as active from previous check), if so, cells are stored with active status in the map (1/3)

The remaining cells are inactive (0)

Parameters
[in]background_dhThe dof handler of the background grid.
[in]particle_handlerThe particle handler that contains all the particles.
[in]n_active_cellsThe number of active cells in triangulation.
[in]mpi_communicatorThe MPI communicator.

Definition at line 129 of file adaptive_sparse_contacts.cc.

References advect_particles_enabled, advected, advected_active, assign_mobility_status(), calculate_granular_temperature_and_solid_fraction(), cell_mobility_status, empty, DEMActionManager::get_action_manager(), granular_temperature_threshold, inactive, local_and_ghost_cells, mobile, mobility_at_nodes, solid_fraction_threshold, sparse_contacts_enabled, and static_active.

◆ map_periodic_nodes()

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::map_periodic_nodes ( const AffineConstraints< double > & constraints)
inline

Map the periodic nodes pairs of the triangulation using the constraints. It allows to compare the mobility status of the nodes with the status of the periodic node.

Note: this might not be the efficient way to pair the periodic nodes.

Parameters
constraints[in]The background constraints of triangulation.

Definition at line 279 of file adaptive_sparse_contacts.h.

References periodic_node_ids.

◆ set_parameters()

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::set_parameters ( const double granular_temperature,
const double solid_fraction,
const bool advect_particles )
inline

Set the threshold values for the mobile status criteria (granular temperature and solid fraction) and the flag for the advection of particles.

Parameters
[in]granular_temperatureThe threshold value for the granular temperature.
[in]solid_fractionThe threshold value for the volumic solid fraction.
[in]advect_particlesThe flag for the advection of particles.

Definition at line 177 of file adaptive_sparse_contacts.h.

References advect_particles_enabled, DEMActionManager::get_action_manager(), granular_temperature_threshold, DEMActionManager::set_sparse_contacts_enabled(), solid_fraction_threshold, and sparse_contacts_enabled.

◆ update_average_velocities_acceleration()

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::update_average_velocities_acceleration ( Particles::ParticleHandler< dim > & particle_handler,
const Tensor< 1, 3 > & g,
const std::vector< Tensor< 1, 3 > > & force,
const double dt )

Calculate or update the cell-averaged velocities and accelerations of the cells. This is used for the advection of particles during integration and the velocities and accelerations map is fully updated at least at each CFD time step since the first DEM iteration computes every contact. This map is also partially updated when cell is mobile in the Verlet integration (not implemented for other scheme). Since this step loops over all the particles of mobile cells and new values of velocities are computed, this helps to have a more accurate value of the average velocities and accelerations when applied to the particles in next DEM time steps.

Parameters
[in]particle_handlerThe particle handler that contains all the particles.
[in]gThe external forces, same for all cells (gravity or other sources).
[in]forceThe contact or hydrodynamic forces.
[in]dtThe DEM time step.

Definition at line 362 of file adaptive_sparse_contacts.cc.

References cell_velocities_accelerations, DEMActionManager::get_action_manager(), local_and_ghost_cells, and sparse_contacts_enabled.

◆ update_local_and_ghost_cell_set()

template<int dim, typename PropertiesIndex>
void AdaptiveSparseContacts< dim, PropertiesIndex >::update_local_and_ghost_cell_set ( const DoFHandler< dim > & background_dh)

Create or update a set of the active and ghost cells so that there is no loop over all the cells of the triangulation for the granular temperature and solid fraction calculation, and during the identification of the mobility status. This set prevents 4 iteration steps over all the cells and the verification if the cell is locally owned, ghost or not. This set is updated at every load balance step since cells are redistributed among processors.

Parameters
[in]background_dhThe DoFHandler of the background grid.

Definition at line 20 of file adaptive_sparse_contacts.cc.

References local_and_ghost_cells, and sparse_contacts_enabled.

Member Data Documentation

◆ advect_particles_enabled

template<int dim, typename PropertiesIndex>
bool AdaptiveSparseContacts< dim, PropertiesIndex >::advect_particles_enabled
private

Flag for the advection of particles.

Definition at line 472 of file adaptive_sparse_contacts.h.

◆ cell_mobility_status

template<int dim, typename PropertiesIndex>
DEM::dem_data_structures<dim>::cell_index_int_map AdaptiveSparseContacts< dim, PropertiesIndex >::cell_mobility_status
private

Map of cell mobility status: <cell index: mobility status>.

Definition at line 442 of file adaptive_sparse_contacts.h.

◆ cell_velocities_accelerations

template<int dim, typename PropertiesIndex>
std::map<typename Triangulation<dim>::active_cell_iterator, std::pair<Tensor<1, 3>, Tensor<1, 3> > > AdaptiveSparseContacts< dim, PropertiesIndex >::cell_velocities_accelerations
private

Map of cell velocities and accelerations * dt: <cell iterator: <velocity, acceleration * dt>>.

Definition at line 462 of file adaptive_sparse_contacts.h.

◆ granular_temperature_threshold

template<int dim, typename PropertiesIndex>
double AdaptiveSparseContacts< dim, PropertiesIndex >::granular_temperature_threshold
private

Threshold value for granular temperature.

Definition at line 477 of file adaptive_sparse_contacts.h.

◆ local_and_ghost_cells

template<int dim, typename PropertiesIndex>
std::set<typename DoFHandler<dim>::active_cell_iterator> AdaptiveSparseContacts< dim, PropertiesIndex >::local_and_ghost_cells
private

Set of locally owned and ghost cells: <local/ghost cells> Used to loop over only the locally owned and ghost cells without looping over all the cells in the triangulation numerous times.

Definition at line 436 of file adaptive_sparse_contacts.h.

◆ mobility_at_nodes

template<int dim, typename PropertiesIndex>
LinearAlgebra::distributed::Vector<int> AdaptiveSparseContacts< dim, PropertiesIndex >::mobility_at_nodes
private

Vector of mobility status at nodes: [mobility status] Used to check the value at node to determine the mobility status of the cell, this type of vector is used to allow update values in parallel.

Definition at line 449 of file adaptive_sparse_contacts.h.

◆ periodic_node_ids

template<int dim, typename PropertiesIndex>
std::unordered_map<unsigned int, unsigned int> AdaptiveSparseContacts< dim, PropertiesIndex >::periodic_node_ids
private

Map of periodic nodes: <periodic node index: coinciding node index>.

Definition at line 454 of file adaptive_sparse_contacts.h.

◆ solid_fraction_threshold

template<int dim, typename PropertiesIndex>
double AdaptiveSparseContacts< dim, PropertiesIndex >::solid_fraction_threshold
private

Threshold value for solid fraction.

Definition at line 482 of file adaptive_sparse_contacts.h.

◆ sparse_contacts_enabled

template<int dim, typename PropertiesIndex>
bool AdaptiveSparseContacts< dim, PropertiesIndex >::sparse_contacts_enabled
private

Flag for adaptive sparse contacts enabling. Useful to exit functions.

Definition at line 467 of file adaptive_sparse_contacts.h.


The documentation for this class was generated from the following files: