### Install and Install Pre-commit Hooks

Source: https://github.com/ml-explore/mlx-c/blob/main/CONTRIBUTING.md

Install pre-commit to automatically format C/C++ and Python code before committing. Run 'pre-commit install' to set up the hooks.

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Install Doxygen using Homebrew

Source: https://github.com/ml-explore/mlx-c/blob/main/docs/README.md

Install the Doxygen documentation system using the Homebrew package manager.

```bash
brew install doxygen
```

--------------------------------

### Install Python Packages

Source: https://github.com/ml-explore/mlx-c/blob/main/docs/README.md

Install required Python packages for the project by referencing the requirements.txt file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Get and Access Device Information

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Demonstrates how to get device information and access its properties. Ensure to free the info object after use.

```c
mlx_device dev = mlx_device_new();
mlx_get_default_device(&dev);
mx_device_info info = mlx_device_info_new();
mx_device_info_get(&info, dev);
// Access device properties via the info object
mx_device_info_free(info);
```

--------------------------------

### Install CMake with Homebrew

Source: https://github.com/ml-explore/mlx-c/blob/main/README.md

Install CMake using the Homebrew package manager. This is a prerequisite for building MLX C.

```shell
brew install cmake
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/ml-explore/mlx-c/blob/main/docs/README.md

Start a local HTTP server to view the built documentation. Replace <port> with your desired port number.

```bash
python -m http.server <port>
```

--------------------------------

### Example Usage of Optional Integer

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/types.md

Demonstrates how to initialize and use the mlx_optional_int type to represent values that may or may not be present.

```c
mlx_optional_int opt = {5, true};   // Has value 5
mlx_optional_int none = {0, false}; // No value
```

--------------------------------

### Example: Exporting Computation Graph

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Demonstrates how to create a node namer, set a name for a result node, export the graph to a DOT file, and clean up resources. The exported graph can be visualized using the 'dot' command.

```c
mlx_node_namer namer = mlx_node_namer_new();
mlx_node_namer_set_name(namer, result, "output");

FILE* f = fopen("graph.dot", "w");
mlx_export_to_dot(f, namer, outputs);
fclose(f);

mlx_node_namer_free(namer);
// Then visualize with: dot -Tpng graph.dot -o graph.png
```

--------------------------------

### Create new empty mlx_string

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Creates a new, empty string handle. No setup is required.

```c
mlx_string mlx_string_new(void);
```

--------------------------------

### Compile User Code with MLX C

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Provides example bash commands for building the MLX C library using CMake and then compiling a user application that links against it. Ensure Metal and Accelerate frameworks are available for Metal backend.

```bash
# Build MLX C (requires CMake)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

# Compile user code (example)
gcc -o myapp myapp.c \
  -I./mlx/c \
  -L./build \
  -lmlx \
  -framework Metal \
  -framework Accelerate
```

--------------------------------

### Build Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet shows how to define a C executable and link it with the mlxc library. Use this for general MLX C examples.

```cmake
add_executable(example ${CMAKE_CURRENT_LIST_DIR}/example.c)
target_link_libraries(example PUBLIC mlxc)
```

--------------------------------

### Build Metal Kernel Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet shows how to build a C executable for Metal kernel examples and link it with the mlxc library. Use this for GPU-accelerated computations on Apple platforms.

```cmake
add_executable(example-metal-kernel
               ${CMAKE_CURRENT_LIST_DIR}/example-metal-kernel.c)
target_link_libraries(example-metal-kernel PUBLIC mlxc)
```

--------------------------------

### Build Gradient Calculation Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet shows how to build a C executable for gradient calculation examples and link it with the mlxc library. Use this for automatic differentiation tasks.

```cmake
add_executable(example-grad ${CMAKE_CURRENT_LIST_DIR}/example-grad.c)
target_link_libraries(example-grad PUBLIC mlxc)
```

--------------------------------

### Build Closure Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet demonstrates building a C executable for examples involving closures and linking it with the mlxc library. Use this for functional programming patterns in C.

```cmake
add_executable(example-closure ${CMAKE_CURRENT_LIST_DIR}/example-closure.c)
target_link_libraries(example-closure PUBLIC mlxc)
```

--------------------------------

### Start Metal Frame Capture

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Initiates Metal frame capture for performance profiling. Captured data will be saved to the specified file path.

```c
int mlx_metal_start_capture(const char* path);
```

--------------------------------

### Build Graph Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet shows how to build a C executable for examples related to computational graphs and linking it with the mlxc library. Use this for exploring MLX's graph computation capabilities.

```cmake
add_executable(example-graph ${CMAKE_CURRENT_LIST_DIR}/example-graph.c)
target_link_libraries(example-graph PUBLIC mlxc)
```

--------------------------------

### Iterate over string-to-array map entries

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

This example demonstrates how to iterate through all key-value pairs in a string-to-array map using its iterator. Remember to free the iterator after use.

```c
typedef struct mlx_map_string_to_array_iterator_ {
  void* ctx;
  void* map_ctx;
} mlx_map_string_to_array_iterator;

mix_map_string_to_array_iterator mlx_map_string_to_array_iterator_new(mlx_map_string_to_array map);

int mlx_map_string_to_array_iterator_next(const char** key, mlx_array* value, mlx_map_string_to_array_iterator it);

int mlx_map_string_to_array_iterator_free(mlx_map_string_to_array_iterator it);

