Oakfield API Documentation 1.0.0
Numerical core APIs
Loading...
Searching...
No Matches
field.h File Reference

Multidimensional contiguous field abstraction with configurable layout. More...

#include <complex.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
Include dependency graph for field.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  SimFieldRepresentation
 Authoritative representation description for a field. More...
 
struct  SimScalarDomain
 Unified scalar-domain descriptor. More...
 
struct  SimFieldAllocator
 Custom allocator description for field memory. More...
 
struct  SimFieldLayout
 Layout description for a field. More...
 
struct  SimField
 Owning multidimensional field. More...
 
struct  SimComplexDouble
 Explicit in-memory representation for a complex double scalar (re, im) More...
 

Macros

#define OAKFIELD_SIM_RESULT_DEFINED
 
#define SIM_HAVE_SIMCOMPLEXDOUBLE   1
 

Typedefs

typedef enum SimResult SimResult
 Return codes shared by libsimcore modules.
 
typedef enum SimFieldStorage SimFieldStorage
 Supported field storage ordering schemes.
 
typedef enum SimFieldDomain SimFieldDomain
 Domain for field representation (physical vs spectral).
 
typedef enum SimFieldValueKind SimFieldValueKind
 Value kind for field scalars.
 
typedef struct SimFieldRepresentation SimFieldRepresentation
 Authoritative representation description for a field.
 
typedef enum SimScalarDomainKind SimScalarDomainKind
 Scalar algebra domain used by IR typing and legality rules.
 
typedef enum SimScalarCapability SimScalarCapability
 Bitmask describing operations supported by a scalar domain.
 
typedef struct SimScalarDomain SimScalarDomain
 Unified scalar-domain descriptor.
 
typedef void *(* SimFieldAllocFn) (void *userdata, size_t size)
 Allocation callbacks used by fields.
 
typedef void(* SimFieldFreeFn) (void *userdata, void *ptr)
 Deallocation callback used by fields.
 
typedef struct SimFieldAllocator SimFieldAllocator
 Custom allocator description for field memory.
 
typedef struct SimFieldLayout SimFieldLayout
 Layout description for a field.
 
typedef struct SimField SimField
 Owning multidimensional field.
 
typedef struct SimComplexDouble SimComplexDouble
 Explicit in-memory representation for a complex double scalar (re, im)
 

Enumerations

enum  SimResult {
  SIM_RESULT_OK = 0 , SIM_RESULT_INVALID_ARGUMENT , SIM_RESULT_INVALID_STATE , SIM_RESULT_OUT_OF_MEMORY ,
  SIM_RESULT_NOT_FOUND , SIM_RESULT_NOT_SUPPORTED , SIM_RESULT_DEPENDENCY_ERROR , SIM_RESULT_TYPE_MISMATCH
}
 Return codes shared by libsimcore modules. More...
 
enum  SimFieldStorage { SIM_FIELD_STORAGE_ROW_MAJOR = 0 }
 Supported field storage ordering schemes. More...
 
enum  SimFieldDomain { SIM_FIELD_DOMAIN_UNKNOWN = 0 , SIM_FIELD_DOMAIN_PHYSICAL , SIM_FIELD_DOMAIN_SPECTRAL , SIM_FIELD_DOMAIN_HYBRID }
 Domain for field representation (physical vs spectral). More...
 
enum  SimFieldValueKind {
  SIM_FIELD_VALUE_REAL_SCALAR = 0 , SIM_FIELD_VALUE_COMPLEX_SCALAR , SIM_FIELD_VALUE_COMPLEX_REAL_CONSTRAINT , SIM_FIELD_VALUE_COMPLEX_IMAG_ZERO_CONSTRAINT ,
  SIM_FIELD_VALUE_UNKNOWN
}
 Value kind for field scalars. More...
 
enum  SimScalarDomainKind {
  SIM_SCALAR_DOMAIN_UNKNOWN = 0 , SIM_SCALAR_DOMAIN_REAL , SIM_SCALAR_DOMAIN_COMPLEX , SIM_SCALAR_DOMAIN_INTEGER ,
  SIM_SCALAR_DOMAIN_MODULAR
}
 Scalar algebra domain used by IR typing and legality rules. More...
 
