{
"title": "square",
"category": "math/signal",
"keywords": [
"square",
"waveform",
"signal processing",
"duty cycle",
"periodic",
"elementwise"
],
"summary": "Generate a periodic square wave with optional duty cycle.",
"references": [],
"gpu_support": {
"elementwise": true,
"reduction": false,
"precisions": [
"f64"
],
"broadcasting": "elementwise",
"notes": "GPU inputs are gathered to the host so the reference implementation can guarantee MATLAB-compatible half-open duty-cycle semantics at the period boundary."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 1,
"constants": "inline",
"notes": "Fusion is intentionally disabled for v1 because the duty-cycle comparison is cheap on the host and would not materially benefit from kernel fusion."
},
"requires_feature": null,
"tested": {
"unit": "builtins::math::signal::square::tests",
"integration": null
},
"description": "`y = square(t)` generates a square wave with period `2*pi` at the sample times in `t`, with values in `{-1, +1}`. `y = square(t, duty)` accepts an explicit duty cycle as a percentage in `[0, 100]`: the output is `+1` over the first `duty/100 * 2*pi` of every period and `-1` for the remainder. The default duty cycle is 50% so that `square` produces the standard symmetric square wave.",
"behaviors": [
"Operates element-wise on scalars, vectors, matrices, and N-D tensors; preserves input shape.",
"Reduces input modulo `2*pi` so the waveform is periodic across negative and positive sample times.",
"Uses half-open interval semantics: `+1` for `phi/(2*pi) < duty/100`, `-1` otherwise.",
"`duty = 0` produces a constant `-1` waveform; `duty = 100` produces a constant `+1` waveform.",
"Integer and logical inputs are promoted to double precision before evaluation.",
"Non-finite sample times (`NaN`, `+Inf`, `-Inf`) propagate as `NaN` element-wise, matching MATLAB.",
"Complex and text inputs are rejected with a builtin-scoped error.",
"Rejects `duty` values outside `[0, 100]` and non-scalar `duty` arguments."
],
"examples": [
{
"description": "Default 50% duty cycle square wave",
"input": "t = 0:pi/4:2*pi;\ny = square(t)",
"output": "y = [1 1 1 1 -1 -1 -1 -1 1]"
},
{
"description": "25% duty cycle square wave",
"input": "t = 0:pi/4:2*pi;\ny = square(t, 25)",
"output": "y = [1 1 -1 -1 -1 -1 -1 -1 1]"
},
{
"description": "Constant outputs at the boundaries",
"input": "y = square([0 pi 2*pi], 100)",
"output": "y = [1 1 1]"
}
],
"faqs": [
{
"question": "What happens exactly at the duty-cycle boundary?",
"answer": "RunMat uses half-open semantics: the boundary phase belongs to the negative half. With the default 50% duty cycle, `square(pi)` returns `-1`. This matches MATLAB's documented behaviour."
},
{
"question": "How do I produce a constant `+1` or `-1`?",
"answer": "Pass `duty = 100` for a constant `+1` waveform and `duty = 0` for a constant `-1` waveform."
},
{
"question": "Can `square` accept complex inputs?",
"answer": "No. `square` is defined on real samples and rejects complex inputs with a builtin-scoped error to match MATLAB."
}
],
"links": [
{
"label": "sawtooth",
"url": "./sawtooth"
},
{
"label": "sin",
"url": "./sin"
},
{
"label": "cos",
"url": "./cos"
},
{
"label": "linspace",
"url": "./linspace"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/math/signal/square.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/signal/square.rs"
}
}