BcManager.hpp

Go to the documentation of this file.

/** \file BcManager.hpp
 * \brief High-level boundary condition management interface
 * \ingroup bc_manager
 *
 * The BcManager provides a high-level interface for applying boundary conditions
 * to finite element problems, working in close integration with MeshsetsManager
 * to bridge mesh-based boundary condition definitions with finite element
 * implementations.
 *
 * \section bcm_integration MeshsetsManager Integration
 * 
 * BcManager operates as the application layer above MeshsetsManager:
 * - **Data Discovery**: MeshsetsManager discovers and organizes boundary condition
 *   meshsets from various mesh formats (CUBIT, Gmsh, Salome, etc.)
 * - **DOF Management**: BcManager translates meshset information into DOF-level
 *   operations for finite element problem setup
 * - **Type Safety**: Provides type-safe interfaces for different boundary condition
 *   types while maintaining format independence
 * - **Problem Integration**: Handles DOF marking, removal, and Index Set creation
 *   for seamless integration with finite element solvers
 *
 * \section bcm_essential_natural Essential vs Natural Boundary Conditions
 * 
 * BcManager supports both essential and natural boundary condition implementations:
 * 
 * \subsection bcm_essential Essential Boundary Conditions (Dirichlet)
 * - **Implementation**: Applied by removing constrained DOFs from the system
 * - **DOF Removal**: `removeBlockDOFsOnEntities()` eliminates constrained DOFs
 * - **System Modification**: Reduces system size by eliminating known DOFs
 * - **Examples**: Fixed displacements, prescribed temperatures, velocity constraints
 * - **Workflow**: Mark DOFs → Remove from system → Apply prescribed values
 * 
 * \subsection bcm_natural Natural Boundary Conditions (Neumann)
 * - **Implementation**: Applied through load vectors and surface integrals
 * - **DOF Marking**: `pushMarkDOFsOnEntities()` identifies affected DOFs
 * - **Entity Access**: Provides entity ranges for integration operations
 * - **Examples**: Applied forces, pressure loads, heat flux, traction boundaries
 * - **Workflow**: Mark DOFs → Integrate over boundaries → Add to load vector
 * 
 * \section bcm_specializations Template Specializations
 * 
 * BcManager uses template specializations to handle different boundary condition
 * types and meshset configurations in a type-safe manner:
 * 
 * \subsection bcm_meshset_types Meshset Type Specializations
 * - **BcMeshsetType<DISPLACEMENTSET>**: Displacement boundary conditions on nodesets
 * - **BcMeshsetType<FORCESET>**: Force boundary conditions on nodesets
 * - **BcMeshsetType<TEMPERATURESET>**: Temperature boundary conditions on nodesets
 * - **BcMeshsetType<HEATFLUXSET>**: Heat flux boundary conditions on sidesets
 * - **BcMeshsetType<PRESSURESET>**: Pressure boundary conditions on sidesets
 * 
 * \subsection bcm_block_specializations Block-Based Specializations
 * - **BcDisplacementMeshsetType<BLOCKSET>**: Volume-based displacement constraints
 * - **BcScalarMeshsetType<BLOCKSET>**: Volume-based scalar field constraints
 * - **BcForceMeshsetType<BLOCKSET>**: Volume-based force application
 * - **BcPressureMeshsetType<BLOCKSET>**: Volume-based pressure conditions
 * - **BcNormalDisplacementMeshsetType<BLOCKSET>**: Normal displacement constraints
 * - **BcAnalyticalDisplacementMeshsetType<BLOCKSET>**: Analytical displacement functions
 * - **BcAnalyticalTractionMeshsetType<BLOCKSET>**: Analytical traction functions
 * 
 * \subsection bcm_data_specializations Data Structure Specializations
 * - **DisplacementCubitBcData**: CUBIT displacement boundary condition data
 * - **TemperatureCubitBcData**: CUBIT temperature boundary condition data
 * - **HeatFluxCubitBcData**: CUBIT heat flux boundary condition data
 * - **ForceCubitBcData**: CUBIT force boundary condition data
 * - **PressureCubitBcData**: CUBIT pressure boundary condition data
 * 
 * \section bcm_specialization_purpose Purpose of Specializations
 * 
 * \subsection bcm_type_safety Type Safety and Compile-Time Checking
 * 
 * The template specialization system provides several critical benefits:
 * 
 * **1. Geometric Entity Differentiation (NODESET vs SIDESET vs BLOCKSET):**
 * - **NODESET (0D)**: Point-based boundary conditions applied to mesh vertices
 *   - Essential: Dirichlet constraints removing DOF degrees of freedom
 *   - Natural: Concentrated loads applied at specific points
 * - **SIDESET (2D)**: Surface-based boundary conditions applied to mesh faces
 *   - Essential: Surface-distributed constraints (e.g., zero normal displacement)
 *   - Natural: Pressure loads, heat flux, traction forces requiring surface integration
 * - **BLOCKSET (3D)**: Volume-based constraints and body forces applied to mesh regions
 *   - Essential: Domain-wide field constraints and material property assignments
 *   - Natural: Body forces, heat sources, manufacturing forces within volumes
 * 
 * **2. Physics-Specific Type Safety:**
 * - **DisplacementCubitBcData**: Vector fields with 3 spatial components (Ux, Uy, Uz)
 * - **TemperatureCubitBcData**: Scalar field with single temperature value
 * - **ForceCubitBcData**: Vector loading with force magnitude and direction
 * - **PressureCubitBcData**: Scalar pressure with automatic normal direction calculation
 * - **HeatFluxCubitBcData**: Scalar flux with surface orientation handling
 * 
 * **3. Compile-Time Dispatch Benefits:**
 * - Prevents runtime errors by catching type mismatches during compilation
 * - Enables optimized code generation for each boundary condition type
 * - Provides clear separation between essential (constraint) and natural (loading) operations
 * - Allows physics-specific validation and error checking
 * 
 * **4. Essential vs Natural BC Implementation Patterns:**
 * ```cpp
 * // Essential BC Pattern (DOF removal):
 * bc_manager.removeBlockDOFsOnEntities<BcMeshsetType<DISPLACEMENTSET>>(
 *     "problem", "DISPLACEMENT", true, false, false);
 * 
 * // Natural BC Pattern (DOF marking for integration):
 * bc_manager.pushMarkDOFsOnEntities<BcMeshsetType<FORCESET>>(
 *     "problem", "DISPLACEMENT", true, false);
 * ```
 * 
 * **5. BLOCKSET Specializations for Advanced Physics:**
 * - **Volume Constraints**: Entire material regions with uniform properties
 * - **Body Forces**: Gravitational, centrifugal, or manufacturing loads
 * - **Material Interfaces**: Coupling between different physics domains
 * - **Analytical Functions**: Mathematical expressions for complex loading patterns
 * - **Multi-Physics Coupling**: Temperature-dependent displacement constraints
 * 
 * \subsection bcm_geometry_handling Geometry-Specific Handling
 * - **NODESET Operations**: Point-based constraints and loads (0D entities)
 * - **SIDESET Operations**: Surface-based conditions and fluxes (2D entities)
 * - **BLOCKSET Operations**: Volume-based constraints and body forces (3D entities)
 * - **Bridge Dimensions**: Proper handling of DOF-to-geometry associations
 * 
 * \subsection bcm_physics_separation Physics-Specific Implementations
 * - **Mechanical**: Displacement, force, pressure, traction boundary conditions
 * - **Thermal**: Temperature and heat flux boundary conditions
 * - **Multi-Physics**: Coupled boundary condition handling across physics domains
 * - **Analytical**: Mathematical function-based boundary condition application
 * 
 * \section bcm_workflow Typical Workflow
 * 
 * 1. **Mesh Loading**: MeshsetsManager discovers boundary condition meshsets
 * 2. **BC Detection**: BcManager identifies available boundary condition types
 * 3. **Essential BCs**: Remove constrained DOFs using `removeBlockDOFsOnEntities()`
 * 4. **Natural BCs**: Mark affected DOFs using `pushMarkDOFsOnEntities()`
 *
 */
 
