analytic_warp.h File Reference

Analytic warp operator (smooth nonlinear deformation) acting on a single field. More...

#include <stddef.h>
#include "oakfield/operator_identity.h"
#include "oakfield/operator_split.h"

Include dependency graph for analytic_warp.h:

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

Go to the source code of this file.

Classes
struct	AnalyticWarpOperatorConfig
	Configuration for the analytic warp operator. More...

Typedefs
typedef enum AnalyticWarpProfile	AnalyticWarpProfile
	Analytic warp profile enumeration.
typedef enum AnalyticWarpComplexMode	AnalyticWarpComplexMode
	Complex processing mode for analytic warp.
typedef struct AnalyticWarpOperatorConfig	AnalyticWarpOperatorConfig
	Configuration for the analytic warp operator.

Enumerations
enum	AnalyticWarpProfile {   ANALYTIC_WARP_PROFILE_DIGAMMA = 0 , ANALYTIC_WARP_PROFILE_TRIGAMMA = 1 , ANALYTIC_WARP_PROFILE_POWER = 2 , ANALYTIC_WARP_PROFILE_TANH = 3 ,   ANALYTIC_WARP_PROFILE_HYPEREXP = 4 , ANALYTIC_WARP_PROFILE_QHYPEREXP }
	Analytic warp profile enumeration. More...
enum	AnalyticWarpComplexMode { ANALYTIC_WARP_COMPLEX_MODE_COMPONENT , ANALYTIC_WARP_COMPLEX_MODE_POLAR }
	Complex processing mode for analytic warp. More...

Functions
SimResult	sim_add_analytic_warp_operator (struct SimContext *context, const AnalyticWarpOperatorConfig *config, size_t *out_index)
	Register an analytic warp operator on the provided context.
SimResult	sim_analytic_warp_config (struct SimContext *context, size_t operator_index, AnalyticWarpOperatorConfig *out_config)
	Retrieve the current configuration for an analytic warp operator.
SimResult	sim_analytic_warp_update (struct SimContext *context, size_t operator_index, const AnalyticWarpOperatorConfig *config)
	Update an existing analytic warp operator with a new configuration.
SimWarpLevel	sim_analytic_warp_effective_level (const AnalyticWarpOperatorConfig *config)
	Compute the conservative warp-level classification for a config.

Detailed Description

Analytic warp operator (smooth nonlinear deformation) acting on a single field.

Applies profile-specific analytic transforms (digamma, trigamma, power, tanh) by sampling gradients and accumulating a response term scaled by lambda and delta.

Complex field support: component-wise (Re/Im) or polar mode (magnitude gradient along phase), selectable via config.

Enumeration Type Documentation

AnalyticWarpComplexMode

enum AnalyticWarpComplexMode

Complex processing mode for analytic warp.

Enumerator
ANALYTIC_WARP_COMPLEX_MODE_COMPONENT	Process real and imaginary parts independently.
ANALYTIC_WARP_COMPLEX_MODE_POLAR	Compute gradient at magnitude, apply along current phase.

AnalyticWarpProfile

enum AnalyticWarpProfile

Analytic warp profile enumeration.

Enumerator
ANALYTIC_WARP_PROFILE_DIGAMMA	Digamma warp (psi).
ANALYTIC_WARP_PROFILE_TRIGAMMA	Trigamma warp (psi_1).
ANALYTIC_WARP_PROFILE_POWER	Power-law warp (|x|^p with sign preservation).
ANALYTIC_WARP_PROFILE_TANH	Hyperbolic tangent warp.
ANALYTIC_WARP_PROFILE_HYPEREXP	Hyperexponential warp using phi(lambda, epsilon; K).
ANALYTIC_WARP_PROFILE_QHYPEREXP	q-deformed hyperexponential warp using phi_q(lambda, epsilon; K, q).

Function Documentation

sim_add_analytic_warp_operator()

SimResult sim_add_analytic_warp_operator	(	struct SimContext *	context,
		const AnalyticWarpOperatorConfig *	config,
		size_t *	out_index
	)

Register an analytic warp operator on the provided context.

The implementation copies and normalizes config, validates the target field, and registers either a split operator or an eligible kernel-backed operator.

Parameters

	context	Simulation context that will own the operator.
	config	Optional operator configuration; NULL selects normalized defaults.
[out]	out_index	Optional destination for the registered operator index.

Returns

SIM_RESULT_OK on success, or an error code from argument validation, field validation, allocation, or operator registration.

sim_analytic_warp_config()

SimResult sim_analytic_warp_config	(	struct SimContext *	context,
		size_t	operator_index,
		AnalyticWarpOperatorConfig *	out_config
	)

Retrieve the current configuration for an analytic warp operator.

Parameters

	context	Simulation context containing the operator.
	operator_index	Registry index of the target operator.
[out]	out_config	Receives the normalized configuration.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL pointers, SIM_RESULT_NOT_FOUND for a missing operator, or SIM_RESULT_INVALID_STATE when the operator has no warp state.

sim_analytic_warp_effective_level()

SimWarpLevel sim_analytic_warp_effective_level

(

const AnalyticWarpOperatorConfig *

config

)

Compute the conservative warp-level classification for a config.

This refines the static schema classification using profile-specific parameters to inform scheduling and dt heuristics without mutating IR. NULL or invalid configs fall back to the conservative high-risk level.

Parameters

config

Optional analytic-warp configuration to classify.

Returns

Effective warp-level classification for scheduling metadata.

sim_analytic_warp_update()

SimResult sim_analytic_warp_update	(	struct SimContext *	context,
		size_t	operator_index,
		const AnalyticWarpOperatorConfig *	config
	)

Update an existing analytic warp operator with a new configuration.

Passing NULL for config keeps the current configuration and reapplies normalization. A successful update refreshes symbolic state, operator metadata, and any registered kernel constants, then invalidates the scheduler plan.

Parameters

context	Simulation context containing the operator.
operator_index	Registry index of the operator to update.
config	Optional replacement configuration.

Returns

SIM_RESULT_OK on success, or an error code from lookup, field validation, state validation, or registration metadata refresh.