sim_field_stats_runtime.h File Reference

Runtime field-statistics configuration, accumulation, and profiling helpers. More...

#include "field.h"
#include "sim_buffer.h"
#include "sim_field_stats.h"
#include <stdbool.h>

Include dependency graph for sim_field_stats_runtime.h:

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

Go to the source code of this file.

Classes
struct	SimPhaseCoherenceConfig
	Controls thresholded phase-coherence metrics and phase-lock detection. More...
struct	SimFieldStatsComputeConfig
	Feature selection for one field-statistics computation. More...
struct	SimFieldStatsComputeTimings
	Wall-clock timings captured for one statistics computation. More...
struct	SimFieldStatsRuntimeProfile
	Rolling counters for runtime field-statistics requests and costs. More...
struct	SimFieldStatsAccumulator
	Streaming accumulator for incrementally building SimFieldStats. More...

Macros
#define	SIM_FIELD_STATS_FEATURE_MASK_NONE   0u
#define	SIM_FIELD_STATS_FEATURE_MASK_DEFAULT

Typedefs
typedef struct SimPhaseCoherenceConfig	SimPhaseCoherenceConfig
	Controls thresholded phase-coherence metrics and phase-lock detection.
typedef enum SimFieldStatsFeature	SimFieldStatsFeature
	Optional field-statistics feature families.
typedef struct SimFieldStatsComputeConfig	SimFieldStatsComputeConfig
	Feature selection for one field-statistics computation.
typedef struct SimFieldStatsComputeTimings	SimFieldStatsComputeTimings
	Wall-clock timings captured for one statistics computation.
typedef enum SimFieldStatsProfileSource	SimFieldStatsProfileSource
	Source path recorded for the most recent stats request or computation.
typedef struct SimFieldStatsRuntimeProfile	SimFieldStatsRuntimeProfile
	Rolling counters for runtime field-statistics requests and costs.
typedef SimBufferDataType	SimFieldDataType
	Legacy field-data type alias backed by SimBufferDataType.
typedef SimBufferView	SimFieldView
	Legacy field view alias backed by SimBufferView.
typedef struct SimFieldStatsAccumulator	SimFieldStatsAccumulator
	Streaming accumulator for incrementally building SimFieldStats.

Enumerations
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 }
	Optional field-statistics feature families. More...
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 }
	Source path recorded for the most recent stats request or computation. More...
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 }
	Legacy field-data type constants mapped to buffer storage constants. More...

Functions
uint32_t	sim_field_stats_normalize_feature_mask (uint32_t feature_mask)
	Clamp and expand a stats feature mask to supported dependencies.
SimFieldStatsComputeConfig	sim_field_stats_default_compute_config (void)
	Return the default stats compute configuration.
bool	sim_field_stats_feature_enabled (const SimFieldStatsComputeConfig *config, uint32_t feature)
	Test whether feature is enabled in a compute config.
SimFieldView	sim_field_view_from_field (SimField *field)
	Build a generic field view over a SimField.
void	sim_field_stats_accumulator_begin_with_config (SimFieldStatsAccumulator *acc, SimFieldStats *stats, const SimFieldStatsComputeConfig *config)
	Initialize a streaming accumulator with an explicit compute config.
void	sim_field_stats_accumulator_begin (SimFieldStatsAccumulator *acc, SimFieldStats *stats)
	Initialize a streaming accumulator with the default compute config.
void	sim_field_stats_accumulate_real (SimFieldStatsAccumulator *acc, double value)
	Accumulate one real sample.
void	sim_field_stats_accumulate_complex (SimFieldStatsAccumulator *acc, double real, double imag)
	Accumulate one complex sample.
void	sim_field_stats_accumulator_finish (SimFieldStatsAccumulator *acc)
	Finalize accumulated statistics into the destination snapshot.
void	sim_field_stats_compute_with_config (const struct SimField *field, SimFieldStats *out, const SimFieldStatsComputeConfig *config, SimFieldStatsComputeTimings *timings)
	Compute field statistics with optional feature selection and timings.
bool	sim_field_stats_compute_spectral_view (const SimFieldView *view, SimFieldStats *stats, size_t *out_dominant_k)
	Compute FFT-derived spectral metrics for a generic field view.
void	sim_field_stats_compute_phase_metrics (const SimFieldView *view, SimFieldStats *stats, const SimPhaseCoherenceConfig *config, size_t dominant_k)
	Compute thresholded, weighted, and deramped phase metrics for a view.
void	sim_field_stats_update_phase_lock (struct SimContext *context, size_t field_index, SimFieldStats *stats)
	Update per-field EMA phase lock state and write it into stats.