#ifndef __BCMANAGER_HPP__
#define __BCMANAGER_HPP__
 
#include "UnknownInterface.hpp"
 
namespace MoFEM {
 
/**
 * \brief Template specialization system for type-safe boundary condition handling
 * \ingroup bc_manager
 *
 * The following template structures provide compile-time type safety for different
 * boundary condition types and meshset configurations. Each template specialization
 * ensures that the correct handling logic is applied based on the boundary condition
 * type and the geometric entity type (NODESET, SIDESET, BLOCKSET).
 *
 * \section template_overview Template System Overview
 * 
 * The template system serves several critical purposes:
 * - **Type Safety**: Prevents mixing incompatible boundary condition types
 * - **Compile-Time Dispatch**: Selects appropriate implementation at compile time
 * - **Code Organization**: Separates physics-specific and geometry-specific logic
 * - **Interface Consistency**: Provides uniform interface across different BC types
 */
 
/**
 * \brief Base template for general boundary condition meshset types
 * \tparam BC CUBIT boundary condition type (DISPLACEMENTSET, FORCESET, etc.)
 *
 * This is the primary template for handling boundary conditions defined on
 * traditional CUBIT meshset types (NODESET, SIDESET). It provides the foundation
 * for most standard boundary condition operations.
 */
template <CubitBC BC> struct BcMeshsetType {};
 
/**
 * \brief Template specialization for scalar field boundary conditions
 * \tparam BC CUBIT boundary condition type for scalar fields
 *
 * Specialized handling for scalar field boundary conditions such as temperature,
 * pressure, or other single-component field constraints. Provides optimized
 * operations for scalar DOF manipulation.
 */
template <CubitBC BC> struct BcScalarMeshsetType {};
 
/**
 * \brief Type alias for temperature boundary conditions
 * \tparam BC CUBIT boundary condition type for temperature
 *
 * Convenience alias that maps temperature boundary conditions to the scalar
 * meshset type specialization, providing a more intuitive interface for
 * thermal analysis applications.
 */
template <CubitBC BC> using BcTemperature = BcScalarMeshsetType<BC>;
 
/**
 * \brief Template specialization for displacement boundary conditions
 * \tparam BC CUBIT boundary condition type for displacements
 *
 * Specialized handling for vector displacement boundary conditions, including
 * support for partial constraints (e.g., fixing only x-direction) and
 * multi-component displacement fields.
 */
template <CubitBC BC> struct BcDisplacementMeshsetType {};
 
/**
 * \brief Template specialization for force boundary conditions
 * \tparam BC CUBIT boundary condition type for forces
 *
 * Handles vector force boundary conditions including concentrated forces,
 * distributed loads, and moment applications. Supports both nodal and
 * surface-based force applications.
 */
template <CubitBC BC> struct BcForceMeshsetType {};
 
/**
 * \brief Template specialization for flux boundary conditions
 * \tparam BC CUBIT boundary condition type for fluxes
 *
 * Specialized for flux-type boundary conditions such as heat flux, mass flux,
 * or other transport phenomena. Typically applied to surface entities
 * (SIDESET) with appropriate integration procedures.
 */
template <CubitBC BC> struct BcFluxMeshsetType {};
 
/**
 * \brief Template specialization for normal displacement constraints
 * \tparam BC CUBIT boundary condition type for normal displacements
 *
 * Handles boundary conditions that constrain motion normal to a surface.
 * Common in contact mechanics, symmetry conditions, and sliding boundary
 * implementations.
 */
template <CubitBC BC> struct BcNormalDisplacementMeshsetType {};
 
/**
 * \brief Template specialization for analytical displacement functions
 * \tparam BC CUBIT boundary condition type for analytical displacements
 *
 * Supports boundary conditions defined by mathematical functions rather than
 * discrete values. Useful for exact solutions, manufactured solutions, and
 * complex time-dependent boundary conditions.
 */
template <CubitBC BC> struct BcAnalyticalDisplacementMeshsetType {};
 
/**
 * \brief Template specialization for analytical traction functions
 * \tparam BC CUBIT boundary condition type for analytical tractions
 *
 * Handles traction boundary conditions defined by mathematical functions.
 * Enables complex loading patterns and time-dependent surface tractions
 * through analytical expressions.
 */
template <CubitBC BC> struct BcAnalyticalTractionMeshsetType {};
 
/**
 * \brief Template specialization for pressure boundary conditions
 * \tparam BC CUBIT boundary condition type for pressure
 *
 * Specialized handling for pressure loads applied to surfaces. Includes
 * support for both uniform and spatially-varying pressure distributions,
 * with proper normal vector calculations for surface integration.
 */
template <CubitBC BC> struct BcPressureMeshsetType {};
 
/**
 * \brief Boundary condition manager for finite element problem setup
 * \ingroup mofem_simple_interface
 *
 * The BcManager provides a high-level, type-safe interface for applying boundary
 * conditions to finite element problems. It serves as the bridge between MeshsetsManager's
 * mesh-based boundary condition discovery and the actual implementation of Essential
 * and Natural boundary conditions in finite element computations.
 *
 * \section bcm_meshsets_connection Connection to MeshsetsManager
 * 
 * BcManager operates as the application layer above MeshsetsManager:
 * 
 * **Data Flow Architecture:**
 * 1. **MeshsetsManager**: Discovers and organizes meshsets from mesh files
 * 2. **BcManager**: Translates meshset data into DOF-level operations
 * 3. **Essential/Natural BC Classes**: Use BcManager data for implementation
 * 
 * **Information Transfer:**
 * - **Meshset Discovery**: MeshsetsManager finds boundary condition meshsets
 * - **Entity Extraction**: BcManager gets entity ranges from meshsets
 * - **DOF Identification**: BcManager maps entities to specific DOFs
 * - **Constraint Application**: Essential/Natural BC classes apply constraints
 * 
 * \section bcm_essential_natural Essential and Natural BC Implementation
 * 
 * BcManager provides the foundation for both Essential and Natural boundary condition
 * implementations through different operational modes:
 * 
 * \subsection bcm_essential_implementation Essential Boundary Conditions (Dirichlet)
 * 
 * **Implementation Strategy**: Remove constrained DOFs from the finite element system
 * 
 * **BcManager Role:**
 * - **DOF Identification**: `pushMarkDOFsOnEntities()` identifies constrained DOFs
 * - **DOF Removal**: `removeBlockDOFsOnEntities()` eliminates DOFs from system
 * - **Index Set Creation**: `getBlockIS()` creates PETSc IS for remaining DOFs
 * - **Problem Modification**: Reduces system size by eliminating known DOFs
 * 
 * **Typical Essential BC Workflow:**
 * ```cpp
 * // 1. Mark DOFs for boundary condition
 * bc_manager.pushMarkDOFsOnEntities<DisplacementCubitBcData>(
 *     problem_name, field_name);
 * 
 * // 2. Remove constrained DOFs from system
 * bc_manager.removeBlockDOFsOnEntities<DisplacementCubitBcData>(
 *     problem_name, field_name);
 * 
 * // 3. Apply prescribed values to eliminated DOFs
 * // (handled by Essential BC implementation classes)
 * ```
 * 
 * **Examples**: Fixed displacements, prescribed temperatures, velocity constraints
 * 
 * \subsection bcm_natural_implementation Natural Boundary Conditions (Neumann)
 * 
 * **Implementation Strategy**: Apply through load vectors and boundary integrals
 * 
 * **BcManager Role:**
 * - **DOF Marking**: `pushMarkDOFsOnEntities()` identifies affected DOFs
 * - **Entity Access**: `getBcStructure()` provides entity ranges for integration
 * - **Marker Creation**: `getMergedBlocksMarker()` combines multiple BC regions
 * - **Integration Support**: Maintains DOFs in system for load application
 * 
 * **Typical Natural BC Workflow:**
 * ```cpp
 * // 1. Mark DOFs affected by boundary condition
 * bc_manager.pushMarkDOFsOnEntities<ForceCubitBcData>(
 *     problem_name, field_name);
 * 
 * // 2. Get entity range for boundary integration
 * auto bc_data = bc_manager.getBcStructure(block_name);
 * auto entities = bc_data->getBcEntsPtr();
 * 
 * // 3. Integrate over boundary entities
 * // (handled by Natural BC implementation classes)
 * ```
 * 
 * **Examples**: Applied forces, pressure loads, heat flux, traction boundaries
 * 
 * \section bcm_usage_with_implementations Usage with BC Implementation Classes
 * 
 * Essential and Natural BC implementation classes use BcManager as their data source:
 * 
 * **Essential BC Classes Usage:**
 * - Obtain constrained DOF information from BcManager
 * - Use DOF removal functionality to modify system matrices
 * - Access prescribed values from CUBIT boundary condition data structures
 * - Implement constraint enforcement through system modification
 * 
 * **Natural BC Classes Usage:**
 * - Obtain entity ranges for boundary integration from BcManager
 * - Access load values from CUBIT boundary condition data structures
 * - Implement load application through boundary element integration
 * - Add contributions to global load vectors
 * 
 * \section bcm_template_specializations Template Specialization System
 * 
 * BcManager uses template specializations to provide type-safe, physics-specific
 * boundary condition handling:
 * 
 * **NODESET vs SIDESET vs BLOCKSET Specializations:**
 * - **NODESET (0D)**: Point-based constraints and loads
 * - **SIDESET (2D)**: Surface-based conditions and fluxes  
 * - **BLOCKSET (3D)**: Volume-based constraints and body forces
 * 
 * **Physics-Specific Specializations:**
 * - **Displacement**: Vector field constraints with component selection
 * - **Temperature**: Scalar field constraints with thermal properties
 * - **Force**: Vector loads with proper load transfer
 * - **Pressure**: Normal surface loads with area integration
 * - **Flux**: Surface flux conditions with normal projections
 * 
 * Key capabilities:
 * - Automatic DOF marking and removal for boundary conditions
 * - Type-safe boundary condition handling through template specializations
 * - Integration with CUBIT boundary condition data structures
 * - Block-based boundary condition management with regex pattern matching
 * - Index set generation for PETSc solver integration
 * - Parallel boundary condition synchronization
 */
struct BcManager : public UnknownInterface {
 
  /**
   * \brief Query interface for BcManager
   * 
   * @param type_index type index for the interface to query
   * @param iface pointer to store the interface
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  MoFEMErrorCode query_interface(boost::typeindex::type_index type_index,
                                 UnknownInterface **iface) const;
 
  /**
   * \brief Constructor for BcManager
   * 
   * @param core reference to MoFEM Core interface for accessing mesh and field data
   */
  BcManager(const MoFEM::Core &core);
  virtual ~BcManager() = default;
 
  /**
   * @brief Data structure storing boundary condition markers and attributes
   * \ingroup mofem_simple_interface
   *
   * The BCs structure encapsulates all data associated with a boundary condition
   * block, including entity ranges, DOF markers, attributes, and type-specific
   * boundary condition data. It provides shared pointer access to component data
   * for efficient memory management and integration with finite element operations.
   */
  struct BCs : boost::enable_shared_from_this<BCs> {
    Range bcEnts; ///< Range of entities in the boundary condition block
    std::vector<double> bcAttributes; ///< Numerical attributes (material properties, etc.)
    std::vector<unsigned char> bcMarkers; ///< DOF markers for boundary condition application
 
    using DofsView = std::vector<boost::weak_ptr<NumeredDofEntity>>;
    boost::shared_ptr<DofsView> dofsViewPtr; ///< View of DOFs associated with boundary condition
 
    boost::shared_ptr<DisplacementCubitBcData> dispBcPtr; ///< Displacement boundary condition data
    boost::shared_ptr<TemperatureCubitBcData> tempBcPtr; ///< Temperature boundary condition data
    boost::shared_ptr<HeatFluxCubitBcData> heatFluxBcPtr; ///< Heat flux boundary condition data
    boost::shared_ptr<ForceCubitBcData> forceBcPtr; ///< Force boundary condition data
    boost::shared_ptr<PressureCubitBcData> pressureBcPtr; ///< Pressure boundary condition data
 
    /**
     * \deprecated Use getBcEntsPtr() instead
     * \brief Get shared pointer to boundary condition entities
     * @return boost::shared_ptr<Range> Shared pointer to entity range
     */
    DEPRECATED inline auto getBcEdgesPtr() {
      return boost::shared_ptr<Range>(shared_from_this(), &bcEnts);
    }
 
    /**
     * \brief Get shared pointer to boundary condition entities
     * 
     * Provides safe shared access to the entity range for the boundary condition.
     * The shared pointer ensures proper lifetime management when the entity range
     * is used across different parts of the application.
     *
     * @return boost::shared_ptr<Range> Shared pointer to entity range
     */
    inline auto getBcEntsPtr() {
      return boost::shared_ptr<Range>(shared_from_this(), &bcEnts);
    }
 