// Example usage:
mix_map_string_to_array_iterator it = mlx_map_string_to_array_iterator_new(map);
const char* key;
Mlx_array value;
while (mlx_map_string_to_array_iterator_next(&key, &value, it) == 0) {
  printf("%s: ...\n", key);
}
mix_map_string_to_array_iterator_free(it);
```

--------------------------------

### Build Export Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet shows how to build a C executable for examples related to exporting models or data and linking it with the mlxc library. Use this for model interoperability.

```cmake
add_executable(example-export ${CMAKE_CURRENT_LIST_DIR}/example-export.c)
target_link_libraries(example-export PUBLIC mlxc)
```

--------------------------------

### Build GGUF Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet demonstrates building a C executable for examples involving the GGUF format and linking it with the mlxc library. Use this for loading and saving models in GGUF format.

```cmake
add_executable(example-gguf ${CMAKE_CURRENT_LIST_DIR}/example-gguf.c)
target_link_libraries(example-gguf PUBLIC mlxc)
```

--------------------------------

### Broadcast Arrays in C

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Applies broadcasting rules to a collection of arrays, making them compatible for element-wise operations. This example prepares arrays `a` and `b` for broadcasting.

```c
mlx_vector_array inputs = mlx_vector_array_new();
ilx_vector_array_append_value(inputs, a);  // Shape (3, 4)
ilx_vector_array_append_value(inputs, b);  // Shape (1, 4)

ilx_vector_array broadcasted;
ilx_broadcast_arrays(&broadcasted, inputs, stream);
// Now both have shape (3, 4)
```

--------------------------------

### Iterating Over MLX Vectors and Maps

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/README.md

Provides examples for iterating through elements of an `mlx_vector_array` and key-value pairs in an `mlx_map_string_to_array`. Ensure iterators are freed after use.

```c
// Vectors
for (size_t i = 0; i < mlx_vector_array_size(vec); i++) {
  mlx_array elem;
  mlx_vector_array_get(&elem, vec, i);
  // Use elem
}

// Maps
ilx_map_string_to_array_iterator it = mlx_map_string_to_array_iterator_new(map);
const char* key;
ilx_array value;
while (mlx_map_string_to_array_iterator_next(&key, &value, it) == 0) {
  printf("%s -> ...\n", key);
}
ilx_map_string_to_array_iterator_free(it);
```

--------------------------------

### Create mlx_vector_int with initial value

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Creates a vector containing a single integer value. This is useful for initializing a vector with a starting point.

```c
mlx_vector_int mlx_vector_int_new_value(int val);
```

--------------------------------

### Get All Keys from Device Info

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Retrieves a list of all available keys within the device info object. Iterates through the keys and prints them. Remember to free the vector of keys.

```c
mlx_vector_string keys = mlx_vector_string_new();
mx_device_info_get_keys(&keys, info);
size_t num_keys = mlx_vector_string_size(keys);
for (size_t i = 0; i < num_keys; i++) {
  char* key = NULL;
  mlx_vector_string_get(&key, keys, i);
  printf("Key: %s\n", key);
}
mx_vector_string_free(keys);
```

--------------------------------

### MLX Unary Operations

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Provides examples of common unary mathematical operations supported by the MLX C API, such as exponential, sine, and logarithm.

```c
mlx_exp(&res, arr, stream);
mix_sin(&res, arr, stream);
mix_log(&res, arr, stream);
```

--------------------------------

### Build Documentation

Source: https://github.com/ml-explore/mlx-c/blob/main/docs/README.md

Build the documentation using Doxygen and then compile it into HTML format using Make.

```bash
doxygen && make html
```

--------------------------------

### Create mlx_vector_array with initial value

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Creates a vector containing a single mlx_array element. This is useful for initializing a vector with a starting value.

```c
mlx_vector_array mlx_vector_array_new_value(const mlx_array val);
```

--------------------------------

### mlx_dtype_size

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Get the size in bytes of a datatype.

```APIDOC
## mlx_dtype_size(mlx_dtype dtype)

### Description
Get the size in bytes of a datatype.

### Parameters
#### Path Parameters
- **dtype** (mlx_dtype) - Required - Datatype to query

### Return
`size_t` — Size in bytes.
```

--------------------------------

### mlx_array_tostring

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets a string representation of the array.

```APIDOC
## mlx_array_tostring

### Description
Gets a string representation of the array.

### Method
C Function

### Parameters
#### Path Parameters
- **str** (mlx_string*) - Output string
- **arr** (const mlx_array) - Array to describe

### Return
`int` — Status code (0 for success).
```

--------------------------------

### Compiling MLX C Project

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/README.md

Provides a sample GCC command for compiling a C program that uses the MLX library. Ensure the paths to headers and libraries are correct.

```bash
# After building MLX C (see MLX repository)
gcc -o program program.c \
  -I/path/to/mlx/headers \
  -L/path/to/mlx/lib \
  -lmlx \
  -framework Metal \
  -framework Accelerate
```

--------------------------------

### mlx_array_dtype

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets the element datatype of the array.

```APIDOC
## mlx_array_dtype

### Description
Gets the element datatype of the array.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - The array to query

### Return
`mlx_dtype` — The element datatype.
```

--------------------------------

### Creating and Manipulating MLX Maps (String to Array)

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Shows how to create string-to-array maps, insert key-value pairs, retrieve values by key, and manage the map's resources.

```c
mlx_map_string_to_array map = mlx_map_string_to_array_new();
mix_map_string_to_array_insert(map, "weight", arr1);
mix_map_string_to_array_insert(map, "bias", arr2);
mix_array weight;
mix_map_string_to_array_get(&weight, map, "weight");
mix_map_string_to_array_free(map);
```

--------------------------------

### mlx_array_ndim

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets the number of dimensions in the array.

```APIDOC
## mlx_array_ndim

