Shared standalone buffer and buffer-view types. More...

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

Include dependency graph for sim_buffer.h:

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

Classes
struct	SimBufferView
	Non-owning typed view over contiguous, strided, or indexed scalar storage. More...

struct	SimBuffer
	Owning contiguous typed buffer for research-facing bulk APIs. More...

Typedefs
typedef enum SimBufferDataType	SimBufferDataType
	Scalar storage types supported by standalone buffers and generic views.

typedef struct SimBufferView	SimBufferView
	Non-owning typed view over contiguous, strided, or indexed scalar storage.

typedef struct SimBuffer	SimBuffer
	Owning contiguous typed buffer for research-facing bulk APIs.

Enumerations
enum	SimBufferDataType { SIM_BUFFER_DOUBLE = 0 , SIM_BUFFER_COMPLEX_DOUBLE , SIM_BUFFER_UNKNOWN , SIM_BUFFER_I32 , SIM_BUFFER_I64 , SIM_BUFFER_U32 , SIM_BUFFER_U64 , SIM_BUFFER_I8 , SIM_BUFFER_U8 }
	Scalar storage types supported by standalone buffers and generic views. More...

Functions
size_t	sim_buffer_element_size (SimBufferDataType type)
	Return the storage size of one buffer element.

SimBufferDataType	sim_buffer_data_type_from_element_size (size_t element_size)
	Infer a legacy buffer type from an element byte size.

SimBufferDataType	sim_buffer_data_type_from_scalar_domain (SimScalarDomain domain)
	Map a scalar-domain descriptor to a supported buffer storage type.

SimScalarDomain	sim_buffer_data_type_to_scalar_domain (SimBufferDataType type)
	Map a buffer storage type to its scalar-domain descriptor.

const char *	sim_buffer_data_type_name (SimBufferDataType type)
	Return a stable lowercase name for a buffer storage type.

bool	sim_buffer_view_is_valid (const SimBufferView *view)
	Test whether a buffer view has data, count, and a supported type.

bool	sim_buffer_view_offset_for_indices (const SimBufferView view, const size_t indices, size_t index_count, size_t *out_offset)
	Resolve multidimensional logical indices to a physical element offset.

bool	sim_buffer_view_offset_for_linear_index (const SimBufferView view, size_t logical_index, size_t out_offset)
	Resolve a linear logical index to a physical element offset.

bool	sim_buffer_view_get_complex (const SimBufferView view, size_t logical_index, SimComplexDouble out_value)
	Read a logical value as a SimComplexDouble.

bool	sim_buffer_view_set_complex (SimBufferView *view, size_t logical_index, SimComplexDouble value)
	Write a SimComplexDouble value into a logical view element.

SimBuffer *	sim_buffer_create (size_t rank, const size_t *shape, SimBufferDataType type)
	Allocate a zero-initialized owning buffer with row-major layout.

SimBuffer *	sim_buffer_create_1d (size_t count, SimBufferDataType type)
	Allocate a one-dimensional zero-initialized owning buffer.

SimBuffer *	sim_buffer_clone_view (const SimBufferView *view)
	Copy a buffer view into a compact owning row-major buffer.

SimResult	sim_buffer_reshape (SimBuffer buffer, size_t rank, const size_t shape)
	Replace a buffer's layout without changing its element count.

void	sim_buffer_destroy (SimBuffer *buffer)
	Release an owning buffer and its storage.

void *	sim_buffer_data (SimBuffer *buffer)
	Return a mutable pointer to owned element storage.

const void *	sim_buffer_const_data (const SimBuffer *buffer)
	Return a read-only pointer to owned element storage.

size_t	sim_buffer_count (const SimBuffer *buffer)
	Return the logical element count.

size_t	sim_buffer_bytes (const SimBuffer *buffer)
	Return the storage size in bytes.

SimBufferDataType	sim_buffer_type (const SimBuffer *buffer)
	Return the buffer storage type.

const SimFieldLayout *	sim_buffer_layout (const SimBuffer *buffer)
	Return the immutable layout descriptor for an owning buffer.

SimBufferView	sim_buffer_view (const SimBuffer *buffer)
	Return a non-owning view over an owning buffer.

Detailed Description

Shared standalone buffer and buffer-view types.

Buffers provide small owning allocations for typed scalar data outside the full SimField lifecycle. Views describe caller-owned storage with optional shape/stride metadata and logical-to-physical remapping, which lets patch and neural helpers read non-contiguous data through one indexing contract.

Enumeration Type Documentation

◆ SimBufferDataType

enum SimBufferDataType

Scalar storage types supported by standalone buffers and generic views.

