{
"title": "zeros",
"category": "array/creation",
"keywords": [
"zeros",
"array",
"logical",
"gpu",
"like"
],
"summary": "Create arrays filled with zeros within the MATLAB language.",
"references": [],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"f32",
"f64"
],
"broadcasting": "none",
"notes": "Uses provider zero-allocation hooks when available; otherwise falls back to uploading a host tensor."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 0,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::array::zeros::tests",
"integration": "builtins::array::zeros::tests::zeros_gpu_like_alloc"
},
"description": "`zeros` creates arrays filled with zeros. RunMat mirrors MATLAB semantics across the scalar, vector, matrix, and N-D forms, including `'like'` and `'logical'` options.",
"behaviors": [
"`zeros()` returns the scalar `0`.",
"`zeros(n)` returns an `n × n` double array.",
"`zeros(m, n, ...)` returns a dense double array with the requested dimensions.",
"`zeros(sz)` accepts a size vector (row or column) and returns an array with `prod(sz)` elements arranged using MATLAB column-major ordering.",
"`zeros(A)` returns an array of zeros with the same size (and device residency) as `A`.",
"`zeros(___, 'logical')` returns a logical array instead of double precision.",
"`zeros(___, 'like', prototype)` matches the device residency and numeric/logical flavour of `prototype`."
],
"examples": [
{
"description": "Creating a 2x3 matrix of zeros",
"input": "A = zeros(2, 3)",
"output": "A = [0 0 0; 0 0 0]"
},
{
"description": "Creating a 4x1 logical matrix of zeros",
"input": "mask = zeros(4, 1, 'logical')",
"output": "mask = [0 0 0 0]"
},
{
"description": "Creating a 128x128 matrix of zeros on a GPU",
"input": "H = zeros(128, 128)",
"output": "H = [0 0 0 ... 0; 0 0 0 ... 0; ...; 0 0 0 ... 0]"
}
],
"faqs": [
{
"question": "When should I use the `zeros` function?",
"answer": "Use `zeros` whenever you need to create arrays pre-filled with the value `0`, such as for initializing weights, creating masks, or testing other algorithms. Preallocating with `zeros` ensures correct type and shape throughout your code and helps prevent bugs caused by uninitialized arrays."
},
{
"question": "Does `zeros` produce double arrays by default?",
"answer": "Yes, by default, `zeros` creates dense double-precision arrays unless you explicitly specify a type such as `'logical'` or use the `'like'` argument to match a prototype array."
},
{
"question": "What does `zeros(n)` return?",
"answer": "`zeros(n)` returns an `n × n` dense double-precision matrix filled with zeros. For example, `zeros(3)` yields a 3-by-3 matrix of all zeros."
},
{
"question": "How do I create a logical array of zeros?",
"answer": "Pass `'logical'` as the last argument:\n```matlab:runnable\nmask = zeros(5, 1, 'logical');\n```\nThis produces a 5x1 logical array, i.e., all elements have value `false` (`0` in binary)."
},
{
"question": "How do I match the type and device residency of an existing array?",
"answer": "Use the `'like', prototype` syntax:\n```matlab:runnable\nA = gpuArray(rand(2,2));\nB = zeros(2, 2, 'like', A);\n```\n`B` will be a GPU array with the same type and shape as `A`."
},
{
"question": "Can I create N-dimensional arrays with zeros?",
"answer": "Yes! Pass more than two dimension arguments (or a size vector):\n```matlab:runnable\nT = zeros(2, 3, 4);\n```\nThis creates a 2×3×4 tensor of zeros."
},
{
"question": "How does `zeros(A)` behave?",
"answer": "If you call `zeros(A)`, where `A` is an array, the result is a new array of zeros with the same shape as `A`."
},
{
"question": "Is the output always dense?",
"answer": "Yes. `zeros` always produces a dense array. For sparse matrices of zeros, use `sparse` with appropriate arguments."
},
{
"question": "What if I call `zeros` with no arguments?",
"answer": "`zeros()` returns the scalar value `0`."
},
{
"question": "Can I use `zeros` to preallocate arrays for later assignment?",
"answer": "Absolutely. Preallocating with `zeros` (or `ones`) and then filling in values is a recommended practice for efficiency and code clarity when the final values are known to overwrite the initial zeros."
}
],
"links": [
{
"label": "ones",
"url": "./ones"
},
{
"label": "eye",
"url": "./eye"
},
{
"label": "gpuArray",
"url": "./gpuarray"
},
{
"label": "gather",
"url": "./gather"
},
{
"label": "colon",
"url": "./colon"
},
{
"label": "false",
"url": "./false"
},
{
"label": "fill",
"url": "./fill"
},
{
"label": "linspace",
"url": "./linspace"
},
{
"label": "logspace",
"url": "./logspace"
},
{
"label": "magic",
"url": "./magic"
},
{
"label": "meshgrid",
"url": "./meshgrid"
},
{
"label": "rand",
"url": "./rand"
},
{
"label": "randi",
"url": "./randi"
},
{
"label": "randn",
"url": "./randn"
},
{
"label": "randperm",
"url": "./randperm"
},
{
"label": "range",
"url": "./range"
},
{
"label": "true",
"url": "./true"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/array/creation/zeros.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/zeros.rs"
},
"gpu_residency": "You usually do NOT need to call `gpuArray` yourself in RunMat (unlike MATLAB).\n\nIn RunMat, the fusion planner keeps residency on GPU in branches of fused expressions. As such, in the above example, the result of the `zeros` call will already be on the GPU when the fusion planner has detected a net benefit to operating the fused expression it is part of on the GPU.\n\nTo preserve backwards compatibility with MathWorks MATLAB, and for when you want to explicitly bootstrap GPU residency, you can call `gpuArray` explicitly to move data to the GPU if you want to be explicit about the residency.\n\nSince MathWorks MATLAB does not have a fusion planner, and they kept their parallel execution toolbox separate from the core language, as their toolbox is a separate commercial product, MathWorks MATLAB users need to call `gpuArray` to move data to the GPU manually whereas RunMat users can rely on the fusion planner to keep data on the GPU automatically.",
"gpu_behavior": [
"When the prototype or `'like'` argument is a GPU tensor, RunMat asks the active acceleration provider to allocate a zero-filled buffer in-place. Providers that do not yet support the zero allocation hooks automatically fall back to uploading a host zero tensor, guaranteeing correct behaviour at the cost of an extra transfer."
]
}