Context-level neural model registry and execution helpers. More...

#include "operators/neural/neural_infer.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for neural_models.h:

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

Classes
struct	SimNeuralModelConfig
	Registration-time model metadata and backend configuration. More...

struct	SimNeuralModelRuntimeStats
	Accumulated runtime counters for a registered model. More...

struct	SimNeuralModelEntry
	Stored registry entry pairing model config with runtime stats. More...

struct	SimNeuralModelRegistry
	Owning dynamic array of neural model entries. More...

Macros
#define	SIM_NEURAL_MODEL_COMMAND_MAX 255U

#define	SIM_NEURAL_MODEL_NOTE_MAX 127U

#define	SIM_NEURAL_MODEL_ERROR_MAX 191U

#define	SIM_NEURAL_DEVICE_MASK_CPU (1U << 0)

#define	SIM_NEURAL_DEVICE_MASK_CUDA (1U << 1)

#define	SIM_NEURAL_DEVICE_MASK_MPS (1U << 2)

Typedefs
typedef enum SimNeuralBackendKind	SimNeuralBackendKind
	Supported neural inference backend families.

typedef enum SimNeuralExecutionDevice	SimNeuralExecutionDevice
	Execution devices that can be requested for inference.

typedef struct SimNeuralModelConfig	SimNeuralModelConfig
	Registration-time model metadata and backend configuration.

typedef struct SimNeuralModelRuntimeStats	SimNeuralModelRuntimeStats
	Accumulated runtime counters for a registered model.

typedef struct SimNeuralModelEntry	SimNeuralModelEntry
	Stored registry entry pairing model config with runtime stats.

typedef struct SimNeuralModelRegistry	SimNeuralModelRegistry
	Owning dynamic array of neural model entries.

Enumerations
enum	SimNeuralBackendKind { SIM_NEURAL_BACKEND_CALLBACK = 0 , SIM_NEURAL_BACKEND_EXTERNAL_PROCESS , SIM_NEURAL_BACKEND_INPROCESS_ONNX_RUNTIME , SIM_NEURAL_BACKEND_INPROCESS_LIBTORCH }
	Supported neural inference backend families. More...

enum	SimNeuralExecutionDevice { SIM_NEURAL_EXEC_DEVICE_CPU = 0 , SIM_NEURAL_EXEC_DEVICE_CUDA , SIM_NEURAL_EXEC_DEVICE_MPS }
	Execution devices that can be requested for inference. More...

Functions
SimNeuralModelConfig	sim_neural_model_config_defaults (void)
	Return a default callback/CPU/deterministic model config.

void	sim_neural_model_runtime_stats_reset (SimNeuralModelRuntimeStats *stats)
	Reset runtime stats to their initial successful CPU state.

const char *	sim_neural_backend_kind_name (SimNeuralBackendKind kind)
	Return a stable name for a backend kind.

bool	sim_neural_backend_kind_from_string (const char text, SimNeuralBackendKind out_kind)
	Parse a backend kind name.

const char *	sim_neural_execution_device_name (SimNeuralExecutionDevice device)
	Return a stable name for an execution device.

bool	sim_neural_execution_device_from_string (const char text, SimNeuralExecutionDevice out_device)
	Parse an execution device name.

bool	sim_neural_model_supports_device (const SimNeuralModelConfig *config, SimNeuralExecutionDevice device)
	Test whether a model configuration supports a device.

SimResult	sim_neural_model_registry_init (SimNeuralModelRegistry *registry)
	Initialize an empty model registry.

void	sim_neural_model_registry_destroy (SimNeuralModelRegistry *registry)
	Destroy a model registry and release entry storage.

SimResult	sim_neural_model_register (struct SimContext context, const SimNeuralModelConfig config, size_t *out_index)
	Register or replace a neural model in a simulation context.

size_t	sim_neural_model_count (const struct SimContext *context)
	Return the number of registered models.

SimResult	sim_neural_model_config_at (const struct SimContext context, size_t model_index, SimNeuralModelConfig out_config)
	Copy model config by registry index.

SimResult	sim_neural_model_stats_at (const struct SimContext context, size_t model_index, SimNeuralModelRuntimeStats out_stats)
	Copy model runtime stats by registry index.

SimResult	sim_neural_model_config (const struct SimContext context, const char model_id, SimNeuralModelConfig *out_config)
	Copy model config by model id.

SimResult	sim_neural_model_stats (const struct SimContext context, const char model_id, SimNeuralModelRuntimeStats *out_stats)
	Copy model runtime stats by model id.

SimResult	sim_neural_model_infer (struct SimContext context, const char model_id, const SimField input, SimField output, const SimNeuralInferenceRequest *request)
	Run inference for a registered model.

Detailed Description

Context-level neural model registry and execution helpers.

Neural model registrations bind a stable model id to either an in-process callback, an external process command, or a compiled backend placeholder. Runtime helpers choose devices, apply determinism policy, invoke inference, and keep per-model statistics inside SimContext.

Macro Definition Documentation

◆ SIM_NEURAL_MODEL_COMMAND_MAX

#define SIM_NEURAL_MODEL_COMMAND_MAX 255U

Maximum external-process command length (excluding null terminator).

◆ SIM_NEURAL_MODEL_ERROR_MAX

#define SIM_NEURAL_MODEL_ERROR_MAX 191U

Maximum stored runtime error length (excluding null terminator).

◆ SIM_NEURAL_MODEL_NOTE_MAX

#define SIM_NEURAL_MODEL_NOTE_MAX 127U

Maximum free-form model note length (excluding null terminator).

Enumeration Type Documentation

◆ SimNeuralBackendKind

enum SimNeuralBackendKind

Supported neural inference backend families.

Enumerator
SIM_NEURAL_BACKEND_CALLBACK	In-process SimNeuralInferenceFn callback.
SIM_NEURAL_BACKEND_EXTERNAL_PROCESS	External executable using the process schema.
SIM_NEURAL_BACKEND_INPROCESS_ONNX_RUNTIME	ONNX Runtime backend, when compiled in.
SIM_NEURAL_BACKEND_INPROCESS_LIBTORCH	LibTorch backend, when compiled in.

◆ SimNeuralExecutionDevice

enum SimNeuralExecutionDevice

Execution devices that can be requested for inference.

Enumerator
SIM_NEURAL_EXEC_DEVICE_CPU	CPU execution.
SIM_NEURAL_EXEC_DEVICE_CUDA	CUDA-capable GPU execution.
SIM_NEURAL_EXEC_DEVICE_MPS	Apple Metal Performance Shaders execution.

Function Documentation

◆ sim_neural_backend_kind_from_string()

bool sim_neural_backend_kind_from_string	(	const char *	text,
		SimNeuralBackendKind *	out_kind
	)

Parse a backend kind name.

Accepted aliases include "external-process", "process", "onnx", and "torch". Matching is case-insensitive.

Parameters

	text	Text to parse.
[out]	out_kind	Receives the parsed backend kind.

Returns: true when parsing succeeds.

◆ sim_neural_backend_kind_name()

const char * sim_neural_backend_kind_name ( SimNeuralBackendKind kind )

Return a stable name for a backend kind.

Unknown values return "callback" for compatibility with the default backend.

Parameters

kind	Backend enum value.

Returns: Static lowercase backend name.

◆ sim_neural_execution_device_from_string()

bool sim_neural_execution_device_from_string	(	const char *	text,
		SimNeuralExecutionDevice *	out_device
	)

Parse an execution device name.

Accepted aliases include "gpu" for CUDA and "metal" for MPS. Matching is case-insensitive.

Parameters

	text	Text to parse.
[out]	out_device	Receives the parsed device.

Returns: true when parsing succeeds.

◆ sim_neural_execution_device_name()

const char * sim_neural_execution_device_name ( SimNeuralExecutionDevice device )

Return a stable name for an execution device.

Unknown values return "cpu" for compatibility with default routing.

Parameters

device Device enum value.

Returns: Static lowercase device name.

◆ sim_neural_model_config()

SimResult sim_neural_model_config	(	const struct SimContext *	context,
		const char *	model_id,
		SimNeuralModelConfig *	out_config
	)

Copy model config by model id.

Parameters

	context	Context to inspect.
	model_id	Registered model id.
[out]	out_config	Receives the stored config.

Returns: SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, or SIM_RESULT_NOT_FOUND.

◆ sim_neural_model_config_at()

SimResult sim_neural_model_config_at	(	const struct SimContext *	context,
		size_t	model_index,
		SimNeuralModelConfig *	out_config
	)

Copy model config by registry index.

Parameters

	context	Context to inspect.
	model_index	Registry index in [0, sim_neural_model_count()).
[out]	out_config	Receives the stored config.

Returns: SIM_RESULT_OK or SIM_RESULT_INVALID_ARGUMENT.

◆ sim_neural_model_config_defaults()

SimNeuralModelConfig sim_neural_model_config_defaults ( void )

Return a default callback/CPU/deterministic model config.

Returns: Zero-initialized config with callback backend, CPU support, default precision, and deterministic=true.

◆ sim_neural_model_count()

size_t sim_neural_model_count ( const struct SimContext * context )