enum  SimScalarCapability {
  SIM_SCALAR_CAP_NONE = 0u , SIM_SCALAR_CAP_ADDITIVE_ARITHMETIC = 1u << 0 , SIM_SCALAR_CAP_MULTIPLICATIVE_ARITHMETIC = 1u << 1 , SIM_SCALAR_CAP_DIVISION = 1u << 2 ,
  SIM_SCALAR_CAP_ORDERING = 1u << 3 , SIM_SCALAR_CAP_FLOOR = 1u << 4 , SIM_SCALAR_CAP_MODULO = 1u << 5 , SIM_SCALAR_CAP_ANALYTIC_CALL = 1u << 6 ,
  SIM_SCALAR_CAP_CONJUGATION = 1u << 7 , SIM_SCALAR_CAP_COMPLEX_ROTATION = 1u << 8 , SIM_SCALAR_CAP_POWER = 1u << 9
}
 Bitmask describing operations supported by a scalar domain. More...
 

Functions

SimResult sim_field_allocator_default (SimFieldAllocator *allocator)
 Populate allocator with libc malloc/free.
 
SimResult sim_field_init (SimField *field, size_t rank, const size_t *shape, size_t element_size, SimFieldStorage storage, const SimFieldAllocator *allocator)
 Initialize an owning field and allocate storage.
 
SimResult sim_field_init_typed (SimField *field, size_t rank, const size_t *shape, SimScalarDomain scalar_domain, SimFieldStorage storage, const SimFieldAllocator *allocator)
 Initialize an owning field with an explicit scalar domain.
 
SimResult sim_field_wrap (SimField *field, const SimFieldLayout *layout, size_t element_size, SimFieldStorage storage, void *data)
 Initialize a non-owning view over existing data.
 
SimResult sim_field_wrap_typed (SimField *field, const SimFieldLayout *layout, SimScalarDomain scalar_domain, SimFieldStorage storage, void *data)
 Initialize a non-owning view with an explicit scalar domain.
 
void sim_field_destroy (SimField *field)
 Release all resources held by a field.
 
SimResult sim_field_index_offset (const SimField *field, const size_t *indices, size_t *out_offset)
 Compute the linear offset for provided indices.
 
SimResult sim_field_element_index (const SimField *field, const size_t *indices, size_t rank, size_t *out_index)
 Compute the linear element index for the provided indices.
 
void * sim_field_data (SimField *field)
 Obtain the raw data pointer.
 
const void * sim_field_data_const (const SimField *field)
 Obtain the raw data pointer (const-qualified).
 
size_t sim_field_element_count (const SimFieldLayout *layout)
 Returns the total number of scalar elements in the field layout.
 
size_t sim_field_bytes (const SimField *field)
 Compute the total number of bytes occupied by the field.
 
size_t sim_field_rank (const SimField *field)
 Access the field rank.
 
const size_t * sim_field_shape (const SimField *field)
 Access the shape array.
 
const size_t * sim_field_strides (const SimField *field)
 Access the stride array.
 
size_t sim_field_width (const SimField *field)
 Convenience width accessor for the fastest-varying axis.
 
size_t sim_field_height (const SimField *field)
 Convenience height accessor for the next-to-fastest axis.
 
SimResult sim_field_index_to_xy (const SimField *field, size_t index, size_t *out_x, size_t *out_y)
 Convert a linear element index into 2D coordinates.
 
SimResult sim_field_xy_to_index (const SimField *field, size_t x, size_t y, size_t *out_index)
 Convert 2D coordinates into a linear element index.
 
bool sim_field_complex_mode (const SimField *field)
 Returns true if the field must behave as complex.
 
bool sim_field_storage_is_complex (const SimField *field)
 Returns whether the field storage is complex (SimComplexDouble).
 
bool sim_field_domain_is_complex (const SimField *field)
 Returns whether the field scalar-domain semantics are complex.
 
bool sim_field_is_complex (const SimField *field)
 Legacy compatibility alias for complex-storage checks.
 
size_t sim_field_components (const SimField *field)
 Returns the number of scalar components per logical element.
 
double * sim_field_real_data (SimField *field)
 Convenience accessor for fields with scalar double elements.
 
const double * sim_field_real_data_const (const SimField *field)
 
int8_t * sim_field_i8_data (SimField *field)
 
