|
Oakfield API Documentation 1.0.0
Numerical core APIs
|
Multidimensional contiguous field abstraction with configurable layout. More...
#include <complex.h>#include <stdbool.h>#include <stddef.h>#include <stdint.h>

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) | |
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) |
| SimComplexDouble * | sim_field_complex_data (SimField *field) |
| Convenience accessor for fields with complex double elements. | |
| const SimComplexDouble * | sim_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) |
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 struct SimComplexDouble 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.
| typedef struct SimScalarDomain SimScalarDomain |
Unified scalar-domain descriptor.
kind encodes scalar algebra class. bit_width, is_signed, and modulus provide parameters for integer/modular families.
| typedef enum SimScalarDomainKind 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.
| enum SimFieldDomain |
Domain for field representation (physical vs spectral).
| enum SimFieldStorage |
| enum SimFieldValueKind |
Value kind for field scalars.
| enum SimResult |
Return codes shared by libsimcore modules.
| enum SimScalarCapability |
Bitmask describing operations supported by a scalar domain.
| enum 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.
| SimResult sim_field_allocator_default | ( | SimFieldAllocator * | allocator | ) |
Populate allocator with libc malloc/free.
| [out] | allocator | Target allocator record. |
| size_t sim_field_bytes | ( | const SimField * | field | ) |
Compute the total number of bytes occupied by the field.
| field | Field instance. |
| 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.
| 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).
| 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.
| void * sim_field_data | ( | SimField * | field | ) |
Obtain the raw data pointer.
| field | Field instance. |
| const void * sim_field_data_const | ( | const SimField * | field | ) |
Obtain the raw data pointer (const-qualified).
| field | Field instance. |
| void sim_field_destroy | ( | SimField * | field | ) |
Release all resources held by a field.
| field | Field to destroy; may be NULL. |
| 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.
| 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.
| field | Field instance. | |
| indices | Array of indices. | |
| rank | Number of indices supplied (must match field rank). | |
| [out] | out_index | Receives the element index (not bytes). |
| 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.
| SimResult sim_field_index_offset | ( | const SimField * | field, |
| const size_t * | indices, | ||
| size_t * | out_offset | ||
| ) |
Compute the linear offset for provided indices.
| field | Field instance. | |
| indices | Array of length SimFieldLayout::rank. | |
| [out] | out_offset | Receives the byte offset within SimField::data. |
| 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.
| 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.
| [out] | field | Field instance to initialize. |
| rank | Dimensionality of the field. | |
| shape | Array of rank entries describing dimension extents. | |
| element_size | Size of a single element in bytes. | |
| storage | Desired storage ordering. | |
| allocator | Optional allocator (pass NULL for default). |
| 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.
| [out] | field | Field instance to initialize. |
| rank | Dimensionality of the field. | |
| shape | Array of rank entries describing dimension extents. | |
| scalar_domain | Exact scalar domain to use for storage and semantics. | |
| storage | Desired storage ordering. | |
| allocator | Optional allocator (pass NULL for default). |
| 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.
| size_t sim_field_rank | ( | const SimField * | field | ) |
Access the field rank.
| field | Field instance. |
field is NULL. | double * sim_field_real_data | ( | SimField * | field | ) |
Convenience accessor for fields with scalar double elements.
| field | Field instance. |
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.
| const size_t * sim_field_shape | ( | const SimField * | field | ) |
Access the shape array.
| field | Field instance. |
| bool sim_field_storage_is_complex | ( | const SimField * | field | ) |
Returns whether the field storage is complex (SimComplexDouble).
| field | Field instance. |
| const size_t * sim_field_strides | ( | const SimField * | field | ) |
Access the stride array.
| field | Field instance. |
| 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.
| 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.
| [out] | field | Field instance to initialize. |
| layout | Layout metadata copied into the field. | |
| element_size | Size of a single element in bytes. | |
| storage | Storage ordering of data. | |
| data | Pointer to externally managed buffer. |
| 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.
| [out] | field | Field instance to initialize. |
| layout | Layout metadata copied into the field. | |
| scalar_domain | Exact scalar domain to use for storage and semantics. | |
| storage | Storage ordering of data. | |
| data | Pointer to externally managed buffer. |