Return the number of registered models.

Parameters

context Context to inspect.

Returns: Model count, or 0 when context is NULL.

◆ sim_neural_model_infer()

SimResult sim_neural_model_infer	(	struct SimContext *	context,
		const char *	model_id,
		const SimField *	input,
		SimField *	output,
		const SimNeuralInferenceRequest *	request
	)

Run inference for a registered model.

The effective request inherits the stored model id, default precision, and routeable device. Unsupported devices or strict determinism requests against non-deterministic models fail before backend invocation but still update model stats.

Parameters

context	Context containing the model registry and runtime clock.
model_id	Registered model id.
input	Input field passed to the backend; caller-owned.
output	Output field passed to the backend; caller-owned and mutable.
request	Optional inference request overrides.

Returns: Backend result, SIM_RESULT_INVALID_ARGUMENT, SIM_RESULT_NOT_FOUND, or SIM_RESULT_NOT_SUPPORTED for unavailable/unsupported routes.

◆ sim_neural_model_register()

SimResult sim_neural_model_register	(	struct SimContext *	context,
		const SimNeuralModelConfig *	config,
		size_t *	out_index
	)

Register or replace a neural model in a simulation context.

model_id must be non-empty. Callback configs require callback_fn; external process configs require external_command. Re-registering an existing model id replaces its config and resets its stats.

Parameters

	context	Target simulation context.
	config	Model configuration to store.
[out]	out_index	Optional receiver for the registry index.

Returns: SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, or SIM_RESULT_OUT_OF_MEMORY.

◆ sim_neural_model_registry_destroy()

void sim_neural_model_registry_destroy ( SimNeuralModelRegistry * registry )

Destroy a model registry and release entry storage.

Parameters

registry Registry to destroy; NULL is ignored.

◆ sim_neural_model_registry_init()

SimResult sim_neural_model_registry_init ( SimNeuralModelRegistry * registry )

Initialize an empty model registry.

Parameters

registry Registry storage to initialize.

Returns: SIM_RESULT_OK or SIM_RESULT_INVALID_ARGUMENT.

◆ sim_neural_model_runtime_stats_reset()

void sim_neural_model_runtime_stats_reset ( SimNeuralModelRuntimeStats * stats )

Reset runtime stats to their initial successful CPU state.

Parameters

stats Stats object to reset; NULL is ignored.

◆ sim_neural_model_stats()

SimResult sim_neural_model_stats	(	const struct SimContext *	context,
		const char *	model_id,
		SimNeuralModelRuntimeStats *	out_stats
	)

Copy model runtime stats by model id.

Parameters

	context	Context to inspect.
	model_id	Registered model id.
[out]	out_stats	Receives the stored stats.

Returns: SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, or SIM_RESULT_NOT_FOUND.

◆ sim_neural_model_stats_at()

SimResult sim_neural_model_stats_at	(	const struct SimContext *	context,
		size_t	model_index,
		SimNeuralModelRuntimeStats *	out_stats
	)

Copy model runtime stats by registry index.

Parameters

	context	Context to inspect.
	model_index	Registry index in [0, sim_neural_model_count()).
[out]	out_stats	Receives the stored stats.

Returns: SIM_RESULT_OK or SIM_RESULT_INVALID_ARGUMENT.

◆ sim_neural_model_supports_device()

bool sim_neural_model_supports_device	(	const SimNeuralModelConfig *	config,
		SimNeuralExecutionDevice	device
	)

Test whether a model configuration supports a device.

A zero supported_device_mask is treated as CPU-only.

Parameters

config	Model configuration to inspect.
device	Requested device.

Returns: true when the device bit is supported.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SIM_NEURAL_MODEL_COMMAND_MAX

◆ SIM_NEURAL_MODEL_ERROR_MAX

◆ SIM_NEURAL_MODEL_NOTE_MAX

Enumeration Type Documentation

◆ SimNeuralBackendKind

◆ SimNeuralExecutionDevice

Function Documentation

◆ sim_neural_backend_kind_from_string()

◆ sim_neural_backend_kind_name()

◆ sim_neural_execution_device_from_string()

◆ sim_neural_execution_device_name()

◆ sim_neural_model_config()

◆ sim_neural_model_config_at()

◆ sim_neural_model_config_defaults()

◆ sim_neural_model_count()

◆ sim_neural_model_infer()

◆ sim_neural_model_register()

◆ sim_neural_model_registry_destroy()

◆ sim_neural_model_registry_init()

◆ sim_neural_model_runtime_stats_reset()

◆ sim_neural_model_stats()

◆ sim_neural_model_stats_at()

◆ sim_neural_model_supports_device()