void	sim_field_stats_set_phase_config (const SimPhaseCoherenceConfig *config)
	Replace the global phase-coherence configuration.
const SimPhaseCoherenceConfig *	sim_field_stats_get_phase_config (void)
	Return the global phase-coherence configuration.
void	sim_field_stats_set_phase_thresholds (double abs_threshold, double rel_threshold)
	Update global absolute and relative phase sample thresholds.
void	sim_field_stats_set_phase_weighted (bool weighted)
	Select whether phase-lock decisions use weighted coherence.
void	sim_field_stats_set_phase_lock_thresholds (double on_threshold, double off_threshold)
	Update global phase-lock hysteresis thresholds.
void	sim_field_stats_set_phase_smoothing (double smoothing_seconds)
	Update the global phase-lock EMA smoothing time constant.
void	sim_field_stats_set_phase_deramp (bool enabled)
	Enable or disable dominant-bin deramping for advanced phase metrics.
void	sim_field_stats_reset_topology_fields (SimFieldStats *stats)
	Clear topology-related fields in a stats snapshot.
void	sim_field_stats_profile_reset (SimFieldStatsRuntimeProfile *profile, const SimFieldStatsComputeConfig *config)
	Reset runtime stats profiling counters.
void	sim_field_stats_profile_record_request (SimFieldStatsRuntimeProfile *profile, size_t field_index, size_t step_index, SimFieldStatsProfileSource source)
	Record a field-statistics request and its cache/source path.
void	sim_field_stats_profile_record_compute (SimFieldStatsRuntimeProfile *profile, size_t field_index, size_t step_index, SimFieldStatsProfileSource source, const SimFieldStatsComputeTimings *timings)
	Record a field-statistics computation and optional timings.
void	sim_field_stats_profile_record_phase_lock (SimFieldStatsRuntimeProfile *profile, uint64_t phase_lock_ns)
	Record phase-lock update duration.

Detailed Description

Runtime field-statistics configuration, accumulation, and profiling helpers.

This header extends the public SimFieldStats snapshot with optional feature masks, phase-coherence controls, generic field views, and runtime profiling counters used by contexts, visual caches, and drift evaluation paths.

Macro Definition Documentation

SIM_FIELD_STATS_FEATURE_MASK_DEFAULT

#define SIM_FIELD_STATS_FEATURE_MASK_DEFAULT

Value:

    (SIM_FIELD_STATS_FEATURE_PHASE_SUMMARY | SIM_FIELD_STATS_FEATURE_SPECTRAL |                    \
     SIM_FIELD_STATS_FEATURE_PHASE_ADVANCED)

Default feature mask used when callers omit an explicit compute config.

SIM_FIELD_STATS_FEATURE_MASK_NONE

#define SIM_FIELD_STATS_FEATURE_MASK_NONE   0u

Empty optional field-statistics feature mask.

Enumeration Type Documentation

anonymous enum

anonymous enum

Legacy field-data type constants mapped to buffer storage constants.

Enumerator
SIM_FIELD_DOUBLE	Double-precision real values.
SIM_FIELD_COMPLEX_DOUBLE	Interleaved complex doubles.
SIM_FIELD_UNKNOWN	Unknown or unsupported storage.
SIM_FIELD_I32	Signed 32-bit integer values.
SIM_FIELD_I64	Signed 64-bit integer values.
SIM_FIELD_U32	Unsigned 32-bit integer values.
SIM_FIELD_U64	Unsigned 64-bit integer values.
SIM_FIELD_I8	Signed 8-bit integer values.
SIM_FIELD_U8	Unsigned 8-bit integer values.

SimFieldStatsFeature

enum SimFieldStatsFeature

Optional field-statistics feature families.

Enumerator
SIM_FIELD_STATS_FEATURE_PHASE_SUMMARY	Basic coherence and circularity.
SIM_FIELD_STATS_FEATURE_SPECTRAL	FFT-derived entropy and bandwidth.
SIM_FIELD_STATS_FEATURE_PHASE_ADVANCED	Weighted, EMA, k0, and regime metrics.

SimFieldStatsProfileSource

enum SimFieldStatsProfileSource

Source path recorded for the most recent stats request or computation.

Enumerator
SIM_FIELD_STATS_PROFILE_SOURCE_NONE	No source has been recorded.
SIM_FIELD_STATS_PROFILE_SOURCE_VIS_CACHE	Visualization stats cache hit.
SIM_FIELD_STATS_PROFILE_SOURCE_VIS_DRIFT_CACHE	Visualization drift-cache hit.
SIM_FIELD_STATS_PROFILE_SOURCE_VIS_COMPUTE	Visualization cache miss computed.
SIM_FIELD_STATS_PROFILE_SOURCE_DRIFT_COMPUTE	Drift-evaluation stats computation.
SIM_FIELD_STATS_PROFILE_SOURCE_DIRECT_COMPUTE	Direct caller-requested computation.

Function Documentation

sim_field_stats_accumulate_complex()

void sim_field_stats_accumulate_complex	(	SimFieldStatsAccumulator *	acc,
		double	real,
		double	imag
	)

Accumulate one complex sample.

Parameters

acc	Accumulator to update.
real	Real component.
imag	Imaginary component.

sim_field_stats_accumulate_real()

void sim_field_stats_accumulate_real	(	SimFieldStatsAccumulator *	acc,
		double	value
	)

Accumulate one real sample.

Parameters

acc	Accumulator to update.
value	Real sample value.

sim_field_stats_accumulator_begin()

void sim_field_stats_accumulator_begin	(	SimFieldStatsAccumulator *	acc,
		SimFieldStats *	stats
	)

Initialize a streaming accumulator with the default compute config.

Parameters

[out]	acc	Accumulator to initialize; NULL is ignored.
[out]	stats	Destination stats snapshot finalized by finish(); may be NULL.

sim_field_stats_accumulator_begin_with_config()

void sim_field_stats_accumulator_begin_with_config	(	SimFieldStatsAccumulator *	acc,
		SimFieldStats *	stats,
		const SimFieldStatsComputeConfig *	config
	)

Initialize a streaming accumulator with an explicit compute config.

Parameters

[out]	acc	Accumulator to initialize; NULL is ignored.
[out]	stats	Destination stats snapshot finalized by finish(); may be NULL.
	config	Optional feature config; NULL selects the default config.

sim_field_stats_accumulator_finish()

void sim_field_stats_accumulator_finish

(

SimFieldStatsAccumulator *

acc

)

Finalize accumulated statistics into the destination snapshot.

Parameters

acc	Accumulator created by sim_field_stats_accumulator_begin().

sim_field_stats_compute_phase_metrics()

void sim_field_stats_compute_phase_metrics	(	const SimFieldView *	view,
		SimFieldStats *	stats,
		const SimPhaseCoherenceConfig *	config,
		size_t	dominant_k
	)

Compute thresholded, weighted, and deramped phase metrics for a view.

Parameters

	view	View to inspect.
[in,out]	stats	Stats snapshot receiving phase fields.
	config	Optional phase config; NULL uses the global phase config.
	dominant_k	Dominant spectral bin used for deramping.

sim_field_stats_compute_spectral_view()

bool sim_field_stats_compute_spectral_view	(	const SimFieldView *	view,
		SimFieldStats *	stats,
		size_t *	out_dominant_k
	)

Compute FFT-derived spectral metrics for a generic field view.

Parameters

	view	View to inspect.
[in,out]	stats	Stats snapshot receiving spectral fields.
[out]	out_dominant_k	Optional dominant spectral bin receiver.

Returns

true when spectral metrics were computed.

sim_field_stats_compute_with_config()

void sim_field_stats_compute_with_config	(	const struct SimField *	field,
		SimFieldStats *	out,
		const SimFieldStatsComputeConfig *	config,
		SimFieldStatsComputeTimings *	timings
	)

Compute field statistics with optional feature selection and timings.

Parameters

	field	Field to inspect.
[out]	out	Destination stats snapshot.
	config	Optional feature config; NULL selects the default config.
[out]	timings	Optional receiver for compute-stage timings.

sim_field_stats_default_compute_config()

SimFieldStatsComputeConfig sim_field_stats_default_compute_config

(

void

)

Return the default stats compute configuration.

Returns

Config with SIM_FIELD_STATS_FEATURE_MASK_DEFAULT enabled.

sim_field_stats_feature_enabled()

bool sim_field_stats_feature_enabled	(	const SimFieldStatsComputeConfig *	config,
		uint32_t	feature
	)

Test whether feature is enabled in a compute config.

Parameters

config	Optional config; NULL selects the default config.
feature	Feature bit to test.

Returns

true when the normalized mask contains feature.

sim_field_stats_get_phase_config()

const SimPhaseCoherenceConfig * sim_field_stats_get_phase_config

(

void

)

Return the global phase-coherence configuration.

Returns

Pointer to internal read-only configuration storage.

sim_field_stats_normalize_feature_mask()

uint32_t sim_field_stats_normalize_feature_mask