### Description
Gets the number of dimensions in the array.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - The array to query

### Return
`size_t` — The number of dimensions.
```

--------------------------------

### mlx_array_dim

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets the size of a specific dimension of the array.

```APIDOC
## mlx_array_dim

### Description
Gets the size of a specific dimension of the array.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - Array to query
- **dim** (int) - Dimension index

### Return
`int` — Size of the dimension.
```

--------------------------------

### mlx_array_shape

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets a pointer to the shape array of the array.

```APIDOC
## mlx_array_shape

### Description
Gets a pointer to the shape array of the array. Valid for `mlx_array_ndim(arr)` elements.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - The array to query

### Return
`const int*` — Pointer to the shape array.

### Example
```c
mlx_array arr = mlx_array_new_data(data, shape, 2, MLX_FLOAT32);
const int* shape_ptr = mlx_array_shape(arr);
// shape_ptr[0] and shape_ptr[1] are the dimensions
```
```

--------------------------------

### Create New Device

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Creates a new device of a specified type and index. Use MLX_GPU for GPU and MLX_CPU for CPU, with an appropriate index.

```c
// Get the first GPU
mlx_device gpu = mlx_device_new_type(MLX_GPU, 0);
// Get the CPU
mlx_device cpu = mlx_device_new_type(MLX_CPU, 0);
```

--------------------------------

### mlx_array_nbytes

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets the total size in bytes of the array.

```APIDOC
## mlx_array_nbytes

### Description
Gets the total size in bytes of the array.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - The array to query

### Return
`size_t` — The total size in bytes.
```

--------------------------------

### Including MLX C Headers

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/README.md

Shows how to include the necessary MLX C header files in your project. You can include all headers with `mlx/c/mlx.h` or specific modules.

```c
#include "mlx/c/mlx.h"  // Include all
// or
#include "mlx/c/array.h"
#include "mlx/c/ops.h"
// etc.
```

--------------------------------

### mlx_array_size

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets the total number of elements in the array.

```APIDOC
## mlx_array_size

### Description
Gets the total number of elements in the array.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - The array to query

### Return
`size_t` — The total number of elements.
```

--------------------------------

### mlx_array_strides

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets a pointer to the strides array (in bytes) of the array.

```APIDOC
## mlx_array_strides

### Description
Gets a pointer to the strides array (in bytes) of the array.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - The array to query

### Return
`const size_t*` — Pointer to the strides array.
```

--------------------------------

### Basic MLX C API Usage Pattern

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Demonstrates the fundamental workflow for using the MLX C API, including stream creation, array initialization, lazy operations, forcing evaluation, data access, and resource cleanup.

```c
#include "mlx/c/mlx.h"

int main(void) {
  // 1. Create stream for async operations
  mlx_stream stream = mlx_default_cpu_stream_new();
  
  // 2. Create arrays
  float data[] = {1, 2, 3, 4, 5, 6};
  int shape[] = {2, 3};
  mlx_array arr = mlx_array_new_data(data, shape, 2, MLX_FLOAT32);
  
  // 3. Perform operations (lazy)
  mlx_array result;
  mlx_add(&result, arr, arr, stream);  // result = arr + arr
  
  // 4. Force evaluation
  mlx_array_eval(result);
  
  // 5. Access data
  const float* result_data = mlx_array_data_float32(result);
  
  // 6. Clean up
  mlx_array_free(arr);
  mlx_array_free(result);
  mlx_stream_free(stream);
  
  return 0;
}
```

--------------------------------

### mlx_array_itemsize

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets the size in bytes of one element in the array.

```APIDOC
## mlx_array_itemsize

### Description
Gets the size in bytes of one element in the array.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - The array to query

### Return
`size_t` — The size in bytes of one element.
```

--------------------------------

### Get Writer Descriptor

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves the user-provided descriptor from an existing mlx_io_writer.

```c
int mlx_io_writer_descriptor(void** desc_, mlx_io_writer io)
```

--------------------------------

### Get Reader Descriptor

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves the user-provided descriptor from an existing mlx_io_reader.

```c
int mlx_io_reader_descriptor(void** desc_, mlx_io_reader io)
```

--------------------------------

### Initialize Distributed Backend

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Initializes the distributed computing backend. Allows for strict error checking and specifies the backend or uses auto-detection.

```c
int mlx_distributed_init(mlx_distributed_group* res, bool strict, const char* bk);
```

--------------------------------

### Create an empty string-to-string map

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Initializes a new, empty map where both keys and values are strings.

```c
typedef struct mlx_map_string_to_string_ {
  void* ctx;
} mlx_map_string_to_string;

mix_map_string_to_string mlx_map_string_to_string_new(void);
```

--------------------------------

### mlx_array_data_float64

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets a pointer to the array data as float64. The array must be evaluated.

```APIDOC
## mlx_array_data_float64

### Description
Gets a pointer to the array data as float64. The array must be evaluated.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - Array (must be evaluated)

### Return
`const double*` — Pointer to data, or NULL if not evaluated.
```

--------------------------------

### mlx_array_data_float32

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets a pointer to the array data as float32. The array must be evaluated.

```APIDOC
## mlx_array_data_float32

### Description
Gets a pointer to the array data as float32. The array must be evaluated.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - Array (must be evaluated)

### Return
`const float*` — Pointer to data, or NULL if not evaluated.
```

--------------------------------

### mlx_array_data_bool

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Gets a pointer to the array data as boolean. The array must be evaluated.

```APIDOC
## mlx_array_data_bool

