ParticleSwarm.h File Reference

Header file for Particle Motion and migration related functions. More...

#include <petsc.h>
#include <petscdmswarm.h>
#include <stdbool.h>
#include <math.h>
#include "variables.h"
#include "logging.h"
#include "walkingsearch.h"
#include "Metric.h"
#include "io.h"

Include dependency graph for ParticleSwarm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
PetscErrorCode	CreateParticleSwarm (UserCtx *user, PetscInt numParticles, PetscInt *particlesPerProcess, BoundingBox *bboxlist)
	Creates and initializes a Particle Swarm.
PetscErrorCode	InitializeSwarm (UserCtx *user)
	Initializes the DMSwarm object within the UserCtx structure.
PetscErrorCode	RegisterSwarmField (DM swarm, const char *fieldName, PetscInt fieldDim, PetscDataType dtype)
	Registers a swarm field without finalizing registration.
PetscErrorCode	RegisterParticleFields (DM swarm)
	Registers necessary particle fields within the DMSwarm.
PetscErrorCode	InitializeRandomGenerators (UserCtx *user, PetscRandom *randx, PetscRandom *randy, PetscRandom *randz)
	Initializes random number generators for assigning particle properties.
PetscErrorCode	InitializeLogicalSpaceRNGs (PetscRandom *rand_logic_i, PetscRandom *rand_logic_j, PetscRandom *rand_logic_k)
	Initializes random number generators for logical space operations [0.0, 1.0).
PetscErrorCode	AssignInitialPropertiesToSwarm (UserCtx *user, PetscInt particlesPerProcess, PetscRandom *rand_phys_x, PetscRandom *rand_phys_y, PetscRandom *rand_phys_z, PetscRandom *rand_logic_i, PetscRandom *rand_logic_j, PetscRandom *rand_logic_k, BoundingBox *bboxlist)
	Initializes all particle properties in the swarm.
PetscErrorCode	DistributeParticles (PetscInt numParticles, PetscMPIInt rank, PetscMPIInt size, PetscInt *particlesPerProcess, PetscInt *remainder)
	Distributes particles evenly across MPI processes, handling any remainders.
PetscErrorCode	FinalizeSwarmSetup (PetscRandom *randx, PetscRandom *randy, PetscRandom *randz, PetscRandom *rand_logic_i, PetscRandom *rand_logic_j, PetscRandom *rand_logic_k)
	Finalizes the swarm setup by destroying random generators and logging completion.
PetscErrorCode	UnpackSwarmFields (PetscInt i, const PetscInt64 *PIDs, const PetscReal *weights, const PetscReal *positions, const PetscInt *cellIndices, PetscReal *velocities, PetscInt *LocStatus, Particle *particle)
	Initializes a Particle struct with data from DMSwarm fields.
PetscErrorCode	UpdateSwarmFields (PetscInt i, const Particle *particle, PetscReal *weights, PetscInt *cellIndices, PetscInt *status_field)
	Updates DMSwarm fields with data from a Particle struct.
PetscBool	IsParticleInsideBoundingBox (const BoundingBox *bbox, const Particle *particle)
	Checks if a particle's location is within a specified bounding box.
PetscErrorCode	UpdateParticleWeights (PetscReal *d, Particle *particle)
	Updates a particle's interpolation weights based on distances to cell faces.
PetscErrorCode	PrepareLoadedSwarmForRelocation (UserCtx *user)
	Resets the location-dependent state of a loaded swarm to force relocation.
PetscErrorCode	InitializeParticleSwarm (SimCtx *simCtx)
	Perform particle swarm initialization, particle-grid interaction, and related operations.

Detailed Description

Header file for Particle Motion and migration related functions.

Header file for Particle Swarm management functions.

This file contains declarations of functions responsible for moving and migrating particle swarms within a simulation using PETSc's DMSwarm.

This file contains declarations of functions responsible for creating, managing, initializing, migrating, and printing particle swarms within a simulation using PETSc's DMSwarm.

Definition in file ParticleSwarm.h.

Function Documentation

CreateParticleSwarm()

PetscErrorCode CreateParticleSwarm	(	UserCtx *	user,
		PetscInt	numParticles,
		PetscInt *	particlesPerProcess,
		BoundingBox *	bboxlist
	)

Creates and initializes a Particle Swarm.

This function sets up a DMSwarm within the provided UserCtx structure, initializes particle fields, and distributes particles across MPI processes. It ensures that the number of particles is evenly divided among the available MPI ranks. If the total number of particles isn't divisible by the number of processes, the remainder is distributed to the first few ranks.

Additionally, it now takes a 'bboxlist' array as an input parameter and passes it on to AssignInitialProperties(), enabling particle initialization at the midpoint of each rank's bounding box if ParticleInitialization is set to 0.

Parameters

[in,out]	user	Pointer to the UserCtx structure containing the simulation context.
[in]	numParticles	Total number of particles to create across all MPI processes.
[in]	bboxlist	Pointer to an array of BoundingBox structures, one per rank.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Note

• Ensure that numParticles is a positive integer.
• The control.dat file should contain necessary PETSc options.

• The bboxlist array should be properly populated before calling this function.

  This function sets up a DMSwarm within the provided UserCtx structure, initializes particle fields, and distributes particles across MPI processes. It ensures that the number of particles is evenly divided among the available MPI ranks. If the total number of particles isn't divisible by the number of processes, the remainder is distributed to the first few ranks.

Parameters

[in,out]	user	Pointer to the UserCtx structure containing the simulation context.
[in]	numParticles	Total number of particles to create across all MPI processes.
[in]	bboxlist	Pointer to an array of BoundingBox structures, one per rank.
[in]	particlesPerProcess

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Note

• Ensure that numParticles is a positive integer.
• The control.dat file should contain necessary PETSc options.
• The bboxlist array should be properly populated before calling this function.

