ndarray - multi-dimensional array library for C, with Zig and Nim bindings

SYNOPSIS

A library for working with multi-dimensional arrays, providing efficient operations through OpenMP parallelization and BLAS optimization. The core implementation is written in C, with first-class support for Zig and Nim through native bindings.

DESCRIPTION

The ndarray library emerged from the need to implement algorithms requiring multi-dimensional array operations in C, without sacrificing performance or ergonomics. It provides a foundation for numerical computing while maintaining zero-copy integration with the GNU Scientific Library (GSL) for vectors and matrices.

The library takes a polyglot approach: the core is implemented in C for maximum portability and performance, while Zig and Nim bindings provide modern language conveniences without sacrificing the underlying efficiency. Each language binding maintains the same conceptual model while respecting the idioms of its host language.

FEATURES

Multi-dimensional arrays: Support for arrays with two or more dimensions (ndim >= 2), with arbitrary shapes for efficient memory layouts.

Parallel operations: OpenMP parallelization of computationally intensive operations, enabling efficient utilization of multi-core processors.

BLAS optimization: Integration with OpenBLAS for high-performance linear algebra operations.

GSL integration: Zero-copy integration with GSL for vectors and matrices, allowing seamless use of GSL's extensive mathematical functions on ndarray data structures.

Language bindings: Native bindings for Zig and Nim, providing idiomatic interfaces while maintaining full access to the underlying C implementation.

DEPENDENCIES

OpenMP - for parallel execution
OpenBLAS - for optimized linear algebra
GSL - for zero-copy integration with scientific computing functions

GETTING STARTED

For C Projects: Consult the C Building guide for compilation instructions and linking requirements.

For Zig Projects: Add the library to your project using the Zig package manager:

zig fetch --save "git+https://github.com/jailop/ndarray-c#main"

See Zig Building for detailed integration instructions.

For Nim Projects: The Nim bindings are included in this repository under the nim/ directory. Add the library to your nimble dependencies or use it directly from the source.

nimble install ndarray

DOCUMENTATION

Design philosophy: Design Considerations explains the architectural decisions and trade-offs that shaped this library.

API reference: Complete API documentation is available at:

https://jailop.github.io/ndarray-c/

AI-generated documentation: An alternative perspective generated by AI can be found at:

https://deepwiki.com/jailop/ndarray-c

LIMITATIONS

Type support: Only double-precision floating point (double) is currently supported for array elements. This decision reflects the library's focus on numerical computing applications where double precision is standard.

Scope: This library implements fundamental operations for multi-dimensional arrays. For specialized vector and matrix operations, the zero-copy GSL integration provides access to GSL's comprehensive function library on vectors ([1,D] or [D,1]) and matrices without data copying overhead.

Dimension limits (Zig): Zig and Nim bindings impose a maximum of 64 dimensions due to the use of thread-local pre-allocated buffers for type conversion. This parameter can be adjusted at compile time if needed.

DEVELOPMENT STATUS

This library is under development. The API is not yet stable and may change without notice. While functional and tested, it is not recommended for production use at this time. Feedback and contributions are welcomed.

PENDING DESIGN DECISIONS

Error handling: The error management strategy is still being refined. Currently, assertions are used to validate invariants, causing program termination when violated. A more sophisticated error handling mechanism is planned.

Naming conventions: The intention is for function names to indicate their behavior: functions returning newly allocated arrays or scalars are explicitly named, while functions without such indication perform in-place operations on the first argument. This convention is still being refined across the codebase.

CONTRIBUTING

Envirioned features and enhancement ideas are tracked in the ROADMAP. Contributions aligned with the project's goals are welcome.

LICENSE

This library is distributed under the BSD 3-Clause License. See the [LICENSE](LICENSE) file for complete terms.

AUTHOR

Jaime Lopez (https://algo.datainquiry.dev)