    /**
     * \brief Get shared pointer to boundary condition markers
     * 
     * Provides safe shared access to the DOF marker vector. Markers are used
     * to identify which DOFs should be constrained or modified by the boundary
     * condition during finite element assembly and solving.
     *
     * @return boost::shared_ptr<std::vector<unsigned char>> Shared pointer to marker vector
     */
    inline auto getBcMarkersPtr() {
      return boost::shared_ptr<std::vector<unsigned char>>(shared_from_this(),
                                                           &bcMarkers);
    }
  };
 
  /**
   * \brief Get command line options for BcManager
   * \ingroup mofem_simple_interface
   *
   * Retrieves configuration options from command line arguments that control
   * boundary condition processing behavior and integration settings.
   *
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  MoFEMErrorCode getOptions();
 
  /**
   * @brief Mark DOFs on side entities for boundary conditions
   * \ingroup mofem_simple_interface
   * 
   * Marks DOFs associated with side entities (faces, edges) of a specified block
   * for boundary condition application. This is commonly used for surface-based
   * boundary conditions like pressure, traction, or flux conditions.
   * 
   * @param problem_name name of the finite element problem
   * @param block_name name of the boundary condition block/meshset
   * @param field_name name of the field containing the DOFs
   * @param bridge_dim dimension of bridge entities connecting DOFs to sides
   * @param lo lowest coefficient (rank) to mark
   * @param hi highest coefficient (rank) to mark
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  MoFEMErrorCode pushMarkSideDofs(const std::string problem_name,
                                  const std::string block_name,
                                  const std::string field_name, int bridge_dim,
                                  int lo, int hi);
 
  /**
   * @brief Remove DOFs on side entities from problem
   * \ingroup mofem_simple_interface
   * 
   * Removes DOFs associated with side entities from the finite element problem.
   * This is typically used to enforce boundary conditions by eliminating
   * constrained DOFs from the solution system.
   * 
   * @param problem_name name of the finite element problem
   * @param block_name name of the boundary condition block/meshset
   * @param field_name name of the field containing the DOFs
   * @param bridge_dim dimension of bridge entities connecting DOFs to sides
   * @param lo lowest coefficient (rank) to remove
   * @param hi highest coefficient (rank) to remove
   * @param is_distributed_mesh true if mesh is distributed across processes
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  MoFEMErrorCode removeSideDOFs(const std::string problem_name,
                                const std::string block_name,
                                const std::string field_name, int bridge_dim,
                                int lo, int hi,
                                bool is_distributed_mesh = true);
 
  /**
   * @brief Remove DOFs from problem based on block entities
   * \ingroup mofem_simple_interface
   *
   * Removes DOFs associated with entities in a specified block from the finite
   * element problem. This is the primary method for enforcing Dirichlet boundary
   * conditions by eliminating constrained DOFs from the system.
   *
   * @param problem_name name of the finite element problem
   * @param block_name name of the boundary condition block/meshset
   * @param field_name name of the field containing the DOFs to remove
   * @param lo lowest coefficient (rank) to remove
   * @param hi highest coefficient (rank) to remove
   * @param get_low_dim_ents include lower dimensional entities in the operation
   * @param is_distributed_mesh true if mesh is distributed across processes
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  MoFEMErrorCode removeBlockDOFsOnEntities(const std::string problem_name,
                                           const std::string block_name,
                                           const std::string field_name, int lo,
                                           int hi, bool get_low_dim_ents = true,
                                           bool is_distributed_mesh = true);
 
  /**
   * @brief Mark DOFs on block entities for boundary conditions
   * \ingroup mofem_simple_interface
   *
   * Marks DOFs associated with entities in a specified block for boundary
   * condition processing. This creates internal data structures needed for
   * subsequent boundary condition application or DOF removal operations.
   *
   * @param problem_name name of the finite element problem
   * @param block_name name of the boundary condition block/meshset
   * @param field_name name of the field containing the DOFs to mark
   * @param lo lowest coefficient (rank) to mark
   * @param hi highest coefficient (rank) to mark
   * @param get_low_dim_ents include lower dimensional entities in the operation
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  MoFEMErrorCode pushMarkDOFsOnEntities(const std::string problem_name,
                                        const std::string block_name,
                                        const std::string field_name, int lo,
                                        int hi, bool get_low_dim_ents = true);
 
  /**
   * @brief Remove DOFs based on boundary condition type template
   * \ingroup mofem_simple_interface
   *
   * Template-based DOF removal that automatically determines the appropriate
   * meshset type and boundary condition handling based on the template parameter.
   * Supports various boundary condition types including displacement, temperature,
   * heat flux, force, and pressure conditions.
   *
   * @tparam T boundary condition type template parameter
   * @param problem_name name of the finite element problem
   * @param field_name name of the field containing the DOFs
   * @param get_low_dim_ents include lower dimensional entities
   * @param block_name_field_prefix use field name as block name prefix
   * @param is_distributed_mesh true if mesh is distributed across processes
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  template <typename T>
  MoFEMErrorCode removeBlockDOFsOnEntities(const std::string problem_name,
                                           const std::string field_name,
                                           bool get_low_dim_ents = true,
                                           bool block_name_field_prefix = false,
                                           bool is_distributed_mesh = true);
 
  /**
   * @brief Mark DOFs based on boundary condition type template
   * \ingroup mofem_simple_interface
   *
   * Template-based DOF marking that automatically determines the appropriate
   * meshset type and boundary condition handling. Creates internal data structures
   * for subsequent boundary condition processing operations.
   *
   * @tparam T boundary condition type template parameter
   * @param problem_name name of the finite element problem
   * @param field_name name of the field containing the DOFs
   * @param get_low_dim_ents include lower dimensional entities
   * @param block_name_field_prefix use field name as block name prefix
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  template <typename T>
  MoFEMErrorCode pushMarkDOFsOnEntities(const std::string problem_name,
                                        const std::string field_name,
                                        bool get_low_dim_ents = true,
                                        bool block_name_field_prefix = false);
 
  /**
   * @brief Remove DOFs with explicit block specification
   * \ingroup mofem_simple_interface
   *
   * Template-based DOF removal with explicit block name specification.
   * Provides fine-grained control over which specific block is processed
   * while maintaining type-safe boundary condition handling.
   *
   * @tparam T boundary condition type template parameter
   * @param problem_name name of the finite element problem
   * @param block_name specific name of the boundary condition block
   * @param field_name name of the field containing the DOFs
   * @param get_low_dim_ents include lower dimensional entities
   * @param is_distributed_mesh true if mesh is distributed across processes
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  template <typename T>
  MoFEMErrorCode removeBlockDOFsOnEntities(const std::string problem_name,
                                           const std::string block_name,
                                           const std::string field_name,
                                           bool get_low_dim_ents = true,
                                           bool is_distributed_mesh = true);
 
  /**
   * @brief Mark DOFs with explicit block specification
   * \ingroup mofem_simple_interface
   *
   * Template-based DOF marking with explicit block name specification.
   * Creates internal data structures for the specified boundary condition
   * block while maintaining type-safe boundary condition handling.
   *
   * @tparam T boundary condition type template parameter
   * @param problem_name name of the finite element problem
   * @param block_name specific name of the boundary condition block
   * @param field_name name of the field containing the DOFs
   * @param get_low_dim_ents include lower dimensional entities
   * @return MoFEMErrorCode Error code indicating success or failure
   */
  template <typename T>
  MoFEMErrorCode pushMarkDOFsOnEntities(const std::string problem_name,
                                        const std::string block_name,
                                        const std::string field_name,
                                        bool get_low_dim_ents = true);
 
  /**
   * @brief Retrieve and remove boundary condition data
   * \ingroup mofem_simple_interface
   *
   * Retrieves the boundary condition data structure for a specified block
   * and removes it from the internal management system. This is typically
   * used when transferring boundary condition data to other processing
   * stages or when cleaning up after boundary condition application.
   *
   * @param block_name name of the boundary condition block to retrieve
   * @return boost::shared_ptr<BCs> Shared pointer to boundary condition data structure
   */
  boost::shared_ptr<BCs> popMarkDOFsOnEntities(const std::string block_name);
 
  /** \todo Add markers for standard BCs from cubit on Nodesets and Sidesets used
   * by cubit for displacements, forces, etc. Also add function to add blockset
   * by id and type.
   */
 
  using BcMapByBlockName = std::map<string, boost::shared_ptr<BCs>>; ///< Map of boundary condition blocks by name
 
  using BcMarkerPtr = boost::shared_ptr<std::vector<char unsigned>>; ///< Shared pointer to marker vector
  
  /**
   * @brief Get boundary condition structure by identifier
   * \ingroup mofem_simple_interface
   *
   * Retrieves the boundary condition data structure for a specific block
   * identifier. Provides direct access to the internal boundary condition
   * management system for advanced operations.
   *
   * @param bc_id identifier of the boundary condition block
   * @return auto Reference to the boundary condition structure
   */
  inline auto getBcStructure(const std::string bc_id) {
    return bcMapByBlockName.at(bc_id);
  }
 