Definition at line 764 of file ParticleSwarm.c.

                                                                                                                                   {
        PetscErrorCode ierr;                      // PETSc error handling variable
        PetscMPIInt rank, size;                   // Variables to store MPI rank and size
        PetscInt remainder = 0;                   // Remainder of particles after division
        
        // Validate input parameters
        if (numParticles <= 0) {
        LOG_ALLOW(GLOBAL,LOG_DEBUG, "CreateParticleSwarm - Number of particles must be positive. Given: %d\n", numParticles);
            return PETSC_ERR_ARG_OUTOFRANGE;
        }
 
        // Insert PETSc options from "control.dat" into the PETSc options database
        //  ierr = PetscOptionsInsertFile(PETSC_COMM_WORLD, NULL, "control.dat", PETSC_TRUE); CHKERRQ(ierr);
        // LOG_ALLOW(LOCAL,LOG_DEBUG,"CreateParticleSwarm - Inserted options from control.dat\n");
        
        LOG_ALLOW_SYNC(GLOBAL,LOG_DEBUG, "CreateParticleSwarm - Domain dimensions: Min_X=%.2f, Max_X=%.2f,Min_Y=%.2f, Max_Y=%.2f,Min_Z=%.2f, Max_Z=%.2f \n", 
            user->Min_X,user->Max_X,user->Min_Y,user->Max_Y, user->Min_Z,user->Max_Z);
        
        // Retrieve MPI rank and size
        ierr = MPI_Comm_rank(PETSC_COMM_WORLD, &rank); CHKERRQ(ierr);
        ierr = MPI_Comm_size(PETSC_COMM_WORLD, &size); CHKERRQ(ierr);
        LOG_ALLOW(GLOBAL,LOG_INFO, "CreateParticleSwarm - Rank %d out of %d processes.\n", rank, size);
 
        // Distribute particles among MPI processes
        ierr = DistributeParticles(numParticles, rank, size, particlesPerProcess, &remainder); CHKERRQ(ierr);
 
        // Initialize the DMSwarm - creates the swarm, sets the type and dimension
        ierr = InitializeSwarm(user); CHKERRQ(ierr);
 
        if (user->da) {
        ierr = DMSwarmSetCellDM(user->swarm, user->da); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_INFO,"CreateParticleSwarm - Associated DMSwarm with Cell DM (user->da).\n");
        } else {
        // If user->da is essential for your simulation logic with particles, this should be a fatal error.
        LOG_ALLOW(GLOBAL, LOG_WARNING, "CreateParticleSwarm - user->da (Cell DM for Swarm) is NULL. Cell-based swarm operations might fail.\n");
        // SETERRQ(PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONGSTATE, "CreateParticleSwarm - user->da (Cell DM) is NULL but required.");
        }
        
        // Register particle fields (position, velocity, CellID, weight, etc.)
        ierr = RegisterParticleFields(user->swarm); CHKERRQ(ierr);
 
        // Set the local number of particles for this rank and additional buffer for particle migration
        ierr = DMSwarmSetLocalSizes(user->swarm, *particlesPerProcess, numParticles); CHKERRQ(ierr);
        LOG_ALLOW(GLOBAL,LOG_INFO, "CreateParticleSwarm - Set local swarm size: %d particles.\n", *particlesPerProcess);
 
        // Optionally, LOG_ALLOW detailed DM info in debug mode
        if (get_log_level() == LOG_DEBUG && is_function_allowed(__func__)) {
        LOG_ALLOW(LOCAL,LOG_DEBUG,"CreateParticleSwarm - Viewing DMSwarm:\n");
            ierr = DMView(user->swarm, PETSC_VIEWER_STDOUT_WORLD); CHKERRQ(ierr);
        }
 
        LOG_ALLOW(LOCAL,LOG_INFO, "CreateParticleSwarm - Particle swarm creation and initialization complete.\n");
 
        return 0;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeSwarm()

PetscErrorCode InitializeSwarm

(

UserCtx *

user

)

Initializes the DMSwarm object within the UserCtx structure.

This function creates the DMSwarm, sets its type and dimension, and configures basic swarm properties.

Parameters

[in,out]

user

Pointer to the UserCtx structure containing simulation context.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 15 of file ParticleSwarm.c.

                                                  {
        PetscErrorCode ierr;  // Error code for PETSc functions
 
        // Create the DMSwarm object for particle management
        ierr = DMCreate(PETSC_COMM_WORLD, &user->swarm); CHKERRQ(ierr);
        ierr = DMSetType(user->swarm, DMSWARM); CHKERRQ(ierr);
        ierr = DMSetDimension(user->swarm, 3); CHKERRQ(ierr);
        ierr = DMSwarmSetType(user->swarm, DMSWARM_BASIC); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_INFO, "InitializeSwarm - DMSwarm created and configured.\n");
 
        return 0;
    }

Here is the caller graph for this function:

RegisterSwarmField()

PetscErrorCode RegisterSwarmField	(	DM	swarm,
		const char *	fieldName,
		PetscInt	fieldDim,
		PetscDataType	dtype
	)

Registers a swarm field without finalizing registration.

This function calls DMSwarmRegisterPetscDatatypeField for the given field, but does not finalize the registration. The finalization is deferred until all fields have been registered.

Parameters

swarm	[in] The DMSwarm object.
fieldName	[in] Name of the field to register.
fieldDim	[in] Dimension of the field (1 for scalar, 3 for vector, etc.).
dtype	[in] The datatype of the swarm field being registered.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 41 of file ParticleSwarm.c.

    {
        PetscErrorCode ierr;
        PetscFunctionBeginUser;
        
        ierr = DMSwarmRegisterPetscDatatypeField(swarm, fieldName, fieldDim, dtype); CHKERRQ(ierr);
        // PetscDataTypes is an extern char* [] defined in petscsystypes.h that gives string names for PetscDataType enums
        LOG_ALLOW(LOCAL,LOG_DEBUG,"RegisterSwarmField - Registered field '%s' with dimension=%d, type=%s.\n",
                fieldName, fieldDim, PetscDataTypes[dtype]);
        
        PetscFunctionReturn(0);
    }

Here is the caller graph for this function:

RegisterParticleFields()

PetscErrorCode RegisterParticleFields

(

DM

swarm

)

Registers necessary particle fields within the DMSwarm.

This function registers fields such as position, velocity, CellID, and weight for each particle.

Parameters

[in,out]

swarm

The DMSwarm object managing the particle swarm.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 64 of file ParticleSwarm.c.

    {
        PetscErrorCode ierr;
        PetscFunctionBeginUser;
        
        // Register each field using the helper function
        ierr = RegisterSwarmField(swarm, "position", 3 ,PETSC_REAL); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG, "Registered field 'position'.\n");
        
        ierr = RegisterSwarmField(swarm, "velocity", 3, PETSC_REAL); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG,"Registered field 'velocity'.\n");
        
        ierr = RegisterSwarmField(swarm, "DMSwarm_CellID", 3, PETSC_INT); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG,"Registered field 'DMSwarm_CellID'.\n");
        
        ierr = RegisterSwarmField(swarm, "weight", 3,PETSC_REAL); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG,"Registered field 'weight'.\n");
 
        ierr = RegisterSwarmField(swarm,"Psi", 1,PETSC_REAL); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG,"Registered field 'Psi' - Scalar.\n");
 
 
        ierr = RegisterSwarmField(swarm,"pos_phy", 3,PETSC_REAL); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG,"Registered field 'pos_phy' - Physical Position.\n");
 
        ierr =  RegisterSwarmField(swarm,"DMSwarm_location_status",1,PETSC_INT);CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG,"Registered field 'DMSwarm_location_status' - Status of Location of Particle(located,lost etc).\n");
        
        // Finalize the field registration after all fields have been added
        ierr = DMSwarmFinalizeFieldRegister(swarm); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_INFO,"RegisterParticleFields - Finalized field registration.\n");
        
        PetscFunctionReturn(0);
    }

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeRandomGenerators()

PetscErrorCode InitializeRandomGenerators	(	UserCtx *	user,
		PetscRandom *	randx,
		PetscRandom *	randy,
		PetscRandom *	randz
	)