### Description
Gets a pointer to the array data as boolean. The array must be evaluated.

### Method
C Function

### Parameters
#### Path Parameters
- **arr** (const mlx_array) - Array (must be evaluated)

### Return
`const bool*` — Pointer to data, or NULL if not evaluated.
```

--------------------------------

### Optional Integer Wrapper Usage

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Demonstrates how to create and use an optional integer wrapper, setting both the value and the has_value flag.

```c
mlx_optional_int opt;
opt.value = 5;
opt.has_value = true;
```

--------------------------------

### Get Writer Description

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves a string representation of the writer's description.

```c
int mlx_io_writer_tostring(mlx_string* str_, mlx_io_writer io)
```

--------------------------------

### Get Reader Description

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves a string representation of the reader's description.

```c
int mlx_io_reader_tostring(mlx_string* str_, mlx_io_reader io)
```

--------------------------------

### Get mlx_vector_array size

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Returns the current number of mlx_array elements stored in the vector.

```c
size_t mlx_vector_array_size(mlx_vector_array vec);
```

--------------------------------

### Save and Load MLX Arrays in C

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Demonstrates saving MLX arrays to files in .npy and .safetensors formats, and subsequently loading them back. Ensure the stream is initialized for loading operations.

```c
// Save (auto format from extension)
ilx_save("array.npy", arr);
ilx_save("array.safetensors", arr);

// Load
ilx_array loaded;
ilx_load(&loaded, "array.npy", stream);
```

--------------------------------

### Get MLX Version

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Retrieves the MLX version string. Ensure to free the string after use.

```c
mlx_string version = mlx_string_new();
mxlx_version(&version);
printf("MLX version: %s\n", mlx_string_data(version));
mxlx_string_free(version);
```

--------------------------------

### Create an empty string-to-array map

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Initializes a new, empty map where keys are strings and values are arrays.

```c
typedef struct mlx_map_string_to_array_ {
  void* ctx;
} mlx_map_string_to_array;

mix_map_string_to_array mlx_map_string_to_array_new(void);
```

--------------------------------

### Get Datatype Size

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Retrieves the size in bytes for a given MLX datatype. This is useful for memory calculations.

```c
size_t mlx_dtype_size(mlx_dtype dtype);
```

--------------------------------

### Creating MLX Arrays

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/README.md

Shows different methods for creating `mlx_array` objects: from a scalar value, from existing data buffers, and by allocating zero-initialized arrays.

```c
// Scalar
ilx_array scalar = mlx_array_new_float32(3.14);

// From buffer
float data[] = {1, 2, 3, 4};
int shape[] = {2, 2};
ilx_array arr = mlx_array_new_data(data, shape, 2, MLX_FLOAT32);

// Allocated by MLX
ilx_array zeros;
int zeros_shape[] = {3, 3};
ilx_zeros(&zeros, zeros_shape, 2, MLX_FLOAT32, stream);
```

--------------------------------

### Get Array Shape

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Retrieves the shape of an MLX array. The shape array contains the size of each dimension.

```c
mlx_array arr = mlx_array_new_data(data, shape, 2, MLX_FLOAT32);
const int* shape_ptr = mlx_array_shape(arr);
// shape_ptr[0] and shape_ptr[1] are the dimensions
```

--------------------------------

### Get Size of Distributed Group

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Returns the total number of processes participating in the specified distributed group.

```c
int mlx_distributed_group_size(mlx_distributed_group group);
```

--------------------------------

### Get mlx_vector_array element by index

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Retrieves a specific mlx_array element from the vector at the given index. The index is 0-based.

```c
int mlx_vector_array_get(mlx_array* res, const mlx_vector_array vec, size_t idx);
```

--------------------------------

### mlx_device_count

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Gets the number of available devices of a specified type (e.g., number of GPUs). Useful for resource enumeration.

```APIDOC
## mlx_device_count

### Description
Get the number of available devices of a given type.

### Parameters
#### Path Parameters
- **count** (int*) - Required - Output count
- **type** (mlx_device_type) - Required - Device type

### Return
`int` — Status code (0 for success).

### Example
```c
int gpu_count;
mlx_device_count(&gpu_count, MLX_GPU);
printf("Available GPUs: %d\n", gpu_count);
```

