{
"title": "ones",
"category": "array/creation",
"keywords": [
"ones",
"array",
"logical",
"gpu",
"like"
],
"summary": "Create arrays filled with ones within the MATLAB language.",
"references": [],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"f32",
"f64"
],
"broadcasting": "none",
"notes": "Uses provider one-allocation hooks when available; otherwise fills via scalar add or uploads from the host."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 0,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::array::ones::tests",
"integration": "builtins::array::ones::tests::ones_gpu_like_alloc"
},
"description": "`ones` creates arrays filled with ones. RunMat mirrors MATLAB semantics across the scalar, vector, matrix, and N-D forms, including `'like'` and `'logical'` options.",
"behaviors": [
"`ones()` returns the scalar `1`.",
"`ones(n)` returns an `n × n` double array.",
"`ones(m, n, ...)` returns a dense double array with the requested dimensions.",
"`ones(sz)` accepts a size vector (row or column) and returns an array with `prod(sz)` elements arranged using MATLAB column-major ordering.",
"`ones(A)` returns an array of ones with the same size (and device residency) as `A`.",
"`ones(___, 'logical')` returns a logical array instead of double precision (all elements set to `true`).",
"`ones(___, 'like', prototype)` matches the device residency and numeric/logical flavour of `prototype`."
],
"examples": [
{
"description": "Creating a 3x3 matrix of ones",
"input": "B = ones(3)",
"output": "B = [1 1 1; 1 1 1; 1 1 1]"
},
{
"description": "Creating a 4x1 logical matrix of ones",
"input": "mask = ones(4, 1, 'logical')",
"output": "mask = [1 1 1 1]"
},
{
"description": "Creating a 64x64 matrix of ones on a GPU",
"input": "H = ones(64, 64)",
"output": "H = [1 1 1 ... 1; 1 1 1 ... 1; ...; 1 1 1 ... 1]"
}
],
"faqs": [
{
"question": "When should I use the `ones` function?",
"answer": "Use `ones` whenever you need to create arrays pre-filled with the value `1`, such as for initializing weights, creating masks, or testing other algorithms. Preallocating with `ones` ensures correct type and shape throughout your code and helps prevent bugs caused by uninitialized arrays."
},
{
"question": "Does `ones` produce double arrays by default?",
"answer": "Yes, by default, `ones` 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 `ones(n)` return?",
"answer": "`ones(n)` returns an `n × n` dense double-precision matrix filled with ones. For example, `ones(3)` yields a 3-by-3 matrix of all ones."
},
{
"question": "How do I create a logical array of ones?",
"answer": "Pass `'logical'` as the last argument:\n```matlab:runnable\nmask = ones(5, 1, 'logical');\n```\nThis produces a 5x1 logical array, i.e., all elements have value `true` (`1` 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 = ones(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 ones?",
"answer": "Yes! Pass more than two dimension arguments (or a size vector):\n```matlab:runnable\nT = ones(2, 3, 4);\n```\nThis creates a 2×3×4 tensor of ones."
},
{
"question": "How does `ones(A)` behave?",
"answer": "If you call `ones(A)`, where `A` is an array, the result is a new array of ones with the same shape as `A`."
},
{
"question": "Is the output always dense?",
"answer": "Yes. `ones` always produces a dense array. For sparse matrices of ones, use `sparse` with appropriate arguments."
},
{
"question": "What if I call `ones` with no arguments?",
"answer": "`ones()` returns the scalar value `1`."
},
{
"question": "Can I use `ones` to preallocate arrays for later assignment?",
"answer": "Absolutely. Preallocating with `ones` (or `zeros`) and then filling in values is a recommended practice for efficiency and code clarity when the final values are known to overwrite the initial ones."
}
],
"links": [
{
"label": "zeros",
"url": "./zeros"
},
{
"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/ones.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/creation/ones.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 `ones` 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 one-filled buffer. Acceleration providers that do not yet support the dedicated hooks fall back to zero-allocation plus scalar fill or, as a last resort, upload a host tensor. This guarantees correct behaviour."
]
}