operator.h

Go to the documentation of this file.

 
#ifndef OAKFIELD_OPERATOR_H
#define OAKFIELD_OPERATOR_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#ifndef OAKFIELD_ENABLE_SYMBOLIC_KERNELS
#define OAKFIELD_ENABLE_SYMBOLIC_KERNELS 1
#endif
 
#ifndef OAKFIELD_ENABLE_ZETA_CORE
#define OAKFIELD_ENABLE_ZETA_CORE 1
#endif
 
#include "field.h"
#include "oakfield/backend.h"
#include "operator_identity.h"
 
struct SimOperatorKernel;
struct SimGraphIR;
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct SimContext;
struct SimOperator;
struct SimOperatorConfig;
struct SimOperatorConfigAdapter;
 
typedef void (*SimOperatorCycleLogFn)(const char* message, void* userdata);
 
#define SIM_OPERATOR_NAME_MAX 63U
#define SIM_OPERATOR_SCHEMA_KEY_MAX 127U
 
typedef enum SimOperatorCategory {
    SIM_OPERATOR_CATEGORY_UNKNOWN = 0, 
    SIM_OPERATOR_CATEGORY_DIFFUSION,   
    SIM_OPERATOR_CATEGORY_ADVECTION,   
    SIM_OPERATOR_CATEGORY_REACTION,    
    SIM_OPERATOR_CATEGORY_POTENTIAL,   
    SIM_OPERATOR_CATEGORY_MEASUREMENT, 
    SIM_OPERATOR_CATEGORY_COUPLING,    
    SIM_OPERATOR_CATEGORY_NOISE,       
    SIM_OPERATOR_CATEGORY_BOUNDARY,    
    SIM_OPERATOR_CATEGORY_THERMOSTAT,  
    SIM_OPERATOR_CATEGORY_UTILITY,     
    SIM_OPERATOR_CATEGORY_NONLINEAR    
} SimOperatorCategory;
 
typedef enum SimContinuityMode {
    SIM_CONTINUITY_NONE    = 0, 
    SIM_CONTINUITY_STRICT  = 1, 
    SIM_CONTINUITY_CLAMPED = 2, 
    SIM_CONTINUITY_LIMITED = 3  
} SimContinuityMode;
 
const char* sim_continuity_mode_name(SimContinuityMode mode);
bool        sim_continuity_mode_from_string(const char* text, SimContinuityMode* out_mode);
 
typedef enum SimContinuityLimiterStrategy {
    SIM_LIMITER_STRATEGY_HARD_CLIP = 1u << 0, 
    SIM_LIMITER_STRATEGY_SOFT_CLIP = 1u << 1, 
    SIM_LIMITER_STRATEGY_SIGMOID_COMPRESSION =
        1u << 2, 
    SIM_LIMITER_STRATEGY_ADAPTIVE_BIAS =
        1u << 3, 
    SIM_LIMITER_STRATEGY_STAT_AWARE =
        1u << 4, 
    SIM_LIMITER_STRATEGY_PER_FIELD_OVERRIDE = 1u << 5 
} SimContinuityLimiterStrategy;
 
const char* sim_continuity_limiter_name(SimContinuityLimiterStrategy strategy);
const char* sim_boundary_policy_name(SimIRBoundaryPolicy policy);
bool        sim_boundary_policy_from_string(const char* text, SimIRBoundaryPolicy* out_policy);
void        sim_operator_config_set_spacing(struct SimOperatorConfig* config,
                                            const double*             spacing,
                                            size_t                    rank);
 
#define SIM_OPERATOR_MAX_SPACING_DIMS 4U
 
typedef enum SimOperatorAlgebraicFlags {
    SIM_OPERATOR_ALG_NONE                = 0u,      
    SIM_OPERATOR_ALG_LINEAR              = 1u << 0, 
    SIM_OPERATOR_ALG_AFFINE              = 1u << 1, 
    SIM_OPERATOR_ALG_SELF_ADJOINT        = 1u << 2, 
    SIM_OPERATOR_ALG_PROJECTION          = 1u << 3, 
    SIM_OPERATOR_ALG_COMMUTES_WITH_NOISE = 1u
                                           << 4, 
    SIM_OPERATOR_ALG_COMMUTES_WITH_BOUNDARY = 1u << 5 
} SimOperatorAlgebraicFlags;
 
typedef struct SimOperatorRepresentation {
    SimFieldDomain    domain;     
    SimFieldValueKind value_kind; 
    bool requires_complex_input;  
    bool preserves_real_subspace; 
    bool
        requires_complex_representation; 
    SimIRBoundaryPolicy boundary;        
    uint8_t             spacing_hint_rank; 
    double
        spacing_hint[SIM_OPERATOR_MAX_SPACING_DIMS]; 
} SimOperatorRepresentation;
 
typedef struct SimOperatorApproximation {
    double spatial_order; 
    double stencil_order; 
    double
        error_constant; 
    double temporal_order; 
} SimOperatorApproximation;
 
typedef enum SimRepresentationMode {
    SIM_REPRESENTATION_MODE_STRICT = 0, 
    SIM_REPRESENTATION_MODE_RELAXED,    
    SIM_REPRESENTATION_MODE_EXPLORATION 
} SimRepresentationMode;
 
typedef enum SimDeterminismFlags {
    SIM_DET_NONE                   = 0U,      
    SIM_DET_PURE_TIME              = 1U << 0, 
    SIM_DET_REWIND_SAFE            = 1U << 1, 
    SIM_DET_NO_STATEFUL_NODES      = 1U << 2, 
    SIM_DET_DETERMINISTIC_RNG_ONLY = 1U << 3  
} SimDeterminismFlags;
 
typedef enum SimNeuralDeterminismPolicy {
    SIM_NEURAL_DETERMINISM_INHERIT = 0, 
    SIM_NEURAL_DETERMINISM_STRICT,      
    SIM_NEURAL_DETERMINISM_BEST_EFFORT, 
    SIM_NEURAL_DETERMINISM_OFF          
} SimNeuralDeterminismPolicy;
 
typedef enum SimNeuralDeviceRequirement {
    SIM_NEURAL_DEVICE_ANY = 0,               
    SIM_NEURAL_DEVICE_CPU_ONLY,              
    SIM_NEURAL_DEVICE_ACCELERATOR_PREFERRED, 
    SIM_NEURAL_DEVICE_ACCELERATOR_REQUIRED   
} SimNeuralDeviceRequirement;
 
typedef enum SimNeuralPrecisionMode {
    SIM_NEURAL_PRECISION_DEFAULT = 0, 
    SIM_NEURAL_PRECISION_FP32,        
    SIM_NEURAL_PRECISION_FP64,        
    SIM_NEURAL_PRECISION_MIXED,       
    SIM_NEURAL_PRECISION_FP16,        
    SIM_NEURAL_PRECISION_BF16         
} SimNeuralPrecisionMode;
 
#define SIM_NEURAL_CHANNEL_AXIS_AUTO 255U
 
typedef struct SimNeuralShapeConstraints {
    uint8_t  min_rank;      
    uint8_t  max_rank;      
    uint8_t  channel_axis;  
    uint32_t min_channels;  
    uint32_t max_channels;  
    bool     channels_last; 
    bool     allow_complex_input; 
} SimNeuralShapeConstraints;
 
typedef struct SimOperatorNeuralContract {
    bool                       enabled; 
    SimNeuralDeterminismPolicy determinism_policy; 
    SimNeuralDeviceRequirement device_requirement; 
    SimNeuralPrecisionMode     precision_mode;     
    SimNeuralShapeConstraints  shape;              
} SimOperatorNeuralContract;
 
typedef enum SimClockMode {
    SIM_CLOCK_FROM_TIME_PARAM = 0, 
    SIM_CLOCK_FROM_STEP_PURE,      
    SIM_CLOCK_ACCUMULATED_STATEFUL 
} SimClockMode;
 
#define SIM_OPERATOR_MAX_INVARIANTS 4U
 
typedef enum SimOperatorInvariantKind {
    SIM_OPERATOR_INVARIANT_NONE = 0, 
    SIM_OPERATOR_INVARIANT_L2_NORM,  
    SIM_OPERATOR_INVARIANT_L1_NORM,  
    SIM_OPERATOR_INVARIANT_ENERGY,   
    SIM_OPERATOR_INVARIANT_MASS,     
    SIM_OPERATOR_INVARIANT_MEAN,     
    SIM_OPERATOR_INVARIANT_VARIANCE  
} SimOperatorInvariantKind;
 
typedef struct SimOperatorInvariant {
    SimOperatorInvariantKind kind;      
    double                   tolerance; 
} SimOperatorInvariant;
 
typedef struct SimOperatorInfo {
    SimOperatorCategory category;      
    SimWarpLevel        warp_level;    
    const char*         schema_key;    
    bool                has_ir_opcode; 
    SimIROpcode         ir_opcode;     
    bool                is_noise;      
    bool        is_differentiable; 
    bool        is_spectral;       
    bool        is_local;          
    bool        is_nonlocal;       
    bool        is_linear;         
    bool        is_warp;           
    bool        preserves_real;    
    double      preferred_dt;      
    const char* abstract_id;       
    const char* (*abstract_id_fn)(
        const struct SimOperator* op);     
    uint32_t            algebraic_flags;   
    SimDeterminismFlags determinism_flags; 
    SimOperatorNeuralContract neural;      
    SimOperatorRepresentation representation; 
    SimOperatorApproximation  approximation;  
    SimOperatorInvariant      invariants[SIM_OPERATOR_MAX_INVARIANTS]; 
    uint8_t                   invariant_count; 
} SimOperatorInfo;
 
typedef struct SimOperatorConfig {
    SimContinuityMode   continuity;     
    double              clamp_min;      
    double              clamp_max;      
    double              continuity_tol; 
    SimIRBoundaryPolicy boundary;       
    uint8_t             spacing_rank;   
    double spacing[SIM_OPERATOR_MAX_SPACING_DIMS]; 
    double norm_budget;                            
    double norm_budget_softness; 
    bool   representation_mode_override_enabled; 
    SimRepresentationMode
        representation_mode_override; 
} SimOperatorConfig;
 
typedef SimResult (*SimOperatorEvalFn)(struct SimContext*  context,
                                       struct SimOperator* self,
                                       void*               userdata);
 
typedef void (*SimOperatorDestroyFn)(void* userdata);
 
typedef const struct SimGraphIR* (*SimOperatorGraphIRViewFn)(const struct SimOperator* self,
                                                             void*                     userdata);
 
typedef struct SimOperator {
    char     name[SIM_OPERATOR_NAME_MAX + 1U];             
    char     schema_key[SIM_OPERATOR_SCHEMA_KEY_MAX + 1U]; 
    uint64_t guid;                              
    SimOperatorEvalFn         evaluate;         
    SimOperatorEvalFn         save_state;       
    SimOperatorEvalFn         restore_state;    
    SimOperatorDestroyFn      destroy;          
    void*                     userdata;         
    size_t*                   dependencies;     
    size_t                    dependency_count; 
    struct SimOperatorKernel* kernel;           
    SimOperatorInfo           info;             
    SimOperatorConfig         config;           
    uint64_t                  read_mask; 
    uint64_t write_mask;          
    size_t*  read_indices;        
    size_t   read_index_count;    
    size_t*  write_indices;       
    size_t   write_index_count;   
    uint64_t required_features;   
    const void* catalog_metadata; 
    const struct SimOperatorConfigAdapter*
                             config_adapter; 
    SimOperatorGraphIRViewFn graph_ir_view;  
} SimOperator;
 
typedef struct SimOperatorKernelBindingDescriptor {
    size_t ir_field_index;      
    size_t context_field_index; 
} SimOperatorKernelBindingDescriptor;
 
typedef struct SimOperatorKernelOutputDescriptor {
    size_t      ir_field_index; 
    SimIRNodeId expression;     
} SimOperatorKernelOutputDescriptor;
 
typedef struct SimOperatorKernelDescriptor {
    const SimIRBuilder* builder; 
    const SimOperatorKernelBindingDescriptor* bindings;      
    size_t                                    binding_count; 
    const SimOperatorKernelOutputDescriptor*  outputs;       
    size_t                                    output_count;  
    const double*                             params; 
    size_t                                    param_count; 
    uint64_t                  required_features; 
    SimKernelComplexSemantics complex_semantics; 
} SimOperatorKernelDescriptor;
 
typedef struct SimOperatorKernel {
    KernelIR                            kernel;        
    SimOperatorKernelBindingDescriptor* binding_map;   
    SimKernelIRBinding*                 bindings;      
    size_t                              binding_count; 
    SimOperatorKernelOutputDescriptor*  output_map;    
    SimKernelIROutput*                  outputs;       
    size_t                              output_count;  
    double*                             params;        
    size_t                              param_count;   
} SimOperatorKernel;
 
typedef struct SimOperatorDescriptor {
    const char*          name;         
    SimOperatorConfig    config;       
    SimOperatorEvalFn    evaluate;     
    SimOperatorDestroyFn destroy;      
    void*                userdata;     
    const size_t*        dependencies; 
    size_t               dependency_count;     
    const SimOperatorKernelDescriptor* kernel; 
    SimOperatorInfo                    info;   
    uint64_t      read_mask;         
    uint64_t      write_mask;        
    const size_t* read_indices;      
    size_t        read_index_count;  
    const size_t* write_indices;     
    size_t        write_index_count; 
    uint64_t      required_features; 
    const void*   catalog_metadata;  
    SimOperatorEvalFn save_state;    
    SimOperatorEvalFn restore_state; 
    const struct SimOperatorConfigAdapter*
                             config_adapter; 
    SimOperatorGraphIRViewFn graph_ir_view;  
} SimOperatorDescriptor;
 
typedef struct SimOperatorRegistry {
    SimOperator* records;  
    size_t       count;    
    size_t       capacity; 
} SimOperatorRegistry;
 
typedef struct SimOperatorPlan {
    size_t* order; 
    size_t  count; 
} SimOperatorPlan;
 
SimResult sim_operator_registry_init(SimOperatorRegistry* registry);
 
void sim_operator_registry_destroy(SimOperatorRegistry* registry);
 
SimResult sim_operator_registry_register(SimOperatorRegistry*         registry,
                                         const SimOperatorDescriptor* descriptor,
                                         size_t*                      out_index);
 
SimOperator* sim_operator_registry_get(SimOperatorRegistry* registry, size_t index);
 
void sim_operator_dependencies(const SimOperator* op, const size_t** out_deps, size_t* out_count);
 
SimResult sim_operator_resolve_plan_with_logger(const SimOperatorRegistry* registry,
                                                SimOperatorPlan*           plan,
                                                SimOperatorCycleLogFn      logger,
                                                void*                      logger_userdata);
 
SimResult sim_operator_resolve_plan(const SimOperatorRegistry* registry, SimOperatorPlan* plan);
 
void sim_operator_plan_destroy(SimOperatorPlan* plan);
 
void* sim_operator_payload(SimOperator* op);
 
const char* sim_operator_name(const SimOperator* op);
 
SimOperatorInfo sim_operator_info(const SimOperator* op);
 
void              sim_operator_config_normalize(SimOperatorConfig* config);
SimOperatorConfig sim_operator_config_defaults(void);
SimOperatorInfo   sim_operator_info_defaults(void);
void              sim_operator_info_normalize(SimOperatorInfo* info);
void              sim_operator_info_set_identity(SimOperatorInfo* info,
                                                 const char*      schema_key,
                                                 SimIROpcode      ir_opcode);
void        sim_operator_info_set_schema_identity(SimOperatorInfo* info, const char* schema_key);
const char* sim_operator_abstract_id(const struct SimOperator* op);
void        sim_operator_set_schema_key(struct SimOperator* op, const char* schema_key);
void        sim_operator_set_catalog_metadata(struct SimOperator* op, const void* metadata);
const void* sim_operator_catalog_metadata(const struct SimOperator* op);
const char* sim_operator_schema_key(const struct SimOperator* op);
const char* sim_operator_schema_key_or(const struct SimOperator* op, const char* fallback);
SimIROpcode sim_operator_ir_opcode(const struct SimOperator* op);
const SimOperatorRepresentation* sim_operator_representation(const struct SimOperator* op);
const char*              sim_operator_representation_domain_name(const struct SimOperator* op);
const char*              sim_operator_representation_value_kind_name(const struct SimOperator* op);
const struct SimGraphIR* sim_operator_graph_ir(const struct SimOperator* op);
bool sim_operator_config_get(const SimOperator* op, SimOperatorConfig* out_config);
void sim_operator_config_set(struct SimOperator* op, const SimOperatorConfig* config);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OAKFIELD_OPERATOR_H */