Initializes random number generators for assigning particle properties.

This function creates and configures separate PETSc random number generators for the x, y, and z coordinates.

Parameters

[in,out]	user	Pointer to the UserCtx structure containing simulation context.
[out]	randx	Pointer to store the RNG for the x-coordinate.
[out]	randy	Pointer to store the RNG for the y-coordinate.
[out]	randz	Pointer to store the RNG for the z-coordinate.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 112 of file ParticleSwarm.c.

                                                                                                                         {
        PetscErrorCode ierr;  // Error code for PETSc functions
        PetscMPIInt rank;
        MPI_Comm_rank(PETSC_COMM_WORLD, &rank);
 
        // Initialize RNG for x-coordinate
        ierr = PetscRandomCreate(PETSC_COMM_SELF, randx); CHKERRQ(ierr);
        ierr = PetscRandomSetType((*randx), PETSCRAND48); CHKERRQ(ierr);
        ierr = PetscRandomSetInterval(*randx, user->bbox.min_coords.x, user->bbox.max_coords.x); CHKERRQ(ierr);
        ierr = PetscRandomSetSeed(*randx, rank + 12345); CHKERRQ(ierr);  // Unique seed per rank
        ierr = PetscRandomSeed(*randx); CHKERRQ(ierr);
        LOG_ALLOW_SYNC(LOCAL,LOG_DEBUG, "InitializeRandomGenerators - Initialized RNG for X-axis.\n");
 
        // Initialize RNG for y-coordinate
        ierr = PetscRandomCreate(PETSC_COMM_SELF, randy); CHKERRQ(ierr);
        ierr = PetscRandomSetType((*randy), PETSCRAND48); CHKERRQ(ierr);
        ierr = PetscRandomSetInterval(*randy, user->bbox.min_coords.y, user->bbox.max_coords.y); CHKERRQ(ierr);
        ierr = PetscRandomSetSeed(*randy, rank + 67890); CHKERRQ(ierr);  // Unique seed per rank
        ierr = PetscRandomSeed(*randy); CHKERRQ(ierr);
        LOG_ALLOW_SYNC(LOCAL,LOG_DEBUG, "InitializeRandomGenerators - Initialized RNG for Y-axis.\n");
 
        // Initialize RNG for z-coordinate
        ierr = PetscRandomCreate(PETSC_COMM_SELF, randz); CHKERRQ(ierr);
        ierr = PetscRandomSetType((*randz), PETSCRAND48); CHKERRQ(ierr);
        ierr = PetscRandomSetInterval(*randz, user->bbox.min_coords.z, user->bbox.max_coords.z); CHKERRQ(ierr);
        ierr = PetscRandomSetSeed(*randz, rank + 54321); CHKERRQ(ierr);  // Unique seed per rank
        ierr = PetscRandomSeed(*randz); CHKERRQ(ierr);
        LOG_ALLOW_SYNC(LOCAL,LOG_DEBUG, "InitializeRandomGenerators - Initialized RNG for Z-axis.\n");
 
        return 0;
    }

Here is the caller graph for this function:

InitializeLogicalSpaceRNGs()

PetscErrorCode InitializeLogicalSpaceRNGs	(	PetscRandom *	rand_logic_i,
		PetscRandom *	rand_logic_j,
		PetscRandom *	rand_logic_k
	)

Initializes random number generators for logical space operations [0.0, 1.0).

This function creates and configures three separate PETSc random number generators, one for each logical dimension (i, j, k or xi, eta, zeta equivalent). Each RNG is configured to produce uniformly distributed real numbers in the interval [0.0, 1.0). These are typically used for selecting owned cells or generating intra-cell logical coordinates.

Parameters

[out]	rand_logic_i	Pointer to store the RNG for the i-logical dimension.
[out]	rand_logic_j	Pointer to store the RNG for the j-logical dimension.
[out]	rand_logic_k	Pointer to store the RNG for the k-logical dimension.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 158 of file ParticleSwarm.c.

                                                                                                                               {
        PetscErrorCode ierr;
        PetscMPIInt rank;
        PetscFunctionBeginUser;
 
        ierr = MPI_Comm_rank(PETSC_COMM_WORLD, &rank); CHKERRQ(ierr);
 
        // --- RNG for i-logical dimension ---
        ierr = PetscRandomCreate(PETSC_COMM_SELF, rand_logic_i); CHKERRQ(ierr);
        ierr = PetscRandomSetType((*rand_logic_i), PETSCRAND48); CHKERRQ(ierr);
        ierr = PetscRandomSetInterval(*rand_logic_i, 0.0, 1.0); CHKERRQ(ierr); // Key change: [0,1)
        ierr = PetscRandomSetSeed(*rand_logic_i, rank + 202401); CHKERRQ(ierr); // Unique seed
        ierr = PetscRandomSeed(*rand_logic_i); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG, "InitializeLogicalSpaceRNGs - Initialized RNG for i-logical dimension [0,1).\n");
 
        // --- RNG for j-logical dimension ---
        ierr = PetscRandomCreate(PETSC_COMM_SELF, rand_logic_j); CHKERRQ(ierr);
        ierr = PetscRandomSetType((*rand_logic_j), PETSCRAND48); CHKERRQ(ierr);
        ierr = PetscRandomSetInterval(*rand_logic_j, 0.0, 1.0); CHKERRQ(ierr); // Key change: [0,1)
        ierr = PetscRandomSetSeed(*rand_logic_j, rank + 202402); CHKERRQ(ierr);
        ierr = PetscRandomSeed(*rand_logic_j); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG, "InitializeLogicalSpaceRNGs - Initialized RNG for j-logical dimension [0,1).\n");
 
        // --- RNG for k-logical dimension ---
        ierr = PetscRandomCreate(PETSC_COMM_SELF, rand_logic_k); CHKERRQ(ierr);
        ierr = PetscRandomSetType((*rand_logic_k), PETSCRAND48); CHKERRQ(ierr);
        ierr = PetscRandomSetInterval(*rand_logic_k, 0.0, 1.0); CHKERRQ(ierr); // Key change: [0,1)
        ierr = PetscRandomSetSeed(*rand_logic_k, rank + 202403); CHKERRQ(ierr);
        ierr = PetscRandomSeed(*rand_logic_k); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL,LOG_DEBUG, "InitializeLogicalSpaceRNGs - Initialized RNG for k-logical dimension [0,1).\n");
 
        PetscFunctionReturn(0);
    }

Here is the caller graph for this function:

AssignInitialPropertiesToSwarm()

PetscErrorCode AssignInitialPropertiesToSwarm	(	UserCtx *	user,
		PetscInt	particlesPerProcess,
		PetscRandom *	rand_phys_x,
		PetscRandom *	rand_phys_y,
		PetscRandom *	rand_phys_z,
		PetscRandom *	rand_logic_i,
		PetscRandom *	rand_logic_j,
		PetscRandom *	rand_logic_k,
		BoundingBox *	bboxlist
	)