(

uint32_t

feature_mask

)

Clamp and expand a stats feature mask to supported dependencies.

Parameters

feature_mask

Caller-supplied feature mask.

Returns

Supported mask; phase-advanced implies phase-summary and spectral.

sim_field_stats_profile_record_compute()

void sim_field_stats_profile_record_compute	(	SimFieldStatsRuntimeProfile *	profile,
		size_t	field_index,
		size_t	step_index,
		SimFieldStatsProfileSource	source,
		const SimFieldStatsComputeTimings *	timings
	)

Record a field-statistics computation and optional timings.

Parameters

profile	Profile to update; NULL is ignored.
field_index	Field index associated with the event.
step_index	Step index associated with the event.
source	Compute source to record.
timings	Optional timings to accumulate.

sim_field_stats_profile_record_phase_lock()

void sim_field_stats_profile_record_phase_lock	(	SimFieldStatsRuntimeProfile *	profile,
		uint64_t	phase_lock_ns
	)

Record phase-lock update duration.

Parameters

profile	Profile to update; NULL is ignored.
phase_lock_ns	Duration in nanoseconds.

sim_field_stats_profile_record_request()

void sim_field_stats_profile_record_request	(	SimFieldStatsRuntimeProfile *	profile,
		size_t	field_index,
		size_t	step_index,
		SimFieldStatsProfileSource	source
	)

Record a field-statistics request and its cache/source path.

Parameters

profile	Profile to update; NULL is ignored.
field_index	Field index associated with the event.
step_index	Step index associated with the event.
source	Request source to record.

sim_field_stats_profile_reset()

void sim_field_stats_profile_reset	(	SimFieldStatsRuntimeProfile *	profile,
		const SimFieldStatsComputeConfig *	config
	)

Reset runtime stats profiling counters.

Parameters

[out]	profile	Profile to reset; NULL is ignored.
	config	Optional compute config to store in the profile.

sim_field_stats_reset_topology_fields()

void sim_field_stats_reset_topology_fields

(

SimFieldStats *

stats

)

Clear topology-related fields in a stats snapshot.

Parameters

stats

Stats snapshot to update; NULL is ignored.

sim_field_stats_set_phase_config()

void sim_field_stats_set_phase_config

(

const SimPhaseCoherenceConfig *

config

)

Replace the global phase-coherence configuration.

Invalid negative thresholds are clamped and lock thresholds are ordered.

Parameters

config

Configuration to copy; NULL is ignored.

sim_field_stats_set_phase_deramp()

void sim_field_stats_set_phase_deramp

(

bool

enabled

)

Enable or disable dominant-bin deramping for advanced phase metrics.

Parameters

enabled

true to compute k0 coherence after deramping.

sim_field_stats_set_phase_lock_thresholds()

void sim_field_stats_set_phase_lock_thresholds	(	double	on_threshold,
		double	off_threshold
	)

Update global phase-lock hysteresis thresholds.

Parameters

on_threshold	Threshold that enters the locked state.
off_threshold	Threshold that exits the locked state.

sim_field_stats_set_phase_smoothing()

void sim_field_stats_set_phase_smoothing

(

double

smoothing_seconds

)

Update the global phase-lock EMA smoothing time constant.

Parameters

smoothing_seconds

Non-negative smoothing constant in seconds.

sim_field_stats_set_phase_thresholds()

void sim_field_stats_set_phase_thresholds	(	double	abs_threshold,
		double	rel_threshold
	)

Update global absolute and relative phase sample thresholds.

Parameters

abs_threshold	Non-negative absolute threshold; negative values leave it unchanged.
rel_threshold	Non-negative relative threshold; negative values leave it unchanged.

sim_field_stats_set_phase_weighted()

void sim_field_stats_set_phase_weighted

(

bool

weighted

)

Select whether phase-lock decisions use weighted coherence.

Parameters

weighted

true to use magnitude-weighted coherence.

sim_field_stats_update_phase_lock()

void sim_field_stats_update_phase_lock	(	struct SimContext *	context,
		size_t	field_index,
		SimFieldStats *	stats
	)

Update per-field EMA phase lock state and write it into stats.

Parameters

	context	Simulation context containing phase-lock runtime arrays.
	field_index	Field index to update.
[in,out]	stats	Stats snapshot receiving EMA and lock state.

sim_field_view_from_field()

SimFieldView sim_field_view_from_field

(

SimField *

field

)

Build a generic field view over a SimField.

Parameters

field

Field to view.

Returns

Buffer view over the field storage, or a zeroed invalid view for NULL.