Enumerator
SIM_BUFFER_DOUBLE	Double-precision real scalar storage.
SIM_BUFFER_COMPLEX_DOUBLE	Interleaved SimComplexDouble storage.
SIM_BUFFER_UNKNOWN	Unknown or unsupported storage type.
SIM_BUFFER_I32	Signed 32-bit integer storage.
SIM_BUFFER_I64	Signed 64-bit integer storage.
SIM_BUFFER_U32	Unsigned 32-bit integer storage.
SIM_BUFFER_U64	Unsigned 64-bit integer storage.
SIM_BUFFER_I8	Signed 8-bit integer storage.
SIM_BUFFER_U8	Unsigned 8-bit integer storage.

Function Documentation

◆ sim_buffer_bytes()

size_t sim_buffer_bytes ( const SimBuffer * buffer )

Return the storage size in bytes.

Parameters

buffer Buffer to inspect.

Returns: Byte count, or 0 when buffer is NULL.

◆ sim_buffer_clone_view()

SimBuffer * sim_buffer_clone_view ( const SimBufferView * view )

Copy a buffer view into a compact owning row-major buffer.

The clone preserves the view's shape when valid layout metadata is present; otherwise it creates a one-dimensional buffer of view->count elements.

Parameters

view	Source view to copy.

Returns: New owning buffer, or NULL if the view cannot be indexed or allocated.

◆ sim_buffer_const_data()

const void * sim_buffer_const_data ( const SimBuffer * buffer )

Return a read-only pointer to owned element storage.

Parameters

buffer Buffer to inspect.

Returns: Read-only data pointer, or NULL when buffer is NULL.

◆ sim_buffer_count()

size_t sim_buffer_count ( const SimBuffer * buffer )

Return the logical element count.

Parameters

buffer Buffer to inspect.

Returns: Element count, or 0 when buffer is NULL.

◆ sim_buffer_create()

SimBuffer * sim_buffer_create	(	size_t	rank,
		const size_t *	shape,
		SimBufferDataType	type
	)

Allocate a zero-initialized owning buffer with row-major layout.

Parameters

rank	Number of dimensions; must be nonzero.
shape	Array of `rank` extents.
type	Scalar storage type.

Returns: Newly allocated buffer, or NULL on invalid input or allocation failure.

◆ sim_buffer_create_1d()

SimBuffer * sim_buffer_create_1d	(	size_t	count,
		SimBufferDataType	type
	)

Allocate a one-dimensional zero-initialized owning buffer.

Parameters

count	Number of elements.
type	Scalar storage type.

Returns: Newly allocated buffer, or NULL on invalid input or allocation failure.

◆ sim_buffer_data()

void * sim_buffer_data ( SimBuffer * buffer )

Return a mutable pointer to owned element storage.

Parameters

buffer Buffer to inspect.

Returns: Mutable data pointer, or NULL when buffer is NULL.

◆ sim_buffer_data_type_from_element_size()

SimBufferDataType sim_buffer_data_type_from_element_size ( size_t element_size )

Infer a legacy buffer type from an element byte size.

Only double and SimComplexDouble are recognized by size alone.

Parameters

element_size Size in bytes.

Returns: Matching buffer type, or SIM_BUFFER_UNKNOWN.

◆ sim_buffer_data_type_from_scalar_domain()

SimBufferDataType sim_buffer_data_type_from_scalar_domain ( SimScalarDomain domain )

Map a scalar-domain descriptor to a supported buffer storage type.

Parameters

domain Valid scalar domain descriptor.

Returns: Matching buffer type, or SIM_BUFFER_UNKNOWN for unsupported domains.

◆ sim_buffer_data_type_name()

const char * sim_buffer_data_type_name ( SimBufferDataType type )

Return a stable lowercase name for a buffer storage type.

Parameters

type	Buffer storage type.

Returns: Static string such as "double", "complex_double", or "unknown".

◆ sim_buffer_data_type_to_scalar_domain()

SimScalarDomain sim_buffer_data_type_to_scalar_domain ( SimBufferDataType type )

Map a buffer storage type to its scalar-domain descriptor.

Parameters

type	Buffer storage type.

Returns: Scalar-domain descriptor, or unknown for unsupported types.

◆ sim_buffer_destroy()

void sim_buffer_destroy ( SimBuffer * buffer )

Release an owning buffer and its storage.

Parameters

buffer Buffer returned by sim_buffer_create(); NULL is ignored.

◆ sim_buffer_element_size()

size_t sim_buffer_element_size ( SimBufferDataType type )

Return the storage size of one buffer element.

Parameters

type	Buffer storage type.

Returns: Element size in bytes, or 0 for SIM_BUFFER_UNKNOWN.

◆ sim_buffer_layout()

const SimFieldLayout * sim_buffer_layout ( const SimBuffer * buffer )