Initializes all particle properties in the swarm.

This function orchestrates the initialization of particle properties. It first determines the inlet face if surface initialization (Mode 0) is selected by parsing "bcs.dat". Then, it initializes basic particle properties (physical position, Particle ID, and placeholder Cell IDs) by calling InitializeParticleBasicProperties. This call uses the provided rand_logic_i/j/k RNGs, which must be pre-initialized for [0,1). The rand_phys_x/y/z RNGs (physically bounded) are passed but may not be used by InitializeParticleBasicProperties for position setting if all initialization paths use logical-to-physical mapping. Finally, it calls helper functions to initialize other registered swarm fields like "velocity", "weight", and "P" (pressure) to default values.

Parameters

[in,out]	user	Pointer to the UserCtx structure.
[in]	particlesPerProcess	Number of particles assigned to this MPI process.
[in]	rand_phys_x	RNG for physical x-coordinates (from InitializeRandomGenerators).
[in]	rand_phys_y	RNG for physical y-coordinates (from InitializeRandomGenerators).
[in]	rand_phys_z	RNG for physical z-coordinates (from InitializeRandomGenerators).
[in]	rand_logic_i	RNG for i-logical dimension tasks [0,1) (from InitializeLogicalSpaceRNGs).
[in]	rand_logic_j	RNG for j-logical dimension tasks [0,1) (from InitializeLogicalSpaceRNGs).
[in]	rand_logic_k	RNG for k-logical dimension tasks [0,1) (from InitializeLogicalSpaceRNGs).
[in]	bboxlist	Array of BoundingBox structures (potentially unused by IPBP).

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

This function orchestrates the initialization of particle properties. It first determines the inlet face if surface initialization (Mode 0) is selected by parsing "bcs.dat". Then, it initializes basic particle properties (physical position, Particle ID, and placeholder Cell IDs) by calling InitializeParticleBasicProperties. This call uses the provided rand_logic_i/j/k RNGs, which must be pre-initialized for [0,1). The rand_phys_x/y/z RNGs (physically bounded) are passed but may not be used by InitializeParticleBasicProperties for position setting if all initialization paths use logical-to-physical mapping. Finally, it calls helper functions to initialize other registered swarm fields like "velocity", "weight", and "Psi" (scalar) to default values.

Parameters

[in,out]	user	Pointer to the UserCtx structure.
[in]	particlesPerProcess	Number of particles assigned to this MPI process.
[in]	rand_phys_x	RNG for physical x-coordinates (from InitializeRandomGenerators).
[in]	rand_phys_y	RNG for physical y-coordinates (from InitializeRandomGenerators).
[in]	rand_phys_z	RNG for physical z-coordinates (from InitializeRandomGenerators).
[in]	rand_logic_i	RNG for i-logical dimension tasks [0,1) (from InitializeLogicalSpaceRNGs).
[in]	rand_logic_j	RNG for j-logical dimension tasks [0,1) (from InitializeLogicalSpaceRNGs).
[in]	rand_logic_k	RNG for k-logical dimension tasks [0,1) (from InitializeLogicalSpaceRNGs).
[in]	bboxlist	Array of BoundingBox structures (potentially unused by IPBP).

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 606 of file ParticleSwarm.c.

    {
        PetscErrorCode ierr;
        PetscFunctionBeginUser;
 
        SimCtx *simCtx = user->simCtx;
        
        // --- 0. Input Validation ---
        if (!user || !bboxlist || !rand_logic_i || !rand_logic_j || !rand_logic_k || !rand_phys_x || !rand_phys_y || !rand_phys_z) {
            // Check all RNGs now as they are passed in
            LOG_ALLOW(GLOBAL, LOG_ERROR, "AssignInitialPropertiesToSwarm - Null user, bboxlist, or RNG pointer.\n");
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "AssignInitialPropertiesToSwarm - Null input detected.");
        }
 
        LOG_ALLOW(GLOBAL, LOG_INFO, "AssignInitialPropertiesToSwarm - Initializing swarm with %d particles per process. Mode: %d.\n",
                particlesPerProcess, simCtx->ParticleInitialization);
 
        // --- 1. Parse BCS File for Inlet Information (if Mode 0) ---
        if (simCtx->ParticleInitialization == 0) {
        if(user->inletFaceDefined == PETSC_FALSE){
        LOG_ALLOW(GLOBAL, LOG_ERROR, "AssignInitialPropertiesToSwarm - ParticleInitialization Mode 0 (Surface Init) selected, but no INLET face was identified from bcs.dat. Cannot proceed.\n");
            SETERRQ(PETSC_COMM_WORLD, PETSC_ERR_ARG_WRONGSTATE, "ParticleInitialization Mode 0 requires an INLET face to be defined in bcs.dat.");
        }else{
        LOG_ALLOW(GLOBAL, LOG_INFO, "AssignInitialPropertiesToSwarm - After ParseBCSFileForInlet, identifiedInletBCFace = %d\n", user->identifiedInletBCFace);
        }
        }
 
        // --- 2. Initialize Basic Particle Properties (Position, PID, Cell IDs placeholder) ---
        // The rand_logic_i/j/k are now passed directly.
        // The rand_phys_x/y/z are passed but InitializeParticleBasicProperties (refactored version)
        // will not use them for setting positions if all its paths use logical-to-physical mapping.
        LOG_ALLOW(LOCAL, LOG_DEBUG, "AssignInitialPropertiesToSwarm - Calling InitializeParticleBasicProperties.\n");
        ierr = InitializeParticleBasicProperties(user, particlesPerProcess,
                                                rand_logic_i, rand_logic_j, rand_logic_k,
                                                bboxlist); // bboxlist passed along
        CHKERRQ(ierr);
        LOG_ALLOW(LOCAL, LOG_INFO, "AssignInitialPropertiesToSwarm - Successfully initialized basic particle properties.\n");
 
        // Note: The logical RNGs (rand_logic_i/j/k) are NOT destroyed here.
        // They were created externally (e.g., by InitializeLogicalSpaceRNGs) and
        // should be destroyed externally (e.g., in FinalizeSwarmSetup).
        // Same for rand_phys_x/y/z.
 
        // --- 3. Initialize Other Swarm Fields (Velocity, Weight, Pressure, etc.) ---
        LOG_ALLOW(LOCAL, LOG_DEBUG, "AssignInitialPropertiesToSwarm - Initializing 'velocity' field.\n");
        ierr = AssignInitialFieldToSwarm(user, "velocity", 3); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL, LOG_INFO, "AssignInitialPropertiesToSwarm - 'velocity' field initialization complete.\n");
 
        LOG_ALLOW(LOCAL, LOG_DEBUG, "AssignInitialPropertiesToSwarm - Initializing 'weight' field.\n");
        ierr = AssignInitialFieldToSwarm(user, "weight", 3); CHKERRQ(ierr); // Assuming weight is vec3
        LOG_ALLOW(LOCAL, LOG_INFO, "AssignInitialPropertiesToSwarm - 'weight' field initialization complete.\n");
 
        LOG_ALLOW(LOCAL, LOG_DEBUG, "AssignInitialPropertiesToSwarm - Initializing 'P' (Pressure) field.\n");
        ierr = AssignInitialFieldToSwarm(user, "Psi", 1); CHKERRQ(ierr);
        LOG_ALLOW(LOCAL, LOG_INFO, "AssignInitialPropertiesToSwarm - 'P' field initialization complete.\n");
        
        LOG_ALLOW(GLOBAL, LOG_INFO, "AssignInitialPropertiesToSwarm - Successfully completed all swarm property initialization.\n");
 
        PetscFunctionReturn(0);
    }

