FieldMultiIndices.hpp

Go to the documentation of this file.

/** \file FieldMultiIndices.hpp
 * \brief Field data structure for finite element approximation spaces
 *
 * Stores field information including approximation space, basis functions,
 * coordinate systems, and DOF management data.
 */
 
 
 
#ifndef __FIELDMULTIINDICES_HPP__
#define __FIELDMULTIINDICES_HPP__
 
namespace MoFEM {
 
template <typename T> struct interface_RefEntity;
struct DofEntity;
 
/** \brief Function returning number of DOFs for given approximation order
 * \ingroup fe_multi_indices
 */
typedef boost::function<int(const int order)> FieldOrderFunct;
 
/** \brief Array of functions defining DOF count for each entity type
 * \ingroup dof_multi_indices
 */
typedef FieldOrderFunct FieldOrderTable[MBMAXTYPE];
 
/**
 * \brief Field data structure for finite element approximation
 * \ingroup dof_multi_indices
 *
 * Stores field information including approximation space, basis functions,
 * coordinate systems, and DOF management. Each field has a unique ID and name.
 * Data is shared between mesh entities and their associated DOFs.
 */
struct Field {
 
  /**
   * \brief Constructor for MOAB field
   * \param moab MOAB interface reference
   * \param meshset EntityHandle containing field entities
   */
  Field(moab::Interface &moab, const EntityHandle meshset);
 
  /** \brief Virtual destructor */
  virtual ~Field() = default;
 
  /** \brief Container for bulk DOF allocation */
  using SequenceDofContainer = multi_index_container<
      boost::weak_ptr<std::vector<DofEntity>>,
      indexed_by<sequenced<>>>;
 
  /** \brief Array mapping entity types to DOF order arrays */
  using DofsOrderMap =
      std::array<std::array<int, MAX_DOFS_ON_ENTITY>, MBMAXTYPE>;
 
  moab::Interface &moab; ///< MOAB interface reference
 
  EntityHandle meshSet; ///< Meshset containing field entities
 
  TagType tagFieldDataVertsType; ///< Tag type for vertex data storage
  Tag th_FieldDataVerts; ///< Tag for field values on vertices
  Tag th_FieldData;      ///< Tag for field values on entities
  Tag th_AppOrder;       ///< Tag for approximation order on entities
  Tag th_FieldRank;      ///< Tag for field rank (vector dimension)
 
  BitFieldId *tagId;                       ///< Field unique identifier
  FieldSpace *tagSpaceData;                ///< Field approximation space
  FieldContinuity *tagFieldContinuityData; ///< Field continuity type
  FieldApproximationBase *tagBaseData;     ///< Field basis functions
 
  /// Field rank (e.g. Temperature=1, displacement in 3D=3)
  FieldCoefficientsNumber *tagNbCoeffData;
  const void *tagName;           ///< Field name
  int tagNameSize;               ///< Field name size in bytes
  const void *tagNamePrefixData; ///< Field name prefix
  int tagNamePrefixSize;         ///< Field name prefix size in bytes
  FieldOrderTable forderTable;   ///< DOF count functions for each entity type
 
  /**
   * \brief Get field order table
   * \return Reference to DOF count functions for each entity type
   */
  inline FieldOrderTable &getFieldOrderTable() { return forderTable; }
 
  /** \brief Bit number corresponding to this field's unique ID */
  unsigned int bitNumber;
 
  /**
   * \brief Get field meshset handle
   *
   * On this meshset handle are stored tags with field data about base, space,
   * number of coefficients, continuity, etc.
   * 
   * Meshset contains entities on which the field is defined.
   *
   * \return EntityHandle containing field entities
   */
  inline EntityHandle getMeshset() const { return meshSet; }
  
  /**
   * \brief Get unique field identifier
   * \return Field ID bitset
   */
  inline const BitFieldId &getId() const { return *((BitFieldId *)tagId); }
 
  /**
   * \brief Get field name as string reference
   * \return Field name string reference
   */
  inline boost::string_ref getNameRef() const {
    return boost::string_ref((char *)tagName, tagNameSize);
  }
 
  /**
   * \brief Get field name as string
   * \return Field name string
   */
  inline std::string getName() const {
    return std::string((char *)tagName, tagNameSize);
  }
 
  /**
   * \brief Get field approximation space
   * \return Approximation space enumeration
   */
  inline FieldSpace getSpace() const { return *tagSpaceData; }
 
  /**
   * \brief Get field approximation space name
   * \return Approximation space name string
   */
  inline auto getSpaceName() const {
    return std::string(FieldSpaceNames[getSpace()]);
  }
 
  /**
   * \brief Get field continuity type
   *
   * There are two types of continuity: CONTINUOUS and DISCONTINUOUS.
   * Discontinuous is used to indicate broken spaces.
   *
   * \return Field continuity enumeration
   */
  inline FieldContinuity getContinuity() const {
    return *tagFieldContinuityData;
  }
 
  /**
   * \brief Get field continuity name
   * \return Field continuity name string
   */
  inline auto getContinuityName() const {
    return std::string(FieldContinuityNames[getContinuity()]);
  }
 
  /**
   * \brief Get approximation basis type
   * \return Approximation basis enumeration
   */
  inline FieldApproximationBase getApproxBase() const { return *tagBaseData; }
 
  /**
   * \brief Get approximation basis name
   * \return Approximation basis name string
   */
  inline auto getApproxBaseName() const {
    return std::string(ApproximationBaseNames[getApproxBase()]);
  }
 
  /**
   * \brief Get number of field coefficients per DOF
   * 
   * Scalar fields have 1 coefficient, vector fields in 3D have 3.
   * Coefficients may represent spatial components, physical quantities,
   * or mixed formulations depending on the field interpretation.
   * 
   * \return Number of coefficients
   */
  inline FieldCoefficientsNumber getNbOfCoeffs() const {
    return *tagNbCoeffData;
  };
 
  /**
   * \brief Get bit number for this field's ID
   * \return Bit position in field ID bitset
   */
  inline FieldBitNumber getBitNumber() const { return bitNumber; }
 
  /**
   * \brief Calculate bit number from field ID bitset
   * \param id Field ID bitset
   * \return Bit position (1-based) or 0 if no bits set
   */
  static inline FieldBitNumber getBitNumberCalculate(const BitFieldId &id) {
    static_assert(BITFIELDID_SIZE >= 32,
                  "Too many fields allowed, can be more but ...");
    FieldBitNumber b = ffsl(id.to_ulong());
    if (b != 0)
      return b;
    return 0;
  }
 
  /**
   * \brief Calculate bit number for this field's ID
   * \return Bit position (1-based) or 0 if no bits set
   */
  inline FieldBitNumber getBitNumberCalculate() const {
    return getBitNumberCalculate(static_cast<BitFieldId &>(*tagId));
  }
 
  /**
   * \brief Get sequence container for bulk DOF allocation
   * 
   * Container stores DOF data in bulk for efficiency. Vectors are destroyed
   * when last entity referencing them is removed. Used primarily for vertex
   * DOFs in H1 spaces where DOF count per vertex is fixed.
   * 
   * \return Reference to DOF sequence container
   */
  inline SequenceDofContainer &getDofSequenceContainer() const {
    return sequenceDofContainer;
  }
 
  /**
   * \brief Get DOF order mapping for specific entity type
   * \param type Entity type (vertex, edge, face, volume)
   * \return Array mapping DOF index to approximation order
   */
  inline const std::array<ApproximationOrder, MAX_DOFS_ON_ENTITY> &
  getDofOrderMap(const EntityType type) const {
    return dofOrderMap[type];
  }
 
  /**
   * \brief Get complete DOF order mapping for all entity types
   * \return Full DOF order mapping array
   */
  inline const DofsOrderMap &getDofOrderMap() const { return dofOrderMap; }
 
  static constexpr int maxBrokenDofsOrder = 10; ///< Maximum order for broken space DOFs
 
  /**
   * \brief Get DOF side mapping for broken spaces
   * 
   * Maps interior DOFs in broken spaces to entities where their traces
   * are non-zero. Used for discontinuous Galerkin methods.
   * 
   * \return Reference to DOF side mapping
   */
  inline std::map<int, BaseFunction::DofsSideMap> &getDofSideMap() const {
    return dofSideMap;
  }
 
  /**
   * \brief Rebuild DOF order mapping arrays
   * \return Error code
   */
  MoFEMErrorCode rebuildDofsOrderMap();
 
  /** \brief Output stream operator for field information */
  friend std::ostream &operator<<(std::ostream &os, const Field &e);
 
  /**
   * \brief Get raw pointer to this field
   * \return Pointer to this field object
   */
  inline const Field *getFieldRawPtr() const { return this; };
 
private:
  mutable SequenceDofContainer sequenceDofContainer;
  mutable DofsOrderMap dofOrderMap;
  mutable std::map<int, BaseFunction::DofsSideMap> dofSideMap;
};
 
/**
 * \brief Base template interface for field pointer management
 * 
 * Provides interface layer between Field class and derived entities.
 * Inherits from reference entity interface for pointer management.
 * 
 * \tparam FIELD Field type
 * \tparam REFENT Reference entity type
 * \ingroup dof_multi_indices
 */
template <typename FIELD, typename REFENT>
struct interface_FieldImpl : public interface_RefEntity<REFENT> {
 
  using interface_type_RefEntity = interface_RefEntity<REFENT>;
 
  /**
   * \brief Constructor with field and reference entity pointers
   * \param field_ptr Shared pointer to field
   * \param ref_ents_ptr Shared pointer to reference entity
   */
  interface_FieldImpl(const boost::shared_ptr<FIELD> &field_ptr,
                      const boost::shared_ptr<REFENT> &ref_ents_ptr)
      : interface_RefEntity<REFENT>(ref_ents_ptr) {}
  
  /** \brief Virtual destructor */
  virtual ~interface_FieldImpl() = default;
};
 
/**
 * \brief Field interface with separate field and reference entity types
 * \tparam FIELD Field type
 * \tparam REFENT Reference entity type
 */
template <typename FIELD, typename REFENT>
struct interface_Field : public interface_FieldImpl<FIELD, REFENT> {
 
  /**
   * \brief Constructor
   * \param field_ptr Shared pointer to field
   * \param ref_ents_ptr Shared pointer to reference entity
   */
  interface_Field(const boost::shared_ptr<FIELD> &field_ptr,
                  const boost::shared_ptr<REFENT> &ref_ents_ptr)
      : interface_FieldImpl<FIELD, REFENT>(field_ptr, ref_ents_ptr),
        sFieldPtr(field_ptr) {}
 
  /** \brief Get field meshset handle */
  inline EntityHandle getMeshset() const {
    return getFieldRawPtr()->getMeshset();
  }
 
  /** \brief Get coordinate system dimension */
  inline int getCoordSysDim(const int d = 0) const {
    return getFieldRawPtr()->getCoordSysDim(d);
  }
 
  /** \brief Get field ID */
  inline const BitFieldId &getId() const {
    return getFieldRawPtr()->getId();
  }
 
  /** \brief Get field name reference */
  inline boost::string_ref getNameRef() const {
    return getFieldRawPtr()->getNameRef();
  }
 
  /** \brief Get field name */
  inline std::string getName() const {
    return getFieldRawPtr()->getName();
  }
 
  /** \brief Get approximation space */
  inline FieldSpace getSpace() const {
    return getFieldRawPtr()->getSpace();
  }
 
  /** \brief Get approximation basis */
  inline FieldApproximationBase getApproxBase() const {
    return getFieldRawPtr()->getApproxBase();
  }
 
  /** \brief Get space continuity */
  inline FieldContinuity getContinuity() const {
    return getFieldRawPtr()->getContinuity();
  }
 
  /** \brief Get space continuity name */
  inline auto getContinuityName() const {
    return getFieldRawPtr()->getContinuityName();
  }
 
  /** \brief Get number of coefficients per DOF */
  inline FieldCoefficientsNumber getNbOfCoeffs() const {
    return getFieldRawPtr()->getNbOfCoeffs();
  }
 
  /** \brief Get bit number for field ID */
  inline FieldBitNumber getBitNumber() const {
    return getFieldRawPtr()->getBitNumber();
  }
 
  /**
   * \brief Get DOF order mapping for entity type
   * \param type Entity type
   * \return DOF order array
   */
  inline std::array<ApproximationOrder, MAX_DOFS_ON_ENTITY> &
  getDofOrderMap(const EntityType type) const {
    return getFieldRawPtr()->getDofOrderMap(type);
  }
 
  /** \brief Get raw field pointer */
  inline const Field *getFieldRawPtr() const {
    return sFieldPtr->getFieldRawPtr();
  };
 
  /** \brief Get field order table */
  inline FieldOrderTable &getFieldOrderTable() {
    return sFieldPtr->getFieldOrderTable();
  };
 
