BC_Handlers.h File Reference

#include "variables.h"
#include "logging.h"

Include dependency graph for BC_Handlers.h:

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

Go to the source code of this file.

Functions
PetscErrorCode	Validate_DrivenFlowConfiguration (UserCtx *user)
	(Private) Validates all consistency rules for a driven flow (channel/pipe) setup.
PetscErrorCode	Create_WallNoSlip (BoundaryCondition *bc)
	Configures a BoundaryCondition object to behave as a no-slip, stationary wall.
PetscErrorCode	Create_InletConstantVelocity (BoundaryCondition *bc)
	Configures a BoundaryCondition object to behave as a constant velocity inlet.
PetscErrorCode	Create_InletParabolicProfile (BoundaryCondition *bc)
	Configures a BoundaryCondition object for a parabolic inlet profile.
PetscErrorCode	Create_InletProfileFromFile (BoundaryCondition *bc)
	Configures a BoundaryCondition object for a file-prescribed inlet profile.
PetscErrorCode	Create_OutletConservation (BoundaryCondition *bc)
	Configures a BoundaryCondition object for conservative outlet treatment.
PetscErrorCode	Create_PeriodicGeometric (BoundaryCondition *bc)
	Configures a BoundaryCondition object for geometric periodic coupling.
PetscErrorCode	Create_PeriodicDrivenConstant (BoundaryCondition *bc)
	Configures a BoundaryCondition object for periodic driven-flow forcing.
PetscErrorCode	Create_PeriodicDrivenInitial (BoundaryCondition *bc)
	Configures a BoundaryCondition object for initial-flux periodic driving.

Function Documentation

Validate_DrivenFlowConfiguration()

PetscErrorCode Validate_DrivenFlowConfiguration

(

UserCtx *

user

)

(Private) Validates all consistency rules for a driven flow (channel/pipe) setup.

This function enforces a strict set of rules to ensure a driven flow simulation is configured correctly. It is called by the main BoundarySystem_Validate dispatcher.

The validation rules are checked in a specific order:

1. Detect if any DRIVEN_ handler is active. If not, the function returns immediately.
2. Ensure that no INLET, OUTLET, or FARFIELD boundary conditions exist anywhere in the domain, as they are physically incompatible with a pressure-driven flow model.
3. Verify that both faces in the driven direction are of mathematical_type PERIODIC.
4. Verify that both faces in the driven direction use the exact same DRIVEN_ handler type.

Parameters

user	The UserCtx for a single block.

Returns

PetscErrorCode 0 on success, non-zero PETSc error code on failure.

(Private) Validates all consistency rules for a driven flow (channel/pipe) setup.

Local to this translation unit.

Definition at line 15 of file BC_Handlers.c.

