neural_tensor_map.h File Reference

Canonical SimField <-> tensor mapping helpers for neural operators. More...

#include "field.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for neural_tensor_map.h:

Go to the source code of this file.

Classes
struct	SimNeuralTensorAffineHook
	Optional affine hook applied during mapping/unmapping. More...
struct	SimNeuralTensorMapConfig
	Mapping policy from SimField layout to canonical tensor layout. More...
struct	SimNeuralTensorView
	Canonical tensor view generated from a field. More...
struct	SimNeuralTensorMapMetrics
	Explicit copy/transform cost metrics emitted by mapping helpers. More...
struct	SimNeuralTensorMapping
	Opaque-ish mapping handle used by input/output mapping paths. More...

Macros
#define	SIM_NEURAL_TENSOR_MAX_RANK   5U
#define	SIM_NEURAL_TENSOR_CHANNEL_AXIS_AUTO   255U

Typedefs
typedef enum SimNeuralTensorValueType	SimNeuralTensorValueType
	Canonical value type exposed to tensor backends.
typedef enum SimNeuralTensorComplexMode	SimNeuralTensorComplexMode
	Complex-field encoding mode for tensor exposure.
typedef struct SimNeuralTensorAffineHook	SimNeuralTensorAffineHook
	Optional affine hook applied during mapping/unmapping.
typedef struct SimNeuralTensorMapConfig	SimNeuralTensorMapConfig
	Mapping policy from SimField layout to canonical tensor layout.
typedef struct SimNeuralTensorView	SimNeuralTensorView
	Canonical tensor view generated from a field.
typedef struct SimNeuralTensorMapMetrics	SimNeuralTensorMapMetrics
	Explicit copy/transform cost metrics emitted by mapping helpers.
typedef struct SimNeuralTensorMapping	SimNeuralTensorMapping
	Opaque-ish mapping handle used by input/output mapping paths.

Enumerations
enum	SimNeuralTensorValueType { SIM_NEURAL_TENSOR_VALUE_REAL_F64 = 0 , SIM_NEURAL_TENSOR_VALUE_COMPLEX_F64_INTERLEAVED }
	Canonical value type exposed to tensor backends. More...
enum	SimNeuralTensorComplexMode { SIM_NEURAL_TENSOR_COMPLEX_INTERLEAVED = 0 , SIM_NEURAL_TENSOR_COMPLEX_SPLIT_CHANNELS }
	Complex-field encoding mode for tensor exposure. More...

Functions
SimNeuralTensorMapConfig	sim_neural_tensor_map_config_defaults (void)
	Return default mapping config (batch=1, channels_last=true, auto channel axis).
SimResult	sim_neural_tensor_map_input (const SimField *field, const SimNeuralTensorMapConfig *config, SimNeuralTensorMapping *out_mapping)
	Map a field as an input tensor view.
SimResult	sim_neural_tensor_map_output (SimField *field, const SimNeuralTensorMapConfig *config, SimNeuralTensorMapping *out_mapping)
	Map a field as an output tensor view.
SimResult	sim_neural_tensor_unmap_output (SimNeuralTensorMapping *mapping)
	Commit output tensor results back into the mapped field.
void	sim_neural_tensor_mapping_release (SimNeuralTensorMapping *mapping)
	Release resources held by a tensor mapping handle.

Detailed Description

Canonical SimField <-> tensor mapping helpers for neural operators.

Mapping helpers expose fields to neural backends as batch/channel/spatial tensor views. The mapping may be zero-copy or may allocate a scratch tensor when layout, channel placement, complex encoding, or affine conversion cannot be represented directly.

Macro Definition Documentation

SIM_NEURAL_TENSOR_CHANNEL_AXIS_AUTO

#define SIM_NEURAL_TENSOR_CHANNEL_AXIS_AUTO   255U

Automatic channel-axis selection value for SimNeuralTensorMapConfig::channel_axis.

SIM_NEURAL_TENSOR_MAX_RANK

#define SIM_NEURAL_TENSOR_MAX_RANK   5U

Maximum tensor rank supported by the mapping helper (N + C + up to 3 spatial).

Typedef Documentation

SimNeuralTensorAffineHook

typedef struct SimNeuralTensorAffineHook SimNeuralTensorAffineHook

Optional affine hook applied during mapping/unmapping.

When enabled, values are transformed as: y = x * scale + bias.

SimNeuralTensorMapConfig

typedef struct SimNeuralTensorMapConfig SimNeuralTensorMapConfig

Mapping policy from SimField layout to canonical tensor layout.

Current implementation supports batch_size == 1.

SimNeuralTensorMapping

typedef struct SimNeuralTensorMapping SimNeuralTensorMapping

Opaque-ish mapping handle used by input/output mapping paths.

Call sim_neural_tensor_mapping_release after use. For output mappings created by sim_neural_tensor_map_output, call sim_neural_tensor_unmap_output before release when fallback copy was used.

SimNeuralTensorView

typedef struct SimNeuralTensorView SimNeuralTensorView

Canonical tensor view generated from a field.

Strides are expressed in logical tensor values (not bytes).

Enumeration Type Documentation

SimNeuralTensorComplexMode

enum SimNeuralTensorComplexMode

Complex-field encoding mode for tensor exposure.

Enumerator
SIM_NEURAL_TENSOR_COMPLEX_INTERLEAVED	Keep complex values interleaved (complex128).
SIM_NEURAL_TENSOR_COMPLEX_SPLIT_CHANNELS	Expand complex values as doubled real channels.

SimNeuralTensorValueType

enum SimNeuralTensorValueType

Canonical value type exposed to tensor backends.

Enumerator
SIM_NEURAL_TENSOR_VALUE_REAL_F64	Real-valued double tensor.
SIM_NEURAL_TENSOR_VALUE_COMPLEX_F64_INTERLEAVED	Interleaved complex<double>.

Function Documentation

sim_neural_tensor_map_config_defaults()

SimNeuralTensorMapConfig sim_neural_tensor_map_config_defaults

(

void

)

Return default mapping config (batch=1, channels_last=true, auto channel axis).

Returns

Mapping config suitable for common NHWC-style inference inputs.

sim_neural_tensor_map_input()

SimResult sim_neural_tensor_map_input	(	const SimField *	field,
		const SimNeuralTensorMapConfig *	config,
		SimNeuralTensorMapping *	out_mapping
	)

Map a field as an input tensor view.

Uses zero-copy aliasing when policy/layout permits; otherwise allocates an intermediate tensor buffer and copies data into canonical order.

Parameters

	field	Source field to expose; caller retains ownership.
	config	Optional mapping policy, or NULL for defaults.
[out]	out_mapping	Receives the tensor view and release bookkeeping.

Returns

SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, SIM_RESULT_NOT_SUPPORTED, or SIM_RESULT_OUT_OF_MEMORY.

sim_neural_tensor_map_output()

SimResult sim_neural_tensor_map_output	(	SimField *	field,
		const SimNeuralTensorMapConfig *	config,
		SimNeuralTensorMapping *	out_mapping
	)

Map a field as an output tensor view.

For fallback-copy mappings, backends should write outputs into the returned tensor view then call sim_neural_tensor_unmap_output to commit.

Parameters

	field	Destination field to expose; caller retains ownership.
	config	Optional mapping policy, or NULL for defaults.
[out]	out_mapping	Receives the tensor view and release bookkeeping.

Returns

SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, SIM_RESULT_NOT_SUPPORTED, or SIM_RESULT_OUT_OF_MEMORY.

sim_neural_tensor_mapping_release()

void sim_neural_tensor_mapping_release

(

SimNeuralTensorMapping *

mapping

)

Release resources held by a tensor mapping handle.

Parameters

mapping

Mapping handle to release; NULL is ignored.

sim_neural_tensor_unmap_output()

SimResult sim_neural_tensor_unmap_output

(

SimNeuralTensorMapping *

mapping

)

Commit output tensor results back into the mapped field.

Required only for fallback-copy output mappings. Safe to call on zero-copy mappings (no-op).

Parameters

mapping

Active mapping returned by sim_neural_tensor_map_output().

Returns

SIM_RESULT_OK or SIM_RESULT_INVALID_ARGUMENT.