field_catalog.c

Go to the documentation of this file.

/**
 * @file field_catalog.c
 * @brief Authoritative persistent-Eulerian-field catalog and runtime view resolver.
 */
 
#include "field_catalog.h"
#include "logging.h"
 
 
#define FIELD_ENTRY(field_id_, name_, alias1_, alias2_, dof_, dm_, layout_, sync_, availability_, capabilities_, global_member_, local_member_, dimension_) \
    [field_id_] = {                                                                                                                                 \
        field_id_, name_, alias1_, alias2_, dof_, dm_, layout_, sync_, availability_, capabilities_,                                              \
        offsetof(UserCtx, global_member_), offsetof(UserCtx, local_member_), dimension_                                                             \
    }
 
static const FieldDescriptor gFieldCatalog[FIELD_ID_COUNT] = {
    FIELD_ENTRY(FIELD_ID_COORDINATES, "Coordinates", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_NODE_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS, FIELD_CAPABILITY_GHOST_UPDATE, Coor, lCoor,
                FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_UCAT, "Ucat", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC |
                FIELD_CAPABILITY_CHECKPOINT, Ucat, lUcat,
                FIELD_DIM_VELOCITY),
    FIELD_ENTRY(FIELD_ID_UCONT, "Ucont", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_COMPONENT_STAGGERED,
                FIELD_SYNC_COMPONENT_STAGGERED, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_STAGGERED_SYNC |
                FIELD_CAPABILITY_CHECKPOINT, Ucont, lUcont,
                FIELD_DIM_VOLUME_FLUX),
    FIELD_ENTRY(FIELD_ID_UCONT_O, "Ucont_o", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_COMPONENT_STAGGERED,
                FIELD_SYNC_COMPONENT_STAGGERED, FIELD_AVAILABILITY_FINEST_LEVEL,
                FIELD_CAPABILITY_GHOST_UPDATE, Ucont_o, lUcont_o,
                FIELD_DIM_VOLUME_FLUX),
    FIELD_ENTRY(FIELD_ID_UCONT_RM1, "Ucont_rm1", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_COMPONENT_STAGGERED,
                FIELD_SYNC_COMPONENT_STAGGERED, FIELD_AVAILABILITY_FINEST_LEVEL,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_CHECKPOINT, Ucont_rm1, lUcont_rm1,
                FIELD_DIM_VOLUME_FLUX),
    FIELD_ENTRY(FIELD_ID_P, "P", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC |
                FIELD_CAPABILITY_CHECKPOINT, P, lP,
                FIELD_DIM_PRESSURE),
    FIELD_ENTRY(FIELD_ID_NU_T, "Nu_t", "Eddy Viscosity", NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_TURBULENCE,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC |
                FIELD_CAPABILITY_CHECKPOINT, Nu_t, lNu_t,
                FIELD_DIM_DIFFUSIVITY),
    /* Holds the model coefficient C that multiplies Delta^2 |S|, which is Cs^2 in the
       classical notation and is signed once backscatter is admitted. Exists only for
       the dynamic model; the constant model prescribes its coefficient from config. */
    FIELD_ENTRY(FIELD_ID_CS, "CS", "Cs", NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_LES_DYNAMIC,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC |
                FIELD_CAPABILITY_CHECKPOINT, CS, lCs,
                FIELD_DIM_DIMENSIONLESS),
    /* Wall-model friction velocity, nonzero only in the first interior cell of a WALL
       face (the RMS over the cell's wall faces). It is the quantity a wall model is scored
       against, and it is computed from the reference cell rather than the cell it is stored
       in, so it is checkpointed and exposed to postprocessing rather than recomputed. */
    FIELD_ENTRY(FIELD_ID_U_TAU, "Utau", "Friction Velocity", NULL, 1, FIELD_DM_DA,
                FIELD_LAYOUT_CELL_CENTERED, FIELD_SYNC_STANDARD,
                FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_WALL_MODEL,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC |
                FIELD_CAPABILITY_CHECKPOINT, Friction_Velocity, lFriction_Velocity,
                FIELD_DIM_VELOCITY),
    /* The wall model's kinematic wall shear stress, one vector per wall-face element,
       stored in that face's dummy cell (no two wall faces share one) and oriented as the
       face's viscous flux per unit area. The viscous operator applies it on the wall face
       in place of a gradient flux. Derived state, rebuilt every wall pass, so not
       checkpointed. */
    FIELD_ENTRY(FIELD_ID_WALL_STRESS, "WallStress", "Wall Shear Stress", NULL, 3, FIELD_DM_FDA,
                FIELD_LAYOUT_CELL_CENTERED, FIELD_SYNC_STANDARD,
                FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_WALL_MODEL,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC,
                Wall_Stress, lWall_Stress,
                FIELD_DIM_VELOCITY_SQUARED),
    /* The synthetic-inflow time filter's state: three unit-variance components per inlet face
       cell, stored in that face's dummy plane. It carries the inflow's memory, so a restart
       reads it back. Only its inlets read it, through the global vector; the restart's ghost
       refresh of the local copy is harmless. */
    FIELD_ENTRY(FIELD_ID_INFLOW_FLUCTUATION, "InflowFluctuation", NULL, NULL, 3, FIELD_DM_FDA,
                FIELD_LAYOUT_CELL_CENTERED, FIELD_SYNC_STANDARD,
                FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_INFLOW_FLUCTUATION,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_CHECKPOINT, InflowFluctuation, lInflowFluctuation,
                FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_DIFFUSIVITY, "Diffusivity", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC, Diffusivity, lDiffusivity,
                FIELD_DIM_DIFFUSIVITY),
    FIELD_ENTRY(FIELD_ID_DIFFUSIVITY_GRADIENT, "DiffusivityGradient", NULL, NULL, 3, FIELD_DM_FDA,
                FIELD_LAYOUT_CELL_CENTERED, FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC, DiffusivityGradient, lDiffusivityGradient,
                FIELD_DIM_VELOCITY),
    FIELD_ENTRY(FIELD_ID_CSI, "Csi", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_I_FACE,
                FIELD_SYNC_I_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, Csi, lCsi,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_ETA, "Eta", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_J_FACE,
                FIELD_SYNC_J_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, Eta, lEta,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_ZET, "Zet", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_K_FACE,
                FIELD_SYNC_K_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, Zet, lZet,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_NVERT, "Nvert", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC |
                FIELD_CAPABILITY_CHECKPOINT, Nvert, lNvert,
                FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_AJ, "Aj", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC, Aj, lAj,
                FIELD_DIM_INVERSE_VOLUME),
    FIELD_ENTRY(FIELD_ID_CENT, "Cent", "Center-Coordinates", NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS, FIELD_CAPABILITY_GHOST_UPDATE, Cent, lCent,
                FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_CENTX, "Centx", "X-Face-Centers", NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_I_FACE,
                FIELD_SYNC_I_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC |
                FIELD_CAPABILITY_PERIODIC_GEOMETRY_SHIFT, Centx, lCentx,
                FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_CENTY, "Centy", "Y-Face-Centers", NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_J_FACE,
                FIELD_SYNC_J_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC |
                FIELD_CAPABILITY_PERIODIC_GEOMETRY_SHIFT, Centy, lCenty,
                FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_CENTZ, "Centz", "Z-Face-Centers", NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_K_FACE,
                FIELD_SYNC_K_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC |
                FIELD_CAPABILITY_PERIODIC_GEOMETRY_SHIFT, Centz, lCentz,
                FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_ICSI, "ICsi", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_I_FACE,
                FIELD_SYNC_I_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, ICsi, lICsi,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_IETA, "IEta", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_I_FACE,
                FIELD_SYNC_I_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, IEta, lIEta,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_IZET, "IZet", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_I_FACE,
                FIELD_SYNC_I_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, IZet, lIZet,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_JCSI, "JCsi", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_J_FACE,
                FIELD_SYNC_J_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, JCsi, lJCsi,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_JETA, "JEta", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_J_FACE,
                FIELD_SYNC_J_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, JEta, lJEta,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_JZET, "JZet", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_J_FACE,
                FIELD_SYNC_J_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, JZet, lJZet,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_KCSI, "KCsi", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_K_FACE,
                FIELD_SYNC_K_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, KCsi, lKCsi,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_KETA, "KEta", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_K_FACE,
                FIELD_SYNC_K_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, KEta, lKEta,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_KZET, "KZet", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_K_FACE,
                FIELD_SYNC_K_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, KZet, lKZet,
                FIELD_DIM_AREA),
    FIELD_ENTRY(FIELD_ID_IAJ, "IAj", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_I_FACE,
                FIELD_SYNC_I_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, IAj, lIAj,
                FIELD_DIM_INVERSE_VOLUME),
    FIELD_ENTRY(FIELD_ID_JAJ, "JAj", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_J_FACE,
                FIELD_SYNC_J_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, JAj, lJAj,
                FIELD_DIM_INVERSE_VOLUME),
    FIELD_ENTRY(FIELD_ID_KAJ, "KAj", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_K_FACE,
                FIELD_SYNC_K_FACE, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_FACE_SYNC, KAj, lKAj,
                FIELD_DIM_INVERSE_VOLUME),
    FIELD_ENTRY(FIELD_ID_PHI, "Phi", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_ALWAYS,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC, Phi, lPhi,
                FIELD_DIM_PRESSURE),
    FIELD_ENTRY(FIELD_ID_PSI, "Psi", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_CHECKPOINT |
                FIELD_CAPABILITY_PARTICLE_SAMPLED, Psi, lPsi,
                FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_NVERT_O, "Nvert_o", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL,
                FIELD_CAPABILITY_GHOST_UPDATE, Nvert_o, lNvert_o,
                FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_PARTICLE_COUNT, "ParticleCount", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_CHECKPOINT, ParticleCount, lParticleCount,
                FIELD_DIM_DIMENSIONLESS),
    /* Corner-staging workspace. Node-centered by construction: the interpolation
     * writes cell-centered data onto grid corners. Not checkpointed, since it is
     * transient scratch rebuilt on every conversion. */
    FIELD_ENTRY(FIELD_ID_CELL_SCALAR_AT_CORNER, "CellScalarAtCorner", NULL, NULL, 1,
                FIELD_DM_DA, FIELD_LAYOUT_NODE_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL,
                FIELD_CAPABILITY_GHOST_UPDATE, CellScalarAtCorner, lCellScalarAtCorner,
                FIELD_DIM_FROM_SOURCE),
    FIELD_ENTRY(FIELD_ID_CELL_VECTOR_AT_CORNER, "CellVectorAtCorner", NULL, NULL, 3,
                FIELD_DM_FDA, FIELD_LAYOUT_NODE_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL,
                FIELD_CAPABILITY_GHOST_UPDATE, CellVectorAtCorner, lCellVectorAtCorner,
                FIELD_DIM_FROM_SOURCE),
    /* Post-processing staging fields. A derived statistic is config-counted and so
     * has no compile-time offset of its own; staging the result here lets the
     * existing ghost, nodal-average, and logging paths address it by name instead
     * of each growing a second, view-based entry point. */
    FIELD_ENTRY(FIELD_ID_POST_SCALAR, "PostScalar", NULL, NULL, 1,
                FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC, PostScalar, lPostScalar,
                FIELD_DIM_FROM_SOURCE),
    FIELD_ENTRY(FIELD_ID_POST_VECTOR, "PostVector", NULL, NULL, 3,
                FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC, PostVector, lPostVector,
                FIELD_DIM_FROM_SOURCE),
    /* The Q-criterion is computed at cell centres. It is catalogued only so the nodal
     * average can refresh its ghosts by name: a cell value written as point data sits
     * half a cell away from the node the file assigns it. Post-processor only. */
    FIELD_ENTRY(FIELD_ID_QCRIT, "Qcrit", NULL, NULL, 1,
                FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL,
                FIELD_CAPABILITY_GHOST_UPDATE | FIELD_CAPABILITY_PERIODIC_CELL_SYNC, Qcrit, lQcrit,
                FIELD_DIM_INVERSE_TIME_SQUARED),
    /* Particle face planes (MetricComputeFacePlanes()). The dual-cell planes are anchored at cell
     * centres, so they take the cell-centred layout and the standard scatter. */
    FIELD_ENTRY(FIELD_ID_PLANE_NORMAL_I, "PlaneNormalI", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_I_FACE,
                FIELD_SYNC_I_FACE, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                PlaneNormalI, lPlaneNormalI, FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_PLANE_NORMAL_J, "PlaneNormalJ", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_J_FACE,
                FIELD_SYNC_J_FACE, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                PlaneNormalJ, lPlaneNormalJ, FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_PLANE_NORMAL_K, "PlaneNormalK", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_K_FACE,
                FIELD_SYNC_K_FACE, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                PlaneNormalK, lPlaneNormalK, FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_PLANE_CENTROID_I, "PlaneCentroidI", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_I_FACE,
                FIELD_SYNC_I_FACE, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                PlaneCentroidI, lPlaneCentroidI, FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_PLANE_CENTROID_J, "PlaneCentroidJ", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_J_FACE,
                FIELD_SYNC_J_FACE, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                PlaneCentroidJ, lPlaneCentroidJ, FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_PLANE_CENTROID_K, "PlaneCentroidK", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_K_FACE,
                FIELD_SYNC_K_FACE, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                PlaneCentroidK, lPlaneCentroidK, FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_SEARCH_CELL_SIZE, "SearchCellSize", NULL, NULL, 1, FIELD_DM_DA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                SearchCellSize, lSearchCellSize, FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_DUAL_PLANE_NORMAL_I, "DualPlaneNormalI", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                DualPlaneNormalI, lDualPlaneNormalI, FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_DUAL_PLANE_NORMAL_J, "DualPlaneNormalJ", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                DualPlaneNormalJ, lDualPlaneNormalJ, FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_DUAL_PLANE_NORMAL_K, "DualPlaneNormalK", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                DualPlaneNormalK, lDualPlaneNormalK, FIELD_DIM_DIMENSIONLESS),
    FIELD_ENTRY(FIELD_ID_DUAL_PLANE_CENTROID_I, "DualPlaneCentroidI", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                DualPlaneCentroidI, lDualPlaneCentroidI, FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_DUAL_PLANE_CENTROID_J, "DualPlaneCentroidJ", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                DualPlaneCentroidJ, lDualPlaneCentroidJ, FIELD_DIM_LENGTH),
    FIELD_ENTRY(FIELD_ID_DUAL_PLANE_CENTROID_K, "DualPlaneCentroidK", NULL, NULL, 3, FIELD_DM_FDA, FIELD_LAYOUT_CELL_CENTERED,
                FIELD_SYNC_STANDARD, FIELD_AVAILABILITY_FINEST_LEVEL | FIELD_AVAILABILITY_PARTICLES, FIELD_CAPABILITY_GHOST_UPDATE,
                DualPlaneCentroidK, lDualPlaneCentroidK, FIELD_DIM_LENGTH)
};
 
_Static_assert(sizeof(gFieldCatalog) / sizeof(gFieldCatalog[0]) == FIELD_ID_COUNT,
               "Field catalog must contain one entry per FieldId.");
 
/**
 * @brief Returns the immutable catalog descriptor for one typed field identity.
 * @details Validates the enum range and the table's ID/index invariant before
 *          exposing the catalog-owned descriptor.
 * @see FieldGetDescriptor()
 */
PetscErrorCode FieldGetDescriptor(FieldId field_id, const FieldDescriptor **descriptor)
{
    PetscFunctionBeginUser;
    PROFILE_HELPER_BEGIN;
    PetscCheck(descriptor != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "Field descriptor output cannot be NULL.");
    PetscCheck(field_id >= 0 && field_id < FIELD_ID_COUNT, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
               "Invalid FieldId value %d.", (int)field_id);
    PetscCheck(gFieldCatalog[field_id].id == field_id, PETSC_COMM_SELF, PETSC_ERR_PLIB,
               "Field catalog entry %d is not initialized consistently.", (int)field_id);
 
    *descriptor = &gFieldCatalog[field_id];
    PROFILE_HELPER_END;
    PetscFunctionReturn(0);
}
 
/**
 * @brief Resolves a canonical field name or registered alias to a typed identity.
 * @details Name comparison is intentionally confined to ingress; numerical
 *          consumers receive the resolved @ref FieldId.
 * @see FieldIdFromName()
 */
PetscErrorCode FieldIdFromName(const char *field_name, FieldId *field_id)
{
    PetscBool found = PETSC_FALSE;
 
    PetscFunctionBeginUser;
    PROFILE_FUNCTION_BEGIN;
    PetscCall(FieldTryIdFromName(field_name, field_id, &found));
    PetscCheck(found, PETSC_COMM_SELF, PETSC_ERR_ARG_UNKNOWN_TYPE,
               "Field name '%s' is not registered in the Eulerian field catalog.", field_name);
    PROFILE_FUNCTION_END;
    PetscFunctionReturn(0);
}
 
/**
 * @brief Searches canonical names and aliases, reporting a miss instead of failing.
 * @see FieldTryIdFromName()
 */
PetscErrorCode FieldTryIdFromName(const char *field_name, FieldId *field_id, PetscBool *found)
{
    PetscFunctionBeginUser;
    PROFILE_FUNCTION_BEGIN;
    PetscCheck(field_name != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "Field name cannot be NULL.");
    PetscCheck(field_id != NULL && found != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "FieldId and found outputs cannot be NULL.");
 
    *field_id = FIELD_ID_INVALID;
    *found = PETSC_FALSE;
    for (PetscInt index = 0; index < FIELD_ID_COUNT; ++index) {
        const FieldDescriptor *descriptor = &gFieldCatalog[index];
        PetscBool match = PETSC_FALSE;
 
        PetscCall(PetscStrcasecmp(field_name, descriptor->canonical_name, &match));
        if (!match && descriptor->alias_1) PetscCall(PetscStrcasecmp(field_name, descriptor->alias_1, &match));
        if (!match && descriptor->alias_2) PetscCall(PetscStrcasecmp(field_name, descriptor->alias_2, &match));
        if (match) {
            *field_id = descriptor->id;
            *found = PETSC_TRUE;
            break;
        }
    }
    PROFILE_FUNCTION_END;
    PetscFunctionReturn(0);
}
 
/**
 * @brief Multiplies the reference scales raised to the dimension's exponents.
 * @see FieldDimensionReferenceScale()
 */
PetscErrorCode FieldDimensionReferenceScale(const ScalingCtx *scaling, FieldDimension dimension,
                                            PetscReal *scale)
{
    PetscFunctionBeginUser;
    PROFILE_FUNCTION_BEGIN;
    PetscCheck(scaling != NULL && scale != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "Scaling context and scale output cannot be NULL.");
    PetscCheck(dimension.kind == FIELD_DIMENSION_FIXED, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
               "Only a field with a fixed physical dimension has a reference scale.");
    *scale = PetscPowRealInt(scaling->L_ref, dimension.length) *
             PetscPowRealInt(scaling->U_ref, dimension.velocity) *
             PetscPowRealInt(scaling->rho_ref, dimension.density);
    PROFILE_FUNCTION_END;
    PetscFunctionReturn(0);
}
 
/**
 * @brief Formats the nonzero exponents, or names the non-fixed kinds.
 * @see FieldDimensionLabel()
 */
PetscErrorCode FieldDimensionLabel(FieldDimension dimension, char *label, size_t length)
{
    const char *symbols[3] = {"L", "U", "rho"};
    const int   exponents[3] = {dimension.length, dimension.velocity, dimension.density};
    size_t      used = 0;
 
    PetscFunctionBeginUser;
    PROFILE_FUNCTION_BEGIN;
    PetscCheck(label != NULL && length > 0, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "Dimension label buffer cannot be NULL or empty.");
    label[0] = '\0';
    if (dimension.kind == FIELD_DIMENSION_NOT_A_QUANTITY) {
        PetscCall(PetscStrncpy(label, "not a physical quantity", length));
        PROFILE_FUNCTION_END;
        PetscFunctionReturn(0);
    }
    if (dimension.kind == FIELD_DIMENSION_FROM_SOURCE) {
        PetscCall(PetscStrncpy(label, "dimension of its source field", length));
        PROFILE_FUNCTION_END;
        PetscFunctionReturn(0);
    }
    for (int index = 0; index < 3; ++index) {
        if (!exponents[index]) continue;
        if (exponents[index] == 1) {
            PetscCall(PetscSNPrintf(label + used, length - used, "%s%s", used ? " " : "", symbols[index]));
        } else {
            PetscCall(PetscSNPrintf(label + used, length - used, "%s%s^%d", used ? " " : "",
                                    symbols[index], exponents[index]));
        }
        PetscCall(PetscStrlen(label, &used));
    }
    if (!used) PetscCall(PetscStrncpy(label, "dimensionless", length));
    PROFILE_FUNCTION_END;
    PetscFunctionReturn(0);
}
 
/**
 * @brief Returns catalog-owned printable text for a field identity.
 * @details Invalid enum values return a non-null diagnostic sentinel string.
 * @see FieldCanonicalName()
 */
const char *FieldCanonicalName(FieldId field_id)
{
    PROFILE_HELPER_BEGIN;
    const char *name = (field_id >= 0 && field_id < FIELD_ID_COUNT && gFieldCatalog[field_id].id == field_id)
                           ? gFieldCatalog[field_id].canonical_name : "InvalidField";
    PROFILE_HELPER_END;
    return name;
}
 
/**
 * @brief Converts layout metadata to the stable diagnostic label used by field loggers.
 * @see FieldLayoutName()
 */
const char *FieldLayoutName(FieldLayout layout)
{
    PROFILE_HELPER_BEGIN;
    const char *name;
    switch (layout) {
        case FIELD_LAYOUT_NODE_CENTERED:       name = "Node-Centered"; break;
        case FIELD_LAYOUT_CELL_CENTERED:       name = "Cell-Centered"; break;
        case FIELD_LAYOUT_I_FACE:              name = "I-Face"; break;
        case FIELD_LAYOUT_J_FACE:              name = "J-Face"; break;
        case FIELD_LAYOUT_K_FACE:              name = "K-Face"; break;
        case FIELD_LAYOUT_COMPONENT_STAGGERED: name = "Component-Staggered"; break;
        default:                               name = "Invalid-Layout"; break;
    }
    PROFILE_HELPER_END;
    return name;
}
 