Here is the call graph for this function:

Here is the caller graph for this function:

DistributeParticles()

PetscErrorCode DistributeParticles	(	PetscInt	numParticles,
		PetscMPIInt	rank,
		PetscMPIInt	size,
		PetscInt *	particlesPerProcess,
		PetscInt *	remainder
	)

Distributes particles evenly across MPI processes, handling any remainders.

This function calculates the number of particles each MPI process should handle, distributing the remainder particles to the first few ranks if necessary.

Parameters

[in]	numParticles	Total number of particles to create across all MPI processes.
[in]	rank	MPI rank of the current process.
[in]	size	Total number of MPI processes.
[out]	particlesPerProcess	Number of particles assigned to the current MPI process.
[out]	remainder	Remainder particles when dividing numParticles by size.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 689 of file ParticleSwarm.c.

                                                                                                                                                      {
 
        // Calculate the base number of particles per process
        *particlesPerProcess = numParticles / size;
        *remainder = numParticles % size;
 
        // Distribute the remainder particles to the first 'remainder' ranks
        if (rank < *remainder) {
            *particlesPerProcess += 1;
            LOG_ALLOW_SYNC(GLOBAL,LOG_INFO,"DistributeParticles - Rank %d receives an extra particle. Total: %d\n", rank, *particlesPerProcess);
        } else {
            LOG_ALLOW_SYNC(GLOBAL,LOG_INFO, "DistributeParticles - Rank %d receives %d particles.\n", rank, *particlesPerProcess);
        }
 
        return 0;
    }

Here is the caller graph for this function:

FinalizeSwarmSetup()

PetscErrorCode FinalizeSwarmSetup	(	PetscRandom *	randx,
		PetscRandom *	randy,
		PetscRandom *	randz,
		PetscRandom *	rand_logic_i,
		PetscRandom *	rand_logic_j,
		PetscRandom *	rand_logic_k
	)

Finalizes the swarm setup by destroying random generators and logging completion.

This function cleans up resources by destroying random number generators and LOG_ALLOWs the completion of swarm setup.

Parameters

[in]	randx	Random number generator for the x-coordinate.
[in]	randy	Random number generator for the y-coordinate.
[in]	randz	Random number generator for the z-coordinate.
[in]	rand_logic_i	Random number generator for the xi-coordinate.
[in]	rand_logic_j	Random number generator for the eta-coordinate.
[in]	rand_logic_k	Random number generator for the zeta-coordinate.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 720 of file ParticleSwarm.c.

                                                                                                                                                                                   {
        PetscErrorCode ierr;  // Error code for PETSc functions
        PetscInt  ParticleInitialization; 
 
        ierr = PetscOptionsGetInt(NULL, NULL, "-pinit", &ParticleInitialization, NULL); CHKERRQ(ierr);
    
        // Destroy random number generators to free resources
        // Physical space
        ierr = PetscRandomDestroy(randx); CHKERRQ(ierr);
        ierr = PetscRandomDestroy(randy); CHKERRQ(ierr);
        ierr = PetscRandomDestroy(randz); CHKERRQ(ierr);
 
        // Logical space
        ierr = PetscRandomDestroy(rand_logic_i); CHKERRQ(ierr);
        ierr = PetscRandomDestroy(rand_logic_j); CHKERRQ(ierr);
        ierr = PetscRandomDestroy(rand_logic_k); CHKERRQ(ierr);      
        
        LOG_ALLOW(LOCAL,LOG_DEBUG,"FinalizeSwarmSetup - Destroyed all random number generators.\n");
 
        return 0;
    }

Here is the caller graph for this function:

UnpackSwarmFields()

PetscErrorCode UnpackSwarmFields	(	PetscInt	i,
		const PetscInt64 *	PIDs,
		const PetscReal *	weights,
		const PetscReal *	positions,
		const PetscInt *	cellIndices,
		PetscReal *	velocities,
		PetscInt *	LocStatus,
		Particle *	particle
	)

Initializes a Particle struct with data from DMSwarm fields.

This helper function populates a Particle structure using data retrieved from DMSwarm fields.

Parameters

[in]	i	Index of the particle in the DMSwarm.
[in]	PIDs	Pointer to the array of particle IDs.
[in]	weights	Pointer to the array of particle weights.
[in]	positions	Pointer to the array of particle positions.
[in]	cellIndices	Pointer to the array of particle cell indices.
[in]	velocities	Pointer to the array of particle velocities.
[in]	LocStatus	Pointer to the array of cell location status indicators.
[out]	particle	Pointer to the Particle struct to initialize.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 837 of file ParticleSwarm.c.

                                                                                  {
        PetscFunctionBeginUser;
        PetscMPIInt rank;
        PetscErrorCode ierr;
 
        ierr = MPI_Comm_rank(PETSC_COMM_WORLD,&rank); CHKERRQ(ierr);
        
        if (particle == NULL) {
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Output Particle pointer is NULL. \n");
        }
        
        // logging the start of particle initialization
        LOG_ALLOW(LOCAL,LOG_INFO, "[Rank %d]Unpacking Particle [%d] with PID: %ld.\n",rank, i, PIDs[i]);
        
        // Initialize PID
        particle->PID = PIDs[i];
        LOG_ALLOW(LOCAL,LOG_DEBUG, "[Rank %d]Particle [%d] PID set to: %ld.\n", rank,i, particle->PID);
        
        // Initialize weights
        particle->weights.x = weights[3 * i];
        particle->weights.y = weights[3 * i + 1];
        particle->weights.z = weights[3 * i + 2];
        LOG_ALLOW(LOCAL,LOG_DEBUG, "[Rank %d]Particle [%d] weights set to: (%.6f, %.6f, %.6f).\n", 
            rank,i, particle->weights.x, particle->weights.y, particle->weights.z);
        
        // Initialize locations
        particle->loc.x = positions[3 * i];
        particle->loc.y = positions[3 * i + 1];
        particle->loc.z = positions[3 * i + 2];
        LOG_ALLOW(LOCAL,LOG_DEBUG, "[Rank %d]Particle [%d] location set to: (%.6f, %.6f, %.6f).\n", 
            rank,i, particle->loc.x, particle->loc.y, particle->loc.z);
        
        // Initialize velocities (assuming default zero; modify if necessary)
        particle->vel.x = velocities[3 * i];
        particle->vel.y = velocities[3 * i + 1];
        particle->vel.z = velocities[3 * i + 2];
        LOG_ALLOW(LOCAL,LOG_DEBUG,"[Rank %d]Particle [%d] velocities unpacked to: [%.6f,%.6f,%.6f].\n",rank, i,particle->vel.x,particle->vel.y,particle->vel.z);
        
        // Initialize cell indices
        particle->cell[0] = cellIndices[3 * i];
        particle->cell[1] = cellIndices[3 * i + 1];
        particle->cell[2] = cellIndices[3 * i + 2];
        LOG_ALLOW(LOCAL,LOG_DEBUG,"[Rank %d]Particle [%d] cell indices set to: [%d, %d, %d].\n",rank,i, particle->cell[0], particle->cell[1], particle->cell[2]);
 
        particle->location_status = (ParticleLocationStatus)LocStatus[i];
        LOG_ALLOW(LOCAL,LOG_DEBUG, "[Rank %d]Particle [%d] Status set to: %d.\n",rank, i, particle->location_status);
 
        // The destination_rank is only set by the location search, not read from the swarm,
        // so we initialize it to a known invalid state.
        particle->destination_rank = MPI_PROC_NULL;
        
        // logging the completion of particle initialization
        LOG_ALLOW(LOCAL,LOG_INFO,"[Rank %d]Completed initialization of Particle [%d]. \n", rank,i);
        
        PetscFunctionReturn(0);
    }

Here is the caller graph for this function:

UpdateSwarmFields()

PetscErrorCode UpdateSwarmFields	(	PetscInt	i,
		const Particle *	particle,
		PetscReal *	weights,
		PetscInt *	cellIndices,
		PetscInt *	status_field
	)

Updates DMSwarm fields with data from a Particle struct.

This helper function writes back the modified Particle data to the corresponding DMSwarm fields.

Parameters

[in]	i	Index of the particle in the DMSwarm.
[in]	particle	Pointer to the Particle struct containing updated data.
[in,out]	weights	Pointer to the array of particle weights.
[in,out]	cellIndices	Pointer to the array of particle cell indices.
[in,out]	LocStatus	Pointer to the array of cell location status indicators.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Definition at line 909 of file ParticleSwarm.c.

                                                                                       {
        PetscFunctionBeginUser;
        
        if (particle == NULL) {
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Input Particle pointer is NULL.\n");
        }
        
        // logging the start of swarm fields update
        LOG_ALLOW(LOCAL,LOG_INFO,"Updating DMSwarm fields for Particle [%d].\n", i);
        
        // Update weights
        weights[3 * i]     = particle->weights.x;
        weights[3 * i + 1] = particle->weights.y;
        weights[3 * i + 2] = particle->weights.z;
        LOG_ALLOW(LOCAL,LOG_DEBUG,"Updated weights for Particle [%d]: (%.6f, %.6f, %.6f).\n", 
            i, weights[3 * i], weights[3 * i + 1], weights[3 * i + 2]);
        
        // Update cell indices
        cellIndices[3 * i]     = particle->cell[0];
        cellIndices[3 * i + 1] = particle->cell[1];
        cellIndices[3 * i + 2] = particle->cell[2];
        LOG_ALLOW(LOCAL,LOG_DEBUG, "Updated cell indices for Particle [%d]: [%d, %d, %d].\n", 
            i, cellIndices[3 * i], cellIndices[3 * i + 1], cellIndices[3 * i + 2]);
 
        status_field[i] = particle->location_status;
        LOG_ALLOW(LOCAL,LOG_DEBUG, "Updated location status for Particle [%d]: [%d].\n", 
            i, status_field[i]);
        
        // logging the completion of swarm fields update
        LOG_ALLOW(LOCAL,LOG_INFO,"Completed updating DMSwarm fields for Particle [%d].\n", i);
        
        PetscFunctionReturn(0);
    }

Here is the caller graph for this function:

IsParticleInsideBoundingBox()

PetscBool IsParticleInsideBoundingBox	(	const BoundingBox *	bbox,
		const Particle *	particle
	)

Checks if a particle's location is within a specified bounding box.

This function determines whether the given particle's location lies inside the provided bounding box. It performs an axis-aligned bounding box (AABB) check by comparing the particle's coordinates to the minimum and maximum coordinates of the bounding box in each dimension (x, y, z).

Logging statements are included to provide detailed information about the function's execution.

Parameters

[in]	bbox	Pointer to the BoundingBox structure containing minimum and maximum coordinates.
[in]	particle	Pointer to the Particle structure containing the particle's location and identifier.

Returns

PetscBool Returns PETSC_TRUE if the particle is inside the bounding box, PETSC_FALSE otherwise.

Note

• The function assumes that the bbox and particle pointers are valid and non-NULL.
• The function includes logging statements that start with the function name.
• Be cautious when logging in performance-critical code sections, especially if the function is called frequently.

This function determines whether the given particle's location lies inside the provided bounding box. It performs an axis-aligned bounding box (AABB) check by comparing the particle's coordinates to the minimum and maximum coordinates of the bounding box in each dimension (x, y, z).

logging statements are included to provide detailed information about the function's execution.

Parameters

[in]	bbox	Pointer to the BoundingBox structure containing minimum and maximum coordinates.
[in]	particle	Pointer to the Particle structure containing the particle's location and identifier.

Returns

PetscBool Returns PETSC_TRUE if the particle is inside the bounding box, PETSC_FALSE otherwise.

Note

• The function assumes that the bbox and particle pointers are valid and non-NULL.
• The function includes logging statements that start with the function name.
• The LOG_ALLOW_SCOPE variable is used to distinguish between GLOBAL and LOCAL LOG_ALLOW outputs.
• Be cautious when logging in performance-critical code sections, especially if the function is called frequently.

Definition at line 964 of file ParticleSwarm.c.

    {
        // Function name for logging purposes
        const char *funcName = "IsParticleInsideBoundingBox";
 
        // Validate input pointers
        if (!bbox) {
            // LOG_ALLOW error message and return PETSC_FALSE
        LOG_ALLOW(LOCAL,LOG_ERROR, "%s: Error - 'bbox' pointer is NULL.", funcName);
            return PETSC_FALSE;
        }
        if (!particle) {
        LOG_ALLOW(LOCAL,LOG_ERROR,"%s: Error - 'particle' pointer is NULL.", funcName);
            return PETSC_FALSE;
        }
 
        // Extract particle location and bounding box coordinates
        const Cmpnts loc = particle->loc;
        const Cmpnts min_coords = bbox->min_coords;
        const Cmpnts max_coords = bbox->max_coords;
 
        // LOG_ALLOW the particle location and bounding box coordinates for debugging
        LOG_ALLOW_SYNC(LOCAL, LOG_DEBUG, "%s: Particle PID %ld location: (%.6f, %.6f, %.6f).\n", funcName, particle->PID, loc.x, loc.y, loc.z);
        LOG_ALLOW_SYNC(LOCAL, LOG_DEBUG, "%s: BoundingBox min_coords: (%.6f, %.6f, %.6f), max_coords: (%.6f, %.6f, %.6f).\n",
            funcName, min_coords.x, min_coords.y, min_coords.z, max_coords.x, max_coords.y, max_coords.z);
 
        // Check if the particle's location is within the bounding box
        if ((loc.x >= min_coords.x && loc.x <= max_coords.x) &&
            (loc.y >= min_coords.y && loc.y <= max_coords.y) &&
            (loc.z >= min_coords.z && loc.z <= max_coords.z)) {
            // Particle is inside the bounding box
            LOG_ALLOW_SYNC(LOCAL,LOG_DEBUG, "%s: Particle PID %ld is inside the bounding box.\n", funcName, particle->PID);
            return PETSC_TRUE;
        }
 
        // Particle is outside the bounding box
        LOG_ALLOW_SYNC(LOCAL, LOG_DEBUG,"%s: Particle PID %ld is outside the bounding box.\n", funcName, particle->PID);
        return PETSC_FALSE;
    }

UpdateParticleWeights()

PetscErrorCode UpdateParticleWeights	(	PetscReal *	d,
		Particle *	particle
	)

Updates a particle's interpolation weights based on distances to cell faces.

This function computes interpolation weights using distances to the six cell faces (d) and updates the weight field of the provided particle.

Parameters

[in]	d	Pointer to an array of distances to the six cell faces.
[out]	particle	Pointer to the Particle structure whose weights are to be updated.

Returns

PetscErrorCode Returns 0 on success, or a non-zero error code on failure.

Definition at line 1015 of file ParticleSwarm.c.

                                                                           {
 
        // Validate input pointers
        if (!d || !particle) {
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
                    "UpdateParticleWeights - Null pointer argument (d or particle).");
        }
 
 
        // Validate distances
        for (PetscInt i = LEFT; i < NUM_FACES; i++) {
            if (d[i] <= INTERPOLATION_DISTANCE_TOLERANCE) {
                LOG_ALLOW(LOCAL, LOG_WARNING,
                    "UpdateParticleWeights - face distance d[%d] = %f <= %f; "
                    "clamping to 1e-14 to avoid zero/negative.\n",
                    i, (double)d[i], INTERPOLATION_DISTANCE_TOLERANCE);
                d[i] = INTERPOLATION_DISTANCE_TOLERANCE;
            }
        }
 
        // LOG_ALLOW the input distances
        LOG_ALLOW(LOCAL, LOG_DEBUG,
            "UpdateParticleWeights - Calculating weights with distances: "
            "[LEFT=%f, RIGHT=%f, BOTTOM=%f, TOP=%f, FRONT=%f, BACK=%f].\n",
            d[LEFT], d[RIGHT], d[BOTTOM], d[TOP], d[FRONT], d[BACK]);
 
        // Compute and update the particle's weights
        particle->weights.x = d[LEFT] / (d[LEFT] + d[RIGHT]);
        particle->weights.y = d[BOTTOM] / (d[BOTTOM] + d[TOP]);
        particle->weights.z = d[BACK] / (d[FRONT] + d[BACK]);
 
        // LOG_ALLOW the updated weights
        LOG_ALLOW(LOCAL,LOG_DEBUG,
            "UpdateParticleWeights - Updated particle weights: x=%f, y=%f, z=%f.\n",
            particle->weights.x, particle->weights.y, particle->weights.z);
 
        return 0;
    }

Here is the caller graph for this function:

PrepareLoadedSwarmForRelocation()

PetscErrorCode PrepareLoadedSwarmForRelocation

(

UserCtx *

user

)

Resets the location-dependent state of a loaded swarm to force relocation.

This function is a critical part of the simulation restart procedure. It must be called immediately after ReadAllSwarmFields has populated a swarm from restart files. Its purpose is to invalidate the "location" state of the loaded particles, ensuring that the LocateAllParticlesInGrid_TEST orchestrator performs a fresh, comprehensive search for every particle based on its loaded position.

It does this by performing two actions on every locally-owned particle:

1. It resets the DMSwarm_CellID field to a sentinel value of (-1, -1, -1). This invalidates any cell index that might have been loaded or defaulted to 0.
2. It sets the DMSwarm_location_status field to NEEDS_LOCATION.

This guarantees that the location logic will not mistakenly use a stale cell index from a previous run and will instead use the robust "Guess -> Verify" strategy appropriate for particles with unknown locations.

Parameters

[in,out]

user

Pointer to the UserCtx structure which contains the DMSwarm object that has just been loaded with data from restart files.

Returns

PetscErrorCode 0 on success, or a non-zero PETSc error code if field access fails.

Definition at line 1078 of file ParticleSwarm.c.

    {
        PetscErrorCode ierr;
        DM             swarm;
        PetscInt       n_local;
        PetscInt      *cell_p;    // Pointer to the raw data for the CellID field
        PetscInt      *status_p;  // Pointer to the raw data for the location_status field
        PetscInt64    *PIDs;      // Pointer to the raw data for the Particle ID field.
        PetscMPIInt   rank,size;
 
        PetscFunctionBeginUser;
 
        ierr = MPI_Comm_rank(PETSC_COMM_WORLD,&rank);  CHKERRQ(ierr);
        ierr = MPI_Comm_size(PETSC_COMM_WORLD,&size);  CHKERRQ(ierr);
 
        SimCtx *simCtx = user->simCtx;
        
        // --- 1. Input Validation and Setup ---
        if (!user || !user->swarm) {
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "UserCtx or its DMSwarm is NULL in PrepareLoadedSwarmForRelocation.");
        }
        swarm = user->swarm;
 
        // Get the number of particles on this MPI rank.
        ierr = DMSwarmGetLocalSize(swarm, &n_local); CHKERRQ(ierr);
 
        // If there are no local particles, there is nothing to do.
        if (n_local == 0) {
            PetscFunctionReturn(0);
        }
    
        
        LOG_ALLOW(GLOBAL, LOG_INFO, "Preparing %d loaded particles for relocation by resetting their CellID and Status.\n", n_local);
 
        // --- 2. Get Writable Access to Swarm Fields ---
        // This provides direct pointers to the underlying data arrays for the fields.
        ierr = DMSwarmGetField(swarm, "DMSwarm_CellID",          NULL, NULL, (void**)&cell_p);   CHKERRQ(ierr);
        ierr = DMSwarmGetField(swarm, "DMSwarm_location_status", NULL, NULL, (void**)&status_p); CHKERRQ(ierr);
        ierr = DMSwarmGetField(swarm, "DMSwarm_pid", NULL, NULL, (void**)&PIDs); CHKERRQ(ierr); CHKERRQ(ierr);
 
        // --- 3. Determine Starting Global PID for this Rank ---
        PetscInt particles_per_rank_ideal = simCtx->np / size; // Assumes user->size is PETSC_COMM_WORLD size
        PetscInt remainder_particles = simCtx->np % size;
        PetscInt base_pid_for_rank = rank * particles_per_rank_ideal + PetscMin(rank, remainder_particles);
        // This calculation must match how particlesPerProcess was determined (e.g., in DistributeParticles).
        
        // --- 4. Loop Through All Local Particles and Reset State ---
        for (PetscInt p = 0; p < n_local; ++p) {
 
            
            // Reset the 3 components of the cell index vector.
            cell_p[3*p + 0] = -1;
            cell_p[3*p + 1] = -1;
            cell_p[3*p + 2] = -1;
 
            // Reset the status to ensure it will be processed by the location algorithm.
            status_p[p] = (ParticleLocationStatus)UNINITIALIZED;
 
        //set the PID for each particle
        PIDs[p] =  (PetscInt64)base_pid_for_rank + p;
        }
 
        // --- 4. Restore Fields ---
        // This returns control of the data arrays back to the DMSwarm. It is a mandatory
        // step to ensure data consistency and prevent memory issues.
        ierr = DMSwarmRestoreField(swarm, "DMSwarm_CellID",          NULL, NULL, (void**)&cell_p);   CHKERRQ(ierr);
        ierr = DMSwarmRestoreField(swarm, "DMSwarm_location_status", NULL, NULL, (void**)&status_p); CHKERRQ(ierr);
        ierr = DMSwarmRestoreField(swarm, "DMSwarm_pid", NULL, NULL, (void**)&PIDs); CHKERRQ(ierr); CHKERRQ(ierr);
 
        LOG_ALLOW(GLOBAL, LOG_DEBUG, "Successfully reset location state for all loaded particles.\n");
 
        PetscFunctionReturn(0);
    }

Here is the caller graph for this function:

InitializeParticleSwarm()

PetscErrorCode InitializeParticleSwarm

(

SimCtx *

simCtx

)

Perform particle swarm initialization, particle-grid interaction, and related operations.

This function handles the following tasks:

1. Initializes the particle swarm using the provided bounding box list (bboxlist) to determine initial placement if ParticleInitialization is 0.
2. Locates particles within the computational grid.
3. Updates particle positions based on grid interactions (if such logic exists elsewhere in the code).
4. Interpolates particle velocities from grid points using trilinear interpolation.

Parameters

[in,out]	user	Pointer to the UserCtx structure containing grid and particle swarm information.
[in]	np	Number of particles to initialize in the swarm.
[in]	bboxlist	Pointer to an array of BoundingBox structures, one per MPI rank.

Returns

PetscErrorCode Returns 0 on success, non-zero on failure.

Note

• Ensure that np (number of particles) is positive.
• The bboxlist array must be correctly computed and passed in before calling this function.
• If ParticleInitialization == 0, particles will be placed at the midpoint of the local bounding box.

Definition at line 1174 of file ParticleSwarm.c.

    {
 
        PetscErrorCode ierr;
        PetscInt particlesPerProcess = 0;         // Number of particles assigned to the local MPI process.
        PetscRandom randx,randy,randz;     // Random number generators[x,y,z]. (used if ParticleInitialization==1).
        PetscRandom rand_logic_i, rand_logic_j,rand_logic_k; // RNGs for Logical space.
        PetscInt    start_step = simCtx->StartStep;
        PetscInt    np = simCtx->np;
        BoundingBox    *bboxlist = simCtx->bboxlist;
        UserCtx *user = simCtx->usermg.mgctx[simCtx->usermg.mglevels - 1].user;
        
        LOG_ALLOW(GLOBAL, LOG_INFO, "Starting particle swarm Initialization with %d particles.\n", np);
        
        // Step 1: Create and initialize the particle swarm
        // Here we pass in the bboxlist, which will be used by CreateParticleSwarm() and subsequently
        // by AssignInitialProperties() to position particles if ParticleInitialization == 0.
        LOG_ALLOW(GLOBAL, LOG_INFO, "Creating particle swarm.\n");
        ierr = CreateParticleSwarm(user, np, &particlesPerProcess,bboxlist); CHKERRQ(ierr);
        LOG_ALLOW(GLOBAL, LOG_INFO, "Particle swarm created successfully.\n");
 
        ierr = PetscOptionsGetInt(NULL, NULL, "-rstart", &start_step, NULL); CHKERRQ(ierr);
 
        if(start_step == 0){
        
        // Create the RNGs
        LOG_ALLOW(LOCAL, LOG_DEBUG, "Initializing physical space RNGs.\n");
        ierr = InitializeRandomGenerators(user, &randx, &randy, &randz); CHKERRQ(ierr);
        
        LOG_ALLOW(LOCAL, LOG_DEBUG, "Initializing logical space RNGs [0,1).\n");
        ierr = InitializeLogicalSpaceRNGs(&rand_logic_i, &rand_logic_j, &rand_logic_k); CHKERRQ(ierr);
        // Assign initial properties to particles
        // The bboxlist array is passed here so that if ParticleInitialization == 0,
        // particles can be placed at the midpoint of the local bounding box corresponding to this rank.
        ierr = AssignInitialPropertiesToSwarm(user, particlesPerProcess, &randx, &randy, &randz, &rand_logic_i,&rand_logic_j,&rand_logic_k,bboxlist); CHKERRQ(ierr);
        // Finalize swarm setup by destroying RNGs if ParticleInitialization == 1
        ierr = FinalizeSwarmSetup(&randx, &randy, &randz, &rand_logic_i, &rand_logic_j, &rand_logic_k); CHKERRQ(ierr);  
 
        // Ensure all ranks complete before proceeding
        LOG_ALLOW_SYNC(GLOBAL, LOG_INFO, " Particles generated & initialized.\n");
        }
        
        else if (start_step > 0){
 
        LOG_ALLOW(LOCAL,LOG_DEBUG," Particle Swarm status being set at restart [Step %d].\n",start_step);
        
        ierr = PreCheckAndResizeSwarm(user,start_step,"dat");
 
        // --- Read Particle Data (EVERY timestep) ---
        // ReadAllSwarmFields should read position and velocity for timestep 'ti'
        
        ierr = ReadAllSwarmFields(user, start_step);
        if (ierr) {
        // Check if the error was specifically a file open error (missing file)
        if (ierr == PETSC_ERR_FILE_OPEN) {
        LOG_ALLOW(GLOBAL, LOG_WARNING, "Missing particle data file(s) for timestep %d. Skipping VTK output for this step.\n",(PetscInt)user->simCtx->step );
        } else {
        LOG_ALLOW(GLOBAL, LOG_ERROR, "Failed to read swarm fields for timestep %d (Error code: %d). Skipping VTK output for this step.\n",(PetscInt)user->simCtx->step  , ierr);
        }
        }
 
        // Ensure  all the swarm fields not read from file are initialized.
        ierr = PrepareLoadedSwarmForRelocation(user);
        
        // Ensure all ranks complete before proceeding
        LOG_ALLOW_SYNC(GLOBAL, LOG_INFO, " Particles generated & initialized.\n");
        
        
        }
        return 0;
    }

Here is the call graph for this function:

Here is the caller graph for this function: