Authoritative identities and storage metadata for persistent Eulerian fields. More...

#include <stddef.h>
#include "variables.h"

Include dependency graph for field_catalog.h:

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

Data Structures
struct	FieldDescriptor
	Immutable metadata for one field identity. More...

struct	FieldView
	Non-owning runtime objects resolved for one field and UserCtx. More...

Enumerations
enum	FieldId { FIELD_ID_INVALID = -1 , FIELD_ID_COORDINATES = 0 , FIELD_ID_UCAT , FIELD_ID_UCONT , FIELD_ID_UCONT_O , FIELD_ID_UCONT_RM1 , FIELD_ID_P , FIELD_ID_NU_T , FIELD_ID_CS , FIELD_ID_DIFFUSIVITY , FIELD_ID_DIFFUSIVITY_GRADIENT , FIELD_ID_CSI , FIELD_ID_ETA , FIELD_ID_ZET , FIELD_ID_NVERT , FIELD_ID_AJ , FIELD_ID_CENT , FIELD_ID_GRID_SPACE , FIELD_ID_CENTX , FIELD_ID_CENTY , FIELD_ID_CENTZ , FIELD_ID_ICSI , FIELD_ID_IETA , FIELD_ID_IZET , FIELD_ID_JCSI , FIELD_ID_JETA , FIELD_ID_JZET , FIELD_ID_KCSI , FIELD_ID_KETA , FIELD_ID_KZET , FIELD_ID_IAJ , FIELD_ID_JAJ , FIELD_ID_KAJ , FIELD_ID_PHI , FIELD_ID_PSI , FIELD_ID_NVERT_O , FIELD_ID_PARTICLE_COUNT , FIELD_ID_K_OMEGA , FIELD_ID_K_OMEGA_O , FIELD_ID_COUNT }
	Compile-time identity for a catalogued Eulerian field. More...

enum	FieldLayout { FIELD_LAYOUT_NODE_CENTERED = 0 , FIELD_LAYOUT_CELL_CENTERED , FIELD_LAYOUT_I_FACE , FIELD_LAYOUT_J_FACE , FIELD_LAYOUT_K_FACE , FIELD_LAYOUT_COMPONENT_STAGGERED }
	Logical storage topology of a field. More...

enum	FieldDMKind { FIELD_DM_DA = 0 , FIELD_DM_FDA , FIELD_DM_FDA2 , FIELD_DM_COORDINATES }
	UserCtx DM family used to store a field. More...

enum	FieldSyncClass { FIELD_SYNC_STANDARD = 0 , FIELD_SYNC_I_FACE , FIELD_SYNC_J_FACE , FIELD_SYNC_K_FACE , FIELD_SYNC_COMPONENT_STAGGERED }
	Extra repair required after the normal PETSc global-to-local scatter. More...

enum	FieldAvailability { FIELD_AVAILABILITY_ALWAYS = 0u , FIELD_AVAILABILITY_FINEST_LEVEL = 1u << 0 , FIELD_AVAILABILITY_TURBULENCE = 1u << 1 , FIELD_AVAILABILITY_LES = 1u << 2 , FIELD_AVAILABILITY_RANS = 1u << 3 , FIELD_AVAILABILITY_PARTICLES = 1u << 4 }
	Conditions controlling when a field can have runtime storage. More...

enum	FieldCapabilities { FIELD_CAPABILITY_NONE = 0u , FIELD_CAPABILITY_GHOST_UPDATE = 1u << 0 , FIELD_CAPABILITY_PERIODIC_CELL_SYNC = 1u << 1 , FIELD_CAPABILITY_PERIODIC_FACE_SYNC = 1u << 2 , FIELD_CAPABILITY_PERIODIC_STAGGERED_SYNC = 1u << 3 , FIELD_CAPABILITY_PERIODIC_GEOMETRY_SHIFT = 1u << 4 }
	Operations supported by a catalog entry. More...

Functions
PetscErrorCode	FieldGetDescriptor (FieldId field_id, const FieldDescriptor **descriptor)
	Return immutable metadata for a valid field identifier.

PetscErrorCode	FieldIdFromName (const char field_name, FieldId field_id)
	Resolve a user-facing field name once into its typed identity.

const char *	FieldCanonicalName (FieldId field_id)
	Return the canonical printable name for an ID.

const char *	FieldLayoutName (FieldLayout layout)
	Return a stable printable label for a field layout.

PetscErrorCode	FieldGetView (UserCtx user, FieldId field_id, FieldView view)
	Resolve the existing DM and global/local vectors for one field.

Detailed Description

Authoritative identities and storage metadata for persistent Eulerian fields.

Field identifiers describe conceptual fields at compile time. They do not own, allocate, or modify PETSc objects. A FieldView resolves one identifier against an existing UserCtx after the normal setup lifecycle has created its DMs and vectors.

Definition in file field_catalog.h.

Data Structure Documentation

◆ FieldDescriptor

struct FieldDescriptor

Immutable metadata for one field identity.

Definition at line 114 of file field_catalog.h.

Data Fields
FieldId	id
const char *	canonical_name
const char *	alias_1
const char *	alias_2
PetscInt	dof
FieldDMKind	dm_kind
FieldLayout	layout
FieldSyncClass	sync_class
unsigned int	availability
unsigned int	capabilities
size_t	global_vec_offset
size_t	local_vec_offset

◆ FieldView

struct FieldView

Non-owning runtime objects resolved for one field and UserCtx.

Definition at line 130 of file field_catalog.h.

Collaboration diagram for FieldView:

[legend]

Data Fields
const FieldDescriptor *	descriptor
DM	dm
Vec	global_vec
Vec	local_vec

Enumeration Type Documentation

◆ FieldId

enum FieldId

Compile-time identity for a catalogued Eulerian field.

Enumerator
FIELD_ID_INVALID
FIELD_ID_COORDINATES
FIELD_ID_UCAT
FIELD_ID_UCONT
FIELD_ID_UCONT_O
FIELD_ID_UCONT_RM1
FIELD_ID_P
FIELD_ID_NU_T
FIELD_ID_CS
FIELD_ID_DIFFUSIVITY
FIELD_ID_DIFFUSIVITY_GRADIENT
FIELD_ID_CSI
FIELD_ID_ETA
FIELD_ID_ZET
FIELD_ID_NVERT
FIELD_ID_AJ
FIELD_ID_CENT
FIELD_ID_GRID_SPACE
FIELD_ID_CENTX
FIELD_ID_CENTY
FIELD_ID_CENTZ
FIELD_ID_ICSI
FIELD_ID_IETA
FIELD_ID_IZET
FIELD_ID_JCSI
FIELD_ID_JETA
FIELD_ID_JZET
FIELD_ID_KCSI
FIELD_ID_KETA
FIELD_ID_KZET
FIELD_ID_IAJ
FIELD_ID_JAJ
FIELD_ID_KAJ
FIELD_ID_PHI
FIELD_ID_PSI
FIELD_ID_NVERT_O
FIELD_ID_PARTICLE_COUNT
FIELD_ID_K_OMEGA
FIELD_ID_K_OMEGA_O
FIELD_ID_COUNT

Definition at line 23 of file field_catalog.h.

             {
    FIELD_ID_INVALID = -1,
    FIELD_ID_COORDINATES = 0,
    FIELD_ID_UCAT,
    FIELD_ID_UCONT,
    FIELD_ID_UCONT_O,
    FIELD_ID_UCONT_RM1,
    FIELD_ID_P,
    FIELD_ID_NU_T,
    FIELD_ID_CS,
    FIELD_ID_DIFFUSIVITY,
    FIELD_ID_DIFFUSIVITY_GRADIENT,
    FIELD_ID_CSI,
    FIELD_ID_ETA,
    FIELD_ID_ZET,
    FIELD_ID_NVERT,
    FIELD_ID_AJ,
    FIELD_ID_CENT,
    FIELD_ID_GRID_SPACE,
    FIELD_ID_CENTX,
    FIELD_ID_CENTY,
    FIELD_ID_CENTZ,
    FIELD_ID_ICSI,
    FIELD_ID_IETA,
    FIELD_ID_IZET,
    FIELD_ID_JCSI,
    FIELD_ID_JETA,
    FIELD_ID_JZET,
    FIELD_ID_KCSI,
    FIELD_ID_KETA,
    FIELD_ID_KZET,
    FIELD_ID_IAJ,
    FIELD_ID_JAJ,
    FIELD_ID_KAJ,
    FIELD_ID_PHI,
    FIELD_ID_PSI,
    FIELD_ID_NVERT_O,
    FIELD_ID_PARTICLE_COUNT,
    FIELD_ID_K_OMEGA,
    FIELD_ID_K_OMEGA_O,
    FIELD_ID_COUNT
} FieldId;

◆ FieldLayout

enum FieldLayout

Logical storage topology of a field.

Enumerator
FIELD_LAYOUT_NODE_CENTERED
FIELD_LAYOUT_CELL_CENTERED
FIELD_LAYOUT_I_FACE
FIELD_LAYOUT_J_FACE
FIELD_LAYOUT_K_FACE
FIELD_LAYOUT_COMPONENT_STAGGERED

Definition at line 67 of file field_catalog.h.

             {
    FIELD_LAYOUT_NODE_CENTERED = 0,
    FIELD_LAYOUT_CELL_CENTERED,
    FIELD_LAYOUT_I_FACE,
    FIELD_LAYOUT_J_FACE,
    FIELD_LAYOUT_K_FACE,
    FIELD_LAYOUT_COMPONENT_STAGGERED
} FieldLayout;

◆ FieldDMKind

enum FieldDMKind

UserCtx DM family used to store a field.

Enumerator
FIELD_DM_DA
FIELD_DM_FDA
FIELD_DM_FDA2
FIELD_DM_COORDINATES

Definition at line 77 of file field_catalog.h.

             {
    FIELD_DM_DA = 0,
    FIELD_DM_FDA,
    FIELD_DM_FDA2,
    FIELD_DM_COORDINATES
} FieldDMKind;

◆ FieldSyncClass

enum FieldSyncClass

Extra repair required after the normal PETSc global-to-local scatter.

Enumerator
FIELD_SYNC_STANDARD
FIELD_SYNC_I_FACE
FIELD_SYNC_J_FACE
FIELD_SYNC_K_FACE
FIELD_SYNC_COMPONENT_STAGGERED

Definition at line 85 of file field_catalog.h.

             {
    FIELD_SYNC_STANDARD = 0,
    FIELD_SYNC_I_FACE,
    FIELD_SYNC_J_FACE,
    FIELD_SYNC_K_FACE,
    FIELD_SYNC_COMPONENT_STAGGERED
} FieldSyncClass;

◆ FieldAvailability

enum FieldAvailability

Conditions controlling when a field can have runtime storage.

Enumerator
FIELD_AVAILABILITY_ALWAYS
FIELD_AVAILABILITY_FINEST_LEVEL
FIELD_AVAILABILITY_TURBULENCE
FIELD_AVAILABILITY_LES
FIELD_AVAILABILITY_RANS
FIELD_AVAILABILITY_PARTICLES

Definition at line 94 of file field_catalog.h.

             {
    FIELD_AVAILABILITY_ALWAYS       = 0u,
    FIELD_AVAILABILITY_FINEST_LEVEL = 1u << 0,
    FIELD_AVAILABILITY_TURBULENCE   = 1u << 1,
    FIELD_AVAILABILITY_LES          = 1u << 2,
    FIELD_AVAILABILITY_RANS         = 1u << 3,
    FIELD_AVAILABILITY_PARTICLES    = 1u << 4
} FieldAvailability;

◆ FieldCapabilities

enum FieldCapabilities

Operations supported by a catalog entry.

Enumerator
FIELD_CAPABILITY_NONE
FIELD_CAPABILITY_GHOST_UPDATE
FIELD_CAPABILITY_PERIODIC_CELL_SYNC
FIELD_CAPABILITY_PERIODIC_FACE_SYNC
FIELD_CAPABILITY_PERIODIC_STAGGERED_SYNC
FIELD_CAPABILITY_PERIODIC_GEOMETRY_SHIFT

Definition at line 104 of file field_catalog.h.

             {
    FIELD_CAPABILITY_NONE                      = 0u,
    FIELD_CAPABILITY_GHOST_UPDATE              = 1u << 0,
    FIELD_CAPABILITY_PERIODIC_CELL_SYNC        = 1u << 1,
    FIELD_CAPABILITY_PERIODIC_FACE_SYNC        = 1u << 2,
    FIELD_CAPABILITY_PERIODIC_STAGGERED_SYNC   = 1u << 3,
    FIELD_CAPABILITY_PERIODIC_GEOMETRY_SHIFT   = 1u << 4
} FieldCapabilities;

Function Documentation

◆ FieldGetDescriptor()

PetscErrorCode FieldGetDescriptor	(	FieldId	field_id,
		const FieldDescriptor **	descriptor
	)

Return immutable metadata for a valid field identifier.

Parameters

[in]	field_id	Compile-time field identity.
[out]	descriptor	Catalog entry owned by the field-catalog module.

Returns: Zero on success; PETSc error for an invalid ID or null output.

Return immutable metadata for a valid field identifier.

Validates the enum range and the table's ID/index invariant before exposing the catalog-owned descriptor.

See also: FieldGetDescriptor()

Definition at line 149 of file field_catalog.c.

{
    PetscFunctionBeginUser;
    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];
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

◆ FieldIdFromName()

PetscErrorCode FieldIdFromName	(	const char *	field_name,
		FieldId *	field_id
	)

Resolve a user-facing field name once into its typed identity.

Parameters

[in]	field_name	Canonical name or registered alias.
[out]	field_id	Resolved field identity.

Returns: Zero on success; PETSc unknown-type error for an unregistered name.

Resolve a user-facing field name once into its typed identity.

Name comparison is intentionally confined to ingress; numerical consumers receive the resolved FieldId.

See also: FieldIdFromName()

Definition at line 169 of file field_catalog.c.

{
    PetscFunctionBeginUser;
    PetscCheck(field_name != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "Field name cannot be NULL.");
    PetscCheck(field_id != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "FieldId output cannot be NULL.");
 
    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;
            PetscFunctionReturn(0);
        }
    }
 
    *field_id = FIELD_ID_INVALID;
    SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_UNKNOWN_TYPE,
            "Field name '%s' is not registered in the Eulerian field catalog.", field_name);
}

Here is the caller graph for this function:

◆ FieldCanonicalName()

const char * FieldCanonicalName ( FieldId field_id )

Return the canonical printable name for an ID.

Parameters

[in] field_id Field identity.

Returns: Canonical name, or "InvalidField" for an invalid ID.

Return the canonical printable name for an ID.

Invalid enum values return a non-null diagnostic sentinel string.

See also: FieldCanonicalName()

Definition at line 200 of file field_catalog.c.

{
    if (field_id < 0 || field_id >= FIELD_ID_COUNT) return "InvalidField";
    if (gFieldCatalog[field_id].id != field_id) return "InvalidField";
    return gFieldCatalog[field_id].canonical_name;
}

Here is the caller graph for this function:

◆ FieldLayoutName()

const char * FieldLayoutName ( FieldLayout layout )

Return a stable printable label for a field layout.

Parameters

[in] layout Layout enum to describe.

Returns: Catalog-owned label, or Invalid-Layout for an invalid enum.

Return a stable printable label for a field layout.

See also: FieldLayoutName()

Definition at line 211 of file field_catalog.c.

{
    switch (layout) {
        case FIELD_LAYOUT_NODE_CENTERED:       return "Node-Centered";
        case FIELD_LAYOUT_CELL_CENTERED:       return "Cell-Centered";
        case FIELD_LAYOUT_I_FACE:              return "I-Face";
        case FIELD_LAYOUT_J_FACE:              return "J-Face";
        case FIELD_LAYOUT_K_FACE:              return "K-Face";
        case FIELD_LAYOUT_COMPONENT_STAGGERED: return "Component-Staggered";
        default:                               return "Invalid-Layout";
    }
}

Here is the caller graph for this function:

◆ FieldGetView()

PetscErrorCode FieldGetView	(	UserCtx *	user,
		FieldId	field_id,
		FieldView *	view
	)

Resolve the existing DM and global/local vectors for one field.

This function never creates storage. Optional fields whose setup conditions were not enabled retain valid descriptors but return PETSC_ERR_ARG_WRONGSTATE because their runtime vectors are absent.

Parameters

[in]	user	Existing per-grid context.
[in]	field_id	Field identity to resolve.
[out]	view	Non-owning runtime view.

Returns: Zero on success or a PETSc argument/state error.

Resolve the existing DM and global/local vectors for one field.

Resolves DM and Vec handles without allocating, referencing, or destroying PETSc storage.

See also: FieldGetView()

Definition at line 230 of file field_catalog.c.

{
    const FieldDescriptor *descriptor = NULL;
 
    PetscFunctionBeginUser;
    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;
        case FIELD_DM_FDA2:
            view->dm = user->fda2;
            break;
        case FIELD_DM_COORDINATES:
            view->dm = user->fda;
            PetscCheck(user->da != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_WRONGSTATE,
                       "Coordinate DM is unavailable for field '%s'.", descriptor->canonical_name);
            PetscCall(DMGetCoordinates(user->da, &view->global_vec));
            PetscCall(DMGetCoordinatesLocal(user->da, &view->local_vec));
            break;
        default:
            SETERRQ(PETSC_COMM_SELF, PETSC_ERR_PLIB,
                    "Field '%s' has an invalid DM selector.", descriptor->canonical_name);
    }
 
    if (descriptor->dm_kind != FIELD_DM_COORDINATES) {
        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);
 
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ FieldDescriptor

◆ FieldView

Enumeration Type Documentation

◆ FieldId

◆ FieldLayout

◆ FieldDMKind

◆ FieldSyncClass

◆ FieldAvailability

◆ FieldCapabilities

Function Documentation

◆ FieldGetDescriptor()

◆ FieldIdFromName()

◆ FieldCanonicalName()

◆ FieldLayoutName()

◆ FieldGetView()