  /**
   * \brief Get DOF side mapping for broken spaces
   * 
   * Maps interior DOFs in broken spaces to entities where their traces
   * are non-zero. Used for discontinuous Galerkin methods.
   * 
   * \return Reference to DOF side mapping
   */
  inline auto &getDofSideMap() { return sFieldPtr->getDofSideMap(); }
 
private:
  mutable boost::shared_ptr<FIELD> sFieldPtr;
};
 
/**
 * \brief Field interface specialization for same field and reference types
 * \tparam T Field/reference type
 */
template <typename T>
struct interface_Field<T, T> : public interface_FieldImpl<T, T> {
  
  /**
   * \brief Constructor
   * \param ptr Shared pointer to field/reference object
   */
  interface_Field(const boost::shared_ptr<T> &ptr)
      : interface_FieldImpl<T, T>(ptr, ptr) {}
 
  using interface_type_FieldImpl = interface_FieldImpl<T,T>;
 
  /** \brief Get field meshset handle */
  inline EntityHandle getMeshset() const {
    return getFieldRawPtr()->getMeshset();
  }
 
  /** \brief Get field ID */
  inline const BitFieldId &getId() const {
    return getFieldRawPtr()->getId();
  }
 
  /** \brief Get field name reference */
  inline boost::string_ref getNameRef() const {
    return getFieldRawPtr()->getNameRef();
  }
 
  /** \brief Get field name */
  inline std::string getName() const {
    return getFieldRawPtr()->getName();
  }
 
  /** \brief Get approximation space */
  inline FieldSpace getSpace() const {
    return getFieldRawPtr()->getSpace();
  }
 
  /** \brief Get approximation space name */
  inline auto getSpaceName() const { return getFieldRawPtr()->getSpaceName(); }
 
  /** \brief Get approximation basis */
  inline FieldApproximationBase getApproxBase() const {
    return getFieldRawPtr()->getApproxBase();
  }
 
  /** \brief Get approximation basis name */
  inline auto getApproxBaseName() const {
    return getFieldRawPtr()->getApproxBaseName();
  }
 
  /** \brief Get number of coefficients per DOF */
  inline FieldCoefficientsNumber getNbOfCoeffs() const {
    return getFieldRawPtr()->getNbOfCoeffs();
  }
 
  /** \brief Get bit number for field ID */
  inline FieldBitNumber getBitNumber() const {
    return getFieldRawPtr()->getBitNumber();
  }
 
  /**
   * \brief Get DOF order mapping for entity type
   * \param type Entity type
   * \return DOF order array
   */
  inline std::array<ApproximationOrder, MAX_DOFS_ON_ENTITY> &
  getDofOrderMap(const EntityType type) const {
    return getFieldRawPtr()->getDofOrderMap(type);
  }
 
  /** \brief Get raw field pointer */
  inline const Field *getFieldRawPtr() const {
    return boost::static_pointer_cast<T>(this->getRefEntityPtr())
        ->getFieldRawPtr();
  };
};
 
/**
 * \brief Multi-index container for field storage and retrieval
 * 
 * Provides multiple indexed access patterns:
 * - By field ID (hash-based unique access)
 * - By meshset handle (ordered unique access)
 * - By field name (ordered unique access)
 * - By field space (ordered non-unique access)
 * 
 * \relates multi_index_container
 */
typedef multi_index_container<
    boost::shared_ptr<Field>,
    indexed_by<
        hashed_unique<tag<BitFieldId_mi_tag>,
                      const_mem_fun<Field, const BitFieldId &, &Field::getId>,
                      HashBit<BitFieldId>, EqBit<BitFieldId>>,
        ordered_unique<tag<Meshset_mi_tag>,
                       member<Field, EntityHandle, &Field::meshSet>>,
        ordered_unique<
            tag<FieldName_mi_tag>,
            const_mem_fun<Field, boost::string_ref, &Field::getNameRef>>,
        ordered_non_unique<tag<BitFieldId_space_mi_tag>,
                           const_mem_fun<Field, FieldSpace, &Field::getSpace>>>>
    Field_multiIndex;
 
/**
 * \brief Simplified field container with ID-based ordering
 * 
 * Single-index container providing ordered access by field ID only.
 * Used for efficient field iteration and subset operations.
 */
typedef multi_index_container<
    boost::shared_ptr<Field>,
    indexed_by<
        ordered_unique<tag<BitFieldId_mi_tag>,
                       const_mem_fun<Field, const BitFieldId &, &Field::getId>,
                       LtBit<BitFieldId>>>>
    Field_multiIndex_view;
 
} // namespace MoFEM
 
#endif // __FIELDMULTIINDICES_HPP__