Return the immutable layout descriptor for an owning buffer.

Parameters

buffer Buffer to inspect.

Returns: Pointer to internal layout metadata, or NULL when buffer is NULL.

◆ sim_buffer_reshape()

SimResult sim_buffer_reshape	(	SimBuffer *	buffer,
		size_t	rank,
		const size_t *	shape
	)

Replace a buffer's layout without changing its element count.

Parameters

buffer	Owning buffer to reshape.
rank	New rank; must be nonzero.
shape	New shape with product equal to sim_buffer_count(buffer).

Returns: SIM_RESULT_OK, SIM_RESULT_INVALID_ARGUMENT, or SIM_RESULT_OUT_OF_MEMORY.

◆ sim_buffer_type()

SimBufferDataType sim_buffer_type ( const SimBuffer * buffer )

Return the buffer storage type.

Parameters

buffer Buffer to inspect.

Returns: Storage type, or SIM_BUFFER_UNKNOWN when buffer is NULL.

◆ sim_buffer_view()

SimBufferView sim_buffer_view ( const SimBuffer * buffer )

Return a non-owning view over an owning buffer.

The view points at the buffer's internal storage and layout arrays, so it is invalidated when the buffer is reshaped or destroyed.

Parameters

buffer Buffer to view.

Returns: View descriptor, or a zeroed invalid view when buffer is NULL.

◆ sim_buffer_view_get_complex()

bool sim_buffer_view_get_complex	(	const SimBufferView *	view,
		size_t	logical_index,
		SimComplexDouble *	out_value
	)

Read a logical value as a SimComplexDouble.

Real and integer storage types are promoted to a complex value with zero imaginary part. Unsupported types or invalid indices write zero and return false.

Parameters

	view	View to read.
	logical_index	Linear logical index.
[out]	out_value	Receives the promoted complex value.

Returns: true when a value was read.

◆ sim_buffer_view_is_valid()

bool sim_buffer_view_is_valid ( const SimBufferView * view )

Test whether a buffer view has data, count, and a supported type.

Layout metadata is optional; this predicate validates the minimal readable view contract.

Parameters

view	View to inspect.

Returns: true when the view can be indexed.

◆ sim_buffer_view_offset_for_indices()

bool sim_buffer_view_offset_for_indices	(	const SimBufferView *	view,
		const size_t *	indices,
		size_t	index_count,
		size_t *	out_offset
	)

Resolve multidimensional logical indices to a physical element offset.

When the view has no layout, a single index is interpreted as the linear element offset. When logical_to_physical is present, multidimensional indices are first converted to row-major logical order before remapping.

Parameters

	view	View to index.
	indices	Array of logical indices.
	index_count	Number of entries in `indices`.
[out]	out_offset	Receives the physical element offset when non-NULL.

Returns: true when the indices are in range and the offset is representable.

◆ sim_buffer_view_offset_for_linear_index()

bool sim_buffer_view_offset_for_linear_index	(	const SimBufferView *	view,
		size_t	logical_index,
		size_t *	out_offset
	)

Resolve a linear logical index to a physical element offset.

Parameters

	view	View to index.
	logical_index	Linear logical index in [0, view->count).
[out]	out_offset	Receives the physical element offset when non-NULL.

Returns: true when the index is valid for the view.

◆ sim_buffer_view_set_complex()

bool sim_buffer_view_set_complex	(	SimBufferView *	view,
		size_t	logical_index,
		SimComplexDouble	value
	)

Write a SimComplexDouble value into a logical view element.

Complex storage receives both channels. Real double storage accepts only values with an exact zero imaginary component. Integer view writes are not currently supported.

Parameters

view	Mutable view to write.
logical_index	Linear logical index.
value	Value to store.

Returns: true when the value was written.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ SimBufferDataType

Function Documentation

◆ sim_buffer_bytes()

◆ sim_buffer_clone_view()

◆ sim_buffer_const_data()

◆ sim_buffer_count()

◆ sim_buffer_create()

◆ sim_buffer_create_1d()

◆ sim_buffer_data()

◆ sim_buffer_data_type_from_element_size()

◆ sim_buffer_data_type_from_scalar_domain()

◆ sim_buffer_data_type_name()

◆ sim_buffer_data_type_to_scalar_domain()

◆ sim_buffer_destroy()

◆ sim_buffer_element_size()

◆ sim_buffer_layout()

◆ sim_buffer_reshape()

◆ sim_buffer_type()

◆ sim_buffer_view()

◆ sim_buffer_view_get_complex()

◆ sim_buffer_view_is_valid()

◆ sim_buffer_view_offset_for_indices()

◆ sim_buffer_view_offset_for_linear_index()

◆ sim_buffer_view_set_complex()