{
    PetscFunctionBeginUser;
 
    // --- CHECK 1: Detect if a driven flow is active. ---
    PetscBool is_driven_flow_active = PETSC_FALSE;
    char      driven_direction = ' ';
    const char* first_driven_face_name = "";
 
    for (int i = 0; i < 6; i++) {
        BCHandlerType handler_type = user->boundary_faces[i].handler_type;
        if (handler_type == BC_HANDLER_PERIODIC_DRIVEN_CONSTANT_FLUX ||
            handler_type == BC_HANDLER_PERIODIC_DRIVEN_INITIAL_FLUX)
        {
            is_driven_flow_active = PETSC_TRUE;
            first_driven_face_name = BCFaceToString((BCFace)i);
            
            if (i <= 1)      driven_direction = 'X';
            else if (i <= 3) driven_direction = 'Y';
            else             driven_direction = 'Z';
            
            break; // Exit loop once we've confirmed it's active and found the direction.
        }
    }
 
    // If no driven flow handler is found, validation for this rule set is complete.
    if (!is_driven_flow_active) {
        PetscFunctionReturn(0);
    }
    
    LOG_ALLOW(GLOBAL, LOG_DEBUG, "  - Driven Flow Handler detected on face %s. Applying driven flow validation rules...\n", first_driven_face_name);
 
    // --- CHECK 2: Ensure no conflicting BCs (Inlet/Outlet/Far-field) are present. ---
    LOG_ALLOW(GLOBAL, LOG_DEBUG, "  - Checking for incompatible Inlet/Outlet/Far-field BCs...\n");
    for (int i = 0; i < 6; i++) {
        BCType math_type = user->boundary_faces[i].mathematical_type;
        if (math_type == INLET || math_type == OUTLET || math_type == FARFIELD) {
             SETERRQ(PETSC_COMM_WORLD, PETSC_ERR_USER_INPUT,
                     "Configuration Error: A DRIVEN flow handler is active, which is incompatible with the %s boundary condition found on face %s.",
                     BCTypeToString(math_type), BCFaceToString((BCFace)i));
        }
    }
    LOG_ALLOW(GLOBAL, LOG_DEBUG, " ... No conflicting BC types found. OK.\n");
 
    // --- CHECK 3: Ensure both ends of the driven direction have identical, valid setups. ---
    LOG_ALLOW(GLOBAL, LOG_DEBUG, "      - Validating symmetry and mathematical types for the '%c' direction...\n", driven_direction);
    
    PetscInt neg_face_idx = 0, pos_face_idx = 0;
    if (driven_direction == 'X') {
        neg_face_idx = BC_FACE_NEG_X; pos_face_idx = BC_FACE_POS_X;
    } else if (driven_direction == 'Y') {
        neg_face_idx = BC_FACE_NEG_Y; pos_face_idx = BC_FACE_POS_Y;
    } else { // 'Z'
        neg_face_idx = BC_FACE_NEG_Z; pos_face_idx = BC_FACE_POS_Z;
    }
 
    BoundaryFaceConfig *neg_face_cfg = &user->boundary_faces[neg_face_idx];
    BoundaryFaceConfig *pos_face_cfg = &user->boundary_faces[pos_face_idx];
 
    // Rule 3a: Both faces must be PERIODIC.
    if (neg_face_cfg->mathematical_type != PERIODIC || pos_face_cfg->mathematical_type != PERIODIC) {
        SETERRQ(PETSC_COMM_WORLD, PETSC_ERR_USER_INPUT,
                "Configuration Error: For a driven flow in the '%c' direction, both the %s and %s faces must be of mathematical_type PERIODIC.",
                driven_direction, BCFaceToString((BCFace)neg_face_idx), BCFaceToString((BCFace)pos_face_idx));
    }
 
    // Rule 3b: Both faces must use the exact same handler type.
    if (neg_face_cfg->handler_type != pos_face_cfg->handler_type) {
        SETERRQ(PETSC_COMM_WORLD, PETSC_ERR_USER_INPUT,
                "Configuration Error: The DRIVEN handlers on the %s and %s faces of the '%c' direction do not match. Both must be the same type (e.g., both CONSTANT_FLUX).",
                BCFaceToString((BCFace)neg_face_idx), BCFaceToString((BCFace)pos_face_idx), driven_direction);
    }
    
    LOG_ALLOW(GLOBAL, LOG_DEBUG, "          ... Symmetry and mathematical types are valid. OK.\n");
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Create_WallNoSlip()

PetscErrorCode Create_WallNoSlip

(

BoundaryCondition *

bc

)

Configures a BoundaryCondition object to behave as a no-slip, stationary wall.

Parameters

[in,out]

bc

Boundary object whose callbacks and handler metadata are installed.

Returns

PetscErrorCode 0 on success.

Configures a BoundaryCondition object to behave as a no-slip, stationary wall.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/BC_Handlers.h.

See also

Create_WallNoSlip()

Definition at line 114 of file BC_Handlers.c.

{
    PetscFunctionBeginUser;
    
    if (!bc) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, 
                     "Input BoundaryCondition object is NULL in Create_WallNoSlip");
 
    // ✅ Set priority
    bc->priority   = BC_PRIORITY_WALL;
    
    // Assign function pointers
    bc->Initialize = NULL;
    bc->PreStep    = NULL;
    bc->Apply      = Apply_WallNoSlip;
    bc->PostStep   = NULL;
    bc->UpdateUbcs = NULL;
    bc->Destroy    = NULL;
    
    // No private data needed for this simple handler
    bc->data = NULL;
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Create_InletConstantVelocity()

PetscErrorCode Create_InletConstantVelocity

(

BoundaryCondition *

bc

)

Configures a BoundaryCondition object to behave as a constant velocity inlet.

Parameters

[in,out]

bc

Boundary object configured with the constant-velocity inlet callbacks.

Returns

PetscErrorCode 0 on success.

Configures a BoundaryCondition object to behave as a constant velocity inlet.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/BC_Handlers.h.

See also

Create_InletConstantVelocity()

Definition at line 322 of file BC_Handlers.c.

{
    PetscErrorCode ierr;
    PetscFunctionBeginUser;
    
    if (!bc) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "BoundaryCondition is NULL");
 
    InletConstantData *data = NULL;
    ierr = PetscMalloc1(1, &data); CHKERRQ(ierr);
    bc->data = (void*)data;
    
    bc->priority   = BC_PRIORITY_INLET;
    bc->Initialize = Initialize_InletConstantVelocity;
    bc->PreStep    = PreStep_InletConstantVelocity;
    bc->Apply      = Apply_InletConstantVelocity;
    bc->PostStep   = PostStep_InletConstantVelocity;
    bc->UpdateUbcs = NULL;
    bc->Destroy    = Destroy_InletConstantVelocity;
    
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Create_InletParabolicProfile()

PetscErrorCode Create_InletParabolicProfile

(

BoundaryCondition *

bc

)

Configures a BoundaryCondition object for a parabolic inlet profile.

The constructed handler computes inlet velocity as a profile function of transverse coordinates, typically used for laminar channel/pipe initialization.

Parameters

bc	A pointer to the generic BoundaryCondition object to be configured.

Returns

PetscErrorCode 0 on success.

Configures a BoundaryCondition object for a parabolic inlet profile.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/BC_Handlers.h.

See also

Create_InletParabolicProfile()

Definition at line 715 of file BC_Handlers.c.

{
    PetscErrorCode ierr;
    PetscFunctionBeginUser;
 
    if (!bc) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "BoundaryCondition is NULL");
 
    InletParabolicData *data = NULL;
    ierr = PetscMalloc1(1, &data); CHKERRQ(ierr);
    bc->data = (void*)data;
 
    bc->priority   = BC_PRIORITY_INLET;
    bc->Initialize = Initialize_InletParabolicProfile;
    bc->PreStep    = PreStep_InletParabolicProfile;
    bc->Apply      = Apply_InletParabolicProfile;
    bc->PostStep   = PostStep_InletParabolicProfile;
    bc->UpdateUbcs = NULL;
    bc->Destroy    = Destroy_InletParabolicProfile;
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Create_InletProfileFromFile()

PetscErrorCode Create_InletProfileFromFile

(

BoundaryCondition *

bc

)

Configures a BoundaryCondition object for a file-prescribed inlet profile.

The constructed handler reads a canonical PICSLICE scalar normal-speed profile and applies it through the existing inlet metric/sign convention.

Parameters

bc	A pointer to the generic BoundaryCondition object to be configured.

Returns

PetscErrorCode 0 on success.

Configures a BoundaryCondition object for a file-prescribed inlet profile.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/BC_Handlers.h.

See also

Create_InletProfileFromFile()

Definition at line 1292 of file BC_Handlers.c.

{
    PetscErrorCode ierr;
    PetscFunctionBeginUser;
 
    if (!bc) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "BoundaryCondition is NULL");
 
    InletProfileFileData *data = NULL;
    ierr = PetscMalloc1(1, &data); CHKERRQ(ierr);
    data->n1 = 0;
    data->n2 = 0;
    data->profile = NULL;
    data->min_speed = 0.0;
    data->max_speed = 0.0;
    data->source_file = NULL;
    bc->data = (void*)data;
 
    bc->priority   = BC_PRIORITY_INLET;
    bc->Initialize = Initialize_InletProfileFromFile;
    bc->PreStep    = PreStep_InletProfileFromFile;
    bc->Apply      = Apply_InletProfileFromFile;
    bc->PostStep   = PostStep_InletProfileFromFile;
    bc->UpdateUbcs = NULL;
    bc->Destroy    = Destroy_InletProfileFromFile;
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Create_OutletConservation()

PetscErrorCode Create_OutletConservation

(

BoundaryCondition *

bc

)

Configures a BoundaryCondition object for conservative outlet treatment.

The constructed handler applies outlet updates that preserve the solver's global mass/flux consistency assumptions.

Parameters

bc	A pointer to the generic BoundaryCondition object to be configured.

Returns

PetscErrorCode 0 on success.

Configures a BoundaryCondition object for conservative outlet treatment.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/BC_Handlers.h.

See also

Create_OutletConservation()

Definition at line 1644 of file BC_Handlers.c.

{
    PetscFunctionBeginUser;
    
    if (!bc) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Input BoundaryCondition is NULL");
 
    // This handler has the highest priority to ensure it runs after
    // all inflow fluxes have been calculated.
    bc->priority   = BC_PRIORITY_OUTLET;
    
    // Assign function pointers
    bc->Initialize = NULL; // No initialization needed
    bc->PreStep    = PreStep_OutletConservation;
    bc->Apply      = Apply_OutletConservation;
    bc->PostStep   = PostStep_OutletConservation;
    bc->UpdateUbcs = NULL;
    bc->Destroy    = NULL; // No private data to destroy
    
    bc->data = NULL;
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Create_PeriodicGeometric()

PetscErrorCode Create_PeriodicGeometric

(

BoundaryCondition *

bc

)

Configures a BoundaryCondition object for geometric periodic coupling.

This constructor wires periodic boundary callbacks that exchange values across opposite faces according to the configured periodic directions.

Parameters

bc	A pointer to the generic BoundaryCondition object to be configured.

Returns

PetscErrorCode 0 on success.

Configures a BoundaryCondition object for geometric periodic coupling.

Full API contract (arguments, ownership, side effects) is documented with the header declaration in include/BC_Handlers.h.

See also

Create_PeriodicGeometric()

Definition at line 2159 of file BC_Handlers.c.

                                                              {
    PetscFunctionBeginUser;
    
    if (!bc) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Input BoundaryCondition is NULL");
    bc->priority = BC_PRIORITY_WALL;
 
    // Assign function pointers
    bc->Initialize = NULL; // No initialization needed
    bc->PreStep    = NULL;
    bc->Apply      = NULL;
    bc->PostStep   = NULL;
    bc->UpdateUbcs = NULL;
    bc->Destroy    = NULL; // No private data to destroy
 
    bc->data = NULL;
 
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

Create_PeriodicDrivenConstant()

PetscErrorCode Create_PeriodicDrivenConstant

(

BoundaryCondition *

bc

)

Configures a BoundaryCondition object for periodic driven-flow forcing.

This constructor wires the periodic callbacks that enforce a prescribed driving strategy (for example constant target flux) on a periodic direction pair.

Parameters

bc	A pointer to the generic BoundaryCondition object to be configured.

Returns

PetscErrorCode 0 on success.

Configures a BoundaryCondition object for periodic driven-flow forcing.

Local to this translation unit.

Definition at line 2325 of file BC_Handlers.c.

{
    PetscErrorCode ierr;
    PetscFunctionBeginUser;
    
    if (!bc) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Input BoundaryCondition object is NULL in Create_PeriodicDrivenConstantFlux");
 
    // --- Allocate the private data structure ---
    DrivenFluxData *data = NULL;
    ierr = PetscNew(&data); CHKERRQ(ierr);
    // Initialize fields to safe default values
    data->direction = ' ';
    data->targetVolumetricFlux = 0.0;
    data->isMasterController = PETSC_FALSE;
    data->enforceSeamFlux = PETSC_FALSE;
    data->lastBulkCorrectionStep = -1;
    
    // Attach the private data to the generic handler object
    bc->data = (void*)data;
    
    // --- Configure the handler's properties and methods ---
    
    // Set priority: Using BC_PRIORITY_INLET ensures this handler's PreStep runs
    // before other handlers (like outlets) that might depend on its calculations.
    // It is the caller's responsibility that there are no Inlets called along with driven periodic to avoid clash.
    bc->priority   = BC_PRIORITY_INLET;
    
    // Assign the function pointers to the implementations in this file.
    bc->Initialize = Initialize_PeriodicDrivenConstant;
    bc->PreStep    = PreStep_PeriodicDrivenConstant;
    bc->Apply      = Apply_PeriodicDrivenConstant;
    bc->PostStep   = NULL; // This handler has no action after the main solver step.
    bc->UpdateUbcs = NULL; // The boundary value is not flow-dependent (it's periodic).
    bc->Destroy    = Destroy_PeriodicDrivenConstant;
    
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Create_PeriodicDrivenInitial()

PetscErrorCode Create_PeriodicDrivenInitial

(

BoundaryCondition *

bc

)

Configures a BoundaryCondition object for initial-flux periodic driving.

Wires the same periodic callbacks as Create_PeriodicDrivenConstant(), but the target flux is measured from the field the run starts with rather than read from the bcs file, so this handler takes no target_flux parameter. The latched target is checkpointed so a restart holds the original value.

Parameters

bc	A pointer to the generic BoundaryCondition object to be configured.

Returns

PetscErrorCode 0 on success.

Configures a BoundaryCondition object for initial-flux periodic driving.

Local to this translation unit.

Definition at line 2669 of file BC_Handlers.c.

{
    PetscErrorCode ierr;
    PetscFunctionBeginUser;
 
    if (!bc) SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_NULL, "Input BoundaryCondition object is NULL in Create_PeriodicDrivenInitial");
 
    // --- Allocate the private data structure ---
    DrivenFluxData *data = NULL;
    ierr = PetscNew(&data); CHKERRQ(ierr);
    // Initialize fields to safe default values
    data->direction = ' ';
    data->targetVolumetricFlux = 0.0;
    data->isMasterController = PETSC_FALSE;
    data->enforceSeamFlux = PETSC_FALSE;
    data->lastBulkCorrectionStep = -1;
 
    // Attach the private data to the generic handler object
    bc->data = (void*)data;
 
    // --- Configure the handler's properties and methods ---
 
    // Same priority reasoning as the constant-flux handler: PreStep must run
    // before any handler that depends on the controller's corrections.
    bc->priority   = BC_PRIORITY_INLET;
 
    bc->Initialize = Initialize_PeriodicDrivenInitial;
    bc->PreStep    = PreStep_PeriodicDrivenInitial;
    bc->Apply      = Apply_PeriodicDrivenConstant;  // Boundary trim is target-agnostic.
    bc->PostStep   = NULL; // This handler has no action after the main solver step.
    bc->UpdateUbcs = NULL; // The boundary value is not flow-dependent (it's periodic).
    bc->Destroy    = Destroy_PeriodicDrivenConstant; // Same private data layout.
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function: