particle_field_catalog.h File Reference

Typed identities and metadata for persistent solver-particle fields. More...

#include <petscdmswarm.h>
#include "field_catalog.h"

Include dependency graph for particle_field_catalog.h:

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

Go to the source code of this file.

Data Structures
struct	ParticleFieldDescriptor
	Immutable metadata for one persistent particle field. More...

Enumerations
enum	ParticleFieldId {   PARTICLE_FIELD_ID_INVALID = -1 , PARTICLE_FIELD_ID_POSITION = 0 , PARTICLE_FIELD_ID_VELOCITY , PARTICLE_FIELD_ID_CELL_ID ,   PARTICLE_FIELD_ID_WEIGHT , PARTICLE_FIELD_ID_DIFFUSIVITY , PARTICLE_FIELD_ID_DIFFUSIVITY_GRADIENT , PARTICLE_FIELD_ID_PSI ,   PARTICLE_FIELD_ID_LOCATION_STATUS , PARTICLE_FIELD_ID_PID , PARTICLE_FIELD_ID_RANK , PARTICLE_FIELD_ID_COUNT }
	Compile-time identity for a persistent solver-particle field. More...
enum	ParticleFieldRegistration { PARTICLE_FIELD_REGISTRATION_PICURV = 0 , PARTICLE_FIELD_REGISTRATION_PETSC }
	Owner of a field's DMSwarm registration. More...
enum	ParticleFieldCapabilities {   PARTICLE_FIELD_CAPABILITY_NONE = 0u , PARTICLE_FIELD_CAPABILITY_DEFAULT_INITIALIZE = 1u << 0 , PARTICLE_FIELD_CAPABILITY_MODEL_UPDATE = 1u << 1 , PARTICLE_FIELD_CAPABILITY_EULERIAN_SCATTER = 1u << 2 ,   PARTICLE_FIELD_CAPABILITY_CHECKPOINT = 1u << 3 , PARTICLE_FIELD_CAPABILITY_USER_INITIALIZE = 1u << 4 }
	Operations supported by a particle-field catalog entry. More...

Functions
PetscErrorCode	ParticleFieldGetDescriptor (ParticleFieldId field_id, const ParticleFieldDescriptor **descriptor)
	Return immutable metadata for a valid particle field ID.
PetscErrorCode	ParticleFieldIdFromName (const char *field_name, ParticleFieldId *field_id)
	Resolve a canonical name or registered alias at a text-ingress boundary.
PetscErrorCode	ParticleFieldTryIdFromName (const char *field_name, ParticleFieldId *field_id, PetscBool *found)
	Look a name up without treating an unknown name as an error.
PetscErrorCode	ParticleFieldIdFromScatterTarget (FieldId target, ParticleFieldId *field_id)
	Find the particle field that scatters to an Eulerian field.
const char *	ParticleFieldName (ParticleFieldId field_id)
	Return the canonical PETSc DMSwarm name for an ID.

Detailed Description

Typed identities and metadata for persistent solver-particle fields.

Particle fields intentionally use a catalog separate from Eulerian fields. They are registered on a DMSwarm, may use integer storage, and do not own a global/local Vec pair in UserCtx. Text is translated only where PETSc or a user/file interface requires a registered DMSwarm name.

Definition in file particle_field_catalog.h.

---

Data Structure Documentation

ParticleFieldDescriptor

struct ParticleFieldDescriptor

Immutable metadata for one persistent particle field.

Definition at line 57 of file particle_field_catalog.h.

Collaboration diagram for ParticleFieldDescriptor:

Data Fields
ParticleFieldId	id
const char *	canonical_name
const char *	alias_1
const char *	alias_2
PetscInt	components
PetscDataType	data_type
ParticleFieldRegistration	registration
unsigned int	capabilities
PetscReal	default_real_value
FieldId	eulerian_scatter_target
FieldDimension	dimension

Enumeration Type Documentation

ParticleFieldId

enum ParticleFieldId

Compile-time identity for a persistent solver-particle field.

Enumerator
PARTICLE_FIELD_ID_INVALID
PARTICLE_FIELD_ID_POSITION
PARTICLE_FIELD_ID_VELOCITY
PARTICLE_FIELD_ID_CELL_ID
PARTICLE_FIELD_ID_WEIGHT
PARTICLE_FIELD_ID_DIFFUSIVITY
PARTICLE_FIELD_ID_DIFFUSIVITY_GRADIENT
PARTICLE_FIELD_ID_PSI
PARTICLE_FIELD_ID_LOCATION_STATUS
PARTICLE_FIELD_ID_PID
PARTICLE_FIELD_ID_RANK
PARTICLE_FIELD_ID_COUNT

Definition at line 23 of file particle_field_catalog.h.

             {
    PARTICLE_FIELD_ID_INVALID = -1,
    PARTICLE_FIELD_ID_POSITION = 0,
    PARTICLE_FIELD_ID_VELOCITY,
    PARTICLE_FIELD_ID_CELL_ID,
    PARTICLE_FIELD_ID_WEIGHT,
    PARTICLE_FIELD_ID_DIFFUSIVITY,
    PARTICLE_FIELD_ID_DIFFUSIVITY_GRADIENT,
    PARTICLE_FIELD_ID_PSI,
    PARTICLE_FIELD_ID_LOCATION_STATUS,
    PARTICLE_FIELD_ID_PID,
    PARTICLE_FIELD_ID_RANK,
    PARTICLE_FIELD_ID_COUNT
} ParticleFieldId;

ParticleFieldRegistration

enum ParticleFieldRegistration

Owner of a field's DMSwarm registration.

Enumerator
PARTICLE_FIELD_REGISTRATION_PICURV
PARTICLE_FIELD_REGISTRATION_PETSC

Definition at line 39 of file particle_field_catalog.h.

             {
    PARTICLE_FIELD_REGISTRATION_PICURV = 0,
    PARTICLE_FIELD_REGISTRATION_PETSC
} ParticleFieldRegistration;

ParticleFieldCapabilities

enum ParticleFieldCapabilities

Operations supported by a particle-field catalog entry.

Enumerator
PARTICLE_FIELD_CAPABILITY_NONE
PARTICLE_FIELD_CAPABILITY_DEFAULT_INITIALIZE
PARTICLE_FIELD_CAPABILITY_MODEL_UPDATE
PARTICLE_FIELD_CAPABILITY_EULERIAN_SCATTER
PARTICLE_FIELD_CAPABILITY_CHECKPOINT
PARTICLE_FIELD_CAPABILITY_USER_INITIALIZE	The particle carries the value, so a configured initial value survives: nothing re-derives it from the Eulerian fields or from particle location.

Definition at line 45 of file particle_field_catalog.h.

             {
    PARTICLE_FIELD_CAPABILITY_NONE               = 0u,
    PARTICLE_FIELD_CAPABILITY_DEFAULT_INITIALIZE = 1u << 0,
    PARTICLE_FIELD_CAPABILITY_MODEL_UPDATE       = 1u << 1,
    PARTICLE_FIELD_CAPABILITY_EULERIAN_SCATTER   = 1u << 2,
    PARTICLE_FIELD_CAPABILITY_CHECKPOINT          = 1u << 3,
    /** The particle carries the value, so a configured initial value survives: nothing
        re-derives it from the Eulerian fields or from particle location. */
    PARTICLE_FIELD_CAPABILITY_USER_INITIALIZE     = 1u << 4
} ParticleFieldCapabilities;

Function Documentation

ParticleFieldGetDescriptor()

PetscErrorCode ParticleFieldGetDescriptor	(	ParticleFieldId	field_id,
		const ParticleFieldDescriptor **	descriptor
	)

Return immutable metadata for a valid particle field ID.

Parameters

[in]	field_id	Typed particle-field identity.
[out]	descriptor	Catalog-owned immutable descriptor.

Returns

Zero on success; a PETSc argument error for invalid input.

Return immutable metadata for a valid particle field ID.

See also

ParticleFieldGetDescriptor()

Definition at line 72 of file particle_field_catalog.c.

{
    PetscFunctionBeginUser;
    PROFILE_FUNCTION_BEGIN;
    PetscCheck(descriptor != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "Particle field descriptor output cannot be NULL.");
    PetscCheck(field_id >= 0 && field_id < PARTICLE_FIELD_ID_COUNT,
               PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE,
               "Invalid ParticleFieldId value %d.", (int)field_id);
    PetscCheck(gParticleFieldCatalog[field_id].id == field_id,
               PETSC_COMM_SELF, PETSC_ERR_PLIB,
               "Particle field catalog entry %d is not initialized consistently.", (int)field_id);
 
    *descriptor = &gParticleFieldCatalog[field_id];
    PROFILE_FUNCTION_END;
    PetscFunctionReturn(0);
}

Here is the caller graph for this function:

ParticleFieldIdFromName()

PetscErrorCode ParticleFieldIdFromName	(	const char *	field_name,
		ParticleFieldId *	field_id
	)

Resolve a canonical name or registered alias at a text-ingress boundary.

Parameters

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

Returns

