From 184120ed12dfd7fc687edddac08171d9c2b1e148 Mon Sep 17 00:00:00 2001 From: Awni Hannun Date: Sat, 6 Jan 2024 05:41:48 -0800 Subject: [PATCH] docs up --- docs/build/html/_sources/index.rst | 7 +- docs/build/html/_sources/indexing.rst | 12 - .../python/_autosummary/mlx.nn.Module.rst | 59 -- .../mlx.nn.losses.smooth_l1_loss.rst | 8 - docs/build/html/_sources/usage/numpy.rst | 103 +++ .../html/_sources/{ => usage}/quick_start.rst | 0 .../_sources/{ => usage}/unified_memory.rst | 0 .../_sources/{ => usage}/using_streams.rst | 0 docs/build/html/cpp/ops.html | 7 +- docs/build/html/dev/extensions.html | 7 +- .../html/examples/linear_regression.html | 13 +- docs/build/html/examples/llama-inference.html | 7 +- docs/build/html/examples/mlp.html | 7 +- docs/build/html/genindex.html | 7 +- docs/build/html/index.html | 14 +- docs/build/html/indexing.html | 703 --------------- docs/build/html/install.html | 11 +- docs/build/html/objects.inv | Bin 6429 -> 6489 bytes .../python/_autosummary/mlx.core.Device.html | 7 +- .../python/_autosummary/mlx.core.Dtype.html | 7 +- .../python/_autosummary/mlx.core.Stream.html | 7 +- .../python/_autosummary/mlx.core.abs.html | 7 +- .../python/_autosummary/mlx.core.add.html | 7 +- .../python/_autosummary/mlx.core.all.html | 7 +- .../_autosummary/mlx.core.allclose.html | 7 +- .../python/_autosummary/mlx.core.any.html | 7 +- .../python/_autosummary/mlx.core.arange.html | 7 +- .../python/_autosummary/mlx.core.arccos.html | 7 +- .../python/_autosummary/mlx.core.arccosh.html | 7 +- .../python/_autosummary/mlx.core.arcsin.html | 7 +- .../python/_autosummary/mlx.core.arcsinh.html | 7 +- .../python/_autosummary/mlx.core.arctan.html | 7 +- .../python/_autosummary/mlx.core.arctanh.html | 7 +- .../python/_autosummary/mlx.core.argmax.html | 7 +- .../python/_autosummary/mlx.core.argmin.html | 7 +- .../_autosummary/mlx.core.argpartition.html | 7 +- .../python/_autosummary/mlx.core.argsort.html | 7 +- .../python/_autosummary/mlx.core.array.T.html | 7 +- .../_autosummary/mlx.core.array.abs.html | 7 +- .../_autosummary/mlx.core.array.all.html | 7 +- .../_autosummary/mlx.core.array.any.html | 7 +- .../_autosummary/mlx.core.array.argmax.html | 7 +- .../_autosummary/mlx.core.array.argmin.html | 7 +- .../_autosummary/mlx.core.array.astype.html | 7 +- .../_autosummary/mlx.core.array.cos.html | 7 +- .../_autosummary/mlx.core.array.dtype.html | 7 +- .../_autosummary/mlx.core.array.exp.html | 7 +- .../python/_autosummary/mlx.core.array.html | 7 +- .../_autosummary/mlx.core.array.item.html | 7 +- .../_autosummary/mlx.core.array.log.html | 7 +- .../_autosummary/mlx.core.array.log1p.html | 7 +- .../mlx.core.array.logsumexp.html | 7 +- .../_autosummary/mlx.core.array.max.html | 7 +- .../_autosummary/mlx.core.array.mean.html | 7 +- .../_autosummary/mlx.core.array.min.html | 7 +- .../_autosummary/mlx.core.array.ndim.html | 7 +- .../_autosummary/mlx.core.array.prod.html | 7 +- .../mlx.core.array.reciprocal.html | 7 +- .../_autosummary/mlx.core.array.reshape.html | 7 +- .../_autosummary/mlx.core.array.round.html | 7 +- .../_autosummary/mlx.core.array.rsqrt.html | 7 +- .../_autosummary/mlx.core.array.shape.html | 7 +- .../_autosummary/mlx.core.array.sin.html | 7 +- .../_autosummary/mlx.core.array.size.html | 7 +- .../_autosummary/mlx.core.array.split.html | 7 +- .../_autosummary/mlx.core.array.sqrt.html | 7 +- .../_autosummary/mlx.core.array.square.html | 7 +- .../_autosummary/mlx.core.array.sum.html | 7 +- .../_autosummary/mlx.core.array.tolist.html | 7 +- .../mlx.core.array.transpose.html | 7 +- .../_autosummary/mlx.core.array.var.html | 7 +- .../_autosummary/mlx.core.array_equal.html | 7 +- .../_autosummary/mlx.core.broadcast_to.html | 7 +- .../python/_autosummary/mlx.core.ceil.html | 7 +- .../python/_autosummary/mlx.core.clip.html | 7 +- .../_autosummary/mlx.core.concatenate.html | 7 +- .../python/_autosummary/mlx.core.conv1d.html | 7 +- .../python/_autosummary/mlx.core.conv2d.html | 7 +- .../_autosummary/mlx.core.convolve.html | 7 +- .../python/_autosummary/mlx.core.cos.html | 7 +- .../python/_autosummary/mlx.core.cosh.html | 7 +- .../_autosummary/mlx.core.default_device.html | 7 +- .../_autosummary/mlx.core.default_stream.html | 7 +- .../_autosummary/mlx.core.dequantize.html | 7 +- .../python/_autosummary/mlx.core.divide.html | 7 +- .../python/_autosummary/mlx.core.equal.html | 7 +- .../python/_autosummary/mlx.core.erf.html | 7 +- .../python/_autosummary/mlx.core.erfinv.html | 7 +- .../python/_autosummary/mlx.core.eval.html | 7 +- .../python/_autosummary/mlx.core.exp.html | 7 +- .../_autosummary/mlx.core.expand_dims.html | 7 +- .../python/_autosummary/mlx.core.eye.html | 9 +- .../python/_autosummary/mlx.core.fft.fft.html | 7 +- .../_autosummary/mlx.core.fft.fft2.html | 7 +- .../_autosummary/mlx.core.fft.fftn.html | 7 +- .../_autosummary/mlx.core.fft.ifft.html | 7 +- .../_autosummary/mlx.core.fft.ifft2.html | 7 +- .../_autosummary/mlx.core.fft.ifftn.html | 7 +- .../_autosummary/mlx.core.fft.irfft.html | 7 +- .../_autosummary/mlx.core.fft.irfft2.html | 7 +- .../_autosummary/mlx.core.fft.irfftn.html | 7 +- .../_autosummary/mlx.core.fft.rfft.html | 7 +- .../_autosummary/mlx.core.fft.rfft2.html | 7 +- .../_autosummary/mlx.core.fft.rfftn.html | 7 +- .../python/_autosummary/mlx.core.flatten.html | 7 +- .../python/_autosummary/mlx.core.floor.html | 7 +- .../_autosummary/mlx.core.floor_divide.html | 7 +- .../python/_autosummary/mlx.core.full.html | 7 +- .../python/_autosummary/mlx.core.grad.html | 7 +- .../python/_autosummary/mlx.core.greater.html | 7 +- .../_autosummary/mlx.core.greater_equal.html | 7 +- .../_autosummary/mlx.core.identity.html | 9 +- .../python/_autosummary/mlx.core.jvp.html | 7 +- .../python/_autosummary/mlx.core.less.html | 7 +- .../_autosummary/mlx.core.less_equal.html | 7 +- .../_autosummary/mlx.core.linalg.norm.html | 7 +- .../_autosummary/mlx.core.linspace.html | 7 +- .../python/_autosummary/mlx.core.load.html | 7 +- .../python/_autosummary/mlx.core.log.html | 7 +- .../python/_autosummary/mlx.core.log10.html | 7 +- .../python/_autosummary/mlx.core.log1p.html | 7 +- .../python/_autosummary/mlx.core.log2.html | 7 +- .../_autosummary/mlx.core.logaddexp.html | 7 +- .../_autosummary/mlx.core.logical_not.html | 7 +- .../_autosummary/mlx.core.logsumexp.html | 7 +- .../python/_autosummary/mlx.core.matmul.html | 7 +- .../python/_autosummary/mlx.core.max.html | 7 +- .../python/_autosummary/mlx.core.maximum.html | 7 +- .../python/_autosummary/mlx.core.mean.html | 7 +- .../python/_autosummary/mlx.core.min.html | 7 +- .../python/_autosummary/mlx.core.minimum.html | 7 +- .../_autosummary/mlx.core.moveaxis.html | 7 +- .../_autosummary/mlx.core.multiply.html | 7 +- .../_autosummary/mlx.core.negative.html | 7 +- .../_autosummary/mlx.core.new_stream.html | 7 +- .../python/_autosummary/mlx.core.ones.html | 9 +- .../_autosummary/mlx.core.ones_like.html | 7 +- .../python/_autosummary/mlx.core.pad.html | 7 +- .../_autosummary/mlx.core.partition.html | 7 +- .../python/_autosummary/mlx.core.prod.html | 7 +- .../_autosummary/mlx.core.quantize.html | 7 +- .../mlx.core.quantized_matmul.html | 7 +- .../mlx.core.random.bernoulli.html | 7 +- .../mlx.core.random.categorical.html | 7 +- .../_autosummary/mlx.core.random.gumbel.html | 9 +- .../_autosummary/mlx.core.random.key.html | 7 +- .../_autosummary/mlx.core.random.normal.html | 9 +- .../_autosummary/mlx.core.random.randint.html | 9 +- .../_autosummary/mlx.core.random.seed.html | 7 +- .../_autosummary/mlx.core.random.split.html | 7 +- .../mlx.core.random.truncated_normal.html | 9 +- .../_autosummary/mlx.core.random.uniform.html | 9 +- .../_autosummary/mlx.core.reciprocal.html | 7 +- .../python/_autosummary/mlx.core.repeat.html | 7 +- .../python/_autosummary/mlx.core.reshape.html | 7 +- .../python/_autosummary/mlx.core.round.html | 7 +- .../python/_autosummary/mlx.core.rsqrt.html | 7 +- .../python/_autosummary/mlx.core.save.html | 7 +- .../mlx.core.save_safetensors.html | 7 +- .../python/_autosummary/mlx.core.savez.html | 7 +- .../mlx.core.savez_compressed.html | 7 +- .../mlx.core.set_default_device.html | 7 +- .../mlx.core.set_default_stream.html | 7 +- .../python/_autosummary/mlx.core.sigmoid.html | 7 +- .../python/_autosummary/mlx.core.sign.html | 7 +- .../_autosummary/mlx.core.simplify.html | 7 +- .../python/_autosummary/mlx.core.sin.html | 7 +- .../python/_autosummary/mlx.core.sinh.html | 7 +- .../python/_autosummary/mlx.core.softmax.html | 7 +- .../python/_autosummary/mlx.core.sort.html | 7 +- .../python/_autosummary/mlx.core.split.html | 7 +- .../python/_autosummary/mlx.core.sqrt.html | 7 +- .../python/_autosummary/mlx.core.square.html | 7 +- .../python/_autosummary/mlx.core.squeeze.html | 7 +- .../python/_autosummary/mlx.core.stack.html | 7 +- .../_autosummary/mlx.core.stop_gradient.html | 7 +- .../_autosummary/mlx.core.subtract.html | 7 +- .../python/_autosummary/mlx.core.sum.html | 7 +- .../_autosummary/mlx.core.swapaxes.html | 7 +- .../python/_autosummary/mlx.core.take.html | 7 +- .../mlx.core.take_along_axis.html | 7 +- .../python/_autosummary/mlx.core.tan.html | 7 +- .../python/_autosummary/mlx.core.tanh.html | 7 +- .../_autosummary/mlx.core.tensordot.html | 7 +- .../_autosummary/mlx.core.transpose.html | 7 +- .../python/_autosummary/mlx.core.tri.html | 7 +- .../python/_autosummary/mlx.core.tril.html | 7 +- .../python/_autosummary/mlx.core.triu.html | 7 +- .../_autosummary/mlx.core.value_and_grad.html | 7 +- .../python/_autosummary/mlx.core.var.html | 7 +- .../python/_autosummary/mlx.core.vjp.html | 7 +- .../python/_autosummary/mlx.core.vmap.html | 7 +- .../python/_autosummary/mlx.core.where.html | 7 +- .../python/_autosummary/mlx.core.zeros.html | 9 +- .../_autosummary/mlx.core.zeros_like.html | 7 +- .../python/_autosummary/mlx.nn.Module.html | 844 ------------------ .../_autosummary/mlx.nn.value_and_grad.html | 7 +- .../_autosummary/mlx.optimizers.AdaDelta.html | 7 +- .../_autosummary/mlx.optimizers.Adagrad.html | 7 +- .../_autosummary/mlx.optimizers.Adam.html | 7 +- .../_autosummary/mlx.optimizers.AdamW.html | 7 +- .../_autosummary/mlx.optimizers.Adamax.html | 7 +- .../_autosummary/mlx.optimizers.Lion.html | 7 +- .../mlx.optimizers.Optimizer.html | 7 +- .../mlx.optimizers.OptimizerState.html | 7 +- .../_autosummary/mlx.optimizers.RMSprop.html | 7 +- .../_autosummary/mlx.optimizers.SGD.html | 7 +- .../_autosummary/mlx.utils.tree_flatten.html | 7 +- .../_autosummary/mlx.utils.tree_map.html | 7 +- .../mlx.utils.tree_unflatten.html | 7 +- .../mlx.nn.losses.smooth_l1_loss.html | 690 -------------- docs/build/html/python/array.html | 7 +- docs/build/html/python/data_types.html | 7 +- .../html/python/devices_and_streams.html | 7 +- docs/build/html/python/fft.html | 7 +- docs/build/html/python/linalg.html | 7 +- docs/build/html/python/nn.html | 7 +- .../python/nn/_autosummary/mlx.nn.ALiBi.html | 7 +- .../nn/_autosummary/mlx.nn.BatchNorm.html | 7 +- .../python/nn/_autosummary/mlx.nn.Conv1d.html | 7 +- .../python/nn/_autosummary/mlx.nn.Conv2d.html | 7 +- .../nn/_autosummary/mlx.nn.Dropout.html | 7 +- .../nn/_autosummary/mlx.nn.Dropout2d.html | 7 +- .../nn/_autosummary/mlx.nn.Dropout3d.html | 7 +- .../nn/_autosummary/mlx.nn.Embedding.html | 7 +- .../python/nn/_autosummary/mlx.nn.GELU.html | 7 +- .../nn/_autosummary/mlx.nn.GroupNorm.html | 7 +- .../nn/_autosummary/mlx.nn.InstanceNorm.html | 7 +- .../nn/_autosummary/mlx.nn.LayerNorm.html | 7 +- .../python/nn/_autosummary/mlx.nn.Linear.html | 7 +- .../python/nn/_autosummary/mlx.nn.Mish.html | 7 +- .../nn/_autosummary/mlx.nn.Module.apply.html | 7 +- .../mlx.nn.Module.apply_to_modules.html | 7 +- .../_autosummary/mlx.nn.Module.children.html | 7 +- .../nn/_autosummary/mlx.nn.Module.eval.html | 7 +- .../mlx.nn.Module.filter_and_map.html | 7 +- .../nn/_autosummary/mlx.nn.Module.freeze.html | 7 +- .../mlx.nn.Module.leaf_modules.html | 7 +- .../mlx.nn.Module.load_weights.html | 7 +- .../_autosummary/mlx.nn.Module.modules.html | 7 +- .../mlx.nn.Module.named_modules.html | 7 +- .../mlx.nn.Module.parameters.html | 7 +- .../mlx.nn.Module.save_weights.html | 7 +- .../nn/_autosummary/mlx.nn.Module.train.html | 7 +- .../mlx.nn.Module.trainable_parameters.html | 7 +- .../_autosummary/mlx.nn.Module.training.html | 7 +- .../_autosummary/mlx.nn.Module.unfreeze.html | 7 +- .../nn/_autosummary/mlx.nn.Module.update.html | 7 +- .../mlx.nn.Module.update_modules.html | 7 +- .../mlx.nn.MultiHeadAttention.html | 7 +- .../python/nn/_autosummary/mlx.nn.PReLU.html | 7 +- .../_autosummary/mlx.nn.QuantizedLinear.html | 7 +- .../nn/_autosummary/mlx.nn.RMSNorm.html | 7 +- .../python/nn/_autosummary/mlx.nn.ReLU.html | 7 +- .../python/nn/_autosummary/mlx.nn.RoPE.html | 7 +- .../python/nn/_autosummary/mlx.nn.SELU.html | 7 +- .../nn/_autosummary/mlx.nn.Sequential.html | 7 +- .../python/nn/_autosummary/mlx.nn.SiLU.html | 7 +- .../mlx.nn.SinusoidalPositionalEncoding.html | 7 +- .../python/nn/_autosummary/mlx.nn.Step.html | 7 +- .../nn/_autosummary/mlx.nn.Transformer.html | 7 +- .../_autosummary_functions/mlx.nn.gelu.html | 7 +- .../mlx.nn.gelu_approx.html | 7 +- .../mlx.nn.gelu_fast_approx.html | 7 +- .../mlx.nn.losses.binary_cross_entropy.html | 7 +- .../mlx.nn.losses.cross_entropy.html | 7 +- .../mlx.nn.losses.hinge_loss.html | 7 +- .../mlx.nn.losses.huber_loss.html | 7 +- .../mlx.nn.losses.kl_div_loss.html | 7 +- .../mlx.nn.losses.l1_loss.html | 7 +- .../mlx.nn.losses.log_cosh_loss.html | 7 +- .../mlx.nn.losses.mse_loss.html | 7 +- .../mlx.nn.losses.nll_loss.html | 7 +- .../mlx.nn.losses.smooth_l1_loss.html | 7 +- .../mlx.nn.losses.triplet_loss.html | 7 +- .../_autosummary_functions/mlx.nn.mish.html | 7 +- .../_autosummary_functions/mlx.nn.prelu.html | 7 +- .../_autosummary_functions/mlx.nn.relu.html | 7 +- .../_autosummary_functions/mlx.nn.selu.html | 7 +- .../_autosummary_functions/mlx.nn.silu.html | 7 +- .../_autosummary_functions/mlx.nn.step.html | 7 +- docs/build/html/python/nn/functions.html | 7 +- docs/build/html/python/nn/layers.html | 7 +- docs/build/html/python/nn/losses.html | 7 +- docs/build/html/python/nn/module.html | 7 +- docs/build/html/python/ops.html | 7 +- docs/build/html/python/optimizers.html | 7 +- docs/build/html/python/random.html | 7 +- docs/build/html/python/transforms.html | 7 +- docs/build/html/python/tree_utils.html | 7 +- docs/build/html/quick_start.html | 799 ----------------- docs/build/html/search.html | 7 +- docs/build/html/searchindex.js | 2 +- docs/build/html/unified_memory.html | 801 ----------------- docs/build/html/usage/numpy.html | 834 +++++++++++++++++ docs/build/html/usage/quick_start.html | 800 +++++++++++++++++ docs/build/html/usage/unified_memory.html | 802 +++++++++++++++++ docs/build/html/usage/using_streams.html | 758 ++++++++++++++++ docs/build/html/using_streams.html | 757 ---------------- 299 files changed, 4436 insertions(+), 5531 deletions(-) delete mode 100644 docs/build/html/_sources/indexing.rst delete mode 100644 docs/build/html/_sources/python/_autosummary/mlx.nn.Module.rst delete mode 100644 docs/build/html/_sources/python/_autosummary_functions/mlx.nn.losses.smooth_l1_loss.rst create mode 100644 docs/build/html/_sources/usage/numpy.rst rename docs/build/html/_sources/{ => usage}/quick_start.rst (100%) rename docs/build/html/_sources/{ => usage}/unified_memory.rst (100%) rename docs/build/html/_sources/{ => usage}/using_streams.rst (100%) delete mode 100644 docs/build/html/indexing.html delete mode 100644 docs/build/html/python/_autosummary/mlx.nn.Module.html delete mode 100644 docs/build/html/python/_autosummary_functions/mlx.nn.losses.smooth_l1_loss.html delete mode 100644 docs/build/html/quick_start.html delete mode 100644 docs/build/html/unified_memory.html create mode 100644 docs/build/html/usage/numpy.html create mode 100644 docs/build/html/usage/quick_start.html create mode 100644 docs/build/html/usage/unified_memory.html create mode 100644 docs/build/html/usage/using_streams.html delete mode 100644 docs/build/html/using_streams.html diff --git a/docs/build/html/_sources/index.rst b/docs/build/html/_sources/index.rst index 9f0445a18..f1fe468ca 100644 --- a/docs/build/html/_sources/index.rst +++ b/docs/build/html/_sources/index.rst @@ -35,9 +35,10 @@ are the CPU and GPU. :caption: Usage :maxdepth: 1 - quick_start - unified_memory - using_streams + usage/quick_start + usage/unified_memory + usage/using_streams + usage/numpy .. toctree:: :caption: Examples diff --git a/docs/build/html/_sources/indexing.rst b/docs/build/html/_sources/indexing.rst deleted file mode 100644 index 093fb1f58..000000000 --- a/docs/build/html/_sources/indexing.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _indexing: - -Indexing Arrays -=============== - -.. currentmodule:: mlx.core - -For the most part, indexing an MLX :obj:`array` works the same as indexing a -NumPy :obj:`numpy.ndarray`. See the `NumPy documentation -`_ for more details on -how that works - diff --git a/docs/build/html/_sources/python/_autosummary/mlx.nn.Module.rst b/docs/build/html/_sources/python/_autosummary/mlx.nn.Module.rst deleted file mode 100644 index 8b28b3ac6..000000000 --- a/docs/build/html/_sources/python/_autosummary/mlx.nn.Module.rst +++ /dev/null @@ -1,59 +0,0 @@ -mlx.nn.Module -============= - -.. currentmodule:: mlx.nn - -.. autoclass:: Module - - - .. automethod:: __init__ - - - .. rubric:: Methods - - .. autosummary:: - - ~Module.__init__ - ~Module.apply - ~Module.apply_to_modules - ~Module.children - ~Module.clear - ~Module.copy - ~Module.eval - ~Module.filter_and_map - ~Module.freeze - ~Module.fromkeys - ~Module.get - ~Module.is_module - ~Module.items - ~Module.keys - ~Module.leaf_modules - ~Module.load_weights - ~Module.modules - ~Module.named_modules - ~Module.parameters - ~Module.pop - ~Module.popitem - ~Module.save_weights - ~Module.setdefault - ~Module.train - ~Module.trainable_parameter_filter - ~Module.trainable_parameters - ~Module.unfreeze - ~Module.update - ~Module.update_modules - ~Module.valid_child_filter - ~Module.valid_parameter_filter - ~Module.values - - - - - - .. rubric:: Attributes - - .. autosummary:: - - ~Module.training - - \ No newline at end of file diff --git a/docs/build/html/_sources/python/_autosummary_functions/mlx.nn.losses.smooth_l1_loss.rst b/docs/build/html/_sources/python/_autosummary_functions/mlx.nn.losses.smooth_l1_loss.rst deleted file mode 100644 index 00a647a75..000000000 --- a/docs/build/html/_sources/python/_autosummary_functions/mlx.nn.losses.smooth_l1_loss.rst +++ /dev/null @@ -1,8 +0,0 @@ -mlx.nn.losses.smooth\_l1\_loss -============================== - -.. currentmodule:: mlx.nn.losses - -.. autoclass:: smooth_l1_loss - - \ No newline at end of file diff --git a/docs/build/html/_sources/usage/numpy.rst b/docs/build/html/_sources/usage/numpy.rst new file mode 100644 index 000000000..ef075ad0c --- /dev/null +++ b/docs/build/html/_sources/usage/numpy.rst @@ -0,0 +1,103 @@ +.. _numpy: + +Conversion to NumPy and Other Frameworks +======================================== + +MLX array implements the `Python Buffer Protocol `_. +Let's convert an array to NumPy and back. + +.. code-block:: python + + import mlx.core as mx + import numpy as np + + a = mx.arange(3) + b = np.array(a) # copy of a + c = mx.array(b) # copy of b + +.. note:: + + Since NumPy does not support ``bfloat16`` arrays, you will need to convert to ``float16`` or ``float32`` first: + ``np.array(a.astype(mx.float32))``. + Otherwise, you will receive an error like: ``Item size 2 for PEP 3118 buffer format string does not match the dtype V item size 0.`` + +By default, NumPy copies data to a new array. This can be prevented by creating an array view: + +.. code-block:: python + + a = mx.arange(3) + a_view = np.array(a, copy=False) + print(a_view.flags.owndata) # False + a_view[0] = 1 + print(a[0].item()) # 1 + +A NumPy array view is a normal NumPy array, except that it does not own its memory. +This means writing to the view is reflected in the original array. + +While this is quite powerful to prevent copying arrays, it should be noted that external changes to the memory of arrays cannot be reflected in gradients. + +Let's demonstrate this in an example: + +.. code-block:: python + + def f(x): + x_view = np.array(x, copy=False) + x_view[:] *= x_view # modify memory without telling mx + return x.sum() + + x = mx.array([3.0]) + y, df = mx.value_and_grad(f)(x) + print("f(x) = x² =", y.item()) # 9.0 + print("f'(x) = 2x !=", df.item()) # 1.0 + + +The function ``f`` indirectly modifies the array ``x`` through a memory view. +However, this modification is not reflected in the gradient, as seen in the last line outputting ``1.0``, +representing the gradient of the sum operation alone. +The squaring of ``x`` occurs externally to MLX, meaning that no gradient is incorporated. +It's important to note that a similar issue arises during array conversion and copying. +For instance, a function defined as ``mx.array(np.array(x)**2).sum()`` would also result in an incorrect gradient, +even though no in-place operations on MLX memory are executed. + +PyTorch +------- + +PyTorch supports the buffer protocol, but it requires an explicit :obj:`memoryview`. + +.. code-block:: python + + import mlx.core as mx + import torch + + a = mx.arange(3) + b = torch.tensor(memoryview(a)) + c = mx.array(b.numpy()) + +Conversion from PyTorch tensors back to arrays must be done via intermediate NumPy arrays with ``numpy()``. + +JAX +--- +JAX fully supports the buffer protocol. + +.. code-block:: python + + import mlx.core as mx + import jax.numpy as jnp + + a = mx.arange(3) + b = jnp.array(a) + c = mx.array(b) + +TensorFlow +---------- + +TensorFlow supports the buffer protocol, but it requires an explicit :obj:`memoryview`. + +.. code-block:: python + + import mlx.core as mx + import tensorflow as tf + + a = mx.arange(3) + b = tf.constant(memoryview(a)) + c = mx.array(b) diff --git a/docs/build/html/_sources/quick_start.rst b/docs/build/html/_sources/usage/quick_start.rst similarity index 100% rename from docs/build/html/_sources/quick_start.rst rename to docs/build/html/_sources/usage/quick_start.rst diff --git a/docs/build/html/_sources/unified_memory.rst b/docs/build/html/_sources/usage/unified_memory.rst similarity index 100% rename from docs/build/html/_sources/unified_memory.rst rename to docs/build/html/_sources/usage/unified_memory.rst diff --git a/docs/build/html/_sources/using_streams.rst b/docs/build/html/_sources/usage/using_streams.rst similarity index 100% rename from docs/build/html/_sources/using_streams.rst rename to docs/build/html/_sources/usage/using_streams.rst diff --git a/docs/build/html/cpp/ops.html b/docs/build/html/cpp/ops.html index bf7b16533..dbce60725 100644 --- a/docs/build/html/cpp/ops.html +++ b/docs/build/html/cpp/ops.html @@ -147,9 +147,10 @@

Usage

Examples

    diff --git a/docs/build/html/dev/extensions.html b/docs/build/html/dev/extensions.html index e7ac596e4..bde17609a 100644 --- a/docs/build/html/dev/extensions.html +++ b/docs/build/html/dev/extensions.html @@ -146,9 +146,10 @@

Usage

Examples

    diff --git a/docs/build/html/examples/linear_regression.html b/docs/build/html/examples/linear_regression.html index ced953d14..5d2417057 100644 --- a/docs/build/html/examples/linear_regression.html +++ b/docs/build/html/examples/linear_regression.html @@ -47,7 +47,7 @@ - + @@ -147,9 +147,10 @@

Usage

Examples