const int8_t * sim_field_i8_data_const (const SimField *field)
 
int32_t * sim_field_i32_data (SimField *field)
 
const int32_t * sim_field_i32_data_const (const SimField *field)
 
int64_t * sim_field_i64_data (SimField *field)
 
const int64_t * sim_field_i64_data_const (const SimField *field)
 
uint8_t * sim_field_u8_data (SimField *field)
 
const uint8_t * sim_field_u8_data_const (const SimField *field)
 
uint32_t * sim_field_u32_data (SimField *field)
 
const uint32_t * sim_field_u32_data_const (const SimField *field)
 
uint64_t * sim_field_u64_data (SimField *field)
 
const uint64_t * sim_field_u64_data_const (const SimField *field)
 
SimComplexDoublesim_field_complex_data (SimField *field)
 Convenience accessor for fields with complex double elements.
 
const SimComplexDoublesim_field_complex_data_const (const SimField *field)
 
SimResult sim_field_promote_inplace_to_complex (SimField *field)
 
SimResult sim_field_require_complex (SimField *field)
 Force a field into complex storage if it is not already using it.
 
SimFieldRepresentation sim_field_representation (const SimField *field)
 
SimScalarDomain sim_field_scalar_domain (const SimField *field)
 
SimResult sim_field_set_scalar_domain (SimField *field, SimScalarDomain domain)
 
bool sim_field_storage_matches_scalar_domain (size_t element_size, SimScalarDomain domain)
 
SimScalarDomain sim_scalar_domain_unknown (void)
 
SimScalarDomain sim_scalar_domain_f64 (void)
 
SimScalarDomain sim_scalar_domain_c64 (void)
 
SimScalarDomain sim_scalar_domain_i8 (void)
 
SimScalarDomain sim_scalar_domain_i32 (void)
 
SimScalarDomain sim_scalar_domain_i64 (void)
 
SimScalarDomain sim_scalar_domain_u8 (void)
 
SimScalarDomain sim_scalar_domain_u32 (void)
 
SimScalarDomain sim_scalar_domain_u64 (void)
 
SimScalarDomain sim_scalar_domain_from_legacy_complex_flag (bool is_complex)
 
SimScalarDomain sim_scalar_domain_from_field_representation (SimFieldRepresentation repr)
 
SimScalarDomain sim_scalar_domain_from_field (const SimField *field)
 
const char * sim_scalar_domain_kind_name (SimScalarDomainKind kind)
 
bool sim_scalar_domain_kind_from_name (const char *text, SimScalarDomainKind *out_kind)
 
const char * sim_scalar_domain_name (SimScalarDomain domain)
 
bool sim_scalar_domain_from_name (const char *text, SimScalarDomain *out_domain)
 
bool sim_scalar_domain_equal (SimScalarDomain lhs, SimScalarDomain rhs)
 
bool sim_scalar_domain_validate (SimScalarDomain domain)
 
bool sim_scalar_domain_is_complex (SimScalarDomain domain)
 
bool sim_scalar_domain_is_integer (SimScalarDomain domain)
 
uint32_t sim_scalar_domain_capabilities (SimScalarDomain domain)
 
bool sim_scalar_domain_supports (SimScalarDomain domain, uint32_t capability_mask)
 
const char * sim_field_domain_name (SimFieldDomain domain)
 
const char * sim_field_value_kind_name (SimFieldValueKind kind)
 
bool sim_field_domain_from_name (const char *text, SimFieldDomain *out_domain)
 
bool sim_field_value_kind_from_name (const char *text, SimFieldValueKind *out_kind)
 
bool sim_field_value_kind_is_complex_valued (SimFieldValueKind kind)
 
bool sim_field_value_kind_has_imag_zero_constraint (SimFieldValueKind kind)
 
bool sim_field_value_kind_has_spectral_real_constraint (SimFieldValueKind kind)
 
bool sim_field_representation_requires_complex_storage (SimFieldRepresentation repr)
 
bool sim_field_representation_has_imag_zero_constraint (SimFieldRepresentation repr)
 
bool sim_field_representation_has_spectral_real_constraint (SimFieldRepresentation repr)
 
SimResult sim_field_validate_representation (const SimField *field, SimFieldRepresentation repr)
 
SimResult sim_field_set_representation (SimField *field, SimFieldRepresentation repr)
 

