{
"title": "trapz",
"category": "math/reduction",
"keywords": [
"trapz",
"trapezoidal integration",
"numerical integration",
"discrete integration",
"gpu"
],
"summary": "Trapezoidal numerical integration of sampled data.",
"references": [],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [
"f32",
"f64"
],
"broadcasting": "matlab",
"notes": "GPU inputs currently gather to the host for trapezoidal integration and re-upload real-valued outputs so downstream code can remain device-resident."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 2,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::math::reduction::trapz::tests"
},
"description": "`trapz(Y)` approximates the integral of sampled data in `Y` using the trapezoidal rule. The integration runs along the first non-singleton dimension unless you specify a different dimension explicitly.",
"behaviors": [
"`trapz(Y)` assumes unit spacing between adjacent samples.",
"`trapz(X, Y)` accepts a scalar spacing, a vector of coordinates whose length matches the working dimension, or an array `X` with the same size as `Y`.",
"`trapz(..., dim)` selects the working dimension explicitly. Dimensions larger than `ndims(Y)` behave like singleton axes, so the result is zero along those slices.",
"Logical inputs are promoted to double precision before integration. Complex-valued `Y` inputs are integrated component-wise and preserve their complex output type.",
"When the selected dimension has length 0 or 1, `trapz` returns zeros because there are no intervals to integrate."
],
"examples": [
{
"description": "Integrating sampled sine data with explicit coordinates",
"input": "x = 0:0.01:pi;\ny = sin(x);\narea = trapz(x, y)",
"output": "area ≈ 2"
},
{
"description": "Using unit spacing for a row vector",
"input": "y = [1 2 3];\nq = trapz(y)",
"output": "q = 4"
},
{
"description": "Integrating each row independently",
"input": "A = [1 2 3; 4 5 6];\nq = trapz(A, 2)",
"output": "q =\n 4\n 10"
},
{
"description": "Running trapz on GPU data",
"input": "G = gpuArray([1 2 3]);\nq = trapz(G);\nresult = gather(q)",
"output": "result = 4"
}
],
"faqs": [
{
"question": "What spacing does `trapz(Y)` assume?",
"answer": "It assumes adjacent samples are one unit apart."
},
{
"question": "What forms of `X` are accepted?",
"answer": "A scalar spacing, a vector of coordinates matching the integration dimension, or an array with the same size as `Y`."
},
{
"question": "What happens for a scalar or singleton slice?",
"answer": "The integral is zero because there are no trapezoids to sum."
},
{
"question": "Does trapz support complex inputs?",
"answer": "Yes. RunMat integrates the real and imaginary parts independently and returns a complex result."
},
{
"question": "Does trapz keep gpuArray residency?",
"answer": "For real-valued results, yes. RunMat currently gathers GPU inputs to the host, computes the trapezoidal integral, and re-uploads the result so downstream GPU code can stay resident."
}
],
"links": [
{
"label": "cumtrapz",
"url": "./cumtrapz"
},
{
"label": "diff",
"url": "./diff"
},
{
"label": "sum",
"url": "./sum"
},
{
"label": "cumsum",
"url": "./cumsum"
},
{
"label": "gpuArray",
"url": "./gpuarray"
},
{
"label": "gather",
"url": "./gather"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/math/reduction/trapz.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/reduction/trapz.rs"
},
"gpu_residency": "Manual `gpuArray` promotion is optional. If sampled data already lives on the GPU, RunMat preserves real-valued outputs as gpuArrays by re-uploading the trapezoidal result after the host fallback path.",
"gpu_behavior": [
"RunMat does not yet expose a native provider hook for `trapz`. When the input is a gpuArray, the runtime gathers the data to host memory, performs the trapezoidal integration with MATLAB-compatible dimension and spacing rules, and re-uploads real-valued outputs so downstream GPU work stays resident."
]
}