/**
 * @brief Binds one descriptor to the PETSc objects already owned by a UserCtx.
 * @details Resolves DM and Vec handles without allocating, referencing, or
 *          destroying PETSc storage.
 * @see FieldGetView()
 */
PetscErrorCode FieldGetView(UserCtx *user, FieldId field_id, FieldView *view)
{
    const FieldDescriptor *descriptor = NULL;
 
    PetscFunctionBeginUser;
    PROFILE_HELPER_BEGIN;
    PetscCheck(user != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "UserCtx cannot be NULL when resolving a field view.");
    PetscCheck(view != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "Field view output cannot be NULL.");
    PetscCall(FieldGetDescriptor(field_id, &descriptor));
 
    view->descriptor = descriptor;
    view->dm = NULL;
    view->global_vec = NULL;
    view->local_vec = NULL;
 
    switch (descriptor->dm_kind) {
        case FIELD_DM_DA:
            view->dm = user->da;
            break;
        case FIELD_DM_FDA:
            view->dm = user->fda;
            break;
        default:
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_PLIB,
                    "Field '%s' has an invalid DM selector.", descriptor->canonical_name);
    }
 
    view->global_vec = *(Vec *)((char *)user + descriptor->global_vec_offset);
    view->local_vec = *(Vec *)((char *)user + descriptor->local_vec_offset);
 
    PetscCheck(view->dm != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
               "DM for field '%s' is unavailable in this UserCtx.", descriptor->canonical_name);
    PetscCheck(view->global_vec != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
               "Global vector for field '%s' is unavailable in this UserCtx.", descriptor->canonical_name);
    PetscCheck(view->local_vec != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
               "Local vector for field '%s' is unavailable in this UserCtx.", descriptor->canonical_name);
 
    PROFILE_HELPER_END;
    PetscFunctionReturn(0);
}
 
#undef FIELD_ENTRY