Detailed Description

Multidimensional contiguous field abstraction with configurable layout.

SimField owns or views contiguous scalar storage with explicit shape, stride, scalar-domain, and representation metadata. Constructors that allocate storage transfer ownership to the field and require sim_field_destroy(); wrapping constructors keep caller-owned data alive only for the lifetime supplied by the caller.

Typedef Documentation

◆ SimComplexDouble

Explicit in-memory representation for a complex double scalar (re, im)

Used instead of "double complex" in public headers to avoid C++/Objective-C++ parsing issues.

◆ SimScalarDomain

Unified scalar-domain descriptor.

kind encodes scalar algebra class. bit_width, is_signed, and modulus provide parameters for integer/modular families.

◆ SimScalarDomainKind

Scalar algebra domain used by IR typing and legality rules.

This descriptor intentionally excludes representation constraints (e.g., Hermitian symmetry), which remain in SimFieldRepresentation.

Enumeration Type Documentation

◆ SimFieldDomain

Domain for field representation (physical vs spectral).

Enumerator
SIM_FIELD_DOMAIN_UNKNOWN 

Domain has not been specified.

SIM_FIELD_DOMAIN_PHYSICAL 

Samples live in physical/sample space.

SIM_FIELD_DOMAIN_SPECTRAL 

Samples live in Fourier/spectral space.

SIM_FIELD_DOMAIN_HYBRID 

Representation mixes physical and spectral semantics.

◆ SimFieldStorage

Supported field storage ordering schemes.

Enumerator
SIM_FIELD_STORAGE_ROW_MAJOR 

Row-major contiguous layout (C-style).

◆ SimFieldValueKind

Value kind for field scalars.

Enumerator
SIM_FIELD_VALUE_REAL_SCALAR 

Real-valued scalar storage.

SIM_FIELD_VALUE_COMPLEX_SCALAR 

Complex-valued scalar storage.

SIM_FIELD_VALUE_COMPLEX_REAL_CONSTRAINT 

Complex storage with Hermitian symmetry / real signal.

SIM_FIELD_VALUE_COMPLEX_IMAG_ZERO_CONSTRAINT 

Complex storage with structurally zero imaginary lane.

SIM_FIELD_VALUE_UNKNOWN 

Value kind has not been specified.

◆ SimResult

enum SimResult

Return codes shared by libsimcore modules.

Enumerator
SIM_RESULT_OK 

Operation succeeded.

SIM_RESULT_INVALID_ARGUMENT 

One or more arguments were invalid.

SIM_RESULT_INVALID_STATE 

Operation not allowed in current state.

SIM_RESULT_OUT_OF_MEMORY 

Allocation failed.

SIM_RESULT_NOT_FOUND 

Requested element was not found.

SIM_RESULT_NOT_SUPPORTED 

Requested capability is not supported.

SIM_RESULT_DEPENDENCY_ERROR 

Graph dependency resolution failed.

SIM_RESULT_TYPE_MISMATCH 

Type mismatch encountered.

◆ SimScalarCapability

Bitmask describing operations supported by a scalar domain.

Enumerator
SIM_SCALAR_CAP_NONE 

No scalar operations are guaranteed.

SIM_SCALAR_CAP_ADDITIVE_ARITHMETIC 

Addition/subtraction supported.

SIM_SCALAR_CAP_MULTIPLICATIVE_ARITHMETIC 

Multiplication supported.

SIM_SCALAR_CAP_DIVISION 

Division supported.

SIM_SCALAR_CAP_ORDERING 

Ordering comparisons supported.

SIM_SCALAR_CAP_FLOOR 

Floor operation supported.

SIM_SCALAR_CAP_MODULO 

Modulo/remainder operation supported.

SIM_SCALAR_CAP_ANALYTIC_CALL 

Analytic function calls supported.

SIM_SCALAR_CAP_CONJUGATION 

Complex conjugation supported.

SIM_SCALAR_CAP_COMPLEX_ROTATION 

Complex phase rotation supported.

SIM_SCALAR_CAP_POWER 

Power operation supported.

◆ SimScalarDomainKind

Scalar algebra domain used by IR typing and legality rules.

This descriptor intentionally excludes representation constraints (e.g., Hermitian symmetry), which remain in SimFieldRepresentation.

