ParticlePhysics.h

Go to the documentation of this file.

/**
 * @file ParticlePhysics.h
 * @brief Header file for Particle related physics modules.
 *
 * This file contains declarations of functions responsible for solving for fields in the particle swarms within a simulation using PETSc's DMSwarm.
 */
 
 #ifndef PARTICLE_PHYSICS_H
 #define PARTICLE_PHYSICS_H
 
// Include necessary headers
#include <petsc.h>        // PETSc library header
#include <petscdmswarm.h> // PETSc DMSwarm header
#include <stdbool.h>
#include <petscsys.h>     // For PetscRealloc
#include <math.h>
#include "variables.h"       // Common type definitions
#include "logging.h"      // Logging macros and definitions
#include "walkingsearch.h"  // Walking search function for particle migration 
 
/**
 * @brief Updates a single particle's field based on its state and the specified field name.
 *
 * This function serves as a switchboard for various particle property calculations.
 * Given a particle's data, it computes a new value for the specified field.
 *
 * Currently supported fields:
 *  - "Psi": Calculates the particle's kinetic energy (0.5 * |v|^2).
 *
 * @param[in]     fieldName   The name of the field to update (e.g., "Psi").
 * @param[in]     t           The current simulation time.
 * @param[in]     pos         The particle's physical position.
 * @param[in]     vel         The particle's velocity.
 * @param[in,out] psi_io      A pointer to the particle's current Psi value (used for accumulation if needed).
 *
 * @return PetscErrorCode 0 on success.
 */
//PetscErrorCode UpdateParticleField(const char *fieldName,
//                                                 PetscReal t,
//                                                 Cmpnts pos,
//                                                 Cmpnts vel,
//                                                 PetscReal *psi_io);
/**
 * @brief Updates a single particle's field based on its state and physics model.
 *
 * Implements the IEM (Interaction by Exchange with the Mean) model for scalar mixing.
 * 
 * Physics: dPsi/dt = -Omega * (Psi - <Psi>)
 * Solution: Psi_new = <Psi> + (Psi_old - <Psi>) * exp(-Omega * dt)
 *
 * @param[in]     fieldName   Name of the field (e.g., "Psi").
 * @param[in]     dt          Time step size.
 * @param[in,out] psi_io      Pointer to the particle's scalar value (Psi).
 * @param[in]     diffusivity Particle diffusivity (Gamma + Gamma_t).
 * @param[in]     mean_val    Local Eulerian mean value (<Psi>).
 * @param[in]     cell_vol    Volume of the host cell (1/Jacobian).
 * @param[in]     C_model     Model constant (C_IEM).
 */
PetscErrorCode UpdateParticleField(const char *fieldName,
                                   PetscReal dt,
                                   PetscReal *psi_io,
                                   PetscReal diffusivity,
                                   PetscReal mean_val,
                                   PetscReal cell_vol,
                                   PetscReal C_model);
 
 
/**
 * @brief Loops over all local particles and updates a specified field.
 *
 * This function orchestrates the update of a single particle field across the entire
 * local swarm. It gets access to the necessary particle data arrays and calls the
 * `UpdateParticleField` kernel for each particle.
 *
 * @param[in,out] user      Pointer to the UserCtx containing the swarm and simulation context.
 * @param[in]     fieldName The name of the field to update (e.g., "Psi").
 *
 * @return PetscErrorCode 0 on success.
 */
PetscErrorCode UpdateFieldForAllParticles(UserCtx *user, const char *fieldName);
 
 
/**
 * @brief Orchestrates the update of all physical properties for particles.
 *
 * This function serves as the top-level entry point for updating particle-specific
 * physical quantities after their position and the surrounding fluid velocity are known.
 * It calls a sequence of more specific update routines for each property.
 *
 * For example, it can be configured to update:
 *  - Particle kinetic energy (stored in "Psi")
 *  - Particle accumulated shear stress
 *  - Particle temperature
 *  - etc.
 *
 * @param[in,out] user  Pointer to the UserCtx containing the swarm and simulation context.
 *
 * @return PetscErrorCode 0 on success.
 */
PetscErrorCode UpdateAllParticleFields(UserCtx *user);
 
#endif // PARTICLE_PHYSICS_H