sim_field_stats_runtime.h

Go to the documentation of this file.

 
#ifndef SIM_FIELD_STATS_RUNTIME_H
#define SIM_FIELD_STATS_RUNTIME_H
 
#include "field.h"
#include "sim_buffer.h"
#include "sim_field_stats.h"
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct SimContext;
 
typedef struct SimPhaseCoherenceConfig {
    double abs_threshold;      
    double rel_threshold;      
    bool weighted;             
    double lock_on;            
    double lock_off;           
    double smoothing_constant; 
    bool deramp_enabled;       
} SimPhaseCoherenceConfig;
 
typedef enum SimFieldStatsFeature {
    SIM_FIELD_STATS_FEATURE_PHASE_SUMMARY = 1u << 0, 
    SIM_FIELD_STATS_FEATURE_SPECTRAL = 1u << 1,      
    SIM_FIELD_STATS_FEATURE_PHASE_ADVANCED = 1u << 2 
} SimFieldStatsFeature;
 
#define SIM_FIELD_STATS_FEATURE_MASK_NONE 0u
 
#define SIM_FIELD_STATS_FEATURE_MASK_DEFAULT                                                       \
    (SIM_FIELD_STATS_FEATURE_PHASE_SUMMARY | SIM_FIELD_STATS_FEATURE_SPECTRAL |                    \
     SIM_FIELD_STATS_FEATURE_PHASE_ADVANCED)
 
typedef struct SimFieldStatsComputeConfig {
    uint32_t feature_mask; 
} SimFieldStatsComputeConfig;
 
typedef struct SimFieldStatsComputeTimings {
    uint64_t total_wall_ns;     
    uint64_t reduction_wall_ns; 
    uint64_t spectral_wall_ns;  
    uint64_t phase_wall_ns;     
} SimFieldStatsComputeTimings;
 
typedef enum SimFieldStatsProfileSource {
    SIM_FIELD_STATS_PROFILE_SOURCE_NONE = 0,            
    SIM_FIELD_STATS_PROFILE_SOURCE_VIS_CACHE = 1,       
    SIM_FIELD_STATS_PROFILE_SOURCE_VIS_DRIFT_CACHE = 2, 
    SIM_FIELD_STATS_PROFILE_SOURCE_VIS_COMPUTE = 3,     
    SIM_FIELD_STATS_PROFILE_SOURCE_DRIFT_COMPUTE = 4,   
    SIM_FIELD_STATS_PROFILE_SOURCE_DIRECT_COMPUTE = 5   
} SimFieldStatsProfileSource;
 
typedef struct SimFieldStatsRuntimeProfile {
    SimFieldStatsComputeConfig config; 
    uint64_t request_count;            
    uint64_t cache_hit_count;          
    uint64_t drift_cache_hit_count;    
    uint64_t cache_miss_count;         
    uint64_t compute_count;            
    uint64_t drift_compute_count;      
    uint64_t direct_compute_count;     
    uint64_t phase_lock_count;         
    uint64_t phase_lock_total_ns;      
    uint64_t phase_lock_last_ns;       
    SimFieldStatsComputeTimings total_compute; 
    SimFieldStatsComputeTimings last_compute;  
    size_t last_field_index;                
    size_t last_step_index;                 
    SimFieldStatsProfileSource last_source; 
} SimFieldStatsRuntimeProfile;
 
typedef SimBufferDataType SimFieldDataType;
 
enum {
    SIM_FIELD_DOUBLE = SIM_BUFFER_DOUBLE,                 
    SIM_FIELD_COMPLEX_DOUBLE = SIM_BUFFER_COMPLEX_DOUBLE, 
    SIM_FIELD_UNKNOWN = SIM_BUFFER_UNKNOWN,               
    SIM_FIELD_I32 = SIM_BUFFER_I32,                       
    SIM_FIELD_I64 = SIM_BUFFER_I64,                       
    SIM_FIELD_U32 = SIM_BUFFER_U32,                       
    SIM_FIELD_U64 = SIM_BUFFER_U64,                       
    SIM_FIELD_I8 = SIM_BUFFER_I8,                         
    SIM_FIELD_U8 = SIM_BUFFER_U8                          
};
 
typedef SimBufferView SimFieldView;
 
typedef struct SimFieldStatsAccumulator {
    double mean_re, M2_re;   
    double mean_im, M2_im;   
    double mean_abs, M2_abs; 
    double sum_mag_sq;                     
    double max_abs;                        
    double mean_square_re, mean_square_im; 
    double phase_mean_re, phase_mean_im;   
    size_t phase_sample_count;             
    size_t sample_count;                   
    uint32_t feature_mask;                 
    SimFieldStats *stats;                  
} SimFieldStatsAccumulator;
 
uint32_t sim_field_stats_normalize_feature_mask(uint32_t feature_mask);
 
SimFieldStatsComputeConfig sim_field_stats_default_compute_config(void);
 
bool sim_field_stats_feature_enabled(const SimFieldStatsComputeConfig *config, uint32_t feature);
 
SimFieldView sim_field_view_from_field(SimField *field);
 
void sim_field_stats_accumulator_begin_with_config(SimFieldStatsAccumulator *acc,
                                                   SimFieldStats *stats,
                                                   const SimFieldStatsComputeConfig *config);
 
void sim_field_stats_accumulator_begin(SimFieldStatsAccumulator *acc, SimFieldStats *stats);
 
void sim_field_stats_accumulate_real(SimFieldStatsAccumulator *acc, double value);
 
void sim_field_stats_accumulate_complex(SimFieldStatsAccumulator *acc, double real, double imag);
 
void sim_field_stats_accumulator_finish(SimFieldStatsAccumulator *acc);
 
void sim_field_stats_compute_with_config(const struct SimField *field, SimFieldStats *out,
                                         const SimFieldStatsComputeConfig *config,
                                         SimFieldStatsComputeTimings *timings);
 
bool sim_field_stats_compute_spectral_view(const SimFieldView *view, SimFieldStats *stats,
                                           size_t *out_dominant_k);
 
void sim_field_stats_compute_phase_metrics(const SimFieldView *view, SimFieldStats *stats,
                                           const SimPhaseCoherenceConfig *config,
                                           size_t dominant_k);
 
void sim_field_stats_update_phase_lock(struct SimContext *context, size_t field_index,
                                       SimFieldStats *stats);
 
void sim_field_stats_set_phase_config(const SimPhaseCoherenceConfig *config);
 
const SimPhaseCoherenceConfig *sim_field_stats_get_phase_config(void);
 
void sim_field_stats_set_phase_thresholds(double abs_threshold, double rel_threshold);
 
void sim_field_stats_set_phase_weighted(bool weighted);
 
void sim_field_stats_set_phase_lock_thresholds(double on_threshold, double off_threshold);
 
void sim_field_stats_set_phase_smoothing(double smoothing_seconds);
 
void sim_field_stats_set_phase_deramp(bool enabled);
 
void sim_field_stats_reset_topology_fields(SimFieldStats *stats);
 
void sim_field_stats_profile_reset(SimFieldStatsRuntimeProfile *profile,
                                   const SimFieldStatsComputeConfig *config);
 
void sim_field_stats_profile_record_request(SimFieldStatsRuntimeProfile *profile,
                                            size_t field_index, size_t step_index,
                                            SimFieldStatsProfileSource source);
 
void sim_field_stats_profile_record_compute(SimFieldStatsRuntimeProfile *profile,
                                            size_t field_index, size_t step_index,
                                            SimFieldStatsProfileSource source,
                                            const SimFieldStatsComputeTimings *timings);
 
void sim_field_stats_profile_record_phase_lock(SimFieldStatsRuntimeProfile *profile,
                                               uint64_t phase_lock_ns);
 
#ifdef __cplusplus
}
#endif
#endif