Enumerator
SIM_SCALAR_DOMAIN_UNKNOWN 

Scalar domain is unspecified.

SIM_SCALAR_DOMAIN_REAL 

Real floating-point algebra.

SIM_SCALAR_DOMAIN_COMPLEX 

Complex floating-point algebra.

SIM_SCALAR_DOMAIN_INTEGER 

Exact integer algebra.

SIM_SCALAR_DOMAIN_MODULAR 

Integer algebra modulo a fixed modulus.

Function Documentation

◆ sim_field_allocator_default()

SimResult sim_field_allocator_default ( SimFieldAllocator allocator)

Populate allocator with libc malloc/free.

Parameters
[out]allocatorTarget allocator record.
Returns
SIM_RESULT_OK on success.

◆ sim_field_bytes()

size_t sim_field_bytes ( const SimField field)

Compute the total number of bytes occupied by the field.

Parameters
fieldField instance.
Returns
Total byte size, or 0 for an invalid field.

◆ sim_field_complex_data()

SimComplexDouble * sim_field_complex_data ( SimField field)

Convenience accessor for fields with complex double elements.

Interpret backing memory as an array of double complex (re,im); returns NULL when the field doesn't correspond to complex double storage.

◆ sim_field_complex_mode()

bool sim_field_complex_mode ( const SimField field)

Returns true if the field must behave as complex.

True when the field is already stored as complex or has been marked to require complex storage (the runtime will promote if needed).

◆ sim_field_components()

size_t sim_field_components ( const SimField field)

Returns the number of scalar components per logical element.

For standard double-precision scalars returns 1, for complex double returns 2.

◆ sim_field_data()

void * sim_field_data ( SimField field)

Obtain the raw data pointer.

Parameters
fieldField instance.
Returns
Writable data pointer, or NULL if uninitialized.

◆ sim_field_data_const()

const void * sim_field_data_const ( const SimField field)

Obtain the raw data pointer (const-qualified).

Parameters
fieldField instance.
Returns
Read-only data pointer, or NULL if uninitialized.

◆ sim_field_destroy()

void sim_field_destroy ( SimField field)

Release all resources held by a field.

Parameters
fieldField to destroy; may be NULL.

◆ sim_field_domain_is_complex()

bool sim_field_domain_is_complex ( const SimField field)

Returns whether the field scalar-domain semantics are complex.

This is representation/scalar-domain aware and may differ from raw storage during transitional states. Prefer this for semantic dispatch.

◆ sim_field_element_index()

SimResult sim_field_element_index ( const SimField field,
const size_t *  indices,
size_t  rank,
size_t *  out_index 
)

Compute the linear element index for the provided indices.

Parameters
fieldField instance.
indicesArray of indices.
rankNumber of indices supplied (must match field rank).
[out]out_indexReceives the element index (not bytes).
Returns
SIM_RESULT_OK on success or SIM_RESULT_INVALID_ARGUMENT.

◆ sim_field_height()

size_t sim_field_height ( const SimField field)

Convenience height accessor for the next-to-fastest axis.

For rank >= 2, returns shape[rank-2]. For rank == 1, returns 1.

◆ sim_field_index_offset()

SimResult sim_field_index_offset ( const SimField field,
const size_t *  indices,
size_t *  out_offset 
)

Compute the linear offset for provided indices.

Parameters
fieldField instance.
indicesArray of length SimFieldLayout::rank.
[out]out_offsetReceives the byte offset within SimField::data.
Returns
SIM_RESULT_OK on success or SIM_RESULT_INVALID_ARGUMENT.

◆ sim_field_index_to_xy()

SimResult sim_field_index_to_xy ( const SimField field,
size_t  index,
size_t *  out_x,
size_t *  out_y 
)

Convert a linear element index into 2D coordinates.

Uses the canonical convention: x=axis rank-1 (fast), y=axis rank-2 (slow). For rank == 1, y is set to 0. For rank > 2, other axes are assumed 0.

◆ sim_field_init()

SimResult sim_field_init ( SimField field,
size_t  rank,
const size_t *  shape,
size_t  element_size,
SimFieldStorage  storage,
const SimFieldAllocator allocator 
)

Initialize an owning field and allocate storage.

Parameters
[out]fieldField instance to initialize.
rankDimensionality of the field.
shapeArray of rank entries describing dimension extents.
element_sizeSize of a single element in bytes.
storageDesired storage ordering.
allocatorOptional allocator (pass NULL for default).
Returns
SIM_RESULT_OK on success, error code otherwise.

◆ sim_field_init_typed()

SimResult sim_field_init_typed ( SimField field,
size_t  rank,
const size_t *  shape,
SimScalarDomain  scalar_domain,
SimFieldStorage  storage,
const SimFieldAllocator allocator 
)

Initialize an owning field with an explicit scalar domain.

This constructor avoids ambiguous size-based inference for integer fields.

Parameters
[out]fieldField instance to initialize.
rankDimensionality of the field.
shapeArray of rank entries describing dimension extents.
scalar_domainExact scalar domain to use for storage and semantics.
storageDesired storage ordering.
allocatorOptional allocator (pass NULL for default).
Returns
SIM_RESULT_OK on success, error code otherwise.

◆ sim_field_is_complex()

bool sim_field_is_complex ( const SimField field)

Legacy compatibility alias for complex-storage checks.

Deprecated for semantic decisions; use sim_field_domain_is_complex(...) for algebraic behavior, or sim_field_storage_is_complex(...) for memory-layout checks.

◆ sim_field_rank()

size_t sim_field_rank ( const SimField field)

Access the field rank.

Parameters
fieldField instance.
Returns
Rank value; zero if field is NULL.

◆ sim_field_real_data()

double * sim_field_real_data ( SimField field)

Convenience accessor for fields with scalar double elements.

Parameters
fieldField instance.
Returns
Pointer to the data as a double array, or NULL if field is invalid.

◆ sim_field_require_complex()

SimResult sim_field_require_complex ( SimField field)

Force a field into complex storage if it is not already using it.

Safe to call repeatedly; returns an error if promotion is not possible.

◆ sim_field_shape()

const size_t * sim_field_shape ( const SimField field)

Access the shape array.

Parameters
fieldField instance.
Returns
Pointer to the shape array, or NULL.

◆ sim_field_storage_is_complex()

bool sim_field_storage_is_complex ( const SimField field)

Returns whether the field storage is complex (SimComplexDouble).

Parameters
fieldField instance.
Returns
true when element size equals 2*sizeof(double), false otherwise.

◆ sim_field_strides()

const size_t * sim_field_strides ( const SimField field)

Access the stride array.

Parameters
fieldField instance.
Returns
Pointer to the stride array, or NULL.

◆ sim_field_width()

size_t sim_field_width ( const SimField field)

Convenience width accessor for the fastest-varying axis.

For rank >= 1, returns shape[rank-1]. Returns 0 for invalid fields.

◆ sim_field_wrap()

SimResult sim_field_wrap ( SimField field,
const SimFieldLayout layout,
size_t  element_size,
SimFieldStorage  storage,
void *  data 
)

Initialize a non-owning view over existing data.

Parameters
[out]fieldField instance to initialize.
layoutLayout metadata copied into the field.
element_sizeSize of a single element in bytes.
storageStorage ordering of data.
dataPointer to externally managed buffer.
Returns
SIM_RESULT_OK on success or SIM_RESULT_INVALID_ARGUMENT.

◆ sim_field_wrap_typed()

SimResult sim_field_wrap_typed ( SimField field,
const SimFieldLayout layout,
SimScalarDomain  scalar_domain,
SimFieldStorage  storage,
void *  data 
)

Initialize a non-owning view with an explicit scalar domain.

This constructor avoids ambiguous size-based inference for integer fields.

Parameters
[out]fieldField instance to initialize.
layoutLayout metadata copied into the field.
scalar_domainExact scalar domain to use for storage and semantics.
storageStorage ordering of data.
dataPointer to externally managed buffer.
Returns
SIM_RESULT_OK on success or an error code otherwise.

◆ sim_field_xy_to_index()

SimResult sim_field_xy_to_index ( const SimField field,
size_t  x,
size_t  y,
size_t *  out_index 
)

Convert 2D coordinates into a linear element index.

Uses the canonical convention: x=axis rank-1 (fast), y=axis rank-2 (slow). For rank == 1, y must be 0. For rank > 2, other axes are assumed 0.