  /**
   * @brief Get the boundary condition map
   * \ingroup mofem_simple_interface
   *
   * Provides access to the complete map of boundary condition blocks
   * managed by this BcManager instance. Useful for iteration and
   * bulk operations on multiple boundary conditions.
   *
   * @return BcMapByBlockName& Reference to the boundary condition map
   */
  inline BcMapByBlockName &getBcMapByBlockName() { return bcMapByBlockName; }
 
  /**
   * @brief Merge entity ranges from multiple boundary condition blocks
   * \ingroup mofem_simple_interface
   *
   * Combines entity ranges from multiple boundary condition blocks that match
   * the provided regular expression patterns. This is useful for creating
   * composite boundary conditions or applying operations to multiple related
   * boundary condition blocks simultaneously.
   *
   * @param bc_regex_vec vector of regular expressions for block name matching
   * @return Range Merged range containing entities from all matching blocks
   */
  Range getMergedBlocksRange(std::vector<std::regex> bc_regex_vec);
 
  /**
   * @brief Merge entity ranges by boundary condition names
   * \ingroup mofem_simple_interface
   *
   * Convenience function that merges entity ranges from boundary condition
   * blocks with names containing the specified substrings. Automatically
   * constructs regular expressions for flexible name matching.
   *
   * @param bc_names vector of boundary condition name patterns to match
   * @return Range Merged range containing entities from all matching blocks
   */
  inline auto getMergedBlocksRange(std::vector<string> bc_names) {
    std::vector<std::regex> reg_vec(bc_names.size());
    for (int i = 0; i != bc_names.size(); ++i) {
      auto full_name = std::string("(.*)_") + bc_names[i] + std::string("(.*)");
      reg_vec[i] = std::regex(full_name);
    }
    return getMergedBlocksRange(reg_vec);
  }
 
  /**
   * @brief Merge DOF markers from multiple boundary condition blocks
   * \ingroup mofem_simple_interface
   *
   * Combines DOF marker vectors from multiple boundary condition blocks that
   * match the provided regular expression patterns. The resulting marker vector
   * represents the union of all DOF constraints from the matching blocks.
   *
   * @param bc_regex_vec vector of regular expressions for block name matching
   * @return BcMarkerPtr Shared pointer to merged marker vector
   */
  BcMarkerPtr getMergedBlocksMarker(std::vector<std::regex> bc_regex_vec);
  
  /**
   * @brief Merge DOF markers by boundary condition names
   * \ingroup mofem_simple_interface
   *
   * Convenience function that merges DOF marker vectors from boundary condition
   * blocks with names containing the specified substrings. Useful for combining
   * markers from related boundary conditions into a single constraint system.
   *
   * @param bc_names vector of boundary condition name patterns to match
   * @return BcMarkerPtr Shared pointer to merged marker vector
   */
  inline auto getMergedBlocksMarker(std::vector<string> bc_names) {
    std::vector<std::regex> reg_vec(bc_names.size());
    for (int i = 0; i != bc_names.size(); ++i) {
      auto full_name = std::string("(.*)_") + bc_names[i] + std::string("(.*)");
      reg_vec[i] = std::regex(full_name);
    }
    return getMergedBlocksMarker(reg_vec);
  }
  
  /**
   * @brief Merge pre-existing marker vectors
   * \ingroup mofem_simple_interface
   *
   * Combines multiple existing DOF marker vectors into a single unified marker
   * vector. This allows for flexible composition of boundary condition constraints
   * from different sources or processing stages.
   *
   * @param boundary_markers_ptr_vec vector of marker pointers to merge
   * @return BcMarkerPtr Shared pointer to merged marker vector
   */
  BcMarkerPtr getMergedBlocksMarker(
      const std::vector<BcMarkerPtr> &boundary_markers_ptr_vec);
 
  /**
   * @brief Check if boundary condition matches regular expression
   * \ingroup mofem_simple_interface
   *
   * Tests whether a boundary condition block name matches the provided
   * regular expression pattern. This is used internally for filtering
   * and selecting boundary condition blocks based on naming patterns.
   *
   * @param bc map element containing block name and boundary condition data
   * @param reg regular expression pattern for matching
   * @return bool true if the block name matches the pattern
   */
  inline auto checkBlock(const std::pair<string, boost::shared_ptr<BCs>> &bc,
                         std::regex reg) {
    return std::regex_match(bc.first, reg);
  }
  
  /**
   * @brief Check if boundary condition matches name pattern
   * \ingroup mofem_simple_interface
   *
   * Tests whether a boundary condition block name contains the specified
   * substring pattern. Automatically constructs a flexible regular expression
   * for convenient name-based filtering.
   *
   * @param bc map element containing block name and boundary condition data
   * @param name substring pattern to search for in the block name
   * @return bool true if the block name contains the pattern
   */
  inline auto
  checkBlock(const std::pair<std::string, boost::shared_ptr<BCs>> &bc,
             std::string name) {
    auto full_name = std::string("(.*)_") + name + std::string("(.*)");
    return checkBlock(bc, std::regex(full_name));
  }
 
  /**
   * @brief Create PETSc Index Set for boundary condition block
   * \ingroup mofem_simple_interface
   *
   * Generates a PETSc Index Set (IS) containing DOF indices for a specified
   * boundary condition block. The IS can be used for matrix/vector operations,
   * subproblem creation, and solver configuration in PETSc-based computations.
   *
   * @param block_prefix prefix for block name construction
   * @param block_name name of the boundary condition block
   * @param field_name name of the field containing the DOFs
   * @param problem_name name of the finite element problem
   * @param lo lowest coefficient (rank) to include
   * @param hi highest coefficient (rank) to include
   * @param is_expand optional existing IS to expand with new indices
   * @return SmartPetscObj<IS> Smart pointer to PETSc Index Set
   */
  SmartPetscObj<IS>
  getBlockIS(const std::string block_prefix, const std::string block_name,
             const std::string field_name, const std::string problem_name,
             int lo, int hi, SmartPetscObj<IS> is_expand = SmartPetscObj<IS>());
 
  /**
   * @brief Create PETSc Index Set for boundary condition block (simplified)
   * \ingroup mofem_simple_interface
   *
   * Simplified version that generates a PETSc Index Set for a boundary condition
   * block without requiring a separate block prefix. This is the most commonly
   * used interface for creating IS objects for boundary condition processing.
   *
   * @param problem_name name of the finite element problem
   * @param block_name name of the boundary condition block
   * @param field_name name of the field containing the DOFs
   * @param lo lowest coefficient (rank) to include
   * @param hi highest coefficient (rank) to include
   * @param is_expand optional existing IS to expand with new indices
   * @return SmartPetscObj<IS> Smart pointer to PETSc Index Set
   */
  SmartPetscObj<IS>
  getBlockIS(const std::string problem_name, const std::string block_name,
             const std::string field_name, int lo, int hi,
             SmartPetscObj<IS> is_expand = SmartPetscObj<IS>());
 
  /**
   * @brief Extract block name and block name from block id
   *
   * @param block_id
   * @param prb_name
   * @return std::pair<std::string, std::string>
   */
  static std::pair<std::string, std::string>
  extractStringFromBlockId(const std::string block_id,
                           const std::string prb_name);
 
private:
  MoFEM::Core &cOre;
 
  BcMapByBlockName bcMapByBlockName;
};
 
template <>
MoFEMErrorCode
BcManager::removeBlockDOFsOnEntities<BcMeshsetType<DISPLACEMENTSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode
BcManager::removeBlockDOFsOnEntities<BcMeshsetType<TEMPERATURESET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode BcManager::removeBlockDOFsOnEntities<BcMeshsetType<HEATFLUXSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode
BcManager::removeBlockDOFsOnEntities<BcDisplacementMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode
BcManager::removeBlockDOFsOnEntities<BcScalarMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string block_name,
    const std::string field_name, bool get_low_dim_ents,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode
BcManager::pushMarkDOFsOnEntities<BcMeshsetType<DISPLACEMENTSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<BcMeshsetType<TEMPERATURESET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<BcMeshsetType<HEATFLUXSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode
BcManager::pushMarkDOFsOnEntities<BcDisplacementMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<BcScalarMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    const std::string block_name, bool get_low_dim_ents);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<DisplacementCubitBcData>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::removeBlockDOFsOnEntities<DisplacementCubitBcData>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<TemperatureCubitBcData>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::removeBlockDOFsOnEntities<TemperatureCubitBcData>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<HeatFluxCubitBcData>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::removeBlockDOFsOnEntities<HeatFluxCubitBcData>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<BcMeshsetType<FORCESET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<BcForceMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<ForceCubitBcData>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode BcManager::removeBlockDOFsOnEntities<BcMeshsetType<FORCESET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode
BcManager::removeBlockDOFsOnEntities<BcForceMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode BcManager::removeBlockDOFsOnEntities<ForceCubitBcData>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix,
    bool is_distributed_mesh);
 
template <>
MoFEMErrorCode
BcManager::pushMarkDOFsOnEntities<BcNormalDisplacementMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode
BcManager::pushMarkDOFsOnEntities<BcAnalyticalDisplacementMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode
BcManager::pushMarkDOFsOnEntities<BcAnalyticalTractionMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);    
 
template <>
MoFEMErrorCode BcManager::pushMarkDOFsOnEntities<BcMeshsetType<PRESSURESET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
template <>
MoFEMErrorCode
BcManager::pushMarkDOFsOnEntities<BcPressureMeshsetType<BLOCKSET>>(
    const std::string problem_name, const std::string field_name,
    bool get_low_dim_ents, bool block_name_field_prefix);
 
} // namespace MoFEM
 
#endif //__BCMANAGER_HPP__
 
/**
 * \defgroup bc_manager Manages boundary conditions
 * \brief Implementation manages boundary conditions
 *
 * \ingroup mofem
 **/