Zero on success; PETSC_ERR_ARG_UNKNOWN_TYPE for unknown text.

Resolve a canonical name or registered alias at a text-ingress boundary.

See also

ParticleFieldIdFromName()

Definition at line 118 of file particle_field_catalog.c.

{
    PetscBool found = PETSC_FALSE;
 
    PetscFunctionBeginUser;
    PROFILE_FUNCTION_BEGIN;
    PetscCall(ParticleFieldTryIdFromName(field_name, field_id, &found));
    PetscCheck(found, PETSC_COMM_SELF, PETSC_ERR_ARG_UNKNOWN_TYPE,
               "Particle field name '%s' is not registered in the persistent particle field catalog.",
               field_name);
    PROFILE_FUNCTION_END;
    PetscFunctionReturn(0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

ParticleFieldTryIdFromName()

PetscErrorCode ParticleFieldTryIdFromName	(	const char *	field_name,
		ParticleFieldId *	field_id,
		PetscBool *	found
	)

Look a name up without treating an unknown name as an error.

Parameters

[in]	field_name	Canonical particle name or registered alias.
[out]	field_id	Resolved identity, or PARTICLE_FIELD_ID_INVALID when not found.
[out]	found	Whether the name is registered.

Returns

Zero on success; PETSc error only for null arguments.

Look a name up without treating an unknown name as an error.

See also

ParticleFieldTryIdFromName()

Definition at line 136 of file particle_field_catalog.c.

{
    PetscFunctionBeginUser;
    PROFILE_FUNCTION_BEGIN;
    PetscCheck(field_name != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "Particle field name cannot be NULL.");
    PetscCheck(field_id != NULL && found != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "ParticleFieldId and found outputs cannot be NULL.");
 
    *field_id = PARTICLE_FIELD_ID_INVALID;
    *found = PETSC_FALSE;
    for (PetscInt index = 0; index < PARTICLE_FIELD_ID_COUNT; ++index) {
        const ParticleFieldDescriptor *descriptor = &gParticleFieldCatalog[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);
}

Here is the caller graph for this function:

ParticleFieldIdFromScatterTarget()

PetscErrorCode ParticleFieldIdFromScatterTarget	(	FieldId	target,
		ParticleFieldId *	field_id
	)

Find the particle field that scatters to an Eulerian field.

Parameters

[in]	target	Eulerian field identity.
[out]	field_id	The particle field whose scatter target is target.

Returns

Zero on success; PETSC_ERR_ARG_WRONG when no particle field scatters there.

Find the particle field that scatters to an Eulerian field.

See also

ParticleFieldIdFromScatterTarget()

Definition at line 95 of file particle_field_catalog.c.

{
    PetscFunctionBeginUser;
    PROFILE_HELPER_BEGIN;
    PetscCheck(field_id != NULL, PETSC_COMM_SELF, PETSC_ERR_ARG_NULL,
               "ParticleFieldId output cannot be NULL.");
    for (PetscInt index = 0; index < PARTICLE_FIELD_ID_COUNT; ++index) {
        if ((gParticleFieldCatalog[index].capabilities & PARTICLE_FIELD_CAPABILITY_EULERIAN_SCATTER) &&
            gParticleFieldCatalog[index].eulerian_scatter_target == target) {
            *field_id = (ParticleFieldId)index;
            PROFILE_HELPER_END;
            PetscFunctionReturn(0);
        }
    }
    SETERRQ(PETSC_COMM_SELF, PETSC_ERR_ARG_WRONG,
            "No particle field scatters to Eulerian field '%s'.", FieldCanonicalName(target));
    PROFILE_HELPER_END;
}

Here is the call graph for this function:

Here is the caller graph for this function:

ParticleFieldName()

const char * ParticleFieldName

(

ParticleFieldId

field_id

)

Return the canonical PETSc DMSwarm name for an ID.

Parameters

[in]

field_id

Typed particle-field identity.

Returns

Catalog-owned canonical name or InvalidParticleField.

Return the canonical PETSc DMSwarm name for an ID.

See also

ParticleFieldName()

Definition at line 169 of file particle_field_catalog.c.

{
    PROFILE_HELPER_BEGIN;
    if (field_id < 0 || field_id >= PARTICLE_FIELD_ID_COUNT) { PROFILE_HELPER_END; return "InvalidParticleField"; }
    if (gParticleFieldCatalog[field_id].id != field_id) { PROFILE_HELPER_END; return "InvalidParticleField"; }
    PROFILE_HELPER_END;
    return gParticleFieldCatalog[field_id].canonical_name;
}

Here is the caller graph for this function: