kernel_ir.h

Go to the documentation of this file.

 
#ifndef OAKFIELD_KERNEL_IR_H
#define OAKFIELD_KERNEL_IR_H
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
 
#include "field.h"
#include "math/special_functions.h"
#include "operator_identity.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef size_t SimIRNodeId;
 
#define SIM_IR_INVALID_NODE ((SimIRNodeId)SIZE_MAX)
/* Sentinel for a missing constant pool entry */
#define SIM_IR_INVALID_CONSTANT_INDEX ((size_t)SIZE_MAX)
 
typedef enum SimIRValueKind {
    SIM_IR_VALUE_SCALAR = 0, 
    SIM_IR_VALUE_VECTOR      
} SimIRValueKind;
 
typedef struct SimIRType {
    SimIRValueKind kind;           
    size_t components;             
    SimScalarDomain scalar_domain; 
} SimIRType;
 
typedef union SimIRDomainPayload {
    SimComplexDouble as_complex; 
    double as_f64;               
    int64_t as_i64;              
    uint64_t as_u64;             
} SimIRDomainPayload;
 
typedef struct SimIRDomainValue {
    SimScalarDomain domain;   
    SimIRDomainPayload value; 
} SimIRDomainValue;
 
typedef struct SimIRShape {
    size_t rank;     
    size_t shape[4]; 
    bool has_shape;  
} SimIRShape;
 
typedef enum SimIRBoundaryPolicy {
    SIM_IR_BOUNDARY_NEUMANN = 0, 
    SIM_IR_BOUNDARY_DIRICHLET,   
    SIM_IR_BOUNDARY_PERIODIC,    
    SIM_IR_BOUNDARY_REFLECTIVE   
} SimIRBoundaryPolicy;
 
typedef enum SimIRDiffMethod {
    SIM_IR_DIFF_METHOD_AUTO = 0, 
    SIM_IR_DIFF_METHOD_CENTRAL, 
    SIM_IR_DIFF_METHOD_FORWARD, 
    SIM_IR_DIFF_METHOD_BACKWARD 
} SimIRDiffMethod;
 
typedef enum SimIRNoiseLaw {
    SIM_IR_NOISE_LAW_ITO = 0,     
    SIM_IR_NOISE_LAW_STRATONOVICH 
} SimIRNoiseLaw;
 
typedef enum SimIRNoiseDistribution {
    SIM_IR_NOISE_DISTRIBUTION_UNIFORM = 0, 
    SIM_IR_NOISE_DISTRIBUTION_GAUSSIAN     
} SimIRNoiseDistribution;
 
typedef enum SimIRParamKind {
    SIM_IR_PARAM_DT = 0,     
    SIM_IR_PARAM_STEP_INDEX, 
    SIM_IR_PARAM_SQRT_DT,    
    SIM_IR_PARAM_TIME        
} SimIRParamKind;
 
typedef struct SimIRDiffSpec {
    SimIRNodeId operand;          
    size_t axis;                  
    double dx;                    
    double scale;                 
    size_t order;                 
    size_t stencil_order;         
    SimIRDiffMethod method;       
    double consistency_constant;  
    SimIRBoundaryPolicy boundary; 
    SimIRType result_type;        
} SimIRDiffSpec;
 
typedef enum SimIRWarpProfile {
    SIM_IR_WARP_PROFILE_DIGAMMA = 0,          
    SIM_IR_WARP_PROFILE_TRIGAMMA = 1,         
    SIM_IR_WARP_PROFILE_DIGAMMA_7_TAIL = 2,   
    SIM_IR_WARP_PROFILE_DIGAMMA_5_TAIL = 3,   
    SIM_IR_WARP_PROFILE_DIGAMMA_ADAPTIVE = 4, 
    SIM_IR_WARP_PROFILE_DIGAMMA_MORTICI = 5   
} SimIRWarpProfile;
 
typedef enum SimIRCallKind {
    SIM_IR_CALL_SIN = 0, 
    SIM_IR_CALL_COS,     
    SIM_IR_CALL_EXP,     
    SIM_IR_CALL_ABS,     
    SIM_IR_CALL_LOG,     
    SIM_IR_CALL_TANH,    
    SIM_IR_CALL_SINH,    
    SIM_IR_CALL_SIGN     
} SimIRCallKind;
 
typedef struct SimIRWarpGuard {
    int mode;         
    double clamp_min; 
    double clamp_max; 
    double tolerance; 
} SimIRWarpGuard;
 
typedef struct SimIRWarpSpec {
    SimIRNodeId operand;      
    double bias;              
    double delta;             
    double lambda;            
    double tolerance;         
    SimIRWarpProfile profile; 
    SimWarpLevel warp_class;  
    SimIRWarpGuard guard;     
    SimIRType result_type;    
} SimIRWarpSpec;
 
typedef struct SimIRNoiseSpec {
    uint32_t seed;                       
    double amplitude;                    
    double variance;                     
    SimIRNoiseLaw law;                   
    SimIRNoiseDistribution distribution; 
    SimIRType value_type;                
} SimIRNoiseSpec;
 
typedef enum SimIRNodeType {
    SIM_IR_NODE_CONSTANT = 0,   
    SIM_IR_NODE_FIELD_REF,      
    SIM_IR_NODE_ADD,            
    SIM_IR_NODE_SUB,            
    SIM_IR_NODE_MUL,            
    SIM_IR_NODE_DIV,            
    SIM_IR_NODE_POW,            
    SIM_IR_NODE_DIFF,           
    SIM_IR_NODE_NOISE,          
    SIM_IR_NODE_WARP,           
    SIM_IR_NODE_PARAM,          
    SIM_IR_NODE_COMPLEX_PACK,   
    SIM_IR_NODE_COMPLEX_ROTATE, 
    SIM_IR_NODE_INDEX,          
    SIM_IR_NODE_CALL,           
    SIM_IR_NODE_FLOOR,          
    SIM_IR_NODE_MOD,            
    SIM_IR_NODE_COORD,          
    SIM_IR_NODE_STATEFUL        
} SimIRNodeType;
 
struct KernelIR;
typedef SimResult (*SimIRStatefulEvalFn)(void *userdata, const struct KernelIR *kernel,
                                         size_t element_index, size_t component, double *out_value);
 
#ifndef SIM_IR_SMALL_CONSTANT_CAPACITY
#define SIM_IR_SMALL_CONSTANT_CAPACITY 4U
#endif
 
typedef struct SimIRNode {
    SimIRNodeType type;        
    SimIRNodeId id;            
    SimIRType value_type;      
    SimIROpcode opcode;        
    SimIRShape inferred_shape; 
    SimWarpLevel warp_class;   
    bool is_local; 
    union {
        struct {
            double scalar;            
            int64_t signed_scalar;    
            uint64_t unsigned_scalar; 
            bool exact_integer;       
            size_t constant_index;    
            double small[SIM_IR_SMALL_CONSTANT_CAPACITY]; 
        } constant;                                       
        size_t field;                                     
        struct {
            SimIRNodeId lhs; 
            SimIRNodeId rhs; 
        } binary;            
        struct {
            SimIRNodeId operand;    
            size_t axis;            
            double dx;              
            double scale;           
            size_t order;           
            size_t stencil_order;   
            SimIRDiffMethod method; 
            double
                consistency_constant; 
            SimIRBoundaryPolicy boundary; 
        } diff;                           
        struct {
            uint32_t seed;                       
            double amplitude;                    
            double variance;                     
            SimIRNoiseLaw law;                   
            SimIRNoiseDistribution distribution; 
        } noise;                                 
        struct {
            SimIRNodeId operand;      
            double bias;              
            double delta;             
            double lambda;            
            double tolerance;         
            SimIRWarpProfile profile; 
            SimIRWarpGuard guard;     
        } warp;                       
        struct {
            SimIRParamKind param; 
        } param;                  
        struct {
            SimIRNodeId operand; 
            SimIRNodeId angle;   
        } complex_rotate;        
        struct {
            SimIRNodeId real; 
            SimIRNodeId imag; 
        } complex_pack;       
        struct {
            SimIRNodeId operand; 
            SimIRCallKind kind;  
        } call;                  
        struct {
            SimIRNodeId operand; 
        } unary;                 
        struct {
            size_t field; 
            size_t axis;  
        } coord;          
        struct {
            SimIRStatefulEvalFn eval; 
            void *userdata;           
            const char *label;        
        } stateful;                   
    } data;                           
} SimIRNode;
 
struct SimWarpSampleSpec;
 
typedef struct SimIRStatefulSpec {
    SimIRStatefulEvalFn eval; 
    void *userdata;           
    const char *label;        
    SimIRType value_type;     
} SimIRStatefulSpec;
 
SimResult sim_ir_warp_sample_response(const struct SimWarpSampleSpec *spec,
                                      SimIRWarpProfile profile, double tolerance,
                                      SimSpecialFallbackFn fallback, void *fallback_userdata,
                                      double *out_response);
 
typedef struct SimIRBuilder {
    SimIRNode *nodes;                     
    size_t count;                         
    size_t capacity;                      
    SimIRBoundaryPolicy default_boundary; 
    /* Constant pool to store per-lane vector constants.
     * Flattened layout of all vector constant values. */
    double *constants_data;         
    size_t *constants_offsets;      
    size_t *constants_components;   
    size_t constants_count;         
    size_t constants_capacity;      
    size_t constants_data_capacity; 
    size_t constants_data_used;     
} SimIRBuilder;
 
SimResult sim_ir_builder_init(SimIRBuilder *builder);
 
void sim_ir_builder_set_default_boundary(SimIRBuilder *builder, SimIRBoundaryPolicy boundary);
 
void sim_ir_builder_reset(SimIRBuilder *builder);
 
void sim_ir_builder_apply_opcode(SimIRBuilder *builder, SimIROpcode opcode, bool preserve_existing);
 
SimResult sim_ir_builder_apply_opcode_reachable(SimIRBuilder *builder, SimIROpcode opcode,
                                                bool preserve_existing, const SimIRNodeId *roots,
                                                size_t root_count);
 
SimResult sim_ir_collect_reachable(const SimIRBuilder *builder, const SimIRNodeId *roots,
                                   size_t root_count, unsigned char *out_reachable,
                                   size_t reachable_count);
 
void sim_ir_diff_spec_init(SimIRDiffSpec *spec, const SimIRBuilder *builder);
 
void sim_ir_builder_destroy(SimIRBuilder *builder);
 
const SimIRNode *sim_ir_builder_get(const SimIRBuilder *builder, SimIRNodeId id);
 
SimIRType sim_ir_builder_node_type(const SimIRBuilder *builder, SimIRNodeId id);
 
SimWarpLevel sim_ir_builder_node_warp_class(const SimIRBuilder *builder, SimIRNodeId id);
 
SimResult sim_ir_builder_set_node_warp_class(SimIRBuilder *builder, SimIRNodeId id,
                                             SimWarpLevel warp_class);
 
SimIRNodeId sim_ir_builder_constant_typed(SimIRBuilder *builder, double value, SimIRType type);
 
SimIRNodeId sim_ir_builder_constant_i64_typed(SimIRBuilder *builder, int64_t value, SimIRType type);
 
SimIRNodeId sim_ir_builder_constant_u64_typed(SimIRBuilder *builder, uint64_t value,
                                              SimIRType type);
 
SimIRNodeId sim_ir_builder_constant_vector_typed(SimIRBuilder *builder, const double *values,
                                                 size_t components, SimIRType type);
 
SimIRNodeId sim_ir_builder_constant_complex(SimIRBuilder *builder, double real, double imag);
 
SimIRNodeId sim_ir_builder_constant_vector(SimIRBuilder *builder, const double *values,
                                           size_t components);
 
bool sim_ir_kernel_has_unsupported_complex_semantics(const struct KernelIR *kernel);
 
SimIRNodeId sim_ir_builder_constant(SimIRBuilder *builder, double value);
 
SimIRNodeId sim_ir_builder_param(SimIRBuilder *builder, SimIRParamKind param);
 
SimIRNodeId sim_ir_builder_index(SimIRBuilder *builder);
 
SimIRNodeId sim_ir_builder_call(SimIRBuilder *builder, SimIRCallKind kind, SimIRNodeId operand);
 
SimIRNodeId sim_ir_builder_floor(SimIRBuilder *builder, SimIRNodeId operand);
 
SimIRNodeId sim_ir_builder_mod(SimIRBuilder *builder, SimIRNodeId lhs, SimIRNodeId rhs);
 
SimIRNodeId sim_ir_builder_coord(SimIRBuilder *builder, size_t field_id, size_t axis);
SimIRNodeId sim_ir_builder_field_ref_typed(SimIRBuilder *builder, size_t field_id, SimIRType type);
 
SimIRNodeId sim_ir_builder_field_ref(SimIRBuilder *builder, size_t field_id);
 
SimIRNodeId sim_ir_builder_binary(SimIRBuilder *builder, SimIRNodeType type, SimIRNodeId lhs,
                                  SimIRNodeId rhs);
 
SimIRNodeId sim_ir_builder_pow(SimIRBuilder *builder, SimIRNodeId lhs, SimIRNodeId rhs);
 
SimIRNodeId sim_ir_builder_diff_spec(SimIRBuilder *builder, const SimIRDiffSpec *spec);
 
SimIRNodeId sim_ir_builder_diff(SimIRBuilder *builder, SimIRNodeId operand, size_t axis, double dx,
                                double scale);
 
SimIRNodeId sim_ir_builder_noise_spec(SimIRBuilder *builder, const SimIRNoiseSpec *spec);
 
SimIRNodeId sim_ir_builder_stateful_spec(SimIRBuilder *builder, const SimIRStatefulSpec *spec);
 
SimIRNodeId sim_ir_builder_stateful(SimIRBuilder *builder, SimIRStatefulEvalFn eval, void *userdata,
                                    const char *label);
 
SimIRNodeId sim_ir_builder_noise(SimIRBuilder *builder, uint32_t seed, double amplitude);
 
SimIRNodeId sim_ir_builder_warp_spec(SimIRBuilder *builder, const SimIRWarpSpec *spec);
 