```

--------------------------------

### MLX Binary Operations with Broadcasting

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Illustrates basic binary arithmetic operations like addition, multiplication, and division, which support broadcasting for arrays of compatible shapes.

```c
mlx_add(&res, a, b, stream);
mix_multiply(&res, a, b, stream);
mix_divide(&res, a, b, stream);
```

--------------------------------

### Creating and Manipulating MLX Vectors

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Demonstrates the creation of dynamic arrays (vectors) and how to append MLX arrays to them, retrieve elements, and manage their lifecycle.

```c
mlx_vector_array vec = mlx_vector_array_new();
mix_vector_array_append_value(vec, arr1);
mix_vector_array_append_value(vec, arr2);
size_t size = mlx_vector_array_size(vec);
mix_array element;
mix_vector_array_get(&element, vec, 0);
mix_vector_array_free(vec);
```

--------------------------------

### Get MLX Version

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/README.md

Retrieves and prints the current MLX version string. Ensure the `mlx_string` is freed after use.

```c
mlx_string version = mlx_string_new();
mlx_version(&version);
printf("MLX version: %s\n", mlx_string_data(version));
mxl_string_free(version);
```

--------------------------------

### Run Pre-commit Hooks on All Files

Source: https://github.com/ml-explore/mlx-c/blob/main/CONTRIBUTING.md

Execute all pre-commit hooks on all files in the repository to ensure consistent code style and quality across the project.

```bash
pre-commit run --all-files
```

--------------------------------

### Get Name Associated with Array Node

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Retrieves the name previously associated with a given array node from the namer object.

```c
int mlx_node_namer_get_name(const char** name, mlx_node_namer namer, const mlx_array arr);
```

--------------------------------

### Create Custom Writer

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Initializes a new custom writer using a user-provided descriptor and a virtual table of I/O operations. The descriptor is passed to all vtable functions.

```c
mlx_io_writer mlx_io_writer_new(void* desc, mlx_io_vtable vtable)
```

--------------------------------

### Get GGUF Array Keys

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves all keys that correspond to arrays within the GGUF file. The keys are stored in a vector of strings.

```c
int mlx_io_gguf_get_keys(mlx_vector_string* keys, mlx_io_gguf io)
```

--------------------------------

### Get Default GPU Stream

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/stream.md

Retrieves a handle to the default GPU stream. This stream is used for operations when no specific stream is provided.

```c
// Get the default GPU stream
mx_stream gpu_stream = mlx_default_gpu_stream_new();
// Perform operations with it
// ...
mx_stream_free(gpu_stream);
```

--------------------------------

### Creating Streams for Asynchronous Execution

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/README.md

Demonstrates how to create different types of streams for asynchronous operations in MLX C: default CPU stream, a GPU stream, and a custom stream tied to a specific device.

```c
mlx_stream cpu_stream = mlx_default_cpu_stream_new();
ilx_stream gpu_stream = mlx_device_new_type(MLX_GPU, 0);
ilx_stream custom_stream = mlx_stream_new_device(my_device);
```

--------------------------------

### Create an empty vector of strings

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Initializes a new, empty vector to store strings.

```c
typedef struct mlx_vector_string_ {
  void* ctx;
} mlx_vector_string;

mix_vector_string mlx_vector_string_new(void);
```

--------------------------------

### MLX Stream for Asynchronous Execution

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Demonstrates the creation and usage of MLX streams for managing asynchronous operations and synchronization.

```c
mlx_stream stream = mlx_default_cpu_stream_new();
mix_add(&result, a, b, stream);  // Operations use stream
mix_synchronize(stream);         // Wait for completion
mix_stream_free(stream);
```

--------------------------------

### Iterating Through MLX Maps

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Demonstrates how to iterate over the key-value pairs in a string-to-array map using an iterator, and how to free the iterator.

```c
mlx_map_string_to_array_iterator it = mlx_map_string_to_array_iterator_new(map);
const char* key;
mix_array value;
while (mlx_map_string_to_array_iterator_next(&key, &value, it) == 0) {
  printf("%s: ...\n", key);
}
mix_map_string_to_array_iterator_free(it);
```

--------------------------------

### Get mlx_string data pointer

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Retrieves a pointer to the null-terminated string data. The returned pointer is valid as long as the string is not freed or modified.

```c
const char* mlx_string_data(mlx_string str);
```

--------------------------------

### mlx_distributed_init

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Initializes the distributed computing backend, with options for strict error checking and backend specification.

```APIDOC
## mlx_distributed_init

### Description
Initialize distributed backend.

### Parameters
#### Path Parameters
- **res** (mlx_distributed_group*) - Required - Output group handle
- **strict** (bool) - Required - Enable strict error checking
- **bk** (const char*) - Optional - Backend name (NULL for auto-detection)

### Return
`int` — Status code (0 for success).
```

--------------------------------

### Basic MLX C Array Operations

Source: https://github.com/ml-explore/mlx-c/blob/main/docs/src/overview.md

Demonstrates the creation, manipulation, and freeing of MLX C arrays and streams. Remember to free all allocated objects.

```c
mlx_stream stream = mlx_default_gpu_stream_new();
lmxlx_array a = mlx_array_new_float(1.0);
lmxlx_array b = mlx_array_new_float(1.0);
lmxlx_array_add(&b, a, b, stream); // b now holds a+b=2
lmxlx_array_add(&b, a, b, stream); // b now holds 3
lmxlx_array_set(&a, b); // a now holds 3 too
lmxlx_array_free(a);
lmxlx_array_free(b);
```

--------------------------------

### Load Array from File (NPY, NPZ, SafeTensors)

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Use this function to load a single MLX array from a file. Supported formats include .npy, .npz, and .safetensors. Ensure a default CPU stream is available for computation.

```c
mlx_array arr;
mlx_stream stream = mlx_default_cpu_stream_new();
ilx_load(&arr, "data.npy", stream);
// Use arr...
ilx_array_free(arr);
ilx_stream_free(stream);
```

--------------------------------

### Get value from string-to-string map

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Retrieves the string value associated with a given key from the string-to-string map. This function is similar to mlx_map_string_to_array_get but for string values.

```c
typedef struct mlx_map_string_to_string_ {
  void* ctx;
} mlx_map_string_to_string;

int mlx_map_string_to_string_get(char** value, const mlx_map_string_to_string map, const char* key);
```

--------------------------------

### mlx_metal_start_capture

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Initiates Metal frame capture for performance profiling, saving the capture data to the specified path.

```APIDOC
## mlx_metal_start_capture

### Description
Start Metal frame capture for profiling.

### Parameters
#### Path Parameters
- **path** (const char*) - Required - Output path for capture file