SimIRNodeId sim_ir_builder_warp(SimIRBuilder *builder, SimIRNodeId operand,
                                SimIRWarpProfile profile, double bias, double delta, double lambda);
 
SimIRNodeId sim_ir_builder_complex_pack(SimIRBuilder *builder, SimIRNodeId real, SimIRNodeId imag);
 
SimIRNodeId sim_ir_builder_complex_rotate(SimIRBuilder *builder, SimIRNodeId operand,
                                          SimIRNodeId angle);
 
SimIRType sim_ir_type_scalar(void);
 
SimIRType sim_ir_type_scalar_domain_typed(SimScalarDomain domain);
 
SimIRType sim_ir_type_vector(size_t components);
 
SimIRType sim_ir_type_complex(void);
 
bool sim_ir_type_is_scalar(SimIRType type);
 
bool sim_ir_type_equal(SimIRType lhs, SimIRType rhs);
 
SimScalarDomain sim_ir_type_scalar_domain(SimIRType type);
 
double sim_ir_warp_profile_eval(SimIRWarpProfile profile, double x, double tolerance);
 
double sim_ir_warp_difference(SimIRWarpProfile profile, double sample, double delta,
                              double tolerance);
 
typedef SimResult (*SimIRFieldEvalFn)(void *userdata, size_t field_id, SimIRType type,
                                      double *out_value);
 
typedef SimResult (*SimIRDiffEvalFn)(void *userdata, const SimIRBuilder *builder,
                                     const SimIRNode *node, SimIRNodeId operand,
                                     double operand_value, double *out_value);
 
typedef SimResult (*SimIRNoiseEvalFn)(void *userdata, const SimIRNode *node, double *out_value);
 
typedef SimResult (*SimIRParamEvalFn)(void *userdata, SimIRParamKind param, double *out_value);
 
typedef SimResult (*SimIRFieldEvalFnComplex)(void *userdata, size_t field_id, SimIRType type,
                                             SimComplexDouble *out_value);
 
typedef SimResult (*SimIRDiffEvalFnComplex)(void *userdata, const SimIRBuilder *builder,
                                            const SimIRNode *node, SimIRNodeId operand,
                                            SimComplexDouble operand_value,
                                            SimComplexDouble *out_value);
 
typedef SimResult (*SimIRNoiseEvalFnComplex)(void *userdata, const SimIRNode *node,
                                             SimComplexDouble *out_value);
 
typedef struct SimIREvaluatorComplex {
    SimIRFieldEvalFnComplex field_value_c; 
    SimIRDiffEvalFnComplex differential_c; 
    SimIRNoiseEvalFnComplex noise_c;       
    SimIRParamEvalFn param_value;          
    void *userdata;                        
} SimIREvaluatorComplex;
 
typedef struct SimIREvaluator {
    SimIRFieldEvalFn
        field_value; 
    SimIRDiffEvalFn
        differential; 
    SimIRNoiseEvalFn noise;       
    SimIRParamEvalFn param_value; 
    void *userdata; 
} SimIREvaluator;
 
typedef SimResult (*SimIRFieldEvalFnDomain)(void *userdata, size_t field_id, SimIRType type,
                                            SimScalarDomain domain, SimIRDomainValue *out_value);
 
typedef SimResult (*SimIRDiffEvalFnDomain)(void *userdata, const SimIRBuilder *builder,
                                           const SimIRNode *node, SimIRNodeId operand,
                                           SimScalarDomain domain, SimIRDomainValue operand_value,
                                           SimIRDomainValue *out_value);
 
typedef SimResult (*SimIRNoiseEvalFnDomain)(void *userdata, const SimIRNode *node,
                                            SimScalarDomain domain, SimIRDomainValue *out_value);
 
typedef SimResult (*SimIRParamEvalFnDomain)(void *userdata, SimIRParamKind param,
                                            SimScalarDomain domain, SimIRDomainValue *out_value);
 
typedef struct SimIREvaluatorDomain {
    SimIRFieldEvalFnDomain field_value; 
    SimIRDiffEvalFnDomain differential; 
    SimIRNoiseEvalFnDomain noise;       
    SimIRParamEvalFnDomain param_value; 
    void *userdata;                     
} SimIREvaluatorDomain;
 
SimResult sim_ir_evaluate_domain(const SimIRBuilder *builder, SimIRNodeId root,
                                 const SimIREvaluatorDomain *evaluator,
                                 SimIRDomainValue *out_value);
 
SimResult sim_ir_evaluate(const SimIRBuilder *builder, SimIRNodeId root,
                          const SimIREvaluator *evaluator, double *out_value);
 
SimResult sim_ir_evaluate_complex(const SimIRBuilder *builder, SimIRNodeId root,
                                  const SimIREvaluatorComplex *evaluator,
                                  SimComplexDouble *out_value);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OAKFIELD_KERNEL_IR_H */