### Return
`int` — Status code (0 for success).
```

--------------------------------

### Get GGUF Metadata Array

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves an array value from the GGUF metadata associated with a given key. The array is stored in the provided mlx_array pointer.

```c
int mlx_io_gguf_get_metadata_array(mlx_array* arr, mlx_io_gguf io, const char* key)
```

--------------------------------

### Build Float64 Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet demonstrates building a C executable specifically for float64 precision and linking it with the mlxc library. Use this when float64 precision is critical.

```cmake
add_executable(example-float64 ${CMAKE_CURRENT_LIST_DIR}/example-float64.c)
target_link_libraries(example-float64 PUBLIC mlxc)
```

--------------------------------

### Get GGUF Metadata String

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves a string value from the GGUF metadata associated with a given key. The string is stored in the provided mlx_string pointer.

```c
int mlx_io_gguf_get_metadata_string(mlx_string* str, mlx_io_gguf io, const char* key)
```

--------------------------------

### mlx_device_new

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Creates a new, empty device object. This handle can be populated later or used as a placeholder.

```APIDOC
## mlx_device_new

### Description
Create a new empty device object.

### Return
`mlx_device` — An empty device handle.

```

--------------------------------

### Get GGUF Array by Key

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves an array from the GGUF object associated with a specific key. The array data is populated into the provided mlx_array pointer.

```c
int mlx_io_gguf_get_array(mlx_array* arr, mlx_io_gguf io, const char* key)
```

--------------------------------

### Create Custom Reader

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Initializes a new custom reader using a user-provided descriptor and a virtual table of I/O operations. The descriptor is passed to all vtable functions.

```c
mlx_io_reader mlx_io_reader_new(void* desc, mlx_io_vtable vtable)
```

--------------------------------

### MLX Operations Pipeline

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/README.md

Illustrates building a computation graph lazily, evaluating it, and then accessing the result. Remember to free allocated resources.

```c
mlx_stream stream = mlx_default_cpu_stream_new();

// Build computation graph (lazy)
ilx_array x = ...;
ilx_array y;
ilx_multiply(&y, x, x, stream);  // y = x * x
ilx_add(&y, y, x, stream);        // y = y + x (updates y)

// Evaluate
ilx_array_eval(y);

// Use result
float result;
ilx_array_item_float32(&result, y);

// Cleanup
ilx_array_free(x);
ilx_array_free(y);
ilx_stream_free(stream);
```

--------------------------------

### Get Rank in Distributed Group

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Returns the rank (process ID) of the current process within the specified distributed group. Rank 0 is the first process.

```c
int mlx_distributed_group_rank(mlx_distributed_group group);
```

--------------------------------

### Create and Free an Empty MLX Array

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Demonstrates the basic creation of an empty MLX array using `mlx_array_new` and its subsequent deallocation with `mlx_array_free`.

```c
mlx_array arr = mlx_array_new();
mlx_array_free(arr);
```

--------------------------------

### Format C/C++ Files with clang-format

Source: https://github.com/ml-explore/mlx-c/blob/main/CONTRIBUTING.md

Manually format C and C++ files using clang-format. Use the '-i' flag to modify files in place.

```bash
clang-format -i file.cpp
clang-format -i file.c
```

--------------------------------

### Get GGUF Metadata Vector of Strings

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Retrieves a vector of strings from the GGUF metadata associated with a given key. The vector is stored in the provided mlx_vector_string pointer.

```c
int mlx_io_gguf_get_metadata_vector_string(mlx_vector_string* vstr, mlx_io_gguf io, const char* key)
```

--------------------------------

### Device Type Enumeration

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Enumerates the possible types of devices, including CPU and GPU.

```c
typedef enum mlx_device_type_ {
  MLX_CPU,
  MLX_GPU
} mlx_device_type;
```

--------------------------------

### mlx_device_info_get

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Populates a device info object with data from a given device.

```APIDOC
## mlx_device_info_get

### Description
Populate device info from a device.

### Parameters
#### Path Parameters
- info (mlx_device_info*) - Output info object
- dev (mlx_device) - Device to query

### Return
`int` — Status code (0 for success).

### Example
```c
mix_device dev = mlx_device_new();
mix_get_default_device(&dev);
mix_device_info info = mlx_device_info_new();
mix_device_info_get(&info, dev);
// Access device properties via the info object
mix_device_info_free(info);
```
```

--------------------------------

### Cholesky Decomposition

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/linalg-and-random.md

Computes the Cholesky decomposition of a positive definite matrix. Specify 'upper' to get an upper triangular matrix, otherwise a lower triangular matrix is returned.

```c
int mlx_linalg_cholesky(mlx_array* res, const mlx_array a, bool upper, const mlx_stream s);
```

--------------------------------

### Build MLX C with CMake

Source: https://github.com/ml-explore/mlx-c/blob/main/README.md

Build the MLX C project using CMake. This command configures the build with a Release build type and then compiles the project.

```shell
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
```

--------------------------------

### Create MLX Array from Data Buffer

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Demonstrates creating an MLX array by copying data from a provided buffer. Requires specifying the data pointer, shape, dimensions, and datatype.

```c
float data[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0};
int shape[] = {2, 3};
mlx_array arr = mlx_array_new_data(data, shape, 2, MLX_FLOAT32);
```

--------------------------------

### Get String Value from Device Info

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Retrieves a string value associated with a given key from the device info object. Handles cases where the key might not exist or is not a string.

```c
const char* device_name = NULL;
mx_device_info_get_string(&device_name, info, "device_name");
printf("Device: %s\n", device_name);
```

--------------------------------

### Generate FFT Frequency Grids (C)

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/linalg-and-random.md

Generates frequency grids for FFT operations. Requires the number of samples and sample spacing.

```c
int mlx_fft_fftfreq(mlx_array* res, int n, double d, const mlx_stream s);
int mlx_fft_rfftfreq(mlx_array* res, int n, double d, const mlx_stream s);
```

--------------------------------

### Get value by key from string-to-array map

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Retrieves the array value associated with a given string key from the map. The output array is stored in the provided pointer. Returns 0 on success.

```c
typedef struct mlx_map_string_to_array_ {
  void* ctx;
} mlx_map_string_to_array;

typedef struct mlx_array_ {
  void* ctx;
} mlx_array;

int mlx_map_string_to_array_get(mlx_array* value, const mlx_map_string_to_array map, const char* key);
```

--------------------------------

### Gather Elements using Indices in C

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Selects elements from an array based on provided indices. This example shows gathering single elements using a vector of indices along a specified axis.

```c
// Gather elements at indices
ilx_array indices = mlx_array_new_int(5);
ilx_array gathered;
int slice_sizes[] = {1};
ilx_gather_single(&gathered, arr, indices, 0, slice_sizes, 1, stream);
```

--------------------------------

### Create new empty mlx_vector_int

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Initializes an empty vector for storing integers.

```c
mlx_vector_int mlx_vector_int_new(void);
```

--------------------------------

### Create New Empty Closure

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/closures.md

Creates a new, empty closure handle. This is the most basic way to initialize a closure.

```c
mlx_closure cls = mlx_closure_new();
```

--------------------------------

### Create MLX Array from Managed Data Buffer

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Shows how to create an MLX array from a data buffer where MLX takes ownership and uses a provided destructor callback (e.g., `free`) to release the data when the array is freed.

```c
float* data = malloc(6 * sizeof(float));
for (int i = 0; i < 6; i++) data[i] = (float)i;
int shape[] = {2, 3};
mlx_array arr = mlx_array_new_data_managed(data, shape, 2, MLX_FLOAT32, free);
```

--------------------------------

### Build Safe Tensors Executable with MLX C Library

Source: https://github.com/ml-explore/mlx-c/blob/main/examples/CMakeLists.txt

This snippet demonstrates building a C executable for handling safe tensors and linking it with the mlxc library. Use this for serialization/deserialization of ML models.

```cmake
add_executable(example-safe-tensors
               ${CMAKE_CURRENT_LIST_DIR}/example-safe-tensors.c)
target_link_libraries(example-safe-tensors PUBLIC mlxc)
```

--------------------------------

### Check Device Availability and Fallback

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Checks if a specific GPU device is available. If not, it suggests falling back to the CPU.

```c
mlx_device gpu = mlx_device_new_type(MLX_GPU, 0);
bool available;
mlx_device_is_available(&available, gpu);
if (!available) {
  // Fall back to CPU
}
```

--------------------------------

### Compute Value and Gradient in C

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Define a function, create a closure, and compute its value and gradient with respect to specified arguments. Ensure necessary MLX types and streams are initialized.

```c
// Define function to differentiate
int loss_fn(mlx_vector_array* outputs, const mlx_vector_array inputs) {
  mlx_array x;
  mlx_vector_array_get(&x, inputs, 0);
  mlx_array x2;
  mlx_multiply(&x2, x, x, stream);
  mlx_vector_array_append_value(*outputs, x2);
  return 0;
}

// Create closures
ilx_closure fun = mlx_closure_new_func(loss_fn);
int argnums[] = {0};
ilx_closure_value_and_grad grad_fn;
ilx_value_and_grad(&grad_fn, fun, argnums, 1);

// Compute
ilx_vector_array inputs = mlx_vector_array_new_value(x_value);
ilx_vector_array values, grads;
ilx_closure_value_and_grad_apply(&values, &grads, grad_fn, inputs);
```

--------------------------------

### Global Empty Array Instance

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Provides a static, globally accessible empty array instance. Use this for initialization purposes.

```c
static mlx_array mlx_array_empty;
```

--------------------------------

### mlx_dtype

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/types.md

Enumeration for array element datatypes. It defines various numerical and boolean types supported by MLX arrays, including integers, floats, and complex numbers. A helper function `mlx_dtype_size` is available to get the size in bytes for each dtype.

```APIDOC
## mlx_dtype

### Description
Array element datatype enumeration.

### Enum Definition
```c
typedef enum mlx_dtype_ {
  MLX_BOOL,
  MLX_UINT8,
  MLX_UINT16,
  MLX_UINT32,
  MLX_UINT64,
  MLX_INT8,
  MLX_INT16,
  MLX_INT32,
  MLX_INT64,
  MLX_FLOAT16,      // Requires HAS_FLOAT16 (ARM/Apple Silicon)
  MLX_FLOAT32,
  MLX_FLOAT64,
  MLX_BFLOAT16,     // Requires HAS_BFLOAT16 (ARM/Apple Silicon)
  MLX_COMPLEX64,
} mlx_dtype;
```

### Query function
- `size_t mlx_dtype_size(mlx_dtype dtype)` — Returns size in bytes
```

--------------------------------

### Generate Bernoulli Samples (C)

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/linalg-and-random.md

Generates Bernoulli (0 or 1) random samples. Requires the probability of generating a 1.

```c
int mlx_random_bernoulli(mlx_array* res, const mlx_array p,
                         const int* shape, size_t shape_num,
                         const mlx_array key, const mlx_stream s);
```

--------------------------------

### Check Metal GPU Support Availability

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/memory-and-utilities.md

Checks if the Metal GPU acceleration framework is available on the system. The result is stored in the provided boolean pointer.

```c
int mlx_metal_is_available(bool* res);
```

--------------------------------

### MLX Default Device Management

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/QUICK-START.md

Shows how to obtain and check the availability of the default MLX device.

```c
mlx_device dev = mlx_device_new();
mix_get_default_device(&dev);
mix_device_is_available(&available, dev);
```

--------------------------------

### Create mlx_closure_value_and_grad with function

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/closures.md

Creates a closure for computing both value and gradients using a provided function. The function must match the specified signature.

```c
mlx_closure_value_and_grad mlx_closure_value_and_grad_new_func(int (*fun)(mlx_vector_array*, mlx_vector_array*, const mlx_vector_array));
```

--------------------------------

### mlx_device_info_get_keys

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Retrieves all available keys present in the device information object.

```APIDOC
## mlx_device_info_get_keys

### Description
Get all available keys in device info.

### Parameters
#### Path Parameters
- keys (mlx_vector_string*) - Output vector of key strings
- info (mlx_device_info) - Device info object

### Return
`int` — Status code (0 for success).

### Common Keys
- `device_name` (string): Name of the device
- `architecture` (string): Architecture identifier
- Other platform-specific keys may be present

### Example
```c
mix_vector_string keys = mlx_vector_string_new();
mix_device_info_get_keys(&keys, info);
size_t num_keys = mlx_vector_string_size(keys);
for (size_t i = 0; i < num_keys; i++) {
  char* key = NULL;
  mlx_vector_string_get(&key, keys, i);
  printf("Key: %s\n", key);
}
mix_vector_string_free(keys);
```
```

--------------------------------

### Metal Kernel Configuration

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/types.md

Defines a configuration structure for custom Metal kernels, containing a context pointer.

```c
typedef struct mlx_fast_metal_kernel_config_ {
  void* ctx;
} mlx_fast_metal_kernel_config;
```

--------------------------------

### Create Empty GGUF Object

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/io-and-serialization.md

Creates and initializes an empty GGUF object. This is typically the first step before loading or manipulating GGUF data.

```c
mlx_io_gguf mlx_io_gguf_new(void)
```

--------------------------------

### Create MLX Array from Managed Data with Payload

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/array.md

Demonstrates creating an MLX array from a data buffer with a custom destructor that accepts a payload. This allows for more complex resource management.

```c
void* custom_dtor(void* payload) { /* custom cleanup */ return NULL; }
float* data = malloc(6 * sizeof(float));
for (int i = 0; i < 6; i++) data[i] = (float)i;
int shape[] = {2, 3};
mlx_array arr = mlx_array_new_data_managed_payload(data, shape, 2, MLX_FLOAT32, NULL, custom_dtor);
```

--------------------------------

### Basic FFT Operations (C)

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/linalg-and-random.md

Performs 1D Fast Fourier Transform (FFT), inverse FFT, real FFT, and inverse real FFT. Allows specifying FFT size and axis.

```c
int mlx_fft_fft(mlx_array* res, const mlx_array a, int n, int axis, mlx_fft_norm norm, const mlx_stream s);
int mlx_fft_ifft(mlx_array* res, const mlx_array a, int n, int axis, mlx_fft_norm norm, const mlx_stream s);
int mlx_fft_rfft(mlx_array* res, const mlx_array a, int n, int axis, mlx_fft_norm norm, const mlx_stream s);
int mlx_fft_irfft(mlx_array* res, const mlx_array a, int n, int axis, mlx_fft_norm norm, const mlx_stream s);
```

--------------------------------

### Create new empty mlx_vector_vector_array

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Initializes an empty vector designed to hold other vectors of arrays.

```c
mlx_vector_vector_array mlx_vector_vector_array_new(void);
```

--------------------------------

### mlx_device_info_new

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Creates a new, empty device information object. This object can be populated with key-value pairs to store device-specific metadata.

```APIDOC
## mlx_device_info_new

### Description
Create a new empty device info object.

### Return
`mlx_device_info` — An empty device info handle.

```

--------------------------------

### Enable Gradient Checkpointing

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/transforms.md

Use mlx_checkpoint to enable gradient checkpointing for a given function. This reduces memory usage during backpropagation by recomputing intermediate values instead of storing them, at the cost of slightly increased computation time.

```c
mlx_closure fun = mlx_closure_new_func(expensive_forward);
lmxlx_closure checkpoint_fn;
lmxlx_checkpoint(&checkpoint_fn, fun);

// Use checkpoint_fn for gradient computation
// Memory usage is reduced but computation is slightly slower
```

--------------------------------

### Create new empty mlx_vector_array

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/data-structures.md

Initializes an empty vector capable of storing mlx_array elements.

```c
mlx_vector_array mlx_vector_array_new(void);
```

--------------------------------

### Count Available GPUs

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/device.md

Retrieves and prints the number of available GPU devices on the system.

```c
int gpu_count;
mlx_device_count(&gpu_count, MLX_GPU);
printf("Available GPUs: %d\n", gpu_count);
```

--------------------------------

### mlx_default_cpu_stream_new

Source: https://github.com/ml-explore/mlx-c/blob/main/_autodocs/api-reference/stream.md

Creates and returns a handle to the current default CPU stream.

```APIDOC
## mlx_default_cpu_stream_new

### Description
Create and return the current default CPU stream.

### Return
`mlx_stream` — The default CPU stream.

### Note
Creates a new handle to the default stream; free with `mlx_stream_free()`.

```